# gov-cy/govcy-express-services architecture

> Architecture diagram of the GitHub repository gov-cy/govcy-express-services, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-09-15). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/gov-cy/govcy-express-services
- Repository: https://github.com/gov-cy/govcy-express-services

## Overview

##### Project type and purpose
- This is an Express-based, middleware-driven npm package designed to render dynamic government service forms (full “backend + light frontend assets” module).
- It loads JSON form configurations, applies authentication (CY Login OpenID Connect), eligibility and validation logic, and submits data to external DSF/DSF-gateway APIs.

##### Top-level structure (from the file tree)
- src/index.mjs, src/standalone.mjs: entry points that bootstrap an Express server.
- src/auth, src/middleware, src/utils: custom middleware layers and utilities.
- src/public, src/resources: static assets (JS, images) and external assets references (govcy-frontend-renderer, govcy-design-system).
- data/*.json and express-service-shema.json: JSON definitions of sites, pages, forms.
- tests/: unit, integration, functional tests verifying each middleware, API client, and end-to-end flows.

##### Key components
A. Client layer
- Browser (User) → HTTPS → Express server
- Static assets (CSS/JS/images) served from src/public or CDN (govcy-design-system CSS/JS)
- govcy-frontend-renderer loaded in browser for dynamic behaviors (conditional logic, file uploads)

B. Server layer (Node.js + Express)
- Express Routes
– /:siteId/:pageUrl — dynamic page rendering & form POST
– /:siteId/review & /success — review & submission flows
– /apis/:siteId/:pageUrl/upload — file upload proxy
– OIDC callback routes (signin-oidc, login, logout)
- Middleware chain (order matters):
1. cyLoginAuth — enforce user authentication via CY Login (OIDC)
2. govcyConfigSiteData — load JSON config for siteId from /data
3. govcyCsrf — CSRF protection
4. govcyLanguageMiddleware — determine site language
5. govcyServiceEligibilityHandler — loop through eligibility API endpoints with caching
6. govcyLoadSubmissionData — GET temp-save if enabled
7. govcyFileUpload / govcyLoadSubmissionDataAPIs — handle file uploads via POST to external API
8. govcyFormsPostHandler — validate form data, store in session, fire-and-forget PUT temp-save
9. govcyPageHandler & govcyPageRender — select Nunjucks layout + govcy-frontend-renderer template
10. govcyHttpErrorHandler, govcyLogger, govcyRequestTimer — error handling, logging, metrics
- Session store (in-memory or configured) to hold dataLayer (inputData + eligibilityResults)

C. Data/configuration
- JSON files in data/ (per site): site metadata, pages array, sections, elements, validations, API endpoint definitions
- express-service-shema.json: schema for validating service JSON
- Environment variables (.env.* and secrets/.env) for API URLs, client IDs/secrets, service IDs, DSF gateway credentials, session secret

D. External services
1. CY Login (OIDC) — authentication provider
2. DSF API Gateway / cyConnect — gateway for submission, temporary-save, file upload/download/delete, eligibility checks
3. govcy-frontend-renderer npm package (client & server-side rendering helper)
4. govcy-design-system (static CSS/JS from CDN)
5. PDF renderer (govcyPDFRender middleware for server-side PDF generation)

##### Relationships and data flow
- Browser → Express: initial GET /:siteId/:page → cookie + Bearer token (after OIDC) → middleware chain
- Express → JSON data files: load site config for rendering pages
- Express → Session: read/write dataLayer (form values, eligibility results)
- Express → Eligibility APIs (external) with user’s access token + client-key/service-id → cache results in session
- Browser POST form → Express govcyFormsPostHandler → validate → session update → optional PUT temp-save API
- Review page POST → Express → submissionAPIEndpoint → external submission API → on success redirect to /success
- File input actions in browser → AJAX → /apis/:siteId/:page/upload → proxy to fileUploadAPIEndpoint → Data layer stores fileId/sha256
- Download/delete file: browser → Express /download or /delete routes → proxy to external endpoints

##### Architectural patterns & principles
- Layered, middleware pipeline (Separation of concerns: auth, config, CSRF, business logic, rendering, error handling).
- Configuration-driven rendering: JSON templates drive page structure (Pattern: JSON → govcy-frontend-renderer → HTML).
- Externalization of state: minimal server-side state (session for dataLayer), heavy reliance on DSF APIs for persistence (microservices).
- Plugin-style modularity: each middleware in src/middleware is independent and testable.
- Resilience & caching: eligibility checks cached by govcyServiceEligibilityHandler; retry logic in govcyApiRequest.

##### Essential elements
- Dynamic JSON config store as a distinct component driving the middleware
- Related middleware into logical clusters

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    Browser["Browser (User)"]:::frontend
    govcyFS["govcy-frontend-renderer & govcy-design-system"]:::frontend
    PublicAssets["Static Assets (src/public)"]:::frontend

    %% Configuration & Env
    ConfigStore["Configuration Store (data/*.json & express-service-shema.json)"]:::config
    EnvVars["Environment Variables (.env*, secrets/.env)"]:::config

    %% External Services
    CYLogin["CY Login (OIDC)"]:::external
    DSFElig["DSF Eligibility API"]:::external
    DSFTempSave["DSF Temp-Save API"]:::external
    DSFSubmit["DSF Submission API"]:::external
    DSFFile["DSF File Services (upload/download/delete)"]:::external

    %% Express Server Entry
    ExpressEntry["Express Entry Points"]:::internal

    %% Express Server Middleware Layers
    subgraph "Express Server" 
        ExpressEntry
        subgraph "Middleware Layers"
            subgraph Authentication
                A1["cyLoginAuth"]:::internal
            end
            subgraph "Config & Language"
                C1["govcyConfigSiteData"]:::internal
                C2["govcyCsrf"]:::internal
                C3["govcyLanguageMiddleware"]:::internal
            end
            subgraph "Eligibility & Data"
                E1["govcyServiceEligibilityHandler"]:::internal
                E2["govcyLoadSubmissionData"]:::internal
            end
            subgraph "File Handling"
                F1["govcyFileUpload"]:::internal
                F2["govcyFileViewHandler"]:::internal
                F3["govcyFileDeleteHandler"]:::internal
            end
            subgraph "Form Handling"
                H1["govcyFormsPostHandler"]:::internal
            end
            subgraph "Page Rendering"
                R1["govcyRoutePageHandler"]:::internal
                R2["govcyPageHandler"]:::internal
                R3["govcyPageRender"]:::internal
            end
            subgraph "Review & Success"
                RS1["govcyReviewPageHandler"]:::internal
                RS2["govcyReviewPostHandler"]:::internal
                RS3["govcySuccessPageHandler"]:::internal
            end
            subgraph "PDF Generation"
                P1["govcyPDFRender"]:::internal
            end
            subgraph "Logging & Error"
                L1["govcyHttpErrorHandler"]:::internal
                L2["govcyLogger"]:::internal
                L3["govcyRequestTimer"]:::internal
            end
        end
        Session["Session Store"]:::internal
    end

    %% Data Flows
    Browser -->|HTTPS GET/POST| ExpressEntry
    Browser -->|GET assets| PublicAssets
    Browser --> govcyFS

    ExpressEntry --> A1
    A1 -->|OIDC redirect| CYLogin
    A1 --> C1
    C1 --> C2
    C2 --> C3
    C3 --> E1
    E1 -->|eligibility checks| DSFElig
    E1 --> E2
    E2 -->|GET temp-save| DSFTempSave
    E2 --> F1
    F1 -->|proxy upload| DSFFile
    F2 -->|proxy download| DSFFile
    F3 -->|proxy delete| DSFFile
    C3 --> H1
    H1 -->|PUT temp-save| DSFTempSave
    H1 -->|session update| Session
    H1 --> R1
    R1 --> R2
    R2 --> R3
    R3 --> Browser
    R3 --> govcyFS
    R3 --> RS1
    RS1 --> RS2
    RS2 -->|submission POST| DSFSubmit
    RS2 --> RS3
    RS3 --> Browser
    ExpressEntry -->|load config| ConfigStore
    ExpressEntry -->|read/write| Session

    %% Click Events
    click ExpressEntry "https://github.com/gov-cy/govcy-express-services/blob/main/src/index.mjs"
    click A1 "https://github.com/gov-cy/govcy-express-services/blob/main/src/middleware/cyLoginAuth.mjs"
    click C1 "https://github.com/gov-cy/govcy-express-services/blob/main/src/middleware/govcyConfigSiteData.mjs"
    click C2 "https://github.com/gov-cy/govcy-express-services/blob/main/src/middleware/govcyCsrf.mjs"
    click C3 "https://github.com/gov-cy/govcy-express-services/blob/main/src/middleware/govcyLanguageMiddleware.mjs"
    click E1 "https://github.com/gov-cy/govcy-express-services/blob/main/src/middleware/govcyServiceEligibilityHandler.mjs"
    click E2 "https://github.com/gov-cy/govcy-express-services/blob/main/src/middleware/govcyLoadSubmissionData.mjs"
    click F1 "https://github.com/gov-cy/govcy-express-services/blob/main/src/middleware/govcyFileUpload.mjs"
    click F2 "https://github.com/gov-cy/govcy-express-services/blob/main/src/middleware/govcyFileViewHandler.mjs"
    click F3 "https://github.com/gov-cy/govcy-express-services/blob/main/src/middleware/govcyFileDeleteHandler.mjs"
    click H1 "https://github.com/gov-cy/govcy-express-services/blob/main/src/middleware/govcyFormsPostHandler.mjs"
    click R1 "https://github.com/gov-cy/govcy-express-services/blob/main/src/middleware/govcyRoutePageHandler.mjs"
    click R2 "https://github.com/gov-cy/govcy-express-services/blob/main/src/middleware/govcyPageHandler.mjs"
    click R3 "https://github.com/gov-cy/govcy-express-services/blob/main/src/middleware/govcyPageRender.mjs"
    click RS1 "https://github.com/gov-cy/govcy-express-services/blob/main/src/middleware/govcyReviewPageHandler.mjs"
    click RS2 "https://github.com/gov-cy/govcy-express-services/blob/main/src/middleware/govcyReviewPostHandler.mjs"
    click RS3 "https://github.com/gov-cy/govcy-express-services/blob/main/src/middleware/govcySuccessPageHandler.mjs"
    click P1 "https://github.com/gov-cy/govcy-express-services/blob/main/src/middleware/govcyPDFRender.mjs"
    click L1 "https://github.com/gov-cy/govcy-express-services/blob/main/src/middleware/govcyHttpErrorHandler.mjs"
    click L2 "https://github.com/gov-cy/govcy-express-services/blob/main/src/middleware/govcyLogger.mjs"
    click L3 "https://github.com/gov-cy/govcy-express-services/blob/main/src/middleware/govcyRequestTimer.mjs"
    click PublicAssets "https://github.com/gov-cy/govcy-express-services/tree/main/src/public"
    click govcyFS "https://github.com/gov-cy/govcy-express-services/blob/main/src/resources/govcyResources.mjs"
    click ConfigStore "https://github.com/gov-cy/govcy-express-services/blob/main/express-service-shema.json"
    click EnvVars "https://github.com/gov-cy/govcy-express-services/blob/main/.env.development"

    %% Styles
    classDef frontend fill:#fddc5c,stroke:#e69a00,color:#000
    classDef internal fill:#a0c4ff,stroke:#3d5a80,color:#000
    classDef config fill:#d3d3d3,stroke:#666,color:#000
    classDef external fill:#caffbf,stroke:#2f8f2f,color:#000
```
