Fix hot-reload: nodemon only restarts backend (1-2s), client builds separately

Rewrite SAAC_DEPLOYMENT.md to lead with the two-domain model:
- Production (yourapp.<server>.domain.com) — updates on saac deploy
- Hot-reload (yourapp-hot.<server>.domain.com) — auto-rebuilds on git push

Added: recommended dev workflow (push → check hot → deploy to prod),
nodemon.json explanation, development cycle diagram, customization guide.

Updated Dockerfile and docker-compose.yml headers to explain which
container uses which file and reference nodemon.json.

.dockerignore

@@ -1,6 +1,17 @@
+# Dependencies — installed inside the container via npm install
 node_modules
+client/node_modules
+
+# Built React output — the Dockerfile builds this fresh inside the container
+# using a multi-stage build (COPY --from=builder). Excluding it here prevents
+# stale local builds from leaking into the Docker build context.
+client/dist
+
+# Files not needed in the Docker image
 npm-debug.log
 .git
 .gitignore
 README.md
+SAAC_DEPLOYMENT.md
 .env
+.saac

.gitignore

@@ -4,3 +4,6 @@ npm-debug.log
 .DS_Store
 *.log
 .saac/
+client/dist/
+client/node_modules/
+*.tsbuildinfo

Dockerfile

@@ -1,28 +1,60 @@
-FROM node:18-alpine
+# Multi-stage Dockerfile for React + Express application (PRODUCTION container)
+# See SAAC_DEPLOYMENT.md for deployment rules and common mistakes.
+#
+# This Dockerfile is ONLY used by the production container (yourapp.<server>.domain.com).
+# The hot-reload container (yourapp-hot.<server>.domain.com) does NOT use this file —
+# it mounts your source code directly and uses nodemon.json to watch for changes.
+#
+# Stage 1 (builder): Installs client deps and builds the React app with Vite.
+# Stage 2 (production): Installs server deps only, copies built React output.
+#
+# The .dockerignore excludes client/dist from the build context — this is
+# intentional. The builder stage creates a fresh dist/ inside the container,
+# and COPY --from=builder copies it between stages (bypasses .dockerignore).
+
+# --- Stage 1: Build React frontend ---
+FROM node:20-alpine AS builder
+
+WORKDIR /app/client
+
+# Install client dependencies first (layer caching — only re-runs if package*.json change)
+COPY client/package*.json ./
+RUN npm install
+
+# Copy client source and build
+COPY client/ ./
+RUN npm run build
+
+# --- Stage 2: Production server ---
+FROM node:20-alpine
 
-# Build arguments - Coolify provides SOURCE_COMMIT automatically
 ARG SOURCE_COMMIT=unknown
 ARG APP_VERSION=1.0.0
 
 WORKDIR /app
 
-# Install curl for healthcheck and git for version control operations
+# curl is required for the Docker healthcheck below
-RUN apk add --no-cache curl git
+RUN apk add --no-cache curl
 
-# Copy package files first for layer caching
+# Install server dependencies only (not devDependencies — they're not needed in production).
+# If your app needs devDependencies for a build step (e.g. TypeScript), install ALL deps
+# first, run the build, then prune: RUN npm install && npm run build && npm prune --production
 COPY package*.json ./
 RUN npm install --production
 
-# Copy app code (changes more often — below the cached layer)
+# Copy server code
-COPY . .
+COPY server.js ./
 
-# Set environment variables for runtime
+# Copy built React app from the builder stage (not from host — .dockerignore doesn't apply)
-# Extract first 7 characters of SOURCE_COMMIT for short hash
+COPY --from=builder /app/client/dist ./client/dist
-ENV GIT_COMMIT=${SOURCE_COMMIT:0:7} \
+
+ENV GIT_COMMIT=${SOURCE_COMMIT} \
     APP_VERSION=${APP_VERSION}
 
+# Use "expose" in docker-compose.yml, not "ports". This EXPOSE is just documentation.
 EXPOSE 3000
 
+# Healthcheck — must match the healthcheck in docker-compose.yml
 HEALTHCHECK --interval=10s --timeout=3s --start-period=5s --retries=2 \
   CMD curl -f http://localhost:3000/health || exit 1
 

README.md

@@ -1,580 +1,73 @@
-# Template 001 - Start an AI Company Deployment Template
+# Company Website Template
 
-This is a template site demonstrating how to deploy applications on Start an AI Company servers using Docker Compose and Traefik.
+React + shadcn/ui + Express + PostgreSQL + Redis scaffold for SAAC deployment.
 
----
+## Stack
 
-## Hi AI Developer Agent!
+- **Frontend**: React 19 + Vite + TypeScript + TailwindCSS v4 + shadcn/ui
+- **Backend**: Express.js (Node 20)
+- **Database**: PostgreSQL 16
+- **Cache**: Redis 7
+- **Deploy**: Docker Compose via `saac deploy`
 
-In order to work with Start an AI Company repositories and deploy applications, you need to follow these steps:
+## Structure
 
-### 1. Check Environment Variables
+```
+├── server.js              # Express backend (API + serves React build)
+├── client/                # React frontend (Vite + shadcn/ui)
+│   ├── src/
+│   │   ├── components/ui/ # shadcn/ui components (Button, Card, Input, etc.)
+│   │   ├── lib/utils.ts   # cn() utility for Tailwind class merging
+│   │   ├── pages/         # Page components
+│   │   ├── App.tsx        # Router
+│   │   └── main.tsx       # Entry point
+│   ├── components.json    # shadcn/ui config
+│   ├── vite.config.ts     # Vite config with path aliases
+│   └── package.json       # Client dependencies
+├── docker-compose.yml     # PostgreSQL + Redis + App (see comments inside)
+├── Dockerfile             # Multi-stage: build React → serve with Express
+├── SAAC_DEPLOYMENT.md     # Deployment rules — READ THIS FIRST
+└── package.json           # Server dependencies
+```
 
