Monorepo topology¶

Architecture

Telha ships from a single repository with three cooperating language layers (Rust, TypeScript, Python) plus shared client SDKs and protobuf contracts. This page describes the topology as designed and verifies it against the tree as built, including where the two disagree.

Overview & purpose¶

The spec exists because, without a fixed topology, neither human contributors nor AI coding agents can reliably locate code, understand module boundaries, or determine which subsystem owns a given file. Ad-hoc structure leads to circular dependencies, unclear ownership, and CI path-filters that silently stop matching anything. Fixing the tree up front also gives the spec-first harness a known location for .ai/specs/ and a known set of "protected paths" to gate, before any enforcement logic can be written.

The spec is scoped to structure only: it fixes directory layout, toolchain versions, and build conventions. Runtime data models (key layout, version records, and so on) are defined in their own specs and linked from Architecture.

Design¶

The core idea¶

One monorepo, three toolchains, one topology that every PR must conform to. Concretely:

• core-engine (Rust): the tritemporal graph and vector engine, compiled to a single telha binary that serves REST, gRPC, and MCP.
• app-layer (TypeScript): the Telha app, a Next.js application, plus the enterprise packages (field encryption, RBAC) that sit on top of core.
• workers (Python): stateless gRPC clients that parse documents and pull from source systems, with no direct storage access of their own.
• sdk, proto, tooling, and .ai/specs are shared infrastructure that all three layers depend on but none of them own.

Why three layers instead of separate repositories¶

The spec's alternatives-considered section explicitly rejects splitting by language into separate repositories: AI coding agents need full-stack context in one place, and cross-repo context switching loses coherence when a single change (say, a new fact type) touches storage, the app layer, and a worker projection at once. It also rejects Nx in favor of Turborepo for the TypeScript build (simpler config for a Yarn-workspace monorepo, better caching for this shape of project) and Poetry in favor of uv for Python (native pyproject.toml workspace support, faster resolution).

Why spec-first¶

The .ai/specs/ directory is the single source of truth for design decisions and is exposed as an MCP resource, so the running system can be cross-checked against its own design manuals. The spec explicitly rejects keeping specs in a separate repository, because the CI gate (below) needs the spec change to land in the same PR as the code it justifies. This is the mechanism the rest of Architecture leans on: every subsystem page here names the spec it was verified against.

flowchart TB
    subgraph specs["Spec-first source of truth"]
      TEMPLATE[".ai/specs/_TEMPLATE.md<br/>14-section manual"]
      COREVSPEC["core-engine/ specs"]
      APPSPEC["app-layer/ specs"]
      INTSPEC["integration/ specs"]
    end

    subgraph build["Three toolchains, one repo"]
      direction LR
      subgraph coreeng["core-engine, Rust"]
        CARGO["Cargo workspace<br/>rust-toolchain.toml"]
      end
      subgraph applayer["app-layer, TypeScript"]
        YARN["Yarn workspaces<br/>+ Turborepo"]
      end
      subgraph wk["workers, Python"]
        UV["uv workspace<br/>pyproject.toml"]
      end
    end

    subgraph shared["Shared infrastructure"]
      PROTO["proto/ (buf-linted)"]
      SDK["sdk/typescript + sdk/python"]
      TOOL["tooling/spec-lint, tooling/packaging"]
    end

    specs -.governs.-> build
    PROTO --> coreeng
    PROTO --> applayer
    PROTO --> wk
    coreeng -->|generates client types| SDK
    TOOL -->|CI gate| specs

Directory topology¶

The tree below is the spec's §4 Architecture section, verified directory by directory against the actual repository at the working tree root.

