CPP Institutional Records Management System

Node.js/Express gateway and UI for the CPP application. Serves HTML/HTMX pages, manages sessions (stored in Neon Postgres), and proxies API calls to the Flask backend.

Requirements

• Node.js 18+
• Flask backend on Railway (or local)
• Neon Postgres (sessions + shared with Flask)
• SMTP credentials (student email login codes)

Local setup

1. Install dependencies:

   npm install
   npm run build:css

2. Configure environment:

   copy .env.example .env    # Windows
   cp .env.example .env      # macOS/Linux

3. Start Flask backend first, then the web app:

   npm run dev

   Open http://localhost:3001

Deploy to Render (recommended for web app)

Use Render for this repo and Railway for cpp-backend. Deploy the backend first.

Prerequisites

• Flask API live on Railway with a public URL, e.g. https://cpp-backend-production.up.railway.app
• Backend health check passes:

  curl https://YOUR-BACKEND.up.railway.app/api/v1/health

Option A — Blueprint (render.yaml)

1. Push this repo to GitHub (Lanoiracali/cpp-student-record).
2. dashboard.render.com → New → Blueprint → connect the repo.
3. Render reads render.yaml and creates the web service.
4. In the Render dashboard, set secrets Render could not fill:
   • FLASK_BACKEND_URL → https://YOUR-BACKEND.up.railway.app
   • DATABASE_URL → Neon connection string (same as backend)
   • SMTP_USER / SMTP_PASS → Gmail App Password
   • SESSION_SECRET → auto-generated by blueprint, or set your own
5. Deploy → open https://cpp-student-record.onrender.com (or your assigned URL).

Option B — Manual Web Service

1. New → Web Service → connect cpp-student-record.

2. Settings:

   • Runtime: Node
   • Build: npm install && npm run build:css
   • Start: npm start
   • Health check path: /health

3. Environment variables:

   Variable	Value
   NODE_ENV	production
   FLASK_BACKEND_URL	https://YOUR-BACKEND.up.railway.app
   DATABASE_URL	Neon connection string
   SESSION_SECRET	openssl rand -hex 32
   SMTP_HOST	smtp.gmail.com
   SMTP_PORT	587
   SMTP_SECURE	false
   SMTP_USER	your email
   SMTP_PASS	Gmail App Password

4. Deploy and verify:

   curl https://YOUR-APP.onrender.com/health

Preflight (before deploy)

# Set production values in .env first, then:
npm run check:deploy

Deploy to Railway (alternative)

You can run both services on Railway instead of Render. See railway.json and the DEPLOY.md guide in the parent folder.

Architecture (production)

Browser  →  Render (cpp-student-record)  →  Railway (cpp-backend)  →  Neon Postgres
              Express + sessions                 Flask API

• Users visit the Render URL only.
• FLASK_BACKEND_URL is server-side (not exposed to the browser).
• Sessions persist in Neon (express_sessions table).

Environment variables

Variable	Required	Description
PORT	Auto	Set by Render
NODE_ENV	Prod	production
FLASK_BACKEND_URL	Yes	Railway backend HTTPS URL
DATABASE_URL	Yes	Neon Postgres
SESSION_SECRET	Yes (prod)	Session signing key
SMTP_*	For email login	Nodemailer

Production notes

• SESSION_SECRET must be set in production or the app exits on startup.
• Cookies use secure: true when NODE_ENV=production (Render provides HTTPS).
• Free tier may spin down after inactivity — first request can be slow (~30s).
• Pick a Render region close to Neon (ap-southeast) if available.
• Do not commit .env.

Features

• Express gateway, HTMX partials, Tailwind CSS
• Teacher/student auth via Flask API
• Nodemailer for student temporary login codes
• Postgres-backed sessions