Platform map

TED OS is a pnpm + Turborepo monorepo. Workspaces live under apps/* and packages/*; every shared package is published under the @tedos/* scope. Apps depend on packages; packages never depend on apps.

Apps

App	Package	What it is
admin	@tedos/admin	The operator's two-level admin (platform + project context). Next.js on Vercel. → admin
console	@tedos/console	The operator superadmin / internals console (console.tuempresa.digital). → console
comprender	(apps/clients/comprender)	The first white-label client instance — tenant #1. → comprender
api	@tedos/api	The Fastify API: product endpoints, the Plan Engine API, webhooks, MCP. On Fly. → api
claude-kit-docs	@tedos/claude-kit-docs	This site (docs.tuempresa.digital), Clerk-gated.
desktop	@tedos/desktop	A Tauri desktop shell — paused.

Packages

Package	Role
@tedos/auth	Reusable Clerk wiring (CSP + middleware) adopted by client apps. → Auth
@tedos/domain	The product System of Record (Drizzle/Postgres). → Product SoR
@tedos/db	The Plan Engine graph schema + migrations. → Plan Engine
@tedos/engine	The last-mile, model-agnostic task orchestrator + connectors. → Engine
@tedos/shared	The frozen cross-app contract (zod-as-source + inferred types) shared by API and admin.
@tedos/admin-ui	The admin design system — tokens, shell, components/ui, shared screen views. → Design system
@tedos/ui	The neutral foundation (palette + type scale), icon- and accent-agnostic.
@tedos/claude-kit-plugin	The packaged claude-kit plugin. → claude-kit

Monorepo boundaries (hard rules)

• No cross-workspace reaching. Import another workspace only through its @tedos/* name — never a relative path into a sibling.
• Direction of dependency: apps depend on packages; packages never depend on apps.
• One workspace per concern. Needed by 2+ workspaces → extract a @tedos/* package.
• Foundation vs. skin. @tedos/ui is neutral; each surface's hue + icons live in its skin (e.g. @tedos/admin-ui carries the admin's Cian + HugeIcons). See Color scope.

The two-database split

The single most load-bearing architectural rule: dev-workflow data and client/product data are separate databases and never share tables.

                      one Fly Managed Postgres cluster (today)
        ┌──────────────────────────┬──────────────────────────┐
        │  plan schema             │  product schema           │
        │  (Plan Engine graph)     │  (product SoR, per-client)│
        │  OUR plans + tasks       │  CLIENTS' data            │
        │  → training-trace corpus │  → never enters the corpus│
        └──────────────────────────┴──────────────────────────┘

Both schemas currently share one cluster (a documented compromise — no real tenant data yet) with a tracked upgrade path to a dedicated cluster before real tenant-PII volume. See Plan Engine and Product SoR.

Where to go next

• The dev-workflow graph → Plan Engine
• The client/product data → Product System of Record
• Per-client data, memory, and the future assistant → Data, memory & assistant
• The task orchestrator → Engine
• The reasoning behind it all → Decisions (ADRs)