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)
│ ├── 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/
│ ├── opal-tokens/ @todayai-labs/opal-tokens — colors, spacing, type
│ ├── ui/ @todayai-labs/opal-ui — Radix-based component library
│ ├── opal/ @todayai-labs/opal-ui — 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/ @todayai-labs/storybook — shared Storybook preset
│ ├── utils/ @todayai-labs/utils — small shared utilities
│ ├── webview-bridge/ @todayai-labs/webview-bridge — web-side bridge SDK
│ └── tsconfig/ @todayai-labs/tsconfig — shared TypeScript base config
│
├── scripts/
│ ├── affected.ts CI scope detection (dynamically discovers packages)
│ ├── cloud/ Cloud-dev bootstrap + log helpers
│ └── ...
│
├── 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)
├── AGENTS.md Agent runtime SSOT (cloud-dev, workflow, repo conventions)
├── CLAUDE.md -> AGENTS.md Claude Code compatibility symlink
└── 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-admin— internal admin / staff app. Deploys toadmin.today.ai(prod) andadmin.todayai.dev(preview). Extracted from this repo in June 2026; see #749 for the cleanup.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, opal-ui, opal-icons, tangible-ui) |
| API mocks | MSW (handlers + fixtures under apps/web/src/lib/msw/) |
| Web framework | Next.js 16 (App Router; middleware.ts is now proxy.ts) |
| Docs sites | Fumadocs (Next.js 16 + MDX) |
Each tool has its own chapter in Toolchain.
What runs where
| Surface | Hosted on | Domain (prod) |
|---|---|---|
apps/web | Vercel | today.ai |
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) |
The admin console is hosted at admin.today.ai from
todayai-labs/today-admin.
Backend domains (todayai.dev / today.ai) and per-app deploy
workflows are covered in Architecture → Three-tier domains
and Workflow → Deployment.
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.