# opengovsg/checkfirst architecture

> Architecture diagram of the GitHub repository opengovsg/checkfirst, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/opengovsg/checkfirst
- Repository: https://github.com/opengovsg/checkfirst

## Overview

##### 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

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend (React SPA)" 
        direction TB
        Browser["Client Browser"]:::external
        CDN["Static Assets (S3/CloudFront)"]:::external
        StaticLambda["Static Lambda"]:::serverless
        Browser -->|"load index.html"| CDN
        Browser -->|"load index.html"| StaticLambda

        CDN -->|"serves public/index.html"| EntryPoint
        StaticLambda -->|"serves public/index.html"| EntryPoint

        EntryPoint["src/client/index.tsx"]:::frontend
        click EntryPoint "https://github.com/opengovsg/checkfirst/blob/develop/src/client/index.tsx"
        EntryPoint --> AppComponent

        AppComponent["src/client/App.tsx"]:::frontend
        click AppComponent "https://github.com/opengovsg/checkfirst/blob/develop/src/client/App.tsx"
        AppComponent --> AuthContext
        AppComponent --> CheckerContext
        AppComponent --> GAContext
        AppComponent --> ApiClient

        AuthContext["AuthContext"]:::frontend
        click AuthContext "https://github.com/opengovsg/checkfirst/blob/develop/src/client/contexts/AuthContext.tsx"
        CheckerContext["CheckerContext"]:::frontend
        click CheckerContext "https://github.com/opengovsg/checkfirst/blob/develop/src/client/contexts/CheckerContext.tsx"
        GAContext["GoogleAnalyticsContext"]:::frontend
        click GAContext "https://github.com/opengovsg/checkfirst/blob/develop/src/client/contexts/GoogleAnalyticsContext.tsx"

        ApiClient["ApiClient"]:::frontend
        click ApiClient "https://github.com/opengovsg/checkfirst/blob/develop/src/client/api/ApiClient.ts"

        subgraph "Pages" 
            direction TB
            Landing["Landing Page"]:::frontend
            click Landing "https://github.com/opengovsg/checkfirst/blob/develop/src/client/pages/Landing/Landing.tsx"
            Dashboard["Dashboard Page"]:::frontend
            click Dashboard "https://github.com/opengovsg/checkfirst/blob/develop/src/client/pages/Dashboard.tsx"
            FormBuilder["Form Builder Page"]:::frontend
            click FormBuilder "https://github.com/opengovsg/checkfirst/blob/develop/src/client/pages/FormBuilder.tsx"
            CheckerPage["Checker Page"]:::frontend
            click CheckerPage "https://github.com/opengovsg/checkfirst/blob/develop/src/client/pages/Checker.tsx"
            Login["Login Page"]:::frontend
            click Login "https://github.com/opengovsg/checkfirst/blob/develop/src/client/pages/Login.tsx"
        end

        AppComponent --> Landing
        AppComponent --> Dashboard
        AppComponent --> FormBuilder
        AppComponent --> CheckerPage
        AppComponent --> Login

        Landing --> ApiClient
        Dashboard --> ApiClient
        FormBuilder --> ApiClient
        CheckerPage --> ApiClient
        Login --> ApiClient
    end

    %% Shared Core Logic
    SharedCore["Shared Core Logic"]:::shared
    Parser["parser.ts"]:::shared
    click Parser "https://github.com/opengovsg/checkfirst/blob/develop/src/shared/core/parser.ts"
    Evaluator["evaluator.ts"]:::shared
    click Evaluator "https://github.com/opengovsg/checkfirst/blob/develop/src/shared/core/evaluator.ts"
    SharedCore --> Parser
    SharedCore --> Evaluator

    %% API Layer
    subgraph "API Layer"
        direction TB
        APIGateway["API Gateway"]:::serverless
        ExpressServer["Express Server"]:::server
        click ExpressServer "https://github.com/opengovsg/checkfirst/blob/develop/src/server/index.ts"
        APIGateway --> LambdaAPI
        LambdaAPI["API Lambda"]:::serverless
        click LambdaAPI "https://github.com/opengovsg/checkfirst/blob/develop/src/server/serverless/api.ts"
        LambdaAPI --> AuthController
        LambdaAPI --> CheckerController
        LambdaAPI --> TemplateController

        ExpressServer --> AuthController
        ExpressServer --> CheckerController
        ExpressServer --> TemplateController

        StaticHandler["Static Lambda"]:::serverless
        click StaticHandler "https://github.com/opengovsg/checkfirst/blob/develop/src/server/serverless/static.ts"
    end

    %% Services and Controllers
    AuthController["AuthController"]:::service
    click AuthController "https://github.com/opengovsg/checkfirst/blob/develop/src/server/auth/AuthController.ts"
    CheckerController["CheckerController"]:::service
    click CheckerController "https://github.com/opengovsg/checkfirst/blob/develop/src/server/checker/CheckerController.ts"
    TemplateController["TemplateController"]:::service
    click TemplateController "https://github.com/opengovsg/checkfirst/blob/develop/src/server/template/TemplateController.ts"

    AuthService["AuthService"]:::service
    click AuthService "https://github.com/opengovsg/checkfirst/blob/develop/src/server/auth/AuthService.ts"
    CheckerService["CheckerService"]:::service
    click CheckerService "https://github.com/opengovsg/checkfirst/blob/develop/src/server/checker/CheckerService.ts"
    TemplateService["TemplateService"]:::service
    click TemplateService "https://github.com/opengovsg/checkfirst/blob/develop/src/server/template/TemplateService.ts"

    AuthController --> AuthService
    CheckerController --> CheckerService
    TemplateController --> TemplateService

    AuthService --> SharedCore
    CheckerService --> SharedCore
    TemplateService --> SharedCore

    %% Database Layer
    subgraph "Database Layer"
        direction TB
        DB["Database"]:::database
        ModelsIndex["models/index.ts"]:::database
        click ModelsIndex "https://github.com/opengovsg/checkfirst/blob/develop/src/server/database/models/index.ts"
        UserModel["User.ts"]:::database
        click UserModel "https://github.com/opengovsg/checkfirst/blob/develop/src/server/database/models/User.ts"
        CheckerModel["Checker.ts"]:::database
        click CheckerModel "https://github.com/opengovsg/checkfirst/blob/develop/src/server/database/models/Checker.ts"
        TemplateModel["Template.ts"]:::database
        click TemplateModel "https://github.com/opengovsg/checkfirst/blob/develop/src/server/database/models/Template.ts"
        Migrations["migrations/"]:::database
        click Migrations "https://github.com/opengovsg/checkfirst/tree/develop/src/server/database/migrations"

        DB --> ModelsIndex
        ModelsIndex --> UserModel
        ModelsIndex --> CheckerModel
        ModelsIndex --> TemplateModel
        Migrations --> DB
    end

    %% Config
    Config["Server Config"]:::config
    click Config "https://github.com/opengovsg/checkfirst/blob/develop/src/server/config.ts"

    %% External Analytics
    GA["Google Analytics"]:::external

    %% Interactions
    ApiClient -->|HTTP Request| APIGateway
    ApiClient -->|HTTP Request| ExpressServer
    APIGateway -->|invoke| LambdaAPI
    ExpressServer -->|route| AuthController
    ExpressServer -->|route| CheckerController
    ExpressServer -->|route| TemplateController

    AuthService -->|queries| DB
    CheckerService -->|queries| DB
    TemplateService -->|queries| DB

    Browser -->|collect data| GA

    Config --> ExpressServer
    Config --> LambdaAPI

    SharedCore --> AppComponent
    SharedCore --> AuthService
    SharedCore --> CheckerService
    SharedCore --> TemplateService

    %% Styles
    classDef frontend fill:#ADD8E6,stroke:#000
    classDef server fill:#FFA500,stroke:#000
    classDef serverless fill:#FFA500,stroke:#000,stroke-dasharray: 5 5
    classDef database fill:#90EE90,stroke:#000
    classDef shared fill:#D8BFD8,stroke:#000
    classDef external fill:#D3D3D3,stroke:#000
    classDef service fill:#FFA500,stroke:#000
    classDef config fill:#ffffff,stroke:#000,stroke-dasharray: 2 2
```
