Skip to main content

Orientation — how to read this project

canonical · pm · updated 2026-09-05 · source

Start here. This doc describes what the system IS and how to navigate the documentation. It is not a log or a record of PRs/processes: for "what happened" see decisions/log.md.

The healthy way to read​

  1. Start with knowledge/INDEX.md — the manifest: one row per doc with its topic, status and owner. Find the canonical doc for your topic there before reading any other.
  2. If a file exists in knowledge/, it is current. Superseded docs are DELETED — git is the archive. There is no archive/ folder; a present doc is the current truth for its topic.
  3. The latest decision wins. When two docs conflict, decisions/log.md and the frontmatter's updated date break the tie.
  4. Read the frontmatter status — canonical = source of truth for its topic · reference = consultable/research, not normative · historical = context only, its decisions may be superseded.
  5. A plan IS a GitHub issue (ADR-006), mirrored to the Plan Engine graph (ADR-004/005). The MDX plan files (apps/admin/src/plans/) are retired — the "where we stand" view is the /plan · /roadmap · /work surface over the graph (plan-engine.md); strategy/roadmap narrative lives here in knowledge/.

Doc map — what to read for what​

You need…Read
The Plan Engine graph (plans + tasks SoT, MCP, sync, admin views)plan-engine.md
The first client / case study (Comprender E1)comprender-mvp-e1.md
Business / roadmap / MVP narrativetedos-business-model.md · comprender-mvp-e1.md
How the product evolves (subplans, timeline, approval)product-development-flow.md
The engine (architecture, reliability, hybrid deployment)packages/engine/ARCHITECTURE.md
Engine connectors (CRM, WhatsApp, Google, HubSpot, GitHub)packages/engine/CONNECTORS.md
UI — design system, screens, gridadmin-design-system.md · tedos-screens.md · grid-system.md
UI — component sourcing (shadcn-first, one implementation per primitive family, dedupe guards)component-sourcing.md
UI — the student account section (/mi-cuenta/*): holder geometry, card-grid recipe, perfil IAportal-mi-cuenta-spec.md
Design — canonical source map (Paper↔repo) + principlesdesign-source-of-truth.md · design-principles.md
The operator console (superadmin / internals)console-design.md
The operator surface in the portal — nav / IA + app chromeoperator-nav-ia-spec.md
Brand — identity + voicebrand.md · brand-tone.md · admin-tone.md
Infra / DevOps — deploy, support emailcd-and-domain-provisioning.md · environments.md · support-email-alias.md (hosting → decisions/log.md)
Architecture decisions (ADRs)decisions/adrs/README.md
The self-writing wiki — pattern + the opsllm-wiki-pattern.md
Dev workflow — worktree & session-ownership modelwiki/kit-worktree-session-model.md
Dev workflow — OpenCode kit variant (spike, go/no-go)opencode-kit-exploration.md
The model seam — one boundary to the open-source model (/v1, tenant routing, local/hosted/mock tiers, engine + apps/chat consumers)wiki/model-client-seam.md
The neutral conversation app — per-tenant RAG chat (@tedos/ui/chat + .chat scope, model-client seam)wiki/apps-chat.md
The operator + builder console — Cian skin, plans viewer + student aula (app.tuempresa.digital)wiki/apps-admin.md
The operator's multi-tenant console — Amber skin, per-org modules/memoria over @tedos/corewiki/apps-console.md
Typed data-fetching — the one @tedos/api-client seam every Next app reads throughwiki/typed-data-fetching.md
Multi-tenant client config — one console configures every org (runtime, no rebuild)wiki/client-configuration-framework.md
What was decided and when (tie-breaker)decisions/log.md
External reference / research (sources/ layer)sources/t3code-teardown.md · sources/mobbin-research.md · sources/design-references-bento.md · sources/marketing-site-reference-benaios.md · sources/hosted-vllm-serving-databricks.md · sources/kit-resource-inventory.md

System status (what it is, today)​

  • Plan Engine graph (@tedos/db + /plan/* API, effort #560, live): the daily-driver source of truth for plans + tasks — a Postgres graph (5 tables in a dedicated plan schema) editable/actionable from both Claude (9 plan_* MCP tools) and the admin (/plan, /roadmap, /work), kept bidirectionally synced with GitHub issues/PRs + Vercel deploys (GitHub stays a mirror; elimination deferred, ADR-005). The dev-workflow graph — never mixes with tenant data. → plan-engine.md.
  • Product System of Record (@tedos/domain, effort E1, live): tenant/client data in a dedicated product Postgres schema — never the dev-workflow Plan Engine graph (ADR-006 hard rule). A unified person deduped across channels with fiscal data; project = tenant = Clerk org. API in apps/api (/projects, /p/:id/students*, /p/:id/summary) behind Clerk auth + role-scoped tenancy. Comprender = tenant #1. → comprender-mvp-e1.md.
  • Plan graph + product SoR share one Fly MPG cluster, isolated by Postgres schema (plan vs product) — a documented compromise (no real tenant data yet) with a tracked upgrade path to a dedicated cluster before real tenant-PII volume or any external training-data export (plan-engine.md §7).
  • Two-level admin shell (apps/admin, FROZEN — ADR-017, 2026-08-31): Level 1 platform (/projects switcher) + Level 2 project context (/p/[projectId] with swapped sidebar + role-scoped nav). No new development; kept only until apps/console absorbs the platform level. apps/portal is the primary tenant surface now. API on Fly (tedos-api, web + worker, Fly Managed Postgres). → comprender-mvp-e1.md.
  • Operator console (apps/console = @tedos/console, console.tuempresa.digital, live): the operator superadmin / internals control room — a cross-tenant surface consuming @tedos/ui/admin chrome + @tedos/shared contracts, pointing at the shared tedos-api. The third Aurea matiz: warm dark + Amber/Halide accent on the ink/pergamino panel, black top-bar (one amber moment per screen). It is the single surface from which an operator configures every client org. → console-design.md.
  • Client Configuration Framework (effort #922, live): one operator console configures everything about an org — identity / domain, branding tokens, locale · tier · enabled modules, feature flags, and AES-256-GCM connector secrets — while one multi-tenant client app resolves the tenant from its request Host and reads all config from the public GET /tenant/config. Config edits are runtime (DB-served, no rebuild); only code changes trigger selective builds, and one deployment serves every tenant domain. → wiki/client-configuration-framework.md.
  • apps/clients/comprender (@tedos/comprender, live, tenant #1): the live multi-screen white-label client app — its screens (Resumen, Alumnos, Ofertas, Pagos, Inscripciones, Certificados, Misión, Conexiones, Run, Reportes) render the shared @tedos/ui/admin/screens bodies, read the product API through their own @tedos/api-client seam, and resolve the tenant per-request by Host (lib/tenant-config.ts) with runtime branding on the .client scope. → comprender-mvp-e1.md.
  • apps/chat (@tedos/chat, live) — the neutral conversation app: a per-tenant RAG chat on the @tedos/ui foundation under the .chat ink-accent scope (one accent moment = Composer Send), talking to the model through the @tedos/model-client seam (AI-SDK streaming). The fourth skin alongside admin (Cian) / console (Amber) / comprender (white-label). → wiki/apps-chat.md.
  • Last-mile engine (@tedos/engine): a model-agnostic orchestrator (open-source first) with a reliability layer — evals, retries, guardrails (PII) and a human gate — plus roles and a council/board-meeting to deliberate decisions. Its model boundary (LLMProvider, ModelPolicy, selectProvider) is now re-exported from the canonical @tedos/model-client home (#874), not implemented twice.
  • Model seam — @tedos/model-client is the single canonical boundary to the open-source model (OpenAI-compatible /v1 + x-tedos-tenant, hybrid local / hosted / mock tiers — only the provider changes); @tedos/engine re-exports it for request/response and apps/chat consumes resolveModelConfig for streaming, while the Python satellites target its wire contract (CONTRACT.md) — no per-app fetcher (#874). → wiki/model-client-seam.md.
  • Connectors: CRM, WhatsApp (Meta / 360dialog), Google, HubSpot, GitHub; a pg-boss-style queue (in-memory so it boots without Postgres). (The legacy in-memory tickets.ts store is retired, #560/#570 — ticket/Deliverable state lives in the Plan Engine graph.)
  • Verticals marketing + accounting over the same core — each delivery reuses the engine.
  • Typed data-fetching seam — @tedos/api-client (openapi-fetch typed by generated @tedos/api-types) is the one transport every Next app reads through; thin per-app lib/api-client.ts seams inject baseUrl + Clerk token, data-fns return ApiResult (no swallowed fallbacks), no-store + React.cache, offline fixtures behind one flag. The generated types are produced by pnpm gen:api from apps/api/openapi.json (the committed spec is the drift check). → wiki/typed-data-fetching.md.
  • apps/admin: Run screens (launch a goal and watch the engine execute) and Timeline inside the authenticated shell; the /api/engine proxy injects the tenant from Clerk.
  • apps/api (Fastify, on Fly): the shared product API — the engine at /engine/* (goal / jobs / decision), the product SoR routes (/projects, /p/:id/*), the operator-console config endpoints + the public Host-resolved GET /tenant/config, and the OpenAPI spec (openapi.json) that generates @tedos/api-types.

Golden rule​

The documentation describes what IS. When you change the state of the system, update the doc for that topic (and its row in INDEX.md) in the same PR — never append to a log file. Changelogs are only written when planning a release.

Ingested wiki pages​

Auto-maintained by the self-writing engine (scripts/knowledge-ingest.sh) — each ingested page is linked here so it stays reachable (never an orphan).