Orientation
Repo tour
The five-minute orientation — what lives where, which tools do what, and which sibling repos are in play.
Layout
today-platform-web/
├── apps/
│ ├── web/ Main product app (Next.js 16, dev port 4060)
│ ├── admin/ Internal admin app (Next.js 16, dev port 4061)
│ ├── onboarding/ Vite-based onboarding standalone (dev port 5174)
│ ├── webview-bridge-docs/ Fumadocs site: WebView Bridge contract + SDK
│ └── dev-docs/ Fumadocs site: this manual (dev port 4070)
│
├── design-system/
│ ├── tokens/ @today/tdx-tokens — colors, spacing, type
│ ├── ui/ @today/tdx-ui — Radix-based component library
│ ├── opal/ @today/opal — onboarding / product flow primitives
│ ├── opal-host/ Host adapter contracts for opal
│ └── docs/ Fumadocs site: TDX design-system reference
│
├── packages/
│ ├── auth-client/ @todayai-labs/auth-client — domain / OIDC URL resolution
│ ├── storybook/ @today/storybook — shared Storybook preset
│ ├── utils/ @today/utils — small shared utilities
│ ├── webview-bridge/ @today/webview-bridge — web-side bridge SDK
│ └── tsconfig/ @today/tsconfig — shared TypeScript base config
│
├── scripts/
│ ├── affected.ts CI scope detection (dynamically discovers packages)
│ ├── dev-server.mjs Per-worktree free-port dev launcher
│ └── ...
│
├── docs/ Long-form documentation (some migrated into this site)
│ ├── plans/ In-progress implementation plans (drafts)
│ └── changes/ Shipped implementation logs (archive)
│
├── .github/workflows/ CI + per-app deploy workflows
├── .moon/ Moon task orchestration config
├── pnpm-workspace.yaml pnpm workspaces + catalog (single source of versions)
├── CLAUDE.md Claude Code agent entry — tacit knowledge for AI runtime
├── AGENTS.md Agent guidelines (cloud-dev, iterative workflow)
└── README.md Public overviewSibling repositories
A few load-bearing repos live outside this one:
todayai-labs/today-cloud— backend services (auth, agent, API). Local full-stack dev requires running it; agent E2E pulls OTPs from there.todayai-labs/today-tck— the canvas / widget toolkit. Published as private@todayai-labs/tck*packages on GitHub Packages.todayai-labs/playground— throwaway prototype demos. Used to live underdemos/in this repo.
Tool baselines
| Concern | Tool |
|---|---|
| Package manager | pnpm 9+ with workspace catalog: (strict) |
| Task orchestration | Moon (.moon/workspace.yml) |
| TypeScript | tsgo --build (TypeScript Native Preview) |
| Lint + format | oxlint + oxfmt (not ESLint / Prettier) |
| Unit tests | Vitest 4 |
| Browser tests | Playwright (smoke / full / visual configs) |
| Component dev | Storybook 10 (web, design-system/ui, design-system/opal) |
| API mocks | MSW (handlers + fixtures under apps/web/src/lib/msw/) |
| Web framework | Next.js 16 (App Router; middleware.ts is now proxy.ts) |
| Vite app | apps/onboarding (Vite 8) |
| Docs sites | Fumadocs (Next.js 16 + MDX) |
Each tool has its own chapter in Toolchain (PR-CB).
What runs where
| Surface | Hosted on | Domain (prod) |
|---|---|---|
apps/web | Vercel | today.ai |
apps/admin | Vercel | admin.today.ai |
apps/onboarding | Vercel | (route under web) |
design-system/docs | Vercel (separate project) | (Vercel default) |
apps/webview-bridge-docs | Vercel (separate project) | (Vercel default) |
apps/dev-docs | Vercel (separate project) | (Vercel default, deployment-protected) |
Three-tier domains (t.ai / todayai.dev / today.ai) and per-app deploy
workflows are covered in Architecture → Three-tier domains
and Workflow → Deployment (PR-CB).
Introduction
The operating manual for the today-platform-web monorepo — toolchain choices, package layout, daily workflow, cross-package architecture, and the AI / agent collaboration surface.
Reading paths
Two ordered reading lists — one for a new human contributor, one for an AI agent picking up a task in this repo.