How dfe-digital/register-placement-schools works
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: routes.rb Routes · user.rb Users · build-and-deploy.yml CI/CD · sessions_controller.rb Auth flow
Components 18
Rails app
Server-rendered Rails monolith and its application-layer concerns.
- Routes · Entry points and request dispatch.
config/routes.rb - Landing · Public start page.
app/controllers/landing_page_controller.rb - Auth flow · Sign-in, sign-out, and callback/session handling.
app/controllers/sessions_controller.rb - Errors · Custom 404/422/500 pages.
app/controllers/errors_controller.rb - Heartbeat · Lightweight health check endpoint.
app/controllers/heartbeat_controller.rb - Sign-in UI · Server-rendered sign-in pages.
app/views/sign_in/index.html.erb - Landing UI · Public landing page templates.
app/views/landing_page/start.html.erb - Error pages · Rendered error templates.
app/views/errors/not_found.html.erb - Service pattern · Shared pattern for service objects.
app/lib/service_pattern.rb - Identity sync · Syncs DfE Sign-In identity data into local records.
app/services/dfe_sign_in_users/update.rb - Email rules · Domain validation for email and DfE email formats.
app/validators/email_format_validator.rb
Delivery & infra
Deployment, maintenance, and infrastructure automation.
- CI/CD · Build, deploy, backup, restore, and maintenance automation.
.github/workflows/build-and-deploy.yml - Terraform · Application, domain, and shared infrastructure definitions.
terraform/application/application.tf - Maintenance site · 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 · Local user and DfE Sign-In user records.
app/models/user.rb - PostgreSQL · Primary relational datastore with UUIDs, audits, and queue tables.
db/schema.rb - Solid Queue · Database-backed asynchronous job processing.
config/queue.yml
Other components
- DfE Sign-In · External authentication boundary via OmniAuth.
config/initializers/omniauth/dfe_sign_in.rb
Connections 18
- 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.