hmpps-contacts-ui: Instructions file for Codex

hmpps-contacts-ui Agent Instructions

Frontend UI for creating and managing prisoner contacts within the Digital Prison Service (DPS). See README.md for setup and running instructions.

Build & Test Commands

npm run build          # compile with esbuild
npm run start:dev      # build + watch (development)
npm run lint           # ESLint, max-warnings 0
npm run lint-fix       # ESLint auto-fix
npm run typecheck      # tsc check (app + integration_tests)
npm run test           # Jest unit tests
npm run test:ci        # Jest in serial mode (CI)
npm run int-test       # Cypress headless (requires docker-compose-test.yml + start-feature)
npm run int-test-ui    # Cypress interactive

Architecture

Routes (controllers)  →  Services (business logic)  →  Data Clients (RestClient subclasses)  →  External APIs

• server/routes/ — feature-grouped Express routers
• server/services/ — orchestration; inject into routes as constructor args
• server/data/ — RestClient subclasses (one per external API)
• server/middleware/ — auth, validation, permissions, audit
• server/views/ — Nunjucks templates (GOV.UK + MoJ design system)
• server/@types/ — generated API types (do not edit by hand; re-generate via scripts/generate-*.sh)

Key Conventions

Controllers

Use method properties (GET =, POST =), not class methods. Handlers must be async (req, res): Promise<void>.

export default class MyController {
  constructor(private readonly myService: MyService) {}

  GET = async (req: Request<MyParams>, res: Response): Promise<void> => { ... }
  POST = async (req: Request<MyParams>, res: Response): Promise<void> => { ... }
}

Routes

Factory function pattern returning a Router. Pass services as parameters; wire controllers inside.

const MyRoutes = (serviceA: ServiceA, serviceB: ServiceB) => {
  const router = Router({ mergeParams: true })
  // ...
  return router
}