# bcgov/cydb-submissions architecture

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

## Overview

CYDB Submissions is a SvelteKit application for collecting public submissions and supporting staff review. The principal workflow validates and stores a form submission and attachments, then exposes searchable staff lists and read-only submission views. Staff authentication, role-gated administration, CHEFS import, OCR processing, and operational probes are additional capabilities. The graph follows relationships supported by the README or supplied source excerpts and SOURCE INDEX; unsampled paths are represented only where their role is documented.

Main entry points: [`src/lib/server/submissions.ts`](https://github.com/bcgov/cydb-submissions/blob/main/src/lib/server/submissions.ts) (Submission persistence), [`src/lib/server/db/schema.ts`](https://github.com/bcgov/cydb-submissions/blob/main/src/lib/server/db/schema.ts) (SQLite data), [`src/lib/server/chefs/ingest.ts`](https://github.com/bcgov/cydb-submissions/blob/main/src/lib/server/chefs/ingest.ts) (CHEFS ingestion), [`src/lib/server/ocr/process-job.ts`](https://github.com/bcgov/cydb-submissions/blob/main/src/lib/server/ocr/process-job.ts) (OCR job processor)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_intake["Submission intake"]
  node_public["Public form<br/>[+page.svelte]"]
  node_form_schema["Form schema<br/>[schema.ts]"]
  node_intake_route["Submission endpoint<br/>[+page.server.ts]"]
  node_submission_service["Submission persistence<br/>[submissions.ts]"]
  node_attachments["Attachment storage<br/>[storage.ts]"]
end

subgraph group_staff["Staff access and review"]
  node_auth["Authentication<br/>[auth-options.ts]"]
  node_staff_routes["Staff routes<br/>[+page.server.ts]"]
  node_search["Search and sort<br/>[query.ts]"]
  node_submission_view["Submission viewer<br/>[+page.server.ts]"]
  node_attachment_route["Attachment access<br/>[+server.ts]"]
  node_admin["Administration<br/>[+page.server.ts]"]
  node_chefs_admin["CHEFS settings<br/>[+page.server.ts]"]
end

subgraph group_processing["Import and processing"]
  node_chefs_poller["CHEFS poller<br/>[poller.ts]"]
  node_chefs_client["CHEFS API client<br/>[client.ts]"]
  node_chefs_mapper["CHEFS mapper<br/>[mapper.ts]"]
  node_chefs_ingest["CHEFS ingestion<br/>[ingest.ts]"]
  node_ocr_queue["OCR job queue<br/>[enqueue.ts]"]
  node_ocr_worker["OCR worker<br/>[worker.ts]"]
  node_ocr_job["OCR job processor<br/>[process-job.ts]"]
  node_ocr_provider["OCR provider<br/>[select-provider.ts]"]
  node_search_index["Search indexing<br/>[indexer.ts]"]
end

subgraph group_platform["Shared platform"]
  node_sqlite[("SQLite data<br/>[schema.ts]")]
  node_health["Health probes<br/>[+server.ts]"]
  node_audit["Audit logging<br/>[audit.ts]"]
end

node_staff_user(("Staff member"))
node_sso(("BC Gov SSO"))

node_public -.->|"posts form"| node_intake_route
node_intake_route -.->|"validates with"| node_form_schema
node_intake_route -.->|"persists submission"| node_submission_service
node_submission_service -->|"writes records"| node_sqlite
node_submission_service -.->|"stores files"| node_attachments
node_submission_service -->|"enqueues attachments"| node_ocr_queue
node_staff_user -.->|"signs in"| node_auth
node_auth -->|"authenticates with"| node_sso
node_staff_routes -.->|"queries submissions"| node_search
node_search -->|"reads records"| node_sqlite
node_staff_routes -.->|"opens submission"| node_submission_view
node_submission_view -.->|"loads details"| node_sqlite
node_submission_view -.->|"previews attachments"| node_attachment_route
node_attachment_route -.->|"reads files"| node_attachments
node_admin -.->|"configures import"| node_chefs_admin
node_chefs_poller -.->|"fetches exports"| node_chefs_client
node_chefs_poller -.->|"maps submissions"| node_chefs_mapper
node_chefs_poller -.->|"ingests results"| node_chefs_ingest
node_chefs_ingest -.->|"downloads files"| node_chefs_client
node_chefs_ingest -->|"writes submissions"| node_submission_service
node_chefs_ingest -.->|"saves attachments"| node_attachments
node_ocr_worker -->|"leases jobs"| node_ocr_queue
node_ocr_worker -->|"processes jobs"| node_ocr_job
node_ocr_job -.->|"analyzes documents"| node_ocr_provider
node_ocr_job -->|"stores OCR results"| node_sqlite
node_health -.->|"checks readiness"| node_sqlite
node_staff_routes -.->|"logs actions"| node_audit
node_ocr_job -.->|"updates search index"| node_search_index

click node_public "https://github.com/bcgov/cydb-submissions/blob/main/src/routes/%2Bpage.svelte"
click node_form_schema "https://github.com/bcgov/cydb-submissions/blob/main/src/lib/form/schema.ts"
click node_intake_route "https://github.com/bcgov/cydb-submissions/blob/main/archive/public-form/%2Bpage.server.ts"
click node_submission_service "https://github.com/bcgov/cydb-submissions/blob/main/src/lib/server/submissions.ts"
click node_attachments "https://github.com/bcgov/cydb-submissions/blob/main/src/lib/server/storage.ts"
click node_sqlite "https://github.com/bcgov/cydb-submissions/blob/main/src/lib/server/db/schema.ts"
click node_auth "https://github.com/bcgov/cydb-submissions/blob/main/src/lib/server/auth-options.ts"
click node_staff_routes "https://github.com/bcgov/cydb-submissions/blob/main/src/routes/submissions/%2Bpage.server.ts"
click node_search "https://github.com/bcgov/cydb-submissions/blob/main/src/lib/server/search/query.ts"
click node_submission_view "https://github.com/bcgov/cydb-submissions/blob/main/src/routes/submissions/%5Buuid%5D/%2Bpage.server.ts"
click node_attachment_route "https://github.com/bcgov/cydb-submissions/blob/main/src/routes/attachments/%5Bid%5D/%2Bserver.ts"
click node_admin "https://github.com/bcgov/cydb-submissions/blob/main/src/routes/admin/%2Bpage.server.ts"
click node_chefs_admin "https://github.com/bcgov/cydb-submissions/blob/main/src/routes/admin/chefs/%2Bpage.server.ts"
click node_chefs_poller "https://github.com/bcgov/cydb-submissions/blob/main/src/lib/server/chefs/poller.ts"
click node_chefs_client "https://github.com/bcgov/cydb-submissions/blob/main/src/lib/server/chefs/client.ts"
click node_chefs_mapper "https://github.com/bcgov/cydb-submissions/blob/main/src/lib/server/chefs/mapper.ts"
click node_chefs_ingest "https://github.com/bcgov/cydb-submissions/blob/main/src/lib/server/chefs/ingest.ts"
click node_ocr_queue "https://github.com/bcgov/cydb-submissions/blob/main/src/lib/server/ocr/enqueue.ts"
click node_ocr_worker "https://github.com/bcgov/cydb-submissions/blob/main/src/lib/server/ocr/worker.ts"
click node_ocr_job "https://github.com/bcgov/cydb-submissions/blob/main/src/lib/server/ocr/process-job.ts"
click node_ocr_provider "https://github.com/bcgov/cydb-submissions/blob/main/src/lib/server/ocr/select-provider.ts"
click node_search_index "https://github.com/bcgov/cydb-submissions/blob/main/src/lib/server/search/indexer.ts"
click node_health "https://github.com/bcgov/cydb-submissions/blob/main/src/routes/healthz/%2Bserver.ts"
click node_audit "https://github.com/bcgov/cydb-submissions/blob/main/src/lib/server/audit.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_public,node_form_schema,node_intake_route,node_submission_service,node_attachments toneBlue
class node_auth,node_staff_routes,node_search,node_submission_view,node_attachment_route,node_admin,node_chefs_admin toneAmber
class node_chefs_poller,node_chefs_client,node_chefs_mapper,node_chefs_ingest,node_ocr_queue,node_ocr_worker,node_ocr_job,node_ocr_provider,node_search_index toneMint
class node_sqlite,node_health,node_audit toneRose
class node_staff_user,node_sso toneIndigo
```

## Components

### Submission intake

- [Public form](https://github.com/bcgov/cydb-submissions/blob/main/src/routes/%2Bpage.svelte): `src/routes/+page.svelte`
- [Form schema](https://github.com/bcgov/cydb-submissions/blob/main/src/lib/form/schema.ts): `src/lib/form/schema.ts`
- [Submission endpoint](https://github.com/bcgov/cydb-submissions/blob/main/archive/public-form/%2Bpage.server.ts): `archive/public-form/+page.server.ts`
- [Submission persistence](https://github.com/bcgov/cydb-submissions/blob/main/src/lib/server/submissions.ts): `src/lib/server/submissions.ts`
- [Attachment storage](https://github.com/bcgov/cydb-submissions/blob/main/src/lib/server/storage.ts): `src/lib/server/storage.ts`

### Staff access and review

- [Authentication](https://github.com/bcgov/cydb-submissions/blob/main/src/lib/server/auth-options.ts): `src/lib/server/auth-options.ts`
- [Staff routes](https://github.com/bcgov/cydb-submissions/blob/main/src/routes/submissions/%2Bpage.server.ts): `src/routes/submissions/+page.server.ts`
- [Search and sort](https://github.com/bcgov/cydb-submissions/blob/main/src/lib/server/search/query.ts): `src/lib/server/search/query.ts`
- [Submission viewer](https://github.com/bcgov/cydb-submissions/blob/main/src/routes/submissions/%5Buuid%5D/%2Bpage.server.ts): `src/routes/submissions/[uuid]/+page.server.ts`
- [Attachment access](https://github.com/bcgov/cydb-submissions/blob/main/src/routes/attachments/%5Bid%5D/%2Bserver.ts): `src/routes/attachments/[id]/+server.ts`
- [Administration](https://github.com/bcgov/cydb-submissions/blob/main/src/routes/admin/%2Bpage.server.ts): `src/routes/admin/+page.server.ts`
- [CHEFS settings](https://github.com/bcgov/cydb-submissions/blob/main/src/routes/admin/chefs/%2Bpage.server.ts): `src/routes/admin/chefs/+page.server.ts`

### Import and processing

- [CHEFS poller](https://github.com/bcgov/cydb-submissions/blob/main/src/lib/server/chefs/poller.ts): `src/lib/server/chefs/poller.ts`
- [CHEFS API client](https://github.com/bcgov/cydb-submissions/blob/main/src/lib/server/chefs/client.ts): `src/lib/server/chefs/client.ts`
- [CHEFS mapper](https://github.com/bcgov/cydb-submissions/blob/main/src/lib/server/chefs/mapper.ts): `src/lib/server/chefs/mapper.ts`
- [CHEFS ingestion](https://github.com/bcgov/cydb-submissions/blob/main/src/lib/server/chefs/ingest.ts): `src/lib/server/chefs/ingest.ts`
- [OCR job queue](https://github.com/bcgov/cydb-submissions/blob/main/src/lib/server/ocr/enqueue.ts): `src/lib/server/ocr/enqueue.ts`
- [OCR worker](https://github.com/bcgov/cydb-submissions/blob/main/src/lib/server/ocr/worker.ts): `src/lib/server/ocr/worker.ts`
- [OCR job processor](https://github.com/bcgov/cydb-submissions/blob/main/src/lib/server/ocr/process-job.ts): `src/lib/server/ocr/process-job.ts`
- [OCR provider](https://github.com/bcgov/cydb-submissions/blob/main/src/lib/server/ocr/select-provider.ts): `src/lib/server/ocr/select-provider.ts`
- [Search indexing](https://github.com/bcgov/cydb-submissions/blob/main/src/lib/server/search/indexer.ts): `src/lib/server/search/indexer.ts`

### Shared platform

- [SQLite data](https://github.com/bcgov/cydb-submissions/blob/main/src/lib/server/db/schema.ts): `src/lib/server/db/schema.ts`
- [Health probes](https://github.com/bcgov/cydb-submissions/blob/main/src/routes/healthz/%2Bserver.ts): `src/routes/healthz/+server.ts`
- [Audit logging](https://github.com/bcgov/cydb-submissions/blob/main/src/lib/server/audit.ts): `src/lib/server/audit.ts`

### Other components

- **Staff member**
- **BC Gov SSO**

## Connections

- Public form → Submission endpoint: posts form
- Submission endpoint → Form schema: validates with
- Submission endpoint → Submission persistence: persists submission
- Submission persistence → SQLite data: writes records (evidence: `src/lib/server/submissions.ts`)
- Submission persistence → Attachment storage: stores files (evidence: `src/lib/server/submissions.ts`)
- Submission persistence → OCR job queue: enqueues attachments (evidence: `src/lib/server/submissions.ts`)
- Staff member → Authentication: signs in
- Authentication → BC Gov SSO: authenticates with (evidence: `src/lib/server/auth-options.ts`)
- Staff routes → Search and sort: queries submissions
- Search and sort → SQLite data: reads records (evidence: `src/lib/server/search/query.ts`)
- Staff routes → Submission viewer: opens submission
- Submission viewer → SQLite data: loads details
- Submission viewer → Attachment access: previews attachments
- Attachment access → Attachment storage: reads files
- Administration → CHEFS settings: configures import
- CHEFS poller → CHEFS API client: fetches exports
- CHEFS poller → CHEFS mapper: maps submissions
- CHEFS poller → CHEFS ingestion: ingests results
- CHEFS ingestion → CHEFS API client: downloads files (evidence: `src/lib/server/chefs/ingest.ts`)
- CHEFS ingestion → Submission persistence: writes submissions (evidence: `src/lib/server/chefs/ingest.ts`)
- CHEFS ingestion → Attachment storage: saves attachments (evidence: `src/lib/server/chefs/ingest.ts`)
- OCR worker → OCR job queue: leases jobs (evidence: `src/lib/server/ocr/worker.ts`)
- OCR worker → OCR job processor: processes jobs (evidence: `src/lib/server/ocr/worker.ts`)
- OCR job processor → OCR provider: analyzes documents
- OCR job processor → SQLite data: stores OCR results (evidence: `src/lib/server/ocr/process-job.ts`)
- Health probes → SQLite data: checks readiness
- Staff routes → Audit logging: logs actions
- OCR job processor → Search indexing: updates search index
