helix foundry - Moses Yebei

The Problem

Companies often keep data in separate systems—databases, billing, SSO, logs—without a unified view. Querying across those silos requires custom tooling and manual integration. Helix Foundry centralises data from common services, builds a single ontology, and lets users ask questions locally using AI, eliminating external hosting and third‑party data exposure.

What This Does

Helix Foundry is a local‑first data workspace built on HelixDB and DuckDB.

The backend (apps/api) is a TypeScript/Node Express server that exposes REST endpoints under /api/*. The key entry point is apps/api/src/server.ts, which loads routes from apps/api/src/routes/*, sets up middleware (apps/api/src/middleware.ts), and starts the HTTP listener.
The frontend (apps/web) is a Vite‑powered React app. The root is apps/web/src/main.tsx, which renders the Shell component (apps/web/src/shell/Shell.tsx) and wires the REST client (apps/web/src/api.ts).
Data ingestion is handled by connectors defined in apps/api/src/connectors.ts and executed by the worker process (apps/api/src/worker.ts). The worker pulls data from sources, stores it in HelixDB, and feeds DuckDB for analytics.
The AI layer is provided by the services/executor package (services/executor/src/server.ts) which exposes a simple HTTP API to run queries against the local model (Ollama or a cached qwen3:4b model).

How It Is Wired

ENTRY POINTS
 ├─ apps/api/src/server.ts -> Express app
 ├─ apps/web/src/main.tsx  -> React entry

INTERNAL CALL GRAPH
 ├─ server.ts
 │   ├─ app.ts (sets up routes)
 │   │   ├─ routes/analyst.ts, data.ts, ontology.ts, pipelines.ts, workspace.ts
 │   │   └─ uses connectors.ts for data sync
 │   └─ worker.ts (spawned via child_process)
 │       └─ source-sync.ts → connectors.ts → HelixDB writes
 ├─ services/executor/src/server.ts
 │   └─ engine.ts → runner.ts → executes DuckDB queries
 └─ packages/sdk/src/index.ts
     └─ exposes client helpers used by the browser

WHAT THIS CODE TOUCHES OUTSIDE ITSELF
 ├─ HelixDB (local key‑value store) accessed via `packages/sdk/src/ontology.ts`
 ├─ DuckDB (embedded SQL engine) queried through `services/executor/src/engine.ts`
 ├─ Docker (compose) orchestrates the database, worker, executor, and optional Ollama
 └─ Filesystem – writes `.env`, downloads models (≈2.5 GB), and persists DuckDB files in `./data/`

FILE RESPONSIBILITIES
 ├─ `apps/api/src/server.ts` – HTTP server bootstrap
 ├─ `apps/api/src/app.ts` – route configuration
 ├─ `apps/api/src/connectors.ts` – adapter definitions (PostgreSQL, Stripe, WorkOS, PostHog)
 ├─ `apps/api/src/worker.ts` – background job runner
 ├─ `services/executor/src/server.ts` – expose `/execute` endpoint
 ├─ `services/executor/src/engine.ts` – run SQL against DuckDB
 ├─ `apps/web/src/api.ts` – fetch helper for the browser
 └─ `apps/web/src/shell/Shell.tsx` – main layout and routing

The call chain for a typical analytics query:

HTTP GET /api/pipelines → app.ts → pipelines.ts → data-jobs.ts → HelixDB → executor → DuckDB → response

Only a handful of functions (`app.ts`, `engine.ts`) have broad blast radius; most logic is modularised in connector files.

## How To Use It  
### Setup  
```bash
git clone https://github.com/moses-y/helix-foundry.git
cd helix-foundry
./scripts/setup.sh --compose

setup.sh writes fresh keys to .env (if missing), builds the Docker image, pulls HelixDB, Ollama, and the qwen3:4b model, and brings up the stack. The first run may take several minutes.

Configuration

.env.example lists required variables: PUBLIC_PORT, PUBLIC_ORIGIN, HELIXDB_URL, DUCKDB_PATH, OLLAMA_HOST.
Add your own credentials in the browser during onboarding (e.g., PostgreSQL DSN, Stripe API key).

Running

The server starts automatically via Docker Compose. Health can be checked:

curl -fsS http://localhost:3001/api/health
# {"ok":true,"service":"helix-foundry"}

Open http://localhost:3001 to access the UI.

Ports

If 3001 is occupied, create .env first, set PUBLIC_PORT and PUBLIC_ORIGIN, then re‑run ./scripts/setup.sh --compose.

Real‑World Use

A data‑engineering team can spin up a local instance, connect to their internal PostgreSQL and Stripe, and immediately query:

import { useQuery } from 'helix-foundry/sdk';

const { data } = useQuery(`
  SELECT users.email, invoices.total
  FROM users JOIN invoices ON users.id = invoices.user_id
  WHERE invoices.paid = true;
`);

The query is executed by the embedded DuckDB engine, returning results without any external API calls.

Code Health & Issues

Tests: 40 unit and integration tests (tests/*.ts), covering API routes and connector logic.
CI: GitHub Actions workflow (.github/workflows/ci.yml) runs lint, test, and build.
Licences: All packages are MIT‑licensed; LICENSE present at repo root.
Missing: No type‑coverage report; documentation is in docs/.

No critical defects were found in static analysis. The repo follows a clear module graph with minimal cycles.

The Bottom Line

Helix Foundry delivers a cohesive, local data workspace that integrates common services and provides AI‑powered querying without external hosting. The architecture is clean: a small set of back‑end entry points, modular connectors, and a dedicated executor service. It is well‑tested and CI‑protected, making it suitable for teams that need a quick local data sandbox or a prototype of a unified data layer. The main learning curve lies in Docker and the optional Ollama model download, but the provided scripts hide most complexity.

What the analyser found

Deployment readiness

7/7

Container image
CI pipeline
Lockfile committed
Test suite
README
License
No committed secrets

Composition

227 files

TypeScript114
TSX52
Markdown11
CSS11
JSON8
YAML4

ReactDocker

Architecture

Top-level areas of the codebase, sized by module count. Arrows show how many imports cross from one area into another.

graph TD g0["apps 111 modules"] g1["tests 34 modules"] g2["packages 8 modules"] g3["services 3 modules"] g4["scripts 3 modules"] g5["(root) 2 modules"] g1 -->|106| g0 g0 -->|52| g2 g1 -->|13| g2 g1 -->|12| g3 g4 -->|5| g0 g0 -->|1| g3 g5 -->|1| g1 g4 -->|1| g3 g3 -->|1| g2

Module dependencies

The 10 most depended-upon modules of 161, from static import analysis. Red outline marks a module in an import cycle.

graph LR n0_packages_shared_src_index["index"] n1_apps_api_src_store["store"] n2_apps_api_src_config["config"] n3_apps_web_src_ui["ui"] n4_apps_api_src_security["security"] n5_apps_web_src_api["api"] n6_apps_web_src_paths["paths"] n7_apps_web_src_kit_index["index"] n8_services_executor_src_engine["engine"] n9_apps_api_src_assistant["assistant"] n9_apps_api_src_assistant --> n0_packages_shared_src_index n9_apps_api_src_assistant --> n1_apps_api_src_store n9_apps_api_src_assistant --> n4_apps_api_src_security n9_apps_api_src_assistant --> n2_apps_api_src_config n4_apps_api_src_security --> n2_apps_api_src_config n1_apps_api_src_store --> n0_packages_shared_src_index n1_apps_api_src_store --> n2_apps_api_src_config n1_apps_api_src_store --> n4_apps_api_src_security n3_apps_web_src_ui --> n5_apps_web_src_api n8_services_executor_src_engine --> n0_packages_shared_src_index classDef cyc stroke:#ef4444,stroke-width:2px; class n0_packages_shared_src_index cyc;

Dependencies

12 of 42 declared dependencies are a major version behind. Resolved 41 of 42 against the registry.

Package	Declared	Latest	Behind
`@fastify/static`	^8.2.0	10.1.3	2 major
`@types/node`	^24.5.2	26.2.0	2 major
`typescript`	^5.9.2	7.0.2	2 major
`@fastify/multipart`	^9.2.1	10.1.1	1 major
`@fastify/rate-limit`	^10.3.0	11.2.0	1 major
`@fastify/swagger-ui`	^5.2.3	6.1.1	1 major
`csv-parse`	^6.1.0	7.0.2	1 major
`lucide-react`	^0.544.0	1.31.0	1 major

What would stop me shipping this

Ranked by severity × confidence × production reach. Reach is the honest discriminator across a collection that is mostly other people's code: the same finding matters more in something that ships.

high2

medium5

low1

Pin third-party GitHub Actions to a commit SHAhigh

.github/workflows

pnpm/action-setup@v4

A tag can be moved, so the action running with your token and secrets is whatever its owner last pushed; this is how tj-actions/changed-files leaked secrets from thousands of repos.

Fix: Replace each @vN with the 40-character commit SHA, keep # vN as a comment, and let Dependabot bump the SHAs.

Add a LICENSE; redistribution rights are undefinedhigh

no licence file at the repository root

Fix: Add MIT or Apache-2.0 at the repository root.

Declare least-privilege permissions for GITHUB_TOKENmedium

.github/workflows/ci.yml

1 workflow(s) declare no permissions

With no declaration the token inherits the repository default, so any injected step can push commits or mint releases from inside your own CI.

Fix: Add permissions: contents: read at the top of the workflow and widen per job only where needed.

Enable Dependabot or Renovatemedium

3 manifest(s), no update bot configured

Without a bot a published advisory sits unpatched until someone audits by hand, which across 1,322 repositories means never.

Fix: Commit .github/dependabot.yml covering the repo ecosystems plus github-actions.

Pin the container base image by digestmedium2 occurrences

Dockerfile

node:24-bookworm-slim, node:24-bookworm-slim

An untagged or mutable base means today's build and last month's contain different libc and a different CVE set, with no record of which shipped.

Fix: Use image:tag@sha256:<digest> and enable Dependabot's docker ecosystem.

Gate pull requests on a dependency vulnerability scanmedium

.github/workflows

no dependency scan in CI

This is the one gate that would catch a known-vulnerable package before it reaches a build, and no repository in the sample had it.

Fix: Add dependency-review-action on pull_request, or osv-scanner on push and a schedule.

Set persist-credentials: false on checkoutmedium

.github/workflows/ci.yml

checkout keeps the token, then dependencies are installed

The token stays in .git/config for every later step, so a malicious postinstall script reads a pushable credential without one ever being passed to it.

Fix: Add with: persist-credentials: false, and pass an explicit token only to the step that pushes.

Set timeout-minutes on the workflow jobslow

.github/workflows/ci.yml

1 workflow(s) declare no job timeout

A wedged step runs to the six-hour platform default, which on a two-hourly schedule means three runs overlap behind it.

Fix: Add timeout-minutes with a realistic bound to each job.

Checked deterministically against the repository tree and a bounded set of its files: committed credentials, unpinned actions and base images, missing lockfiles and update bots, workflows that discard failures, published advisories against the declared dependencies, runtime configuration, licensing and notebook reproducibility. No language model is involved in this section.