# bcgov/csa architecture

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

- Interactive diagram: https://gitdiagram.com/bcgov/csa
- Repository: https://github.com/bcgov/csa

## Overview

Child Special Allowance is a web application for managing children’s eligibility and federal benefit processing. Staff review and update contact records, run eligibility, assemble batches, submit them to CRA, and process CRA responses and weekly files. The repository separates the React interface, NestJS API, scheduled/job execution, and integration/synchronization services. The README documents the end-to-end flow; source excerpts provide concrete UI/API and ICM-ingestion relationships. Several domain connections are documented but their internal implementations were not sampled, so those links cite the README.

Main entry points: [`frontend/src/service/api-service.ts`](https://github.com/bcgov/csa/blob/dev/frontend/src/service/api-service.ts) (API client), [`frontend/src/App.tsx`](https://github.com/bcgov/csa/blob/dev/frontend/src/App.tsx) (CSA workspace), [`backend/src/api/contacts/contacts.controller.ts`](https://github.com/bcgov/csa/blob/dev/backend/src/api/contacts/contacts.controller.ts) (Contact endpoints), [`backend/src/common/database/prisma.service.ts`](https://github.com/bcgov/csa/blob/dev/backend/src/common/database/prisma.service.ts) (Application database)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Staff interface"]
  node_frontend["CSA workspace<br/>[App.tsx]"]
  node_weekly_ui["Weekly processing"]
  node_job_ui["Job monitoring"]
  node_api_client["API client<br/>[api-service.ts]"]
end

subgraph group_api["Application API"]
  node_contact_api["Contact endpoints"]
  node_batch_api["Batch endpoints"]
  node_weekly_api["Weekly-file endpoints"]
  node_admin_api["Access verification<br/>[admin.service.ts]"]
  node_job_api["Job endpoints<br/>[jobs.controller.ts]"]
end

subgraph group_jobs["Jobs and eligibility"]
  node_eligibility["Eligibility rules"]
  node_ingest_handler["ICM ingestion job"]
  node_job_service["Job coordination<br/>[jobs.service.ts]"]
end

subgraph group_integrations["External data flows"]
  node_icm_sync["ICM synchronization<br/>[icm.service.ts]"]
  node_mis_sync["MIS synchronization<br/>[mis.service.ts]"]
  node_cra_outbound["CRA file preparation"]
  node_cra_transfer["CRA transfer"]
  node_cra_inbound["CRA response processing"]
  node_weekly_processing["Weekly record matching"]
end

subgraph group_platform["Identity and persistence"]
  node_auth["Authentication and guards<br/>[csa.guard.ts]"]
  node_database[("Application database<br/>[prisma.service.ts]")]
end

node_staff(("Staff user"))
node_cra(("Canada Revenue Agency"))

node_staff -->|"uses"| node_frontend
node_frontend -->|"requests data"| node_api_client
node_frontend -->|"loads and updates"| node_contact_api
node_api_client -->|"sends HTTP requests"| node_contact_api
node_frontend -.->|"submits contacts"| node_batch_api
node_weekly_ui -->|"requests weekly data"| node_api_client
node_api_client -->|"sends HTTP requests"| node_weekly_api
node_job_ui -.->|"requests job status"| node_api_client
node_api_client -->|"calls jobs API"| node_job_api
node_contact_api -.->|"runs eligibility"| node_eligibility
node_job_api -->|"records job runs"| node_job_service
node_job_api -.->|"launches jobs"| node_ingest_handler
node_ingest_handler -->|"reads last success"| node_job_service
node_ingest_handler -->|"ingests ICM data"| node_icm_sync
node_staff -->|"runs eligibility"| node_eligibility
node_staff -->|"creates batch"| node_batch_api
node_batch_api -.->|"prepares CRA submission"| node_cra_outbound
node_cra_outbound -.->|"transfers file"| node_cra_transfer
node_cra_transfer -.->|"submits file"| node_cra
node_cra -.->|"returns response"| node_cra_inbound
node_cra_inbound -.->|"processes weekly records"| node_weekly_processing
node_weekly_processing -.->|"provides records"| node_weekly_api
node_auth -->|"verifies CSA access"| node_admin_api
node_contact_api -->|"guards requests"| node_auth
node_weekly_api -->|"guards requests"| node_auth
node_icm_sync -.->|"persists synced data"| node_database
node_mis_sync -.->|"persists synced data"| node_database
node_eligibility -.->|"updates eligibility"| node_database
node_weekly_processing -.->|"stores processed records"| node_database

click node_frontend "https://github.com/bcgov/csa/blob/dev/frontend/src/App.tsx"
click node_weekly_ui "https://github.com/bcgov/csa/blob/dev/frontend/src/components/WeeklyFileProcessingTab.tsx"
click node_job_ui "https://github.com/bcgov/csa/blob/dev/frontend/src/components/JobMonitoringTab.tsx"
click node_api_client "https://github.com/bcgov/csa/blob/dev/frontend/src/service/api-service.ts"
click node_contact_api "https://github.com/bcgov/csa/blob/dev/backend/src/api/contacts/contacts.controller.ts"
click node_batch_api "https://github.com/bcgov/csa/blob/dev/backend/src/api/batches/batches.controller.ts"
click node_weekly_api "https://github.com/bcgov/csa/blob/dev/backend/src/api/weekly-files/weekly-files.controller.ts"
click node_admin_api "https://github.com/bcgov/csa/blob/dev/backend/src/api/admin/admin.service.ts"
click node_eligibility "https://github.com/bcgov/csa/blob/dev/backend/src/sync/eligibility/eligibility.service.ts"
click node_ingest_handler "https://github.com/bcgov/csa/blob/dev/backend/src/sync/handlers/ingest-icm.handler.ts"
click node_job_api "https://github.com/bcgov/csa/blob/dev/backend/src/api/jobs/jobs.controller.ts"
click node_job_service "https://github.com/bcgov/csa/blob/dev/backend/src/jobs/jobs.service.ts"
click node_icm_sync "https://github.com/bcgov/csa/blob/dev/backend/src/sync/icm/icm.service.ts"
click node_mis_sync "https://github.com/bcgov/csa/blob/dev/backend/src/sync/mis/mis.service.ts"
click node_cra_outbound "https://github.com/bcgov/csa/blob/dev/backend/src/cra/outbound/outbound-file.service.ts"
click node_cra_transfer "https://github.com/bcgov/csa/blob/dev/backend/src/cra/transfer/cra-transfer.service.ts"
click node_cra_inbound "https://github.com/bcgov/csa/blob/dev/backend/src/cra/inbound/inbound-response.service.ts"
click node_weekly_processing "https://github.com/bcgov/csa/blob/dev/backend/src/cra/inbound/inbound-weekly-response.service.ts"
click node_auth "https://github.com/bcgov/csa/blob/dev/backend/src/api/common/guards/csa.guard.ts"
click node_database "https://github.com/bcgov/csa/blob/dev/backend/src/common/database/prisma.service.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_frontend,node_weekly_ui,node_job_ui,node_api_client,node_staff toneBlue
class node_contact_api,node_batch_api,node_weekly_api,node_admin_api,node_job_api toneAmber
class node_eligibility,node_ingest_handler,node_job_service toneMint
class node_icm_sync,node_mis_sync,node_cra_outbound,node_cra_transfer,node_cra_inbound,node_weekly_processing toneRose
class node_auth,node_database,node_cra toneIndigo
```

## Components

### Staff interface

- [CSA workspace](https://github.com/bcgov/csa/blob/dev/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Weekly processing](https://github.com/bcgov/csa/blob/dev/frontend/src/components/WeeklyFileProcessingTab.tsx): `frontend/src/components/WeeklyFileProcessingTab.tsx`
- [Job monitoring](https://github.com/bcgov/csa/blob/dev/frontend/src/components/JobMonitoringTab.tsx): `frontend/src/components/JobMonitoringTab.tsx`
- [API client](https://github.com/bcgov/csa/blob/dev/frontend/src/service/api-service.ts): `frontend/src/service/api-service.ts`

### Application API

- [Contact endpoints](https://github.com/bcgov/csa/blob/dev/backend/src/api/contacts/contacts.controller.ts): `backend/src/api/contacts/contacts.controller.ts`
- [Batch endpoints](https://github.com/bcgov/csa/blob/dev/backend/src/api/batches/batches.controller.ts): `backend/src/api/batches/batches.controller.ts`
- [Weekly-file endpoints](https://github.com/bcgov/csa/blob/dev/backend/src/api/weekly-files/weekly-files.controller.ts): `backend/src/api/weekly-files/weekly-files.controller.ts`
- [Access verification](https://github.com/bcgov/csa/blob/dev/backend/src/api/admin/admin.service.ts): `backend/src/api/admin/admin.service.ts`
- [Job endpoints](https://github.com/bcgov/csa/blob/dev/backend/src/api/jobs/jobs.controller.ts): `backend/src/api/jobs/jobs.controller.ts`

### Jobs and eligibility

- [Eligibility rules](https://github.com/bcgov/csa/blob/dev/backend/src/sync/eligibility/eligibility.service.ts): `backend/src/sync/eligibility/eligibility.service.ts`
- [ICM ingestion job](https://github.com/bcgov/csa/blob/dev/backend/src/sync/handlers/ingest-icm.handler.ts): `backend/src/sync/handlers/ingest-icm.handler.ts`
- [Job coordination](https://github.com/bcgov/csa/blob/dev/backend/src/jobs/jobs.service.ts): `backend/src/jobs/jobs.service.ts`

### External data flows

- [ICM synchronization](https://github.com/bcgov/csa/blob/dev/backend/src/sync/icm/icm.service.ts): `backend/src/sync/icm/icm.service.ts`
- [MIS synchronization](https://github.com/bcgov/csa/blob/dev/backend/src/sync/mis/mis.service.ts): `backend/src/sync/mis/mis.service.ts`
- [CRA file preparation](https://github.com/bcgov/csa/blob/dev/backend/src/cra/outbound/outbound-file.service.ts): `backend/src/cra/outbound/outbound-file.service.ts`
- [CRA transfer](https://github.com/bcgov/csa/blob/dev/backend/src/cra/transfer/cra-transfer.service.ts): `backend/src/cra/transfer/cra-transfer.service.ts`
- [CRA response processing](https://github.com/bcgov/csa/blob/dev/backend/src/cra/inbound/inbound-response.service.ts): `backend/src/cra/inbound/inbound-response.service.ts`
- [Weekly record matching](https://github.com/bcgov/csa/blob/dev/backend/src/cra/inbound/inbound-weekly-response.service.ts): `backend/src/cra/inbound/inbound-weekly-response.service.ts`

### Identity and persistence

- [Authentication and guards](https://github.com/bcgov/csa/blob/dev/backend/src/api/common/guards/csa.guard.ts): `backend/src/api/common/guards/csa.guard.ts`
- [Application database](https://github.com/bcgov/csa/blob/dev/backend/src/common/database/prisma.service.ts): `backend/src/common/database/prisma.service.ts`

### Other components

- **Staff user**
- **Canada Revenue Agency**

## Connections

- Staff user → CSA workspace: uses (evidence: `README.md`)
- CSA workspace → API client: requests data (evidence: `frontend/src/App.tsx`)
- CSA workspace → Contact endpoints: loads and updates
- API client → Contact endpoints: sends HTTP requests
- CSA workspace → Batch endpoints: submits contacts
- Weekly processing → API client: requests weekly data (evidence: `frontend/src/components/WeeklyFileProcessingTab.tsx`)
- API client → Weekly-file endpoints: sends HTTP requests
- Job monitoring → API client: requests job status
- API client → Job endpoints: calls jobs API
- Contact endpoints → Eligibility rules: runs eligibility
- Job endpoints → Job coordination: records job runs (evidence: `backend/src/api/jobs/jobs.controller.ts`)
- Job endpoints → ICM ingestion job: launches jobs
- ICM ingestion job → Job coordination: reads last success (evidence: `backend/src/sync/handlers/ingest-icm.handler.ts`)
- ICM ingestion job → ICM synchronization: ingests ICM data (evidence: `backend/src/sync/handlers/ingest-icm.handler.ts`)
- Staff user → Eligibility rules: runs eligibility (evidence: `README.md`)
- Staff user → Batch endpoints: creates batch (evidence: `README.md`)
- Batch endpoints → CRA file preparation: prepares CRA submission
- CRA file preparation → CRA transfer: transfers file
- CRA transfer → Canada Revenue Agency: submits file
- Canada Revenue Agency → CRA response processing: returns response (evidence: `README.md`)
- CRA response processing → Weekly record matching: processes weekly records
- Weekly record matching → Weekly-file endpoints: provides records
- Authentication and guards → Access verification: verifies CSA access (evidence: `backend/src/api/common/guards/csa.guard.ts`)
- Contact endpoints → Authentication and guards: guards requests (evidence: `backend/src/api/contacts/contacts.controller.ts`)
- Weekly-file endpoints → Authentication and guards: guards requests (evidence: `backend/src/api/weekly-files/weekly-files.controller.ts`)
- ICM synchronization → Application database: persists synced data
- MIS synchronization → Application database: persists synced data
- Eligibility rules → Application database: updates eligibility
- Weekly record matching → Application database: stores processed records
