Spec: Monorepo Topology and Toolchain¶

File: .ai/specs/core-engine/2026-07-02-monorepo-topology.md Status: Approved Owners: shared Related: PR-001, PRD §3.1

1. Overview¶

This spec defines the canonical directory structure, toolchain versions, and build conventions for the Telha unified monorepo. It establishes the three-layer architecture (Rust core engine, TypeScript app layer, Python workers) and the spec-first enforcement mechanism that governs all subsequent changes. Every PR in the project must conform to the topology defined here.

2. Problem Statement¶

Without a fixed topology, AI coding agents and human contributors cannot reliably locate code, understand module boundaries, or determine which subsystem owns a given file. Ad-hoc directory structures lead to circular dependencies, unclear ownership, and broken CI path-filters. The spec-first harness requires a known location for specs and protected paths before any enforcement can work.

3. Proposed Solution¶

The repository MUST follow the exact directory tree from PRD §3.1. Three toolchains coexist in one repository: Rust (Cargo workspace), TypeScript (Yarn workspaces + Turborepo), and Python (uv workspace). CI pipelines are path-filtered per language. The spec-first harness (linter + CI gate) is operational from day one. The .ai/specs/ directory is the single source of truth for design decisions, exposed as an MCP resource.

4. Architecture¶

/telha-v2
  ├── /core-engine                Rust binary (telha-core)
  │     ├── /src/{storage,graph,temporal,vector,query,schema,api,grpc,mcp,planner,jobs}
  │     ├── Cargo.toml
  │     ├── build.rs              protobuf codegen (PR-025)
  │     └── rust-toolchain.toml
  ├── /app-layer                  TypeScript (Yarn workspaces + Turborepo)
  │     ├── /apps/mercato         Next.js web application
  │     ├── /packages/{core,enterprise,ai-assistant,ui,queue,events,search}
  │     ├── turbo.json
  │     └── package.json
  ├── /workers                    Python (uv workspace)
  │     ├── /workers_common
  │     ├── /{docling,firecrawl,code,tabular}_worker
  │     └── pyproject.toml
  ├── /sdk
  │     ├── /typescript           @telha/sdk (dual transport)
  │     └── /python               telha (REST, pydantic)
  ├── /proto                      Protobuf contracts (buf-linted)
  ├── /tooling/spec-lint          spec linter (Node, zero-dep)
  ├── /.ai/specs/                 design manuals (MCP-readable)
  └── /.github/workflows/         CI pipelines

5. Data Models¶

This spec defines directory layout, not runtime data models. The data model for each subsystem is defined in its own spec (see composite-key-layout, version-record-model, etc.). The only normative structural element here is the .ai/specs/ directory tree:

• _TEMPLATE.md — mandatory 14-section spec template (never edited directly)
• README.md — rules and gate documentation
• core-engine/ — storage, query, temporal, vector, planner specs
• app-layer/ — Open Mercato module and feature specs
• integration/ — cross-layer contracts (gRPC, routing, encryption)

6. API Contracts¶

This spec defines no runtime APIs. The build interface is:

# Rust
cd core-engine && cargo build

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

# Python
cd workers && uv sync

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

All three toolchains MUST succeed from a clean clone as the Phase 0 acceptance gate.

7. UI/UX¶

Not applicable — this spec defines repository structure, not user-facing surfaces. The developer UX is the build commands above and the CI feedback loops defined in PR-003.

8. Configuration¶

9. Alternatives Considered¶

• Separate repositories per language: rejected because AI coding agents need full-stack context in one repo; cross-repo context switching loses coherence.
• Nx instead of Turborepo: rejected because Turborepo has simpler config for a Yarn-workspace monorepo and better caching for our use case.
• Poetry instead of uv: rejected because uv is faster and has native workspace support via pyproject.toml [tool.uv.workspace].
• Specs in a separate repo: rejected because the spec-first CI gate requires specs to be in the same PR as code changes.

10. Implementation Approach¶

PR-001 creates the full scaffold in six commits: root files, Rust workspace, TypeScript app layer, Python workers, SDK skeletons, and the spec tree. Each commit compiles independently. The spec-lint tool and CI gate (PR-002) are wired immediately after.

11. Migration Path¶

Greenfield — no existing code to migrate. The .qoder/ directory contains pre-built planning documents (PRD, build doc) that are referenced by symlink from the root README. The spec-first harness was prototyped in .qoder/ and promoted to standard locations.

12. Success Metrics¶

• cargo build succeeds in core-engine/ (produces telha binary stub)
• yarn turbo build succeeds in app-layer/ (all 7 packages + Next.js app compile)
• uv sync succeeds in workers/ (all worker packages resolve)
• node tooling/spec-lint/spec-lint.mjs .ai/specs exits 0 on all 26+ specs
• CI spec-gate workflow runs on every PR and blocks design changes without specs
• Iterator-gate workflow rejects raw iterator usage outside core-engine/src/storage/

13. Open Questions¶

None.

14. Changelog¶

• 2026-07-02 — v0.1: initial topology spec documenting PR-001 decisions.