express-postgres-templated v1.0.0

What's New

• EJS templating — Server-side rendered views with partials and layouts for rapid page building.
• pg Pool with Neon support — Production-ready PostgreSQL connection pool with SSL for Neon serverless Postgres.
• Auto-migration runner — Idempotent migration system that runs on every deploy via npm run migrate.
• Health check endpoint — GET /health returns {"status":"healthy"} without touching the database (avoids Neon auto-suspend).
• Environment validation — App exits fast and clearly if DATABASE_URL is not set, with actionable error messages.
• CSS scoping via sub-paths — Static assets mounted at scoped paths (/css, /docs) so API routes stay unmasked.

Architecture

This template scaffolds a complete Express + Postgres app following Polsia's mandatory architecture rules:

Layer	Location	Rule
Entry point	server.js	Max 300 lines — wiring only
Routes	routes/	One file per endpoint group
Database	db/	Only db/index.js constructs Pool
Migrations	migrations/	Timestamped files, tracked in _migrations
Business logic	services/	Named exports, no inline DB queries

Environment Variables

Variable	Required	Description
DATABASE_URL	Yes	Neon connection string (with SSL). App will not start without it.
PORT	No	Server port. Defaults to 3000.
OPENAI_API_KEY	No	Required only if using AI features (via Polsia platform).
GITHUB_TOKEN	No	Raise GitHub API rate limit from 60 to 5,000 req/hr.

Key Dependencies

• express — Web framework
• ejs — Template engine for server-rendered HTML
• pg — PostgreSQL client with connection pooling
• openai — AI generation via Polsia's OpenAI-compatible proxy

Usage

# Install
npm install

# Run migrations (creates schema, core tables)
npm run migrate

# Start dev server
npm run dev

# Production (Render)
npm run build  # runs migrate then start

Migration System

The migrate.js runner is invoked on every deploy. It:

1. Creates _migrations tracking table (idempotent)
2. Creates core tables: users, sources, documents (idempotent)
3. Runs pending migrations from migrations/ in filename order
4. Tracks each applied migration in _migrations

New migrations: create migrations/{timestamp}_{name}.js with module.exports = { name: '...', up: async (client) => { ... } }.

Bug Fixes

• Route shadowing fixed — Root-level express.static was intercepting /api/* before routes could handle it. Static now mounted at scoped sub-paths (/css, /docs) after API route registration.
• GitHub URL parser — Regex was incorrectly escaping the dot in github.com — now correctly matches standard GitHub repository URLs.