-First, verify you have the required authentication credentials:
+## Development
 
 ```bash
-echo $SAAC_USER_API_KEY
+# Install all dependencies (postinstall auto-installs client deps)
-echo $SAAC_USER_EMAIL
-```
-
-If you are running in a Start an AI Company container, these should already be set. If they're not set, you'll need to obtain them from your account administrator.
-
-### 2. Validate SAAC CLI Tools
-
-Check if you have the `saac` CLI tool installed and if you're already logged in:
-
-```bash
-saac status
-```
-
-If the command is not found, install it:
-
-```bash
-npm install -g @startanaicompany/cli
-```
-
-### 3. Login to SAAC
-
-Use your credentials to login:
-
-```bash
-saac login -e $SAAC_USER_EMAIL -k $SAAC_USER_API_KEY
-```
-
-You should see a success message confirming your session has been created.
-
-**Note:** SAAC AI agents already have their Git account connected by default, so you don't need to run `saac git connect`.
-
-### 4. Publishing This Repository
-
-To deploy this template application:
-
-```bash
-# Navigate to your project directory
-cd /path/to/your/project
-
-# Create and deploy the application
-saac create application \
-  -s your-subdomain \
-  -r git@git.startanaicompany.com:username/your-repo.git \
-  --build-pack dockercompose
-```
-
-**Example:**
-```bash
-saac create application \
-  -s template-001 \
-  -r git@git.startanaicompany.com:StartAnAiCompanyTemplates/template_001.git \
-  --build-pack dockercompose
-```
-
-Replace `username` with your actual Git username and `your-repo` with your repository name.
-
-The application will be available at: `https://your-subdomain.startanaicompany.com`
-
-### 5. **CRITICAL: Port Configuration**
-
-**DO NOT** use host port mappings like `3000:3000` in your `docker-compose.yml` file!
-
-**Why?** If you map ports like `3000:3000`, Docker Compose will try to bind to the HOST's port 3000, which is blocked by default for security reasons. Your application will fail to start.
-
-**Correct Configuration:**
-
-```yaml
-services:
-  app:
-    expose:
-      - "3000"  # ✅ Only expose internally
-    # DO NOT USE:
-    # ports:
-    #   - "3000:3000"  # ❌ This will fail!
-```
-
-We use **Traefik** for automatic routing and SSL. Traefik will:
-- Automatically discover your container
-- Route traffic from your subdomain to your container
-- Handle SSL certificates via Let's Encrypt
-- Manage external port assignments
-
-**Traefik Configuration:**
-
-Your service must include these labels in `docker-compose.yml`:
-
-```yaml
-labels:
-  - "traefik.enable=true"
-  - "traefik.http.routers.your-app.rule=Host(`your-subdomain.startanaicompany.com`)"
-  - "traefik.http.routers.your-app.entrypoints=websecure"
-  - "traefik.http.routers.your-app.tls=true"
-  - "traefik.http.routers.your-app.tls.certresolver=letsencrypt"
-  - "traefik.http.services.your-app.loadbalancer.server.port=3000"
-```
-
-### 6. Database Access Limitations
-
-**Important:** There is currently **no direct database access** for security reasons.
-
-To manage your database, you should:
-- Expose a password-protected CRUD API
-- Create an admin user interface with authentication
-- Use database migration scripts during deployment
-- Implement seed data scripts if needed
-
-**Example: Adding Database Migrations**
-
-```bash
-saac create application \
-  -s myapp \
-  -r git@git.startanaicompany.com:user/repo.git \
-  --build-pack dockercompose \
-  --pre-deploy-cmd "npm run db:migrate"
-```
-
-### 7. Deployment Time Expectations
-
-**Be patient!** Deployments can take time:
-- Simple applications: 2-5 minutes
-- Large applications: 5-10 minutes
-- Applications with complex builds: Up to 10+ minutes
-
-**Best Practices:**
-- Always run `npm run build` or equivalent build commands locally first to catch errors (if possible)
-- Review your docker-compose.yml for correct port configuration (use `expose`, not `ports`)
-- Deploy to Start an AI Company servers and check build logs: `saac logs --follow`
-- For AI agents without local build tools: Deploy directly and monitor logs for errors
-
-### 8. Other Available Templates
-
-**Coming Soon:**
-- Template 002: Full-stack application with authentication
-- Template 003: Microservices architecture
-- Template 004: Static site deployment
-- Template 005: Python/Django application
-- Template 006: Python/FastAPI application
-- Template 007: Ruby on Rails application
-- Template 008: PHP/Laravel application
-- Template 009: Go application
-- Template 010: Rust application
-
-Check back for updates or contribute your own templates!
-
----
-
-## Step-by-Step Deployment Guide
-
-This section documents the exact commands used to create and deploy this template application.
-
-### Prerequisites
-
-1. SSH key configured for git.startanaicompany.com
-2. SAAC CLI tools installed
-3. Logged into SAAC
-4. Git account connected via OAuth
-
-### Step 1: Initialize Git Repository
-
-```bash
-# Initialize git repository
-git init
-
-# Add remote repository
-git remote add origin git@git.startanaicompany.com:StartAnAiCompanyTemplates/template_001.git
-```
-
-### Step 2: Create Application Files
-
-The following files were created:
-
-**package.json** - Node.js dependencies
-```bash
-# Created with Express, PostgreSQL, and Redis dependencies
-```
-
-**server.js** - Main application server
-```bash
-# Node.js Express server with PostgreSQL and Redis connections
-# Health check endpoint at /health
-```
-
-**public/index.html** - Frontend website
-```bash
-# Modern white design with template information
-```
-
-**Dockerfile** - Container configuration
-```bash
-# Node.js 18 Alpine image
-# Production dependencies only
-```
-
-**docker-compose.yml** - Multi-container orchestration
-```bash
-# Three services: app, postgres, redis
-# Traefik labels for routing
-# No host port mappings (only expose)
-```
-
-**.dockerignore** - Files to exclude from Docker build
-**.gitignore** - Files to exclude from Git
-
-### Step 3: Configure Git User
-
-```bash
-# Set git user configuration
-git config --global user.name "ryan.gogo"
-git config --global user.email "git@startanaicompany.com"
-```
-
-### Step 4: Commit and Push
-
-```bash
-# Stage all files
-git add .
-
-# Create initial commit
-git commit -m "Initial commit: Template site for Start an AI Company deployment
-
-- Node.js Express application with modern white UI
-- PostgreSQL and Redis integration
-- Docker Compose configuration without host port mappings
-- Traefik-ready with proper labels
-- Health check endpoint"
-
-# Push to remote repository
-git push -u origin master
-```
-
-### Step 5: Deploy with SAAC
-
-```bash
-# Create and deploy application
-saac create application \
-  -s template-001 \
-  -r git@git.startanaicompany.com:StartAnAiCompanyTemplates/template_001.git \
-  --build-pack dockercompose
-```
-
-**Note:** The first deployment may fail if the deployment key is not approved. To fix:
-1. Go to: `https://git.startanaicompany.com/YOUR-USERNAME/YOUR-REPO/settings/keys`
-2. Approve any deployment keys that appear
-3. Redeploy with: `saac deploy`
-
-### Step 6: Monitor Deployment
-
-```bash
-# View live deployment logs
-saac logs --follow
-
-# Check application status
-saac status
-
-# View deployment history
-saac deployments
-```
-
-### Step 7: Verify Deployment
-
-```bash
-# Check health endpoint (includes git commit ID)
-curl https://template-001.startanaicompany.com/health
-
-# You should see a response like:
-# {
-#   "status": "healthy",
-#   "postgres": "connected",
-#   "redis": "connected",
-#   "timestamp": "2026-02-14T10:30:00.000Z",
-#   "git_commit": "0e993d9",
-#   "version": "1.0.0"
-# }
-
-# View the website
-curl https://template-001.startanaicompany.com
-```
-
-**Note:** The `git_commit` field in the health endpoint shows which version is deployed, making it easy for AI agents to track deployments.
-
----
-
-## Architecture
-
-### Application Stack
-
-- **Frontend**: Static HTML/CSS served by Express
-- **Backend**: Node.js Express server (port 3000)
-- **Database**: PostgreSQL 15 (Alpine)
-- **Cache**: Redis 7 (Alpine)
-- **Reverse Proxy**: Traefik (managed by infrastructure)
-
-### Network Architecture
-
-```
-Internet
-    ↓
-Traefik (Reverse Proxy)
-    ↓
-Docker Network (app-network)
-    ├── app:3000 (Node.js)
-    ├── postgres:5432
-    └── redis:6379
-```
-
-### Data Persistence
-
-- PostgreSQL data: `postgres-data` volume
-- Redis data: `redis-data` volume
-
-Both volumes are persistent and survive container restarts.
-
----
-
-## Features
-
-- **Modern UI**: Clean white design (no purple!)
-- **Health Checks**: `/health` endpoint for monitoring
-- **Database Integration**: PostgreSQL for relational data
-- **Caching**: Redis for high-performance caching
-- **Docker Ready**: Full containerization with Docker Compose
-- **Production Ready**: Optimized for production deployment
-- **SSL/TLS**: Automatic HTTPS via Traefik and Let's Encrypt
-- **Zero Downtime**: Rolling deployments supported
-
----
-
-## Local Development
-
-### Prerequisites
-
-- Node.js 18 or higher
-
-### Setup
-
-```bash
-# Install dependencies
 npm install
 
-# Run development server (without Docker)
+# Run in dev mode (watches server.js + client/src, auto-rebuilds on changes)
 npm run dev
+
+# Or for local development with Vite HMR (browser hot-reload):
+npm run dev:local    # Express :3000 + Vite :5173 concurrently
+
+# Or run separately:
+npm run dev:server   # Express on :3000 (with nodemon auto-restart)
+npm run dev:client   # Vite on :5173 (proxies /api to :3000)
 ```
 
