# bccsa/luminary architecture

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

- Interactive diagram: https://gitdiagram.com/bccsa/luminary
- Repository: https://github.com/bccsa/luminary

## Overview

Luminary is an offline-first content platform with a public app, an editorial CMS, a shared client library, and a CouchDB-backed API. The reader workflow is to browse or search content, receive locally available results, and synchronize data with the API; the editorial workflow is to manage content and related platform settings through the CMS. The graph preserves major capabilities visible in the tree, including recommendations, full-text search, static rendering, media storage, and access control. Some of these branches are represented by their source paths because their implementation was not sampled.

Main entry points: [`app/src/pages`](https://github.com/bccsa/luminary/tree/main/app/src/pages) (Reader app), [`cms/src/pages`](https://github.com/bccsa/luminary/tree/main/cms/src/pages) (Editorial CMS), [`shared/src/util/HybridQuery/HybridQuery.ts`](https://github.com/bccsa/luminary/blob/main/shared/src/util/HybridQuery/HybridQuery.ts) (Hybrid queries), [`api/src/auth/authIdentity.service.ts`](https://github.com/bccsa/luminary/blob/main/api/src/auth/authIdentity.service.ts) (Authentication)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["User clients"]
  node_app["Reader app"]
  node_cms["Editorial CMS"]
  node_client_queries["Content queries<br/>[useContentQuery.ts]"]
  node_cms_content["Content editing"]
  node_recommendations["Recommendations"]
  node_ssg["Static rendering"]
end

subgraph group_shared["Shared runtime"]
  node_shared_library["Shared client library<br/>[index.ts]"]
  node_hybrid["Hybrid queries<br/>[HybridQuery.ts]"]
  node_local_db[("Local database<br/>[database.ts]")]
  node_sync["Offline sync"]
  node_fts["Full-text search"]
  node_worker["Worker tasks<br/>[workerClient.ts]"]
end

subgraph group_api["API services"]
  node_query_api["Query endpoint"]
  node_query_service["Query service<br/>[query.service.ts]"]
  node_change_api["Change requests"]
  node_identity["Authentication"]
  node_permissions["Access control"]
  node_storage_api["Media and storage<br/>[s3.service.ts]"]
end

subgraph group_data["Persistence and integrations"]
  node_db_service["Database service<br/>[db.service.ts]"]
  node_couchdb[("CouchDB")]
  node_object_storage[("Object storage")]
  node_auth_provider["Identity provider"]
end

node_reader(("Reader"))
node_editor(("Editor"))

node_reader -->|"uses"| node_app
node_editor -->|"uses"| node_cms
node_app -.->|"requests content"| node_client_queries
node_cms -.->|"edits content"| node_cms_content
node_client_queries -.->|"queries through"| node_hybrid
node_hybrid -->|"queries locally"| node_local_db
node_hybrid -->|"dispatches tasks"| node_worker
node_hybrid -.->|"synchronizes via"| node_sync
node_app -.->|"uses"| node_recommendations
node_app -.->|"searches with"| node_fts
node_app -.->|"renders statically"| node_ssg
node_cms -.->|"searches with"| node_fts
node_app -->|"uses library"| node_shared_library
node_cms -->|"uses library"| node_shared_library
node_query_api -->|"calls"| node_query_service
node_query_service -->|"queries"| node_db_service
node_query_service -->|"checks access"| node_permissions
node_query_api -->|"guards request"| node_identity
node_identity -->|"loads identity data"| node_db_service
node_identity -->|"uses access map"| node_permissions
node_cms_content -.->|"submits changes"| node_change_api
node_change_api -.->|"persists changes"| node_db_service
node_db_service -->|"reads and writes"| node_couchdb
node_storage_api -.->|"stores media"| node_object_storage
node_identity -->|"validates tokens"| node_auth_provider

click node_app "https://github.com/bccsa/luminary/tree/main/app/src/pages"
click node_cms "https://github.com/bccsa/luminary/tree/main/cms/src/pages"
click node_client_queries "https://github.com/bccsa/luminary/blob/main/app/src/composables/useContentQuery.ts"
click node_cms_content "https://github.com/bccsa/luminary/tree/main/cms/src/components/content"
click node_recommendations "https://github.com/bccsa/luminary/tree/main/app/src/recommendation"
click node_ssg "https://github.com/bccsa/luminary/tree/main/app/src/ssg"
click node_shared_library "https://github.com/bccsa/luminary/blob/main/shared/src/index.ts"
click node_hybrid "https://github.com/bccsa/luminary/blob/main/shared/src/util/HybridQuery/HybridQuery.ts"
click node_local_db "https://github.com/bccsa/luminary/blob/main/shared/src/db/database.ts"
click node_sync "https://github.com/bccsa/luminary/tree/main/shared/src/api/sync"
click node_fts "https://github.com/bccsa/luminary/tree/main/shared/src/fts"
click node_worker "https://github.com/bccsa/luminary/blob/main/shared/src/worker/workerClient.ts"
click node_query_api "https://github.com/bccsa/luminary/blob/main/api/src/endpoints/query.controller.ts"
click node_query_service "https://github.com/bccsa/luminary/blob/main/api/src/endpoints/query.service.ts"
click node_change_api "https://github.com/bccsa/luminary/blob/main/api/src/endpoints/changeRequest.service.ts"
click node_identity "https://github.com/bccsa/luminary/blob/main/api/src/auth/authIdentity.service.ts"
click node_permissions "https://github.com/bccsa/luminary/blob/main/api/src/permissions/permissions.service.ts"
click node_storage_api "https://github.com/bccsa/luminary/blob/main/api/src/s3/s3.service.ts"
click node_db_service "https://github.com/bccsa/luminary/blob/main/api/src/db/db.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_app,node_cms,node_client_queries,node_cms_content,node_recommendations,node_ssg toneBlue
class node_shared_library,node_hybrid,node_local_db,node_sync,node_fts,node_worker toneAmber
class node_query_api,node_query_service,node_change_api,node_identity,node_permissions,node_storage_api toneMint
class node_db_service,node_couchdb,node_object_storage,node_auth_provider toneRose
class node_reader,node_editor toneIndigo
```

## Components

### User clients

- [Reader app](https://github.com/bccsa/luminary/tree/main/app/src/pages): `app/src/pages`
- [Editorial CMS](https://github.com/bccsa/luminary/tree/main/cms/src/pages): `cms/src/pages`
- [Content queries](https://github.com/bccsa/luminary/blob/main/app/src/composables/useContentQuery.ts): `app/src/composables/useContentQuery.ts`
- [Content editing](https://github.com/bccsa/luminary/tree/main/cms/src/components/content): `cms/src/components/content`
- [Recommendations](https://github.com/bccsa/luminary/tree/main/app/src/recommendation): `app/src/recommendation`
- [Static rendering](https://github.com/bccsa/luminary/tree/main/app/src/ssg): `app/src/ssg`

### Shared runtime

- [Shared client library](https://github.com/bccsa/luminary/blob/main/shared/src/index.ts): `shared/src/index.ts`
- [Hybrid queries](https://github.com/bccsa/luminary/blob/main/shared/src/util/HybridQuery/HybridQuery.ts): `shared/src/util/HybridQuery/HybridQuery.ts`
- [Local database](https://github.com/bccsa/luminary/blob/main/shared/src/db/database.ts): `shared/src/db/database.ts`
- [Offline sync](https://github.com/bccsa/luminary/tree/main/shared/src/api/sync): `shared/src/api/sync`
- [Full-text search](https://github.com/bccsa/luminary/tree/main/shared/src/fts): `shared/src/fts`
- [Worker tasks](https://github.com/bccsa/luminary/blob/main/shared/src/worker/workerClient.ts): `shared/src/worker/workerClient.ts`

### API services

- [Query endpoint](https://github.com/bccsa/luminary/blob/main/api/src/endpoints/query.controller.ts): `api/src/endpoints/query.controller.ts`
- [Query service](https://github.com/bccsa/luminary/blob/main/api/src/endpoints/query.service.ts): `api/src/endpoints/query.service.ts`
- [Change requests](https://github.com/bccsa/luminary/blob/main/api/src/endpoints/changeRequest.service.ts): `api/src/endpoints/changeRequest.service.ts`
- [Authentication](https://github.com/bccsa/luminary/blob/main/api/src/auth/authIdentity.service.ts): `api/src/auth/authIdentity.service.ts`
- [Access control](https://github.com/bccsa/luminary/blob/main/api/src/permissions/permissions.service.ts): `api/src/permissions/permissions.service.ts`
- [Media and storage](https://github.com/bccsa/luminary/blob/main/api/src/s3/s3.service.ts): `api/src/s3/s3.service.ts`

### Persistence and integrations

- [Database service](https://github.com/bccsa/luminary/blob/main/api/src/db/db.service.ts): `api/src/db/db.service.ts`
- **CouchDB**
- **Object storage**
- **Identity provider**

### Other components

- **Reader**
- **Editor**

## Connections

- Reader → Reader app: uses
- Editor → Editorial CMS: uses
- Reader app → Content queries: requests content
- Editorial CMS → Content editing: edits content
- Content queries → Hybrid queries: queries through
- Hybrid queries → Local database: queries locally (evidence: `shared/src/util/HybridQuery/HybridQuery.ts`)
- Hybrid queries → Worker tasks: dispatches tasks (evidence: `shared/src/util/HybridQuery/HybridQuery.ts`)
- Hybrid queries → Offline sync: synchronizes via (evidence: `shared/src/util/HybridQuery/HybridQuery.ts`)
- Reader app → Recommendations: uses
- Reader app → Full-text search: searches with
- Reader app → Static rendering: renders statically
- Editorial CMS → Full-text search: searches with
- Reader app → Shared client library: uses library
- Editorial CMS → Shared client library: uses library
- Query endpoint → Query service: calls (evidence: `api/src/endpoints/query.controller.ts`)
- Query service → Database service: queries (evidence: `api/src/endpoints/query.service.ts`)
- Query service → Access control: checks access (evidence: `api/src/endpoints/query.service.ts`)
- Query endpoint → Authentication: guards request (evidence: `api/src/endpoints/query.controller.ts`)
- Authentication → Database service: loads identity data (evidence: `api/src/auth/authIdentity.service.ts`)
- Authentication → Access control: uses access map (evidence: `api/src/auth/authIdentity.service.ts`)
- Content editing → Change requests: submits changes
- Change requests → Database service: persists changes
- Database service → CouchDB: reads and writes
- Media and storage → Object storage: stores media
- Authentication → Identity provider: validates tokens (evidence: `api/src/auth/authIdentity.service.ts`)
