17 · Repository structure

What lives where. For the product, what works today and the domain model, see 00. Operator runbooks are in the git-ignored private/ folder, not here.

1. Top level

ensemble/
├── apps/                  Runnable applications (§2)
│   ├── hub-web/           Next.js 15 App Router: the Hub UI
│   ├── landing/           Static landing page for ensemblework.com (Next.js export, no API calls)
│   ├── docs/              Static public documentation from docs/ for docs.ensemblework.com (docs/40)
│   ├── hub-api/           Fastify + Prisma API, scheduler, workspace queue, assistant
│   ├── agent-runtime/     Python model adapters and plot service (port 5055)
│   ├── context-bridge/    MCP server for editors and agents (stdio + loopback HTTP); hub-api also serves it at /mcp
│   ├── cli/               The `ensemble` CLI (npm name ensemblework): runner + MCP
│   ├── desktop/           Tauri 2 desktop app (static Hub export + local hub-api sidecar)
│   ├── quick-capture/     Tauri tray app with a global capture shortcut (built with cargo, not a pnpm package)
│   └── skill-forge/       Python package stub (pyproject.toml + empty ensemble_forge/)
├── packages/
│   ├── brand/             Woven Chorus artwork, motion controller, CLI identity (docs/BRAND.md)
│   ├── shared-types/      Zod domain types, settings, modules, plots, connectors, files, shortcuts
│   ├── block-diagrams/    Diagram DSL: parse, layout, SVG, Mermaid (docs/21)
│   ├── ide-theme/         VS Code theme conversion and built-in Code-tab themes
│   └── prompts/           Placeholder (README and package.json only)
├── infra/
│   ├── docker-compose.yml Local Postgres 16 + pgvector and Redis 7, loopback only
│   ├── sql/init.sql       Extensions: vector, pg_trgm, uuid-ossp
│   └── deploy/            Server installs (docs/01 §8): home/ is the home-server install (Docker,
│                          Cloudflare Tunnel, user units, cron watchdog, observability/); the files
│                          beside it are the alternative Ubuntu VM install (Caddy, system units)
├── scripts/               Dev, build, packaging, release and measurement scripts (§3)
├── packaging/             CLI release metadata renderer: Homebrew, Scoop, winget, nfpm, AUR (docs/26 §7)
├── design/                Generated brand outputs: brand/ (mark, icon, loader, gallery) and icons/
│                          (app and UI icons), written by scripts/build-ensemble-brand.mjs
├── docs/                  Current guides; index in docs/README.md
├── .github/               workflows/ (ci, deploy, desktop, cli-release), actions/vercel-deploy,
│                          agents/, skills/ (block-diagrams, ensemble-context), copilot-instructions.md
├── data/import/           Git-ignored local import drop zone
├── eval/, skills/         Empty placeholders (.gitkeep)
├── private/               Git-ignored operator runbooks; never publish secrets
├── release.json           Canonical version for every surface
├── AGENTS.md              Instructions for coding agents (CLAUDE.md and .github/copilot-instructions.md point here)
└── README.md              How to run it

Root files: package.json (repo commands: pnpm dev, db:*, desktop:*, bridge:*, brand:*, version:*), pnpm-workspace.yaml, turbo.json (TypeScript task graph; pnpm dev does not use it), tsconfig.base.json, .env.example (development configuration, 01 §3), LICENSE.md.

2. Applications

apps/hub-web/
├── app/                      login, signup, forgot, reset, verify, link, p/[token] (public links), shared/[id]
├── app/(hub)/                One folder per page: today, board, needs-me, runs, tasks, pages, projects,
│                             context, meetings, files, skills, workspace, code, plots, diagrams, metrics,
│                             recap, routines, marketplace, connect, settings, spaces, shared,
│                             shared-by-me, completed, trash, welcome, start, …
├── components/<surface>/      One folder per surface (board, editor = TipTap, files = viewers per format,
│                             connectors/brands = logos, …); ui.tsx is the kit
├── lib/                      API clients, SSE, auth, access/presence, connect configs, export, files
│                             (PDF/Word conversion, slide reader, export back), plots
└── e2e/                      Playwright scripts run by hand; assistant-tile-catalog.ts runs in `test`