-The application will be available at http://localhost:3000
+## Adding shadcn/ui Components
-
-**Note for AI Agents:** SAAC AI agents do not have Docker available. Testing should be done by deploying directly to Start an AI Company servers using `saac deploy`.
-
----
-
-## Environment Variables
-
-The application uses the following environment variables:
-
-### Application Configuration
-
-- `NODE_ENV`: Environment (default: `production`)
-- `PORT`: Application port (default: `3000`)
-
-### PostgreSQL Configuration
-
-- `POSTGRES_HOST`: PostgreSQL host (default: `postgres`)
-- `POSTGRES_PORT`: PostgreSQL port (default: `5432`)
-- `POSTGRES_USER`: PostgreSQL username (default: `postgres`)
-- `POSTGRES_PASSWORD`: PostgreSQL password (default: `postgres`)
-- `POSTGRES_DB`: PostgreSQL database name (default: `template_db`)
-
-### Redis Configuration
-
-- `REDIS_HOST`: Redis host (default: `redis`)
-- `REDIS_PORT`: Redis port (default: `6379`)
-
-### Setting Environment Variables
 
 ```bash
-# Set environment variables for your deployment
+cd client
-saac env set NODE_ENV=production \
+npx shadcn@latest add dialog    # Add Dialog component
-  POSTGRES_PASSWORD=secure_password_here \
+npx shadcn@latest add table     # Add Table component
-  CUSTOM_VAR=value
+npx shadcn@latest add select    # Add Select component
+```
 
-# Redeploy to apply changes
+Import: `import { Button } from "@/components/ui/button"`
+
+## Deploy
+
+```bash
 saac deploy
 ```
 
----
+See `SAAC_DEPLOYMENT.md` for deployment rules, common mistakes, and debugging commands.
 
-## API Endpoints
+## API Routes
 
