# dfe-digital/register-placement-schools architecture

> Architecture diagram of the GitHub repository dfe-digital/register-placement-schools, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-04-09). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/dfe-digital/register-placement-schools
- Repository: https://github.com/dfe-digital/register-placement-schools

## Overview

1. **Overall shape**
   - This is a **Ruby on Rails monolith** for the “Register of placement schools.”
   - The app is primarily server-rendered, with a small amount of JavaScript and PWA support rather than a separate frontend service.

2. **Core request flow**
   - Web requests enter through Rails controllers and routes in `config/routes.rb`.
   - The visible user-facing pages appear to be a **landing page** and **sign-in flow**, plus standard **error pages** and a **heartbeat** endpoint for health checks.

3. **Authentication boundary**
   - Authentication is integrated with **DfE Sign-In** via OmniAuth (`config/initializers/omniauth/dfe_sign_in.rb`).
   - The flow is split across `sessions_controller`, `sign_in_controller`, and `sign_out_controller`.
   - Local persistence includes `user` and `dfe_sign_in_user` models, with a service object under `app/services/dfe_sign_in_users/update.rb` likely responsible for syncing identity data from the external auth provider into the local database.

4. **Domain data and persistence**
   - The application uses **PostgreSQL** through ActiveRecord.
   - Migrations show support for **UUID primary keys** and `pgcrypto`.
   - The `audited` gem is installed and schema migrations add audit indexes, so change history is persisted as part of the data model rather than handled externally.

5. **Business logic placement**
   - The repo uses a **service-object pattern** (`app/lib/service_pattern.rb`, `app/services/...`) to keep non-trivial domain logic out of controllers and models.
   - Validators for email formatting live in `app/validators`, indicating user identity and contact data are part of the domain rules.

6. **UI and presentation layer**
   - Views are server-rendered ERB templates under `app/views`.
   - Styling is built from Sass under `app/assets/stylesheets`.
   - The app uses GOV.UK-oriented form tooling (`govuk_formbuilder` initializer), which suggests a government service UI style and component set.
   - There is also PWA support via a manifest and service worker in `app/views/pwa`.

7. **Operational endpoints and resilience**
   - `HeartbeatController` provides a lightweight health endpoint for uptime and deployment checks.
   - `ErrorsController` maps to custom 404/500/422 pages, and public static error pages also exist under `public/`.
   - Logging and request hygiene are configured centrally with `semantic_logger` and parameter filtering.

8. **Background and asynchronous work**
   - The repo includes `app/jobs`, `ApplicationJob`, and `config/queue.yml` / `config/recurring.yml`, indicating Rails-backed background processing.
   - `solid_queue` is installed in the database migrations, so async work is likely stored and processed via the app’s own Postgres-backed queue infrastructure rather than a separate queue broker.

9. **Runtime and deployment**
   - The application is packaged for containerized deployment with a `Dockerfile`, `docker-compose.yml`, `Procfile.dev`, and Puma config.
   - Multiple environment files exist for **production, staging, qa, review, test, and development**, showing the service is promoted through several non-prod environments.
   - `config/credentials.yml.enc`, `config/storage.yml`, and environment-specific configs indicate runtime configuration is environment-driven.

10. **Maintenance and failover architecture**
   - The `maintenance_page/` directory is a separate deliverable with its own Dockerfile, Nginx config, HTML assets, and Kubernetes manifests.
   - It includes **failover/failback scripts** and ingress manifests that switch traffic between the main app and a maintenance service.
   - This means the service is designed to support controlled downtime or disaster recovery without changing the primary Rails codebase.

11. **Infrastructure as code**
   - Terraform is used for both the application and its domain/infrastructure setup.
   - There are separate Terraform areas for application deployment, environment-specific domains, and shared infrastructure/zones.
   - Status monitoring is also codified in Terraform (`statuscake.tf`), so availability checks are part of the deployed architecture.

12. **Delivery and environment automation**
   - GitHub Actions workflows handle builds, deploys, review apps, database backup/restore, and maintenance operations.
   - This suggests a CI/CD model where application release, environment provisioning, and database lifecycle tasks are automated and tied to the repository.

