Design — README

Telemachus — Platform Design

Design docs for the platform subsystems that make Telemachus a team platform rather than a single-user workspace, plus the Localization flagship that proves the platform can build real tools. These are proposals with data shapes and contracts for review — concrete enough to build from, with the genuine policy forks flagged Decisions to confirm in each doc.

Doc	Subsystem	One line
rbac-and-teams.md	RBAC & Teams	Who exists, what they may do, whose data is whose.
quotas.md	Quotas	What is metered per user/team, and the limits.
ai-queue-and-concurrency.md	AI workload scheduler	Admission, placement & concurrency caps — a workload queue (SLURM/k8s-style), not a message bus; local now, federation-ready.
localization.md	Localization	i18n top-to-bottom + a manager tool (extract → team-complete → CI-gate); English at launch, ja/nl/es-419 built by the tool.
multi-tenancy.md	Multi-tenancy	Many companies on one instance, behind a flag: an org above the team, a superadmin tier above the org admin, an org gate at step 0 of every check. (Operators: ../ops/multi-tenancy-runbook.md.)
workflow-engine.md	Workflow engine	Plugins that process in steps: a public data spec as the contract, `define-workflow` as the Racket authoring surface, every step a scheduler job. (Operators: ../ops/workflow-engine-runbook.md.)
brand/	Brand	The Mentor mark — direction 02 of the nine-direction identity study: an arched helm whose two eyes are an owl's and whose gold brow bar over the nasal guard is a T. SVG assets, palette, type and usage rules.
document-repository.md	Document repository	Binary documents of any format, team access control with creator-set visibility, exposed as an S3-compatible API; content-addressed bytes behind a plugin seam (`rs3` local). (✅ Built, slices 49–55 — including content search and the documents fold. Operators: ../ops/document-repository-runbook.md.)
saas-onboarding.md	Onboarding / SaaS	Provision a per-tenant instance seeded with exactly one owner (signup / subscription / VM launch); operator-vs-owner split, magic-link activation.
beta-onboarding-experience.md	Beta onboarding	Skinnable, admin-configurable pre-sales lead capture; core = mechanism, plugin = presentation; extensible `attributes` model + a token-themed render contract.
documentation-generation.md	Documentation generation	Generate the reference (tools, workflows, permissions, API, plugins) from the source of truth; commit it, drift-gate it in CI, and make its prose a `doc.` namespace the Localization Manager translates. Forces a declarative route table and permission descriptions. (Decided 11 Sep 2026; ✅ built, slice 60 — `docs/reference/`, drift-gated.)
knowledge-graph.md	Knowledge Graph	Entities and relations extracted from the team's documents, every fact traceable to a document version; visibility inherited from the source via `can?`; extracted by a workflow, queried through search, an agent tool and a tab. (Decided 11 Sep 2026; ✅ built, slice 61.)
document-sharing.md	Document sharing	Three capabilities (view / edit / manage) over the grants table that already exists; team principals inside an org; expiring grants; derived documents inherit at creation. (Decided 12 Sep 2026; ✅ built, slices 56 and 59 — including the share dialog and "Shared with me".)
document-workflows.md	Document workflows	Uploads that trigger processing — one seam inside `repo-put!` covering console, shim and S3; runs as the uploader; extract → fields (schema-validated) → form → translations, every output a repository document with provenance. The first-user path. (Decided 12 Sep 2026; ✅ built, slices 57–59 — the tools, the `doc-pipeline` plugin, "Run workflow…", upload triggers (S3 included), the Automations card, "Processed by", DOCX rendering, and the invoice scenario in the e2e gate.)
pull-executors.md	Pull-model executors	Inference hosts that come to the work: a worker claims jobs from the existing `jobs` table over HTTP with a scoped worker token, holds a lease with heartbeats, posts the result; capability matching at claim; `infer.chat` as the first remote kind so every model-using tool works unchanged; per-org executors (TEN‑2e). (Decided 15 Sep 2026; ✅ built, slice 66 — issue #15.)
nix-packaging.md	Build & deploy (toolchain, not a platform subsystem)	✅ Built. Reproducible `nix develop` / `nix build` / `nix run`; retires the brew+`PLTCOLLECTS` ritual and unlocks live Postgres testing.

How they interlock

RBAC defines the principals (users, teams, service tokens). Those same principals are the subjects that quotas meter and the queue attributes work to. Read RBAC first.
Quotas set the caps (tokens/day, max concurrency, storage). The governor enforces the concurrency/rate portion at admission time; the quota service owns the accounting and the periodic budgets.
The scheduler places admitted work on an executor (a compute resource) and holds a slot only per step, so long agent flows don't starve others. It is a workload queue (schedules jobs onto resources, SLURM/k8s-style), not a message queue (0mq/NATS); a message transport may later be the wire to remote executors, but that is deferred and out of RI scope.
Localization is composed from the other three, not new infra: the manager is RBAC-gated (who edits which locale), meters AI drafts through quotas, runs bulk drafts as scheduler jobs, and ships as an SDK localization extension. That it needs no new plumbing is the proof — the platform builds a real tool out of its own primitives, and that tool then produces ja/nl/es-419.

request ─▶ RBAC check ─▶ quota check ─▶ scheduler admission ─▶ executor slot ─▶ model
             (may?)        (budget?)      (place? fair? depth?)   (local now;
                                                                  remote later)
                └──────────────── audit_log (every decision) ─────────────────┘

Cross-cutting tenets baked in

Contract-first / swappable backends. Each subsystem is defined as an interface (AuthzService, QuotaService, Scheduler) that any backend implements; refimpl/racketmaximus is the reference implementation. Frontends and alternative backends target the contract, not the Racket code.
Every feature is manageable + activatable. Each subsystem exposes a management surface and honors a global/team feature activation flag (features registry, §RBAC). Enforcement decisions and management actions write to a shared audit_log.
Backend-neutral data. Shapes below use generic types (text, int, timestamp, json) — no SQLite-only or Postgres-only constructs — so the SQLite→Postgres move stays a db-kit backend swap.
Hooks the engine we already built. run-agent's injected effects are the enforcement seam: the #:llm effect is wrapped by the governor + token meter; the #:exec effect is wrapped by the RBAC tool-permission check + tool-quota meter. The pure spine is untouched — this is exactly what the injected-effects design was for.

Tenancy (decided — revised in slice 45)

Team is the tenancy boundary, and above it sits an org (a company). Every deployment has at least one org; TELEMACHUS_MULTITENANT decides whether it may have more.

Flag off (default) — exactly one implicit org, and the product behaves as it always has: a deployment serves one legal entity containing one or many teams. This was decision TEN.
Flag on — several companies share one instance, isolated by an org gate that runs before every permission, grant and token-scope check. A superadmin (instance:*) runs the instance; each company's org admin (org:*) runs only its own. This is decision TEN‑2, which supersedes TEN. See multi-tenancy.md.

The hosted offering can now serve different legal entities either way: as one isolated instance per tenant (saas-onboarding.md), or as several orgs on one instance. The two compose — a provisioned instance is just a deployment with the flag off.

Follow-up design items (noted, not yet drafted)

Management-contract & audit. The uniform per-feature management/activate interface and the shared audit_log are referenced by every doc; they may earn a short dedicated spec.
Security model. The posture is built and spread across the subsystem docs and CLAUDE.md; a consolidated design doc is owed (see the FSD).

Kickoff decisions

All the choices needed to start building — with recommendations and a decision log — are compiled in decisions.md.

Status

Every design in the table above is built, except where a row says otherwise. The generated reference for what exists is under ../reference/. The checkboxes in ../FeatureRequirements.md track it.