Citizens Advice is a network of independent charities that helps people find a way forward with their problems, from legal rights and housing to debt, work, and health. Operating across England and Wales, the organisation provides free, confidential, and impartial advice, empowering individuals to make informed decisions and access the support they need.
Project Overview
Project Intro
The Witness Service Referral project modernised how Citizens Advice supports vulnerable court witnesses and partner organisations.
Before this work, referrals arrived through inconsistent channels — emails, phone calls, and outdated web forms — creating delays and risking missed support for those who needed it most.
I joined the Content Platform team to lead the build of a standalone Rails 7 referral service: fast to launch, secure by design, and capable of integrating directly with the Witness Box case-management API. The goal was to create a GOV.UK-style experience that balanced empathy and efficiency — helping witnesses access help confidently while keeping data safe and traceable.
Client Description — Citizens Advice
Citizens Advice is the UK’s largest network of independent charities offering free, confidential information and advice to help people resolve their problems — from legal and financial issues to housing, health, and justice.
The organisation’s Witness Service provides emotional and practical support to witnesses in criminal courts, helping them give their best evidence and feel less anxious during proceedings.
For this initiative, Citizens Advice needed a secure, accessible referral platform that could operate outside the legacy website, integrate with internal case-management systems, and comply with strict data-protection standards.
The resulting service empowers both self-referring witnesses and partner organisations to request help quickly — a critical upgrade in the support process.
Role & Scope
- Role: Senior Full-Stack Engineer embedded in the Content Platform squad
- Timeline: 3 months (concept to pilot)
- Team: 1 designer, 1 content designer, 2 engineers, 1 SRE, and Witness Service stakeholders
- My remit: Own the application architecture, implement dual referral journeys, strengthen security and observability, and steer deployments and instrumentation.
Problem
Witness referrals were coming through fragmented channels, leading to delays and lost cases.
We needed a single multi-step form that could handle both self-referrals and professional referrals, comply with data retention and privacy rules, and send validated submissions directly into the Witness Box API — with observability, monitoring, and rollback safety nets.
What I Built
- Rails 7 + Redis Service: A dedicated app built with the Citizens Advice Design System baked in for rapid iteration (
Gemfile:6–65,package.json:4–27). - Wizard-Based UX: Dual referral journeys (individual and organisation) that reuse shared steps for maintainability (
docs/architecture-decisions/0005-form-workflows.md:11–74). - Data Safeguards: Session TTLs, environment-gated authentication, and full session resets post-submission (
config/initializers/session_store.rb:5–16). - Witness Box API Integration: A Faraday-based client and formatters that map data to API contracts with Datadog-backed observability (
app/services/api/witnessbox.rb:3–47). - Delivery Pipeline: Infrastructure guidance for CDK + Helm deployments, with rollback playbooks and secrets management (
infrastructure/README.md:1–148).
Technical Highlights
Dual Workflow Wizard
Two parallel wizard classes — individual and organisation — manage unique step flows and validations while reusing shared components like PersonNeedingSupport. This balances clarity and code reuse (app/models/witness_referral/steps/person_needing_support.rb:5–30).
Safety-First Data Handling
Redis-backed sessions auto-expire after 24 hours, purging PII safely. Feature-flagged HTTP Basic Auth locks down non-production environments, backed by request specs and ADR documentation (docs/architecture-decisions/0004-dev-environment-basic-auth.md:11–158).
Witness Box API Integration
A lightweight Faraday client handles authentication and environment routing. Formatter objects sanitize and transform session data before posting to the API. Contract tests ensure payload integrity and response validity.
Accessible Front End
Every page uses the Citizens Advice Design System for visual and semantic consistency with GOV.UK. Enhancements like Accessible Autocomplete and focus management improve usability across devices (app/views/witness_referral/start/index.html.haml:2–22).
Observability & Analytics
Integrated Datadog APM and semantic JSON logging for production; disabled automatically in dev for clean local logs. GA4 via Tag Manager captures funnel analytics per step (docs/analytics.md:1–6).
Delivery & Ops
Automated CDK + Helm deployments within the Content Platform ecosystem, sharing ECR and CI/CD pipelines. Rollback procedures and cluster ownership follow documented playbooks for resilience.
Impact
- Unified self-referral and organisation referral workflows into one accessible service.
- Reduced form deployment time from hours to minutes by decoupling from the main website.
- Strengthened data privacy with expiring sessions and restricted non-prod access.
- Delivered auditable, monitored API integration ensuring confidence in inbound data.
What’s Next
- Complete organisation-specific formatter for parity with individual referral flows.
- Integrate live Witness Box court lookup API to replace static lists.
- Expand analytics dashboards to surface completion and drop-off metrics per step.
Stack at a Glance
- Backend: Ruby 3.2.2, Rails 7.0.8, WizardSteps, Redis session store, Faraday, ViewComponent
- Frontend: Citizens Advice Design System, HAML, esbuild, Sass, Accessible Autocomplete
- Tooling: RSpec/Capybara, RuboCop, Brakeman, Datadog APM, Semantic Logger, GA4, AWS CDK + Helm
Outcome
A secure, fast, and accessible referral platform that modernised a critical citizen-facing service — enabling timely, reliable witness support while setting a new technical standard for form-based services at Citizens Advice.