# cerne-io/platform architecture

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

- Interactive diagram: https://gitdiagram.com/cerne-io/platform
- Repository: https://github.com/cerne-io/platform

## Overview

Cerne OSS is a self-hosted participatory narrative inquiry platform. A workspace owner designs a story instrument, shares a public form or interview, gathers anonymous stories and signifier responses, then explores and analyzes patterns in a dashboard. The graph also shows workspace access and persistence, plus optional AI assistance. The README documents the product capabilities and backend architecture; the sampled source establishes several frontend and server dependencies, but does not expose every route handler or page-to-service call, so unsampled relationships are not asserted.

Main entry points: [`src/App.tsx`](https://github.com/cerne-io/platform/blob/main/src/App.tsx) (React application), [`server/index.ts`](https://github.com/cerne-io/platform/blob/main/server/index.ts) (HTTP API), [`src/services/aiAssistantService.ts`](https://github.com/cerne-io/platform/blob/main/src/services/aiAssistantService.ts) (AI services), [`src/pages/Settings.tsx`](https://github.com/cerne-io/platform/blob/main/src/pages/Settings.tsx) (Workspace settings)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workspace["Workspace & runtime"]
  node_app["React application<br/>[App.tsx]"]
  node_auth["Workspace access<br/>[AuthContext.tsx]"]
  node_projects["Project workspace<br/>[ProjectContext.tsx]"]
  node_api["HTTP API<br/>[index.ts]"]
  node_database[("Embedded PGlite<br/>[migrate.ts]")]
  node_settings["Workspace settings<br/>[Settings.tsx]"]
end

subgraph group_design["Instrument design"]
  node_design["Instrument designer<br/>[Design.tsx]"]
  node_designdata["Instrument configuration"]
end

subgraph group_collection["Story collection"]
  node_collect["Collection setup<br/>[Collect.tsx]"]
  node_formdata["Form configuration loading"]
  node_publicform["Public form service"]
  node_submission["Story submission<br/>[useFormHandlers.ts]"]
  node_interviewer["AI-assisted interview"]
end

subgraph group_analysis["Exploration &amp; analysis"]
  node_explore["Story exploration<br/>[Explore.tsx]"]
  node_dashboard["Pattern dashboard<br/>[Dashboard.tsx]"]
  node_publicdashboard["Shared dashboard"]
end

subgraph group_ai["Optional AI"]
  node_aihelpers["AI services"]
end

node_owner(("Workspace owner"))
node_participant(("Story participant"))
node_llm{{"OpenAI-compatible LLM"}}

node_owner -->|"uses"| node_app
node_participant -->|"opens shared form"| node_app
node_app -->|"provides access state"| node_auth
node_app -->|"provides project state"| node_projects
node_app -->|"uses backend"| node_api
node_api -->|"persists data"| node_database
node_owner -->|"designs instrument"| node_design
node_design -.->|"configures questions"| node_designdata
node_designdata -->|"syncs configuration"| node_database
node_owner -->|"prepares collection"| node_collect
node_collect -.->|"loads form data"| node_formdata
node_formdata -->|"fetches public form"| node_publicform
node_participant -->|"submits story"| node_submission
node_submission -.->|"sends response"| node_api
node_participant -->|"shares narrative"| node_interviewer
node_owner -->|"explores stories"| node_explore
node_owner -->|"analyzes patterns"| node_dashboard
node_owner -->|"shares read-only view"| node_publicdashboard
node_owner -->|"configures workspace"| node_settings
node_settings -.->|"configures AI"| node_aihelpers
node_aihelpers -->|"requests completions"| node_llm
node_interviewer -.->|"uses AI assistance"| node_aihelpers

click node_app "https://github.com/cerne-io/platform/blob/main/src/App.tsx"
click node_auth "https://github.com/cerne-io/platform/blob/main/src/contexts/AuthContext.tsx"
click node_projects "https://github.com/cerne-io/platform/blob/main/src/contexts/ProjectContext.tsx"
click node_api "https://github.com/cerne-io/platform/blob/main/server/index.ts"
click node_database "https://github.com/cerne-io/platform/blob/main/server/db/migrate.ts"
click node_design "https://github.com/cerne-io/platform/blob/main/src/pages/Design.tsx"
click node_designdata "https://github.com/cerne-io/platform/blob/main/src/services/designOutputService.ts"
click node_collect "https://github.com/cerne-io/platform/blob/main/src/pages/Collect.tsx"
click node_formdata "https://github.com/cerne-io/platform/blob/main/src/hooks/queries/useFormDataQuery.ts"
click node_publicform "https://github.com/cerne-io/platform/blob/main/src/services/publicFormService.ts"
click node_submission "https://github.com/cerne-io/platform/blob/main/src/contexts/form/useFormHandlers.ts"
click node_interviewer "https://github.com/cerne-io/platform/blob/main/src/pages/PublicInterviewer.tsx"
click node_explore "https://github.com/cerne-io/platform/blob/main/src/pages/Explore.tsx"
click node_dashboard "https://github.com/cerne-io/platform/blob/main/src/pages/Dashboard.tsx"
click node_publicdashboard "https://github.com/cerne-io/platform/blob/main/src/pages/PublicDashboard.tsx"
click node_settings "https://github.com/cerne-io/platform/blob/main/src/pages/Settings.tsx"
click node_aihelpers "https://github.com/cerne-io/platform/blob/main/src/services/aiAssistantService.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_auth,node_projects,node_api,node_database,node_settings toneBlue
class node_design,node_designdata toneAmber
class node_collect,node_formdata,node_publicform,node_submission,node_interviewer toneMint
class node_explore,node_dashboard,node_publicdashboard toneRose
class node_aihelpers,node_owner,node_participant,node_llm toneIndigo
```

## Components

### Workspace & runtime

- [React application](https://github.com/cerne-io/platform/blob/main/src/App.tsx): `src/App.tsx`
- [Workspace access](https://github.com/cerne-io/platform/blob/main/src/contexts/AuthContext.tsx): `src/contexts/AuthContext.tsx`
- [Project workspace](https://github.com/cerne-io/platform/blob/main/src/contexts/ProjectContext.tsx): `src/contexts/ProjectContext.tsx`
- [HTTP API](https://github.com/cerne-io/platform/blob/main/server/index.ts): `server/index.ts`
- [Embedded PGlite](https://github.com/cerne-io/platform/blob/main/server/db/migrate.ts): `server/db/migrate.ts`
- [Workspace settings](https://github.com/cerne-io/platform/blob/main/src/pages/Settings.tsx): `src/pages/Settings.tsx`

### Instrument design

- [Instrument designer](https://github.com/cerne-io/platform/blob/main/src/pages/Design.tsx): `src/pages/Design.tsx`
- [Instrument configuration](https://github.com/cerne-io/platform/blob/main/src/services/designOutputService.ts): `src/services/designOutputService.ts`

### Story collection

- [Collection setup](https://github.com/cerne-io/platform/blob/main/src/pages/Collect.tsx): `src/pages/Collect.tsx`
- [Form configuration loading](https://github.com/cerne-io/platform/blob/main/src/hooks/queries/useFormDataQuery.ts): `src/hooks/queries/useFormDataQuery.ts`
- [Public form service](https://github.com/cerne-io/platform/blob/main/src/services/publicFormService.ts): `src/services/publicFormService.ts`
- [Story submission](https://github.com/cerne-io/platform/blob/main/src/contexts/form/useFormHandlers.ts): `src/contexts/form/useFormHandlers.ts`
- [AI-assisted interview](https://github.com/cerne-io/platform/blob/main/src/pages/PublicInterviewer.tsx): `src/pages/PublicInterviewer.tsx`

### Exploration & analysis

- [Story exploration](https://github.com/cerne-io/platform/blob/main/src/pages/Explore.tsx): `src/pages/Explore.tsx`
- [Pattern dashboard](https://github.com/cerne-io/platform/blob/main/src/pages/Dashboard.tsx): `src/pages/Dashboard.tsx`
- [Shared dashboard](https://github.com/cerne-io/platform/blob/main/src/pages/PublicDashboard.tsx): `src/pages/PublicDashboard.tsx`

### Optional AI

- [AI services](https://github.com/cerne-io/platform/blob/main/src/services/aiAssistantService.ts): `src/services/aiAssistantService.ts`

### Other components

- **Workspace owner**
- **Story participant**
- **OpenAI-compatible LLM**

## Connections

- Workspace owner → React application: uses (evidence: `README.md`)
- Story participant → React application: opens shared form (evidence: `README.md`)
- React application → Workspace access: provides access state (evidence: `src/App.tsx`)
- React application → Project workspace: provides project state (evidence: `src/App.tsx`)
- React application → HTTP API: uses backend (evidence: `README.md`)
- HTTP API → Embedded PGlite: persists data (evidence: `README.md`)
- Workspace owner → Instrument designer: designs instrument (evidence: `README.md`)
- Instrument designer → Instrument configuration: configures questions
- Instrument configuration → Embedded PGlite: syncs configuration (evidence: `src/services/designOutputService.ts`)
- Workspace owner → Collection setup: prepares collection (evidence: `README.md`)
- Collection setup → Form configuration loading: loads form data
- Form configuration loading → Public form service: fetches public form (evidence: `src/hooks/queries/useFormDataQuery.ts`)
- Story participant → Story submission: submits story (evidence: `README.md`)
- Story submission → HTTP API: sends response
- Story participant → AI-assisted interview: shares narrative (evidence: `README.md`)
- Workspace owner → Story exploration: explores stories (evidence: `README.md`)
- Workspace owner → Pattern dashboard: analyzes patterns (evidence: `README.md`)
- Workspace owner → Shared dashboard: shares read-only view (evidence: `README.md`)
- Workspace owner → Workspace settings: configures workspace (evidence: `README.md`)
- Workspace settings → AI services: configures AI
- AI services → OpenAI-compatible LLM: requests completions (evidence: `README.md`)
- AI-assisted interview → AI services: uses AI assistance