How alphagov/pay-selfservice works
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.