# opencrvs/opencrvs-core architecture

> Architecture diagram of the GitHub repository opencrvs/opencrvs-core, 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/opencrvs/opencrvs-core
- Repository: https://github.com/opencrvs/opencrvs-core

## Overview

OpenCRVS is a civil-registration and vital-statistics platform. Its main user workflow is to authenticate a registrar, create or find a birth, death, or other vital-event record, submit it for review and registration, then manage corrections, duplicates, and certificates. The client also supports authorization, offline work, drafts, and document handling. Gateway and documents services expose configuration, authentication proxying, and file operations; country configuration handles user notifications, while optional MOSIP-facing code exchanges identity credentials. The map reflects documented routes and sampled calls; several feature implementations and their wiring were not sampled.

Main entry points: [`packages/client/src/v2-events/routes/routes.ts`](https://github.com/opencrvs/opencrvs-core/blob/develop/packages/client/src/v2-events/routes/routes.ts) (Event routes), [`packages/client/src/App.tsx`](https://github.com/opencrvs/opencrvs-core/blob/develop/packages/client/src/App.tsx) (Client app), [`packages/gateway/src/config/routes.ts`](https://github.com/opencrvs/opencrvs-core/blob/develop/packages/gateway/src/config/routes.ts) (API gateway), [`packages/documents/src/config/routes.ts`](https://github.com/opencrvs/opencrvs-core/blob/develop/packages/documents/src/config/routes.ts) (Document service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Registrar application"]
  node_client_app["Client app<br/>[App.tsx]"]
  node_client_routes["Event routes<br/>[routes.ts]"]
  node_authorization["Access checks"]
  node_client_storage[("Offline storage<br/>[storage.ts]")]
end

subgraph group_registration["Event registration"]
  node_event_search["Record search<br/>[index.tsx]"]
  node_declaration["Event declaration<br/>[index.tsx]"]
  node_review["Event review<br/>[Review.tsx]"]
  node_correction["Corrections<br/>[index.tsx]"]
  node_dedup["Duplicate review"]
  node_certificate["Certificates<br/>[index.ts]"]
end

subgraph group_platform["Core services"]
  node_gateway["API gateway<br/>[routes.ts]"]
  node_auth["Authentication<br/>[handler.ts]"]
  node_documents["Document service<br/>[routes.ts]"]
  node_document_storage[("File storage")]
end

subgraph group_identity["Identity integration"]
  node_mosip_route["Packet manager"]
  node_mosip_callback(("MOSIP callback"))
end

subgraph group_support["Notifications and QA"]
  node_country_notifications["User notifications"]
  node_testland_proxy["QA write proxy"]
end

node_registrar(("Registrar"))
node_qa_user(("QA user"))

node_registrar -->|"uses"| node_client_app
node_client_app -->|"navigates"| node_client_routes
node_client_app -->|"checks access"| node_authorization
node_client_app -->|"persists offline"| node_client_storage
node_client_routes -->|"routes to"| node_event_search
node_client_routes -->|"routes to"| node_declaration
node_client_routes -->|"routes to"| node_review
node_client_routes -->|"routes to"| node_correction
node_client_routes -->|"routes to"| node_dedup
node_client_routes -->|"routes to"| node_certificate
node_gateway -->|"proxies auth"| node_auth
node_gateway -->|"proxies uploads"| node_documents
node_documents -->|"stores files"| node_document_storage
node_mosip_route -.->|"posts credential"| node_mosip_callback
node_qa_user -->|"submits changes"| node_testland_proxy
node_testland_proxy -->|"proxies entity writes"| node_gateway

click node_client_app "https://github.com/opencrvs/opencrvs-core/blob/develop/packages/client/src/App.tsx"
click node_client_routes "https://github.com/opencrvs/opencrvs-core/blob/develop/packages/client/src/v2-events/routes/routes.ts"
click node_authorization "https://github.com/opencrvs/opencrvs-core/blob/develop/packages/client/src/hooks/useAuthorization.ts"
click node_client_storage "https://github.com/opencrvs/opencrvs-core/blob/develop/packages/client/src/storage.ts"
click node_event_search "https://github.com/opencrvs/opencrvs-core/blob/develop/packages/client/src/v2-events/features/events/Search/index.tsx"
click node_declaration "https://github.com/opencrvs/opencrvs-core/blob/develop/packages/client/src/v2-events/features/events/actions/declare/index.tsx"
click node_review "https://github.com/opencrvs/opencrvs-core/blob/develop/packages/client/src/v2-events/features/events/components/Review.tsx"
click node_correction "https://github.com/opencrvs/opencrvs-core/blob/develop/packages/client/src/v2-events/features/events/actions/correct/request/index.tsx"
click node_dedup "https://github.com/opencrvs/opencrvs-core/blob/develop/packages/client/src/v2-events/features/events/actions/dedup/ReviewDuplicate.tsx"
click node_certificate "https://github.com/opencrvs/opencrvs-core/blob/develop/packages/client/src/v2-events/features/events/actions/print-certificate/index.ts"
click node_gateway "https://github.com/opencrvs/opencrvs-core/blob/develop/packages/gateway/src/config/routes.ts"
click node_auth "https://github.com/opencrvs/opencrvs-core/blob/develop/packages/auth/src/features/authenticate/handler.ts"
click node_documents "https://github.com/opencrvs/opencrvs-core/blob/develop/packages/documents/src/config/routes.ts"
click node_mosip_route "https://github.com/opencrvs/opencrvs-core/blob/develop/packages/mosip-mock/src/routes/packet-manager-create.ts"
click node_country_notifications "https://github.com/opencrvs/opencrvs-core/blob/develop/packages/countryconfig-template/src/config/routes/userNotificationRoutes.ts"
click node_testland_proxy "https://github.com/opencrvs/opencrvs-core/blob/develop/packages/testland/src/qa-tools/write-proxy-routes.ts"

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_client_app,node_client_routes,node_authorization,node_client_storage,node_qa_user toneBlue
class node_event_search,node_declaration,node_review,node_correction,node_dedup,node_certificate toneAmber
class node_gateway,node_auth,node_documents,node_document_storage toneMint
class node_mosip_route,node_mosip_callback toneRose
class node_country_notifications,node_testland_proxy,node_registrar toneIndigo
```

## Components

### Registrar application

- [Client app](https://github.com/opencrvs/opencrvs-core/blob/develop/packages/client/src/App.tsx): `packages/client/src/App.tsx`
- [Event routes](https://github.com/opencrvs/opencrvs-core/blob/develop/packages/client/src/v2-events/routes/routes.ts): `packages/client/src/v2-events/routes/routes.ts`
- [Access checks](https://github.com/opencrvs/opencrvs-core/blob/develop/packages/client/src/hooks/useAuthorization.ts): `packages/client/src/hooks/useAuthorization.ts`
- [Offline storage](https://github.com/opencrvs/opencrvs-core/blob/develop/packages/client/src/storage.ts): `packages/client/src/storage.ts`

### Event registration

- [Record search](https://github.com/opencrvs/opencrvs-core/blob/develop/packages/client/src/v2-events/features/events/Search/index.tsx): `packages/client/src/v2-events/features/events/Search/index.tsx`
- [Event declaration](https://github.com/opencrvs/opencrvs-core/blob/develop/packages/client/src/v2-events/features/events/actions/declare/index.tsx): `packages/client/src/v2-events/features/events/actions/declare/index.tsx`
- [Event review](https://github.com/opencrvs/opencrvs-core/blob/develop/packages/client/src/v2-events/features/events/components/Review.tsx): `packages/client/src/v2-events/features/events/components/Review.tsx`
- [Corrections](https://github.com/opencrvs/opencrvs-core/blob/develop/packages/client/src/v2-events/features/events/actions/correct/request/index.tsx): `packages/client/src/v2-events/features/events/actions/correct/request/index.tsx`
- [Duplicate review](https://github.com/opencrvs/opencrvs-core/blob/develop/packages/client/src/v2-events/features/events/actions/dedup/ReviewDuplicate.tsx): `packages/client/src/v2-events/features/events/actions/dedup/ReviewDuplicate.tsx`
- [Certificates](https://github.com/opencrvs/opencrvs-core/blob/develop/packages/client/src/v2-events/features/events/actions/print-certificate/index.ts): `packages/client/src/v2-events/features/events/actions/print-certificate/index.ts`

### Core services

- [API gateway](https://github.com/opencrvs/opencrvs-core/blob/develop/packages/gateway/src/config/routes.ts): `packages/gateway/src/config/routes.ts`
- [Authentication](https://github.com/opencrvs/opencrvs-core/blob/develop/packages/auth/src/features/authenticate/handler.ts): `packages/auth/src/features/authenticate/handler.ts`
- [Document service](https://github.com/opencrvs/opencrvs-core/blob/develop/packages/documents/src/config/routes.ts): `packages/documents/src/config/routes.ts`
- **File storage**

### Identity integration

- [Packet manager](https://github.com/opencrvs/opencrvs-core/blob/develop/packages/mosip-mock/src/routes/packet-manager-create.ts): `packages/mosip-mock/src/routes/packet-manager-create.ts`
- **MOSIP callback**

### Notifications and QA

- [User notifications](https://github.com/opencrvs/opencrvs-core/blob/develop/packages/countryconfig-template/src/config/routes/userNotificationRoutes.ts): `packages/countryconfig-template/src/config/routes/userNotificationRoutes.ts`
- [QA write proxy](https://github.com/opencrvs/opencrvs-core/blob/develop/packages/testland/src/qa-tools/write-proxy-routes.ts): `packages/testland/src/qa-tools/write-proxy-routes.ts`

### Other components

- **Registrar**
- **QA user**

## Connections

- Registrar → Client app: uses
- Client app → Event routes: navigates
- Client app → Access checks: checks access
- Client app → Offline storage: persists offline
- Event routes → Record search: routes to
- Event routes → Event declaration: routes to
- Event routes → Event review: routes to
- Event routes → Corrections: routes to
- Event routes → Duplicate review: routes to
- Event routes → Certificates: routes to
- API gateway → Authentication: proxies auth
- API gateway → Document service: proxies uploads
- Document service → File storage: stores files
- Packet manager → MOSIP callback: posts credential
- QA user → QA write proxy: submits changes
- QA write proxy → API gateway: proxies entity writes