Tech Stack & Build System

Stack

Layer	Technology
Backend	Node.js 18+, Express 5
Database	PostgreSQL (via `pg` pool in `backend/db.js`)
Auth	bcryptjs, cookie-based sessions (httpOnly, 24h expiry)
File uploads	Multer 2 (10MB limit)
Frontend	React 19 (Create React App / react-scripts 5)
Frontend serving	Express serves `frontend/build/` as static files on port 3001
UI Icons	lucide-react
Charts	recharts
Spreadsheet parsing	xlsx (frontend), pandas + openpyxl (backend Python scripts)
Markdown rendering	react-markdown
Diagrams	mermaid

Architecture: Single-Port Serving

Express on port 3001 serves both the API and the production frontend build:

API routes: /api/* — handled by Express route handlers
Frontend: everything else — served as static files from frontend/build/

There is no separate frontend server in production. The React dev server (npm start on port 3000) is only for local development with hot-reload. In production and on the dev server, you must run npm run build in frontend/ after any frontend code change, then restart the backend.

After editing frontend source files:

cd frontend && npm run build    # Compile new bundle into frontend/build/
# Then restart backend (or it will serve the new static files on next request)

The CI/CD pipeline handles this automatically — build-frontend stage runs before deploy.

Common Commands

Backend

cd backend
node setup.js          # Initialize DB, tables, indexes, default admin user
node server.js         # Start backend on port 3001 (serves API + frontend build)

Frontend

cd frontend
npm install            # Install dependencies
npm run build          # Production build → frontend/build/ (REQUIRED after code changes)
npm start              # Dev server on port 3000 (local dev only, NOT used in production)
npm test               # Run tests (react-scripts test)

Both servers (from project root)

./start-servers.sh     # Start backend + frontend in background
./stop-servers.sh      # Stop all servers

Database Migrations (run from `backend/`)

node migrations/run-all.js    # Runs all migrations in order (idempotent)

Python Scripts (from `backend/scripts/`)

# Compliance xlsx parsing (called automatically by upload flow)
python3 parse_compliance_xlsx.py <file>

# Bulk notes import
python3 import_notes_from_csv.py input.csv --dry-run
python3 import_notes_from_csv.py input.csv

Python dependencies: pandas>=2.0.0, openpyxl>=3.0.0 (install via apt or venv).

Environment Configuration

backend/.env — PORT, CORS_ORIGINS, SESSION_SECRET, NVD_API_KEY, Ivanti API credentials
frontend/.env — REACT_APP_API_BASE, REACT_APP_API_HOST
Both .env files are gitignored; see .env.example files for templates.
React env vars are baked in at build time — you must rebuild (npm run build) after changing them.

Ports

Environment	URL	Notes
Production / Dev server	http://IP:3001	Express serves API + static frontend build
Local dev (frontend only)	http://localhost:3000	React dev server with hot-reload, proxies API to :3001

3.2 KiB Raw Blame History