How gov-cy/govcy-express-services works
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