# bcgov/myss-api architecture

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

## Overview

MySelfServe API serves the BC income-assistance self-service portal. Clients and workers enter through FastAPI routes; authentication and role checks protect operations, domain services coordinate workflows, and Siebel/ICM supplies case-management functions. Service-request submission includes PIN validation, optional PDF generation, and draft handling; monthly reports use PIN checks and a Redis-backed period cache. The README also documents registration, eligibility, employment plans, payments, attachments, notifications, and administration. Several of those branches are represented from the tree and SOURCE INDEX; their internal calls were not sampled.

Main entry points: [`app/routers`](https://github.com/bcgov/myss-api/tree/main/app/routers) (Other feature routes), [`app/main.py`](https://github.com/bcgov/myss-api/blob/main/app/main.py) (FastAPI application), [`app/domains/service_requests/service.py`](https://github.com/bcgov/myss-api/blob/main/app/domains/service_requests/service.py) (Service request workflow), [`app/domains/monthly_reports/service.py`](https://github.com/bcgov/myss-api/blob/main/app/domains/monthly_reports/service.py) (Monthly reports)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API and access"]
  node_app["FastAPI application<br/>[main.py]"]
  node_auth["JWT access control<br/>[dependencies.py]"]
  node_sr_routes["Service request routes"]
  node_registration_routes["Registration routes<br/>[registration.py]"]
  node_admin_routes["Admin routes<br/>[ao.py]"]
  node_attachment_routes["Attachment routes<br/>[attachments.py]"]
  node_other_routes["Other feature routes"]
end

subgraph group_domains["Business domains"]
  node_registration["Registration workflow<br/>[service.py]"]
  node_service_requests["Service request workflow<br/>[service.py]"]
  node_drafts["Draft persistence"]
  node_monthly["Monthly reports<br/>[service.py]"]
  node_eligibility["Eligibility calculation<br/>[calculator.py]"]
  node_payments["Payments<br/>[service.py]"]
  node_attachments["Attachment handling<br/>[service.py]"]
  node_employment["Employment plans<br/>[service.py]"]
  node_notifications["Notifications<br/>[service.py]"]
  node_pin["PIN validation<br/>[pin_service.py]"]
  node_pdf["PDF generation"]
end

subgraph group_integrations["ICM integration"]
  node_icm_factory["ICM client provider<br/>[deps.py]"]
  node_icm_client["ICM HTTP client<br/>[client.py]"]
  node_icm_services["ICM feature clients"]
end

subgraph group_state["State and messaging"]
  node_redis[("Redis cache<br/>[redis_client.py]")]
  node_postgres[("PostgreSQL database<br/>[session.py]")]
  node_email_tasks["Email background tasks<br/>[send_bulk_email.py]"]
end

node_client(("Portal client"))
node_siebel["Siebel / ICM"]

node_client -->|"calls API"| node_app
node_app -->|"registers routes"| node_sr_routes
node_app -->|"registers routes"| node_registration_routes
node_app -->|"registers routes"| node_other_routes
node_app -->|"registers routes"| node_admin_routes
node_sr_routes -->|"requires role"| node_auth
node_sr_routes -->|"delegates to"| node_service_requests
node_service_requests -->|"uses drafts"| node_drafts
node_service_requests -->|"validates PIN"| node_pin
node_service_requests -->|"generates PDF"| node_pdf
node_service_requests -->|"finalizes request"| node_icm_services
node_registration_routes -->|"delegates to"| node_registration
node_monthly -->|"validates PIN"| node_pin
node_monthly -->|"reads and writes"| node_redis
node_monthly -->|"requests report data"| node_icm_services
node_icm_factory -->|"creates clients"| node_icm_client
node_icm_services -->|"uses HTTP client"| node_icm_client
node_icm_client -->|"sends REST calls"| node_siebel
node_attachment_routes -->|"delegates to"| node_attachments
node_admin_routes -->|"gets ICM client"| node_icm_factory
node_other_routes -.->|"feature routing"| node_monthly
node_other_routes -.->|"feature routing"| node_eligibility
node_other_routes -.->|"feature routing"| node_payments
node_other_routes -.->|"feature routing"| node_employment
node_other_routes -.->|"feature routing"| node_notifications
node_notifications -->|"queues email"| node_email_tasks

click node_app "https://github.com/bcgov/myss-api/blob/main/app/main.py"
click node_auth "https://github.com/bcgov/myss-api/blob/main/app/auth/dependencies.py"
click node_sr_routes "https://github.com/bcgov/myss-api/blob/main/app/routers/service_requests.py"
click node_registration_routes "https://github.com/bcgov/myss-api/blob/main/app/routers/registration.py"
click node_admin_routes "https://github.com/bcgov/myss-api/blob/main/app/routers/admin/ao.py"
click node_attachment_routes "https://github.com/bcgov/myss-api/blob/main/app/routers/attachments.py"
click node_other_routes "https://github.com/bcgov/myss-api/tree/main/app/routers"
click node_registration "https://github.com/bcgov/myss-api/blob/main/app/domains/registration/service.py"
click node_service_requests "https://github.com/bcgov/myss-api/blob/main/app/domains/service_requests/service.py"
click node_drafts "https://github.com/bcgov/myss-api/blob/main/app/domains/service_requests/draft_repository.py"
click node_monthly "https://github.com/bcgov/myss-api/blob/main/app/domains/monthly_reports/service.py"
click node_eligibility "https://github.com/bcgov/myss-api/blob/main/app/domains/eligibility/calculator.py"
click node_payments "https://github.com/bcgov/myss-api/blob/main/app/domains/payment/service.py"
click node_attachments "https://github.com/bcgov/myss-api/blob/main/app/domains/attachments/service.py"
click node_employment "https://github.com/bcgov/myss-api/blob/main/app/domains/employment_plans/service.py"
click node_notifications "https://github.com/bcgov/myss-api/blob/main/app/domains/notifications/service.py"
click node_icm_factory "https://github.com/bcgov/myss-api/blob/main/app/services/icm/deps.py"
click node_icm_client "https://github.com/bcgov/myss-api/blob/main/app/services/icm/client.py"
click node_icm_services "https://github.com/bcgov/myss-api/tree/main/app/services/icm"
click node_pin "https://github.com/bcgov/myss-api/blob/main/app/domains/account/pin_service.py"
click node_pdf "https://github.com/bcgov/myss-api/blob/main/app/domains/service_requests/pdf_generation_service.py"
click node_redis "https://github.com/bcgov/myss-api/blob/main/app/cache/redis_client.py"
click node_postgres "https://github.com/bcgov/myss-api/blob/main/app/db/session.py"
click node_email_tasks "https://github.com/bcgov/myss-api/blob/main/app/workers/tasks/send_bulk_email.py"

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_app,node_auth,node_sr_routes,node_registration_routes,node_admin_routes,node_attachment_routes,node_other_routes,node_client toneBlue
class node_registration,node_service_requests,node_drafts,node_monthly,node_eligibility,node_payments,node_attachments,node_employment,node_notifications,node_pin,node_pdf toneAmber
class node_icm_factory,node_icm_client,node_icm_services toneMint
class node_redis,node_postgres,node_email_tasks toneRose
class node_siebel toneIndigo
```

## Components

### API and access

- [FastAPI application](https://github.com/bcgov/myss-api/blob/main/app/main.py): `app/main.py`
- [JWT access control](https://github.com/bcgov/myss-api/blob/main/app/auth/dependencies.py): `app/auth/dependencies.py`
- [Service request routes](https://github.com/bcgov/myss-api/blob/main/app/routers/service_requests.py): `app/routers/service_requests.py`
- [Registration routes](https://github.com/bcgov/myss-api/blob/main/app/routers/registration.py): `app/routers/registration.py`
- [Admin routes](https://github.com/bcgov/myss-api/blob/main/app/routers/admin/ao.py): `app/routers/admin/ao.py`
- [Attachment routes](https://github.com/bcgov/myss-api/blob/main/app/routers/attachments.py): `app/routers/attachments.py`
- [Other feature routes](https://github.com/bcgov/myss-api/tree/main/app/routers): `app/routers`

### Business domains

- [Registration workflow](https://github.com/bcgov/myss-api/blob/main/app/domains/registration/service.py): `app/domains/registration/service.py`
- [Service request workflow](https://github.com/bcgov/myss-api/blob/main/app/domains/service_requests/service.py): `app/domains/service_requests/service.py`
- [Draft persistence](https://github.com/bcgov/myss-api/blob/main/app/domains/service_requests/draft_repository.py): `app/domains/service_requests/draft_repository.py`
- [Monthly reports](https://github.com/bcgov/myss-api/blob/main/app/domains/monthly_reports/service.py): `app/domains/monthly_reports/service.py`
- [Eligibility calculation](https://github.com/bcgov/myss-api/blob/main/app/domains/eligibility/calculator.py): `app/domains/eligibility/calculator.py`
- [Payments](https://github.com/bcgov/myss-api/blob/main/app/domains/payment/service.py): `app/domains/payment/service.py`
- [Attachment handling](https://github.com/bcgov/myss-api/blob/main/app/domains/attachments/service.py): `app/domains/attachments/service.py`
- [Employment plans](https://github.com/bcgov/myss-api/blob/main/app/domains/employment_plans/service.py): `app/domains/employment_plans/service.py`
- [Notifications](https://github.com/bcgov/myss-api/blob/main/app/domains/notifications/service.py): `app/domains/notifications/service.py`
- [PIN validation](https://github.com/bcgov/myss-api/blob/main/app/domains/account/pin_service.py): `app/domains/account/pin_service.py`
- [PDF generation](https://github.com/bcgov/myss-api/blob/main/app/domains/service_requests/pdf_generation_service.py): `app/domains/service_requests/pdf_generation_service.py`

### ICM integration

- [ICM client provider](https://github.com/bcgov/myss-api/blob/main/app/services/icm/deps.py): `app/services/icm/deps.py`
- [ICM HTTP client](https://github.com/bcgov/myss-api/blob/main/app/services/icm/client.py): `app/services/icm/client.py`
- [ICM feature clients](https://github.com/bcgov/myss-api/tree/main/app/services/icm): `app/services/icm`

### State and messaging

- [Redis cache](https://github.com/bcgov/myss-api/blob/main/app/cache/redis_client.py): `app/cache/redis_client.py`
- [PostgreSQL database](https://github.com/bcgov/myss-api/blob/main/app/db/session.py): `app/db/session.py`
- [Email background tasks](https://github.com/bcgov/myss-api/blob/main/app/workers/tasks/send_bulk_email.py): `app/workers/tasks/send_bulk_email.py`

### Other components

- **Portal client**
- **Siebel / ICM**

## Connections

- Portal client → FastAPI application: calls API (evidence: `README.md`)
- FastAPI application → Service request routes: registers routes (evidence: `app/main.py`)
- FastAPI application → Registration routes: registers routes (evidence: `app/main.py`)
- FastAPI application → Other feature routes: registers routes (evidence: `app/main.py`)
- FastAPI application → Admin routes: registers routes (evidence: `app/main.py`)
- Service request routes → JWT access control: requires role (evidence: `app/routers/service_requests.py`)
- Service request routes → Service request workflow: delegates to (evidence: `app/routers/service_requests.py`)
- Service request workflow → Draft persistence: uses drafts (evidence: `app/domains/service_requests/service.py`)
- Service request workflow → PIN validation: validates PIN (evidence: `app/domains/service_requests/service.py`)
- Service request workflow → PDF generation: generates PDF (evidence: `app/domains/service_requests/service.py`)
- Service request workflow → ICM feature clients: finalizes request (evidence: `app/domains/service_requests/service.py`)
- Registration routes → Registration workflow: delegates to (evidence: `app/routers/registration.py`)
- Monthly reports → PIN validation: validates PIN (evidence: `app/domains/monthly_reports/service.py`)
- Monthly reports → Redis cache: reads and writes (evidence: `app/domains/monthly_reports/service.py`)
- Monthly reports → ICM feature clients: requests report data (evidence: `app/domains/monthly_reports/service.py`)
- ICM client provider → ICM HTTP client: creates clients (evidence: `app/services/icm/deps.py`)
- ICM feature clients → ICM HTTP client: uses HTTP client (evidence: `app/services/icm/service_requests.py`)
- ICM HTTP client → Siebel / ICM: sends REST calls (evidence: `README.md`)
- Attachment routes → Attachment handling: delegates to (evidence: `app/routers/attachments.py`)
- Admin routes → ICM client provider: gets ICM client (evidence: `app/routers/admin/ao.py`)
- Other feature routes → Monthly reports: feature routing
- Other feature routes → Eligibility calculation: feature routing
- Other feature routes → Payments: feature routing
- Other feature routes → Employment plans: feature routing
- Other feature routes → Notifications: feature routing
- Notifications → Email background tasks: queues email
