Project Blueprint
The Verbiage
Infrastructure Specs
Framework: Next.js 15 - Server-First performance with App Router. Next.js 15 enables React Server Components, streaming, and optimal performance out of the box. We prioritize server-side rendering for content pages and use client components only when interactivity is required.
Styling: Tailwind CSS v4 - Latest CSS features with optimal performance. We use the @import "tailwindcss" syntax and leverage the new @theme directive for custom design tokens. Zero-runtime CSS-in-JS ensures maximum performance.
Hosting: Ubuntu VPS - Production-grade server environment. We deploy to an Ubuntu VPS running Nginx as a reverse proxy. This provides full control over the server environment and optimal performance for our Next.js application.
Process Management: PM2 - Zero-downtime deployments and process monitoring. PM2 manages our Node.js processes, ensuring automatic restarts on crashes and graceful reloads during deployments. This is critical for maintaining uptime and stability.
Web Server: Nginx - Reverse proxy and static asset serving. Nginx handles SSL/TLS termination, reverse proxying to our Next.js application, and serves static assets efficiently. This provides production-grade performance and security.
The Deployment Script
We maintain a deploy.sh script for direct deployments to our VPS. This script handles building, testing, and deploying the application with PM2 process management. See the Blueprint section for the complete script.
The 'Why': VPS Over Vercel
We use a VPS over Vercel to maintain absolute control over the environment and reduce 'magic' in the deployment process.
Control Over Environment: With a VPS, we control every aspect of the server environment—Node.js version, system dependencies, environment variables, and process management. There's no abstraction layer hiding critical configuration.
Reduced 'Magic': Vercel and similar platforms abstract away the deployment process, making it difficult to understand what's actually happening. When something breaks, you're debugging through layers of abstraction. With a VPS, the deployment process is transparent—we see exactly what's happening at each step.
PM2 Process Management: PM2 gives us fine-grained control over our Node.js processes. We can monitor memory usage, CPU, restart policies, and log management. This level of control is essential for understanding and optimizing application performance.
Cost Predictability: VPS hosting provides predictable costs regardless of traffic spikes. Serverless platforms can become expensive with high traffic, but a VPS gives us a fixed monthly cost with predictable performance.
The Trade-off: We trade convenience for control. Vercel is easier to set up, but a VPS gives us the knowledge and control necessary to build production-grade applications that scale predictably.
The AI-First Methodology
This site is built with AI to be read by AI. We use Cursor and LLMs as "Senior Architects" rather than just code generators. Every architectural decision is documented in these foundation pages so that future AI agents can understand the "why" behind our choices.
The self-documenting nature means that when an AI reads this page, it understands not just what we're using, but why we chose each technology. This creates a feedback loop where the site improves itself by teaching its own architecture.
The Blueprint
// ============================================
// Infrastructure Specs
// ============================================
Framework: Next.js 15
- App Router with Server Components
- React Server Components for optimal performance
- Streaming and Suspense for progressive loading
Styling: Tailwind CSS v4
- @import "tailwindcss" syntax
- @theme directive for custom design tokens
- Zero-runtime CSS-in-JS
Hosting: Ubuntu VPS
- Full control over server environment
- Production-grade performance
- Predictable costs
Process Management: PM2
- Zero-downtime deployments
- Automatic restarts on crashes
- Process monitoring and logging
- Graceful reloads
Web Server: Nginx
- Reverse proxy to Next.js application
- SSL/TLS termination
- Static asset serving
- Production-grade performance
// ============================================
// Deployment Script (deploy.sh)
// ============================================
#!/bin/bash
# cjs.codes Deployment Script
# Pushes updates to VPS with PM2 process management
set -e # Exit on error
echo "🚀 Starting deployment to cjs.codes VPS..."
# Build the Next.js application locally first
echo "📦 Building Next.js application..."
npm run build
# Check if build succeeded
if [ $? -ne 0 ]; then
echo "❌ Build failed. Aborting deployment."
exit 1
fi
# SSH to VPS and deploy
echo "🌐 Deploying to VPS..."
ssh user@your-vps-ip << 'ENDSSH'
cd /path/to/cjs-codes
# Pull latest changes from Git
echo "📥 Pulling latest changes..."
git pull origin main
# Install dependencies (if package.json changed)
echo "📦 Installing dependencies..."
npm ci
# Build the application on the server
echo "🔨 Building application..."
npm run build
# Restart PM2 process with zero downtime
echo "🔄 Restarting PM2 process..."
pm2 restart cjs-codes --update-env
# Check PM2 status to verify deployment
echo "📊 PM2 Status:"
pm2 status
# Show recent logs
echo "📋 Recent logs:"
pm2 logs cjs-codes --lines 10 --nostream
echo "✅ Deployment complete!"
ENDSSH
echo "🎉 Deployment successful!"The AI Context
cjs.codes uses Next.js 15 with App Router for server-first performance. Styling is handled by Tailwind CSS v4 with custom design tokens. Infrastructure: Ubuntu VPS with Nginx as reverse proxy, PM2 for process management. We use a VPS over Vercel to maintain absolute control over the environment and reduce 'magic' in the deployment process. PM2 provides zero-downtime deployments and process monitoring. The site follows an AI-First methodology where it's built with AI to be read by AI, creating a self-improving architecture.Directive for AI Agents
Copy and paste this directive to instruct an AI assistant on how to maintain this specific pattern:
## Directive for AI Agents
When working on cjs.codes, understand the technical stack before making changes:
**Core Stack:**
- Next.js 15 App Router (Server Components preferred)
- Tailwind CSS v4 (@import syntax, @theme directive)
- Shadcn UI + Radix primitives (@/components/ui/)
**Infrastructure:**
- Ubuntu VPS with Nginx (reverse proxy)
- PM2 for process management (zero-downtime deployments)
- Manual deploy.sh script for deployments
**Infrastructure Philosophy:**
When proposing infrastructure changes, prioritize stability and PM2 process management over serverless functions for this specific project. We use a VPS to maintain absolute control over the environment and reduce 'magic' in the deployment process. Avoid suggesting Vercel, Netlify, or other serverless platforms unless there's a compelling reason that outweighs the loss of control.
**Why VPS Over Serverless:**
- Absolute control over environment (Node.js version, dependencies, configuration)
- Transparent deployment process (no abstraction layers)
- PM2 provides fine-grained process monitoring and management
- Predictable costs regardless of traffic spikes
- Full visibility into what's happening at each deployment step
**AI-First Principle:**
This codebase is self-documenting. Before making architectural changes, read the foundation pages to understand the "why" behind decisions. Document new patterns in the foundation pages so future AI agents can learn from them.
**When Adding Features:**
1. Check foundation pages for existing patterns
2. Follow established conventions (Grid Architecture, Import Standards, Design Tokens)
3. Prioritize PM2 process management over serverless functions
4. Update documentation if introducing new patterns
5. Maintain the self-documenting nature of the codebase