/telha-v2
  ├── /core-engine                 Rust binary (telha-core / telha)
  │     ├── /src/{api,backup,clarify,erasure,graph,grpc,ingest,
  │     │         jobs,llm,mcp,model,planner,query,retention,
  │     │         schema,storage,temporal,vector,verify,watch}
  │     ├── Cargo.toml / Cargo.lock
  │     ├── build.rs               protobuf codegen
  │     ├── rust-toolchain.toml
  │     ├── benches/, fuzz/, tests/, openapi/
  │     └── run-*.cmd               local gate/lint/test scripts
  ├── /app-layer                   TypeScript (Yarn workspaces + Turborepo)
  │     ├── /apps/mercato          Next.js web application
  │     ├── /packages/{core,enterprise,ai-assistant,clarify-bot,
  │     │              contracts,ui,queue,events,search}
  │     ├── turbo.json / package.json / .yarnrc.yml
  ├── /workers                     Python (uv workspace)
  │     ├── /workers_common
  │     ├── /docling_worker, /firecrawl_worker, /code_worker,
  │     │   /tabular_worker, /email_worker
  │     ├── /entra_connector, /sharepoint_connector,
  │     │   /exchange_connector, /slack_connector,
  │     │   /salesforce_connector
  │     └── pyproject.toml
  ├── /sdk
  │     ├── /typescript            @telha/sdk (dual transport: REST + gRPC)
  │     └── /python                telha-sdk (REST, pydantic)
  ├── /proto
  │     ├── buf.yaml                buf v2, STANDARD lint, FILE breaking-check
  │     ├── /telha/v1               app_layer.proto, worker.proto
  │     └── /mcp                    tools.json
  ├── /tooling
  │     ├── /spec-lint              spec-lint.mjs (Node, zero-dep)
  │     └── /packaging              Windows zip packaging, sample config, smoke probe
  ├── /.ai/specs
  │     ├── _TEMPLATE.md
  │     ├── README.md
  │     ├── /core-engine, /app-layer, /integration
  ├── /.github/workflows           CI pipelines (spec-gate, rust, typescript,
  │                                 python, rust-bench, rust-fuzz, eval-nightly,
  │                                 release-build)
  ├── /deploy                      systemd unit + env template for the binary
  ├── /eval                        standalone Rust workspace for offline eval runs
  └── /docs                        this documentation site (MkDocs + Material)

Core engine module map¶

core-engine/src/ is organized by subsystem, one directory per concern. Each maps to one or more architecture pages:

App layer package map¶

Workers map¶

workers/ holds both format workers (parse documents into facts) and source connectors (pull from external systems), all as independent uv workspace members sharing workers_common:

Format workers correspond to the projection specs (docling-projection, web-ingestion, tabular-projection, code-projection, email-projection) and connectors correspond to the connector-framework and identity-connector specs; see Format workers and Connector framework.

Toolchains per layer¶

Build interface, unchanged from the spec and confirmed runnable from a clean clone:

# Rust core engine
cd core-engine && cargo build

# TypeScript app layer
cd app-layer && yarn install && yarn turbo build

# Python workers
cd workers && uv sync

# Spec lint
node tooling/spec-lint/spec-lint.mjs .ai/specs

All three toolchains succeeding from a clean clone is the spec's Phase 0 acceptance gate (§12 Success Metrics).

The spec-first CI gate¶

The gate is .github/workflows/spec-gate.yml, and it runs three separate jobs on every pull request (opened, synchronize, reopened, labeled, unlabeled):

flowchart LR
    PR["Pull request"] --> LINT["Job: lint\nspec-lint.mjs over .ai/specs/"]
    PR --> GATE["Job: gate\ndesign-change requires spec"]
    PR --> ITER["Job: iterator-gate\nF1 tenant isolation"]

    LINT -->|exit 0| PASS1["pass"]
    LINT -->|violation| FAIL1["fail: RULE-01..11 violation"]

    GATE --> DIFF["diff base...HEAD\nchanged.txt"]
    DIFF --> PROTECTED{"touches a\nprotected path?"}
    PROTECTED -->|no| PASS2["pass"]
    PROTECTED -->|yes| SPECCHANGE{"spec file\nchanged too?"}
    SPECCHANGE -->|yes| PASS3["pass"]
    SPECCHANGE -->|no| LABEL{"'no-spec-needed'\nlabel present?"}
    LABEL -->|yes| WARN["warn + pass\n(needs PR justification)"]
    LABEL -->|no| FAIL2["fail: add spec as\nfirst commit"]

    ITER --> GREP["grep .raw_iterator( / .iterator( /\n.prefix_iterator( in core-engine/src/"]
    GREP --> OUTSIDE{"match outside\nsrc/storage/?"}
    OUTSIDE -->|yes| FAIL3["fail: F1 violation"]
    OUTSIDE -->|no| PASS4["pass"]

