# unlockdigital/loci architecture

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

- Interactive diagram: https://gitdiagram.com/unlockdigital/loci
- Repository: https://github.com/unlockdigital/loci

## Overview

Loci is a research-evidence viewer and authoring system: a reader browses published objects, selects a model annotation, follows its video and timed transcript, and shares a citation or moment. Authors manage source objects, models, videos, transcripts, and annotations through the authenticated console; search and public delivery provide discovery and reader access. The API also includes project-scoped authoring review and semantic/visual search capabilities. Edges are limited to README-described behavior or relationships visible in the supplied excerpts and source index; unsampled subsystems are represented at their exact enclosing directories.

Main entry points: [`apps/web/src/lib/api.js`](https://github.com/unlockdigital/loci/blob/main/apps/web/src/lib/api.js) (API client), [`apps/web/src/evidence/EvidenceObjectApp.jsx`](https://github.com/unlockdigital/loci/blob/main/apps/web/src/evidence/EvidenceObjectApp.jsx) (Evidence viewer), [`apps/api/app/main.py`](https://github.com/unlockdigital/loci/blob/main/apps/api/app/main.py) (API routing), [`apps/api/app/api/v1/endpoints`](https://github.com/unlockdigital/loci/tree/main/apps/api/app/api/v1/endpoints) (Domain endpoints)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_reader["Public experience"]
  node_public_browse["Object browser"]
  node_evidence_viewer["Evidence viewer"]
  node_model_canvas["3D model canvas<br/>[ModelCanvas.jsx]"]
  node_public_shell["Public experience shell"]
  node_search_ui["Search controls"]
  node_web_api["API client<br/>[api.js]"]
  node_navigation["Share navigation<br/>[navigation.js]"]
  node_brand["Brand components<br/>[BrandLockup.jsx]"]
  node_search_ui_studio["Studio search<br/>[StudioSearch.jsx]"]
end

subgraph group_authoring["Authoring and review"]
  node_console["Authoring console<br/>[App.jsx]"]
  node_authoring_routes["Authoring endpoints<br/>[routes.py]"]
  node_auth["Authentication<br/>[auth.py]"]
end

subgraph group_api["API and domain services"]
  node_api_entry["API routing<br/>[main.py]"]
  node_public_routes["Public object and clip routes"]
  node_domain_routes["Domain endpoints"]
  node_search_service["Semantic and visual search<br/>[search.py]"]
  node_media_services["Media and transcript services"]
  node_publication["Public publication services<br/>[public_sync.py]"]
end

subgraph group_data["Persistence and integrations"]
  node_db_session["Database session<br/>[session.py]"]
  node_entities[("Research records<br/>[entities.py]")]
  node_ai_providers["Embedding providers"]
end

node_reader(("Reader"))
node_postgres[("PostgreSQL")]
node_redis["Redis queue"]

node_reader -->|"browses"| node_public_browse
node_public_browse -.->|"opens object"| node_evidence_viewer
node_evidence_viewer -.->|"selects model"| node_model_canvas
node_evidence_viewer -->|"requests evidence"| node_web_api
node_search_ui -->|"fetches suggestions"| node_web_api
node_evidence_viewer -->|"renders search"| node_search_ui_studio
node_public_shell -->|"uses canvas"| node_model_canvas
node_console -->|"requests clips"| node_web_api
node_console -->|"loads transcript"| node_web_api
node_web_api -.->|"calls API"| node_api_entry
node_api_entry -->|"routes requests"| node_public_routes
node_api_entry -->|"routes requests"| node_domain_routes
node_domain_routes -->|"dispatches search"| node_search_service
node_domain_routes -->|"dispatches authoring"| node_authoring_routes
node_domain_routes -->|"dispatches auth"| node_auth
node_search_service -->|"uses embeddings"| node_ai_providers
node_authoring_routes -->|"queries records"| node_entities
node_db_session -->|"connects"| node_postgres
node_authoring_routes -->|"uses session"| node_db_session
node_search_service -->|"queries records"| node_db_session
node_entities -->|"maps tables"| node_db_session
node_public_routes -.->|"serves published data"| node_publication
node_media_services -.->|"records media"| node_entities
node_api_entry -.->|"uses queue"| node_redis

click node_public_browse "https://github.com/unlockdigital/loci/blob/main/apps/web/src/public/PublicBrowseApp.jsx"
click node_evidence_viewer "https://github.com/unlockdigital/loci/blob/main/apps/web/src/evidence/EvidenceObjectApp.jsx"
click node_model_canvas "https://github.com/unlockdigital/loci/blob/main/apps/web/src/components/ModelCanvas.jsx"
click node_public_shell "https://github.com/unlockdigital/loci/blob/main/apps/web/src/components/PublicExperienceShell.jsx"
click node_search_ui "https://github.com/unlockdigital/loci/blob/main/apps/web/src/components/SearchAutosuggest.jsx"
click node_web_api "https://github.com/unlockdigital/loci/blob/main/apps/web/src/lib/api.js"
click node_navigation "https://github.com/unlockdigital/loci/blob/main/apps/web/src/lib/navigation.js"
click node_brand "https://github.com/unlockdigital/loci/blob/main/apps/web/src/components/BrandLockup.jsx"
click node_console "https://github.com/unlockdigital/loci/blob/main/apps/web/src/App.jsx"
click node_authoring_routes "https://github.com/unlockdigital/loci/blob/main/apps/api/app/api/v1/endpoints/authoring/routes.py"
click node_auth "https://github.com/unlockdigital/loci/blob/main/apps/api/app/api/v1/endpoints/auth.py"
click node_search_ui_studio "https://github.com/unlockdigital/loci/blob/main/apps/web/src/evidence/studio/StudioSearch.jsx"
click node_api_entry "https://github.com/unlockdigital/loci/blob/main/apps/api/app/main.py"
click node_public_routes "https://github.com/unlockdigital/loci/tree/main/apps/api/app/api/public/endpoints"
click node_domain_routes "https://github.com/unlockdigital/loci/tree/main/apps/api/app/api/v1/endpoints"
click node_search_service "https://github.com/unlockdigital/loci/blob/main/apps/api/app/api/v1/endpoints/search.py"
click node_media_services "https://github.com/unlockdigital/loci/tree/main/apps/api/app/services"
click node_publication "https://github.com/unlockdigital/loci/blob/main/apps/api/app/services/public_sync.py"
click node_db_session "https://github.com/unlockdigital/loci/blob/main/apps/api/app/db/session.py"
click node_entities "https://github.com/unlockdigital/loci/blob/main/apps/api/app/models/entities.py"
click node_ai_providers "https://github.com/unlockdigital/loci/tree/main/apps/api/app/services/ai"

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_browse,node_evidence_viewer,node_model_canvas,node_public_shell,node_search_ui,node_web_api,node_navigation,node_brand,node_search_ui_studio toneBlue
class node_console,node_authoring_routes,node_auth,node_postgres,node_redis toneAmber
class node_api_entry,node_public_routes,node_domain_routes,node_search_service,node_media_services,node_publication toneMint
class node_db_session,node_entities,node_ai_providers toneRose
class node_reader toneIndigo
```

## Components

### Public experience

- [Object browser](https://github.com/unlockdigital/loci/blob/main/apps/web/src/public/PublicBrowseApp.jsx): `apps/web/src/public/PublicBrowseApp.jsx`
- [Evidence viewer](https://github.com/unlockdigital/loci/blob/main/apps/web/src/evidence/EvidenceObjectApp.jsx): `apps/web/src/evidence/EvidenceObjectApp.jsx`
- [3D model canvas](https://github.com/unlockdigital/loci/blob/main/apps/web/src/components/ModelCanvas.jsx): `apps/web/src/components/ModelCanvas.jsx`
- [Public experience shell](https://github.com/unlockdigital/loci/blob/main/apps/web/src/components/PublicExperienceShell.jsx): `apps/web/src/components/PublicExperienceShell.jsx`
- [Search controls](https://github.com/unlockdigital/loci/blob/main/apps/web/src/components/SearchAutosuggest.jsx): `apps/web/src/components/SearchAutosuggest.jsx`
- [API client](https://github.com/unlockdigital/loci/blob/main/apps/web/src/lib/api.js): `apps/web/src/lib/api.js`
- [Share navigation](https://github.com/unlockdigital/loci/blob/main/apps/web/src/lib/navigation.js): `apps/web/src/lib/navigation.js`
- [Brand components](https://github.com/unlockdigital/loci/blob/main/apps/web/src/components/BrandLockup.jsx): `apps/web/src/components/BrandLockup.jsx`
- [Studio search](https://github.com/unlockdigital/loci/blob/main/apps/web/src/evidence/studio/StudioSearch.jsx): `apps/web/src/evidence/studio/StudioSearch.jsx`

### Authoring and review

- [Authoring console](https://github.com/unlockdigital/loci/blob/main/apps/web/src/App.jsx): `apps/web/src/App.jsx`
- [Authoring endpoints](https://github.com/unlockdigital/loci/blob/main/apps/api/app/api/v1/endpoints/authoring/routes.py): `apps/api/app/api/v1/endpoints/authoring/routes.py`
- [Authentication](https://github.com/unlockdigital/loci/blob/main/apps/api/app/api/v1/endpoints/auth.py): `apps/api/app/api/v1/endpoints/auth.py`

### API and domain services

- [API routing](https://github.com/unlockdigital/loci/blob/main/apps/api/app/main.py): `apps/api/app/main.py`
- [Public object and clip routes](https://github.com/unlockdigital/loci/tree/main/apps/api/app/api/public/endpoints): `apps/api/app/api/public/endpoints`
- [Domain endpoints](https://github.com/unlockdigital/loci/tree/main/apps/api/app/api/v1/endpoints): `apps/api/app/api/v1/endpoints`
- [Semantic and visual search](https://github.com/unlockdigital/loci/blob/main/apps/api/app/api/v1/endpoints/search.py): `apps/api/app/api/v1/endpoints/search.py`
- [Media and transcript services](https://github.com/unlockdigital/loci/tree/main/apps/api/app/services): `apps/api/app/services`
- [Public publication services](https://github.com/unlockdigital/loci/blob/main/apps/api/app/services/public_sync.py): `apps/api/app/services/public_sync.py`

### Persistence and integrations

- [Database session](https://github.com/unlockdigital/loci/blob/main/apps/api/app/db/session.py): `apps/api/app/db/session.py`
- [Research records](https://github.com/unlockdigital/loci/blob/main/apps/api/app/models/entities.py): `apps/api/app/models/entities.py`
- [Embedding providers](https://github.com/unlockdigital/loci/tree/main/apps/api/app/services/ai): `apps/api/app/services/ai`

### Other components

- **Reader**
- **PostgreSQL**
- **Redis queue**

## Connections

- Reader → Object browser: browses (evidence: `README.md`)
- Object browser → Evidence viewer: opens object (evidence: `README.md`)
- Evidence viewer → 3D model canvas: selects model (evidence: `README.md`)
- Evidence viewer → API client: requests evidence (evidence: `apps/web/src/evidence/EvidenceObjectApp.jsx`)
- Search controls → API client: fetches suggestions (evidence: `apps/web/src/components/SearchAutosuggest.jsx`)
- Evidence viewer → Studio search: renders search (evidence: `apps/web/src/evidence/EvidenceObjectApp.jsx`)
- Public experience shell → 3D model canvas: uses canvas (evidence: `apps/web/src/components/PublicExperienceShell.jsx`)
- Authoring console → API client: requests clips (evidence: `apps/web/src/App.jsx`)
- Authoring console → API client: loads transcript (evidence: `apps/web/src/App.jsx`)
- API client → API routing: calls API
- API routing → Public object and clip routes: routes requests
- API routing → Domain endpoints: routes requests
- Domain endpoints → Semantic and visual search: dispatches search (evidence: `apps/api/app/api/v1/router.py`)
- Domain endpoints → Authoring endpoints: dispatches authoring (evidence: `apps/api/app/api/v1/endpoints/authoring/routes.py`)
- Domain endpoints → Authentication: dispatches auth (evidence: `apps/api/app/api/v1/router.py`)
- Semantic and visual search → Embedding providers: uses embeddings (evidence: `apps/api/app/api/v1/endpoints/search.py`)
- Authoring endpoints → Research records: queries records (evidence: `apps/api/app/api/v1/endpoints/authoring/routes.py`)
- Database session → PostgreSQL: connects (evidence: `apps/api/app/db/session.py`)
- Authoring endpoints → Database session: uses session (evidence: `apps/api/app/api/v1/endpoints/authoring/routes.py`)
- Semantic and visual search → Database session: queries records (evidence: `apps/api/app/api/v1/endpoints/search.py`)
- Research records → Database session: maps tables (evidence: `apps/api/app/models/entities.py`)
- Public object and clip routes → Public publication services: serves published data
- Media and transcript services → Research records: records media (evidence: `apps/api/app/services/notify_digest_worker.py`)
- API routing → Redis queue: uses queue