13. **Quality and governance**
   - The repo uses RSpec for tests, RuboCop for style/linting, Brakeman for security scanning, and ERB linting.
   - ADRs are checked into `adr/`, so important architecture decisions are versioned alongside the code.

14. **How to draw the diagram**
   - The main diagram should center on the **Rails app + PostgreSQL** pair.
   - Add an external **DfE Sign-In identity provider** feeding the auth flow.
   - Show a **background job/queue lane** backed by the same database.
   - Show **Terraform/GitHub Actions** as the deployment/control plane.
   - Show the **maintenance page service** as a separate ingress target used during failover or maintenance mode.

Main entry points: [`config/routes.rb`](https://github.com/dfe-digital/register-placement-schools/blob/main/config/routes.rb) (Routes), [`app/models/user.rb`](https://github.com/dfe-digital/register-placement-schools/blob/main/app/models/user.rb) (Users), [`.github/workflows/build-and-deploy.yml`](https://github.com/dfe-digital/register-placement-schools/blob/main/.github/workflows/build-and-deploy.yml) (CI/CD), [`app/controllers/sessions_controller.rb`](https://github.com/dfe-digital/register-placement-schools/blob/main/app/controllers/sessions_controller.rb) (Auth flow)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Rails app"]
  node_routes["Routes<br/>Rails routing<br/>[routes.rb]"]
  node_landing_controller["Landing<br/>controller"]
  node_auth_controllers["Auth flow<br/>controllers"]
  node_errors_controller["Errors<br/>controller"]
  node_heartbeat_controller["Heartbeat<br/>controller"]
  node_sign_in_views["Sign-in UI<br/>views<br/>[index.html.erb]"]
  node_landing_views["Landing UI<br/>views<br/>[start.html.erb]"]
  node_error_views["Error pages<br/>views<br/>[not_found.html.erb]"]
  node_service_pattern["Service pattern<br/>support module<br/>[service_pattern.rb]"]
  node_identity_sync["Identity sync<br/>[update.rb]"]
  node_validators["Email rules<br/>validators"]
end

subgraph group_ops["Delivery & infra"]
  node_ci_cd["CI/CD<br/>GitHub Actions"]
  node_terraform["Terraform<br/>infrastructure as code<br/>[application.tf]"]
  node_maintenance_page["Maintenance site<br/>failover service"]
end

subgraph group_data["Persistence"]
  node_models[("Users<br/>models<br/>[user.rb]")]
  node_database[("PostgreSQL<br/>database<br/>[schema.rb]")]
  node_queue["Solid Queue<br/>background jobs<br/>[queue.yml]"]
end

node_omniauth(("DfE Sign-In<br/>external identity provider<br/>[dfe_sign_in.rb]"))

node_routes -->|"public pages"| node_landing_controller
node_routes -->|"auth endpoints"| node_auth_controllers
node_routes -->|"error pages"| node_errors_controller
node_routes -->|"health check"| node_heartbeat_controller
node_landing_controller -->|"renders"| node_landing_views
node_auth_controllers -->|"renders"| node_sign_in_views
node_errors_controller -->|"renders"| node_error_views
node_auth_controllers -->|"delegates"| node_omniauth
node_omniauth -.->|"identity data"| node_models
node_identity_sync -->|"updates"| node_models
node_service_pattern -.->|"structure"| node_identity_sync
node_validators -.->|"validates"| node_models
node_models -->|"persists"| node_database
node_queue -->|"backed by"| node_database
node_ci_cd -->|"provisions"| node_terraform
node_ci_cd -->|"switches traffic"| node_maintenance_page
node_terraform -->|"deploys"| node_maintenance_page
node_ci_cd -.->|"backup/restore"| node_database

click node_routes "https://github.com/dfe-digital/register-placement-schools/blob/main/config/routes.rb"
click node_landing_controller "https://github.com/dfe-digital/register-placement-schools/blob/main/app/controllers/landing_page_controller.rb"
click node_auth_controllers "https://github.com/dfe-digital/register-placement-schools/blob/main/app/controllers/sessions_controller.rb"
click node_errors_controller "https://github.com/dfe-digital/register-placement-schools/blob/main/app/controllers/errors_controller.rb"
click node_heartbeat_controller "https://github.com/dfe-digital/register-placement-schools/blob/main/app/controllers/heartbeat_controller.rb"
click node_sign_in_views "https://github.com/dfe-digital/register-placement-schools/blob/main/app/views/sign_in/index.html.erb"
click node_landing_views "https://github.com/dfe-digital/register-placement-schools/blob/main/app/views/landing_page/start.html.erb"
click node_error_views "https://github.com/dfe-digital/register-placement-schools/blob/main/app/views/errors/not_found.html.erb"
click node_service_pattern "https://github.com/dfe-digital/register-placement-schools/blob/main/app/lib/service_pattern.rb"
click node_identity_sync "https://github.com/dfe-digital/register-placement-schools/blob/main/app/services/dfe_sign_in_users/update.rb"
click node_validators "https://github.com/dfe-digital/register-placement-schools/blob/main/app/validators/email_format_validator.rb"
click node_models "https://github.com/dfe-digital/register-placement-schools/blob/main/app/models/user.rb"
click node_database "https://github.com/dfe-digital/register-placement-schools/blob/main/db/schema.rb"
click node_queue "https://github.com/dfe-digital/register-placement-schools/blob/main/config/queue.yml"
click node_omniauth "https://github.com/dfe-digital/register-placement-schools/blob/main/config/initializers/omniauth/dfe_sign_in.rb"
click node_ci_cd "https://github.com/dfe-digital/register-placement-schools/blob/main/.github/workflows/build-and-deploy.yml"
click node_terraform "https://github.com/dfe-digital/register-placement-schools/blob/main/terraform/application/application.tf"
click node_maintenance_page "https://github.com/dfe-digital/register-placement-schools/blob/main/maintenance_page/manifests/maintenance/service_maintenance.yml"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_routes,node_landing_controller,node_auth_controllers,node_errors_controller,node_heartbeat_controller,node_sign_in_views,node_landing_views,node_error_views,node_service_pattern,node_identity_sync,node_validators toneBlue
class node_ci_cd,node_terraform,node_maintenance_page toneAmber
class node_models,node_database,node_queue toneMint
class node_omniauth toneNeutral
```

## Components

### Rails app

Server-rendered Rails monolith and its application-layer concerns.

- [Routes](https://github.com/dfe-digital/register-placement-schools/blob/main/config/routes.rb): Rails routing · Entry points and request dispatch. · `config/routes.rb`
- [Landing](https://github.com/dfe-digital/register-placement-schools/blob/main/app/controllers/landing_page_controller.rb): controller · Public start page. · `app/controllers/landing_page_controller.rb`
- [Auth flow](https://github.com/dfe-digital/register-placement-schools/blob/main/app/controllers/sessions_controller.rb): controllers · Sign-in, sign-out, and callback/session handling. · `app/controllers/sessions_controller.rb`
- [Errors](https://github.com/dfe-digital/register-placement-schools/blob/main/app/controllers/errors_controller.rb): controller · Custom 404/422/500 pages. · `app/controllers/errors_controller.rb`
- [Heartbeat](https://github.com/dfe-digital/register-placement-schools/blob/main/app/controllers/heartbeat_controller.rb): controller · Lightweight health check endpoint. · `app/controllers/heartbeat_controller.rb`
- [Sign-in UI](https://github.com/dfe-digital/register-placement-schools/blob/main/app/views/sign_in/index.html.erb): views · Server-rendered sign-in pages. · `app/views/sign_in/index.html.erb`
- [Landing UI](https://github.com/dfe-digital/register-placement-schools/blob/main/app/views/landing_page/start.html.erb): views · Public landing page templates. · `app/views/landing_page/start.html.erb`
- [Error pages](https://github.com/dfe-digital/register-placement-schools/blob/main/app/views/errors/not_found.html.erb): views · Rendered error templates. · `app/views/errors/not_found.html.erb`
- [Service pattern](https://github.com/dfe-digital/register-placement-schools/blob/main/app/lib/service_pattern.rb): support module · Shared pattern for service objects. · `app/lib/service_pattern.rb`
- [Identity sync](https://github.com/dfe-digital/register-placement-schools/blob/main/app/services/dfe_sign_in_users/update.rb): service · Syncs DfE Sign-In identity data into local records. · `app/services/dfe_sign_in_users/update.rb`
- [Email rules](https://github.com/dfe-digital/register-placement-schools/blob/main/app/validators/email_format_validator.rb): validators · Domain validation for email and DfE email formats. · `app/validators/email_format_validator.rb`

### Delivery & infra

Deployment, maintenance, and infrastructure automation.

- [CI/CD](https://github.com/dfe-digital/register-placement-schools/blob/main/.github/workflows/build-and-deploy.yml): GitHub Actions · Build, deploy, backup, restore, and maintenance automation. · `.github/workflows/build-and-deploy.yml`
- [Terraform](https://github.com/dfe-digital/register-placement-schools/blob/main/terraform/application/application.tf): infrastructure as code · Application, domain, and shared infrastructure definitions. · `terraform/application/application.tf`
- [Maintenance site](https://github.com/dfe-digital/register-placement-schools/blob/main/maintenance_page/manifests/maintenance/service_maintenance.yml): failover service · Separate maintenance target and ingress switch-over path. · `maintenance_page/manifests/maintenance/service_maintenance.yml`

### Persistence

Primary data store and database-backed background processing.

- [Users](https://github.com/dfe-digital/register-placement-schools/blob/main/app/models/user.rb): models · Local user and DfE Sign-In user records. · `app/models/user.rb`
- [PostgreSQL](https://github.com/dfe-digital/register-placement-schools/blob/main/db/schema.rb): database · Primary relational datastore with UUIDs, audits, and queue tables. · `db/schema.rb`
- [Solid Queue](https://github.com/dfe-digital/register-placement-schools/blob/main/config/queue.yml): background jobs · Database-backed asynchronous job processing. · `config/queue.yml`

### Other components

- [DfE Sign-In](https://github.com/dfe-digital/register-placement-schools/blob/main/config/initializers/omniauth/dfe_sign_in.rb): external identity provider · External authentication boundary via OmniAuth. · `config/initializers/omniauth/dfe_sign_in.rb`

## Connections

- Routes → Landing: public pages · Routes dispatch to the landing page controller.
- Routes → Auth flow: auth endpoints · Routes dispatch sign-in and sign-out flows.
- Routes → Errors: error pages · Routes map custom error responses.
- Routes → Heartbeat: health check · Routes expose a heartbeat endpoint.
- Landing → Landing UI: renders · Landing controller renders the start page.
- Auth flow → Sign-in UI: renders · Authentication controllers render sign-in UI.
- Errors → Error pages: renders · Error controller renders the custom error pages.
- Auth flow → DfE Sign-In: delegates · Authentication flow delegates to DfE Sign-In via OmniAuth.
- DfE Sign-In → Users: identity data · External identity maps into local user records.
- Identity sync → Users: updates · Service object syncs DfE Sign-In user data into the database.
- Service pattern → Identity sync: structure · Service objects follow the shared service pattern.
- Email rules → Users: validates · Email rules protect persisted user data.
- Users → PostgreSQL: persists · ActiveRecord stores users and audit history in PostgreSQL.
- Solid Queue → PostgreSQL: backed by · Jobs are stored and processed through the database-backed queue.
- CI/CD → Terraform: provisions · Automation deploys and operates infrastructure via Terraform.
- CI/CD → Maintenance site: switches traffic · Workflows support maintenance and failover operations.
- Terraform → Maintenance site: deploys · Infrastructure code defines the maintenance ingress and service.
- CI/CD → PostgreSQL: backup/restore · Automation manages database lifecycle tasks.
