# dwp/govuk-casa architecture

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

- Interactive diagram: https://gitdiagram.com/dwp/govuk-casa
- Repository: https://github.com/dwp/govuk-casa

## Overview

##### Project type and purpose
- CASA is a Node.js framework/library (not a standalone full-stack application) built on Express.js. It provides:
- A set of middleware, routing, templating and configuration ingestion utilities
- A plugin/hook architecture for extensibility
- Nunjucks-based views and GOV.UK Design System–compliant components
- Multi-language support via i18n

##### File structure
- Top-level:
- src/ – core library code (lib/, middleware/, routes/, core-plugins/)
- views/ – built-in view components and layouts (Nunjucks macros, templates)
- assets/ – SCSS partials for the GOV.UK theme
- examples/ – sample “consumer” Express apps that mount CASA
- docs/, tests/, scripts/ – documentation, E2E + unit tests, build scripts
- Core architecture patterns:
- Express middleware pipeline
- Plugin/hook registration (pre- and post-steer, custom plugins under core-plugins/)
- Configuration ingestion -> Journey plan builder -> Mutable router
- MVC-style separation:
– “Controller” logic in middleware and route handlers
– “View” logic in Nunjucks templates and component macros
– “Model” logic in definitions (fields/pages/plan)

##### README for additional insights
- CASA is heavily centered on:
- Configuration-driven “journey” definitions (pages, fields, routing rules)
- Extensibility via hooks and plugins
- Shallow learning curve built on Express
- No prebuilt database or external persistence beyond the session store

## Diagram (Mermaid)

