89 lines
3.2 KiB
Markdown
89 lines
3.2 KiB
Markdown
|
# 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:**
|
||
|
|
```bash
|
||
|
|
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
|
||
|
|
```bash
|
||
|
|
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
|
||
|
|
```bash
|
||
|
|
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)
|
||
|
|
```bash
|
||
|
|
./start-servers.sh # Start backend + frontend in background
|
||
|
|
./stop-servers.sh # Stop all servers
|
||
|
|
```
|
||
|
|
|
||
|
|
### Database Migrations (run from `backend/`)
|
||
|
|
```bash
|
||
|
|
node migrations/run-all.js # Runs all migrations in order (idempotent)
|
||
|
|
```
|
||
|
|
|
||
|
|
### Python Scripts (from `backend/scripts/`)
|
||
|
|
```bash
|
||
|
|
# 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 |
|