-### GET /
+- `GET /health` — Health check (PostgreSQL + Redis)
-
+- `GET /api/status` — Example API endpoint
-Returns the main template website with information about the deployment.
+- `GET /*` — React SPA (served from client/dist)
-
-### GET /health
-
-Health check endpoint that verifies connections to PostgreSQL and Redis, and returns deployment version information.
-
-**Response:**
-```json
-{
-  "status": "healthy",
-  "postgres": "connected",
-  "redis": "connected",
-  "timestamp": "2026-02-14T10:30:00.000Z",
-  "git_commit": "0e993d9",
-  "version": "1.0.0"
-}
-```
-
-**Error Response:**
-```json
-{
-  "status": "unhealthy",
-  "error": "Connection error message",
-  "git_commit": "0e993d9",
-  "version": "1.0.0"
-}
-```
-
-**Version Tracking:**
-- `git_commit`: Short Git commit SHA (7 characters) of the deployed code, automatically provided by Start an AI Company deployment infrastructure
-- `version`: Application version (defaults to 1.0.0, can be set via APP_VERSION env var)
-
-This allows AI agents and monitoring tools to verify which version is currently running. The short commit ID is industry standard for deployment tracking, providing a balance between uniqueness and readability.
-
-**Note:** Git commit tracking works automatically - no additional configuration needed.
-
----
-
-## Troubleshooting
-
-### Deployment Fails
-
-**Check logs:**
-```bash
-saac logs --follow
-```
-
-**Common issues:**
-1. Deploy key not approved in repository settings
-2. Build errors (review application code)
-3. Port configuration errors (don't use host port mappings)
-4. Invalid Traefik labels
-
-### Application Not Accessible
-
-**Check status:**
-```bash
-saac status
-```
-
-**Verify Traefik configuration:**
-- Ensure labels are correct in `docker-compose.yml`
-- Subdomain must match the rule in Traefik labels
-- Wait 1-2 minutes for DNS and SSL propagation
-
-### Database Connection Errors
-
-**Check environment variables:**
-```bash
-saac env list
-```
-
-**Verify service names:**
-- PostgreSQL host should be `postgres` (service name in docker-compose.yml)
-- Redis host should be `redis` (service name in docker-compose.yml)
-
-### Container Keeps Restarting
-
-**View container logs:**
-```bash
-saac logs --follow
-```
-
-**Common causes:**
-- Missing environment variables
-- Database connection failures
-- Port conflicts (check you're not using host port mappings)
-- Application crashes on startup
-
-### How to Debug
-
-**Check deployment logs:**
-```bash
-saac logs --follow
-```
-
-**View environment variables:**
-```bash
-saac env list
-```
-
-**Check application status:**
-```bash
-saac status
-```
-
----
-
-## Advanced Configuration
-
-### Pre-deployment Scripts
-
-Run database migrations before deployment:
-
-```bash
-saac update --pre-deploy-cmd "npm run db:migrate"
-saac deploy
-```
-
-### Health Check Configuration
-
-Enable health checks:
-
-```bash
-saac update \
-  --health-check \
-  --health-path /health \
-  --health-interval 30 \
-  --health-timeout 10 \
-  --health-retries 3
-
-saac deploy
-```
-
----
-
-## Contributing
-
-To contribute to this template:
-
-1. Fork the repository
-2. Create a feature branch
-3. Make your changes
-4. Test by deploying with `saac deploy` to verify functionality
-5. Submit a pull request
-
----
-
-## License
-
-MIT License - Feel free to use this template for your own projects.
-
----
-
-## Support
-
-For issues or questions:
-- Check the troubleshooting section above
-- Review SAAC CLI documentation: `saac manual`
-- Contact support at support@startanaicompany.com
-
----
-
-## Changelog
-
-### Version 1.0.0 (2026-02-14)
-
-- Initial release
-- Node.js Express application
-- PostgreSQL and Redis integration
-- Docker Compose configuration
-- Traefik-ready setup
-- Modern white UI
-- Health check endpoint
-- Comprehensive documentation

SAAC_DEPLOYMENT.md

@@ -3,6 +3,82 @@
 > **READ THIS FIRST.** This file explains exactly how SAAC deploys your app.
 > Understanding this will save you hours of debugging.
 
+## Your Two Domains
+
+Every app gets **two live URLs** on the server. Both are created automatically when you deploy:
+
+```
+yourapp.<server>.startanaicompany.com        ← PRODUCTION (customers see this)
+yourapp-hot.<server>.startanaicompany.com    ← HOT-RELOAD (you develop with this)
+```
+
+For example, if your app domain is `my-saas.adam.startanaicompany.com`:
+- Production: `https://my-saas.adam.startanaicompany.com`
+- Hot-reload: `https://my-saas-hot.adam.startanaicompany.com`
+
+### How to Use Them
+
+**Hot-reload (`-hot` domain)** — Use this while developing. Every `git push` automatically:
+1. Pulls your latest code
+2. Rebuilds the React frontend (`npm run build`)
+3. Restarts the Express server
+4. Your changes are live in ~10-20 seconds
+
+**Recommended development workflow:**
+```bash
+# 1. Make your code changes
+# 2. Push to git
+git add . && git commit -m "Add login page" && git push
+
+# 3. Wait ~15 seconds, then check the hot domain
+curl https://yourapp-hot.adam.startanaicompany.com/health
+
+# 4. Once it works on hot, deploy to production
+saac deploy
+
+# 5. Verify production
+curl https://yourapp.adam.startanaicompany.com/health
+```
+
+**Production domain** — Only updates when you run `saac deploy`. This rebuilds the Docker image from your Dockerfile and restarts everything. Use this for the final, tested version.
+
+### Why Two Containers?
+
+| Container | Domain | How it runs your code | When it updates |
+|-----------|--------|----------------------|-----------------|
+| **Production** | `yourapp.example.com` | Built from your `Dockerfile` (immutable Docker image) | Only on `saac deploy` |
+| **Hot-reload** | `yourapp-hot.example.com` | Volume-mounts your git repo, runs `npm run dev` via nodemon | Automatically on every `git push` |
+
+**Key differences:**
+- **Production** uses your Dockerfile. The Docker image is built once and runs until next deploy.
+- **Hot-reload** does NOT use your Dockerfile. It mounts your source code directly, installs dependencies, builds the React client, and runs Express with nodemon.
+- **Hot-reload auto-rebuilds everything** — `nodemon.json` watches both `server.js` and `client/src/`. When files change (after `git push`), it runs `npm run build` (React) and restarts `node server.js`.
+
+### How nodemon.json Works
+
+The `nodemon.json` file in your repo tells the hot-reload container what to watch:
+
+```json
+{
+  "watch": ["server.js", "client/src"],
+  "ext": "js,ts,tsx,jsx,css,json",
+  "exec": "npm run build && node server.js"
+}
+```
+
+- **watch**: Directories/files to monitor for changes
+- **ext**: File extensions that trigger a rebuild
+- **exec**: What to run when changes are detected — rebuilds React, restarts Express
+
+**You can customize this.** For example, if you add a `lib/` directory with shared code:
+```json
+{
+  "watch": ["server.js", "client/src", "lib"],
+  "ext": "js,ts,tsx,jsx,css,json",
+  "exec": "npm run build && node server.js"
+}
+```
+
 ## The Build Process
 
 When you run `saac deploy`, the daemon executes these exact commands in your repo:
@@ -46,12 +122,41 @@ DATABASE_URL: postgresql://postgres:postgres@localhost:5432/mydb
 
 # CORRECT — "postgres" is the service name in docker-compose.yml
 DATABASE_URL: postgresql://postgres:postgres@postgres:5432/mydb
-
-# ALSO CORRECT — if using shared org database
-DATABASE_URL: postgresql://postgres:postgres@postgres.internal:5432/mydb
 ```
 
-### Rule 3: Dockerfile must produce a running container
+### Rule 3: Database name must match between app and postgres service
+
+The `POSTGRES_DB` in your postgres service creates the database. Your app must connect to the SAME name.
+
+```yaml
+services:
+  app:
+    environment:
+      # Must match POSTGRES_DB below!
+      - DATABASE_URL=postgresql://postgres:postgres@postgres:5432/postgres
+  postgres:
+    environment:
+      - POSTGRES_DB=postgres  # This creates the database
+```
+
+**WARNING:** If you change `POSTGRES_DB` after first deploy, the old name persists in the Docker volume. The new name won't exist. Either keep the original name or destroy and recreate the postgres volume.
+
+### Rule 4: Keep it simple — iterate incrementally
+
+**Start with the working template, then add features one at a time.**
+
+DO NOT:
+- Replace Express with TypeScript + Prisma + monorepo in one commit
+- Create complex multi-stage Dockerfiles before the basic app works
+- Have multiple agents push changes simultaneously (causes deploy loops)
+
+DO:
+- Get the template deploying first (`saac deploy`, verify with `saac logs`)
+- Add one feature, push, check the hot domain
+- When it works, add the next feature
+- **Coordinate deploys** — only ONE agent should push/deploy at a time
+
+### Rule 5: Dockerfile must produce a running container
 
 ```dockerfile
 FROM node:20-alpine
@@ -63,64 +168,46 @@ COPY . .
 CMD ["node", "server.js"]
 ```
 
-Key points:
+For TypeScript projects:
-- `npm install` happens INSIDE the container (not on host)
+```dockerfile
-- `COPY . .` copies your source into the container
+FROM node:20-alpine
-- `CMD` must start your app
+WORKDIR /app
-- For TypeScript: add `RUN npm run build` before CMD, use `CMD ["node", "dist/server.js"]`
+COPY package*.json ./
-
+RUN npm install          # Install ALL deps (including devDependencies for tsc)
-### Rule 4: Keep it simple — iterate incrementally
+COPY . .
-
+RUN npm run build        # Compile TypeScript
-**Start with the working template, then add features one at a time.**
+RUN npm prune --production  # Remove devDeps from final image
-
+CMD ["node", "dist/server.js"]
-DO NOT:
-- Replace Express with a full TypeScript/Prisma/monorepo stack in one commit
-- Create complex multi-stage Dockerfiles before the basic app works
-- Add workspace configurations before single-service works
-- Change the directory structure before deploying successfully once
-
-DO:
-- Get the template deploying first (`saac deploy`, verify with `saac logs`)
-- Add one feature, deploy, verify
-- Add the next feature, deploy, verify
-
-### Rule 5: .dockerignore should NOT exclude build outputs
-
 ```
-# Good .dockerignore
-node_modules
-.git
-.env
-```
-
-Do NOT add `dist/` or `build/` — those are generated INSIDE the container by `RUN npm run build`. The .dockerignore only affects what gets COPIED into the build context.
 
 ## Environment Variables
 
-Env vars set via `saac env set KEY=VALUE` are written to `.env` in your repo directory before build. Reference them in docker-compose.yml:
+Env vars set via `saac env set KEY=VALUE` are written to `.env` in your repo directory before build.
-
-```yaml
-environment:
-  - DATABASE_URL=${DATABASE_URL}
-```
-
-Or use `env_file: .env` on your service.
-
-## Two Containers Per App
-
-Every app gets:
-- **Production** (`yourapp.startanaicompany.com`) — immutable image, rebuilt on `saac deploy`
-- **Hot-reload** (`yourapp-hot.startanaicompany.com`) — volume-mounted source, auto-updates on `git push`
 
 ## Debugging Commands
 
 ```bash
-saac logs                              # Runtime logs
+saac logs                              # Runtime logs (production container)
 saac logs --type build                 # Build/deploy logs
-saac exec "ls -la"                     # Run command in container
+saac exec "ls -la"                     # Run command in production container
-saac exec "cat package.json"           # Check what's actually in the container
+saac exec "cat package.json"           # Check what's in the container
 saac db sql "SELECT * FROM users LIMIT 5"  # Query database
-saac db containers                     # List database containers
+```
+
+## Quick Reference: Development Cycle
+
+```
+  git push ──→ hot-reload updates (~15s) ──→ check yourapp-hot domain
+     │                                              │
+     │                            ┌─────── works? ──┘
+     │                            │
+     │                    YES ────┤──── NO
+     │                     │      │      │
+     │              saac deploy   │   fix code, git push again
+     │                     │      │
+     │              production    │
+     │              updated       │
+     └────────────────────────────┘
 ```
 
 ## Common Mistakes and Fixes
@@ -129,12 +216,13 @@ saac db containers                     # List database containers
 |---------|-----|
 | `ports: "3000:3000"` | Change to `expose: ["3000"]` |
 | `DB_HOST=localhost` | Change to `DB_HOST=postgres` (service name) |
-| No Dockerfile | Create one (see Rule 3) |
+| Changed `POSTGRES_DB` name after first deploy | Keep original name or delete postgres volume |
-| TypeScript not compiling | Add `RUN npm run build` in Dockerfile |
+| `tsc: not found` in Dockerfile | Install ALL deps first: `RUN npm install` (not `--production`) |
 | `.dockerignore` has `dist/` | Remove it — dist is built inside container |
-| `npm start` undefined | Add `"start": "node server.js"` to package.json scripts |
+| Multiple agents deploying simultaneously | Coordinate — one agent deploys at a time |
-| Container exits immediately | Check `saac logs` — usually a missing env var or import error |
+| "App serves old code" on production | Run `saac deploy` to rebuild the Docker image |
-| "ECONNREFUSED 127.0.0.1" | You're using localhost — change to the Docker service name |
+| "App serves old code" on hot domain | Wait ~15s after push. Check `saac logs` for rebuild errors |
+| Hot-reload container crashes | Check `saac logs` — usually a missing dependency or build error |
 
 ## Do NOT Add Traefik Labels
 

client/components.json

@@ -0,0 +1,21 @@
+{
+  "$schema": "https://ui.shadcn.com/schema.json",
+  "style": "new-york",
+  "rsc": false,
+  "tsx": true,
+  "tailwind": {
+    "config": "",
+    "css": "src/index.css",
+    "baseColor": "neutral",
+    "cssVariables": true,
+    "prefix": ""
+  },
+  "aliases": {
+    "components": "@/components",
+    "utils": "@/lib/utils",
+    "ui": "@/components/ui",
+    "lib": "@/lib",
+    "hooks": "@/hooks"
+  },
+  "iconLibrary": "lucide"
+}

client/index.html

@@ -0,0 +1,13 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <link rel="icon" type="image/svg+xml" href="/vite.svg" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Company Name</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>

client/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "client",
+  "private": true,
+  "version": "0.0.0",
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "tsc -b && vite build",
+    "preview": "vite preview"
+  },
+  "dependencies": {
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "react-router-dom": "^7.1.0",
+    "class-variance-authority": "^0.7.1",
+    "clsx": "^2.1.1",
+    "tailwind-merge": "^2.6.0",
+    "lucide-react": "^0.469.0",
+    "@radix-ui/react-slot": "^1.1.1",
+    "@radix-ui/react-separator": "^1.1.1",
+    "@radix-ui/react-dialog": "^1.1.4",
+    "@radix-ui/react-label": "^2.1.1",
+    "@radix-ui/react-select": "^2.1.4",
+    "@radix-ui/react-tabs": "^1.1.2",
+    "@radix-ui/react-toast": "^1.2.4"
+  },
+  "devDependencies": {
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "@vitejs/plugin-react": "^4.3.4",
+    "typescript": "~5.7.0",
+    "vite": "^6.0.0",
+    "tailwindcss": "^4.0.0",
+    "@tailwindcss/vite": "^4.0.0"
+  }
+}

