# alphagov/pay-selfservice architecture

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

- Interactive diagram: https://gitdiagram.com/alphagov/pay-selfservice
- Repository: https://github.com/alphagov/pay-selfservice

## Overview

Based on our analysis of the file tree and the README, the project is a full-stack Node.js web application providing a self-service admin tool for GOV.UK Pay. It uses a layered (or MVC‐style) architecture where the presentation layer (Nunjucks views, client-side JavaScript, SCSS assets) is separated from the business logic (controllers, services, middleware, models) and integrated with external services (such as public authentication, connector, ledger, etc.).

##### Main components and layers
- Frontend/Presentation Layer:
– Views are rendered from Nunjucks templates (found in src/views) and include static assets (Sass, images, CSV files, etc. in src/assets).
– Client-side JavaScript (in src/client-side) providing interactive functionality.
- Backend/Web Server:
– The Express-based server is started from src/server.js and configured in src/config.
– Controllers in src/controllers handle specific routes and business logic. These are organized into feature sets (such as login, registration, payment-links, dashboards, etc.).
– Routes are defined in src/routes.js and integrated with middleware.
- Middleware:
– Various middleware components (in src/middleware) handle error handling, permission checking, logging, and session management.
- Service Layer:
– Services located in src/services encapsulate business logic and orchestrate interactions with external clients.
– These include clients for external systems such as Public Auth, Connector, Ledger, Stripe, Zendesk, etc. (located in src/services/clients).
- Data/Model Layer:
– Domain models in src/models define constants and data structures (e.g., payment providers, error identifiers, etc.).
- External Integrations:
– There are several external API client integrations to systems like Public Auth, Connector, Ledger, and payment processors.
- Testing and CI/CD:
– Unit tests (via Mocha), end-to-end tests (via Cypress in the test directory), and Pact tests in test/pact.
– Continuous integration pipelines set up via GitHub Actions (.github/workflows).
- DevOps/Deployment Components:
– Dockerfile and scripts (in scripts/*) define how the application is containerized and launched using the Pay CLI.

##### Interaction flows
- Requests hit the Express server at a defined port (by default 9200 or as configured) and are processed through middleware (e.g., for error handling, session and permission management).
- The request routes to appropriate controllers based on the URL (as mapped in src/routes.js).
- Controllers invoke business logic methods via service classes and then render views with Nunjucks for the frontend.
- Client-side assets (JS and CSS) are built by tools such as esbuild (via esbuild.config.mjs) and served statically.
- When needed, the service layer makes calls to external systems (via service clients) to authenticate, validate transactions, manage payments, etc.
- Logging and error tracking are integrated throughout (e.g., via middleware and utilities in src/utils/sentry.js).

##### Architectural patterns and design principles
- A clear separation of concerns is observed (MVC or layered architecture) – the presentation (views, assets), business logic (controllers, services) and external integrations (clients).
- Reusability is maintained through modular controllers and services (with each controller residing in its own subdirectory for different functionalities such as “api-keys”, “login”, “registration”, “dashboards”, etc.).
- Extensive testing infrastructure (unit, integration, Cypress, Pact) assures system reliability.

##### Relevant technologies and libraries
- Node.js as the runtime and Express (or similar) for handling HTTP requests.
- Nunjucks templating for view rendering.
- ESBuild for asset bundling.
- Testing frameworks such as Mocha, Cypress, and Pact for different testing strategies.
- Docker and Pay CLI for containerization and local development/deployment.

b. Within the backend, subdivide:
– Show controllers grouped by domain features.
– Link the controllers to middleware (error handling, authentication, etc.).
– Connect the controllers to the service layer representing business logic.
– Illustrate the service layer’s connections to external API services.
c. In the frontend layer, indicate client assets (HTML rendered from Nunjucks, client-side JS, CSS) and show how they interface with the backend (e.g., via HTTP requests).
d. Components for the development toolchain (Docker, Pay CLI) and testing suites to underline continuous deployment and integration aspects.

- Every component is clearly named and grouped logically.

## Diagram (Mermaid)

```mermaid
graph TB
    %% Frontend – Presentation Layer
    subgraph "Frontend – Presentation Layer"
        A1["Nunjucks Views"]:::frontend
        A2["Static Assets"]:::frontend
        A3["Client-side JS"]:::frontend
    end

    %% Backend Layer
    subgraph "Backend Layer"
        B1["Express Server"]:::backend
        B2["Server Config"]:::backend
        B3["Routes"]:::backend
        B4["Controllers"]:::backend
        B5["Middleware"]:::backend
        B6["Services"]:::backend
        B7["External API Clients"]:::backend
        B8["Models"]:::backend
    end

    %% External Systems
    subgraph "External Systems"
        E1["Public Auth"]:::external
        E2["Connector"]:::external
        E3["Ledger"]:::external
        E4["Stripe"]:::external
        E5["Zendesk"]:::external
    end

    %% Testing and CI/CD
    subgraph "Integration & Testing"
        C1["Tests"]:::test
        C2["CI/CD"]:::test
    end

    %% DevOps / Deployment
    subgraph "DevOps & Deployment"
        D1["Dockerfile"]:::devops
        D2["Scripts"]:::devops
    end

    %% Connections between Frontend and Backend
    A3 -->|"HTTP_Request"| B1
    B1 -->|"ConfiguredBy"| B2
    B1 -->|"UsesRoutes"| B3
    B3 -->|"Directs"| B4
    B3 -->|"Applies"| B5
    B5 -->|"ForwardsRequest"| B4
    B4 -->|"Invokes"| B6
    B4 -->|"RenderView"| A1
    B6 -->|"CallsAPIs"| B7
    B6 -->|"UsesData"| B8
    B7 -->|"ExternalAPICall"| E1
    B7 -->|"ExternalAPICall"| E2
    B7 -->|"ExternalAPICall"| E3
    B7 -->|"ExternalAPICall"| E4
    B7 -->|"ExternalAPICall"| E5

    %% Connections for Testing and CI/CD
    C1 ---|"Validates"| B4
    C1 ---|"Validates"| B6
    C2 ---|"Deploys"| B1
    C2 ---|"Deploys"| A1
    C2 ---|"Deploys"| D1
    C2 ---|"Deploys"| D2

    %% Connections for DevOps/Deployment
    D1 -->|"Containerize"| B1
    D2 -->|"HelperScripts"| B1

    %% Styles and Classes
    classDef frontend fill:#b3d9ff,stroke:#333,stroke-width:2px;
    classDef backend fill:#d9ffb3,stroke:#333,stroke-width:2px;
    classDef external fill:#ffe6cc,stroke:#333,stroke-width:2px;
    classDef test fill:#e6ccff,stroke:#333,stroke-width:2px;
    classDef devops fill:#ffd1dc,stroke:#333,stroke-width:2px;

    %% Click Events
    click A1 "https://github.com/alphagov/pay-selfservice/tree/master/src/views"
    click A2 "https://github.com/alphagov/pay-selfservice/tree/master/src/assets"
    click A3 "https://github.com/alphagov/pay-selfservice/tree/master/src/client-side"
    click B1 "https://github.com/alphagov/pay-selfservice/blob/master/src/server.js"
    click B2 "https://github.com/alphagov/pay-selfservice/tree/master/src/config"
    click B4 "https://github.com/alphagov/pay-selfservice/tree/master/src/controllers"
    click B3 "https://github.com/alphagov/pay-selfservice/blob/master/src/routes.js"
    click B5 "https://github.com/alphagov/pay-selfservice/tree/master/src/middleware"
    click B6 "https://github.com/alphagov/pay-selfservice/tree/master/src/services"
    click B7 "https://github.com/alphagov/pay-selfservice/tree/master/src/services/clients"
    click B8 "https://github.com/alphagov/pay-selfservice/tree/master/src/models"
    click C1 "https://github.com/alphagov/pay-selfservice/tree/master/test"
    click C2 "https://github.com/alphagov/pay-selfservice/tree/master/.github/workflows"
    click D1 "https://github.com/alphagov/pay-selfservice/tree/master/Dockerfile"
    click D2 "https://github.com/alphagov/pay-selfservice/tree/master/scripts"
```
