# helixdb/helix-foundry architecture

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

- Interactive diagram: https://gitdiagram.com/helixdb/helix-foundry
- Repository: https://github.com/helixdb/helix-foundry

## Overview

Helix Foundry is a local-first data workspace that connects company data, proposes a shared ontology, and lets users explore records, metrics, and AI-backed answers. The main workflow is guided setup, source connection and sync, ontology review, then workspace exploration or Analyst queries. The graph also preserves documented pipelines, versioned Parquet datasets, developer access, and external integrations. README statements support several subsystem links; sampled code confirms API routing, proposal drafting, shared schemas, persistence, and DuckDB execution. Unsampled implementations are represented only at paths established by the tree or index.

Main entry points: [`apps/api/src/app.ts`](https://github.com/helixdb/helix-foundry/blob/main/apps/api/src/app.ts) (API routes), [`apps/web/src/main.tsx`](https://github.com/helixdb/helix-foundry/blob/main/apps/web/src/main.tsx) (Workspace experience), [`apps/web/src/api.ts`](https://github.com/helixdb/helix-foundry/blob/main/apps/web/src/api.ts) (Web API client), [`apps/api/src/datasets.ts`](https://github.com/helixdb/helix-foundry/blob/main/apps/api/src/datasets.ts) (Versioned datasets)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Workspace UI"]
  node_webui["Workspace experience<br/>[main.tsx]"]
  node_dataui["Connection screens<br/>[connections.tsx]"]
  node_ontologyui["Ontology explorer<br/>[graph.tsx]"]
  node_homeui["Home metrics<br/>[home.tsx]"]
  node_analystui["Analyst experience<br/>[chat.tsx]"]
  node_webapi["Web API client<br/>[api.ts]"]
end

subgraph group_connect["Data Connections"]
  node_onboarding["Guided setup<br/>[onboarding.ts]"]
  node_connectors["Source connectors<br/>[connectors.ts]"]
  node_sync["Source sync<br/>[source-sync.ts]"]
  node_datasets["Versioned datasets<br/>[datasets.ts]"]
  node_discovery["Source discovery"]
end

subgraph group_model["Ontology &amp; Workspace"]
  node_ontology["Ontology proposals<br/>[assistant.ts]"]
  node_review["Proposal review<br/>[review.tsx]"]
  node_records["Ontology records<br/>[records.ts]"]
  node_pipelines["Pipeline builder<br/>[pipelines.ts]"]
  node_metrics["Workspace metrics<br/>[metrics.ts]"]
end

subgraph group_query["Analysis &amp; Execution"]
  node_analyst["Question answering<br/>[assistant.ts]"]
  node_executor["SQL execution<br/>[engine.ts]"]
  node_jobs["Background jobs<br/>[jobs.ts]"]
end

subgraph group_platform["API &amp; Persistence"]
  node_api["API routes<br/>[app.ts]"]
  node_store[("Resource store<br/>[store.ts]")]
  node_sdk["TypeScript SDK<br/>[index.ts]"]
end

node_person(("Local user"))
node_helix[("HelixDB")]
node_duckdb[("DuckDB")]
node_sources[("Company data sources")]
node_ai{{"AI provider"}}

node_person -->|"uses"| node_webui
node_webui -->|"calls"| node_webapi
node_webui -->|"routes to"| node_dataui
node_webui -->|"routes to"| node_ontologyui
node_webui -->|"routes to"| node_homeui
node_webui -->|"routes to"| node_analystui
node_dataui -->|"requests"| node_webapi
node_ontologyui -->|"requests"| node_webapi
node_analystui -->|"requests"| node_webapi
node_webapi -->|"sends API requests"| node_api
node_person -->|"configures sources"| node_onboarding
node_onboarding -->|"configures"| node_connectors
node_sources -->|"provides data"| node_connectors
node_connectors -->|"ingests and syncs"| node_sync
node_sync -->|"refreshes snapshots"| node_datasets
node_datasets -.->|"profiles data"| node_discovery
node_datasets -->|"informs suggestions"| node_ontology
node_person -->|"reviews changes"| node_review
node_review -.->|"submits decisions"| node_api
node_api -->|"routes requests"| node_ontology
node_api -->|"routes record access"| node_records
node_api -->|"registers routes"| node_pipelines
node_api -->|"persists resources"| node_store
node_ontology -->|"loads and saves proposals"| node_store
node_store -->|"reads and writes"| node_helix
node_person -->|"asks questions"| node_analyst
node_analyst -->|"requests interpretation"| node_ai
node_analyst -->|"executes SQL"| node_executor
node_executor -->|"queries snapshots"| node_duckdb
node_executor -->|"reads and materializes"| node_datasets
node_api -.->|"queues work"| node_jobs
node_jobs -->|"runs scheduled sync"| node_sync
node_jobs -->|"runs analysis jobs"| node_analyst
node_person -->|"explores metrics"| node_metrics
node_homeui -->|"displays metrics"| node_metrics
node_person -->|"builds batch pipelines"| node_pipelines
node_pipelines -->|"stores pipeline jobs"| node_store
node_sdk -->|"accesses developer API"| node_api

click node_webui "https://github.com/helixdb/helix-foundry/blob/main/apps/web/src/main.tsx"
click node_dataui "https://github.com/helixdb/helix-foundry/blob/main/apps/web/src/areas/data/connections.tsx"
click node_ontologyui "https://github.com/helixdb/helix-foundry/blob/main/apps/web/src/areas/ontology/graph.tsx"
click node_homeui "https://github.com/helixdb/helix-foundry/blob/main/apps/web/src/areas/workspace/home.tsx"
click node_analystui "https://github.com/helixdb/helix-foundry/blob/main/apps/web/src/areas/analyst/chat.tsx"
click node_webapi "https://github.com/helixdb/helix-foundry/blob/main/apps/web/src/api.ts"
click node_onboarding "https://github.com/helixdb/helix-foundry/blob/main/apps/api/src/onboarding.ts"
click node_connectors "https://github.com/helixdb/helix-foundry/blob/main/apps/api/src/connectors.ts"
click node_sync "https://github.com/helixdb/helix-foundry/blob/main/apps/api/src/source-sync.ts"
click node_datasets "https://github.com/helixdb/helix-foundry/blob/main/apps/api/src/datasets.ts"
click node_discovery "https://github.com/helixdb/helix-foundry/blob/main/apps/api/src/source-discovery.ts"
click node_ontology "https://github.com/helixdb/helix-foundry/blob/main/apps/api/src/assistant.ts"
click node_review "https://github.com/helixdb/helix-foundry/blob/main/apps/web/src/review.tsx"
click node_records "https://github.com/helixdb/helix-foundry/blob/main/apps/api/src/records.ts"
click node_pipelines "https://github.com/helixdb/helix-foundry/blob/main/apps/api/src/routes/pipelines.ts"
click node_metrics "https://github.com/helixdb/helix-foundry/blob/main/apps/api/src/metrics.ts"
click node_analyst "https://github.com/helixdb/helix-foundry/blob/main/apps/api/src/assistant.ts"
click node_executor "https://github.com/helixdb/helix-foundry/blob/main/services/executor/src/engine.ts"
click node_jobs "https://github.com/helixdb/helix-foundry/blob/main/apps/api/src/jobs.ts"
click node_api "https://github.com/helixdb/helix-foundry/blob/main/apps/api/src/app.ts"
click node_store "https://github.com/helixdb/helix-foundry/blob/main/apps/api/src/store.ts"
click node_sdk "https://github.com/helixdb/helix-foundry/blob/main/packages/sdk/src/index.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_webui,node_dataui,node_ontologyui,node_homeui,node_analystui,node_webapi,node_person toneBlue
class node_onboarding,node_connectors,node_sync,node_datasets,node_discovery,node_helix,node_duckdb,node_sources toneAmber
class node_ontology,node_review,node_records,node_pipelines,node_metrics toneMint
class node_analyst,node_executor,node_jobs toneRose
class node_api,node_store,node_sdk,node_ai toneIndigo
```

## Components

### Workspace UI

- [Workspace experience](https://github.com/helixdb/helix-foundry/blob/main/apps/web/src/main.tsx): `apps/web/src/main.tsx`
- [Connection screens](https://github.com/helixdb/helix-foundry/blob/main/apps/web/src/areas/data/connections.tsx): `apps/web/src/areas/data/connections.tsx`
- [Ontology explorer](https://github.com/helixdb/helix-foundry/blob/main/apps/web/src/areas/ontology/graph.tsx): `apps/web/src/areas/ontology/graph.tsx`
- [Home metrics](https://github.com/helixdb/helix-foundry/blob/main/apps/web/src/areas/workspace/home.tsx): `apps/web/src/areas/workspace/home.tsx`
- [Analyst experience](https://github.com/helixdb/helix-foundry/blob/main/apps/web/src/areas/analyst/chat.tsx): `apps/web/src/areas/analyst/chat.tsx`
- [Web API client](https://github.com/helixdb/helix-foundry/blob/main/apps/web/src/api.ts): `apps/web/src/api.ts`

### Data Connections

- [Guided setup](https://github.com/helixdb/helix-foundry/blob/main/apps/api/src/onboarding.ts): `apps/api/src/onboarding.ts`
- [Source connectors](https://github.com/helixdb/helix-foundry/blob/main/apps/api/src/connectors.ts): `apps/api/src/connectors.ts`
- [Source sync](https://github.com/helixdb/helix-foundry/blob/main/apps/api/src/source-sync.ts): `apps/api/src/source-sync.ts`
- [Versioned datasets](https://github.com/helixdb/helix-foundry/blob/main/apps/api/src/datasets.ts): `apps/api/src/datasets.ts`
- [Source discovery](https://github.com/helixdb/helix-foundry/blob/main/apps/api/src/source-discovery.ts): `apps/api/src/source-discovery.ts`

### Ontology & Workspace

- [Ontology proposals](https://github.com/helixdb/helix-foundry/blob/main/apps/api/src/assistant.ts): `apps/api/src/assistant.ts`
- [Proposal review](https://github.com/helixdb/helix-foundry/blob/main/apps/web/src/review.tsx): `apps/web/src/review.tsx`
- [Ontology records](https://github.com/helixdb/helix-foundry/blob/main/apps/api/src/records.ts): `apps/api/src/records.ts`
- [Pipeline builder](https://github.com/helixdb/helix-foundry/blob/main/apps/api/src/routes/pipelines.ts): `apps/api/src/routes/pipelines.ts`
- [Workspace metrics](https://github.com/helixdb/helix-foundry/blob/main/apps/api/src/metrics.ts): `apps/api/src/metrics.ts`

### Analysis & Execution

- [Question answering](https://github.com/helixdb/helix-foundry/blob/main/apps/api/src/assistant.ts): `apps/api/src/assistant.ts`
- [SQL execution](https://github.com/helixdb/helix-foundry/blob/main/services/executor/src/engine.ts): `services/executor/src/engine.ts`
- [Background jobs](https://github.com/helixdb/helix-foundry/blob/main/apps/api/src/jobs.ts): `apps/api/src/jobs.ts`

### API & Persistence

- [API routes](https://github.com/helixdb/helix-foundry/blob/main/apps/api/src/app.ts): `apps/api/src/app.ts`
- [Resource store](https://github.com/helixdb/helix-foundry/blob/main/apps/api/src/store.ts): `apps/api/src/store.ts`
- [TypeScript SDK](https://github.com/helixdb/helix-foundry/blob/main/packages/sdk/src/index.ts): `packages/sdk/src/index.ts`

### Other components

- **Local user**
- **HelixDB**
- **DuckDB**
- **Company data sources**
- **AI provider**

## Connections

- Local user → Workspace experience: uses (evidence: `README.md`)
- Workspace experience → Web API client: calls (evidence: `apps/web/src/api.ts`)
- Workspace experience → Connection screens: routes to (evidence: `apps/web/src/main.tsx`)
- Workspace experience → Ontology explorer: routes to (evidence: `apps/web/src/main.tsx`)
- Workspace experience → Home metrics: routes to (evidence: `apps/web/src/main.tsx`)
- Workspace experience → Analyst experience: routes to (evidence: `apps/web/src/main.tsx`)
- Connection screens → Web API client: requests (evidence: `apps/web/src/areas/data/connections.tsx`)
- Ontology explorer → Web API client: requests (evidence: `apps/web/src/areas/ontology/graph.tsx`)
- Analyst experience → Web API client: requests
- Web API client → API routes: sends API requests (evidence: `apps/web/src/api.ts`)
- Local user → Guided setup: configures sources (evidence: `README.md`)
- Guided setup → Source connectors: configures (evidence: `README.md`)
- Company data sources → Source connectors: provides data (evidence: `README.md`)
- Source connectors → Source sync: ingests and syncs (evidence: `README.md`)
- Source sync → Versioned datasets: refreshes snapshots (evidence: `README.md`)
- Versioned datasets → Source discovery: profiles data
- Versioned datasets → Ontology proposals: informs suggestions (evidence: `README.md`)
- Local user → Proposal review: reviews changes (evidence: `README.md`)
- Proposal review → API routes: submits decisions
- API routes → Ontology proposals: routes requests (evidence: `apps/api/src/app.ts`)
- API routes → Ontology records: routes record access (evidence: `apps/api/src/app.ts`)
- API routes → Pipeline builder: registers routes (evidence: `apps/api/src/app.ts`)
- API routes → Resource store: persists resources (evidence: `apps/api/src/app.ts`)
- Ontology proposals → Resource store: loads and saves proposals (evidence: `apps/api/src/assistant.ts`)
- Resource store → HelixDB: reads and writes (evidence: `apps/api/src/store.ts`)
- Local user → Question answering: asks questions (evidence: `README.md`)
- Question answering → AI provider: requests interpretation (evidence: `README.md`)
- Question answering → SQL execution: executes SQL (evidence: `README.md`)
- SQL execution → DuckDB: queries snapshots (evidence: `services/executor/src/engine.ts`)
- SQL execution → Versioned datasets: reads and materializes (evidence: `README.md`)
- API routes → Background jobs: queues work
- Background jobs → Source sync: runs scheduled sync (evidence: `apps/api/src/jobs.ts`)
- Background jobs → Question answering: runs analysis jobs (evidence: `apps/api/src/jobs.ts`)
- Local user → Workspace metrics: explores metrics (evidence: `README.md`)
- Home metrics → Workspace metrics: displays metrics (evidence: `README.md`)
- Local user → Pipeline builder: builds batch pipelines (evidence: `README.md`)
- Pipeline builder → Resource store: stores pipeline jobs (evidence: `apps/api/src/routes/pipelines.ts`)
- TypeScript SDK → API routes: accesses developer API (evidence: `README.md`)