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
• Chat runtime (already documented in apps/web/docs/chat/) — Architecture → Chat runtime (high-level, links to the local docs)
• 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 injects the validated window.__todayWebView descriptor, provides the isolated promise bridge, runs the device connector/tool runtime, and packages platform-native artifacts.

Linux builds produce AppImage and deb packages for x64 and arm64. GitHub PR and desktop-release workflows publish those files as private artifacts or Release assets; 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.