Conversational Factory
§ 07 · Build

Repo map

How the parent workspace is organized — services, schemas, examples, and the conventions that keep them honest.

View as .md

Intent

This repository is one reference implementation of the Conversational Factory roles — not the definition of the product. The canonical artifact is the role specification (see role definitions and system architecture); this tree is one way to satisfy it. It hosts the services that make up the read-only query chain and the shared contracts between them.

Source of truth. The concepts are canonical; the code is reference. For the layout of this particular reference tree, the live repo conversational-factory is authoritative; where a path here and a path there disagree, the repo wins. The query-plane role is filled by a separate, source-agnostic component (modelpond) and is not part of this tree.

Structure

  • docs/ — product thesis, system architecture, role definitions, repository guidance
  • schemas/ — shared, versioned contracts
  • services/ — runnable services and prototypes
  • examples/ — sample datasets and query flows
  • scripts/ — first-run.sh, dev-certs.sh, smoke-run.sh
  • top-level Makefile + docker-compose.yml — the one-command bring-up

Services

  • services/conversational-gateway/ — the read-only MCP front door: NL → query translation, answer composition, audit chain. The genuinely novel work.
  • services/query-plane/ — the small, opinionated read API (i3X v1) that the gateway consumes; the AI-facing surface.
  • services/witness/ — a reference passive-ingest data plane: observes and ingests passively into the standardized record (its own Docker Compose stack: app + workers + Postgres + Redis). One example of the role, not the definition.
  • services/discovery/ — a reference active-ingest data plane: polls/queries/enumerates read-only where there’s no existing traffic to observe. The active counterpart to the witness; one example of the role, not the definition.
  • services/shared/ — shared types and contract code.

Schemas

schemas/ carries the contract surface: assets/, common/, events/, gateway/, i3x/, query-plane/, state/, system/. schemas/i3x/ is the open read-API standard the query plane implements.

Working conventions

  • Keep shared schemas implementation-agnostic where possible.
  • Prefer explicit versioned contracts once services begin to consume them.
  • Keep marketing and product positioning out of service packages.
  • Treat read-only access as the default contract — there is no write path to a device anywhere in the chain, by design.