A Dockerized Express 5 backend that accepts simulation parameter sets from researchers, queues them for processing by EC2 workers, and stores results (per-model-per-function lowest fitness values) to Amazon DynamoDB with real-time progress tracking.
# Install dependencies
npm install
# Create .env (see docs/setup.md for details)
cp .env.example .env # or create manually
# Start DynamoDB Local and create the tables
docker compose up -d dynamodb
npm run db:create
# Start development server
npm run dev
# Or start everything with Docker Compose
docker-compose up --buildThe server runs on http://localhost:3000.
Swagger UI available at http://localhost:3000/api/v1/docs.
Full documentation is available in the docs/ directory:
| Document | Description |
|---|---|
| PRD | Product requirements, user stories, implementation decisions |
| Context | Living codebase context: layout, API surface, conventions, gotchas |
| Implementation Plan | Master plan for the 001-004 work and the decisions log |
| Feature Plans | Per-feature plans (001 repo health, 002 refresh tokens, 003 error semantics, 004 docs) |
| Setup Guide | Installation, environment variables, Docker |
| Architecture | Project structure, design decisions, request lifecycle |
| Authentication | JWT auth flow, refresh token rotation, RBAC |
| API Reference | All endpoints with request/response examples |
| Database Models | DynamoDB tables, keys, GSIs, item shapes (CLAUDE.md) |
| Middleware | Auth, admin, validation, error handling, logging |
| Testing | Test structure, running tests, coverage |
| Layer | Technology |
|---|---|
| Runtime | Node.js 20 |
| Framework | Express 5 |
| Database | Amazon DynamoDB (AWS SDK v3, no ODM) |
| Auth | JWT + bcrypt + refresh token rotation (hashed at rest) |
| Validation | Zod 4 |
| Logging | Winston + Morgan |
| Security | Helmet, CORS, httpOnly cookies |
| API Docs | Swagger/OpenAPI 3.0 |
| Testing | Jest 30 + Supertest 7 (107 tests, 6 suites) |
| Containerization | Docker (multi-stage, Node 20 slim) |
All routes are versioned under /api/v1.
| Endpoint Group | Auth | Description |
|---|---|---|
/api/v1/register, /login, /verify, /refresh, /logout |
— | Authentication |
/api/v1/user/profile, /user/password |
Bearer token | User profile management |
/api/v1/simulation/* |
Bearer token | Simulation CRUD, results, and .txt data import |
/api/v1/admin/* |
Bearer token + Admin | Admin oversight |
/api/v1/health |
— | Health check |
/api/v1/docs |
— | Swagger UI |
See the API Reference for complete details.
npm start # Start production server
npm run dev # Start dev server (nodemon hot-reload)
npm test # Run all tests -- requires DynamoDB Local:
# docker compose up -d dynamodb (container de-dynamodb, port 8000)
npm run test:watch # Run tests in watch mode
npm run test:coverage # Run tests with coverage report├── app.js # Express app (middleware, routes)
├── server.js # Server entry point
├── config/ # Database, logger, S3 and SQS clients
├── controllers/ # Route handlers (auth, simulation, admin, user)
├── middleware/ # auth, admin, validation, error handling
├── models/ # DynamoDB data-access facades (User, Simulation) — no ODM
├── routes/ # Express routers (auth, simulation, admin, user)
├── validators/ # Zod validation schemas
├── utils/ # importParser (.txt import format) + typed HTTP errors
├── docs/ # Documentation + Swagger config
├── tests/ # Jest + Supertest test suites
├── Dockerfile # Production image
├── Dockerfile.dev # Development image
└── docker-compose.yml # DynamoDB Local + backend services
See Architecture for detailed breakdown.
The dashboard compares up to 80 different Differential Evolution models by combining:
- 10 mutation schemes (1–10)
- 4 crossover operators (1–4)
- 2 selection methods (1–2)
Across 10 benchmark fitness functions (1–10), the system computes all combinations as a Cartesian product and stores the lowest fitness value for each model per function.