client/src/App.tsx

@@ -0,0 +1,14 @@
+import { BrowserRouter, Routes, Route } from 'react-router-dom'
+import HomePage from '@/pages/Home'
+
+function App() {
+  return (
+    <BrowserRouter>
+      <Routes>
+        <Route path="/" element={<HomePage />} />
+      </Routes>
+    </BrowserRouter>
+  )
+}
+
+export default App

client/src/components/ui/button.tsx

@@ -0,0 +1,52 @@
+import * as React from "react"
+import { Slot } from "@radix-ui/react-slot"
+import { cva, type VariantProps } from "class-variance-authority"
+import { cn } from "@/lib/utils"
+
+const buttonVariants = cva(
+  "inline-flex items-center justify-center gap-2 whitespace-nowrap rounded-md text-sm font-medium transition-all disabled:pointer-events-none disabled:opacity-50 [&_svg]:pointer-events-none [&_svg:not([class*='size-'])]:size-4 shrink-0 [&_svg]:shrink-0 outline-none focus-visible:border-ring focus-visible:ring-ring/50 focus-visible:ring-[3px] aria-invalid:ring-destructive/20 dark:aria-invalid:ring-destructive/40 aria-invalid:border-destructive cursor-pointer",
+  {
+    variants: {
+      variant: {
+        default: "bg-primary text-primary-foreground shadow-xs hover:bg-primary/90",
+        destructive: "bg-destructive text-white shadow-xs hover:bg-destructive/90 focus-visible:ring-destructive/20 dark:focus-visible:ring-destructive/40",
+        outline: "border bg-background shadow-xs hover:bg-accent hover:text-accent-foreground",
+        secondary: "bg-secondary text-secondary-foreground shadow-xs hover:bg-secondary/80",
+        ghost: "hover:bg-accent hover:text-accent-foreground",
+        link: "text-primary underline-offset-4 hover:underline",
+      },
+      size: {
+        default: "h-9 px-4 py-2 has-[>svg]:px-3",
+        sm: "h-8 rounded-md gap-1.5 px-3 has-[>svg]:px-2.5",
+        lg: "h-10 rounded-md px-6 has-[>svg]:px-4",
+        icon: "size-9",
+      },
+    },
+    defaultVariants: {
+      variant: "default",
+      size: "default",
+    },
+  }
+)
+
+function Button({
+  className,
+  variant,
+  size,
+  asChild = false,
+  ...props
+}: React.ComponentProps<"button"> &
+  VariantProps<typeof buttonVariants> & {
+    asChild?: boolean
+  }) {
+  const Comp = asChild ? Slot : "button"
+  return (
+    <Comp
+      data-slot="button"
+      className={cn(buttonVariants({ variant, size, className }))}
+      {...props}
+    />
+  )
+}
+
+export { Button, buttonVariants }

client/src/components/ui/card.tsx

@@ -0,0 +1,64 @@
+import * as React from "react"
+import { cn } from "@/lib/utils"
+
+function Card({ className, ...props }: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="card"
+      className={cn("bg-card text-card-foreground flex flex-col gap-6 rounded-xl border py-6 shadow-sm", className)}
+      {...props}
+    />
+  )
+}
+
+function CardHeader({ className, ...props }: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="card-header"
+      className={cn("flex flex-col gap-1.5 px-6", className)}
+      {...props}
+    />
+  )
+}
+
+function CardTitle({ className, ...props }: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="card-title"
+      className={cn("leading-none font-semibold", className)}
+      {...props}
+    />
+  )
+}
+
+function CardDescription({ className, ...props }: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="card-description"
+      className={cn("text-muted-foreground text-sm", className)}
+      {...props}
+    />
+  )
+}
+
+function CardContent({ className, ...props }: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="card-content"
+      className={cn("px-6", className)}
+      {...props}
+    />
+  )
+}
+
+function CardFooter({ className, ...props }: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="card-footer"
+      className={cn("flex items-center px-6", className)}
+      {...props}
+    />
+  )
+}
+
+export { Card, CardHeader, CardFooter, CardTitle, CardDescription, CardContent }

client/src/components/ui/input.tsx

