How helixdb/helix-foundry works
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: app.ts API routes · main.tsx Workspace experience · api.ts Web API client · datasets.ts Versioned datasets
Components 27
Workspace UI
- Workspace experience
apps/web/src/main.tsx - Connection screens
apps/web/src/areas/data/connections.tsx - Ontology explorer
apps/web/src/areas/ontology/graph.tsx - Home metrics
apps/web/src/areas/workspace/home.tsx - Analyst experience
apps/web/src/areas/analyst/chat.tsx - Web API client
apps/web/src/api.ts
Data Connections
- Guided setup
apps/api/src/onboarding.ts - Source connectors
apps/api/src/connectors.ts - Source sync
apps/api/src/source-sync.ts - Versioned datasets
apps/api/src/datasets.ts - Source discovery
apps/api/src/source-discovery.ts
Ontology & Workspace
- Ontology proposals
apps/api/src/assistant.ts - Proposal review
apps/web/src/review.tsx - Ontology records
apps/api/src/records.ts - Pipeline builder
apps/api/src/routes/pipelines.ts - Workspace metrics
apps/api/src/metrics.ts
Analysis & Execution
- Question answering
apps/api/src/assistant.ts - SQL execution
services/executor/src/engine.ts - Background jobs
apps/api/src/jobs.ts
API & Persistence
- API routes
apps/api/src/app.ts - Resource store
apps/api/src/store.ts - TypeScript SDK
packages/sdk/src/index.ts
Other components
- Local user
- HelixDB
- DuckDB
- Company data sources
- AI provider
Connections 38
- Local user → Workspace experience: uses
README.md - Workspace experience → Web API client: calls
apps/web/src/api.ts - Workspace experience → Connection screens: routes to
apps/web/src/main.tsx - Workspace experience → Ontology explorer: routes to
apps/web/src/main.tsx - Workspace experience → Home metrics: routes to
apps/web/src/main.tsx - Workspace experience → Analyst experience: routes to
apps/web/src/main.tsx - Connection screens → Web API client: requests
apps/web/src/areas/data/connections.tsx - Ontology explorer → Web API client: requests
apps/web/src/areas/ontology/graph.tsx - Analyst experience → Web API client: requests
- Web API client → API routes: sends API requests
apps/web/src/api.ts - Local user → Guided setup: configures sources
README.md - Guided setup → Source connectors: configures
README.md - Company data sources → Source connectors: provides data
README.md - Source connectors → Source sync: ingests and syncs
README.md - Source sync → Versioned datasets: refreshes snapshots
README.md - Versioned datasets → Source discovery: profiles data
- Versioned datasets → Ontology proposals: informs suggestions
README.md - Local user → Proposal review: reviews changes
README.md - Proposal review → API routes: submits decisions
- API routes → Ontology proposals: routes requests
apps/api/src/app.ts - API routes → Ontology records: routes record access
apps/api/src/app.ts - API routes → Pipeline builder: registers routes
apps/api/src/app.ts - API routes → Resource store: persists resources
apps/api/src/app.ts - Ontology proposals → Resource store: loads and saves proposals
apps/api/src/assistant.ts - Resource store → HelixDB: reads and writes
apps/api/src/store.ts - Local user → Question answering: asks questions
README.md - Question answering → AI provider: requests interpretation
README.md - Question answering → SQL execution: executes SQL
README.md - SQL execution → DuckDB: queries snapshots
services/executor/src/engine.ts - SQL execution → Versioned datasets: reads and materializes
README.md - API routes → Background jobs: queues work
- Background jobs → Source sync: runs scheduled sync
apps/api/src/jobs.ts - Background jobs → Question answering: runs analysis jobs
apps/api/src/jobs.ts - Local user → Workspace metrics: explores metrics
README.md - Home metrics → Workspace metrics: displays metrics
README.md - Local user → Pipeline builder: builds batch pipelines
README.md - Pipeline builder → Resource store: stores pipeline jobs
apps/api/src/routes/pipelines.ts - TypeScript SDK → API routes: accesses developer API
README.md