apps/hub-api/src/
├── app.ts, index.ts          HTTP app factory (used by tests) and server entry
├── routes/                   REST + SSE, one module per area
├── assistant/                Hub action layer: loop, registry, tools/, playbooks in skills/*.md (docs/11)
├── bridge/                   Context Bridge resolution and briefs (docs/CONTEXT_BRIDGE.md)
├── connectors/               Google, Microsoft, GitHub, Slack, Linear; OAuth, tokens, ingest, triage, sync,
│                             people sync; mcp/ (remote MCP client); items/ (connected items, docs/31);
│                             meetings/ (meeting-note vendors)
├── imports/                  Importers from other apps, CSV/zip readers, mapping, jobs (docs/27)
├── files/                    File store and caps, extraction worker, pages from files, imports, attachments (docs/32)
├── context/, people/, projects/   Context board order, people views, identities, project links
├── cowork/                   Morning brief, quick capture, nudges, weekly recap, meetings
├── jobs/                     In-process scheduler, retention, claim locks, skill mining, blob sweep
├── workspace/                Agent execution: queue worker, engines/, sandbox/, trust, runner (docs/06)
├── repo/                     Repository reads and mirrors for the Code tab and diagrams
├── remote/, devices/         Remote tasks on a paired computer (docs/25)
├── browser/, capture/        The computer's browser broker and capture service: screenshots and video (docs/25 §10)
├── subscriptions/            Subscription sign-in, detection and assistant turns on paired computers (docs/30)
├── included/                 Included-model catalog, budget and accounting (docs/33)
├── spaces/, sharing/         Spaces (docs/28); sharing policy, gate, links, presence (docs/29)
├── analytics/                Interaction log and Prometheus metrics (docs/07 §1.3)
├── desktop/                  Desktop sidecar entry and helpers
├── runtime/                  In-process model adapters (desktop/CLI) and plot worker
├── plots/, diagrams/         Plot store, service, cache (docs/20); block-diagram revisions
├── pages/                    Page store, history, Markdown, live co-editing
├── marketplace/, layouts/, desk/   Templates, Today layouts, desk entries
├── ensemble/                 @ensemble surfaces, citations, watchers
├── themes/                   Open VSX theme fetch for the Code tab
├── node/                     Ensemble Node: rooms, routing, node turns, approvals, run reports (docs/35)
├── services/                 Shared task and record writes
├── test/                     HTTP harness, route coverage, temporary folders
└── lib/                      auth, undo, ledger, redis, sse, prisma, secrets, blob store, office, …
apps/hub-api/prisma/          schema.prisma, migrations/, seed.ts, demo-branch.ts, demo/
apps/hub-api/scripts/         migrate-deploy.mjs, route-inventory.ts, assistant-eval.ts, secret and deletion-log tools

apps/agent-runtime/ensemble_agent/
├── main.py                   FastAPI app: health, chat/tools (+ stream), search, complete, models, credentials, plots
├── models.py                 Provider adapters (Gemini, OpenAI, Anthropic, Copilot, Mistral, OpenRouter, Ollama)
├── credentials.py, vault.py  Per-user encrypted keys; included.py, hosted_access.py, redact.py beside them
├── orchestrator/, workers/   Planner, executor and task-type plans; not used by workspace assignment
├── tools/, audit/            Tool catalog and guarded writes; ledger writer
└── plots/                    Matplotlib parse/run worker
apps/agent-runtime/tests/     pytest suite

apps/landing/                 app/ (home, four topic pages, /download, /privacy, /terms, robots, sitemap), lib/
                              (site, topics, download.ts install data), public/ (install.sh, install.ps1, llms.txt,
                              IndexNow key), scripts/indexnow.mjs, vercel.json (script headers, ensemblework.app redirects)
                              Privacy/terms own the hosted Google-data and Limited Use disclosures linked by the Google connector.
apps/context-bridge/          src/ (MCP server; exports ./server, ./hub, ./config), clients/ (editor configs), test/, scripts/
apps/docs/                    scripts/build.mjs (tracked docs → out/), src/ (Markdown renderer, browser UI,
                              shared search.js and its types), test/; exports @ensemble/docs/search for the API lookup
apps/cli/                     src/ (commands, tui/, login, sidecar, editors, services), scripts/build.mjs
                              (esbuild → dist/ensemble.mjs), bin/ensemble (POSIX launcher), launcher/ (Go, Windows)
apps/desktop/                 src-tauri/ (Rust shell: sidecar, site, assets, diagnostics), ui/ (offline page)
apps/quick-capture/           src-tauri/ + ui/

3. Scripts

4. Where a change usually belongs

node_modules/, .next/, out/, dist/, .venv/, __pycache__/, *.egg-info/, .turbo/, target/, test caches, docs/screenshots/ and .ensemble/ are outputs or local state. They are git-ignored; do not put source code there.