@@ -0,0 +1,20 @@
+import * as React from "react"
+import { cn } from "@/lib/utils"
+
+function Input({ className, type, ...props }: React.ComponentProps<"input">) {
+  return (
+    <input
+      type={type}
+      data-slot="input"
+      className={cn(
+        "file:text-foreground placeholder:text-muted-foreground selection:bg-primary selection:text-primary-foreground border-input flex h-9 w-full min-w-0 rounded-md border bg-transparent px-3 py-1 text-base shadow-xs transition-[color,box-shadow] outline-none file:inline-flex file:h-7 file:border-0 file:bg-transparent file:text-sm file:font-medium disabled:pointer-events-none disabled:opacity-50 md:text-sm",
+        "focus-visible:border-ring focus-visible:ring-ring/50 focus-visible:ring-[3px]",
+        "aria-invalid:ring-destructive/20 dark:aria-invalid:ring-destructive/40 aria-invalid:border-destructive",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+export { Input }

client/src/components/ui/separator.tsx

@@ -0,0 +1,25 @@
+import * as React from "react"
+import * as SeparatorPrimitive from "@radix-ui/react-separator"
+import { cn } from "@/lib/utils"
+
+function Separator({
+  className,
+  orientation = "horizontal",
+  decorative = true,
+  ...props
+}: React.ComponentProps<typeof SeparatorPrimitive.Root>) {
+  return (
+    <SeparatorPrimitive.Root
+      data-slot="separator"
+      decorative={decorative}
+      orientation={orientation}
+      className={cn(
+        "bg-border shrink-0 data-[orientation=horizontal]:h-px data-[orientation=horizontal]:w-full data-[orientation=vertical]:h-full data-[orientation=vertical]:w-px",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+export { Separator }

client/src/index.css

@@ -0,0 +1,107 @@
+@import "tailwindcss";
+
+@custom-variant dark (&:is(.dark *));
+
+@theme inline {
+  --color-background: var(--background);
+  --color-foreground: var(--foreground);
+  --color-card: var(--card);
+  --color-card-foreground: var(--card-foreground);
+  --color-popover: var(--popover);
+  --color-popover-foreground: var(--popover-foreground);
+  --color-primary: var(--primary);
+  --color-primary-foreground: var(--primary-foreground);
+  --color-secondary: var(--secondary);
+  --color-secondary-foreground: var(--secondary-foreground);
+  --color-muted: var(--muted);
+  --color-muted-foreground: var(--muted-foreground);
+  --color-accent: var(--accent);
+  --color-accent-foreground: var(--accent-foreground);
+  --color-destructive: var(--destructive);
+  --color-destructive-foreground: var(--destructive-foreground);
+  --color-border: var(--border);
+  --color-input: var(--input);
+  --color-ring: var(--ring);
+  --color-sidebar-background: var(--sidebar-background);
+  --color-sidebar-foreground: var(--sidebar-foreground);
+  --color-sidebar-primary: var(--sidebar-primary);
+  --color-sidebar-primary-foreground: var(--sidebar-primary-foreground);
+  --color-sidebar-accent: var(--sidebar-accent);
+  --color-sidebar-accent-foreground: var(--sidebar-accent-foreground);
+  --color-sidebar-border: var(--sidebar-border);
+  --color-sidebar-ring: var(--sidebar-ring);
+  --radius-sm: calc(var(--radius) - 4px);
+  --radius-md: calc(var(--radius) - 2px);
+  --radius-lg: var(--radius);
+  --radius-xl: calc(var(--radius) + 4px);
+}
+
+:root {
+  --radius: 0.625rem;
+  --background: oklch(1 0 0);
+  --foreground: oklch(0.145 0 0);
+  --card: oklch(1 0 0);
+  --card-foreground: oklch(0.145 0 0);
+  --popover: oklch(1 0 0);
+  --popover-foreground: oklch(0.145 0 0);
+  --primary: oklch(0.205 0 0);
+  --primary-foreground: oklch(0.985 0 0);
+  --secondary: oklch(0.97 0 0);
+  --secondary-foreground: oklch(0.205 0 0);
+  --muted: oklch(0.97 0 0);
+  --muted-foreground: oklch(0.556 0 0);
+  --accent: oklch(0.97 0 0);
+  --accent-foreground: oklch(0.205 0 0);
+  --destructive: oklch(0.577 0.245 27.325);
+  --destructive-foreground: oklch(0.577 0.245 27.325);
+  --border: oklch(0.922 0 0);
+  --input: oklch(0.922 0 0);
+  --ring: oklch(0.708 0 0);
+  --sidebar-background: oklch(0.985 0 0);
+  --sidebar-foreground: oklch(0.145 0 0);
+  --sidebar-primary: oklch(0.205 0 0);
+  --sidebar-primary-foreground: oklch(0.985 0 0);
+  --sidebar-accent: oklch(0.97 0 0);
+  --sidebar-accent-foreground: oklch(0.205 0 0);
+  --sidebar-border: oklch(0.922 0 0);
+  --sidebar-ring: oklch(0.708 0 0);
+}
+
+.dark {
+  --background: oklch(0.145 0 0);
+  --foreground: oklch(0.985 0 0);
+  --card: oklch(0.145 0 0);
+  --card-foreground: oklch(0.985 0 0);
+  --popover: oklch(0.145 0 0);
+  --popover-foreground: oklch(0.985 0 0);
+  --primary: oklch(0.985 0 0);
+  --primary-foreground: oklch(0.205 0 0);
+  --secondary: oklch(0.269 0 0);
+  --secondary-foreground: oklch(0.985 0 0);
+  --muted: oklch(0.269 0 0);
+  --muted-foreground: oklch(0.708 0 0);
+  --accent: oklch(0.269 0 0);
+  --accent-foreground: oklch(0.985 0 0);
+  --destructive: oklch(0.577 0.245 27.325);
+  --destructive-foreground: oklch(0.577 0.245 27.325);
+  --border: oklch(0.269 0 0);
+  --input: oklch(0.269 0 0);
+  --ring: oklch(0.439 0 0);
+  --sidebar-background: oklch(0.205 0 0);
+  --sidebar-foreground: oklch(0.985 0 0);
+  --sidebar-primary: oklch(0.488 0.243 264.376);
+  --sidebar-primary-foreground: oklch(0.985 0 0);
+  --sidebar-accent: oklch(0.269 0 0);
+  --sidebar-accent-foreground: oklch(0.985 0 0);
+  --sidebar-border: oklch(0.269 0 0);
+  --sidebar-ring: oklch(0.439 0 0);
+}
+
+@layer base {
+  * {
+    @apply border-border;
+  }
+  body {
+    @apply bg-background text-foreground;
+  }
+}

client/src/lib/utils.ts

@@ -0,0 +1,6 @@
+import { type ClassValue, clsx } from "clsx"
+import { twMerge } from "tailwind-merge"
+
+export function cn(...inputs: ClassValue[]) {
+  return twMerge(clsx(inputs))
+}

client/src/main.tsx

@@ -0,0 +1,10 @@
+import { StrictMode } from 'react'
+import { createRoot } from 'react-dom/client'
+import './index.css'
+import App from './App'
+
+createRoot(document.getElementById('root')!).render(
+  <StrictMode>
+    <App />
+  </StrictMode>,
+)

client/src/pages/Home.tsx

@@ -0,0 +1,85 @@
+import { Button } from '@/components/ui/button'
+import { Card, CardHeader, CardTitle, CardDescription, CardContent } from '@/components/ui/card'
+import { Separator } from '@/components/ui/separator'
+
+export default function HomePage() {
+  return (
+    <div className="min-h-screen bg-background">
+      {/* Header */}
+      <header className="border-b">
+        <div className="container mx-auto flex h-16 items-center justify-between px-4">
+          <h1 className="text-xl font-bold">Company Name</h1>
+          <nav className="flex items-center gap-4">
+            <Button variant="ghost">About</Button>
+            <Button variant="ghost">Contact</Button>
+            <Button>Get Started</Button>
+          </nav>
+        </div>
+      </header>
+
+      {/* Hero */}
+      <section className="container mx-auto px-4 py-24 text-center">
+        <h2 className="text-4xl font-bold tracking-tight sm:text-5xl">
+          Welcome to Your Company
+        </h2>
+        <p className="mx-auto mt-6 max-w-2xl text-lg text-muted-foreground">
+          This is your company website scaffold built with React, shadcn/ui, and TailwindCSS.
+          Start building your product here.
+        </p>
+        <div className="mt-10 flex justify-center gap-4">
+          <Button size="lg">Get Started</Button>
+          <Button size="lg" variant="outline">Learn More</Button>
+        </div>
+      </section>
+
+      <Separator />
+
+      {/* Features */}
+      <section className="container mx-auto px-4 py-16">
+        <h3 className="mb-8 text-center text-2xl font-bold">Features</h3>
+        <div className="grid gap-6 sm:grid-cols-2 lg:grid-cols-3">
+          <Card>
+            <CardHeader>
+              <CardTitle>Feature One</CardTitle>
+              <CardDescription>Description of the first feature.</CardDescription>
+            </CardHeader>
+            <CardContent>
+              <p className="text-sm text-muted-foreground">
+                Add details about this feature here.
+              </p>
+            </CardContent>
+          </Card>
+          <Card>
+            <CardHeader>
+              <CardTitle>Feature Two</CardTitle>
+              <CardDescription>Description of the second feature.</CardDescription>
+            </CardHeader>
+            <CardContent>
+              <p className="text-sm text-muted-foreground">
+                Add details about this feature here.
+              </p>
+            </CardContent>
+          </Card>
+          <Card>
+            <CardHeader>
+              <CardTitle>Feature Three</CardTitle>
+              <CardDescription>Description of the third feature.</CardDescription>
+            </CardHeader>
+            <CardContent>
+              <p className="text-sm text-muted-foreground">
+                Add details about this feature here.
+              </p>
+            </CardContent>
+          </Card>
+        </div>
+      </section>
+
+      {/* Footer */}
+      <footer className="border-t py-8">
+        <div className="container mx-auto px-4 text-center text-sm text-muted-foreground">
+          &copy; {new Date().getFullYear()} Company Name. All rights reserved.
+        </div>
+      </footer>
+    </div>
+  )
+}

client/src/vite-env.d.ts

@@ -0,0 +1 @@
+/// <reference types="vite/client" />

client/tsconfig.app.json

@@ -0,0 +1,3 @@
+{
+  "extends": "./tsconfig.json"
+}

client/tsconfig.json

@@ -0,0 +1,25 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "useDefineForClassFields": true,
+    "lib": ["ES2020", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "skipLibCheck": true,
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "isolatedModules": true,
+    "moduleDetection": "force",
+    "noEmit": true,
+    "jsx": "react-jsx",
+    "strict": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noFallthroughCasesInSwitch": true,
+    "noUncheckedSideEffectImports": true,
+    "baseUrl": ".",
+    "paths": {
+      "@/*": ["./src/*"]
+    }
+  },
+  "include": ["src"]
+}

client/vite.config.ts

@@ -0,0 +1,22 @@
+import { defineConfig } from 'vite'
+import react from '@vitejs/plugin-react'
+import tailwindcss from '@tailwindcss/vite'
+import path from 'path'
+
+export default defineConfig({
+  plugins: [react(), tailwindcss()],
+  resolve: {
+    alias: {
+      '@': path.resolve(__dirname, './src'),
+    },
+  },
+  server: {
+    proxy: {
+      '/api': 'http://localhost:3000',
+      '/health': 'http://localhost:3000',
+    },
+  },
+  build: {
+    outDir: 'dist',
+  },
+})

docker-compose.yml

@@ -1,3 +1,17 @@
+# SAAC Application Stack — PRODUCTION container
+# See SAAC_DEPLOYMENT.md for full deployment rules and common mistakes.
+#
+# This file is used by "saac deploy" to build the production Docker image.
+# Your app also gets a HOT-RELOAD container (yourapp-hot.<server>.domain.com)
+# that auto-rebuilds on every git push — see nodemon.json for its config.
+#
+# Key rules:
+#   1. Use "expose", NEVER "ports" — Traefik handles routing
+#   2. Database host = service name ("postgres"), NEVER "localhost"
+#   3. Do NOT change POSTGRES_DB after first deploy — Docker volume keeps the old name
+#   4. Do NOT add Traefik labels — SAAC uses file provider, labels are ignored
+#   5. Keep it simple — get this working first, then iterate
+
 services:
   app:
     build:
@@ -9,11 +23,17 @@ services:
     environment:
       - NODE_ENV=production
       - PORT=3000
+      # Database host MUST be the service name ("postgres"), not "localhost".
+      # In Docker, localhost = inside this container. "postgres" resolves to
+      # the postgres service below via Docker DNS.
       - POSTGRES_HOST=postgres
       - POSTGRES_PORT=5432
       - POSTGRES_USER=postgres
       - POSTGRES_PASSWORD=postgres
-      - POSTGRES_DB=template_db
+      # WARNING: Do NOT change POSTGRES_DB after first deploy!
+      # The Docker volume persists the original database name.
+      # If you change this, the new database won't exist and your app will crash.
+      - POSTGRES_DB=postgres
       - REDIS_HOST=redis
       - REDIS_PORT=6379
       - APP_VERSION=${APP_VERSION:-1.0.0}
@@ -22,6 +42,9 @@ services:
         condition: service_healthy
       redis:
         condition: service_healthy
+    # Use "expose" to make the port available to Traefik on the Docker network.
+    # NEVER use "ports" (e.g. "3000:3000") — it binds to the host and conflicts
+    # with other apps. Traefik handles all external routing automatically.
     expose:
       - "3000"
     healthcheck:
@@ -37,7 +60,8 @@ services:
     environment:
       - POSTGRES_USER=postgres
       - POSTGRES_PASSWORD=postgres
-      - POSTGRES_DB=template_db
+      # This creates the database on first start. Must match POSTGRES_DB above.
+      - POSTGRES_DB=postgres
     volumes:
       - postgres-data:/var/lib/postgresql/data
     expose:

nodemon.json

@@ -0,0 +1,5 @@
+{
+  "watch": ["server.js"],
+  "ext": "js,json",
+  "exec": "node server.js"
+}

package.json

@@ -1,18 +1,25 @@
 {
   "name": "template-001",
   "version": "1.0.0",
-  "description": "Template site for Start an AI Company deployment",
+  "description": "SAAC company website template — React + shadcn/ui + Express + PostgreSQL",
   "main": "server.js",
   "scripts": {
     "start": "node server.js",
-    "dev": "nodemon server.js"
+    "dev": "nodemon",
+    "build": "cd client && npm run build",
+    "postinstall": "[ -d client ] && cd client && npm install || true",
+    "dev:local": "concurrently \"nodemon server.js\" \"cd client && npm run dev\"",
+    "dev:server": "nodemon server.js",
+    "dev:client": "cd client && npm run dev"
   },
   "dependencies": {
     "express": "^4.18.2",
     "pg": "^8.11.3",
-    "redis": "^4.6.12"
+    "redis": "^4.6.12",
+    "cors": "^2.8.5"
   },
   "devDependencies": {
-    "nodemon": "^3.0.2"
+    "nodemon": "^3.0.2",
+    "concurrently": "^8.2.2"
   }
 }

public/index.html

@@ -1,166 +0,0 @@
-<!DOCTYPE html>
-<html lang="en">
-<head>
-    <meta charset="UTF-8">
-    <meta name="viewport" content="width=device-width, initial-scale=1.0">
-    <title>Template Site - Start an AI Company</title>
-    <style>
-        * {
-            margin: 0;
-            padding: 0;
-            box-sizing: border-box;
-        }
-
-        body {
-            font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Oxygen, Ubuntu, Cantarell, sans-serif;
-            background: linear-gradient(135deg, #f5f7fa 0%, #ffffff 100%);
-            min-height: 100vh;
-            display: flex;
-            justify-content: center;
-            align-items: center;
-            padding: 20px;
-        }
-
-        .container {
-            background: white;
-            border-radius: 20px;
-            box-shadow: 0 20px 60px rgba(0, 0, 0, 0.08);
-            padding: 60px 40px;
-            max-width: 800px;
-            text-align: center;
-            border: 1px solid rgba(0, 0, 0, 0.05);
-        }
-
-        .logo {
-            width: 80px;
-            height: 80px;
-            background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
-            border-radius: 16px;
-            margin: 0 auto 30px;
-            display: flex;
-            align-items: center;
-            justify-content: center;
-            font-size: 40px;
-            color: white;
-            font-weight: bold;
-        }
-
-        h1 {
-            font-size: 2.5rem;
-            color: #1a202c;
-            margin-bottom: 20px;
-            font-weight: 700;
-            line-height: 1.2;
-        }
-
-        p {
-            font-size: 1.2rem;
-            color: #4a5568;
-            line-height: 1.8;
-            margin-bottom: 30px;
-        }
-
-        .features {
-            display: grid;
-            grid-template-columns: repeat(auto-fit, minmax(200px, 1fr));
-            gap: 20px;
-            margin-top: 40px;
-        }
-
-        .feature {
-            background: #f7fafc;
-            padding: 25px 20px;
-            border-radius: 12px;
-            border: 1px solid #e2e8f0;
-            transition: transform 0.2s, box-shadow 0.2s;
-        }
-
-        .feature:hover {
-            transform: translateY(-5px);
-            box-shadow: 0 10px 30px rgba(0, 0, 0, 0.1);
-        }
-
-        .feature-icon {
-            font-size: 2rem;
-            margin-bottom: 10px;
-        }
-
-        .feature-title {
-            font-weight: 600;
-            color: #2d3748;
-            margin-bottom: 8px;
-            font-size: 1rem;
-        }
-
-        .feature-desc {
-            font-size: 0.875rem;
-            color: #718096;
-            margin: 0;
-        }
-
-        .footer {
-            margin-top: 50px;
-            padding-top: 30px;
-            border-top: 1px solid #e2e8f0;
-            color: #718096;
-            font-size: 0.9rem;
-        }
-
-        .status-indicator {
-            display: inline-block;
-            width: 10px;
-            height: 10px;
-            background: #48bb78;
-            border-radius: 50%;
-            margin-right: 8px;
-            animation: pulse 2s infinite;
-        }
-
-        @keyframes pulse {
-            0%, 100% {
-                opacity: 1;
-            }
-            50% {
-                opacity: 0.5;
-            }
-        }
-    </style>
-</head>
-<body>
-    <div class="container">
-        <div class="logo">T</div>
-        <h1>This site is a template site on how to deploy on Start an AI Company servers</h1>
-        <p>A modern, scalable deployment template featuring Docker Compose, PostgreSQL, Redis, and Traefik integration.</p>
-
-        <div class="features">
-            <div class="feature">
-                <div class="feature-icon">🐳</div>
-                <div class="feature-title">Docker Ready</div>
-                <p class="feature-desc">Containerized with Docker Compose</p>
-            </div>
-            <div class="feature">
-                <div class="feature-icon">🗄️</div>
-                <div class="feature-title">PostgreSQL</div>
-                <p class="feature-desc">Robust database solution</p>
-            </div>
-            <div class="feature">
-                <div class="feature-icon">⚡</div>
-                <div class="feature-title">Redis Cache</div>
-                <p class="feature-desc">High-performance caching</p>
-            </div>
-            <div class="feature">
-                <div class="feature-icon">🚀</div>
-                <div class="feature-title">Traefik Ready</div>
-                <p class="feature-desc">Automatic routing & SSL</p>
-            </div>
-        </div>
-
-        <div class="footer">
-            <p>
-                <span class="status-indicator"></span>
-                Status: Running on Start an AI Company infrastructure
-            </p>
-        </div>
-    </div>
-</body>
-</html>

server.js

@@ -6,13 +6,16 @@ const path = require('path');
 const app = express();
 const PORT = process.env.PORT || 3000;
 
+// Middleware
+app.use(express.json());
+
 // PostgreSQL connection
 const pool = new Pool({
   host: process.env.POSTGRES_HOST || 'postgres',
   port: process.env.POSTGRES_PORT || 5432,
   user: process.env.POSTGRES_USER || 'postgres',
   password: process.env.POSTGRES_PASSWORD || 'postgres',
-  database: process.env.POSTGRES_DB || 'template_db'
+  database: process.env.POSTGRES_DB || 'postgres'
 });
 
 // Redis connection
@@ -23,30 +26,22 @@ const redisClient = redis.createClient({
   }
 });
 
-// Connect to Redis
 redisClient.connect().catch(console.error);
 
-// Test database connections
 pool.query('SELECT NOW()', (err, res) => {
   if (err) {
     console.error('PostgreSQL connection error:', err);
   } else {
-    console.log('PostgreSQL connected successfully at:', res.rows[0].now);
+    console.log('PostgreSQL connected at:', res.rows[0].now);
   }
 });
 
-redisClient.on('connect', () => {
+redisClient.on('connect', () => console.log('Redis connected'));
-  console.log('Redis connected successfully');
+redisClient.on('error', (err) => console.error('Redis error:', err));
-});
 
-redisClient.on('error', (err) => {
+// --- API Routes ---
-  console.error('Redis connection error:', err);
-});
 
-// Serve static files
+// Health check
-app.use(express.static('public'));
-
-// Health check endpoint
 app.get('/health', async (req, res) => {
   try {
     const pgResult = await pool.query('SELECT NOW()');
@@ -56,24 +51,37 @@ app.get('/health', async (req, res) => {
       postgres: 'connected',
       redis: 'connected',
       timestamp: pgResult.rows[0].now,
-      git_commit: process.env.GIT_COMMIT || 'unknown',
       version: process.env.APP_VERSION || '1.0.0'
     });
   } catch (error) {
-    res.status(500).json({
+    res.status(500).json({ status: 'unhealthy', error: error.message });
-      status: 'unhealthy',
-      error: error.message,
-      git_commit: process.env.GIT_COMMIT || 'unknown',
-      version: process.env.APP_VERSION || '1.0.0'
-    });
   }
 });
 
-// Main route
+// Example API endpoint — replace with your own
-app.get('/', (req, res) => {
+app.get('/api/status', async (req, res) => {
-  res.sendFile(path.join(__dirname, 'public', 'index.html'));
+  try {
+    const pgResult = await pool.query('SELECT NOW()');
+    res.json({ ok: true, time: pgResult.rows[0].now });
+  } catch (error) {
+    res.status(500).json({ ok: false, error: error.message });
+  }
+});
+
+// --- Serve React Frontend ---
+// In production, serve the built React app from client/dist
+const clientDist = path.join(__dirname, 'client', 'dist');
+app.use(express.static(clientDist));
+
+// SPA fallback — all non-API routes serve index.html so React Router works
+app.get('*', (req, res, next) => {
+  if (req.path.startsWith('/api/') || req.path === '/health') return next();
+  res.sendFile(path.join(clientDist, 'index.html'));
 });
 
 app.listen(PORT, '0.0.0.0', () => {
   console.log(`Server running on port ${PORT}`);
 });
+
+// Export for testing
+module.exports = { app, pool, redisClient };