# bcgov/social-middleware architecture

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

## Overview

social-middleware is a NestJS API bridging frontend social-service applications with identity, MongoDB, and downstream services. Users authenticate through BC Services Card, then create and progress an application package through forms and household screening before referral or submission. The graph preserves those distinct stages and supporting attachment, notification, and Siebel capabilities. Several subsystems are represented from the tree and README; their internal call paths are not asserted where source excerpts do not show them.

Main entry points: [`social-middleware/src/application-package/services/application-package.service.ts`](https://github.com/bcgov/social-middleware/blob/main/social-middleware/src/application-package/services/application-package.service.ts) (Application lifecycle service), [`social-middleware/src/auth/auth.controller.ts`](https://github.com/bcgov/social-middleware/blob/main/social-middleware/src/auth/auth.controller.ts) (Authentication API), [`social-middleware/src/household/household.controller.ts`](https://github.com/bcgov/social-middleware/blob/main/social-middleware/src/household/household.controller.ts) (Household API), [`social-middleware/src/application-form/services/application-form.service.ts`](https://github.com/bcgov/social-middleware/blob/main/social-middleware/src/application-form/services/application-form.service.ts) (Form management)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_identity["Identity and sessions"]
  node_auth_api["Authentication API<br/>[auth.controller.ts]"]
  node_auth_strategy["Authentication strategies"]
  node_user_service["User management<br/>[user.service.ts]"]
  node_session_guard["Session guard"]
end

subgraph group_application["Application lifecycle"]
  node_application_api["Application package API"]
  node_application_service["Application lifecycle service"]
  node_attachments_api["Attachments API"]
  node_attachments_service["Attachment handling"]
end

subgraph group_forms_household["Forms and household"]
  node_form_api["Application form API"]
  node_form_service["Form management"]
  node_household_api["Household API"]
  node_household_service["Household management"]
  node_access_service["Screening access codes"]
  node_forms_api["Form token API"]
  node_forms_service["Form token handling<br/>[forms.service.ts]"]
end

subgraph group_integrations["External services"]
  node_bcsc["BC Services Card"]
  node_notifications["Notifications"]
  node_notification_queue["Email queue"]
  node_ches["Email delivery<br/>[ches.service.ts]"]
  node_siebel["Siebel services"]
end

subgraph group_platform["API and persistence"]
  node_application_store[("Application records")]
  node_form_store[("Form records")]
  node_household_store[("Household records")]
  node_health_api["Health endpoint"]
  node_mongo[("MongoDB")]
end

node_frontend(("Frontend user"))

node_frontend -->|"authenticates at"| node_auth_api
node_auth_api -->|"dispatches callback"| node_auth_strategy
node_auth_api -->|"looks up user"| node_user_service
node_auth_strategy -.->|"exchanges credentials"| node_bcsc
node_frontend -->|"manages applications"| node_application_api
node_application_api -->|"delegates operations"| node_application_service
node_application_service -->|"reads and updates"| node_application_store
node_application_service -->|"uses forms"| node_form_service
node_application_service -->|"checks household"| node_household_service
node_application_service -->|"uses access codes"| node_access_service
node_application_service -->|"uses user data"| node_user_service
node_application_service -->|"uses Siebel API"| node_siebel
node_frontend -.->|"submits forms"| node_form_api
node_form_api -->|"delegates form work"| node_form_service
node_form_service -->|"reads and writes"| node_form_store
node_frontend -.->|"manages household"| node_household_api
node_household_api -->|"delegates operations"| node_household_service
node_household_api -->|"manages access codes"| node_access_service
node_household_service -->|"reads and updates"| node_household_store
node_access_service -->|"associates member"| node_household_service
node_frontend -.->|"uploads attachments"| node_attachments_api
node_attachments_api -->|"delegates attachment work"| node_attachments_service
node_household_api -->|"sends notifications"| node_notifications
node_notifications -->|"queues email"| node_notification_queue
node_notification_queue -.->|"delivers email"| node_ches
node_frontend -->|"requests form access"| node_forms_api
node_forms_api -->|"delegates token work"| node_forms_service
node_frontend -->|"checks service health"| node_health_api
node_auth_api -.->|"protects routes"| node_session_guard
node_form_service -.->|"persists form data"| node_mongo

click node_auth_api "https://github.com/bcgov/social-middleware/blob/main/social-middleware/src/auth/auth.controller.ts"
click node_auth_strategy "https://github.com/bcgov/social-middleware/tree/main/social-middleware/src/auth/strategies"
click node_user_service "https://github.com/bcgov/social-middleware/blob/main/social-middleware/src/auth/user.service.ts"
click node_session_guard "https://github.com/bcgov/social-middleware/blob/main/social-middleware/src/auth/session-auth.guard.ts"
click node_application_api "https://github.com/bcgov/social-middleware/blob/main/social-middleware/src/application-package/application-package.controller.ts"
click node_application_service "https://github.com/bcgov/social-middleware/blob/main/social-middleware/src/application-package/services/application-package.service.ts"
click node_application_store "https://github.com/bcgov/social-middleware/blob/main/social-middleware/src/application-package/schema/application-package.schema.ts"
click node_form_api "https://github.com/bcgov/social-middleware/blob/main/social-middleware/src/application-form/application-form.controller.ts"
click node_form_service "https://github.com/bcgov/social-middleware/blob/main/social-middleware/src/application-form/services/application-form.service.ts"
click node_form_store "https://github.com/bcgov/social-middleware/blob/main/social-middleware/src/application-form/schemas/application-form.schema.ts"
click node_household_api "https://github.com/bcgov/social-middleware/blob/main/social-middleware/src/household/household.controller.ts"
click node_household_service "https://github.com/bcgov/social-middleware/blob/main/social-middleware/src/household/services/household.service.ts"
click node_access_service "https://github.com/bcgov/social-middleware/blob/main/social-middleware/src/household/services/access-code.service.ts"
click node_household_store "https://github.com/bcgov/social-middleware/blob/main/social-middleware/src/household/schemas/household-members.schema.ts"
click node_attachments_api "https://github.com/bcgov/social-middleware/blob/main/social-middleware/src/attachments/attachments.controller.ts"
click node_attachments_service "https://github.com/bcgov/social-middleware/blob/main/social-middleware/src/attachments/attachments.service.ts"
click node_notifications "https://github.com/bcgov/social-middleware/blob/main/social-middleware/src/notifications/services/notification.service.ts"
click node_notification_queue "https://github.com/bcgov/social-middleware/blob/main/social-middleware/src/notifications/queue/notification-queue.service.ts"
click node_ches "https://github.com/bcgov/social-middleware/blob/main/social-middleware/src/notifications/services/ches.service.ts"
click node_siebel "https://github.com/bcgov/social-middleware/blob/main/social-middleware/src/siebel/siebel-api.service.ts"
click node_forms_api "https://github.com/bcgov/social-middleware/blob/main/social-middleware/src/forms/forms.controller.ts"
click node_forms_service "https://github.com/bcgov/social-middleware/blob/main/social-middleware/src/forms/forms.service.ts"
click node_health_api "https://github.com/bcgov/social-middleware/blob/main/social-middleware/src/health/health.controller.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_auth_api,node_auth_strategy,node_user_service,node_session_guard,node_frontend toneBlue
class node_application_api,node_application_service,node_attachments_api,node_attachments_service toneAmber
class node_form_api,node_form_service,node_household_api,node_household_service,node_access_service,node_forms_api,node_forms_service toneMint
class node_bcsc,node_notifications,node_notification_queue,node_ches,node_siebel toneRose
class node_application_store,node_form_store,node_household_store,node_health_api,node_mongo toneIndigo
```

## Components

### Identity and sessions

- [Authentication API](https://github.com/bcgov/social-middleware/blob/main/social-middleware/src/auth/auth.controller.ts): `social-middleware/src/auth/auth.controller.ts`
- [Authentication strategies](https://github.com/bcgov/social-middleware/tree/main/social-middleware/src/auth/strategies): `social-middleware/src/auth/strategies`
- [User management](https://github.com/bcgov/social-middleware/blob/main/social-middleware/src/auth/user.service.ts): `social-middleware/src/auth/user.service.ts`
- [Session guard](https://github.com/bcgov/social-middleware/blob/main/social-middleware/src/auth/session-auth.guard.ts): `social-middleware/src/auth/session-auth.guard.ts`

### Application lifecycle

- [Application package API](https://github.com/bcgov/social-middleware/blob/main/social-middleware/src/application-package/application-package.controller.ts): `social-middleware/src/application-package/application-package.controller.ts`
- [Application lifecycle service](https://github.com/bcgov/social-middleware/blob/main/social-middleware/src/application-package/services/application-package.service.ts): `social-middleware/src/application-package/services/application-package.service.ts`
- [Attachments API](https://github.com/bcgov/social-middleware/blob/main/social-middleware/src/attachments/attachments.controller.ts): `social-middleware/src/attachments/attachments.controller.ts`
- [Attachment handling](https://github.com/bcgov/social-middleware/blob/main/social-middleware/src/attachments/attachments.service.ts): `social-middleware/src/attachments/attachments.service.ts`

### Forms and household

- [Application form API](https://github.com/bcgov/social-middleware/blob/main/social-middleware/src/application-form/application-form.controller.ts): `social-middleware/src/application-form/application-form.controller.ts`
- [Form management](https://github.com/bcgov/social-middleware/blob/main/social-middleware/src/application-form/services/application-form.service.ts): `social-middleware/src/application-form/services/application-form.service.ts`
- [Household API](https://github.com/bcgov/social-middleware/blob/main/social-middleware/src/household/household.controller.ts): `social-middleware/src/household/household.controller.ts`
- [Household management](https://github.com/bcgov/social-middleware/blob/main/social-middleware/src/household/services/household.service.ts): `social-middleware/src/household/services/household.service.ts`
- [Screening access codes](https://github.com/bcgov/social-middleware/blob/main/social-middleware/src/household/services/access-code.service.ts): `social-middleware/src/household/services/access-code.service.ts`
- [Form token API](https://github.com/bcgov/social-middleware/blob/main/social-middleware/src/forms/forms.controller.ts): `social-middleware/src/forms/forms.controller.ts`
- [Form token handling](https://github.com/bcgov/social-middleware/blob/main/social-middleware/src/forms/forms.service.ts): `social-middleware/src/forms/forms.service.ts`

### External services

- **BC Services Card**
- [Notifications](https://github.com/bcgov/social-middleware/blob/main/social-middleware/src/notifications/services/notification.service.ts): `social-middleware/src/notifications/services/notification.service.ts`
- [Email queue](https://github.com/bcgov/social-middleware/blob/main/social-middleware/src/notifications/queue/notification-queue.service.ts): `social-middleware/src/notifications/queue/notification-queue.service.ts`
- [Email delivery](https://github.com/bcgov/social-middleware/blob/main/social-middleware/src/notifications/services/ches.service.ts): `social-middleware/src/notifications/services/ches.service.ts`
- [Siebel services](https://github.com/bcgov/social-middleware/blob/main/social-middleware/src/siebel/siebel-api.service.ts): `social-middleware/src/siebel/siebel-api.service.ts`

### API and persistence

- [Application records](https://github.com/bcgov/social-middleware/blob/main/social-middleware/src/application-package/schema/application-package.schema.ts): `social-middleware/src/application-package/schema/application-package.schema.ts`
- [Form records](https://github.com/bcgov/social-middleware/blob/main/social-middleware/src/application-form/schemas/application-form.schema.ts): `social-middleware/src/application-form/schemas/application-form.schema.ts`
- [Household records](https://github.com/bcgov/social-middleware/blob/main/social-middleware/src/household/schemas/household-members.schema.ts): `social-middleware/src/household/schemas/household-members.schema.ts`
- [Health endpoint](https://github.com/bcgov/social-middleware/blob/main/social-middleware/src/health/health.controller.ts): `social-middleware/src/health/health.controller.ts`
- **MongoDB**

### Other components

- **Frontend user**

## Connections

- Frontend user → Authentication API: authenticates at
- Authentication API → Authentication strategies: dispatches callback (evidence: `social-middleware/src/auth/auth.controller.ts`)
- Authentication API → User management: looks up user (evidence: `social-middleware/src/auth/auth.controller.ts`)
- Authentication strategies → BC Services Card: exchanges credentials
- Frontend user → Application package API: manages applications
- Application package API → Application lifecycle service: delegates operations (evidence: `social-middleware/src/application-package/application-package.controller.ts`)
- Application lifecycle service → Application records: reads and updates (evidence: `social-middleware/src/application-package/services/application-package.service.ts`)
- Application lifecycle service → Form management: uses forms (evidence: `social-middleware/src/application-package/services/application-package.service.ts`)
- Application lifecycle service → Household management: checks household (evidence: `social-middleware/src/application-package/services/application-package.service.ts`)
- Application lifecycle service → Screening access codes: uses access codes (evidence: `social-middleware/src/application-package/services/application-package.service.ts`)
- Application lifecycle service → User management: uses user data (evidence: `social-middleware/src/application-package/services/application-package.service.ts`)
- Application lifecycle service → Siebel services: uses Siebel API (evidence: `social-middleware/src/application-package/services/application-package.service.ts`)
- Frontend user → Application form API: submits forms
- Application form API → Form management: delegates form work (evidence: `social-middleware/src/application-form/application-form.controller.ts`)
- Form management → Form records: reads and writes (evidence: `social-middleware/src/application-form/services/application-form.service.ts`)
- Frontend user → Household API: manages household
- Household API → Household management: delegates operations (evidence: `social-middleware/src/household/household.controller.ts`)
- Household API → Screening access codes: manages access codes (evidence: `social-middleware/src/household/household.controller.ts`)
- Household management → Household records: reads and updates (evidence: `social-middleware/src/household/services/household.service.ts`)
- Screening access codes → Household management: associates member (evidence: `social-middleware/src/household/services/access-code.service.ts`)
- Frontend user → Attachments API: uploads attachments
- Attachments API → Attachment handling: delegates attachment work (evidence: `social-middleware/src/attachments/attachments.controller.ts`)
- Household API → Notifications: sends notifications (evidence: `social-middleware/src/household/household.controller.ts`)
- Notifications → Email queue: queues email (evidence: `social-middleware/src/notifications/services/notification.service.ts`)
- Email queue → Email delivery: delivers email
- Frontend user → Form token API: requests form access
- Form token API → Form token handling: delegates token work (evidence: `social-middleware/src/forms/forms.controller.ts`)
- Frontend user → Health endpoint: checks service health
- Authentication API → Session guard: protects routes (evidence: `social-middleware/src/auth/auth.controller.ts`)
- Form management → MongoDB: persists form data