Job 1: lint¶

Runs node tooling/spec-lint/spec-lint.mjs .ai/specs on Node 22, checking every spec file in the tree against eleven rules (RULE-01 through RULE-11), enforced by tooling/spec-lint/spec-lint.mjs:

The 14 canonical sections, in required order, are: Overview, Problem Statement, Proposed Solution, Architecture, Data Models, API Contracts, UI/UX, Configuration, Alternatives Considered, Implementation Approach, Migration Path, Success Metrics, Open Questions, Changelog. This spec you are reading right now is itself linted against that same template.

Job 2: gate (design-change requires spec)¶

This job computes the changed-files diff against the PR's base branch, then checks whether any changed path matches the protected-path regex baked into the workflow:

^(core-engine/src/(storage|graph|temporal|vector|query|schema|planner|jobs)/|
  proto/|
  workers/(docling_worker|firecrawl_worker|code_worker|tabular_worker|email_worker)/|
  app-layer/packages/enterprise/field-crypto/)

If a protected path is touched:

• The PR passes if a file under .ai/specs/{core-engine,app-layer,integration}/ was also changed in the same diff.
• Otherwise, the PR passes with a warning if it carries the no-spec-needed label (intended for typo fixes inside protected paths; the label requires a justification comment, and changing the protected-path list itself requires CODEOWNERS review of the workflow file).
• Otherwise, the job fails and instructs the author to add the spec as the first commit of the PR.

Job 3: iterator-gate (F1 tenant isolation)¶

A separate, narrower structural gate: it greps core-engine/src/ for .raw_iterator(, .iterator(, and .prefix_iterator( calls and fails if any match falls outside core-engine/src/storage/. The intent is that no call site anywhere in the engine can construct an unbounded RocksDB iterator that bypasses the KeyCodec/ScanRange layer; tenant isolation is enforced structurally rather than by convention. This is not one of the three jobs described in the spec's prose, but it is deployed in the same workflow file.

Lint can also be run locally, either over the whole tree or a single file:

node tooling/spec-lint/spec-lint.mjs                 # whole tree
node tooling/spec-lint/spec-lint.mjs --file <path>   # one file

As-built notes¶

The spec's own Changelog (§14) has a single entry, "2026-07-02, v0.1: initial topology spec documenting PR-001 decisions," and records no deviations. The items below are differences found by comparing the spec's prose directly against the repository as it exists today; they are not recorded in the spec's changelog itself.

None of these are functional defects: every added directory has its own normative spec, and the core three-layer, three-toolchain shape the spec mandates is intact. They are documented here because this page's job is to describe the system as built, not just as designed, per the spec-first convention that governs the rest of this section.

Related¶

• Architecture overview, how the spec-first convention applies across all subsystems.
• Storage engine & key layout, what lives under core-engine/src/storage/.
• The version record model, what lives under core-engine/src/model/ and core-engine/src/temporal/.
• gRPC contracts, the proto/telha/v1/ contracts and how app-layer and workers call core.
• Connector framework, the workers/*_connector members.
• Format workers, the workers/*_worker members.
• Field encryption, app-layer/packages/enterprise/src/field-crypto/.
• Eval harness, the standalone /eval Rust workspace.
• Core concepts, the product ideas this engine implements.
• Developers › Query language and REST API, the surfaces core-engine/src/api/ and core-engine/src/query/ expose.