How opengovsg/checkfirst works
Project Type and Purpose
• CheckFirst is a full-stack, single-repository web application for building “eligibility checkers” and calculators for Singapore Government policies.
• The client is a React/TypeScript SPA; the server is Node.js/Express using Sequelize for data persistence, with optional AWS Lambda/API Gateway serverless deployments.
High-Level File Structure Analysis
• Top-level config files: ESLint, Prettier, Husky, GitHub workflows, serverless.yml, webpack.config.js, tsconfig.json.
• public/: static HTML, robots.txt, manifest.json.
• src/client/: the frontend React application (components, pages, services, contexts, hooks, assets, styles, theme).
• src/server/: the backend (Express app entrypoint, serverless entrypoints, routing modules under api/, feature modules: auth, checker, template; database config, migrations, models, seeders; utils; bootstrap scripts).
• src/shared/: shared core logic (parser, evaluator) usable by both client and server.
• src/types/: global TypeScript declarations.
README Insights
• The server has two entrypoints: a traditional Express HTTP server (src/server/index.ts) and serverless handlers (src/server/serverless/api.ts, static.ts).
• DB defaults to SQLite; production uses Postgres via Sequelize with migration scripts.
• Environment variables configured in src/server/config.
A. Main Components
• Client Browser (React SPA)
• Static Asset Host (S3/CloudFront or serverless static handler)
• API Layer:
– Express.js server for self-hosted deployments
– API Gateway + AWS Lambda for serverless deployments
• Authentication Service (JWT/session via AuthController/AuthService)
• Checker Service (CRUD for checkers)
• Template Service (CRUD for templates)
• Database (SQLite for dev, Postgres on RDS in prod) via Sequelize models
• Shared Logic Module (parser, evaluator) used by client builder and server validation
• External Services:
– AWS S3/CloudFront or Static Lambda for static files
– AWS Secrets Manager or Env vars for config
– Google Analytics (client)
B. Relationships & Interactions
1. Browser loads index.html → static assets (JS/CSS/images) from S3/CloudFront or static Lambda
2. React App mounts (App.tsx), uses contexts (AuthContext, CheckerContext)
3. Client invokes ApiClient → HTTP calls to API Gateway or Express server
4. API Gateway routes to Lambda (serverless/api) or Express routes → controllers (AuthController, CheckerController, TemplateController)
5. Controllers invoke Services → Sequelize Models → Database
6. Shared evaluator/parser used by both client builder and server‐side validation
7. Responses flow back through API → client updates UI
8. Auth flows: login → AuthService generates JWT/session → stored in browser (cookie or localStorage) → attached to subsequent requests
C. Architectural Patterns & Principles
• Layered MVC structure on server: Controllers → Services → Models
• Component-based and context-driven architecture on client (React hooks & contexts)
• Shared core logic extracted to shared/core for DRY validation and parsing
• Infrastructure as code: serverless.yml for AWS Lambda + API Gateway
• Migration management via Sequelize CLI
D. Key Technologies
• Frontend: React, TypeScript, Webpack, React Router (via PrivateRoute), Zustand-like contexts, styled-components or CSS modules
• Backend: Node.js, Express.js, TypeScript, Sequelize ORM, serverless framework
• Database: SQLite (dev), PostgreSQL (prod)
• CI/CD: GitHub Actions (ci.yml), Dependabot, Mergify
• Git Hooks: Husky, Commitlint