Architecture Overview

Technical stack, deployment model, environment configuration, and runtime behavior.

Tech Stack

Runtime

Component	Technology	Notes
Runtime	Node.js 18	Single-process Express app
Web Framework	Express 4
Database	PostgreSQL (Neon — serverless)	Connection via `DATABASE_URL`
Hosting	Render	Web service, ephemeral filesystem
Migrations	node-pg-migrate	Run on deploy via `npm run migrate`

Frontend

Component	Technology
Markup	Vanilla HTML/CSS
Typography	Space Grotesk, JetBrains Mono, DM Sans
Analytics	GA4 (client-side), Polsia beacon
Tracking	Meta Pixel (Facebook)

Build & Deploy

File	Purpose
`render.yaml`	Render service definition — start command, env vars, health check
`Dockerfile`	Container image (used for local dev)
`migrate.js`	Runs on each deploy: `npm run migrate && npm start`
`polsia.toml`	Cron schedules (Blaxel-compatible)

Deployment

Startup Sequence

npm run migrate — runs all pending node-pg-migrate migrations in migrations/
npm start → server.js — middleware setup, route mounts, API key seed
If POLSIA_IN_PROCESS_CRONS_ENABLED === 'true' → scheduler daemon starts (30s polling)
app.listen(port) — Render health check ready

Scheduler Daemon (Blaxel Migration Notes)

The in-process scheduler runs via setInterval(runSchedulerCycle, 30000). It is guarded by POLSIA_IN_PROCESS_CRONS_ENABLED === 'true'. On Blaxel shadow, that env is false — Blaxel handles scheduling via polsia.toml [[crons]].

See jobs/scheduler-cycle.js for the standalone cron runner (used by Blaxel).

Health Check

Render health probe at /health — returns { "status": "ok" } with no auth required. The /api/health path also returns healthy — kept for backwards compatibility.

Environment Variables

Required

Variable	Description
`DATABASE_URL`	Neon PostgreSQL connection string. Required — server exits if missing.
`PORT`	Listen port (default: 3000)

Optional

Variable	Default	Description
`POLSIA_IN_PROCESS_CRONS_ENABLED`	`false`	Enable in-process scheduler on Render. Blaxel shadow sets this to `false`.
`POLSIA_ANALYTICS_SLUG`	`""`	Polsia analytics slug for beacon pixel on landing page.
`GOOGLE_ANALYTICS_ID`	`G-GPUFORGEPLACEHOLDER`	GA4 measurement ID.

Port Reference

Path	Auth	Description
`/health`	None	Render health probe
`/api/health`	None	Backwards-compatible health check
`/`	None	Landing page
`/login`	None	Login page
`/dashboard`	None (client-gated)	Operator dashboard
`/docs`	None	API Reference
`/docs/hub`	None	Documentation hub
`/docs/hld`	None	High-Level Design
`/docs/lld`	None	Low-Level Design
`/docs/architecture`	None	Architecture overview (this page)
`/pitch`	None	Downloadable pitch deck
`/admin`	None (client-gated)	Admin dashboard
`/api/*`	Bearer token	All API endpoints (demo mode if no auth)