```mermaid
graph TD
    subgraph Initialization
        ConfigIngest["Configuration Ingestor"]:::core
        PlanBuilder["Plan Builder"]:::core
        ConfigIngest --> PlanBuilder
    end

    subgraph "Session & Context"
        JourneyContext["JourneyContext"]:::core
        SessionMiddleware["Session Middleware"]:::middleware
    end

    subgraph "Request Handling"
        BodyParser["Body Parser"]:::middleware
        CSRF["CSRF Protection"]:::middleware
        I18n["Internationalization"]:::middleware
        GatherFields["Gather Fields"]:::middleware
        Sanitise["Sanitise Fields"]:::middleware
        Validate["Validate Fields"]:::middleware
        PreHook["Pre Hooks"]:::middleware
        Steering["Steer Journey (MutableRouter)"]:::middleware
        PostHook["Post Hooks"]:::middleware
        Progress["Progress Tracking"]:::middleware
        Skip["Skip Waypoint"]:::middleware
        ServeFirst["Serve First Waypoint"]:::middleware
    end

    subgraph Routing
        JourneyRoutes["Journey Routes"]:::core
        StaticRoutes["Static Assets"]:::core
        AncillaryRoutes["Ancillary Routes"]:::core
    end

    subgraph Plugins
        CorePlugins["Core Plugins"]:::plugins
    end

    subgraph Views_Assets
        Components["Nunjucks Components"]:::views
        Layouts["Layouts"]:::views
        Partials["Partials"]:::views
        Errors["Error Templates"]:::views
        SessionTimeout["Session Timeout View"]:::views
        SCSS["SCSS Assets"]:::views
    end

    subgraph External
        Node["Node.js Runtime"]:::external
        Express["Express.js"]:::external
        GOVUK["GOV.UK Design System"]:::external
        Locales["Locale Files"]:::external
    end

    ConsumerApp["Consumer Express App"]:::external

    Node --> Express
    ConsumerApp -->|mounts CASA| Express
    Express --> BodyParser --> CSRF --> I18n --> GatherFields --> Sanitise --> Validate --> PreHook --> Steering --> PostHook --> Progress --> Skip --> ServeFirst --> Routing
    Steering -->|uses| MutableRouter["MutableRouter"]:::core
    ConfigIngest -->|initializes| MutableRouter
    PlanBuilder -->|builds| MutableRouter
    Express --> JourneyContext
    Express --> SessionMiddleware
    Routing --> JourneyRoutes
    Routing --> StaticRoutes
    Routing --> AncillaryRoutes
    PreHook --> CorePlugins
    PostHook --> CorePlugins
    JourneyRoutes --> Components
    JourneyRoutes --> Layouts
    JourneyRoutes --> Partials
    JourneyRoutes --> Errors
    JourneyRoutes --> SessionTimeout
    SCSS -->|overrides| GOVUK
    Express -->|loads| Locales

    classDef core fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef middleware fill:#90EE90,stroke:#333,stroke-width:1px
    classDef plugins fill:#FFA500,stroke:#333,stroke-width:1px
    classDef views fill:#D8BFD8,stroke:#333,stroke-width:1px
    classDef external fill:#D3D3D3,stroke:#333,stroke-width:1px

    click ConsumerApp "https://github.com/dwp/govuk-casa/blob/main/examples/barebones/app.js"
    click ConfigIngest "https://github.com/dwp/govuk-casa/blob/main/src/lib/configuration-ingestor.js"
    click PlanBuilder "https://github.com/dwp/govuk-casa/blob/main/src/lib/Plan.js"
    click MutableRouter "https://github.com/dwp/govuk-casa/blob/main/src/lib/MutableRouter.js"
    click JourneyContext "https://github.com/dwp/govuk-casa/blob/main/src/lib/JourneyContext.js"
    click SessionMiddleware "https://github.com/dwp/govuk-casa/blob/main/src/middleware/session.js"
    click BodyParser "https://github.com/dwp/govuk-casa/blob/main/src/middleware/body-parser.js"
    click CSRF "https://github.com/dwp/govuk-casa/blob/main/src/middleware/csrf.js"
    click I18n "https://github.com/dwp/govuk-casa/blob/main/src/middleware/i18n.js"
    click GatherFields "https://github.com/dwp/govuk-casa/blob/main/src/middleware/gather-fields.js"
    click Sanitise "https://github.com/dwp/govuk-casa/blob/main/src/middleware/sanitise-fields.js"
    click Validate "https://github.com/dwp/govuk-casa/blob/main/src/middleware/validate-fields.js"
    click PreHook "https://github.com/dwp/govuk-casa/blob/main/src/middleware/pre.js"
    click Steering "https://github.com/dwp/govuk-casa/blob/main/src/middleware/steer-journey.js"
    click PostHook "https://github.com/dwp/govuk-casa/blob/main/src/middleware/post.js"
    click Progress "https://github.com/dwp/govuk-casa/blob/main/src/middleware/progress-journey.js"
    click Skip "https://github.com/dwp/govuk-casa/blob/main/src/middleware/skip-waypoint.js"
    click ServeFirst "https://github.com/dwp/govuk-casa/blob/main/src/middleware/serve-first-waypoint.js"
    click JourneyRoutes "https://github.com/dwp/govuk-casa/blob/main/src/routes/journey.js"
    click StaticRoutes "https://github.com/dwp/govuk-casa/blob/main/src/routes/static.js"
    click AncillaryRoutes "https://github.com/dwp/govuk-casa/blob/main/src/routes/ancillary.js"
    click CorePlugins "https://github.com/dwp/govuk-casa/tree/main/src/core-plugins/"
    click Components "https://github.com/dwp/govuk-casa/tree/main/views/casa/components/"
    click Layouts "https://github.com/dwp/govuk-casa/tree/main/views/casa/layouts/"
    click Partials "https://github.com/dwp/govuk-casa/tree/main/views/casa/partials/"
    click Errors "https://github.com/dwp/govuk-casa/tree/main/views/casa/errors/"
    click SessionTimeout "https://github.com/dwp/govuk-casa/blob/main/views/casa/session-timeout.njk"
    click SCSS "https://github.com/dwp/govuk-casa/tree/main/assets/scss/"
    click Express "https://github.com/dwp/govuk-casa/blob/main/src/index.js"
    click Locales "https://github.com/dwp/govuk-casa/tree/main/locales/"
```
