# hmcts/cath-service architecture

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

- Interactive diagram: https://gitdiagram.com/hmcts/cath-service
- Repository: https://github.com/hmcts/cath-service

## Overview

This repository appears to implement a court hearing-list publication service within a larger HMCTS monorepo: people browse and download lists, while administrators manage publication-related data and media applications. The tree also shows authentication, subscriptions, notifications and system administration. Sampled code confirms web/API route mounting, user and application persistence, blob storage, publication generation and notification behavior; it does not show the full publication entry point or how page controllers call APIs, so those links are omitted.

Main entry points: [`apps/web/src/app.ts`](https://github.com/hmcts/cath-service/blob/master/apps/web/src/app.ts) (Web application), [`libs/notifications/src/notification/notification-service.ts`](https://github.com/hmcts/cath-service/blob/master/libs/notifications/src/notification/notification-service.ts) (Subscription notifications), [`apps/postgres`](https://github.com/hmcts/cath-service/tree/master/apps/postgres) (PostgreSQL), [`apps/web/src/pages/(public)`](https://github.com/hmcts/cath-service/tree/master/apps/web/src/pages/(public)) (Public pages)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web experience"]
  node_web_app["Web application<br/>[app.ts]"]
  node_public_pages["Public pages"]
  node_list_pages["Hearing-list pages"]
  node_auth_pages["Authentication pages"]
  node_web_api["Web API routes"]
  node_api_app["API application<br/>[app.ts]"]
end

subgraph group_publication["Publication workflow"]
  node_publication_service["Publication processing<br/>[service.ts]"]
  node_excel_storage["Excel file storage"]
  node_notifications["Subscription notifications"]
end

subgraph group_admin["Administration"]
  node_admin_pages["Admin pages"]
  node_system_admin_pages["System admin pages"]
  node_admin_upload_storage["Upload staging<br/>[storage.ts]"]
  node_media_application["Media applications<br/>[query.ts]"]
  node_id_proof_storage["ID proof storage<br/>[storage.ts]"]
end

subgraph group_platform["Persistence and services"]
  node_account_repository["Account repository<br/>[query.ts]"]
  node_database[("PostgreSQL")]
  node_redis[("Redis")]
  node_blob_store[("Azure blob storage")]
  node_email_service["Email delivery"]
end

node_public_user(("Public user"))
node_media_user(("Media applicant"))
node_admin_user(("Administrator"))

node_public_user -->|"browses"| node_web_app
node_media_user -->|"applies"| node_web_app
node_admin_user -->|"administers"| node_web_app
node_web_app -->|"mounts pages"| node_public_pages
node_web_app -->|"mounts pages"| node_list_pages
node_web_app -->|"mounts pages"| node_auth_pages
node_web_app -->|"mounts pages"| node_admin_pages
node_web_app -->|"mounts pages"| node_system_admin_pages
node_web_app -->|"mounts routes"| node_web_api
node_api_app -->|"mounts routes"| node_web_api
node_publication_service -->|"stores Excel"| node_excel_storage
node_publication_service -->|"dispatches notices"| node_notifications
node_notifications -->|"sends email"| node_email_service
node_notifications -->|"downloads files"| node_blob_store
node_notifications -->|"reads subscriptions"| node_database
node_notifications -->|"updates status"| node_database
node_excel_storage -->|"uploads files"| node_blob_store
node_admin_upload_storage -->|"stages uploads"| node_redis
node_admin_pages -->|"stages files"| node_admin_upload_storage
node_public_pages -->|"creates applications"| node_media_application
node_media_application -->|"writes application"| node_database
node_public_pages -->|"saves ID proof"| node_id_proof_storage
node_id_proof_storage -->|"uploads proof"| node_blob_store
node_account_repository -->|"reads and writes users"| node_database

click node_web_app "https://github.com/hmcts/cath-service/blob/master/apps/web/src/app.ts"
click node_public_pages "https://github.com/hmcts/cath-service/tree/master/apps/web/src/pages/(public)"
click node_list_pages "https://github.com/hmcts/cath-service/tree/master/apps/web/src/pages/(list-types)"
click node_auth_pages "https://github.com/hmcts/cath-service/tree/master/apps/web/src/pages/(auth)"
click node_web_api "https://github.com/hmcts/cath-service/tree/master/apps/api/src/routes"
click node_api_app "https://github.com/hmcts/cath-service/blob/master/apps/api/src/app.ts"
click node_publication_service "https://github.com/hmcts/cath-service/blob/master/libs/publication/src/processing/service.ts"
click node_excel_storage "https://github.com/hmcts/cath-service/blob/master/libs/excel-generation/src/file-storage/file-storage-service.ts"
click node_notifications "https://github.com/hmcts/cath-service/blob/master/libs/notifications/src/notification/notification-service.ts"
click node_admin_pages "https://github.com/hmcts/cath-service/tree/master/apps/web/src/pages/(admin)"
click node_system_admin_pages "https://github.com/hmcts/cath-service/tree/master/apps/web/src/pages/(system-admin)"
click node_admin_upload_storage "https://github.com/hmcts/cath-service/blob/master/libs/admin-pages/src/manual-upload/storage.ts"
click node_media_application "https://github.com/hmcts/cath-service/blob/master/libs/public-pages/src/media-application/repository/query.ts"
click node_id_proof_storage "https://github.com/hmcts/cath-service/blob/master/libs/public-pages/src/media-application/storage.ts"
click node_account_repository "https://github.com/hmcts/cath-service/blob/master/libs/account/src/repository/query.ts"
click node_database "https://github.com/hmcts/cath-service/tree/master/apps/postgres"

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_web_app,node_public_pages,node_list_pages,node_auth_pages,node_web_api,node_api_app,node_public_user toneBlue
class node_publication_service,node_excel_storage,node_notifications toneAmber
class node_admin_pages,node_system_admin_pages,node_admin_upload_storage,node_media_application,node_id_proof_storage toneMint
class node_account_repository,node_database,node_redis,node_blob_store,node_email_service toneRose
class node_media_user,node_admin_user toneIndigo
```

## Components

### Web experience

- [Web application](https://github.com/hmcts/cath-service/blob/master/apps/web/src/app.ts): `apps/web/src/app.ts`
- [Public pages](https://github.com/hmcts/cath-service/tree/master/apps/web/src/pages/(public)): `apps/web/src/pages/(public)`
- [Hearing-list pages](https://github.com/hmcts/cath-service/tree/master/apps/web/src/pages/(list-types)): `apps/web/src/pages/(list-types)`
- [Authentication pages](https://github.com/hmcts/cath-service/tree/master/apps/web/src/pages/(auth)): `apps/web/src/pages/(auth)`
- [Web API routes](https://github.com/hmcts/cath-service/tree/master/apps/api/src/routes): `apps/api/src/routes`
- [API application](https://github.com/hmcts/cath-service/blob/master/apps/api/src/app.ts): `apps/api/src/app.ts`

### Publication workflow

- [Publication processing](https://github.com/hmcts/cath-service/blob/master/libs/publication/src/processing/service.ts): `libs/publication/src/processing/service.ts`
- [Excel file storage](https://github.com/hmcts/cath-service/blob/master/libs/excel-generation/src/file-storage/file-storage-service.ts): `libs/excel-generation/src/file-storage/file-storage-service.ts`
- [Subscription notifications](https://github.com/hmcts/cath-service/blob/master/libs/notifications/src/notification/notification-service.ts): `libs/notifications/src/notification/notification-service.ts`

### Administration

- [Admin pages](https://github.com/hmcts/cath-service/tree/master/apps/web/src/pages/(admin)): `apps/web/src/pages/(admin)`
- [System admin pages](https://github.com/hmcts/cath-service/tree/master/apps/web/src/pages/(system-admin)): `apps/web/src/pages/(system-admin)`
- [Upload staging](https://github.com/hmcts/cath-service/blob/master/libs/admin-pages/src/manual-upload/storage.ts): `libs/admin-pages/src/manual-upload/storage.ts`
- [Media applications](https://github.com/hmcts/cath-service/blob/master/libs/public-pages/src/media-application/repository/query.ts): `libs/public-pages/src/media-application/repository/query.ts`
- [ID proof storage](https://github.com/hmcts/cath-service/blob/master/libs/public-pages/src/media-application/storage.ts): `libs/public-pages/src/media-application/storage.ts`

### Persistence and services

- [Account repository](https://github.com/hmcts/cath-service/blob/master/libs/account/src/repository/query.ts): `libs/account/src/repository/query.ts`
- [PostgreSQL](https://github.com/hmcts/cath-service/tree/master/apps/postgres): `apps/postgres`
- **Redis**
- **Azure blob storage**
- **Email delivery**

### Other components

- **Public user**
- **Media applicant**
- **Administrator**

## Connections

- Public user → Web application: browses
- Media applicant → Web application: applies
- Administrator → Web application: administers
- Web application → Public pages: mounts pages
- Web application → Hearing-list pages: mounts pages
- Web application → Authentication pages: mounts pages
- Web application → Admin pages: mounts pages
- Web application → System admin pages: mounts pages
- Web application → Web API routes: mounts routes
- API application → Web API routes: mounts routes
- Publication processing → Excel file storage: stores Excel
- Publication processing → Subscription notifications: dispatches notices
- Subscription notifications → Email delivery: sends email
- Subscription notifications → Azure blob storage: downloads files
- Subscription notifications → PostgreSQL: reads subscriptions
- Subscription notifications → PostgreSQL: updates status
- Excel file storage → Azure blob storage: uploads files
- Upload staging → Redis: stages uploads
- Admin pages → Upload staging: stages files
- Public pages → Media applications: creates applications
- Media applications → PostgreSQL: writes application
- Public pages → ID proof storage: saves ID proof
- ID proof storage → Azure blob storage: uploads proof
- Account repository → PostgreSQL: reads and writes users