Apps

At a glance

The admin console (admin.today.ai) was extracted to todayai-labs/today-admin in June 2026; see #749 for the cleanup.

Only apps/web gets per-worktree free-port scanning today — apps/web/scripts/dev-server.mts scans 4060-4069 for the first free port, so two web worktrees auto-take different ports. The other apps use fixed or framework-default ports and can conflict on parallel worktrees.

@todayai-labs/web — main product

apps/web. The user-facing product. Next.js 16 with the App Router, served at today.ai in production and todayai.dev in preview/dev.

Notable concerns covered elsewhere in this manual (in upcoming chapters):

• Three dev modes (localhost-direct / local / remote) — Workflow → Local development
• BFF auth proxy (apps/web/src/app/api/auth/[...all]/route.ts) — Architecture → Auth interaction
• Cookie state on the app origin — Architecture → Auth cookie state
• OpenAPI codegen via pnpm api:generate — Architecture → API codegen
• MSW handlers + fixtures under apps/web/src/lib/msw/ — Architecture → MSW mocks
• Canonical Chat runtime — Architecture → Chat runtime, with its design record under apps/web/docs/chat/
• Playwright config split (smoke / full / visual) — Toolchain → Testing → Playwright

@todayai-labs/desktop-client — Electron host

apps/desktop-client. The Linux, macOS, and Windows Electron shell for the main web application. It exposes the standardized Web Extended Interface through its isolated preload, runs the Client Node Adapter, routes CPI to the Swift macOS host or the Node platform adapters, and packages platform-native artifacts.

Linux builds produce AppImage packages for x64 and arm64. The GitHub PR workflow publishes those files as private artifacts; the public Today download page is a separate rollout. Production Linux remote tools also remain gated until cloud API platform normalization and linux / linux-connector device registration are enabled.

See the desktop-client README for dev/build commands, package formats, and the platform-specific capability matrix.

@todayai-labs/tangible — Tangible product surface

apps/tangible. A second Next.js 16 app that hosts the Tangible product surface — books, polaroids, paper-textured cards, fish-eye memory timeline. Lives at tangible.todayai.dev in preview and (target) tangible.today.ai in production.

Tangible is an OAuth client of apps/web rather than a sibling auth provider. The runtime split:

• Auth. auth.todayai.dev (apps/web's better-auth) issues the authorization code; apps/tangible/src/app/api/auth/exchange/route.ts performs the confidential-client token exchange (the OIDC_CLIENT_SECRET stays server-only) and writes the tokens into httpOnly cookies. The browser side never sees the tokens; it asks /api/auth/session for the decoded user identity.
• API. apps/tangible/src/app/api/proxy/[...path]/route.ts is the same-origin BFF proxy. It reads the access cookie, attaches Authorization: Bearer … + canonical X-Client-Platform / X-App-Version headers, and forwards to api.todayai.dev. The browser uses the typed @todayai-labs/api-client SDK with baseUrl overridden to /api/proxy, so every page can call the SDK directly without touching fetch.
• UI. @todayai-labs/tangible-ui is the self-contained component package (zero @todayai-labs/* runtime deps — see Workspace → Design system).

The four authed pages — /overview, /tasks, /automations, /memory — each fetch real data via TanStack Query + the api-client SDK and render through the tangible-ui components. See #764, #766, #767, #769, and #770 for the extraction history.

@todayai-labs/webview-bridge-docs — bridge contract site

apps/webview-bridge-docs. A separate Fumadocs site that documents the WebView Bridge wire contract plus the web SDK (@todayai-labs/webview-bridge). Read by native client teams (iOS, macOS, Android, Windows, Linux) and by anyone writing web code that runs inside a WebView or the Electron app shell.

This site (@todayai-labs/dev-docs) does not duplicate that content. See Docs sites for the boundary.

@todayai-labs/dev-docs — this site

apps/dev-docs. You are reading it. Engineering manual for the today-platform-web monorepo itself. Read by new contributors and by AI agents working in the repo.

Adding a new app

Full checklist: workspace/adding-package. The short version:

1. Create apps/<name>/ with package.json (@todayai-labs/<name>), tsconfig.json, tsconfig.app.json, tsconfig.node.json, moon.yml.
2. Run pnpm install to register the workspace.
3. Add the project to tsconfig.json's references at the repo root if it participates in tsgo --build.
4. If it deploys to Vercel: create a Vercel project, add VERCEL_PROJECT_ID_<NAME> to GitHub repo variables, add .github/workflows/deploy-<name>.yml.

scripts/affected.ts discovers packages dynamically from pnpm-workspace.yaml, so you do not need to register the new app there.