Generic Web/API Template

This repository is a standalone Node/Express template for building server-rendered web apps backed by a JSON API and PostgreSQL. It is designed to be forked for new projects while keeping two clear service boundaries:

• web/: Express server-rendered pages with Mustache, async render middleware, Webpack-built page bundles, DOM components, frontend helpers, and API-backed frontend models.
• api/: Express JSON API with routers, middleware, entity model classes, PostgreSQL driver helper (Postgres) that owns all SQL construction, authentication (Cookies helper, jose JWT, Google OAuth ID token verification), and a complete Transactional Email Outbox Workflow (MailOutbox, MailWorker, MJML templates, and Nodemailer transport).

The template includes built-in authentication with HttpOnly cookies, JWT verification, password login, user registration, and Google login flow (/auth/register, /auth/google, /auth/login, /auth/me, /auth/logout), plus a background outbox mail worker service (mail-worker) for reliable transactional email delivery with 8-attempt stepped backoff retries and operator requeue CLI tools. The checked-in sample items flow and sample-welcome email template are intentionally small so new projects can adapt them to their own domain without removing product-specific behavior.

AI Agent Workflow

The reusable workflow library starts at .agents/prompts/START-HERE.prompt.md. It routes an agent to focused command, domain, stack, and practice prompts after the request and scope are confirmed. See the prompt library guide and routing index; copy .agents/ into a derived repository to bring the workflow with the template.

Environment Variables for Email

Variable	Description
EMAIL_TESTING	Enables Ethereal virtual SMTP transport in local development/testing. Must be false in production.
SMTP_HOST / SMTP_PORT / SMTP_SECURE	SMTP server connection parameters required in production.
SMTP_USER / SMTP_PASSWORD	Optional SMTP authentication credentials.
SMTP_FROM_NAME / SMTP_FROM_EMAIL	Required sender identity used by the mail service.

Quick Start

cp .env.example .env
docker compose -f compose.dev.yaml up -d --build

Open:

• Web: http://localhost
• API readiness: http://localhost:3000/ready

Development Commands

# Start the local stack (web, api, mail-worker, postgres)
docker compose -f compose.dev.yaml up -d --build

# Run database migrations
docker compose -f compose.dev.yaml exec api npm run db:migrate

# API unit tests (includes email outbox and template tests)
docker compose -f compose.dev.yaml exec api sh -c "NODE_ENV=test npm run test:unit"

# Requeue a failed outbox mail job
docker compose -f compose.dev.yaml exec api npm run mail:requeue -- <mailPublicId>

# API integration tests
docker compose -f compose.dev.yaml exec api sh -c "NODE_ENV=test npm run test:integration"

# Web production build
docker compose -f compose.dev.yaml exec web npm run build

# Browser smoke tests
docker compose -f compose.dev.yaml -f compose.playwright.yaml up -d playwright
docker compose -f compose.dev.yaml -f compose.playwright.yaml exec playwright npx playwright test

Use INDEX.md to navigate the repository. Read GUIDE.md for the module boundaries and TESTING.md for validation details.