# CI/CD Pipeline Optimization
Source: https://docs.tuturuuu.com/build/development-tools/ci-cd-optimization

Centralized affected-path gating and smart caching to minimize unnecessary CI/CD runs.

<Info>
  **Prerequisite**: Read the [CI/CD
  Pipelines](/build/development-tools/ci-cd-pipelines) page to understand the
  basic workflow structure.
</Info>

## Overview

Our CI/CD pipelines avoid wasted builds, tests, and deployments through a
**centralized affected-path gate** plus **build caching**. Instead of every
workflow re-implementing its own change detection, automatic deployments share
the same TypeScript decision function while avoiding a separate configuration
runner when the decision can be made inside an already-required job.

This page documents how that gate works, how the per-app Vercel workflows are
wired, and how to debug skip decisions.

<Note>
  The platform is mid-migration from `apps/web` (Next.js, port `7803`) to
  `apps/tanstack-web` (TanStack Start) plus `apps/backend` (Rust, port `7820`).
  See [TanStack + Rust
  migration](/platform/architecture/tanstack-rust-migration). The optimization
  model below applies to both stacks: every Vercel app target is gated the same
  way, regardless of framework.
</Note>

## The Problem

Before centralized gating, workflows ran on every push regardless of:

* Whether files relevant to that specific app or package actually changed
* Whether the change only touched an unrelated app
* Whether build artifacts were already cached

With a large monorepo of apps and shared packages, this meant a single commit to
one app could trigger dozens of unrelated build and deploy workflows, slowing
feedback and congesting the Actions queue.

## How Gating Works Today

Vercel affected-app gating does **not** rely on GitHub's native
`on.push.paths` filters. Path filters are coarse (they cannot understand
workspace dependency graphs), so the Vercel logic stays centralized. A narrow
exception is the external-app compatibility build: its contract is simply
"`apps/external` or any internal package changed," so native trigger paths can
avoid creating a runner at all for unrelated app-only commits.

The shared logic is organized in four pieces:

1. **`tuturuuu.ts`** — the source of truth. It exports a `ci` toggle map (each
   workflow can be globally enabled/disabled), the `vercelWorkflowTargets` table
   that maps each app to its preview/production workflow and package name, and
   the `getWorkflowDecision()` function that decides whether a given workflow is
   affected by a set of changed files.
2. **`scripts/ci/resolve-changed-files.ts`** — resolves the changed-file set for
   the current event (push payload, pull-request base/head, or git diff against
   the last successful deployment marker).
3. **`.github/workflows/ci-check.yml`** — the reusable gate for non-Vercel
   workflows that still need an individual `should_run` output.
4. **`.github/workflows/vercel-production.yaml`** — the single production
   planner. It resolves every app against that app's last successful deployment
   marker in one runner, then calls only affected production workflows as
   reusable jobs in the same commit-associated push run.

### Reusable and inline gates

Non-Vercel gated workflows can declare a `check-ci` job that calls
`ci-check.yml`, then gate their real job on the result. Platform preview is
different: it must complete on every protected `main` push so
`supabase-staging.yaml` receives its workflow-run signal. Its deploy job checks
configuration and affected paths inline, then skips install/build/deploy steps
when the app is unaffected. This keeps the workflow signal while using one
runner instead of a configuration runner followed by a deploy runner.

```yaml theme={null}
jobs:
  Deploy-Preview:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
        with:
          fetch-depth: 0
      - uses: actions/setup-node@v7
        with:
          node-version: 24
      - name: Compute changed files
        id: changed_files
        run: node --experimental-strip-types scripts/ci/resolve-changed-files.ts
      - name: Check preview configuration
        id: check_config
        run: node --experimental-strip-types scripts/ci/check-workflow-config.ts
```

Internally, `ci-check.yml` uses a sparse checkout (only the manifests and
scripts it needs), computes the changed files, and runs the decision script:

```yaml theme={null}
- name: Compute changed files
  id: changed_files
  env:
    GITHUB_TOKEN: ${{ github.token }}
    WORKFLOW_NAME: ${{ inputs.workflow_name }}
  run: node --experimental-strip-types scripts/ci/resolve-changed-files.ts

- name: Check Configuration
  id: check_config
  env:
    CHANGED_FILES_FILE: ${{ steps.changed_files.outputs.changed_files_path }}
    WORKFLOW_NAME: ${{ inputs.workflow_name }}
  run: node --experimental-strip-types scripts/ci/check-workflow-config.ts
```

The scripts run with Node's `--experimental-strip-types`, so the `.ts` sources
execute directly without a separate build step. Trusted manual satellite
preview workflows launch their guarded deploy job directly: manual dispatch
already bypasses affected-path gating, so a reusable preflight would only add a
second queued runner. These workflows remain protected by the `main` dispatch
ref, `TRUSTED_PREVIEW_DEPLOY_ACTORS`, and their GitHub Environment. Preview
concurrency is keyed by workflow and `preview_ref`; a repeated request for the
same preview cancels stale work, while different preview refs remain independent.

### The production planner

A `production` push starts one `plan` job instead of starting one
`check-ci` runner per app. `resolve-production-vercel-targets.ts` reads the
workspace graph once, memoizes dependency closures, resolves each target from
its own successful deployment marker, and emits a reviewable Actions summary.
Static reusable jobs call only the selected `vercel-production-<app>.yaml`
workflows, so deployments stay attached to the original push SHA instead of
appearing as detached `workflow_dispatch` runs.

Per-app production workflows remain independently protected by their GitHub
Environment and a static per-app concurrency group. The group must include the
app identifier because reusable workflows inherit caller context; a shared
caller-derived key would cancel sibling deployments and show red X statuses
instead of clean skips. They accept `workflow_call` for commit-driven planner
jobs and retain `workflow_dispatch` for deliberate operator reruns. Their
`cancel-in-progress` predicate is enabled only for a `production` push, so a
`main` commit or manual recovery run cannot cancel an active production deploy.
A missing or untrusted marker fails open for that app without forcing every
other app's gate open.

### The decision function

`getWorkflowDecision()` in `tuturuuu.ts` resolves to `should_run` using this
order of precedence:

1. **Global toggle.** If the workflow is `false` in the `ci` map, it never runs.
2. **`workflow_dispatch` bypass.** Manual runs always proceed (affected-path
   gating is skipped), so you can force a deploy from the Actions UI.
3. **Non-Vercel workflows.** Workflows without an entry in
   `vercelWorkflowTargets` fall back to their static `ci` toggle.
4. **Unavailable change data.** If the changed-file set cannot be resolved, the
   gate stays **open** (`should_run = true`) to fail safe.
5. **Affected-path matching (Vercel workflows).** The workflow runs only if at
   least one changed file matches one of:
   * a **global affecting path** (`bun.lock`, `package.json`, `turbo.json`,
     `tuturuuu.ts`, `.github/workflows/ci-check.yml`, the shared Bun/remote-cache
     actions, or the deterministic metadata generator);
   * the workflow's **own** workflow file;
   * the target app's directory (e.g. `apps/web/**` for the platform target);
   * any package inside the target app's **workspace dependency closure**. The
     closure is built from `workspace:*` dependencies, so editing a shared
     package only triggers the apps that actually depend on it.

If nothing matches, the decision is `should_run = false` and the heavy job is
skipped.

### Vercel target table

Every Vercel app is registered once in `vercelWorkflowTargets`. Adding a new app
means adding a single entry there (app slug, app path, package name, and the
preview/production workflow filenames) — the gating logic and changed-file
matching then apply automatically.

```ts theme={null}
{
  app: 'platform',
  appPath: 'apps/web',
  packageName: '@tuturuuu/web',
  previewWorkflow: 'vercel-preview-platform.yaml',
  productionWorkflow: 'vercel-production-platform.yaml',
}
```

**Applied to:** the 24-target production planner, the inline platform preview
gate, and other gated CI workflows wired through `ci-check.yml`. The other 23
preview workflows are trusted manual dispatches and therefore do not allocate a
standalone configuration runner.

## Build Caching

Once a workflow decides it must run, cacheable JavaScript work is invoked from
the repository root through
`.github/actions/run-with-turbo-remote-cache/action.yml`:

```yaml theme={null}
- name: Type check
  uses: ./.github/actions/run-with-turbo-remote-cache
  with:
    command: bun turbo:local run type-check --concurrency=4
    token: ${{ secrets.TURBO_TOKEN }}
    team: ${{ vars.TURBO_TEAM || secrets.TURBO_TEAM }}
```

The composite action exposes credentials only to the wrapped command step. It
runs locally when both token and team are absent, rejects a token without a
team, and keeps Turbo's local rebuild behavior available if the remote service
is unavailable. `TURBO_TOKEN` must never be passed to pull-request or
Dependabot jobs. Those jobs restore a task-family-scoped `.turbo` fallback from
GitHub's cache without writing shared entries; trusted default-branch jobs seed
that fallback.

The shared Bun runtime and package-download caches follow the same ownership
rule: only trusted `main` jobs save entries. Production, pull-request,
Dependabot, and other branch jobs restore the default-branch cache without
creating branch-scoped duplicates. This is especially important for Bun's
package cache, which can approach 1 GB for the full monorepo lockfile.

Turborepo hashes inputs and reuses cached task outputs, so unchanged builds,
type checks, and tests resolve to cache hits instead of recompiling. The task
graph includes transit-only dependency nodes for tests: dependency source
changes invalidate downstream tests without running every dependency's test
suite. Build outputs include framework output, coverage, and TypeScript
incremental state where those artifacts are deterministic. Output-affecting
environment values are hashed, while CPU, heap, and concurrency controls are
pass-through values.

Every active Vercel project has a checked-in `buildCommand` that invokes its
full workspace build through root Turbo. The 48 deployment workflows generate
deterministic source metadata and then wrap `vercel build`; they do not run a
separate dependency prebuild. This lets an unchanged full app build restore as
one task while `.vercel/output` remains an in-job handoff to
`vercel deploy --prebuilt`, not an uploaded artifact or generic cache.

Docker and Rust verification use the same principle at their native cache
layers. Each shared GitHub BuildKit scope has one trusted `main` writer: Docker
setup owns web, TanStack, and storage scopes; Rust CI owns the backend scope;
and E2E shard 1 owns the small leaf-service scopes. Production, other shards,
and migration E2E restore without exporting. Expensive web, TanStack, and
backend images use `mode=max`; validation-only development and small leaf
images use `mode=min` or restore-only caching. Dockerized E2E jobs explicitly
select a `docker-container` Buildx builder so Compose can import and export the
GitHub cache backend. Turbo values enter image builds only as BuildKit secrets.
Rust verify and deploy jobs share one pinned,
toolchain-aware Cargo cache, with writes restricted to protected branches.

Flutter workflows cache dependencies and native tool state (pub, Gradle, and
CocoaPods), never final APK, AAB, IPA, archive, or application-bundle outputs.
Dependency resolution and the platform build always execute so a cache hit
cannot skip validation. Managed uv and CodeQL caches remain owned by their
upstream actions rather than being duplicated.

Automatic CodeQL is owned by GitHub's organization-managed
`dynamic/github-code-scanning/codeql` workflow, which scans
JavaScript/TypeScript and Python. The checked-in `.github/workflows/codeql.yml`
is manual-only: it preserves an explicit fallback and avoids the Security UI's
missing-workflow warning without adding push, pull-request, or cron duplicates.
`bun git-sync` mirrors the already-scanned `main` SHA to `production`.

The full Dockerized E2E graph is created for E2E specs, Playwright and Docker
configuration, database fixtures, package manifests, lockfiles, and its own
runner scripts. Ordinary application source commits do not create six expensive
E2E consumers. There is no cron schedule: automatic E2E runs are commit-driven
and path-scoped, while manual dispatch remains available for deliberate
validation. E2E uses native push paths and launches its image producer directly,
without an extra static switchboard job.

Supabase staging and production migrations use the last successful migration
deployment marker as their change-range baseline. Each workflow resolves the
entire pending range, fails open when no trustworthy marker exists, and runs
`supabase db push --include-all` only when `apps/database/**` or migration
control files changed. Evaluation and deployment share one serialized job per
environment, so no-op workflow-run signals finish quickly while database
migrations cannot race. Production still requires the successful same-SHA
platform deployment marker and staging migration before applying changes.

## Runner And Storage Policy

Tuturuuu is a public repository in a GitHub Free organization. Standard hosted
Linux and Windows jobs are budgeted for 4 CPUs and 16 GB RAM; the organization
can run 20 jobs concurrently, including at most 5 macOS jobs. CPU-bound Turbo
checks therefore default to concurrency 4. Memory-heavy Next.js and Docker
stages limit inner build concurrency to 2 and retain an 8 GB Node heap. Keep
independent jobs parallel, keep macOS matrices below the platform limit, and do
not switch to billable larger runners as a cache optimization.

The live repository cache configuration, queried through GitHub's API, is a
10 GB maximum with 7-day retention. The weekly Actions resource report groups
cache usage by key prefix and reports informational status at 80%, warning at
90%, and critical status at 100%. It also reports artifact count, bytes, age,
and largest workflow families without enforcing a fixed artifact byte cap.
Steady-state cache usage should stay below 9 GB to leave eviction headroom.
The July 10 audit observed active usage temporarily above the configured limit;
that is eviction lag and cache churn, not an additional open-source allowance.

Artifacts are retained only as long as their handoff or diagnostic value
requires:

* E2E and Playwright diagnostics: one failure-only artifact per shard or
  migration mode, 7 days.
* Package-release tarballs: 1 day with compression disabled.
* Mobile development deliverables: 7 days; production store deliverables: 14
  days. Pre-compressed bundles are archived first and uploaded without
  redundant compression.
* Discord JUnit and Cloudflare smoke diagnostics: failure-only or explicit
  7-day retention as applicable.

Every artifact upload must declare both retention and missing-file behavior.
Required release outputs fail when absent; optional diagnostics may warn.
Closed trusted pull requests delete cache entries scoped to their merge ref.
Legacy broad Turbo, run-ID Supabase, final Flutter-output, and old Rust cache
prefixes are removed manually only after their replacements demonstrate hits;
default-branch CodeQL caches are never part of automated cleanup.

<Note>
  Earlier versions of these workflows ran an inline Turborepo `--dry-run=json`
  step to *decide* whether to skip a build. That per-workflow skip step has been
  removed in favor of the centralized `ci-check` gate above. Turborepo is now
  used for caching the build itself, not for the run/skip decision.
</Note>

## Race-Condition Handling

Production deployments serialize each app and branch with GitHub Actions
concurrency:

```yaml theme={null}
concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: ${{ github.event_name == 'push' && github.ref == 'refs/heads/production' }}
```

When another production commit arrives, GitHub cancels the superseded run and
keeps the newest run deployable. Older runs no longer finish green after
skipping every deployment step, which makes queued and deployed SHAs
observable without allowing stale artifacts to replace newer production code.
Commits that exist only on `main` and manual recovery dispatches leave an active
production deployment running.

Affected-app gating always diffs the newest SHA against the last successful
deployment marker. If no trustworthy marker is available, the gate fails open
and runs the deployment instead of considering only the newest push payload;
this preserves app changes from canceled intermediate commits.

## Edge Case Handling

`resolve-changed-files.ts` and the gate are written to fail safe.

### Missing or unresolvable change data

If the changed-file set cannot be computed (e.g. an unusual event payload or a
missing base commit), `getWorkflowDecision()` returns `should_run = true`. The
guiding principle: **build when uncertain** rather than skip incorrectly.

### Initial commits and shallow clones

When a parent commit is unavailable (the very first commit, or a shallow clone
without history), the changed-file resolver cannot diff against a base, so the
gate opens and a full build runs. The workflow that needs deeper history checks
out with an appropriate `fetch-depth`, and `ci-check.yml` uses `fetch-depth: 0`
with a sparse checkout so it always has enough history to diff.

### Last-successful-deployment markers

For push events, the resolver can diff against the SHA of the last successful
deployment (recorded as a GitHub deployment marker) rather than only the parent
commit. This catches the case where intermediate commits never deployed, so the
full diff since the last live deploy is considered.

## Monitoring & Debugging

### Inspect the gate decision

`check-workflow-config.ts` logs its decision and the matched paths. Preview
`check-ci` logs show the individual decision; production uses the planner's
**Production Vercel deployment plan** job summary, including the per-app
baseline source and deploy/skip result. Individual logs still look like:

```text theme={null}
Workflow: vercel-production-platform.yaml
Should run: false
Reason: vercel-production-platform.yaml is unaffected by the changed paths
```

or, when it does run:

```text theme={null}
Should run: true
Reason: vercel-production-platform.yaml is affected by 3 changed path(s)
Matched paths:
- apps/web/src/app/page.tsx
- packages/ui/src/button.tsx
```

### Reproduce a decision locally

You can run the decision script directly to debug why a workflow did or did not
run:

```bash theme={null}
CHANGED_FILES="apps/web/src/app/page.tsx" \
WORKFLOW_NAME="vercel-production-platform.yaml" \
node --experimental-strip-types scripts/ci/check-workflow-config.ts
```

There are also unit tests covering the gating logic:

```bash theme={null}
node --test scripts/ci/check-workflow-config.test.js
node --test scripts/ci/resolve-changed-files.test.js
node --test scripts/ci/resolve-production-vercel-targets.test.js
```

### Common Issues

#### Issue: A workflow never runs for legitimate changes

**Likely causes:**

* The app is missing (or misconfigured) in `vercelWorkflowTargets`.
* The changed package is not in the target app's workspace dependency closure
  (the app does not actually `workspace:*`-depend on it).
* The workflow is toggled off in the `ci` map in `tuturuuu.ts`.

**Fix:** Verify the target entry and the dependency edges, then re-run the local
reproduction above to confirm the decision.

#### Issue: A workflow always runs

**Likely causes:**

* A global affecting path (`bun.lock`, `package.json`, `turbo.json`,
  `tuturuuu.ts`) changed — these intentionally trigger every Vercel target.
* The change-data resolver failed, so the gate fell open by design.

This is usually correct behavior; only investigate if it persists for changes
that clearly do not touch shared roots.

#### Issue: Need to force a run

Use the app workflow's manual trigger. A direct `workflow_dispatch` starts that
app without re-running affected-path gating:

```yaml theme={null}
on:
  workflow_dispatch:
```

## Performance Impact

The exact savings depend on the size of the app set and how localized each
commit is, so treat the following as **illustrative** rather than a fixed figure.

The monorepo currently registers **24 active Vercel app targets**, each with a
preview and a production workflow (**48 Vercel deploy workflows**), out of 91
workflow files. Production planning prevents a single-app change from creating
23 unrelated production runners. Preview workflows create a runner only for the
inline platform signal or an explicitly requested satellite preview.

For a change that touches only one app:

```text theme={null}
1 production planner workflow
+ only the affected app deployment workflows
+ one inline platform preview gate on protected main
+ direct satellite preview jobs only when explicitly dispatched
```

Each skipped production app now consumes no runner at all; only the shared
planner and selected reusable deployment jobs run under the production push.
Changes to shared roots
(`package.json`, `bun.lock`, `turbo.json`, `tuturuuu.ts`) intentionally fan out
to all targets, so headline skip rates will vary with how often those roots
change.

<Note>
  To measure real-world impact, inspect the production planner's job summary and
  compare its selected workflow count with the 24 registered targets. Platform
  preview reports its inline decision in the deploy job; manual satellite
  previews have no separate gate job.
</Note>

## Best Practices

### 1. Keep `tuturuuu.ts` as the source of truth

When adding an app or workflow, register Vercel app metadata in
`vercelWorkflowTargets` and register automatic switchboard-controlled workflows
in the `ci` map. Trusted manual satellite previews and intentionally
path-triggered compatibility smokes do not keep unused `ci` toggles. The gate
and the tests key off these boundaries.

### 2. Trust the fail-safe

When change data is missing, the gate opens and the workflow runs. This is
intentional — it is safer to build unnecessarily than to skip a real change.
Don't add ad-hoc skip logic that defeats it.

### 3. Model dependencies with `workspace:*`

The dependency-closure matching only works because shared packages are wired as
`workspace:*` dependencies. If an app consumes shared code without declaring the
dependency, the gate will not know to run it when that package changes.

### 4. Use `workflow_dispatch` to debug

To bypass gating for a one-off investigation, trigger the workflow manually from
the Actions UI rather than touching the gate logic.

### 5. Update tests when changing the gate

`getWorkflowDecision()` and the resolver are covered by unit tests under
`scripts/ci/`. Update them alongside any change to the matching rules so the
behavior stays pinned.

## Further Reading

* [CI/CD Pipelines](/build/development-tools/ci-cd-pipelines)
* [TanStack + Rust migration](/platform/architecture/tanstack-rust-migration)
* [Turborepo: Remote Caching](https://turborepo.com/docs/core-concepts/remote-caching)
* [GitHub Actions: Reusing workflows](https://docs.github.com/en/actions/using-workflows/reusing-workflows)

## Summary

Our CI/CD optimization centralizes change detection so each workflow stays thin:

* Reusable `ci-check.yml` calls remain available where a separate gate is
  necessary; production planning and platform preview avoid per-app preflight
  fan-out.
* `tuturuuu.ts` decides, per workflow, whether the change is relevant — including
  workspace dependency-closure awareness for shared packages.
* The remote-cache wrapper keeps Turbo credentials step-scoped and gives
  secretless jobs a GitHub-backed local fallback.
* Turborepo caches full app builds, type checks, tests, and release preparation
  once a run is warranted.
* The gate fails safe (builds on uncertainty), and trusted manual satellite
  previews start their guarded deploy job directly.

The result: a one-app change selects only the necessary production deploys in
the commit-associated push run,
platform preview retains its required staging signal without a second runner,
manual previews never queue a redundant preflight, and superseded previews are
canceled before they occupy the queue indefinitely.


# CI/CD Pipelines
Source: https://docs.tuturuuu.com/build/development-tools/ci-cd-pipelines

High-level CI/CD overview, with current operational runbooks linked from one place.

This page is the entry point for CI/CD. The day-to-day operational detail now lives
in the dedicated DevOps pages below so the docs stay current as workflows change.

## Read Next

* [DevOps & Deployment Overview](/build/devops/overview)
* [Environments & Release Flow](/build/devops/environments-release-flow)
* [Web Docker Deployment](/build/devops/web-docker-deployment)
* [GitHub Actions Runbook](/build/devops/github-actions-runbook)
* [Secrets & Configuration](/build/devops/secrets-and-configuration)

## Current CI/CD Shape

Tuturuuu currently automates:

* Vercel preview deployments for non-`production` branches
* Vercel production deployments from the `production` branch
* Independent Vercel preview and production deployments for satellite apps such as `apps/cms`
* Affected-app gating for Vercel deployments before dependency install, build, or deploy work
* Supabase staging migrations driven from `main` and production migrations driven from `production`
* Docker parity and image validation for the self-hosted web runtime
* Modal deployment for `apps/discord`
* Mobile build artifact generation
* Package publishing to npm
* Quality, lint, type, test, and security checks

## Important Repo Conventions

* `ci-check.yml` reads `tuturuuu.ts` and can disable an individual workflow centrally.
* Vercel workflows use `tuturuuu.ts` app metadata and workspace `workspace:*` dependency closures to run only affected app deploys.
* `bun.lock` changes run all Vercel app deploys because lockfile ownership is ambiguous without a source or manifest path.
* Manual `workflow_dispatch` runs enabled workflows even when changed paths would otherwise be unaffected.
* Production Vercel workflows cancel superseded per-app runs only for newer
  `production` pushes. A `main` commit or manual recovery run never cancels an
  active production deployment.
* The external-app internal-package build uses the same cancel-superseded policy, so rapid pushes cannot finish as green no-op builds.
* Database migrations are not treated the same as app deploys; staging and production each have explicit prerequisite logic, with staging now sourced from `main`.
* Docker changes are guarded by `docker-setup-check.yaml`, including dev and production image builds.

## When To Use This Page

Use this page for orientation. Use the DevOps pages for the runbook you actually need
while operating the system.


# Cleaning Your Tuturuuu Clone
Source: https://docs.tuturuuu.com/build/development-tools/cleaning-clone

How to reset your local Tuturuuu repository to a clean state.

<Info>
  This guide helps you reset your Tuturuuu repository to a clean state, which is
  useful if you encounter dependency issues or want to ensure a fresh
  development environment.
</Info>

## Prerequisites

* Ensure you have [bun](https://bun.sh/) installed. The repository pins a specific
  Bun version via the `packageManager` field in the root `package.json` (currently
  `bun@1.3.14`) — match that version so your local toolchain stays in sync.
* Node `>=22` is also required (see the `engines` field in the root `package.json`).

## Quick Cleanup (Recommended)

The repository ships a one-shot root script that performs the full cleanup for you:

```bash theme={null}
bun clean
```

This removes `bun.lock`, deletes every `node_modules` directory, and clears all
`.next` and `.turbo` build caches across the monorepo (it uses
`npkill --delete-all` under the hood). After it finishes, reinstall everything:

```bash theme={null}
bun i
```

<Tip>
  `bun clean` is the supported shortcut for the manual steps below. Reach for the
  manual steps when you want finer control over which folders are removed.
</Tip>

## Manual Cleanup (Granular Alternative)

### 1. Delete the lockfile

Remove the `bun.lock` file at the root of your repository (if it exists):

```bash theme={null}
rm bun.lock
```

### 2. Remove all `node_modules` folders

Use [npkill](https://github.com/voidcosmos/npkill) to find and remove all `node_modules` directories:

```bash theme={null}
bunx npkill
```

* In the `npkill` interface, select and delete all `node_modules` folders found in your repo.

<Tip>
  If you don't have `npkill` installed, `bunx` will download and run it
  automatically.
</Tip>

### 3. Clear build caches (optional)

Remove stale `.next` and `.turbo` build caches if you suspect they are causing
issues (the `bun clean` shortcut does this automatically):

```bash theme={null}
find . -name node_modules -prune -o \( -name .next -o -name .turbo \) -type d -exec rm -rf {} +
```

### 4. Reinstall dependencies

Install all required dependencies using bun:

```bash theme={null}
bun i
```

This will install fresh dependencies for all apps and packages in the monorepo.

<Info>
  After completing these steps, your repository should be in a clean state. You
  can now continue with the usual development workflow as described in
  <a href="/build/development-tools/development">Development</a>.
</Info>

## Troubleshooting

* If you still encounter issues, try restarting your IDE or terminal.
* Make sure your bun version is up to date: `bun upgrade`.
* If problems persist, check the [Development](/build/development-tools/development) guide or ask for help in the project discussions.


# Codex Plugin
Source: https://docs.tuturuuu.com/build/development-tools/codex-plugin

Use and maintain the local Tuturuuu Codex plugin.

The local Tuturuuu Codex plugin lives at `plugins/tuturuuu`. It packages
repo-specific operating knowledge as Codex skills so future agent sessions can
load focused guidance without copying long instructions into every prompt.

## Discovery

Codex discovers repo-local plugins through
`.agents/plugins/marketplace.json`. The Tuturuuu marketplace is named
`tuturuuu`, displays as `Tuturuuu`, and points its local plugin entry at
`./plugins/tuturuuu`.

After changing marketplace metadata or plugin files, validate the plugin and
refresh the repo-local marketplace from the repo root. Do not bump
`plugins/tuturuuu/.codex-plugin/plugin.json` `version` for ordinary authored
workflow updates unless a release workflow or user request requires it.
The repo-local plugin manifest is currently refreshed to `0.2.23`.

```bash theme={null}
codex plugin marketplace add ./
```

Restart Codex after refreshing the marketplace. Then open the plugin directory,
choose the `Tuturuuu` marketplace, and install or update the `Tuturuuu` plugin.

If Codex does not show the repo marketplace after restart, add the repo root as
a local marketplace source from the CLI:

```bash theme={null}
codex plugin marketplace add ./
```

## skills.sh Discovery

The public skills.sh registry discovers skills from GitHub repositories after
someone installs the repo with the `skills` CLI. The platform repo exposes the
Tuturuuu plugin skills for that flow through two root metadata files:

* `.claude-plugin/marketplace.json` points compatible skill installers at
  `plugins/tuturuuu/skills`.
* `skills.sh.json` groups the public repo page so Tuturuuu skills appear ahead
  of unrelated installed project skills.

Do not run the public install trigger before the metadata is pushed to GitHub.
After pushing the metadata commit, run the trigger from a disposable directory,
not from this checkout:

```bash theme={null}
npx skills add tutur3u/platform --agent codex --copy -y \
  --skill tuturuuu-agent-coordination \
  --skill tuturuuu-browser-vercel-debugging \
  --skill tuturuuu-ci-docs \
  --skill tuturuuu-cli \
  --skill tuturuuu-cli-finance \
  --skill tuturuuu-cli-tasks \
  --skill tuturuuu-cms-studio \
  --skill tuturuuu-commit \
  --skill tuturuuu-database \
  --skill tuturuuu-devbox-ops \
  --skill tuturuuu-development-tooling \
  --skill tuturuuu-e2e-auth-debugging \
  --skill tuturuuu-external-apps \
  --skill tuturuuu-mobile-task-board \
  --skill tuturuuu-platform \
  --skill tuturuuu-pr-merge-sync \
  --skill tuturuuu-review-comments \
  --skill tuturuuu-satellite-app-ux \
  --skill tuturuuu-validation-offload \
  --skill tuturuuu-web-release
```

Then verify the cached page after refresh at
`https://skills.sh/tutur3u/platform`.

## Included Skills

* `$tuturuuu-platform`: repo-wide workflow guidance for `apps/web`,
  `packages/*`, `apps/database`, `apps/docs`, translations, navigation, and
  verification follow-through, including shared-worktree preflight, scoped
  staging expectations, and Effect adoption guidance for TypeScript
  server/service orchestration.
* `$tuturuuu-browser-vercel-debugging`: authenticated Browser/Chrome and Vercel
  CLI guidance for reproducing deployed UI/API bugs, correlating runtime and
  build logs, checking satellite routing/auth, auditing responsive and i18n
  behavior, investigating performance/cost, and verifying improvements without
  mutating customer data.
* `$tuturuuu-cms-studio`: CMS and external-project content studio guidance for
  `apps/cms`, branded project adapters, landing-page content editing, content
  collections, media workflows, preview delivery, and non-technical editor UX.
* `$tuturuuu-satellite-app-ux`: standalone app shell guidance for satellite apps
  such as Mail and CMS, including `@tuturuuu/satellite` auth, app-session
  routes, i18n, workspace navigation, permissions, and focused operational UX.
* `$tuturuuu-external-apps`: external and branded sibling app integration
  guidance for app-token exchange, refreshable admin sessions, direct signed
  storage uploads, external-project mutations, delivery fallbacks, and
  sanitized diagnostics.
* `$tuturuuu-e2e-auth-debugging`: local E2E authentication guidance for native
  Playwright patch iteration, `dev-session`, guest access, onboarding
  redirects, app-session verification, rate-limit tests, and explicit
  Docker-parity auth checks.
* `$tuturuuu-commit`: scoped commit workflow guidance for explicit commit,
  commit-and-push, atomic staging, Conventional Commit subjects, shared-worktree
  path isolation, commit-window claim/wait/release, proof-gated no-verify
  commit evidence, hook failure handling, and final commit reporting.
* `$tuturuuu-agent-coordination`: shared-worktree coordination guidance for
  dirty checkouts, active ownership notes, archived context, overlapping edits,
  stale handoffs, explicit write sets, commit-window coordination, and
  path-scoped staging safety.
* `$tuturuuu-cli`: core native `ttr` CLI install, browser login, copy-token
  login, workspace discovery, scoped help, SDK-backed command surfaces, task
  template command boundaries, version checks, and release verification
  guidance. It documents autonomous Bun and CLI installation with
  `curl -fsSL https://bun.sh/install | bash` on macOS/Linux,
  `powershell -c "irm bun.sh/install.ps1 | iex"` on Windows, then
  `bun i -g tuturuuu`.
* `$tuturuuu-cli-tasks`: focused `ttr tasks` and `ttr task-templates` guidance
  for task capture, task board/list/label discovery, open-task defaults,
  compact task tables, task creation, reusable task-template import/export,
  template instantiation, splitting, movement, completion, closure, and task
  verification. It documents ttr-first task capture for requests to add, create,
  template, track, or split Tuturuuu tasks, including label discovery and
  closing superseded combined tasks after replacements are created.
* `$tuturuuu-cli-finance`: focused `ttr finance` guidance for wallet,
  transaction, category, budget, and recurring CRUD; analytics reads; finance
  pagination footers; explicit-workspace finance read diagnostics; and wrapped
  finance response normalization in the SDK client.
* `$tuturuuu-development-tooling`: shared guidance for improving Codex skills,
  plugin behavior, validation scripts, docs runbooks, helper scripts, and
  durable workflow learnings that should benefit future Tuturuuu contributors
  and assistants, including Turborepo/Next cache boundaries, local dev-speed
  diagnostics, release-please merge automation, and package release automation
  rules.
* `$tuturuuu-pr-merge-sync`: PR closeout guidance for quiet-window review
  watching, efficient GitHub polling, merge/admin-merge follow-through, the hard
  main-green gate before `bun git-sync`, production sync, and production
  workflow verification.
* `$tuturuuu-devbox-ops`: operational guidance for `ttr box` setup, runner
  registration, one-shot smoke tests, 24/7 system services, runner-token
  cleanup, CLI upgrades, and infrastructure devbox observability.
* `$tuturuuu-validation-offload`: validation strategy guidance for deciding
  when to run focused tests, `bun check`, Supabase, Docker, or browser-heavy
  workflows through internal devboxes instead of the local agent session.
* `$tuturuuu-web-release`: `apps/web` release badge metadata, blue/green
  runtime snapshot fallback, `PLATFORM_BUILD_*` precedence, and
  release-please-managed `TUTURUUU_PLATFORM_VERSION` guidance.
* `$tuturuuu-mobile-task-board`: Flutter mobile task-board guidance for task
  dates, overdue behavior, task detail routing, description mode, assignee
  flows, and release-please-managed mobile version metadata.
* `$tuturuuu-database`: Supabase migration, RLS, workspace-scoped API write,
  generated type, storage, and database verification guidance.
* `$tuturuuu-ci-docs`: GitHub Actions, `tuturuuu.ts`, validation script,
  docs-page, and docs navigation guidance.
* `$tuturuuu-review-comments`: GitHub PR review-thread guidance for checking,
  re-checking, validating, fixing, resolving, and committing unresolved review
  comments. Addressed review threads are resolved by default after validation;
  commits and pushes still require an explicit user request. Its bundled
  `fetch_review_threads.py` helper supports `--active-only --summary` and emits
  review-thread counts for final re-check reports.

## Translation Key Workflow

When a platform change introduces a new translation key, prefer the root helper
instead of editing message JSON by hand:

```bash theme={null}
bun i18n:add --app web --key common.save --value en=Save --value vi=Lưu
```

Use `--dir apps/<app>/messages` for non-standard message directories and
`--all` only for shared UI keys that must exist in every detected app message
setup. The helper detects locale JSON files in the target setup, requires a
value for each locale, blocks unsafe key paths, prevents accidental overwrites
unless `--overwrite` is passed, and writes sorted JSON. Manual message edits are
reserved for broad copy rewrites or value-only updates; run `bun i18n:sort`
after those edits.

For larger translation updates, use bulk modes instead of repeatedly editing
JSON:

```bash theme={null}
bun i18n:add --app web --mode add --entries '{"common.save":{"en":"Save","vi":"Lưu"}}'
bun i18n:add --app web --mode remove --entries '["common.old"]'
bun i18n:add --app web --mode replace --entries-file ./translations.json
```

Bulk add and replace entries use a JSON object keyed by translation key, with
locale values underneath each key. Bulk remove accepts an array of translation
keys. Replace and remove fail when a key is missing unless `--ignore-missing` is
passed.

## CI Coverage

`.github/workflows/codex-plugin.yaml` runs the plugin-local validator and parses
the docs navigation JSON. The workflow is enabled through `tuturuuu.ts`, matching
the repo's other CI switchboard-controlled checks.

The CI check currently verifies:

* plugin manifest JSON and interface metadata
* natural default prompt examples for the invokable skills, written as short
  user requests instead of visible `$skill` commands
* dedicated prompt coverage for CMS studio and landing-page content management
* dedicated prompt coverage for external app integrations and direct uploads
* dedicated prompt coverage for satellite app UX and app-session workflows
* dedicated prompt coverage for native local E2E auth and dev-session debugging
* dedicated prompt coverage for browser and Vercel production troubleshooting
* dedicated prompt coverage for shared-worktree coordination and agent handoff
* dedicated prompt coverage for PR quiet-window merge sync with main-green
  gating before production sync
* dedicated prompt coverage for devbox runner operations and validation offload
* dedicated prompt coverage for web release badge metadata
* durable CI tooling guidance for npm package release auto-recovery
* durable CI tooling guidance for Supabase CLI setup retry and GitHub-tokened
  release lookup
* durable CI tooling guidance for bounded Codecov coverage test retries
* scoped commit workflow coverage for explicit commit requests
* native `ttr` task-template workflow coverage in the CLI task skill
* proof-gated no-verify commit evidence coverage
* commit-window claim, wait, release, and stale-lock guidance
* repo marketplace metadata at `.agents/plugins/marketplace.json`
* public skills.sh discovery metadata at `.claude-plugin/marketplace.json`
* public skills.sh grouping metadata at `skills.sh.json`
* skill folder and frontmatter naming parity
* `agents/openai.yaml` defaults for every skill
* skill `references/` links
* plugin docs page registration in `apps/docs/docs.json`
* Codex plugin workflow registration in `tuturuuu.ts`
* absence of scaffold `[TODO: ...]` placeholders
* absence of machine-specific local paths in plugin text

## Shared Worktree Coordination

Agents should assume that humans or other agents may have uncommitted work in the
same checkout. The docs-facing protocol lives in the
[Agent Operating Manual](/overview/agent-operating-manual#shared-worktree-coordination),
and the agent-facing workflow lives in `$tuturuuu-agent-coordination`.

Open Tuturuuu pull requests are always handled in isolated worktrees under
`.worktrees/`. Run `bun setup` immediately after creating the PR worktree, keep
the worktree and local task branch while the PR is open, and remove both only
after the merge is confirmed on `main` and post-merge verification is complete.
This lifecycle is documented in the Agent Operating Manual and enforced as a
cross-cutting rule in `AGENTS.md`.

For user-authorized continuous integration, the same lifecycle applies to each
verified checkpoint: integrate it into current `main`, require the exact main
SHA to be fully green, run `bun git-sync`, verify production, then remove only
the completed worktree and local task branch. Rust-heavy retained worktrees use
`bun rust-cache report` plus bounded `prune`/`auto` cleanup rather than broad
filesystem deletion.

Use `tmp/agent-coordination/` for lightweight agent-to-agent notes when work may
overlap, the worktree is dirty, the task is long-running, or the task changes
agent workflow rules. The directory is ignored by git, so it can hold live
intent, ownership, status, verification, risk, and handoff messages without
polluting commits.

Active notes are notes marked `working`, `blocked`, or `handoff`. Treat stale
active notes as ownership signals until you have read them and checked the
current worktree. Keep active notes as direct files under
`tmp/agent-coordination/`; archive completed notes under
`tmp/agent-coordination/archive/<YYYY>/<original-note-name>.md` after they are
marked `done` and no longer need top-level visibility.

Use `bun git-commit-window` before changing the staged set or creating commits
in a shared checkout. `claim` creates an advisory lock under
`tmp/agent-coordination/git-commit-window.lock.json`; `wait` sleeps until the
current lock is released or expires, then claims it before notifying the waiting
agent that it can commit. Claims default to 10 minutes, accept only 5-10-minute
TTLs, and should be held only while staging, inspecting, committing, amending,
rebasing, or finishing commit-and-push follow-through. Release the lock with
`bun git-commit-window release --token <token>` after the commit operation
finishes or aborts, and do not record tokens in coordination notes.

Archived notes are historical context for targeted lookup, not locks. Agents
should search them by path, feature, or workflow only when previous decisions or
verification matter to the current task. If another active note claims the same
file set, agents should choose non-overlapping slices, write a response note, or
ask the human partner to arbitrate. They should never format, stage, or fix
unrelated dirty files simply because a repo-wide check or commit hook reports
them.

When coordinating subagents, split work into named lanes with disjoint owned
paths, excluded paths, validation commands, and a no-stage/no-commit boundary
unless the lane explicitly owns a commit. The coordinator owns integration and
shared generated artifacts by default, including TanStack route trees, migration
manifests, route overrides, OpenAPI snapshots, docs navigation, sorted
translation bundles, and Supabase generated types. Workers should report
generated drift and hand off exact follow-up instead of silently committing it.
When a generator can see dirty or untracked files owned by another lane,
regenerate from a clean worktree or an explicit input set and copy back only the
intended artifact.

Write a lane contract before spawning: owner, mode, owned paths, excluded paths,
generated outputs, validation, handoff shape, and commit authority. Read-only
lanes return evidence and risks without taking ownership. In Codex, choose
either a typed worker/explorer role with explicit lane context in the prompt or
a full-history fork without a role override; the harness rejects a spawn request
that asks for both. After integrating a
slice, checkpoint before dispatching more work: refresh status, close completed
subagents, update the parent note with the commit or handoff state, list
validation and unrelated blockers, and choose the next lane from the current
worktree state.

The normal scoped commit path still lets Git hooks run. Agents may use
`git commit --no-verify` only when they can produce a proof packet for their
exact staged paths: reviewed status and staged diff output, path ownership,
separated validation mapped to the relevant `bun check` components, path-based
rationale for skipped components, and `bun check:mobile` coverage when
`apps/mobile` is touched. Incomplete proof, unclear ownership, or uncertain
check mapping means the hook should run or the risk should be reported instead
of bypassed.

## AGENTS.md Split

Root `AGENTS.md` is intentionally a compact hard-policy index. Detailed
implementation gotchas and composable patterns live in focused Tuturuuu skill
references instead:

* web/API/shared UI patterns in `$tuturuuu-platform`
* release badge/version metadata in `$tuturuuu-web-release`
* database/API/storage patterns in `$tuturuuu-database`
* CI/root-script/tooling patterns in `$tuturuuu-development-tooling`
* Docker blue/green watcher patterns in `$tuturuuu-ci-docs`
* mobile task-board and overlay patterns in `$tuturuuu-mobile-task-board`

When a session reveals durable knowledge, update the narrowest matching skill
reference and docs page. Add to root `AGENTS.md` only when the rule is a
cross-cutting hard mandate that agents must see before skill loading.

## Validate The Plugin

Run the local validator after changing the plugin manifest or its skills:

```bash theme={null}
python3 plugins/tuturuuu/scripts/validate_plugin.py
```

The local validator also checks the root skills.sh metadata files against the
actual Tuturuuu skill folders, so add every new public skill to both
`.claude-plugin/marketplace.json` and `skills.sh.json`.

For individual skills, run the Codex skill validator:

```bash theme={null}
python3 ~/.codex/skills/.system/skill-creator/scripts/quick_validate.py plugins/tuturuuu/skills/tuturuuu-platform
python3 ~/.codex/skills/.system/skill-creator/scripts/quick_validate.py plugins/tuturuuu/skills/tuturuuu-cms-studio
python3 ~/.codex/skills/.system/skill-creator/scripts/quick_validate.py plugins/tuturuuu/skills/tuturuuu-satellite-app-ux
python3 ~/.codex/skills/.system/skill-creator/scripts/quick_validate.py plugins/tuturuuu/skills/tuturuuu-e2e-auth-debugging
python3 ~/.codex/skills/.system/skill-creator/scripts/quick_validate.py plugins/tuturuuu/skills/tuturuuu-external-apps
python3 ~/.codex/skills/.system/skill-creator/scripts/quick_validate.py plugins/tuturuuu/skills/tuturuuu-commit
python3 ~/.codex/skills/.system/skill-creator/scripts/quick_validate.py plugins/tuturuuu/skills/tuturuuu-agent-coordination
python3 ~/.codex/skills/.system/skill-creator/scripts/quick_validate.py plugins/tuturuuu/skills/tuturuuu-cli
python3 ~/.codex/skills/.system/skill-creator/scripts/quick_validate.py plugins/tuturuuu/skills/tuturuuu-cli-tasks
python3 ~/.codex/skills/.system/skill-creator/scripts/quick_validate.py plugins/tuturuuu/skills/tuturuuu-cli-finance
python3 ~/.codex/skills/.system/skill-creator/scripts/quick_validate.py plugins/tuturuuu/skills/tuturuuu-development-tooling
python3 ~/.codex/skills/.system/skill-creator/scripts/quick_validate.py plugins/tuturuuu/skills/tuturuuu-devbox-ops
python3 ~/.codex/skills/.system/skill-creator/scripts/quick_validate.py plugins/tuturuuu/skills/tuturuuu-validation-offload
python3 ~/.codex/skills/.system/skill-creator/scripts/quick_validate.py plugins/tuturuuu/skills/tuturuuu-web-release
python3 ~/.codex/skills/.system/skill-creator/scripts/quick_validate.py plugins/tuturuuu/skills/tuturuuu-mobile-task-board
python3 ~/.codex/skills/.system/skill-creator/scripts/quick_validate.py plugins/tuturuuu/skills/tuturuuu-database
python3 ~/.codex/skills/.system/skill-creator/scripts/quick_validate.py plugins/tuturuuu/skills/tuturuuu-ci-docs
python3 ~/.codex/skills/.system/skill-creator/scripts/quick_validate.py plugins/tuturuuu/skills/tuturuuu-review-comments
```

The Codex skill validator imports `yaml`, so it requires `PyYAML` in the active
Python environment. The plugin-local validator uses only the Python standard
library.

## Maintenance Rules

* Keep `plugins/tuturuuu/.codex-plugin/plugin.json` aligned with the plugin
  folder name. Do not bump its `version` for ordinary authored work unless a
  release workflow or user request requires it; when a user explicitly asks for
  a plugin refresh, bump the manifest and keep this page current.
* Keep each skill folder name aligned with its `SKILL.md` frontmatter `name`.
* Keep plugin and skill default prompts short, natural, and action-oriented.
  Marketplace prompt cards should read like user goals, for example "Clear the
  unresolved review comments on this PR."
* Keep skill text portable across machines. Prefer repo-relative paths,
  `<repo-root>`, or `~` over user-specific absolute paths.
* Put detailed guidance in `references/` and keep `SKILL.md` focused on the
  workflow that should be loaded immediately.
* Keep shared-worktree and commit-window coordination guidance aligned across
  `AGENTS.md`, the Agent Operating Manual, `$tuturuuu-agent-coordination`, and
  `$tuturuuu-commit`.
* Keep the open-PR `.worktrees/` lifecycle, immediate `bun setup`, and
  post-merge worktree/branch cleanup guidance aligned across `AGENTS.md`, the
  Agent Operating Manual, `$tuturuuu-agent-coordination`, the platform
  checklist, and `$tuturuuu-pr-merge-sync`. Keep the authorized continuous
  integration, main-green, `bun git-sync`, production verification, and bounded
  Rust-cache cleanup rules aligned on those same surfaces.
* Keep parallel subagent lane, staged-set ownership, generated-artifact
  ownership, and hook-failure guidance aligned across the Agent Operating
  Manual, `$tuturuuu-agent-coordination`, `$tuturuuu-commit`, and Git
  conventions docs.
* Keep platform release/version guidance aligned across `AGENTS.md`,
  `$tuturuuu-web-release`, and the Web Docker Deployment runbook.
* Add marketplace metadata only when deciding where the plugin should be
  installed from: repo-local `.agents/plugins/marketplace.json` or home-local
  `~/.agents/plugins/marketplace.json`.
* Keep public skills.sh metadata aligned across `.claude-plugin/marketplace.json`
  and `skills.sh.json`; do not modify `.agents/skills` just to publish the
  Tuturuuu plugin skills.


# Development
Source: https://docs.tuturuuu.com/build/development-tools/development

Learn how to preview changes locally.

<Info>
  **Prerequisite**: You should have installed [Node.js](https://nodejs.org)
  (version 22 or higher, matching the repo's `engines.node` of `>=22`).
</Info>

## Installation

Step 1. Install [bun](https://bun.sh/docs/installation) on your machine (if you don't already have it yet), by running the following command:

**macOS/Linux:**

```bash theme={null}
curl -fsSL https://bun.sh/install | bash
```

**Windows:**

```bash theme={null}
powershell -c "irm bun.sh/install.ps1 | iex"
```

## Why Bun?

We chose bun as our runtime and package manager based on its [design goals](https://bun.sh/docs#design-goals), which align perfectly with our platform's needs:

* **4x Faster Startup**: Bun processes start significantly faster than Node.js, improving development experience and CI/CD performance
* **Built-in TypeScript & JSX Support**: No need for additional transpilation setup - bun natively executes `.ts`, `.tsx`, and `.jsx` files
* **All-in-One Toolkit**: Combines runtime, package manager, bundler, test runner, and script runner in a single executable
* **Web Standards Compatibility**: Implements modern Web APIs like `fetch`, `WebSocket`, and `ReadableStream` out of the box
* **Node.js Compatibility**: Drop-in replacement for Node.js with full compatibility for existing projects
* **Better Performance**: Powered by JavaScriptCore engine with reduced memory usage and faster execution

These benefits make bun an ideal choice for our monorepo architecture and development workflow.

Step 2. **Configure Tiptap Pro Registry:**

<Warning>This step is no longer needed.</Warning>

Step 3. After configuring Tiptap Pro registry, you can install all dependencies by running the following command:

<CodeGroup>
  ```bash standard theme={null}
  bun install
  ```

  ```bash short-hand theme={null}
  bun i
  ```
</CodeGroup>

This repository's Bun configuration enforces a minimum release age of 1 day for
new npm package versions. If Bun skips a just-published release during install,
wait for the package to age past the gate or choose an older published version.

To complete the initial setup, please restart your IDE so that it can recognize the newly installed dependencies. Additionally, some recommended VS Code Extensions may only work after restarting your IDE.

<Tip>
  If you're using VS Code, you can install following the recommended extensions
  that will help you with the development process:
  [Biome](https://marketplace.visualstudio.com/items?itemName=biomejs.biome)
  (this repo standardizes on Biome for linting and formatting via `biome.json`,
  not ESLint or Prettier),
  [Vitest](https://marketplace.visualstudio.com/items?itemName=vitest.explorer),
  [Tailwind CSS
  IntelliSense](https://marketplace.visualstudio.com/items?itemName=bradlc.vscode-tailwindcss),
  [Version
  Lens](https://marketplace.visualstudio.com/items?itemName=pflannery.vscode-versionlens),
  [Error
  Lens](https://marketplace.visualstudio.com/items?itemName=usernamehw.errorlens),
  [Pretty TypeScript
  Errors](https://marketplace.visualstudio.com/items?itemName=YoavBls.pretty-ts-errors),
  [Material Icon
  Theme](https://marketplace.visualstudio.com/items?itemName=PKief.material-icon-theme).
</Tip>

### Zed

This monorepo tracks project-level Zed settings in `.zed/settings.json`.
Opening the repository root in Zed can otherwise trigger expensive scans across
generated output and local dependency trees, especially `node_modules`,
`.turbo`, `.next`, package `dist` directories, Flutter build output, Rust
`target`, and Python virtualenv/cache folders.

Keep large generated directories in `file_scan_exclusions`. Zed's
`file_scan_exclusions` setting replaces the default list instead of extending
it, so include Zed's default VCS/system exclusions whenever adding project
exclusions. The project uses TypeScript 7 RC's `tsc` for compiler checks and a
single TypeScript language server path for TypeScript, TSX, and JavaScript;
avoid enabling competing TypeScript language servers for the same language
unless you are deliberately comparing language server behavior.

## Development

### Start Next.js apps

To develop all apps and packages (without requiring a local setup), run the following command:

```bash bun theme={null}
bun dev
```

<Info>
  This command will start all Next.js apps in development mode. You can access
  the platform app by visiting the following URL:
  [https://tuturuuu.localhost](https://tuturuuu.localhost)
</Info>

Local app development uses Portless, so each app gets a stable Tuturuuu
subdomain instead of relying on its fallback port. The app package `dev`
scripts run the repo's Portless-safe wrapper, and the underlying framework
command remains available through `dev:app` for direct port-based debugging.

The wrapper only removes stale static aliases for the same app when their
default backend port is closed, then starts Portless with the original app
config. This fixes old worktree aliases such as
`zalo-qr-chat-setup.tuturuuu.localhost` without cleaning certificates, deleting
unrelated routes, or touching other apps' active aliases. Package-local
`bun dev --force` delegates to `portless run --name <app> --force` so Portless
can take over a live route when you explicitly request it.

Root app-specific commands such as `bun dev:chat`, `bun dev:calendar`, and
`bun dev:edu` reuse app servers that are already running. The launcher checks
active Portless routes first, then the app's default localhost port; if it finds
a direct localhost listener, it tries to register a matching Portless alias so
cross-app auth can still use the `*.tuturuuu.localhost` URL. Pass `--force` or
`--no-reuse` when you intentionally want the command to include already-running
app workspaces. Force mode starts the package `dev --force` path so Portless can
take over the matching route instead of leaving a stale static alias in place.

`bun dev:tanstack-web` starts the TanStack Start migration frontend at
`https://tanstack.tuturuuu.localhost`, with fallback port `7824`. It is the
dedicated frontend for the Next.js-to-TanStack migration and should call
Rust-owned APIs through `packages/internal-api` helpers instead of direct
browser access to protected `apps/web` routes. See
`platform/architecture/tanstack-rust-migration` for the route manifest, Docker,
E2E, benchmark gates, and Cloudflare Workers preparation.

For the Cloudflare-compatible preview shape, start the Worker entrypoints
instead of the normal Portless dev wrapper:

```bash theme={null}
bun wrangler dev --config apps/backend/wrangler.jsonc
bun --cwd apps/tanstack-web run preview:cloudflare
```

Use the same environment variable names as deployment:
`BACKEND_INTERNAL_TOKEN`, `BACKEND_PUBLIC_ORIGIN`, and
`BACKEND_INTERNAL_URL`. Keep values in your shell or ignored local env files;
do not add literal tokens or account-specific origins to docs, Wrangler config,
package manifests, or source. After deploying preview Workers, run
`bun smoke:cloudflare` with `BACKEND_WORKER_ORIGIN`,
`TANSTACK_WEB_WORKER_ORIGIN`, and `BACKEND_INTERNAL_TOKEN` to verify backend
health/readiness, protected migration status, missing/invalid token rejection,
and the TanStack root shell.

`bun dev:web` is intentionally lean: by default it starts only `apps/web` and
does not start the `@tuturuuu/types` or `@tuturuuu/supabase` package watch
builds. Use this default for app-route and UI work so the local process tree
stays small. When you are actively editing those package sources and need their
`dist` output rebuilt live, opt in explicitly:

```bash theme={null}
bun dev:web --with-shared-watchers
```

You can also pass `--no-shared-watchers` to other root app launchers when you
want the same low-memory posture for a focused app session.

`apps/web` does not mount React Query Devtools in its default development
provider. Keep the default off for faster cold route compiles and lower
Turbopack memory pressure; add a local, temporary devtools mount only while
debugging query cache behavior, then remove it before committing.

Keep the always-mounted public shell small. The mobile menu drawer, marketing
footer body, report-problem dialog, and authenticated dropdown-only affordances
should stay behind dynamic imports when possible, and shell icons should use
`@tuturuuu/icons/lucide-static` instead of the root `@tuturuuu/icons` entrypoint.
This prevents the public `/login` compile graph from pulling large Radix,
footer, or full icon-package chunks into every `bun dev:web` session.

`bun dev:chat` also manages the local chat realtime sidecar. It reuses
`localhost:7817` when a sidecar is already running; otherwise it starts
`apps/chat-realtime` so `apps/web` can proxy chat SSE traffic for `apps/chat`.

| App           | Local URL                                  |
| ------------- | ------------------------------------------ |
| Platform      | `https://tuturuuu.localhost`               |
| Calendar      | `https://calendar.tuturuuu.localhost`      |
| Chat          | `https://chat.tuturuuu.localhost`          |
| CMS           | `https://cms.tuturuuu.localhost`           |
| Drive         | `https://drive.tuturuuu.localhost`         |
| External      | `https://external.tuturuuu.localhost`      |
| Finance       | `https://finance.tuturuuu.localhost`       |
| Hive          | `https://hive.tuturuuu.localhost`          |
| Hive Realtime | `https://realtime.hive.tuturuuu.localhost` |
| Infra         | `https://infra.tuturuuu.localhost`         |
| Inventory     | `https://inventory.tuturuuu.localhost`     |
| Learn         | `https://learn.tuturuuu.localhost`         |
| Mail          | `https://mail.tuturuuu.localhost`          |
| Meet          | `https://meet.tuturuuu.localhost`          |
| Mind          | `https://mind.tuturuuu.localhost`          |
| Nova          | `https://nova.tuturuuu.localhost`          |
| Playground    | `https://playground.tuturuuu.localhost`    |
| QR            | `https://qr.tuturuuu.localhost`            |
| Rewise        | `https://rewise.tuturuuu.localhost`        |
| Shortener     | `https://shortener.tuturuuu.localhost`     |
| Tasks         | `https://tasks.tuturuuu.localhost`         |
| Teach         | `https://teach.tuturuuu.localhost`         |
| Track         | `https://track.tuturuuu.localhost`         |

When debugging without Portless, run an app's `dev:app` script directly. If
auth redirects or absolute links must stay on the raw listener port, set
`BASE_URL`, `WEB_APP_URL`, or the app-specific URL environment variable to that
legacy fallback port for the direct debug session.

Keep runtime defaults, auth redirects, and cross-app links on the Portless
origins during local development. Use the shared local app URL helpers instead
of hard-coding `localhost` fallbacks in satellite app constants or proxies, so a
browser session that starts on `tasks.tuturuuu.localhost` stays under the
`tuturuuu.localhost` namespace through login and return URLs.

For a native production-mode smoke test of `apps/web`, run the native build and
then start it through the same Portless hostname:

```bash theme={null}
bun run build:web
cd apps/web
bun run start
```

`bun run start` delegates to Portless and runs the built Next.js server through
`start:app`, so the browser URL remains `https://tuturuuu.localhost` while the
server listens on the backend port that Portless injects through `PORT`.

Use `bun dev:edu` when working on the education apps together. It starts Learn,
Teach, their shared packages, and the central web app so cross-app login can
complete locally.

Next.js still prints the internal listener port, for example
`http://localhost:4803`, because Portless assigns a free backend port to the app
process. App `dev:app` scripts also print a `Portless URL:` line from the
`PORTLESS_URL` environment variable; use that URL in the browser:

```text theme={null}
Portless URL: https://tuturuuu.localhost
```

If Turbo cannot prompt for the Portless sudo password while starting app dev
scripts, run the Portless setup helper first:

```bash theme={null}
bun portless:setup
```

The helper starts the Portless HTTPS proxy on port `443` before Turbo launches
package `dev` scripts. It no-ops when the proxy is already responding and skips
in non-interactive shells or CI. `bun setup` runs this helper after dependency
installation so fresh local checkouts are ready before the build step, then
invokes Turborepo through the repo-local `turbo:local` helper instead of any
globally installed Turbo binary. To install Portless as an OS startup service
instead of only starting the current proxy daemon, run:

```bash theme={null}
bun portless:setup -- --service
```

### Diagnose a broken local environment

When a local app suddenly cannot reach another app — for example the Inventory
landing page throws `InternalApiError: 404` because its server-side call to
`https://tuturuuu.localhost/api/...` is not routed — run the doctor:

```bash theme={null}
bun doctor
```

It checks the Node runtime, Docker daemon, local Supabase ports, local Redis
ports, apps/web Redis env wiring, app-local Supabase env consistency, whether
the Portless proxy is responding on port `443`, and the health of every
registered Portless route. The report uses colored `OK`, `WARN`, and `FAIL`
statuses in interactive terminals. Supabase env mismatch warnings are compact
by default so secret-like values stay out of the normal output; use the verbose
view when you need redacted per-file fingerprints:

```bash theme={null}
bun doctor --verbose
```

The most common failure after overlapping or crashed dev sessions is a
**stale routing table**: the proxy still points a live app route at a dead
dev-server port, so cross-app internal API calls return `404`. The doctor flags
those routes as `DEAD` and exits non-zero. Static aliases for apps you simply
are not running are reported as warnings, not failures, and include an exact
cleanup command. An initialized but empty Portless route table is treated as
healthy because no apps may be running yet.

Apply the safe automatic Portless repair (start the proxy, or reset it when
routes are stale) and re-run the checks:

```bash theme={null}
bun doctor --fix
```

`bun setup` deliberately no-ops when a proxy is already responding, so it does
**not** clear a stale routing table on its own. To force a clean restart — stop
the proxy, prune orphaned dev servers from crashed sessions, then start a fresh
proxy that apps re-register against — run:

```bash theme={null}
bun portless:reset
```

After a reset, restart your dev servers (for example `bun dev:inventory`) so
each app re-registers its route with the new proxy.

If `bun doctor` still warns about an inactive static alias after a reset, that
alias was created with `portless alias` and is not deleted by proxy resets.
Start the app if you still use the alias, or remove the alias shown in the
doctor output:

```bash theme={null}
bunx portless alias --remove <alias-name>
```

If the doctor warns that app env files use mismatched Supabase values, choose
the intended source app and keep these three keys together:
`NEXT_PUBLIC_SUPABASE_URL`, `NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY`, and
`SUPABASE_SECRET_KEY`. For quick local development, copy `apps/web/.env.local`
to app-local `.env.local` files:

```bash theme={null}
bun dev:sync:apps
```

Preview the target files first with:

```bash theme={null}
bun dev:sync:apps:dry-run
```

This sync compares app env files only. The root `.env.local` can intentionally
target a different Docker or deployment workflow without keeping the app
mismatch warning alive.

### Diagnose web dev memory and cache pressure

When `apps/web` feels slow or Activity Monitor reports high Node.js usage, start
with the dev diagnostic before moving routes into another app:

```bash theme={null}
bun diagnose:dev:web
```

Read the report by pressure type:

* `Live Next dev process RSS` is the memory held by the running `next dev`
  process tree. If this is high, inspect the top processes and the latest trace
  spans before changing architecture.
* `apps/web/.next/dev/cache/turbopack` is generated Turbopack filesystem cache.
  Multi-GB cache growth can make disk usage look like a live memory leak even
  when process RSS is modest.
* `apps/web/.next/cache` can include the Next 16.3 Turbopack build filesystem
  cache from local builds. It speeds repeated local `next build` runs, but it is
  still local artifact state and must stay out of Turborepo task outputs.
* `.turbo/cache` is Turborepo task cache. It is separate from the live Next.js
  dev server and should not be treated as app RSS.
* `Build memory policy` reports Docker and `next build` memory budgets. Those
  caps explain build behavior only; do not compare them directly to `next dev`
  RSS.
* `Likely pressure` calls out whether the current evidence points to live RSS,
  cache growth, watcher limits, or build-only memory settings.

If the report points at Turbopack cache growth, stop the web dev server and
preview the targeted cleanup first:

```bash theme={null}
bun clean:dev:web --dry-run
```

Then remove the web Next dev output:

```bash theme={null}
bun clean:dev:web
```

Use `bun clean:dev:web --all-next-dev --dry-run` when several app dev caches
exist and you want to inspect every `apps/*/.next/dev` target before deleting
them. Add `--include-turbo-cache` only when the report also calls out
`.turbo/cache` growth after branch or dependency graph churn. Avoid the broad
root `bun clean` command for this problem because it deletes dependency and
build state that is unrelated to the current dev-server slowdown.

Then restart the targeted app command you were using, such as `bun dev:web`.
Avoid deleting unrelated app output while other agents or local sessions are
working in the same checkout.

If live RSS is the real pressure, use the latest `.next/dev/trace` spans and
the matching process tree to reduce the compiled import graph first. Favor
narrow package subpath imports and lazy-loaded settings panels before splitting
an app boundary. A dedicated infrastructure app only reduces `apps/web` memory
when infrastructure pages leave the web route graph; running `apps/web` and an
infrastructure app together can increase total RAM.

Native local dev leaves Watchpack polling off unless the environment explicitly
sets `WATCHPACK_POLLING`. This keeps file watching lighter on macOS and Linux.
If the diagnostic reports watcher `EMFILE` errors or route discovery stops
updating on your machine, restart with polling enabled:

```bash theme={null}
WATCHPACK_POLLING=true bun dev:web
```

If the doctor warns that apps/web is missing Redis env, configure the local SRH
bridge and start the Redis stack in one step:

```bash theme={null}
bun redis:setup
```

`bun redis:setup` writes `UPSTASH_REDIS_REST_URL=http://localhost:8079` and the
matching local token into `apps/web/.env.local`, then runs `bun redis:start`.
Restart `bun dev:web` after setup so the app picks up the new env values.

To clear local Redis data while keeping the same local env wiring, run:

```bash theme={null}
bun redis:reset
```

This starts the local Redis stack if needed, then runs `FLUSHALL` inside the
Redis container.

To stop the local dev environment, run:

```bash theme={null}
bun stop
```

This stops this repo's Portless-registered Next.js dev servers, prunes Portless
routes, removes stale static aliases for this project, stops local Supabase,
and finishes by running `bun doctor`. Preview the cleanup first with:

```bash theme={null}
bun stop --dry-run
```

### Start Local Supabase Instance

To start a local supabase instance (database), run the following command:

```bash bun theme={null}
bun sb:start
```

<Info>
  This command will start a local supabase instance on your machine. You can
  access the supabase instance by visiting the following URL:
  [http://localhost:8003](http://localhost:8003)
</Info>

<Warning>
  You need to have Docker installed and running on your machine to start a local
  supabase instance.
</Warning>

### Stop Local Supabase Instance

To stop the local supabase instance, run the following command:

```bash standard theme={null}
bun sb:stop
```

`bun stop` is broader than Supabase. It stops this repo's local dev servers,
cleans stale Portless aliases, stops Supabase, and verifies the result with
`bun doctor`.

### Better Development Experience

In case you want to run all local development servers, run the following command:

```bash bun theme={null}
bun devx
```

<Info>
  Running `devx` will:

  1. Stop the currently running supabase instance and save current data as backup (if there is any)
  2. Install all dependencies
  3. Start a new supabase instance (using backed up data)
  4. Start all Next.js apps in development mode

  If you want to have the same procedure without the backup, you can run `bun devrs` instead. This will:

  1. Stop the currently running supabase instance (if there is any)
  2. Install all dependencies
  3. Start a new supabase instance (with clean data from seed.sql)
  4. Start all Next.js apps in development mode
</Info>

<Tip>
  In case you don't want to run a local supabase instance, you can run `bun dev`
  instead.
</Tip>

### Local development

#### Seed accounts

There are 5 seed accounts that are already set up for local development:

1. [local@tuturuuu.com](mailto:local@tuturuuu.com)
2. [user1@tuturuuu.com](mailto:user1@tuturuuu.com)
3. [user2@tuturuuu.com](mailto:user2@tuturuuu.com)
4. [user3@tuturuuu.com](mailto:user3@tuturuuu.com)
5. [user4@tuturuuu.com](mailto:user4@tuturuuu.com)

You can use any of these accounts to log in to the app and quickly test the functionality of the app, since they are already set up with the necessary data.

#### Authentication

A local mail server (**InBucket**) is automatically set up by Supabase to handle authentication emails.

<Info>
  You can access the mail server by visiting the following URL:
  [http://localhost:8004](http://localhost:8004)
</Info>

## Build

To build all apps and packages, run the following command:

```bash bun theme={null}
bun run build
```

## Test

To run all tests, run the following command:

```bash bun theme={null}
bun run test
```

To run the Flutter mobile quality gate, use:

```bash bun theme={null}
bun check:mobile
```

`bun check:mobile` runs Dart format, Flutter analyze, and Flutter tests for
`apps/mobile`. Flutter test output is streamed by default so slow suites still
show progress instead of appearing stuck.

### Mobile release builds

The native build commands verify or hydrate each flavor's ignored Firebase SDK
configuration from the `tuturuuu-mobile` Firebase project before compiling. The
Firebase CLI must be authenticated with access to that project.

```bash theme={null}
# Production Android App Bundle
bun build:android

# Signed production iOS IPA
bun build:ios
```

The default iOS command requires an Apple signing identity and provisioning
profile. `bun build:ios:ipa` is an alias for the same signed release build. To
compile the production app on a machine without signing credentials, use:

```bash theme={null}
bun build:ios:unsigned
```

`bun build:android` only produces signed production bundles. Configure the
protected upload keystore through all four `ANDROID_KEYSTORE_*` environment
variables or `apps/mobile/android/key.properties`; the command fails before
compilation when signing is absent and verifies the resulting AAB with
`jarsigner`. The Mobile Store Deployment workflow hydrates these credentials in
its protected runner and executes this exact command. Development builds remain
available through `bun build:android:dev`.

To hydrate or validate a native Firebase configuration without compiling, run:

```bash theme={null}
bun mobile:firebase:configure --environment production --platform android
bun mobile:firebase:configure --environment production --platform ios
```

<Warning>
  Tests are still a work in progress. We're currently working on adding tests to all packages to ensure the best quality possible.
</Warning>

## Git Conventions

Tuturuuu uses standardized conventions for Git commits and branch naming. For more information, see the [Git Conventions](/build/development-tools/git-conventions) guide to learn how to format your commits and branch names to align with our workflow.


# Documenting
Source: https://docs.tuturuuu.com/build/development-tools/documenting

Learn how to contribute to our documentation.

<Info>
  **Prerequisite**: You should have [Docker](https://www.docker.com/) and Bun
  installed, and the [Tuturuuu
  Monorepo](https://github.com/tutur3u/platform) cloned locally.
</Info>

Step 1. Start the docs site from the repo root:

```bash theme={null}
bun dev:docs
```

This uses the repo-managed Docker docs stack, which runs Mintlify inside a
Node.js 24 container instead of relying on a globally installed CLI.

The documentation website is now available at `http://localhost:3000`.

To stop the stack:

```bash theme={null}
bun dev:docs:down
```

### Custom Ports

The docs stack exposes port `3000` by default through `${DOCS_PORT:-3000}` in
`docker-compose.docs.yml`. You can use the `--port` flag to customize the
host-side port binding. For example:

```bash theme={null}
bun dev:docs -- --port 3333
```

If the chosen port is already taken, Docker will fail to bind the host port.

## Runtime Details

* The docs image is defined in `apps/docs/Dockerfile`.
* The development stack is defined in `docker-compose.docs.yml`.
* The root command wrapper lives in `scripts/docker-docs.js`.
* The container pins the runtime to Node.js 24 and installs Mintlify inside the
  image.

## Writing Documentation

### File Structure

Each documentation file should follow this structure:

```mdx theme={null}
---
title: "Page Title"
description: "Brief description of the page content"
updatedAt: "YYYY-MM-DD"
---

# Page Title

Content goes here...
```

### Content Guidelines

1. **Use clear headings** to structure your content
2. **Include code examples** with proper syntax highlighting
3. **Add cross-references** to related documentation
4. **Keep content up-to-date** by updating the `updatedAt` field
5. **Use consistent formatting** throughout

### Code Examples

When including code examples:

* Use proper syntax highlighting
* Include TypeScript types
* Show both server and client examples
* Include error handling
* Test examples before committing

### Images and Assets

* Store images in the `images/` directory
* Use descriptive filenames
* Optimize images for web
* Include alt text for accessibility

## Contributing

### Before You Start

1. Check if documentation already exists
2. Look for similar patterns in existing docs
3. Follow the established structure
4. Read the [Organization Guide](/overview/organization-guide) for structure

### Making Changes

1. **Create a branch** for your documentation changes
2. **Write clear, concise content** that's easy to understand
3. **Include practical examples** that developers can use
4. **Update related documentation** if needed
5. **Test your changes** locally with `bun dev:docs`

### Review Process

1. **Self-review** your changes for clarity and accuracy
2. **Check links** to ensure they work correctly
3. **Verify code examples** are correct and complete
4. **Update the table of contents** if adding new sections
5. **Submit a pull request** with a clear description

## Best Practices

### Writing Style

* **Be concise** but comprehensive
* **Use active voice** when possible
* **Write for your audience** (developers)
* **Include context** for complex topics
* **Use consistent terminology** throughout

### Organization

* **Group related content** together
* **Use clear section headings**
* **Include a table of contents** for long pages
* **Cross-reference** related documentation
* **Keep examples practical** and realistic

### Maintenance

* **Update documentation** when APIs change
* **Remove outdated information** promptly
* **Keep examples current** with latest versions
* **Review documentation regularly** for accuracy
* **Ask for feedback** from other developers


# Git Conventions
Source: https://docs.tuturuuu.com/build/development-tools/git-conventions

Learn how Tuturuuu uses Conventional Commits and Branch naming to improve development workflow.

<Info>
  **Prerequisite**: You should be familiar with basic Git operations and
  understand the [Monorepo Architecture](/build/development-tools/monorepo-architecture) of our
  codebase.
</Info>

## Overview

Tuturuuu follows standardized conventions for Git commits and branch naming to improve collaboration, automate releases, and maintain a clean, navigable repository history. We use two main specifications:

1. [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) for structured commit messages
2. [Conventional Branch](https://conventional-branch.github.io/) for consistent branch naming

These conventions help automate our CI/CD workflows, generate changelogs, and make our development process more efficient.

## Conventional Commits

### What are Conventional Commits?

Conventional Commits is a specification for adding human and machine-readable meaning to commit messages. It provides a set of rules for creating an explicit commit history, making it easier to write automated tools on top of.

The basic structure of a conventional commit is:

```
<type>[optional scope]: <description>

[optional body]

[optional footer(s)]
```

### Types

Tuturuuu uses the following commit types:

| Type       | Description                                     | Example                                          |
| ---------- | ----------------------------------------------- | ------------------------------------------------ |
| `feat`     | New feature or enhancement                      | `feat: add dark mode support`                    |
| `fix`      | Bug fix                                         | `fix: prevent crash when user data is undefined` |
| `docs`     | Documentation changes                           | `docs: update installation instructions`         |
| `style`    | Code style changes (formatting, no code change) | `style: format code with prettier`               |
| `refactor` | Code refactoring                                | `refactor: simplify authentication logic`        |
| `perf`     | Performance improvements                        | `perf: optimize database queries`                |
| `test`     | Add or fix tests                                | `test: add unit tests for auth middleware`       |
| `build`    | Changes affecting build system or dependencies  | `build: update dependency to fix security issue` |
| `ci`       | Changes to CI configuration files and scripts   | `ci: simplify workflow branch filters`           |
| `chore`    | Routine tasks, maintenance                      | `chore: update package.json metadata`            |

### Scopes

Scopes provide additional context about which part of the codebase is affected. In our monorepo structure, we often use package or app names as scopes:

```
feat(web): add new dashboard layout
fix(ui): correct button alignment in mobile view
chore(types): update supabase database types
```

### Breaking Changes

Breaking changes must be indicated by adding a `!` after the type/scope or by using a `BREAKING CHANGE:` footer:

```
feat(api)!: require authentication for all endpoints

BREAKING CHANGE: All API endpoints now require authentication tokens.
```

### Examples

Here are some examples of conventional commits used in our codebase:

```
feat(web): add new calendar integration
fix(supabase): correct permission issue in auth policy
docs(readme): update development setup instructions
style: apply consistent formatting with prettier
refactor(utils): simplify date formatting functions
perf(queries): optimize workspace user loading
test(auth): add tests for token verification
build(deps): update Next.js to v14
ci(vercel): add automatic preview deployments
chore(release): publish packages
```

## Conventional Branches

### What are Conventional Branches?

Conventional Branch refers to a structured naming convention for Git branches that makes it easier to identify branches by type and purpose.

The basic structure is:

```
<type>/<description>
```

### Branch Types

Tuturuuu uses the following branch types:

| Type         | Description                            | Example                         |
| ------------ | -------------------------------------- | ------------------------------- |
| `main`       | Main development branch                | `main`                          |
| `feature`    | For new features                       | `feature/user-dashboard`        |
| `feat`       | Short feature prefix also accepted     | `feat/invite-link-permissions`  |
| `fix`        | Short bug-fix prefix also accepted     | `fix/invite-membership-check`   |
| `bugfix`     | For bug fixes                          | `bugfix/login-error`            |
| `hotfix`     | For urgent fixes                       | `hotfix/security-vulnerability` |
| `release`    | For preparing releases                 | `release/v1.2.0`                |
| `chore`      | For maintenance tasks                  | `chore/update-dependencies`     |
| `docs`       | For documentation-only work            | `docs/git-conventions-refresh`  |
| `style`      | For formatting or stylistic cleanups   | `style/biome-pass`              |
| `refactor`   | For internal code restructuring        | `refactor/task-query-shell`     |
| `perf`       | For performance-focused changes        | `perf/workspace-user-search`    |
| `dependabot` | Automated dependency update branches   | `dependabot/npm_and_yarn/next`  |
| `claude`     | AI-assisted scratch or experimental PR | `claude/rate-limit-audit`       |

Release Please bot branches are also accepted with the
`release-please--branches--` prefix. Do not create human-authored branches with
that prefix.

### Naming Rules

1. Use lowercase alphanumeric characters and hyphens
2. Keep names concise but descriptive
3. Include ticket/issue numbers when applicable
4. Avoid special characters (except hyphens)

### Examples

```
feature/workspace-sharing
feat/public-course-sharing
fix/file-upload-error
bugfix/auth-vulnerability
release/v2.5.0
chore/update-react-18
docs/git-conventions-refresh
feature/issue-123-user-profile
```

### Merge Commit Exception

Authored commits should follow Conventional Commits. The common exception is a
Git-generated merge commit when syncing a long-lived branch, for example:

```bash theme={null}
Merge branch 'main' into feat/studying-platform
```

Keep that merge summary when the goal is to preserve the branch's merge history.
Use a conventional commit message again for the next authored commit after the
merge.

## How These Conventions Improve Our Workflow

### 1. Automated Changelog Generation

Our conventional commits are used to automatically generate changelogs for releases. Different commit types are categorized accordingly:

```markdown theme={null}
# Changelog

## Features

- add dark mode support (#123)
- add calendar integration (#124)

## Bug Fixes

- prevent crash when user data is undefined (#125)

## Documentation

- update installation instructions (#126)
```

### 2. Semantic Versioning

Conventional commits help determine the next semantic version for packages:

* `fix:` commits trigger a PATCH increment (1.0.0 → 1.0.1)
* `feat:` commits trigger a MINOR increment (1.0.0 → 1.1.0)
* Commits with `BREAKING CHANGE` trigger a MAJOR increment (1.0.0 → 2.0.0)

### 3. Automated Release PRs And Package Publishing

Release Please reads Conventional Commits from `production`, updates
`release-please-config.json` packages through `.release-please-manifest.json`,
and opens one combined release PR with package versions and changelogs. Package
publish workflows do not generate versions; they publish only after a
release-please version bump lands on `production`. Local manifests keep
Tuturuuu workspace dependencies as `workspace:*`; npm release workflows rewrite
the checked-out package manifest with
`scripts/ci/prepare-npm-package-manifest.js` immediately before `npm pack` so
published artifacts contain installable npm version ranges. Package-included
`file:` tarball dependencies, such as `@tuturuuu/ui`'s vendored SheetJS tarball,
must not leak a consumer-relative `file:` range into the npm manifest. Package
preparation expands the checked-in archive into the artifact, redirects the
package export to those immutable bytes, and removes the install-time dependency
edge. Do not rewrite the vetted archive to a mutable external tarball URL.
Before any build or pack work starts, package workflows run
`scripts/ci/package-release-readiness.js gate-package-release packages/<name>`.
The gate checks publishable Tuturuuu workspace dependency versions on npm once,
dispatches missing dependency workflows, and exits green without occupying a
runner while dependencies are pending. If the related dependency workflow for
the same production SHA failed, completed successfully without npm visibility,
or cannot be inspected, the gate fails immediately. Publish jobs still wait for
their own version to become visible after `npm publish`, then a separate
non-OIDC job dispatches direct dependent package workflows. Workflow-published
package manifests must carry
provenance-compatible `repository` metadata for `tutur3u/platform`; otherwise
npm rejects trusted publishes with `E422`. For example,
`release-types-package.yaml` triggers from production changes to
`packages/types/package.json`:

When bringing the generated release PR branch back to `main`, run
`bun git-release-please` from a clean `main` checkout. The helper fetches the
latest `release-please--branches--production` branch, merges it without
committing, syncs `platform-version.txt` into the platform badge constant and
test expectation, runs `bun ff`, stages the resolved merge, then runs `bun check`
directly before the merge commit lands. When the staged release merge includes
`apps/mobile` paths, the helper also runs `bun check:mobile`. If you are already
inside a manual merge, run
`bun release:sync-platform-version` to resolve the recurring
`TUTURUUU_PLATFORM_VERSION` conflict before staging the merge.

```yaml theme={null}
on:
  push:
    branches: [production]
    paths:
      - "packages/types/package.json"
  # ...

jobs:
  check-version-bump:
    if: github.ref == 'refs/heads/production' && needs.check-ci.outputs.should_run == 'true'
    # ...
```

### 4. Better Code Reviews

With conventional commits and branches, it's easier to understand the purpose of a pull request at a glance:

* A PR from `feature/user-dashboard` with commits like `feat: add user stats widget` clearly indicates a new feature
* A PR from `bugfix/auth-issue` with commits like `fix: prevent token expiration error` indicates a bug fix

### 5. Simplifying Navigation

Conventional branch names make it easier to navigate the repository history and find specific changes. For example:

```bash theme={null}
# Find all feature branches
git branch --list "feature/*"

# Find branches related to authentication
git branch --list "*auth*"
```

## Tools and Enforcement

We use a dedicated CI/CD check to enforce our Git conventions:

### Branch Naming Check

We use a GitHub Action workflow to verify that branch names follow our convention:

```yaml theme={null}
name: Branch Name Check

on:
  push:
    branches-ignore:
      - main
      - production

jobs:
  check-branch-name:
    name: Check branch name
    runs-on: ubuntu-latest
    steps:
      - name: Check branch name
        run: |
          BRANCH_NAME=${GITHUB_REF#refs/heads/}
          if ! [[ $BRANCH_NAME =~ ^(feature|feat|fix|bugfix|hotfix|release|chore|docs|style|refactor|perf|dependabot|claude)/.+|^release-please--branches--.+ ]]; then
            echo "❌ Branch name '$BRANCH_NAME' doesn't follow the conventional branch format."
            echo "Branch name should be in format: type/description"
            echo "Allowed types: feature, feat, fix, bugfix, hotfix, release, chore, docs, style, refactor, perf, dependabot, claude"
            echo "Release Please bot branches are also allowed with the release-please--branches-- prefix."
            exit 1
          else
            echo "✅ Branch name follows convention: $BRANCH_NAME"
          fi
```

## Best Practices

### Writing Good Commit Messages

1. Use the imperative mood ("add" not "added" or "adds")
2. Keep the description in lowercase to match the repository's observed convention
   (for example, `feat(backend): migrate nova team read`)
3. Do not end the description with a period
4. Keep the description under 72 characters
5. Use the body to explain the what and why, not the how

Example of a well-formatted commit:

```
feat(auth): add multi-factor authentication support

Implement TOTP-based multi-factor authentication to improve security.
The implementation follows the RFC 6238 standard.

Closes #123
```

### Coordinating Commits In Shared Checkouts

When multiple agents or humans may commit in the same checkout, use the commit
window before changing the staged set. The lock is advisory and lives under the
ignored `tmp/agent-coordination/` directory, so it protects the Git index and
commit operation without becoming part of a commit. Claims default to 10
minutes and may only be 5-10 minutes, so claim only when ready to stage,
inspect, and commit.

This coordination is **per-checkout** and **harness-agnostic**. The commit
window and the `tmp/agent-coordination/` notes both live in the working
directory, so they coordinate every agent or human sharing one checkout —
parallel Codex or Claude Code sessions, background tasks, and same-directory
subagents — regardless of which tool they run under. A separate `git worktree`
has its own lock file, its own notes, and its own Git index, so the window does
not span worktrees; separate worktrees stay isolated by being on different
branches and integrate through the shared remote instead. In a hot shared
checkout, commit your owned paths promptly in small scoped commits: a large
unstaged set can be discarded by a concurrent rebase, `reset --hard`,
`checkout`, or `stash` from any agent or human. (`bun git-sync` is isolated and
safe; manual destructive Git is not.)

```bash theme={null}
bun git-commit-window status
bun git-commit-window claim --owner "<agent/task>" --scope "type(scope): subject"
git add path/to/file-a path/to/file-b
git diff --cached --stat
git diff --cached --name-only
git commit -m "type(scope): subject"
bun git-commit-window release --token <token>
```

If another agent owns the window and it is appropriate to wait, use `wait`. The
command sleeps until the active lock is released or expires, then claims the
window before reporting that it is safe to proceed. The waiting period can be
longer than the claim TTL, but the claimed window remains capped at 10 minutes:

```bash theme={null}
bun git-commit-window wait --owner "<agent/task>" --scope "type(scope): subject"
```

Use `--allow-staged` only after inspecting existing staged files. The commit
window does not grant ownership of files or permission to stage unrelated paths.
Existing staged files are owned by the staging agent or coordinator until
explicitly reassigned. If a file appears as `MM`, both its staged and unstaged
diffs need owner review before commit.

Let commit hooks run by default. This is a proof-gated no-verify path: use
`git commit --no-verify` only when the current agent can prove its exact staged
paths would pass the checks normally covered by `bun check`. The proof packet
should include reviewed
`git status --short`, `git diff --cached --stat`, and
`git diff --cached --name-only` output; the touched files or narrow path group;
the separated checks that covered each affected `bun check` component; any
skipped components with path-based rationale; unrelated dirty files excluded
from the claim; and `bun check:mobile` coverage when `apps/mobile` is touched.
If ownership is unclear, proof is incomplete, or the check mapping is uncertain,
do not bypass the hook.

Commit hooks and repo checks can read the whole worktree, including files owned
by other agents. If they fail on unrelated dirty files, release the commit
window and report the blocker instead of formatting, fixing, staging, or
committing those files for convenience. Only the staged-set owner may use the
proof-gated no-verify path, and only with exact-path evidence for the staged
files.

### Branch Management

1. Create branches from the latest `main` branch
2. Keep branches focused on a single task or issue
3. Regularly rebase long-lived branches on `main` to avoid merge conflicts
4. Delete branches after they've been merged

### Synchronizing Release Branches

Use the root command below when `production` should point at the same commit as
`main`:

```bash theme={null}
bun git-sync
```

The command fetches `origin`, creates a temporary detached worktree, refreshes
`main`, and fast-forwards `production` to the current `main` commit from that
temporary worktree before pushing those branches. It finishes by fetching again
and verifying that local and remote `main` and `production` both resolve to the
same commit. The checkout you started from is left untouched, so uncommitted
work on another branch can keep running while the release refs are synchronized.

If a branch that needs to move is already checked out in another worktree, Git
will refuse to force-update that branch. Switch that worktree away from the
branch or update it manually, then rerun `bun git-sync`.

`bun git-sync` does not create commits for you. Commit all intended changes on
`main` first; if `production` contains commits that are not already in `main`,
reconcile the branch manually before rerunning the command.

Use `--only-branch` to update one active sync branch while leaving the other
untouched:

```bash theme={null}
bun git-sync --only-branch production
```

`main` is still refreshed locally as the source commit, but only `production` is
fast-forwarded and pushed. Use `--only-branch main` when you only want to pull
and push `main`.

The retired `staging` branch is no longer a supported `--only-branch` target.
The Supabase staging environment still exists, but its workflow is driven from
`main`.

Use `--current-branch` or `-c` when `main` and `production` should move to the
latest commit on the branch you currently have checked out instead of latest
`origin/main`:

```bash theme={null}
bun git-sync --current-branch
bun git-sync -c
```

Current-branch mode still uses a temporary detached worktree, leaves the checkout
you started from untouched, and only moves the selected sync branches. It does
not push the source branch unless the source branch is itself one of the selected
sync branches, such as running from `main`.

Combine `-c` with `--only-branch` when only one long-lived branch should move to
the current checkout's commit:

```bash theme={null}
bun git-sync -c --only-branch production
```

Use `--no-push` for local-only synchronization:

```bash theme={null}
bun git-sync --no-push
bun git-sync --only-branch production --no-push
bun git-sync -c --no-push
```

With `--no-push`, the command fetches, pulls with `--ff-only`, and fast-forwards
the selected local branches, but it never pushes to `origin`. Final verification
checks local refs only.

### Pull Request Workflow

1. Create a branch with the appropriate type based on the work
2. Make commits using conventional commit messages
3. Push the branch and create a pull request
4. Use conventional commit style for the PR title
5. After approval and merge, delete the branch

## Conclusion

Following these Git conventions helps us maintain a clean, understandable repository history, automate release processes, and improve collaboration across the team. By standardizing both commit messages and branch names, we create a more efficient development workflow.

For more information, refer to the official documentation for [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) and [Conventional Branch](https://conventional-branch.github.io/).


# Local Supabase Development
Source: https://docs.tuturuuu.com/build/development-tools/local-supabase-development

Learn how to work with Supabase locally in the Tuturuuu development workflow.

<Info>
  **Prerequisite**: You should have installed
  [Docker](https://www.docker.com/products/docker-desktop/) and followed the
  [Development](/build/development-tools/development) setup guide.
</Info>

## Overview

Tuturuuu utilizes Supabase for database management and authentication. This guide explains how to work efficiently with Supabase in the local development workflow.

## Basic Commands

### Starting Supabase

To start a local Supabase instance tailored for Tuturuuu:

```bash theme={null}
bun sb:start
```

This command launches a local Supabase instance on your machine. The local ports
are pinned in `apps/database/supabase/config.toml`:

| Service                | URL / Port                                               |
| ---------------------- | -------------------------------------------------------- |
| REST/Auth API          | [http://localhost:8001](http://localhost:8001)           |
| Postgres database      | `postgresql://postgres:postgres@localhost:8002/postgres` |
| Studio (dashboard)     | [http://localhost:8003](http://localhost:8003)           |
| InBucket (test emails) | [http://localhost:8004](http://localhost:8004)           |

<Info>
  Run `bun sb:status` at any time to print the live URLs, keys, and the DB
  connection string for your running instance. Prefer reading these values from
  `bun sb:status` over hard-coding them, since they are the source of truth for
  the current container.
</Info>

### Stopping Supabase

To stop the local Supabase instance:

```bash theme={null}
bun sb:stop
```

### Checking Status

To view the current URLs and status of your local Supabase instance:

```bash theme={null}
bun sb:status
```

## Development Workflow

### Recommended Startup

When developing for Tuturuuu, you have several options to start your environment:

1. **Standard Approach**: Start Next.js apps and Supabase separately.

   ```bash theme={null}
   bun dev      # Starts all Next.js apps
   bun sb:start # Starts Supabase
   ```

2. **Enhanced Development Experience**: Use the `devx` command for a streamlined setup.

   ```bash theme={null}
   bun devx
   ```

   This command:

   * Stops any running Supabase instance and saves current data as backup
   * Installs all dependencies
   * Starts a new Supabase instance (using backed up data)
   * Starts all Next.js apps in development mode

3. **Fresh Database Setup**: When switching branches with potential schema changes.

   ```bash theme={null}
   bun devrs
   ```

   This command (`bun sb:stop && bun sb:start && bun sb:reset && bun dev`):

   * Stops any running Supabase instance (without backup)
   * Starts a new Supabase instance
   * Resets the database to use the latest schema and seed data
   * Starts all Next.js apps in development mode

   App-scoped variants also exist (for example `bun devrs:web`, `bun devrs:tasks`)
   that reset Supabase and then start only that app's dev server.

<Warning>
  Use `bun devrs` when switching between branches that might have different
  database migrations to ensure your local database schema matches the branch
  you're working on.
</Warning>

### Syncing With Schema Changes

If you're keeping your Next.js server running but need to reset your database to match the current branch's schema:

```bash theme={null}
bun sb:reset
```

This command will reset your local database to use the latest schema definitions and automatically regenerate TypeScript types. After the reset, the database package also runs the local AI credits bootstrap, which syncs gateway models through the local Supabase REST API and retries the short PostgREST schema-cache warmup window that can happen immediately after containers restart.

## Database Schema Management

### Making Schema Changes

There are two approaches to modifying the database schema:

#### 1. Using the Supabase UI

1. Navigate to your local Supabase Studio at [http://localhost:8003](http://localhost:8003)
2. Make your changes through the UI
3. Generate a migration file:
   ```bash theme={null}
   bun sb:diff
   ```
   This creates a migration file based on the differences between your current schema and the previous state.

<Warning>
  Be cautious when using `sb:diff` for schema changes. If you rename columns or
  tables, the migration will drop the old ones and create new ones, which can
  result in data loss in production environments.
</Warning>

#### 2. Creating Manual Migrations

For more control, you can create empty migration files and populate them manually:

```bash theme={null}
bun sb:new add_custom_function
```

This creates a new empty migration file in `apps/database/supabase/migrations`
using the provided migration name. If you omit the name, the helper uses
`new_migration`.

### Applying Migrations

After creating a migration, apply it to your local database:

```bash theme={null}
bun sb:up
```

<Info>
  This same process is used to keep our production database up-to-date with the
  schema defined in the `production` branch.
</Info>

### Validating an Exact Worktree in Isolation

Database plans pinned to an older commit must not reset or reuse the ordinary
`tuturuuu` stack when its migration history belongs to another checkout. Run the
disposable validator from the repository root instead:

```bash theme={null}
bun --cwd apps/database sb:validate:isolated
```

For a focused pgTAP file, pass its path relative to `apps/database`:

```bash theme={null}
bun --cwd apps/database sb:validate:isolated --test supabase/tests/workspace-creator-membership.sql
```

To replace the checked-in database types only after the disposable reset and
focused pgTAP test both succeed, add the exact approved output path:

```bash theme={null}
bun --cwd apps/database sb:validate:isolated --typegen packages/types/src/supabase.ts --test supabase/tests/habit-tracker-write-rls.sql
```

The type generator uses the same pinned Supabase binary and disposable project,
includes the `public`, `private`, and `storage` schemas, buffers its output, and
atomically replaces `packages/types/src/supabase.ts` only after a successful,
non-empty result. Reset, pgTAP, type generation, or output-write failure keeps
the existing generated file unchanged. No other output path is accepted.

The runner derives a Docker-safe project identity from the exact worktree path
and Git commit, selects an available deterministic eight-port block, and prints
both before starting. It copies only Git-tracked files from
`apps/database/supabase` into a directory named
`tuturuuu-supabase-*` under the operating system's temporary directory. The
temporary config receives the isolated project id and ports; the tracked
`supabase/config.toml` is never edited.

The isolated lifecycle starts that project, resets it from the copied exact-base
migrations, runs the full or focused pgTAP suite, and stops that project with
`--no-backup` in cleanup. It never invokes `supabase stop --all` or the default
`sb:stop`/`sb:reset` aliases. Ordinary development continues to use
`sb:start`, `sb:up`, and `sb:reset` unchanged.

SIGINT and SIGTERM request the same scoped cleanup while preserving the failing
command or signal exit code. A hard process or machine termination can leave the
temporary directory behind; its `.tuturuuu-isolated-supabase.json` records the
project id, worktree commit, ports, and last lifecycle step. Resume or explicitly
clean that recorded directory without guessing its Docker identity:

```bash theme={null}
bun --cwd apps/database sb:validate:isolated --resume /tmp/tuturuuu-supabase-EXAMPLE
bun --cwd apps/database sb:validate:isolated --cleanup /tmp/tuturuuu-supabase-EXAMPLE
```

The exact temporary parent varies by operating system. Use the disposable path
printed when the run starts; cleanup refuses paths outside the owned temporary
directory pattern. If scoped Docker cleanup fails, the metadata directory is
kept so the command can be retried safely.

### Generating TypeScript Types

After schema changes, regenerate the TypeScript types to keep your code in sync with the database schema:

```bash theme={null}
bun sb:typegen
```

The generator includes the `public`, `private`, and `storage` schemas. Keep
server-owned/private tables out of Supabase REST exposure, but still regenerate
types after migrations so server-only helpers and storage paths can import
accurate generated row shapes.

Alternatively, you can use the shorthand:

```bash theme={null}
bun typegen
```

<Info>
  This step is automatically performed when running `bun sb:reset`, making it
  useful when catching up with a new branch's schema.
</Info>

### Using Generated TypeScript Types

The Supabase-generated TypeScript types are available at `packages/types/src/supabase.ts`. These types are accessible to all apps that have the `@tuturuuu/types` package installed.

You can use these types to ensure type safety when working with Supabase data:

With supabase-js v2, table types flow from the client itself rather than a
generic on `.from()`. The Tuturuuu Supabase helpers in `@tuturuuu/supabase` are
already typed with the generated `Database` type, so queries are type-safe out of
the box. Reach for the `Database` type directly when you need a specific row
shape:

```typescript theme={null}
import type { Database } from '@tuturuuu/types/supabase';

type WorkspaceMemberRow =
  Database['public']['Tables']['workspace_members']['Row'];

// Type-safe access to tables (the client already knows the row shapes)
const { data, error } = await supabase
  .from('workspace_members')
  .select('*')
  .eq('ws_id', workspaceId);

// data is typed as WorkspaceMemberRow[] | null

// Type-safe access to specific columns
const { data: workspace } = await supabase
  .from('workspaces')
  .select('id, name, handle')
  .eq('id', workspaceId)
  .single();

// TypeScript knows the structure of 'workspace' with proper types
const workspaceName: string | undefined = workspace?.name;
```

### Short-hand Type Access

For more convenient access to common table types, Tuturuuu also provides short-hand type definitions in `packages/types/src/db.ts`. These are easier to use and remember than the full database type paths:

```typescript theme={null}
import type { WorkspaceCourse, WorkspaceRole } from '@tuturuuu/types/db';

// Use short-hand types directly
const { data: roles } = await supabase
  .from('workspace_roles')
  .select('*')
  .eq('ws_id', workspaceId);

// Type is now WorkspaceRole[]
roles?.forEach((role: WorkspaceRole) => {
  console.log(role.name, role.permissions);
});

// Short-hand types can also include extended properties
const course: WorkspaceCourse = {
  id: 'course-id',
  ws_id: 'workspace-id',
  name: 'Course Name',
  created_at: new Date().toISOString(),
  updated_at: new Date().toISOString(),
  href: '/courses/course-id', // Extended property not in the database
};
```

You can add your own short-hand types to `db.ts` for tables you frequently work with. This is especially useful for tables that have complex structures or need additional client-side properties.

This ensures that your code correctly interacts with the database schema, reducing runtime errors and improving development experience.

## Migration Files

All migration files are stored in `apps/database/supabase/migrations`. These files:

* Contain SQL commands that create and modify the database schema
* Are executed in order based on the timestamp prefix in their filenames
* Include descriptive names after the timestamp to help developers understand their purpose

<Warning>
  When contributing new migrations in a Pull Request, always add them after the
  latest migration file from the `main` branch. This maintains the correct
  execution order and prevents issues when syncing the production database.
</Warning>

## Local Authentication

A local mail server (**InBucket**) is automatically set up by Supabase to handle authentication emails. You can access it at [http://localhost:8004](http://localhost:8004).

With InBucket, you can:

* Receive all authentication emails sent by your local Supabase instance
* Test any email combination without needing actual mail delivery
* View password reset links, confirmation emails, and other authentication flows
* Troubleshoot email templates and content

This makes it easy to test different authentication scenarios without configuring a real email service or waiting for actual email delivery.

Five seed accounts are pre-configured for local development:

1. [local@tuturuuu.com](mailto:local@tuturuuu.com)
2. [user1@tuturuuu.com](mailto:user1@tuturuuu.com)
3. [user2@tuturuuu.com](mailto:user2@tuturuuu.com)
4. [user3@tuturuuu.com](mailto:user3@tuturuuu.com)
5. [user4@tuturuuu.com](mailto:user4@tuturuuu.com)

These accounts are already set up with the necessary data, allowing you to quickly test the app's functionality. However, you can register any new email address and the authentication emails will be captured by InBucket for you to inspect.

<Warning>
  OTP send limits include email-scoped cooldowns in the web process. Playwright
  tests that only need to assert the OTP stage should use a dedicated throwaway
  email address instead of a seed login account. Reserve seed accounts for tests
  that must complete authentication.
</Warning>

### Playwright E2E Safety

Web E2E runs must use the local Supabase stack. For local debugging and patch
iteration, run the web app and Playwright on the native machine so code changes
are picked up quickly and server logs stay visible.

Avoid `bun test:e2e`, `bun --cwd apps/web test:e2e`, and
`bun test:e2e:web:docker` as the first local debugging path. Those commands
route through `scripts/run-web-e2e-docker.js`, which writes
`tmp/e2e/web.env`, resets local Supabase, builds and runs the production-style
Docker web stack, and then runs Playwright. Reserve that Dockerized path for
explicit CI-parity checks or production-Docker runtime bugs.

For the native workflow, start or reset local Supabase with the database package
scripts, start `apps/web` natively with the local E2E environment, and run the
focused Playwright spec directly from `apps/web`. Native web server Supabase
URLs should resolve to `http://127.0.0.1:8001`; `host.docker.internal` is only
for the Dockerized web stack.

Do not point E2E at a cloud Supabase project. The Playwright global setup fails
fast if `BASE_URL` is not local or if `NEXT_PUBLIC_SUPABASE_URL`,
`SUPABASE_SERVER_URL`, or `SUPABASE_URL` resolves outside the local Supabase
origins on port `8001`.

## Further Information

For more details about Supabase CLI usage, refer to the [Supabase CLI documentation](https://supabase.com/docs/guides/local-development/cli/getting-started).

## Row Level Security (RLS)

Row Level Security (RLS) is a powerful Postgres feature that allows you to control access to rows in a database table based on the user making the request. In Tuturuuu, we use RLS extensively to ensure data security.

### Enabling RLS

RLS should be enabled on all tables in exposed schemas (like `public`). When creating tables through the Supabase UI, RLS is enabled by default. For tables created using SQL, you need to explicitly enable RLS:

```sql theme={null}
alter table <schema_name>.<table_name> enable row level security;
```

### Creating RLS Policies

Policies define the conditions under which users can access or modify data. Here are some common patterns used in Tuturuuu:

#### Organization-based Access

In Tuturuuu, workspace-scoped resource tables use `ws_id`, and membership rows
use `workspace_members.ws_id` plus the `workspace_member_type` enum. Use
`MEMBER` when an example requires a full member rather than a guest. For
application-specific mutations, pair membership with the maintained permission
helper and confirm the permission name in the generated enum. The canonical
[RLS policy reference](/reference/database/rls-policies) explains when a
different membership or permission rule is appropriate.

```sql theme={null}
-- Allow users to select data from their organizations
create policy "Users can view data from their organizations"
on public.table_name
for select
to authenticated
using (
  exists (
    select 1
    from public.workspace_members workspace_member
    where workspace_member.ws_id = table_name.ws_id
      and workspace_member.user_id = (select auth.uid())
      and workspace_member.type = 'MEMBER'
  )
);

-- Allow members with manage_projects to insert data
create policy "Project managers can insert data"
on public.table_name
for insert
to authenticated
with check (
  exists (
    select 1
    from public.workspace_members workspace_member
    where workspace_member.ws_id = table_name.ws_id
      and workspace_member.user_id = (select auth.uid())
      and workspace_member.type = 'MEMBER'
  )
  and public.has_workspace_permission(
    table_name.ws_id,
    (select auth.uid()),
    'manage_projects'
  )
);

-- UPDATE needs USING for the existing row and WITH CHECK for the new row
create policy "Project managers can update data"
on public.table_name
for update
to authenticated
using (
  exists (
    select 1
    from public.workspace_members workspace_member
    where workspace_member.ws_id = table_name.ws_id
      and workspace_member.user_id = (select auth.uid())
      and workspace_member.type = 'MEMBER'
  )
  and public.has_workspace_permission(
    table_name.ws_id,
    (select auth.uid()),
    'manage_projects'
  )
)
with check (
  exists (
    select 1
    from public.workspace_members workspace_member
    where workspace_member.ws_id = table_name.ws_id
      and workspace_member.user_id = (select auth.uid())
      and workspace_member.type = 'MEMBER'
  )
  and public.has_workspace_permission(
    table_name.ws_id,
    (select auth.uid()),
    'manage_projects'
  )
);

-- DELETE uses USING because there is no new row to check
create policy "Project managers can delete data"
on public.table_name
for delete
to authenticated
using (
  exists (
    select 1
    from public.workspace_members workspace_member
    where workspace_member.ws_id = table_name.ws_id
      and workspace_member.user_id = (select auth.uid())
      and workspace_member.type = 'MEMBER'
  )
  and public.has_workspace_permission(
    table_name.ws_id,
    (select auth.uid()),
    'manage_projects'
  )
);
```

#### Role-based Access

Use `public.has_workspace_permission(p_ws_id, p_user_id, p_permission)` rather
than joining retired member-role columns. Permission checks should still be
paired with membership when a workspace-wide default permission must not admit
non-members.

If a policy needs a recursion-free membership lookup, keep the helper in a
non-exposed schema, derive identity from the request, and harden its execution
boundary before referencing it from a policy:

```sql theme={null}
create or replace function private.can_access_workspace(p_ws_id uuid)
returns boolean
language plpgsql
security definer
stable
set search_path = ''
as $$
declare
  v_caller_id uuid := (select auth.uid());
begin
  if coalesce((select auth.jwt() ->> 'role'), '') = 'service_role' then
    return true;
  end if;

  if v_caller_id is null then
    return false;
  end if;

  return exists (
    select 1
    from public.workspace_members workspace_member
    where workspace_member.ws_id = p_ws_id
      and workspace_member.user_id = v_caller_id
      and workspace_member.type = 'MEMBER'
  );
end;
$$;

revoke execute on function private.can_access_workspace(uuid)
from public, anon, authenticated, service_role;
grant execute on function private.can_access_workspace(uuid)
to authenticated, service_role;
```

Because `private` is not a Data API schema, this narrowly granted helper cannot
be invoked as an exposed RPC. A public Data API RPC needs its own internal
workspace permission check; a page or route check is not enough. Revoke
`public` and `anon`, grant only the required caller role, and cover the grant
matrix and allowed/denied calls with pgTAP. See
[Workspace-Scoped Security Definer RPCs](/reference/database/rls-policies#pattern-9-workspace-scoped-security-definer-rpcs).

```sql theme={null}
-- Allow full members with manage_projects to access a resource
create policy "Project managers can view workspace data"
on public.table_name
for select
to authenticated
using (
  exists (
    select 1
    from public.workspace_members workspace_member
    where workspace_member.ws_id = table_name.ws_id
      and workspace_member.user_id = (select auth.uid())
      and workspace_member.type = 'MEMBER'
  )
  and public.has_workspace_permission(
    table_name.ws_id,
    (select auth.uid()),
    'manage_projects'
  )
);
```

### Performance Optimization for RLS

For better performance in your RLS policies:

1. **Wrap function calls in subqueries**:

   ```sql theme={null}
   -- Instead of this
   using (auth.uid() = user_id);

   -- Use this
   using ((select auth.uid()) = user_id);
   ```

2. **Use hardened security-definer helpers only when needed**. The
   `private.can_access_workspace` recipe above shows the required caller,
   service-role, search-path, and grant controls. Wrap stable helper calls in a
   scalar subquery so Postgres can evaluate them once per statement:

   ```sql theme={null}
   create policy "Users can access workspace data"
   on public.table_name
   for select
   to authenticated
   using ((select private.can_access_workspace(table_name.ws_id)));
   ```

3. **Add explicit filters** in your queries even when you have RLS:
   ```typescript theme={null}
   // Even though RLS will filter by workspace_id, adding the filter explicitly improves performance
   const { data } = await supabase
     .from('projects')
     .select()
     .eq('workspace_id', workspaceId);
   ```

### Testing RLS Policies

Tuturuuu ships a large suite of database tests in
`apps/database/supabase/tests/`. These are [pgTAP](https://pgtap.org/) test files
(each one wraps its assertions in a transaction and rolls back), and they run
against the local Supabase instance through the Supabase CLI.

To run the database test suite locally:

1. Make sure a local Supabase instance is running (`bun sb:start`).
2. Add or edit a `*.sql` test file in `apps/database/supabase/tests/`.
3. Run the tests through the database workspace's Supabase CLI wrapper:

   ```bash theme={null}
   # From the repo root
   bun --cwd apps/database scripts/run-supabase.js test db
   ```

   `run-supabase.js` resolves the pinned local Supabase binary and invokes
   `supabase test db`, which executes every `tests/*.sql` file against the local
   database. There is no dedicated `bun sb:test` alias — the test runner is the
   Supabase CLI itself.

Each test file begins by enabling pgTAP, then uses helpers like `plan()`,
`is()`, and `throws_ok()` to assert behavior. A trimmed example:

```sql theme={null}
begin;

create extension if not exists pgtap with schema extensions;
set local search_path = public, extensions;

select plan(2);

-- Impersonate an authenticated user
set local role authenticated;
select set_config(
  'request.jwt.claims',
  '{"sub":"00000000-0000-0000-0000-000000000001","role":"authenticated"}',
  true
);

-- Should return data the user is allowed to see
select isnt_empty(
  $$ select 1 from public.workspaces where id = '00000000-0000-0000-0000-000000000000' $$,
  'User can see a workspace they belong to'
);

-- Should be blocked by RLS for an unrelated workspace
select is_empty(
  $$ select 1 from public.workspaces where id = '11111111-1111-1111-1111-111111111111' $$,
  'User cannot see a workspace they do not belong to'
);

select * from finish();
rollback;
```

<Info>
  Look through the existing files in `apps/database/supabase/tests/` (for
  example `user-profile-rls.sql` and the `private-schema-*` suites) to follow the
  established pgTAP patterns for impersonating roles and asserting RLS behavior.
</Info>

## Database Triggers

Triggers in Postgres allow you to automatically execute a function when a specified database event occurs (INSERT, UPDATE, DELETE). In Tuturuuu, we use triggers for various purposes like:

* Maintaining audit logs
* Syncing data between tables
* Enforcing complex business rules

### Creating Triggers

Here's how to create a trigger in your Tuturuuu development workflow:

1. First, create a trigger function:

```sql theme={null}
create or replace function public.handle_new_user()
returns trigger
language plpgsql
security definer
set search_path = ''
as $$
declare
  v_workspace_id uuid := gen_random_uuid();
begin
  -- Create a personal workspace for the new user
  insert into public.workspaces (id, name, personal, creator_id)
  values (v_workspace_id, new.email || '''s workspace', true, new.id);

  -- Record the creator as a full member without re-querying the workspace
  insert into public.workspace_members (ws_id, user_id, type)
  values (v_workspace_id, new.id, 'MEMBER');

  return new;
end;
$$;

revoke execute on function public.handle_new_user()
from public, anon, authenticated, service_role;
grant execute on function public.handle_new_user() to supabase_auth_admin;
```

2. Then, create the trigger:

```sql theme={null}
create trigger on_auth_user_created
  after insert on auth.users
  for each row
  execute function public.handle_new_user();
```

### Common Triggers in Tuturuuu

#### Audit Logging

```sql theme={null}
create or replace function private.audit_log_changes()
returns trigger
language plpgsql
security definer
as $$
begin
  insert into public.audit_logs (
    table_name,
    record_id,
    action,
    old_data,
    new_data,
    performed_by
  )
  values (
    TG_TABLE_NAME,
    coalesce(new.id, old.id),
    TG_OP,
    case when TG_OP = 'DELETE' or TG_OP = 'UPDATE' then row_to_json(old) else null end,
    case when TG_OP = 'INSERT' or TG_OP = 'UPDATE' then row_to_json(new) else null end,
    coalesce(auth.uid(), '00000000-0000-0000-0000-000000000000'::uuid)
  );
  return coalesce(new, old);
end;
$$;

-- Apply this trigger to a table
create trigger projects_audit_trigger
  after insert or update or delete
  on public.projects
  for each row
  execute function private.audit_log_changes();
```

#### Automated Timestamps

```sql theme={null}
create or replace function public.update_timestamp()
returns trigger
language plpgsql
as $$
begin
  new.updated_at = now();
  return new;
end;
$$;

-- Apply to a table
create trigger update_projects_timestamp
  before update
  on public.projects
  for each row
  execute function public.update_timestamp();
```

### Testing Triggers

You can test triggers by running SQL commands in the local Supabase instance and verifying the results:

```sql theme={null}
-- Insert a test user
insert into auth.users (id, email)
values ('test-uuid', 'test@example.com');

-- Verify the trigger created a workspace
select * from public.workspaces where creator_id = 'test-uuid';

-- Verify the creator is a full member of the workspace
select * from public.workspace_members
where user_id = 'test-uuid' and type = 'MEMBER';
```

## Seeding Your Database

Database seeding is the process of populating your database with initial data. In Tuturuuu, we use seeding to:

1. Create test users and workspaces for local development
2. Initialize lookup tables with standard values
3. Ensure a consistent starting point for all developers

### Seed Files Location

In Tuturuuu, seed files are stored in `apps/database/supabase/seed.sql`. This file is automatically executed when you run `bun sb:reset` or start a fresh Supabase instance.

### Real Examples from Tuturuuu's Seed File

Let's look at some real examples from Tuturuuu's seed.sql file:

#### 1. Authentication Users

The seed file creates five default test users with pre-set passwords:

```sql theme={null}
-- Populate auth users
INSERT INTO
    "auth"."users" (
        "instance_id",
        "id",
        "aud",
        "role",
        "email",
        "encrypted_password",
        "email_confirmed_at",
        /* other fields... */
    )
VALUES
    (
        '00000000-0000-0000-0000-000000000000',
        '00000000-0000-0000-0000-000000000001',
        'authenticated',
        'authenticated',
        'local@tuturuuu.com',
        crypt('password123', gen_salt('bf')),
        '2023-02-18 23:31:13.017218+00',
        /* other values... */
    ),
    /* additional users... */
```

All seed users have the same password: `password123`, making it easy to log in for testing.

#### 2. Workspaces

The seed creates several workspaces for testing different scenarios:

```sql theme={null}
-- Populate workspaces
insert into
    public.workspaces (id, name, handle, creator_id)
values
    (
        '00000000-0000-0000-0000-000000000000',
        'Tuturuuu',
        'tuturuuu',
        '00000000-0000-0000-0000-000000000001'
    ),
    (
        '00000000-0000-0000-0000-000000000001',
        'Prototype All',
        'prototype-all',
        null
    ),
    /* additional workspaces... */
```

#### 3. Workspace Members and Roles

The seed also sets up relationships between users and workspaces with different roles:

```sql theme={null}
-- Populate workspace_members
insert into
    public.workspace_members (user_id, ws_id, role)
values
    (
        '00000000-0000-0000-0000-000000000001',
        '00000000-0000-0000-0000-000000000000',
        'OWNER'
    ),
    (
        '00000000-0000-0000-0000-000000000002',
        '00000000-0000-0000-0000-000000000000',
        'ADMIN'
    ),
    (
        '00000000-0000-0000-0000-000000000003',
        '00000000-0000-0000-0000-000000000000',
        'MEMBER'
    ),
    /* additional members... */
```

#### 4. Workspace Features Configuration

The seed file configures workspace features using secrets:

```sql theme={null}
-- Populate workspace_secrets
insert into
    public.workspace_secrets (ws_id, name, value)
values
    (
        '00000000-0000-0000-0000-000000000000',
        'ENABLE_CHAT',
        'true'
    ),
    (
        '00000000-0000-0000-0000-000000000000',
        'ENABLE_EDUCATION',
        'true'
    ),
    /* additional features... */
```

#### 5. Domain-specific Data

The seed includes domain-specific data for different workspace types. For example, user group metric data:

```sql theme={null}
-- Populate user group metrics
insert into
    public.user_group_metrics (id, ws_id, name, unit, is_weighted)
values
    (
        '00000000-0000-0000-0000-000000000001',
        '00000000-0000-0000-0000-000000000003',
        'Nhiệt độ',
        '°C',
        true
    ),
    (
        '00000000-0000-0000-0000-000000000002',
        '00000000-0000-0000-0000-000000000003',
        'Chiều cao',
        'cm',
        false
    ),
    /* additional metrics... */
```

`user_group_metrics.is_weighted = false` keeps a metric visible for entry and category views without counting it toward report totals or averages. Metric categories live in `user_group_metric_categories` and are linked through `user_group_metric_category_links`.

When renaming or recreating these metric tables, keep authenticated CRUD grants and service-role grants in the same migration as the table change. The group indicators dashboard reads the renamed tables through protected API/server paths after workspace permission checks, and missing grants can surface as `permission denied for table user_group_metric_categories`.

When code uses `createAdminClient()` for these protected reads, name the local client `sbAdmin`. Do not name a service-role client `supabase`; reserve that name for request-scoped or user-scoped clients so route authorization is easy to audit.

### Creating Seed Data

Here's how to create and modify seed data:

1. Edit the `apps/database/supabase/seed.sql` file
2. Add SQL statements to insert your data
3. Run `bun sb:reset` to apply the seed data

Example seed data format:

```sql theme={null}
-- Create a new user group
INSERT INTO public.workspace_user_groups (id, name, ws_id)
VALUES
  ('your-uuid-here', 'New Group', 'workspace-uuid-here')
ON CONFLICT (id) DO NOTHING;

-- Add a new workspace feature
INSERT INTO public.workspace_secrets (ws_id, name, value)
VALUES
  ('workspace-uuid-here', 'ENABLE_NEW_FEATURE', 'true')
ON CONFLICT (ws_id, name) DO UPDATE
SET value = EXCLUDED.value;
```

### Creating a Custom Seed File

Sometimes you might want to create a custom seed file for specific testing scenarios:

1. Create a new SQL file in the `apps/database/supabase` directory
2. Add your custom seed data
3. Run it with the Supabase CLI:

```bash theme={null}
bun supabase db reset --db-url=postgresql://postgres:postgres@localhost:54322/postgres
psql postgresql://postgres:postgres@localhost:54322/postgres -f apps/database/supabase/my_custom_seed.sql
```

### Exporting Current Data as Seed

You can also export your current database data to use as seed data:

```bash theme={null}
# Export only data (not schema) to seed.sql
bun supabase db dump --db-url=postgresql://postgres:postgres@localhost:54322/postgres --data-only > apps/database/supabase/new_seed.sql
```

This is helpful when you've set up data manually and want to preserve it for future development environments.

### Recommended Seeding Workflow

For Tuturuuu development, we recommend:

1. Start with a fresh database: `bun sb:reset`
2. Make changes through the UI or your app
3. When you're satisfied, export the data: `bun supabase db dump --data-only > apps/database/supabase/new_seed.sql`
4. Edit the generated SQL to keep only what you need
5. Update the main `seed.sql` file with your changes
6. Test by running `bun sb:reset` again

## AI Integration with Vercel AI SDK

Tuturuuu uses Vercel's AI SDK for its AI features, utilizing structured data generation capabilities that integrate with Supabase. This section covers how to work with AI features in the development workflow.

### Overview of AI SDK in Tuturuuu

The AI SDK standardizes integrating various AI models across supported providers into Tuturuuu applications. It enables structured data generation, tool calling, and streaming responses to create rich AI-powered features.

The main libraries used are:

* `ai` - Core Vercel AI SDK package
* `@ai-sdk/google` - Provider-specific integration for Google models
* `@tuturuuu/supabase` - Supabase client with Tuturuuu-specific utilities

### Generating Structured Data

Tuturuuu uses the AI SDK's structured data generation capabilities to create typed responses from AI models. This approach ensures type safety and consistent data structures for features like:

* Flashcards generation
* Quiz generation
* Learning plans
* Task management

#### Example: Flashcard Generation

The structured data pattern used in Tuturuuu follows this workflow:

1. Define a schema using Zod
2. Connect to Supabase for authentication and workspace validation
3. Generate structured data using the AI SDK
4. Stream the response to the client

Here's an example from Tuturuuu's codebase:

```typescript theme={null}
// 1. Define the schema
import { z } from 'zod';

export const flashcardSchema = z.object({
  flashcards: z.array(
    z.object({
      front: z.string().describe('Question. Do not use emojis or links.'),
      back: z.string().describe('Answer. Do not use emojis or links.'),
    })
  ),
});

// 2. Setup API endpoint
export async function POST(req: Request) {
  const sbAdmin = await createAdminClient();
  const { wsId, context } = await req.json();

  // Validate user and workspace permissions
  const {
    data: { user },
  } = await supabase.auth.getUser();
  if (!user) return new Response('Unauthorized', { status: 401 });

  // Check workspace feature flag
  const { count, error } = await sbAdmin
    .from('workspace_secrets')
    .select('*', { count: 'exact', head: true })
    .eq('ws_id', wsId)
    .eq('name', 'ENABLE_CHAT')
    .eq('value', 'true');

  if (error) return new Response(error.message, { status: 500 });
  if (count === 0)
    return new Response('You are not allowed to use this feature.', {
      status: 401,
    });

  // 3. Generate structured data using AI SDK
  const result = streamObject({
    model: google('gemini-2.0-flash-001', {
      safetySettings: [
        // Safety settings configuration...
      ],
    }),
    prompt: `Generate 10 flashcards with the following context: ${context}`,
    schema: flashcardSchema,
  });

  // 4. Stream the response to the client
  return result.toTextStreamResponse();
}
```

### Available Models

Tuturuuu supports multiple AI models through Vercel AI SDK. You can define which models are available in your application by updating the `models.ts` file in the `packages/ai` directory:

```typescript theme={null}
export const models = [
  {
    value: 'gemini-2.0-flash-001',
    label: 'gemini-2.0-flash',
    provider: 'Google',
    description: 'Gemini 2.0 Flash delivers next-gen features...',
    context: 1000000,
  },
  // Add other models here...
];

export const defaultModel = models.find(
  (model) =>
    model.value === 'gemini-2.0-flash-001' && model.provider === 'Google Vertex'
);
```

### Creating Custom Schema Types

To create new structured data types for AI generation, add your schema definition to the `packages/ai/src/object/types.ts` file:

```typescript theme={null}
export const myNewSchema = z.object({
  items: z.array(
    z.object({
      name: z.string().describe('Name of the item'),
      description: z.string().describe('Description of the item'),
      priority: z.enum(['high', 'medium', 'low']).describe('Priority level'),
    })
  ),
});
```

### Integration with Supabase

Tuturuuu's AI features leverage Supabase for:

1. **Authentication** - Validating users before making AI requests
2. **Authorization** - Checking workspace permissions via `workspace_secrets`
3. **Feature Flags** - Using `workspace_secrets` to enable/disable AI features per workspace
4. **Storage** - Storing AI-generated content for later use

To enable AI features for a workspace, ensure the appropriate flags are set in the `workspace_secrets` table:

```sql theme={null}
-- Enable AI chat features for a workspace
INSERT INTO public.workspace_secrets (ws_id, name, value)
VALUES ('your-workspace-id', 'ENABLE_CHAT', 'true');

-- Enable AI document features for a workspace
INSERT INTO public.workspace_secrets (ws_id, name, value)
VALUES ('your-workspace-id', 'ENABLE_DOCS', 'true');
```

### Testing AI Features Locally

When testing AI features in your local environment:

1. Ensure you have the required API keys set in your `.env.local` file:

   ```
   GOOGLE_GENERATIVE_AI_API_KEY=your-api-key
   ```

2. Verify the workspace has the necessary feature flags enabled in your local database

   ```sql theme={null}
   SELECT * FROM workspace_secrets WHERE ws_id = 'your-workspace-id' AND name = 'ENABLE_CHAT';
   ```

3. Use the AI-enabled accounts from the seed data (`local@tuturuuu.com`) as they often have additional permissions

### Error Handling

When integrating AI features, implement proper error handling to account for:

1. Missing API keys
2. Model unavailability
3. Invalid user input
4. Exceeded token limits

Example error handling pattern used in Tuturuuu:

```typescript theme={null}
try {
  // AI SDK code here
} catch (error) {
  console.log(error);
  return NextResponse.json(
    {
      message: `## Edge API Failure\nCould not complete the request. Please view the **Stack trace** below.\n\`\`\`bash\n${(error as Error)?.stack || 'No stack trace available'}`,
    },
    {
      status: 200,
    }
  );
}
```


# Monorepo Architecture
Source: https://docs.tuturuuu.com/build/development-tools/monorepo-architecture

Understanding Tuturuuu monorepo architecture and the benefits of using Turborepo.

<Info>
  **Prerequisite**: You should have followed the
  [Development](/build/development-tools/development) setup guide to understand
  the basic structure of the codebase.
</Info>

## What is a Monorepo?

A monorepo is a single repository containing multiple distinct projects with well-defined relationships. This approach differs from a polyrepo strategy where each project has its own separate repository.

> "A monorepo is a single repository containing multiple distinct projects, with well-defined relationships."
> — [monorepo.tools](https://monorepo.tools/)

It's important to note that a monorepo is not the same as a monolith. A monolith is a single, tightly coupled application, while a monorepo can contain many independent applications, libraries, and tools that can be deployed separately.

## Why Tuturuuu Uses a Monorepo

Tuturuuu's platform is built as a monorepo (`@tutur3u/platform`) for several key reasons:

### 1. Code Sharing Without Overhead

Our monorepo structure makes it easy to share code across different applications and services without the overhead of publishing packages. Core components, utilities, and business logic can be shared across multiple applications without duplicating code.

```
platform/
├── apps/
│   ├── web/      # Main web application
│   ├── tanstack-web/ # TanStack Start migration frontend
│   ├── backend/  # Rust API runtime for migrated web APIs
│   ├── cms/      # Dedicated Tuturuuu CMS satellite app
│   ├── docs/     # Documentation site (Mintlify)
│   ├── rewise/   # Rewise application
│   ├── nova/     # Nova application
│   ├── calendar/ # Standalone calendar application
│   └── ...       # Other applications
└── packages/
    ├── ai/       # Shared AI functions & configurations
    ├── ui/       # Shared UI components
    ├── types/    # Shared TypeScript types
    ├── utils/    # Shared utilities
    ├── supabase/ # Supabase client and utilities
    └── ...       # Other shared packages
```

### 2. Atomic Changes Across Projects

When making changes that affect multiple parts of the platform, we can make those changes in a single commit. This ensures that all parts of the system remain compatible with each other, reducing integration issues.

For example, when updating a database schema:

1. We can update the Supabase schema in `apps/database/supabase/migrations`
2. Update the TypeScript types in `packages/types/src/supabase.ts`
3. Update all affected applications in the same pull request

### 3. Consistent Developer Experience

A monorepo allows us to standardize tooling, testing, and deployment processes across all projects. This creates a consistent development experience regardless of which part of the platform a developer is working on.

All developers use the same:

* Package manager (bun)
* Build system (Turborepo)
* Code style guidelines (enforced by Biome)
* Testing framework
* CI/CD pipelines

### 4. Simplified Dependency Management

Managing dependencies in a monorepo is simpler because we can ensure all projects use the same versions of shared dependencies, avoiding version conflicts.

## Why We Chose Turborepo

Tuturuuu uses [Turborepo](https://turborepo.org/) as its build system for several reasons:

### 1. Incremental Builds with Caching

Turborepo provides intelligent caching of build artifacts. This means that if a file hasn't changed, Turborepo will use the cached result instead of rebuilding it, significantly reducing build times.

```bash theme={null}
# Only builds what changed since the last build
bun run build
```

### 2. Parallel Task Execution

Turborepo automatically parallelizes tasks, maximizing the use of available CPU cores.

```bash theme={null}
# Runs lint across all packages in parallel
bun lint
```

### 3. Task Orchestration

Turborepo understands dependencies between packages and ensures tasks are run in the correct order.

```json theme={null}
// In turbo.json (Turbo 2.x uses "tasks", not the older "pipeline")
{
  "tasks": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": ["dist/**", ".next/**", "!.next/cache/**", "!.next/dev/**"]
    }
  }
}
```

Keep local Next development state out of Turbo build outputs. The `.next/dev`
tree belongs to `next dev`; archiving it can capture multi-GB Turbopack caches
and make `bun dev:web` slower.

When local `apps/web` compilation feels slow, run the dev-speed diagnostic
before changing code:

```bash theme={null}
bun diagnose:dev:web
```

It reports generated cache sizes, Next slow-filesystem warnings, and the
slowest `.next/dev/trace` spans from the previous `next dev` session. It also
flags watcher `EMFILE` errors; the web dev launcher raises the child process
open-file limit to `65536` by default, and unusual local shells can override
that with `TUTURUUU_DEV_MAX_OPEN_FILES`. Native local dev leaves
`WATCHPACK_POLLING` unset by default for lower watcher overhead; set
`WATCHPACK_POLLING=true` only when a local filesystem or container workflow
needs polling to keep route discovery reliable.

### 4. Remote Caching

For CI/CD pipelines, Turborepo supports remote caching, which means build artifacts can be shared across different environments.

## Monorepo Structure

Our monorepo is organized into several main directories:

### apps/

Contains all deployable applications. Each application is a standalone project that can be deployed independently.

```
apps/
├── web/      # Main web application and central API host
├── tanstack-web/ # TanStack Start frontend replacing apps/web
├── backend/  # Dedicated Rust API runtime for migrated web APIs
├── cms/      # Dedicated Tuturuuu CMS frontend
├── docs/     # Documentation site (Mintlify)
├── rewise/   # Rewise application
├── nova/     # Nova application
└── database/ # Database migrations and scripts
```

`apps/tanstack-web` and `apps/backend` are the migration pair for replacing the
legacy `apps/web` runtime. The TanStack app owns migrated frontend routes and
Start server functions; the Rust backend owns migrated API, job, cron, and
private/admin call paths. Both apps can run in Docker for local and blue/green
rehearsals, and both have Cloudflare Worker preview entrypoints:
`apps/tanstack-web/wrangler.jsonc` and `apps/backend/wrangler.jsonc`.

Cloudflare preview is incremental, not the production cutover. Bind
`BACKEND_INTERNAL_TOKEN`, `BACKEND_PUBLIC_ORIGIN`, and
`BACKEND_INTERNAL_URL` through Wrangler or Cloudflare secrets, run
`bun check:cloudflare` before preview deployment, and keep `apps/web` serving
production until the TanStack/Rust route manifest, Docker E2E compare report,
benchmark report, and migration gates pass.

### packages/

Contains shared libraries and utilities that are used by multiple applications.

```
packages/
├── ui/       # Shared UI components
├── types/    # Shared TypeScript types including Supabase types
├── utils/    # Shared utilities
├── ai/       # AI-related utilities
└── supabase/ # Supabase client and utilities
```

## Development Workflow

When working in our monorepo, you'll typically:

1. Clone the repository: `git clone https://github.com/tutur3u/platform.git`
2. Install dependencies: `bun install`
3. Start the development servers: `bun dev` or `bun devx` (with Supabase)

Satellite apps can also be started with app-specific scripts when you only need one frontend plus the shared `web` API host. For example, `bun dev:cms` runs the CMS app together with the shared packages and `apps/web`.

For more detailed instructions on development workflow, see the [Development](/build/development-tools/development) and [Local Supabase Development](/build/development-tools/local-supabase-development) guides.

## Best Practices

When working in our monorepo, follow these best practices:

### 1. Keep Projects Modular

Even though all code lives in one repository, maintain clear boundaries between projects. Each package or app should have a well-defined purpose and API.

### 2. Use Workspace References

When one project depends on another within the monorepo, use workspace references:

```json theme={null}
{
  "dependencies": {
    "@tuturuuu/ui": "workspace:*",
    "@tuturuuu/types": "workspace:*"
  }
}
```

### 3. Think About Build Order

Be mindful of dependencies between packages. If package B depends on package A, ensure that changes to package A trigger rebuilds of package B.

### 4. Use Correct Scope for Changes

* For changes that affect a single application, focus your changes there
* For changes that affect multiple applications, consider extracting common code to a shared package
* For global changes (like tooling updates), ensure you test across all affected projects

## Common Challenges and Solutions

### Challenge: Long Build Times

**Solution:** Turborepo's caching mechanism helps, but also:

* Be selective about what you build during development
* Use `bun --filter` to focus on specific packages

```bash theme={null}
# Only build the web app and its dependencies
bun --filter web... build
```

### Challenge: Dependency Management

**Solution:**

* Regularly update dependencies
* Bun automatically detects workspace packages from the root `package.json` workspaces field
* Consider using `bun dedupe` to eliminate duplicate dependencies

### Challenge: CI/CD Pipeline Complexity

**Solution:**

* Use GitHub Actions workflows that are specific to the affected parts of the codebase
* Leverage Turborepo's `--filter` and `--since` flags to only build what's changed

## Further Resources

* [monorepo.tools](https://monorepo.tools/): Comprehensive information about monorepos
* [Turborepo Documentation](https://turbo.build/repo/docs): Official Turborepo documentation
* [Bun Workspace](https://bun.sh/docs/install/workspaces): How bun handles monorepos


# Development Tools
Source: https://docs.tuturuuu.com/build/development-tools/overview

Tools and guides for developing on the Tuturuuu platform

This section contains tools, guides, and best practices for developing on the Tuturuuu platform.

## Getting Started

* [Development Setup](/build/development-tools/development) - Set up your development environment
* [Monorepo Architecture](/build/development-tools/monorepo-architecture) - Understand the project structure
* [Git Conventions](/build/development-tools/git-conventions) - Code contribution guidelines

## Development Workflow

* [Local Supabase Development](/build/development-tools/local-supabase-development) - Database development setup
* [CI/CD Pipelines](/build/development-tools/ci-cd-pipelines) - Continuous integration and deployment
* [DevOps & Deployment](/build/devops/overview) - Operational runbooks for environments, workflows, Docker, and secrets
* [Cleaning Clone](/build/development-tools/cleaning-clone) - Reset your local environment

## Documentation

* [Documenting](/build/development-tools/documenting) - How to write and maintain documentation

## Development Guidelines

### Code Quality

* Formatting and linting are handled by [Biome](https://biomejs.dev/) (`biome.json`),
  not ESLint or Prettier. Use `bun ff` to format, lint, and check in one pass.
* Run `bun check` before opening a PR — it is the repo's verification gate for
  TypeScript, JavaScript, root-script, and config changes (run focused tests first).
* Default to Server Components in `apps/web`; add `'use client'` only for state,
  browser APIs, or interactivity.
* Prefer typed expected errors and dependency services via `@tuturuuu/utils/effect`
  for new server/service orchestration.

### Git Workflow

* Use [Conventional Commits](/build/development-tools/git-conventions) for commit
  messages and branch names.
* The branch checker only accepts these prefixes: `feature/`, `feat/`, `fix/`,
  `bugfix/`, `hotfix/`, `release/`, `chore/`, `docs/`, `style/`, `refactor/`,
  `perf/`, `dependabot/`, and `claude/`.
* Keep commits atomic and write descriptive PR descriptions.
* Do not manually bump `TUTURUUU_PLATFORM_VERSION`, package versions, or
  changelogs — Release Please owns version updates.

### Testing

* Tests run with Vitest. Use `bun test` for the full suite or filter to a single
  workspace (for example `bun --filter @tuturuuu/web test`).
* Write unit tests for utilities and cover error scenarios.
* Run focused tests before the full `bun check` gate.

### Performance

* Default to server-side rendering and Server Components where possible.
* Use TanStack Query for client-side fetching and caching; avoid `useEffect` for
  data fetching.
* Minimize bundle size and profile performance regularly.

## Tools and Scripts

### Package Management

Dependencies are always installed from inside the owning workspace — never by
hand-editing the root `package.json` and never with a `--workspace` flag.

```bash theme={null}
# Install all dependencies
bun install

# Add a dependency to an app (e.g. apps/web)
cd apps/web && bun add <package>

# Add a dependency to a shared package (e.g. packages/ui)
cd packages/ui && bun add <package>

# Update dependencies across the monorepo
bun update-all
```

### Development Commands

```bash theme={null}
# Start all apps
bun dev

# Start a specific app
bun dev:web

# Run tests (Vitest)
bun test

# Run the full verification gate before a PR
bun check
```

### Database Commands

```bash theme={null}
# Start the local Supabase stack
bun sb:start

# Create a new migration
bun sb:new

# Apply pending migrations locally
bun sb:up

# Generate TypeScript types from the local schema
bun sb:typegen

# Reset the local database (re-runs all migrations + seeds)
bun sb:reset
```

<Warning>
  `bun sb:push` and `bun sb:linkpush` push migrations to the **remote**
  Supabase project and are reserved for the maintainer applying production
  changes. Do not run them — prepare migrations locally with `bun sb:up` and let
  the user apply production changes.
</Warning>

## Troubleshooting

### Common Issues

1. **Build / Check Failures**: Run `bun check` to surface TypeScript and Biome errors, and confirm dependencies are installed with `bun install`
2. **Database Issues**: Ensure the local Supabase stack is running (`bun sb:start`) and migrations are applied (`bun sb:up`)
3. **Test Failures**: Check environment setup and re-run the focused Vitest workspace before the full `bun check` gate
4. **Performance Issues**: Use React DevTools and bundle analyzers

### Getting Help

* Check existing documentation
* Search GitHub issues
* Ask in team channels
* Create detailed bug reports

## Contributing

When contributing to the platform:

1. Read the relevant documentation
2. Follow the established patterns
3. Write tests for new features
4. Update documentation
5. Submit a pull request with a clear description


# Remote Devboxes
Source: https://docs.tuturuuu.com/build/development-tools/remote-devboxes

Run heavy Tuturuuu development workflows on containerized self-hosted remote runners.

## Overview

Remote devboxes let internal root workspace members offload expensive local work
to self-hosted runner machines. A runner connects outbound to `tuturuuu.com`,
receives a synced dirty checkout, runs commands in an isolated container, streams
logs, stores artifacts, and releases the lease automatically for one-off work.

V1 is intentionally self-hosted. It does not provision cloud machines. Any
runner host should have Node.js, Bun, Docker, and Git available.

## Quick Start

```bash theme={null}
ttr login
ttr box doctor
ttr box setup
ttr box setup --dir .
ttr box setup --dir . --clone-into ./tuturuuu
ttr box agent register --name "ci-lab-1"
ttr box agent start --token <runner-token>
ttr box repair --dir .
ttr box upgrade --runner <runner-id>
TUTURUUU_DEVBOX_RUNNER_TOKEN=<runner-token> ttr box shutdown
```

`ttr box setup` is the default bootstrap for a runner host. It first checks
whether the current directory is already a Tuturuuu platform checkout. If it is,
setup reuses that checkout. Otherwise it can clone or reuse
`https://github.com/tutur3u/platform.git`, install dependencies with
`bun install --frozen-lockfile`, start local Supabase with `bun sb:start`,
verify `supabase status -o json`, and write local Supabase connection values
into ignored `apps/*/.env.local` files. Secret values are redacted from human
and JSON output.

Pass `--dir <path>` for a specific checkout. If the target exists but is not a
valid Tuturuuu checkout, interactive setup asks whether it should clone into a
nested `tuturuuu` directory. In non-interactive shells, pass
`--clone-into <path>` explicitly:

```bash theme={null}
ttr box setup --dir . --clone-into ./tuturuuu
```

Use `--yes` only when the host should install detected missing prerequisites
automatically. Runner registration and service installation are separate
choices.

To register the machine and install a boot-starting runner service in one
non-interactive command after login:

```bash theme={null}
ttr box setup --agent --service --runner-name "$(hostname)-devbox" --yes
```

The setup command stores the runner token in a restricted local env file and
installs a system-level runner service on Linux systemd or macOS launchd. The
service starts after reboot and restarts automatically if the runner exits.
Runner heartbeats report a small observability snapshot, including `ttr`, Bun,
Node, Docker, Git, OS, CPU, RAM, load average, and uptime. Root workspace admins
can inspect those fields from Infrastructure > Devboxes.

Devbox agent poll and heartbeat traffic is blocked by default at the platform
API boundary. Set `TUTURUUU_DEVBOX_AGENT_API_ENABLED=true` on the web app before
starting or repairing runners. When the flag is absent, agent poll and heartbeat
requests return `403` before runner tokens are authenticated or runner state is
updated.

If a host completed `ttr box setup` but does not appear in Infrastructure >
Devboxes, confirm it was registered as a runner. Plain setup prepares the
checkout, dependencies, local Supabase, and ignored env files only; it does not
create a `private.devbox_runners` row. Run setup with `--agent --service`, or
register and start the agent manually, then confirm `ttr whoami` on that host is
pointing at the same production origin and root workspace user.

If the host appears as registered but shows no heartbeat, inspect the installed
service on that host:

```bash theme={null}
sudo systemctl status --no-pager --full tuturuuu-devbox-runner.service
sudo journalctl -u tuturuuu-devbox-runner.service -n 80 --no-pager
```

The runner service reads its token from the local `devbox-runner.env` file. If
the journal shows a missing runner token or stale wrapper, upgrade the CLI and
repair the service. Repair reuses the existing token file; it does not register
a new runner token or create another runner row.

```bash theme={null}
ttr upgrade
ttr box repair --dir .
```

Use dry-run first when you want to confirm the checkout, token file, service
manager, wrapper path, and service path without writing files or calling sudo:

```bash theme={null}
ttr box repair --dir . --dry-run
```

Upgrade a runner's global CLI through the same brokered queue:

```bash theme={null}
ttr box upgrade --runner <runner-id>
```

The upgrade command queues `bun i -g tuturuuu` for the selected runner, waits
for completion, and returns the remote command logs and exit code.

Remove a runner from the cluster from the runner host with its runner token:

```bash theme={null}
TUTURUUU_DEVBOX_RUNNER_TOKEN=<runner-token> ttr box shutdown
```

Shutdown deletes the runner's server-side token rows and marks the runner
revoked. If the host installed a systemd or launchd runner service, stop and
disable that service as well so the OS does not keep restarting an invalid
agent process.

Run heavy commands remotely:

```bash theme={null}
ttr box run -- bun check
ttr box run -- bun sb:reset
ttr box run -- bun test:e2e
ttr box build --cwd apps/web
```

By default, `ttr box run` creates an auto lease, waits for an authenticated
runner to claim the job, streams recorded logs after completion, and releases
the lease after one-off work. Use `--keep` for repeated sync/run work:

```bash theme={null}
ttr box run --keep --preview-port 7803 -- bun test:e2e
ttr box sync --lease <lease-id> --watch
ttr box preview --lease <lease-id> --port 7803
ttr box release <lease-id>
```

## Build, Serve, And Tunnel

Use `ttr box build` for common build workloads without spelling the full remote
command every time:

```bash theme={null}
ttr box build
ttr box build --cwd apps/web
ttr box build --build-command "bun turbo:local run build -F @tuturuuu/web"
```

Use `ttr box serve` when the remote devbox should build an app, start the
server, and keep the run alive. It defaults to `apps/web` on port `7803`, stores
the preview port on the run, and returns immediately unless `--wait` is passed:

```bash theme={null}
ttr box serve --cwd apps/web --port 7803
ttr box preview --lease <lease-id> --port 7803
ttr box logs <run-id>
ttr box stop <run-id>
```

`ttr box build`, `ttr box serve`, and `ttr box tunnel` do not set a remote
command timeout by default. Pass `--timeout <duration>` only when the run should
be killed automatically.

To expose a served app through a Cloudflare tunnel, keep the token in a local
environment variable and pass the variable name to the devbox. The queued
command references `$CLOUDFLARED_TOKEN`; the raw token is delivered only as
run-scoped env and is redacted from logs.

```bash theme={null}
export CLOUDFLARED_TOKEN=<token-from-cloudflare>
ttr box serve --cloudflared --cloudflared-token-env CLOUDFLARED_TOKEN
ttr box tunnel --cloudflared-token-env CLOUDFLARED_TOKEN
```

`ttr box tunnel` runs a dockerized `cloudflare/cloudflared` container with host
networking on the runner. The command policy blocks inline `cloudflared --token ...` arguments, so operators should use `--cloudflared-token-env` or
another local environment variable indirection rather than pasting raw tokens
into commands.

## Container Boundary

Commands run in a per-lease Docker container or Compose project. The runner
mounts only the synced workspace and named cache volumes. Host execution is not
exposed in v1, and arbitrary host path mounts are blocked unless an operator
explicitly allowlists them.

Allowed remote workflows include:

* `bun check`, `bun test`, and package-local Bun commands
* `bun test:e2e` and Docker-backed Playwright workflows
* `bun sb:start`, `bun sb:reset`, `bun sb:up`, and `bun sb:typegen`

Blocked defaults include privileged Docker containers, Docker prune-all style
commands, absolute host mounts, `sudo`, and host-destructive filesystem
operations.

## Env And Secrets

Remote env is explicit. Local `.env*` files are never synced automatically.
The setup command only prepares ignored app env files inside the runner
checkout so local Supabase-backed apps and E2E workflows can use that runner's
own Supabase stack.

```bash theme={null}
ttr box run --env DATABASE_URL=postgres://remote -- bun check
ttr box run --database-url-env DEVBOX_DATABASE_URL -- bun check
ttr box serve --database-url-env DEVBOX_DATABASE_URL
ttr box run --env-file .env.remote -- bun test:e2e
ttr box env set --lease <lease-id> API_TOKEN=value
ttr box env unset --lease <lease-id> API_TOKEN
```

Brokered env values are scoped to the run or lease, delivered only to the
claimed runner, and redacted from command logs.

For split-resource development, run Supabase or another database on one devbox,
publish its reachable URL as `DEVBOX_DATABASE_URL` on the operator machine, and
queue the app devbox with `--database-url-env DEVBOX_DATABASE_URL`. This lets a
database-heavy runner and a Next.js runner share work while the current machine
only brokers commands and opens previews.

## Cache Policy

Runners use named cache volumes for Bun installs, Turbo, Playwright browsers,
Supabase Docker state, package manager cache, and optional `node_modules`.
Cache keys include the repo fingerprint, lockfile hash, runtime image digest,
platform, command profile, Bun/Node versions, and cache schema version.

Cleanup runs on runner startup, after runs, and during heartbeat maintenance.
The runner evicts incompatible caches first, including legacy Bun install caches
when the Bun version, lockfile hash, package profile, or cache schema changes.
It then enforces cache budgets with least-recently-used eviction while keeping a
small set of recent compatible caches to avoid thrashing.

Operators can inspect and prune cache metadata:

```bash theme={null}
ttr box cache list
ttr box cache doctor
ttr box cache prune
```

## Access

Remote devbox API routes require a Tuturuuu CLI/app session and root workspace
membership with `workspace_members.type = 'MEMBER'`. Guests and non-root
workspace users cannot create runs, leases, previews, or runner tokens.

## Local Executable Verification

Use an isolated CLI config when testing local `apps/web` so the production CLI
session is not overwritten:

```bash theme={null}
bun sb:status
docker exec supabase_db_tuturuuu psql -U postgres -d postgres -tAc "select to_regclass('private.devbox_leases'), exists (select 1 from supabase_migrations.schema_migrations where version = '20260603171600')"
TUTURUUU_CONFIG=/tmp/ttr-devbox-local-config.json bun ttr login --base-url http://localhost:7803
TUTURUUU_CONFIG=/tmp/ttr-devbox-local-config.json bun ttr box agent register --name local-devbox
TUTURUUU_CONFIG=/tmp/ttr-devbox-local-config.json bun ttr box agent start --token <runner-token>
TUTURUUU_CONFIG=/tmp/ttr-devbox-local-config.json bun ttr box run -- bun --version
```

The final command should print the remote command logs and exit with the remote
command's exit code. In local Supabase, `private.devbox_runs.status` should end
as `succeeded` with `exit_code = 0`.

## Production Readiness

The production API needs migration
`20260603171600_create_private_devboxes.sql` before any `ttr box` command can
create leases or runs. If the CLI prints a schema-cache error such as
`private.devbox_leases` not being found, first confirm the production migration
workflow ran for the deployed SHA. If the table exists but PostgREST still
returns the schema-cache error, refresh the schema cache from Supabase SQL
Editor:

```sql theme={null}
select to_regclass('private.devbox_leases');
select version from supabase_migrations.schema_migrations
where version = '20260603171600';
notify pgrst, 'reload schema';
```


# Adaptive Abuse Rate Limits
Source: https://docs.tuturuuu.com/build/devops/adaptive-abuse-rate-limits

Operate the reputation layer that distinguishes trusted organic users from risky automation without exposing static scoring rules.

## Overview

Authenticated rate limits now use a server-side reputation layer. The layer
scores users, sessions, API keys, IPs, CIDRs, and user-location pairs from
auditable signals, then returns a coarse risk tier and rate-limit multiplier to
the API and PostgREST guards.

The policy is intentionally server-only. The repository is open source, so do not
move scoring thresholds, bypass rules, or detailed reason codes into client code,
response headers, or public docs. User-agent, missing-header, and request-shape
checks are weak signals; they can raise caution but cannot earn trust by
themselves.

## Trust Tiers

| Tier                 | Operator meaning                                       | Rate-limit behavior                                  |
| -------------------- | ------------------------------------------------------ | ---------------------------------------------------- |
| `trusted`            | Sustained low-risk, organic usage with no recent abuse | Higher authenticated budgets                         |
| `standard`           | Normal authenticated activity or fail-safe default     | Current authenticated budgets                        |
| `watch`              | Suspicious but not high-confidence abuse               | Standard or slightly lower budgets                   |
| `challenge_required` | Medium-risk browser mutation activity                  | Browser mutation routes require Turnstile step-up    |
| `restricted`         | High-risk activity or manual restriction               | Stricter budgets and normal abuse blocks still apply |

Trust never bypasses active user suspension, active IP blocks, sensitive auth
route protections, workspace-secret hard overrides, or severe backend abuse
cascades.

One exception exists for active IP blocks: an authenticated user who passes
Turnstile through `/api/v1/rate-limit-appeals` can receive a short Redis relief
key scoped to the same browser session and `ip:<address>`. The relief only lets
that session continue while admins review the appeal; it does not clear the
global `blocked_ips` row or help unrelated users behind the same IP.

## API Abuse IP Blocks

Session-authenticated routes may defer proxy-side `api_abuse` IP blocks only
long enough to validate route authentication. Do not treat bearer-shaped tokens,
`ttr_` strings, Supabase auth cookie names, or app-session cookie presence as
proof of an authenticated session. If the route auth check fails, return the
original block response before invoking the handler or recording normal auth
failure side effects.

## Emergency Protection Controls

Platform admins with root workspace `manage_workspace_roles` can temporarily
disable edge IP blocking or route rate limits from Infrastructure -> Rate
Limits. The controls are stored in Redis for the proxy runtime.

Redis-backed protection is intentionally availability-sensitive. When Redis is
not configured, cannot initialize, or a Redis command fails, `apps/web` fails
open for route rate limits, abuse counters, and IP-block enforcement. The app
continues to run authentication, authorization, payload-size checks, Turnstile,
user suspension, and normal request validation, but it does not enforce stale
database/manual IP blocks or process-local fallback buckets. Restore Redis to
restore rate-limit and IP-block enforcement.

* Disabling IP blocking stops enforcement of cached `ip:blocked:<ip>` entries
  and prevents proxy abuse counters from creating new edge IP blocks. It does
  not delete `blocked_ips` rows or existing Redis block keys.
* Disabling route rate limits skips the proxy read/mutate buckets while leaving
  payload size checks and malformed request validation active.

Use these controls only for incident response or false-positive mitigation.
Re-enable them after the affected traffic pattern is understood and prefer
specific trusted workspace, IP, CIDR, or user overrides for durable fixes.

## Signals

The layer records rolling signals for:

* rate-limit hits, failed auth, repeated `4xx`, `401`, `403`, and `429`
* payload abuse and automation-like clients
* missing or scripted browser headers as weak negative signals
* older accounts, stable sessions, successful organic usage, and passed
  challenges as positive signals
* admin overrides and override revocations

If reputation lookup, challenge verification, or signal recording fails, request
handling must fall back to standard limits. Failures must never grant elevated
limits.

## Backend 429 Cascades

Supabase Auth and PostgREST/backend `429` responses are availability signals,
not user-scoped abuse proof. Handlers return `429` to the caller with
`Retry-After`, but a single backend rate limit must not create or extend
`ip:blocked:<ip>`, `blocked_ips`, or `user_suspensions`. User suspension
requires manual operator action or repeated, user-attributable abuse counters,
and automated suspensions should be expiry-bound unless a separate policy
explicitly justifies permanence.

## Shared-IP Login Traffic

English centers, classrooms, and offices often put many legitimate teachers
behind one public NAT IP. The proxy guard therefore keeps password login, OTP
send, and OTP verify on separate auth buckets instead of sharing the generic
mutation budget:

| Policy           | Default minute/hour/day budget | Override variables                                                                                                   |
| ---------------- | ------------------------------ | -------------------------------------------------------------------------------------------------------------------- |
| `password-login` | `60 / 600 / 4000`              | `API_PROXY_PASSWORD_LOGIN_LIMIT_MINUTE`, `API_PROXY_PASSWORD_LOGIN_LIMIT_HOUR`, `API_PROXY_PASSWORD_LOGIN_LIMIT_DAY` |
| `otp-send`       | `30 / 180 / 300`               | `API_PROXY_OTP_SEND_LIMIT_MINUTE`, `API_PROXY_OTP_SEND_LIMIT_HOUR`, `API_PROXY_OTP_SEND_LIMIT_DAY`                   |
| `otp-verify`     | `60 / 600 / 4000`              | `API_PROXY_OTP_VERIFY_LIMIT_MINUTE`, `API_PROXY_OTP_VERIFY_LIMIT_HOUR`, `API_PROXY_OTP_VERIFY_LIMIT_DAY`             |

OTP send also has a shared-IP abuse guard with
`ABUSE_OTP_SEND_IP_LIMIT_MINUTE`, `ABUSE_OTP_SEND_IP_LIMIT_HOUR`, and
`ABUSE_OTP_SEND_IP_LIMIT_DAY`. Keep the per-email cooldown/hour/day limits in
place; they are the primary protection against repeated sends to the same
mailbox. Human auth route `429` responses should return `Retry-After`,
`X-RateLimit-Client-IP`, and `X-RateLimit-Policy` to the caller so the
rate-limit details dialog can show the server-observed public IP and policy
without asking the customer to visit a separate IP lookup page. These auth
`429`s must not be converted into `api_abuse` IP blocks by the proxy escalation
path. Utility-level OTP send, OTP verify, MFA verify, reauth verify, and
password-login failure counters also throttle without writing `blocked_ips`
rows; their abuse events include `hard_block_suppressed` metadata when the old
hard-block threshold would have been crossed. Generic anonymous API route-limit
hits, malformed auth-cookie abuse, scanner-like requests, `api_auth_failed`, and
manual operator blocks can still escalate to hard IP blocks.

## Trusted-Location Read Uplift

High-density centers (many staff behind one office NAT IP) can hit the read-limit
toast ("Bạn đang bị giới hạn tần suất. Thử lại sau 60 giây…") during normal
browsing. Untrusted read traffic keys per `ip:<ip>` against the anonymous default
(`60 / 240 / 1200` per minute/hour/day), so everyone behind the shared IP draws
from one bucket. A trusted-location override keyed by CIDR scales that bucket at
the edge (e.g. `60 -> 300/min` at `5x`) and lets trusted sessions key
per-session. The `subject_key` must match the edge `getCidrSubjectKeyEdge` form
(`cidr:<a.b.c>.0/24` for IPv4, `cidr:<prefix>::/64` for IPv6).

1. Confirm the center's public IP via Infrastructure -> Abuse Intelligence or by
   asking the center, then derive the `/24`.
2. Insert a time-bound override. An operator runs this against production; the
   platform never auto-pushes production SQL:

```sql theme={null}
insert into public.abuse_trust_overrides
  (subject_type, subject_key, tier, trust_multiplier, limit_mode, reason, expires_at)
values
  ('cidr', 'cidr:203.0.113.0/24', 'trusted', 5.00, 'inherit_multiplier',
   'Trusted center office NAT — many staff, organic read traffic',
   now() + interval '90 days');
```

3. The edge trust cache (`EDGE_TRUST_CACHE_TTL_SECONDS`, \~1h) reconciles via
   `list_trusted_subjects_for_cache()` and the `sync-trust-cache` cron, so the
   uplift takes effect within the TTL without a deploy. Set
   `API_PROXY_EDGE_TRUST_ENABLED=0` as a kill switch to fall back to legacy
   per-IP read limiting.

Fix read amplification in the app first (batch per-row table fetches server-side
so one page load costs a few reads, not dozens); the location uplift is
defense-in-depth for genuinely dense, legitimate locations.

## Trusted-Workspace Uplift

Admins can also raise limits for a legitimate high-volume workspace from
Infrastructure -> Rate Limits by creating a `workspace` subject rule:

* `subject_type`: `workspace`
* `subject_key`: `workspace:<workspace_uuid>`
* `tier`: `trusted`
* `limit_mode`: `inherit_multiplier`
* `trust_multiplier`: start at `3`
* `expires_at`: prefer 30-90 days

Workspace rules are enforced at the edge for workspace-scoped API reads and are
visible in the Rate Limits admin center. They are safer than globally unblocking
or uplifting a noisy IP when many unrelated organizations may share that public
address. Keep them time-bound and review live usage before renewing.

## Rate-Limit Appeals

When the details dialog shows `X-Proxy-Block-Reason: ip-already-blocked`, the
request is being rejected by an active hard IP block. Raising route limits alone
will not unblock that user. Admins should first inspect Infrastructure ->
Blocked IPs and Abuse Intelligence, then clear the block if it is a false
positive.

Legitimate authenticated users can submit a review request from the rate-limit
details dialog. The submission route is the only route allowed through an active
IP block, and it still requires:

* an authenticated session cookie
* a valid Turnstile token
* bounded sanitized diagnostics from the dialog
* a low per-user/IP appeal throttle

Submitting an appeal writes `rate_limit_appeals` and grants only temporary
session+IP relief. From Infrastructure -> Rate Limit Appeals, admins can approve,
reject, or close the appeal. Approval clears the active IP block and, by
default, creates a time-bound trusted workspace rule with `3x` multiplier for 30
days. Admins can edit the workspace ID, multiplier, and expiry before approval,
or create more specific IP/CIDR/user rules manually from Infrastructure -> Rate
Limits.

## Step-Up Challenges

Browser mutations with medium risk should require Turnstile through the existing
server verification path. The API returns a generic challenge-required response
without exposing the exact scoring rules. API keys, CLI calls, cron jobs,
webhooks, and native clients do not receive browser challenges; they rely on
token, workspace, and API-key reputation instead.

## Local E2E Isolation

The Playwright rate-limit suite intentionally exhausts budgets and records 429
signals. Its `resetDbRateLimits()` helper must clear both PostgREST rate-limit
counters and generated adaptive abuse state (`abuse_activity_signals`,
`abuse_step_up_challenges`, and `abuse_reputation_subjects`) before each spec.
Specs that intentionally hit authenticated route limits should use Redis and a
fresh local dev-session account per test/retry so Redis-backed user keys and
asynchronous adaptive reputation writes cannot bleed into the next case. Without
Redis, `apps/web` rate-limit and IP-block checks fail open and will not produce
the expected `429` responses.

## Admin Investigation

Use Infrastructure -> Abuse Intelligence to inspect:

* trusted, watched, and restricted subject counts
* recent signals and coarse reason codes
* challenge pass/fail trends
* risky users, sessions, API keys, IPs, and CIDRs
* active manual overrides

When investigating a false positive:

1. Check whether the subject has recent rate-limit, auth-failure, or payload
   abuse signals.
2. Compare the subject with related location and user-location entries.
3. Review challenge outcomes and recent route diversity before granting trust.
4. Add a time-bound override only when the activity is clearly organic.
5. Revoke trust immediately if the subject later shows scripted behavior,
   account takeover indicators, or noisy API-key traffic.

For a live classroom login incident, ask the customer to open the rate-limit
details dialog and share the copied details. Use the `identity.clientIp`,
`limit.retryAfterSeconds`, and `limit.policy` fields to check Infrastructure ->
Abuse Intelligence for active IP blocks or abuse events with `api_abuse` or
`password_login_failed`. If the activity is confirmed organic, clear the active
false-positive block, reset affected counters, or add a time-bound IP/CIDR trust
or rate-limit uplift. Do not relax the per-email OTP cooldown or failed-attempt
protections.

If the copied details include `limit.proxyBlockReason =
ip-already-blocked`, route-limit tuning is secondary. Clear the active block or
approve the user's Rate Limit Appeal first, then decide whether the root cause
needs a trusted workspace, IP/CIDR uplift, or app-level batching fix.

Manual overrides require a reason and are written to the audit signal stream.
Prefer expiry-bound overrides for trust and watch decisions so stale operational
judgment does not become permanent policy.


# Chat Realtime Runbook
Source: https://docs.tuturuuu.com/build/devops/chat-realtime-runbook

Operating notes for the internal Chat realtime sidecar and web API proxy.

Chat realtime lives in `apps/chat-realtime`. It is an internal Bun SSE service
used by `apps/web` for workspace chat fanout. Browser clients never connect to
the sidecar directly; they subscribe to
`/api/v1/workspaces/:wsId/chat/realtime`, and `apps/web` verifies membership,
mints a short-lived internal token, connects to the sidecar, and forwards SSE
events back through the normal web origin.

## Required Environment

* `CHAT_REALTIME_TOKEN_SECRET`: preferred shared HMAC secret used by `apps/web`
  and `apps/chat-realtime`. If unset, both fall back to the platform Supabase
  service secret. Production should set this explicitly when rotating realtime
  credentials independently.
* `CHAT_REALTIME_INTERNAL_URL`: Docker-internal origin for `apps/web`, normally
  `http://chat-realtime:7817`. Local non-Docker `bun dev` defaults to
  `http://localhost:7817`.

No Cloudflare tunnel port is required for Chat realtime. The public route is the
existing `apps/web` API path, which keeps authorization, cookies, app-session
auth, and deployment topology owned by the web container.

## Blue/Green Deployment

`docker-compose.web.prod.yml` includes `chat-realtime` as a support sidecar
managed by the blue/green watcher. The sidecar exposes only port `7817` inside
the Compose network. `apps/web` publishes committed chat mutations to
`POST /publish`; clients receive them via the proxied SSE stream.

Every published event must include an explicit `audience`. Channel events use a
workspace audience, while direct, group, and AI conversation events use a
user-list audience derived from the authorized conversation members. The sidecar
keeps workspace rooms for connection management, but it filters each event by
that audience before sending any full conversation or message payload to a
client.

If Chat realtime is unavailable, chat mutations still succeed. The web API logs
the publish failure and clients continue to recover through normal query
refetching and reconnects.


# Environments & Release Flow
Source: https://docs.tuturuuu.com/build/devops/environments-release-flow

How branches map to environments, and what happens between preview, staging, production, and self-hosted deploys.

This page explains how Tuturuuu moves from code to running environments.

## Branch-to-Environment Map

| Branch or event                     | What deploys                                                                                       | Follow-up automation                                                                                                                 |
| ----------------------------------- | -------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| Feature branch push                 | CI only; Vercel preview deployments require trusted manual dispatch from `main` with `preview_ref` | None by default                                                                                                                      |
| `main` push                         | Platform Vercel preview build validation                                                           | `supabase-staging.yaml` can apply staging migrations after the preview build succeeds                                                |
| `production` push                   | Platform Vercel production deployment                                                              | `supabase-production.yaml` can apply production migrations after the deployment and staging prerequisites pass                       |
| `main` push for `apps/discord`      | Discord Modal deployment after Python CI succeeds                                                  | None                                                                                                                                 |
| Manual `workflow_dispatch`          | Depends on workflow                                                                                | Bypasses normal branch trigger timing, but not the workflow logic; production Supabase migration dispatches must select `production` |
| Self-hosted server after `git pull` | Docker deploy from current checkout                                                                | Optional blue/green cutover through `bun serve:web:docker:bg`                                                                        |

## Hosted Web Release Flow

### Preview

* Preview workflows are named `vercel-preview-<app>.yaml`.
* Most preview workflows are manual-only from `main` with a required
  `preview_ref`; `vercel-preview-platform.yaml` also triggers on protected
  `main` pushes so the staging database workflow receives a same-SHA platform
  build signal.
* `e2e-tests.yaml` also runs only on non-`production` pushes; production
  promotion relies on the already-green validation before the branch is
  promoted plus the production build-validation gates below.
* Production workflows cancel superseded per-app runs only when a newer
  `production` push arrives; `main` commits and manual recovery runs leave an
  active production deployment untouched.
* Each deploy job is bound to a `vercel-preview-<app>` GitHub Environment and
  introduces Vercel credentials only after dependency installation.
* Platform preview is build validation only; on-premise machines own the actual
  `apps/web` runtime deployment.
* Satellite preview deploys remain the normal Vercel validation surface for
  branch work and merged `main` changes.
* Platform preview can reuse a successful same-SHA production platform build
  marker to avoid redundant preview builds. Production does not reuse preview
  markers because it must build and deploy the prebuilt production artifacts.

### Staging Database

* `supabase-staging.yaml` is tied to the `Vercel Platform Preview Deployment` workflow on `main`.
* The staging migration runs only when the triggering platform preview build concludes successfully, or when manually dispatched.
* The staging deploy step runs `supabase db push --include-all` after linking
  the staging Supabase project, so staging can converge after `main` migration
  history changes.
* This means `main` is where app preview and staging schema advancement are
  meant to stay aligned.
* If a production commit was promoted before the same-SHA staging migration run
  existed, manually dispatch `supabase-staging.yaml` from `main`; production
  migration re-evaluates after that staging run succeeds.

### Production

* Satellite production web deploys run through `vercel-production-<app>.yaml`.
* A production push first runs `vercel-production.yaml`, which computes all
  affected apps in one runner and dispatches only the necessary per-app
  workflows. Each target uses its own last successful deployment marker, so an
  app skipped on an earlier commit still receives any undeployed changes.
* Hosted `apps/web` production deploys run through
  `vercel-production-platform.yaml`; self-hosted machines still use the Docker
  release flow below for their own runtime deployment.
* `apps/apps` production deploys are handled by `vercel-production-apps.yaml`.
* `apps/qr` production deploys are handled by `vercel-production-qr.yaml`.
* Each production app uses a workflow-and-branch concurrency group whose
  `cancel-in-progress` predicate matches only `production` push events, so the
  newest production SHA remains deployable without letting `main` commits or
  manual recovery runs cancel it.
* Production deploy jobs are bound to `vercel-production-<app>` GitHub
  Environments and reject manual dispatches unless the selected branch is
  `production`.

### Browser App Version Metadata

* Browser apps share one platform version from
  `packages/utils/src/platform-release.ts`; do not read visible app versions
  from individual app `package.json` files.
* The shared browser app version is the `TUTURUUU_PLATFORM_VERSION` constant
  exported from `packages/utils/src/platform-release.ts`. Release Please owns
  that value (it carries the `x-release-please-version` annotation), so do not
  pin a literal version in docs or bump it by hand. Read the constant directly
  when you need the current value.
* Every Vercel browser app workflow runs
  `bun run --silent scripts/ci/generate-build-metadata.ts` before
  `vercel build`. The generated metadata includes the commit hash, short hash,
  commit message, ref, environment, deployment URL, deployment stamp, and build
  timestamp.
* The account-scoped version badge uses `public.user_configs` key
  `SHOW_VERSION_BADGE`. It is hidden by default and only exact
  `@tuturuuu.com` accounts may enable a truthy value.
* Exact-domain enforcement happens on the server through
  `isExactTuturuuuDotComEmail`; subdomains such as `@xwf.tuturuuu.com` are not
  eligible, and client cookies cannot make the badge render for ineligible
  users.

### Production Database

`supabase-production.yaml` is stricter than staging:

1. It re-evaluates automatically after either `Vercel Production Deployment
   Planner` completes its selected production deploys on `production` or
   `Supabase Staging Migration` completes on `main`.
2. The production planner for the target commit must have concluded
   successfully on `production`, and the selected platform deployment must have
   recorded the successful
   `vercel-production-platform` deployment marker for the same SHA. A workflow
   run that skipped because package releases were still publishing is not
   enough.
3. The `main` staging migration for the same target commit must have completed
   with a `success` conclusion.
4. A manual dispatch can still be used when an operator explicitly wants to run
   it, but the dispatch must select the `production` branch and still satisfy
   the same production-deployment and staging-migration SHA checks.

The staging-triggered path is an automatic retry for the case where production
production deploy finishes before staging migration does. The production
migration job still checks out the verified target commit explicitly before
running `supabase db push --include-all`. This keeps production schema changes
behind application deployment, staging validation, and branch promotion
for the same commit.

## Self-Hosted Web Release Flow

If a server receives code through `git pull`, use the Docker production commands from
the checked-out commit:

* `bun serve:web:docker` for in-place replacement
* `bun serve:web:docker:bg` for blue/green rebuild-before-cutover deployment

Blue/green is the safer path when uptime matters because the new image is built and
health-checked before the proxy is reloaded.

## Migration Release Path (TanStack + Rust)

`apps/web` (Next.js, port `7803`) is being replaced by `apps/tanstack-web`
(TanStack Start) plus `apps/backend` (the Rust HTTP core, port `7820`). See
[the TanStack/Rust migration overview](/platform/architecture/tanstack-rust-migration)
for the full plan.

While that migration is incomplete, Docker blue/green remains the canonical
production rollout and rollback mechanism for the live hostname. Cloudflare
Workers are used as a separate, incremental **preview** surface to prove Worker
compatibility for `apps/tanstack-web` and `apps/backend` before any cutover:

* Validate the Wrangler deploy configs without contacting Cloudflare with
  `bun check:cloudflare`.
* Deploy the Rust backend Worker (`apps/backend/wrangler.jsonc`) and the
  TanStack Start Worker (`apps/tanstack-web/wrangler.jsonc`) to preview, then
  smoke both returned origins with `bun smoke:cloudflare`.
* Do not route the production hostname to preview Workers until the
  TanStack/Rust route manifest, compare-mode Docker E2E, benchmark report, and
  cutover gates (`bun migration:tanstack:gates`) all pass.
* Rollback from the preview path is DNS/routing-based (remove the Cloudflare
  route or roll back the Worker version); the Docker blue/green `apps/web` stack
  keeps serving the canonical hostname throughout.

The full Cloudflare preview, secret-bootstrap, smoke, and cutover-gate runbook
lives in
[Web Docker Deployment → Cloudflare Preview Path](/build/devops/web-docker-deployment).

## Team Release Checklist

1. Merge the change set with green CI.
2. If Docker behavior changed, make sure `docker-setup-check.yaml` is green.
3. If database migrations changed, confirm the `main`-driven staging path first.
4. Promote to `production` only after preview and staging behavior is understood.
5. Confirm the follow-up Supabase workflow after production deployment.
6. For self-hosted rollout, deploy from the intended commit and prefer `bun serve:web:docker:bg`.

## Rollback Guidance

* Vercel-hosted rollback: for satellite apps, redeploy the previous known-good commit or use Vercel rollback tooling.
* Supabase rollback: use a corrective migration instead of editing applied migration history.
* Self-hosted Docker rollback: checkout the previous known-good commit and rerun `bun serve:web:docker:bg`.

## What Not To Do

* Do not push production schema changes directly from a laptop as the normal path.
* Do not assume staging and production migrations are interchangeable; they are gated differently.
* Do not manually dispatch production Supabase migration from `main`; the only
  valid `main` path is the automatic staging-migration re-evaluation, and the
  production gate still requires the same commit to have both a successful
  production platform deployment and a completed successful `main` staging
  migration.
* Do not use the in-place Docker path when you specifically need rebuild-before-restart semantics.


# GitHub Actions Runbook
Source: https://docs.tuturuuu.com/build/devops/github-actions-runbook

How the repository’s automation is organized, gated, and operated.

GitHub Actions is the primary automation plane for Tuturuuu.

## Workflow Gatekeeping

Every major workflow can be disabled centrally through
`tuturuuu.ts`.

The reusable workflow
`ci-check.yml`
reads that config and emits `should_run`, which downstream jobs use before doing
real work.

For Vercel deployments, the production planner and platform preview perform
affected-app gating before any install, build, or deploy step starts. They check
the current GitHub event's changed files against Vercel app metadata and
workspace dependency closures from `tuturuuu.ts`. Platform preview performs the
check inside its deploy job so protected `main` pushes create one runner, not a
reusable gate runner followed by a deployment runner.

The changed-file resolver must evaluate the full effective change range:

* Manual `workflow_dispatch` runs bypass affected-app gating when the workflow is
  enabled.
* Vercel production push workflows first look for the latest successful GitHub
  Deployment marker for the same workflow and branch, then diff that marker SHA
  to the current `GITHUB_SHA`.
* If no marker is available, push events use the GitHub event payload's complete
  commit file list instead of falling back to only the latest commit.
* Pull request events diff the PR base SHA to the PR head SHA.
* If the resolver cannot prove the full range, it leaves changed-file state
  unavailable so Vercel gating defaults open.

Affected Vercel rules:

* `apps/<app>/**` runs that app's preview or production Vercel workflow.
* `packages/<package>/**` runs every Vercel app whose transitive `workspace:*`
  dependency closure includes that package.
* Storefront UI modules under
  `packages/ui/src/components/ui/storefront/**` are scoped to their verified
  consumers, Inventory and Storefront, instead of rebuilding every app that
  imports another part of `@tuturuuu/ui`.
* `apps/*/package.json` and `packages/*/package.json` are dependency changes for
  their owning workspaces.
* `bun.lock`, root `package.json`, `turbo.json`, `tuturuuu.ts`, and
  `.github/workflows/ci-check.yml` run every Vercel app workflow.
* A Vercel workflow file change, such as
  `.github/workflows/vercel-preview-calendar.yaml`, runs that specific workflow.
* If changed files cannot be computed, the Vercel gate defaults open.

Production pushes run `.github/workflows/vercel-production.yaml` once. That
planner evaluates all targets from their individual deployment markers and
calls only the affected `vercel-production-<app>.yaml` workflows as reusable
jobs. This keeps every automatic deployment attached to the original push SHA
instead of creating `workflow_dispatch` runs. Do not restore per-app `push`
triggers or `check-ci` jobs; doing so recreates the queued preflight fan-out the
planner replaces.

Each reusable production workflow uses a static per-app concurrency prefix plus
the Git ref. Do not derive this key from reusable-workflow caller context: that
can make sibling app jobs share one group, cancel one another, and surface red X
statuses where unselected jobs should be skipped. Enable `cancel-in-progress`
only when the inherited event is a push to `refs/heads/production`; `main`
commits and manual recovery dispatches must not cancel the active deployment.

`bun.lock`-only changes intentionally run all Vercel app deploys because ownership
is ambiguous without a manifest or source path.

## Pull Request Close Cancellation

`cancel-pr-runs-on-close.yaml` runs on the `pull_request_target` `closed` event
and cancels active GitHub Actions runs that still belong to the closed pull
request. It exists to stop queued or long-running checks after a PR is closed
without adding `closed` triggers to every CI workflow.

Because `pull_request_target` runs with base-repository privileges, keep this
workflow narrow:

* Do not checkout or execute pull request head code.
* Checkout only the trusted default branch, with persisted credentials disabled.
* Pin GitHub-owned actions to full commit SHAs.
* Grant only `actions: write` and `contents: read` to the cancellation job.
* Do not pass repository secrets other than the short-lived `GITHUB_TOKEN`.

The cancellation script lists active runs by the closed PR head SHA. It cancels
matching PR workflow runs and same-repository branch push runs for the PR branch,
but never cancels `main` or `production` push runs. Runs in contributor forks are
outside the base repository token's authority and are not cancelled by this
workflow. The same trusted job paginates through Actions cache entries and
deletes only entries whose ref equals the closed pull request's merge ref
(`refs/pull/<number>/merge`). It never deletes default-branch cache entries.

## Main Workflow Groups

### Hosted web build and deployment checks

* `vercel-preview-platform.yaml`
* `vercel-preview-apps.yaml`
* `vercel-preview-calendar.yaml`
* `vercel-preview-chat.yaml`
* `vercel-preview-cms.yaml`
* `vercel-preview-drive.yaml`
* `vercel-preview-finance.yaml`
* `vercel-preview-inventory.yaml`
* `vercel-preview-infrastructure.yaml`
* `vercel-preview-learn.yaml`
* `vercel-preview-mail.yaml`
* `vercel-preview-meet.yaml`
* `vercel-preview-mind.yaml`
* `vercel-preview-nova.yaml`
* `vercel-preview-qr.yaml`
* `vercel-preview-rewise.yaml`
* `vercel-preview-shortener.yaml`
* `vercel-preview-storefront.yaml`
* `vercel-preview-tasks.yaml`
* `vercel-preview-teach.yaml`
* `vercel-preview-track.yaml`
* A matching `vercel-production-*.yaml` workflow exists for each app above

This list drifts as satellite apps are added; treat
`.github/workflows/vercel-preview-*.yaml` and
`.github/workflows/vercel-production-*.yaml` as the authoritative source.

CMS uses the same Vercel deployment pattern as the other satellite apps:

* preview workflow: `vercel-preview-cms.yaml`
* production workflow: `vercel-production-cms.yaml`
* project secret: `VERCEL_CMS_PROJECT_ID`
* environments: `vercel-preview-cms` and `vercel-production-cms`

The Apps gateway uses the same pattern:

* preview workflow: `vercel-preview-apps.yaml`
* production workflow: `vercel-production-apps.yaml`
* project secret: `VERCEL_APPS_PROJECT_ID`
* environments: `vercel-preview-apps` and `vercel-production-apps`

QR uses the same pattern:

* preview workflow: `vercel-preview-qr.yaml`
* production workflow: `vercel-production-qr.yaml`
* project secret: `VERCEL_QR_PROJECT_ID`
* environments: `vercel-preview-qr` and `vercel-production-qr`

Infrastructure uses the same deployment pattern:

* preview workflow: `vercel-preview-infrastructure.yaml`
* production workflow: `vercel-production-infrastructure.yaml`
* project secret: `VERCEL_INFRASTRUCTURE_PROJECT_ID`
* environments: `vercel-preview-infrastructure` and
  `vercel-production-infrastructure`

Mail uses the same deployment pattern:

* preview workflow: `vercel-preview-mail.yaml`
* production workflow: `vercel-production-mail.yaml`
* project secret: `VERCEL_MAIL_PROJECT_ID`
* environments: `vercel-preview-mail` and `vercel-production-mail`

These workflows:

* run with default `contents: read` permissions
* bind deploy jobs to `vercel-preview-<app>` or `vercel-production-<app>`
  GitHub Environments
* run preview workflows only through manual dispatch from `main`, with a
  required `preview_ref` input and an actor present in the
  `TRUSTED_PREVIEW_DEPLOY_ACTORS` repository variable; `vercel-preview-platform.yaml`
  is the exception and also runs on protected `main` pushes so Supabase staging
  migrations keep their same-SHA prerequisite signal
* reject production manual dispatches from non-production branches before
  install/build/deploy work starts
* call production workflows from the production push planner through
  `workflow_call`; retain `workflow_dispatch` only for deliberate operator reruns
* install Bun with `.github/actions/setup-bun-with-retry`, pinned to the root
  `packageManager` Bun version and retried with exponential backoff
* install dependencies through `scripts/ci/run-with-backoff.sh` so transient Bun
  tarball or cache failures retry after cache cleanup
* build selected shared workspace dependencies before Vercel resolves package exports:
  `@tuturuuu/types`, `@tuturuuu/supabase`, and `@tuturuuu/internal-api`
* run `vercel pull`
* run `vercel build`
* deploy prebuilt artifacts for satellite apps and the hosted platform
  production workflow
* treat `vercel-preview-platform.yaml` as platform build validation only;
  self-hosted machines own their own Docker `apps/web` runtime deployment
* cancel superseded production runs through per-workflow, per-branch
  concurrency only for newer `production` pushes, so `main` commits and manual
  recovery dispatches cannot interrupt the active deployment
* record non-blocking GitHub Deployment markers after successful Vercel preview
  builds and production deploys so the next production push can evaluate every
  change since the last successful run

The platform preview workflow can cross-credit a successful same-SHA production
platform build marker. Production does not cross-credit preview markers because
it must build and deploy the prebuilt production artifacts. This only applies to
the platform workflows; satellite Vercel workflows still build and deploy
independently.

### Database automation

* `supabase-staging.yaml`
* `supabase-production.yaml`

These cover staging schema promotion and production schema promotion.

Database workflows that install the Supabase CLI use
`.github/actions/setup-supabase-cli-with-retry` after checkout. The local action
passes `github.token` through to `supabase/setup-cli@v2`, leaves `version` empty
so the repo-pinned Supabase CLI version is used instead of the anonymous
`latest` release lookup, and retries failed setup attempts with bounded
exponential backoff.

### Docker automation

* `docker-setup-check.yaml`
* `rust-backend.yml`

`docker-setup-check.yaml` is the workflow to watch whenever Docker files,
compose files, or Docker helper scripts change. `rust-backend.yml` owns the
`apps/backend` Rust service checks and the migration Cloudflare checks:
formatting, locked dependency fetch, Clippy, tests, Cloudflare Worker target
validation, smoke reporter unit tests, native binary build, Docker image build,
`apps/tanstack-web` type-check/test validation, and the TanStack route-tree
generator/formatter unit test. Keep `scripts/generate-tanstack-route-tree.*`
in this workflow's path filters so route-tree generation changes run before
TanStack/Rust deployment handoff.

### TanStack/Rust Cloudflare deployment

`rust-backend.yml` is also the manually dispatched Cloudflare preview deployment
workflow for the migration pair:

* Rust backend Worker: `apps/backend/wrangler.jsonc`, Worker name
  `tuturuuu-backend`.
* TanStack Start Worker: `apps/tanstack-web/wrangler.jsonc`, Worker name
  `tuturuuu-tanstack-web`.

The workflow stays switchboard-controlled by the `rust-backend.yml` entry in
`tuturuuu.ts`. Pull request and push runs are validation-only and use
`contents: read`; they do not require Cloudflare secrets just to type-check,
test, lint config, build the Rust Worker bundle, or build the backend Docker
image.

Manual dispatch inputs:

* `deploy_target`: `none`, `backend`, `tanstack-web`, or `all`.
* `deployment_mode`: `dry-run` or `deploy`. Keep the default `dry-run` for the
  first run in a new account or environment.

Run `rust-backend.yml` from `main` for Cloudflare deployments. The deployment
preflight requires the dispatch ref to be `refs/heads/main` and `github.actor`
to be listed in the comma-delimited `TRUSTED_CLOUDFLARE_DEPLOY_ACTORS`
repository variable before it loads `CLOUDFLARE_API_TOKEN`. Keep that allowlist
limited to maintainers who can approve secret-backed Worker deployments.
Cloudflare deploy credentials must not be exposed to arbitrary branch code;
review or merge deployment changes before dispatching a secret-backed run.

The deploy jobs are bound to the `cloudflare-workers-preview` GitHub
Environment. Configure these GitHub values there before expecting deployment
jobs to run:

| Name                                      | GitHub storage       | Purpose                                                                                             |
| ----------------------------------------- | -------------------- | --------------------------------------------------------------------------------------------------- |
| `CLOUDFLARE_API_TOKEN`                    | Environment secret   | Cloudflare API token with Workers Scripts edit access for this account.                             |
| `CLOUDFLARE_ACCOUNT_ID`                   | Environment variable | Cloudflare account id used by Wrangler. A same-named secret is accepted only as a fallback.         |
| `BACKEND_WORKER_ORIGIN`                   | Environment variable | Deployed Rust backend Worker origin used by the post-deploy smoke gate.                             |
| `TANSTACK_WEB_WORKER_ORIGIN`              | Environment variable | Deployed TanStack Worker origin used by the post-deploy smoke gate.                                 |
| `CLOUDFLARE_SMOKE_BACKEND_INTERNAL_TOKEN` | Environment secret   | Dedicated smoke token mapped to `BACKEND_INTERNAL_TOKEN` only while running `bun smoke:cloudflare`. |

If either value is missing, the workflow emits a
`Cloudflare deployment skipped` warning, records setup guidance in the job
summary, and skips deploy jobs after CI validation has completed. The warning
names only the missing GitHub Environment keys, not their values. A non-empty
but invalid or under-scoped token normally surfaces as a Worker secret preflight
skip or a Wrangler failure before upload.

Worker runtime secrets live in Cloudflare, not GitHub. After the GitHub
credential preflight passes, a dedicated Worker secret preflight checks the
selected Workers with `wrangler secret list`.
It reads only secret names, never secret values. If Wrangler cannot list names,
or if any required name is
missing, the workflow emits a warning, writes setup commands to the job summary,
and skips the selected deploy job instead of failing later inside a deploy
step. Missing-secret warnings use the `Missing Worker secrets` wording and list
only secret names plus `bun wrangler secret put ...` commands; they never print
or infer secret values.

| Worker                  | Required Cloudflare Worker secrets                                                                                                                                                                    |
| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `tuturuuu-backend`      | `BACKEND_INTERNAL_TOKEN`, `TUTURUUU_APP_COORDINATION_SECRET`, `SUPABASE_URL`, `SUPABASE_SERVICE_ROLE_KEY`, `CRON_SECRET`, `DISCORD_APP_DEPLOYMENT_URL`, `AURORA_EXTERNAL_URL`, `AURORA_EXTERNAL_WSID` |
| `tuturuuu-tanstack-web` | `BACKEND_PUBLIC_ORIGIN`, `BACKEND_INTERNAL_TOKEN`                                                                                                                                                     |

Bootstrap missing Worker secrets from a trusted local shell with Wrangler:

```sh theme={null}
bun wrangler secret put BACKEND_INTERNAL_TOKEN --config apps/backend/wrangler.jsonc
bun wrangler secret put TUTURUUU_APP_COORDINATION_SECRET --config apps/backend/wrangler.jsonc
bun wrangler secret put SUPABASE_URL --config apps/backend/wrangler.jsonc
bun wrangler secret put SUPABASE_SERVICE_ROLE_KEY --config apps/backend/wrangler.jsonc
bun wrangler secret put CRON_SECRET --config apps/backend/wrangler.jsonc
bun wrangler secret put DISCORD_APP_DEPLOYMENT_URL --config apps/backend/wrangler.jsonc
bun wrangler secret put AURORA_EXTERNAL_URL --config apps/backend/wrangler.jsonc
bun wrangler secret put AURORA_EXTERNAL_WSID --config apps/backend/wrangler.jsonc
bun wrangler secret put BACKEND_PUBLIC_ORIGIN --config apps/tanstack-web/wrangler.jsonc
bun wrangler secret put BACKEND_INTERNAL_TOKEN --config apps/tanstack-web/wrangler.jsonc
```

Deploy the backend before the TanStack Worker when `deploy_target` is not `all`.
The TanStack Worker has a `BACKEND` service binding to `tuturuuu-backend`, so a
frontend-only deployment assumes the backend Worker and its secrets already
exist. When `deploy_target=all`, a skipped backend deployment also keeps the
TanStack deployment skipped, even if the TanStack Worker secrets are present.

`deployment_mode=dry-run` compiles and runs Wrangler checks without uploading,
but it still uses the same Cloudflare account, token, Worker name, and secret
name preflights as `deployment_mode=deploy`. Treat a dry-run skip as a setup
gap, not as a deploy failure. `deployment_mode=deploy` uploads the selected
Worker version only after those preflights pass.

When `deploy_target=all` and `deployment_mode=deploy`, the
`post-deploy-smoke` job runs only after both Worker deploy jobs succeed. It
requires `BACKEND_WORKER_ORIGIN`, `TANSTACK_WEB_WORKER_ORIGIN`, and
`CLOUDFLARE_SMOKE_BACKEND_INTERNAL_TOKEN`; missing values fail the full deploy
workflow with a warning, an error, and setup guidance in the step summary
instead of silently skipping runtime verification. The warning title is
`Cloudflare smoke inputs missing`, and the error title is
`Cloudflare smoke verification blocked`. The job runs:

```sh theme={null}
bun smoke:cloudflare --output "$CLOUDFLARE_SMOKE_REPORT_PATH"
```

The JSON report is written under
`tmp/benchmarks/web-migration/<run-id>-<attempt>/cloudflare-smoke.json`,
uploaded as the `cloudflare-smoke-<run-id>-<attempt>` workflow artifact, and
summarized in the GitHub step summary. The report must come from the deployed
backend and TanStack Worker origins; do not point these variables at local
Wrangler or Docker origins in the `cloudflare-workers-preview` Environment.

### Quality and security

* `type-check.yaml`
* `turbo-unit-tests.yaml`
* `biome-check.yaml`
* `codeql.yml`
* `codecov.yaml`
* `i18n-check.yaml`
* `check-migrations.yml`
* `check-migration-timestamps.yml`
* `branch-name-check.yaml`

The test workflows (`turbo-unit-tests.yaml` and `codecov.yaml`) run `bun setup`
through `scripts/ci/run-with-backoff.sh` before executing tests so dependency
installation and workspace package builds match the local setup path while
surviving transient tarball extraction failures. The Codecov coverage test run
also uses the helper with a two-attempt cap so transient runner interruptions
such as exit code `130` retry once without masking deterministic test failures.
Vercel workflows should invoke Turborepo through `bun turbo:local ...` after the
retried `bun install` so CI uses the pinned repo dependency instead of resolving
a global or downloaded Turbo binary. Cacheable builds, type checks, and tests
must be executed through `.github/actions/run-with-turbo-remote-cache`; trusted
jobs pass the dedicated repository `TURBO_TOKEN` and `TURBO_TEAM` variable,
while pull-request and Dependabot jobs leave both inputs empty and use the
task-family local fallback cache.

Vercel deploy credentials must stay environment-scoped. Do not put
`${{ secrets.* }}` values in a Vercel workflow-level `env:` block, and do not
export production Supabase, encryption, or provider secrets from GitHub
Actions. Store app runtime and build-time configuration in the Vercel project
environment. Remote-cache identity is the narrow exception: it is passed only
to the wrapped `vercel build` step and never written to `GITHUB_ENV` or a
workflow/job environment. The regression test
`bun test scripts/ci/release-workflows.test.js` enforces this for every
`vercel-preview-*.yaml` and `vercel-production-*.yaml` workflow.

### Cache and artifact resources

`actions-storage-report.yaml` runs weekly and can be dispatched manually. It
is read-only: it queries the repository's live Actions cache policy and current
cache/artifact inventories, groups cache bytes by key prefix, and summarizes
artifact count, size, age, and largest workflow families. Cache status is
informational at 80% of the configured limit, warning at 90%, and critical at
100%. The report does not assume a fixed artifact byte entitlement and does not
require an organization billing token.

The July 10, 2026 audit found a 10 GB cache maximum and 7-day retention. Target
steady-state usage below 9 GB so GitHub does not continuously evict and recreate
high-reuse entries. Prefer Bun downloads, package-manager data, task-family
Turbo state, native dependencies, shared Rust state, and service-scoped
BuildKit layers over final application binaries. Leave managed uv and CodeQL
caching to their official actions.

All `upload-artifact` steps must set `retention-days` and
`if-no-files-found`. Optional failure diagnostics may warn; release and deploy
handoffs must fail when absent. E2E diagnostics are failure-only and retained 7
days, package tarballs are retained 1 day, development mobile deliverables 7
days, and production store deliverables 14 days.

Preview deploy credentials must not be exposed to arbitrary branch push code.
Most preview Vercel workflows are manual-only: run the workflow from `main`,
provide the branch, tag, or SHA in `preview_ref`, and keep
`TRUSTED_PREVIEW_DEPLOY_ACTORS` limited to maintainers who can approve
secret-backed preview builds. The workflow still checks out and builds the
requested `preview_ref`, so reviewers should treat that ref as code that can
execute during install/build.

Automatic CodeQL uses GitHub's organization-managed
`dynamic/github-code-scanning/codeql` workflow for JavaScript/TypeScript and
Python. `codeql.yml` is a manual-only fallback so the repository retains an
explicit workflow file without duplicating managed push or pull-request scans.
Do not add automatic or cron triggers to the fallback; `bun git-sync` mirrors
the already-scanned `main` commit to `production`.

`e2e-tests.yaml` uses native push paths for E2E specs, Playwright and Docker
configuration, database fixtures, dependency manifests, lockfiles, and its own
runner scripts. Normal application source-only commits do not create the image
bundle and six downstream consumers. E2E has no cron trigger: automatic runs
are limited to matching commits, and maintainers can still use manual dispatch
for an intentional full run.

Supabase migration workflows still consume the required platform workflow-run
signals, but compare the target SHA with the last successful migration marker.
Only database and migration-control changes proceed to Supabase CLI setup and
`db push`; an unavailable marker fails open. Staging and production each use a
single serialized evaluate-and-migrate job, and production preserves the
same-SHA platform deployment plus staging-success prerequisites.

Cloudflare Worker manual deployments follow the same trust boundary: run
`rust-backend.yml` from `main`, keep `TRUSTED_CLOUDFLARE_DEPLOY_ACTORS` limited
to trusted maintainers, and avoid exposing `CLOUDFLARE_API_TOKEN` to unreviewed
branch code. The workflow checks the protected dispatch ref and actor allowlist
before loading Cloudflare credentials or running Worker deploy steps.

`vercel-preview-platform.yaml` also runs on protected `main` pushes. Keep that
exception narrow: `supabase-staging.yaml` is triggered by the platform preview
build workflow and production migration requires a successful `main` staging
migration for the same SHA before it can run `supabase db push --include-all`.

### Other delivery surfaces

* `discord-modal-deploy.yml`
* `mobile-build-android.yaml`
* `mobile-build-ios.yaml`
* `mobile-build-macos.yaml`
* `mobile-build-windows.yaml`
* `mobile-deploy-stores.yaml`
* `release-*.yaml` package publishing workflows

## Operational Rules

### Manual dispatch

Use `workflow_dispatch` when:

* you need to rerun a deployment intentionally
* you need to promote a migration outside the normal trigger timing
* you need to recover from a failed but otherwise understood automation path

Manual dispatch bypasses affected-app gating. Generic switchboard-controlled
workflows still honor disabled `ci` entries, while trusted manual satellite
preview workflows launch their guarded deploy job directly and do not keep an
unused `tuturuuu.ts` toggle.

For preview Vercel deployments, dispatch the workflow from `main`, set
`preview_ref` to the branch, tag, or SHA to deploy, and confirm the actor is in
`TRUSTED_PREVIEW_DEPLOY_ACTORS`. Do not reintroduce preview `push` triggers for
secret-backed Vercel workflows, and do not add a standalone `check-ci` job to a
manual-only preview: the dispatch already selected the build and the extra job
only consumes another runner. Preview concurrency uses the workflow plus
`preview_ref`, so rerunning the same target cancels stale work without canceling
a different preview target.

Package release workflows that expose production secrets or trusted publishing
authority must add their own ref guard before dependency installation or publish
jobs. Release Please is the only workflow that generates monorepo version and
changelog PRs. It runs from `production`, uses
`secrets.RELEASE_PLEASE_TOKEN` so generated PRs and releases can trigger
downstream workflows, and falls back to `github.token` only to keep the job from
failing when the bot token is not provisioned. The `github.token` fallback does
not trigger downstream workflow runs from generated release PRs. Release Please
rejects non-production manual dispatches before the write-capable release job.
Package publish workflows consume release-please version bumps on `production`;
they must not recreate checksum or PR-title version bump automation. Package
release workflows use npm trusted publishing: build and artifact-pack work runs
before any OIDC permission is granted, then the `publish-npm` job downloads one
tarball, verifies its package name and version, and runs `npm publish` without
`NPM_TOKEN`. Each publish job is bound to its package release environment, and
the matching npm trusted publisher must use this repository, the workflow
filename, and that environment. Manual dispatch is only valid with the branch
selector set to `production`; non-production refs are rejected before the package
or publish jobs can start. Every workflow-published package manifest must also
declare `repository.type: "git"`,
`repository.url: "https://github.com/tutur3u/platform"`, and
`repository.directory` matching the package path. npm validates those fields
against GitHub Actions provenance and rejects publishes with `E422` when the
packed manifest has an empty or mismatched repository URL. The tarball handoff
uses required-file behavior, one-day retention, and compression level 0 because
`.tgz` is already compressed. Preparation runs any package lifecycle build
through root Turbo first, then calls `npm pack --ignore-scripts` so `prepack`
cannot bypass the shared cache wrapper.

Release Please can move an oversized generated pull request body into
`release-notes.md` on a companion
`release-please--branches--<branch>--release-notes` branch. The workflow runs
`node scripts/ci/release-please-overflow-recovery.js --target-branch production`
before `googleapis/release-please-action@v5`; when a merged pending release PR
still points at a missing overflow file, the script recreates the branch and
file from the merged manifest bump and current `production` changelogs, then the
normal Release Please action can create the releases. If the script reports
`skipped`, inspect the pending labels and merged release PR body before retrying.

The same workflow then runs
`node scripts/ci/release-please-auto-approve.js --target-branch production`,
which approves the generated release PR while it is still nothing but generated
output. The `Protected branches` ruleset requires an approving review, so an
untouched release PR otherwise sits at `REVIEW_REQUIRED` indefinitely. Every one
of these must hold or the script skips and leaves the PR for a human: the head
branch is a `release-please--branches--` branch against the target branch, the
PR was opened by a release automation identity, every commit is a
`chore(release): release ...` commit by that same account, and every changed
file is one release-please itself rewrites. That last allowlist is **derived
from `release-please-config.json`** — each package's changelog, its version file
for its release type, and its `extra-files` — so adding a package or changing
its release type cannot silently widen what auto-approval accepts.

Nothing needs to un-approve: the ruleset sets `dismiss_stale_reviews_on_push`,
so any later push to the release branch drops the approval, including one this
workflow never observes. The step deliberately uses `github.token` rather than
`RELEASE_PLEASE_TOKEN`, because GitHub refuses a review from the account that
opened the pull request — release-please and the approval have to be different
identities. While `RELEASE_PLEASE_TOKEN` is unset both are `github-actions[bot]`,
and the script reports `blocked` and leaves the run green rather than failing.
Use `--dry-run` to see the decision without posting a review.

`release-please-auto-merge.yaml` closes the loop on the generated release PR. It
runs every third day at 06:00 UTC (`cron: "0 6 */3 * *"`) and on manual dispatch,
and it does not reimplement the merge in YAML: it runs `bun git-release-please`
and then `bun git-sync`, the same two commands the release flow uses locally, so
the scheduled path and the manual path cannot drift. Those scripts own the merge
rules — platform version sync, conflict detection, `bun check`, and
fast-forward safety — and are covered by `scripts/git-release-please.test.js`
and `scripts/git-sync.test.js`.

The workflow resolves what to do before it installs anything. It prefers
`origin/release-please--branches--production`, ignores the companion
`--release-notes` overflow branch, and skips the merge entirely when the release
branch is already an ancestor of `origin/main` — so a run with nothing to merge
is a clean no-op rather than a red run. It separately checks whether
`origin/production` has drifted from `origin/main` and syncs even when there was
no merge, which is what makes the schedule self-healing. Every run that pushes
ends by asserting the two refs resolve to the same commit and fails loudly if
they do not.

Day-of-month cron stepping restarts each month, so the 31st and the 1st can land
a day apart. That is harmless here precisely because an empty run does nothing.

The job checks out `main` with `fetch-depth: 0` and
`secrets.RELEASE_PLEASE_TOKEN`, falling back to `github.token`. The fallback
cannot complete a release: the `Protected branches` ruleset covers `main` and
`production` and its only bypass actor is `OrganizationAdmin`, so a run on
`github.token` merges cleanly and then dies on
`GH013: Changes must be made through a pull request`. `RELEASE_PLEASE_TOKEN`
must therefore hold a personal access token (`repo` + `workflow` scopes) owned
by an organization admin. Granting the Actions app a ruleset bypass is **not**
an alternative: pushes made with `GITHUB_TOKEN` do not trigger `push`
workflows, so the `production` push would silently skip
`Vercel Production Deployment Planner` and the next `Release Please` run and
stall the release chain. A run that would need to push checks for the secret up
front and fails with an actionable error, rather than discovering it after
`bun check`.

The job also installs Flutter (`3.44.x`, the same pin as `mobile.yaml`) and runs
`flutter pub get` in `apps/mobile` before the merge. Release Please bumps
`apps/mobile/pubspec.yaml` on every release, so `touchesMobile()` in
`scripts/git-release-please.js` is always true and `bun check` is always
followed by `bun check:mobile`; without a toolchain `dart-format`,
`flutter-analyze` and `flutter-test` all exit `127`.

Top-level `permissions` is `{}` and
`contents: write` is granted on the job alone, and `concurrency` is grouped with
`cancel-in-progress: false` because cancelling a half-finished release merge
would leave `main` and `production` split. Use the `dry_run` dispatch input to
exercise the merge and run `bun git-sync --no-push` without publishing anything.

Keep internal Tuturuuu dependencies as `workspace:*` in source package
manifests so local builds always use the checked-out workspace. Package release
workflows must first run
`node scripts/ci/package-release-readiness.js gate-package-release packages/<name>`
in a short pre-build gate. The gate checks the package version and publishable
Tuturuuu workspace dependencies once, dispatches missing dependency workflows,
and exits green without build, pack, or publish work while dependencies are
pending. If a dependency workflow for the same production SHA already failed,
completed successfully without npm visibility, or cannot be inspected, the gate
fails immediately. When the gate outputs `should_publish == true` and
`dependencies_ready == true`, the workflow can build and rewrite the checked-out
manifest immediately before `npm pack` with
`node scripts/ci/prepare-npm-package-manifest.js packages/<name>`. That
temporary rewrite replaces `workspace:` protocol ranges with the current
workspace package versions so npm consumers can install the tarball. It must
preserve package-included `file:` tarball dependencies, such as `@tuturuuu/ui`'s
vendored SheetJS tarball, instead of rewriting them to mutable external tarball
URLs. After
`npm publish`, the publish job polls `npm view` for the exact published version
before it reports success, then a separate non-OIDC job dispatches direct
dependent package workflows without checking out the repo or carrying publish
authority. The internal
`node scripts/ci/package-release-readiness.js dispatch-dependent-workflows packages/<name>`
command is available for direct/manual dispatches that can read the checkout.
If npm returns first-publish or permission errors, fix the npm package access and
trusted publisher setup instead of skipping the package. If a published package
depends on another release-please-managed Tuturuuu package, that dependency also
needs its own
`release-*-package.yaml` workflow and matching `tuturuuu.ts` entry.

The platform production Vercel workflow also runs
`node scripts/ci/package-release-readiness.js gate-changed-package-versions`
before installing dependencies. Release-please package bumps therefore publish
and become visible on npm before the normal production platform deployment
continues. The helper intentionally checks only the checked-out latest commit,
not the whole push event payload, so package changes from earlier commits in a
multi-commit push are not bound to an unrelated newer SHA. If the latest commit
does change package manifests, the deploy job grants `actions: write` because
the helper may dispatch missing package release workflows for that same
production SHA. When related package releases are queued or running, the helper
sets `packages_ready=false`; the platform build skips successfully instead of
polling npm until the runner times out. npm publish authority remains isolated to
package `publish-npm` jobs. A skipped package gate must not count as production
deployment for database migrations. Database paths therefore select the
platform deployment in the production planner, and `supabase-production.yaml`
requires both the successful planner run and the `vercel-production-platform`
deployment marker for the same SHA before it can run production migrations.
The gate queries the planner run because reusable app workflows do not create
standalone Actions runs.

Filtered production Docker installs only include the selected app and the
dependencies that app needs. Workspace packages with direct `tsc` build scripts
must declare `typescript` in their own `devDependencies`; do not
rely on the root devDependency for production Docker builds. Programmatic
compiler API consumers must stay on the active TypeScript 7 toolchain instead
of carrying legacy compiler compatibility packages.

Next.js production apps also declare `@typescript/native-preview` in their own
`devDependencies` while the repo uses the TypeScript 7 native compiler package.
The TS7 `typescript` package does not ship the legacy
`typescript/lib/typescript.js` API file that Next checks during build-time
TypeScript setup; the native-preview marker makes Next use its supported TS7
native compiler path instead of trying to auto-install classic TypeScript.

### Superseded-run guards

Production Vercel workflows use a static per-app concurrency prefix and Git ref
with a `cancel-in-progress` predicate restricted to push events on
`refs/heads/production`. A newer production push cancels only the older run for
that same app instead of cancelling sibling app deployments or allowing an
obsolete run to finish green. A `main` commit or manual recovery dispatch does
not cancel the running production deploy. The newest production run stays queued
or active and deploys the cumulative branch state.

Deployment markers still let affected-app gating compare every change since
the last successful deployment, including changes accumulated across canceled
intermediate runs. If the marker is missing or cannot be trusted, Vercel gating
defaults open so a later unrelated commit cannot hide an earlier app change.

### Prerequisite guards

* `supabase-staging.yaml` requires a successful `main` platform preview build
  trigger unless manually dispatched.
* Its deploy step links the staging project and runs
  `supabase db push --include-all`.
* `supabase-production.yaml` runs after the production deployment planner and
  also re-evaluates after a matching `main` staging migration succeeds. It still
  checks the latest planner result, a successful production platform deployment
  marker, and a completed successful staging migration for the same commit
  before running
  `supabase db push --include-all`.

### Mobile iOS native assets

Mobile workflows cache the Flutter SDK/pub downloads through the Flutter setup
action. Android workflows also use the toolchain-aware Gradle cache, and iOS or
macOS workflows cache CocoaPods downloads plus the trunk repository. They do
not cache `apps/mobile/build`, final APK/AAB/IPA/app bundles, `Pods`, or
`apps/mobile/.dart_tool`. Flutter native asset hook outputs can become stale
across simulator/device builds and SDK updates; a stale `.dart_tool` cache can
leave `NativeAssetsManifest.json` referencing `objective_c` while
`build/native_assets/ios/` is missing the generated framework.

Every workflow still runs `flutter pub get` and its platform build on every run.
Development deliverables are retained for 7 days and production store
deliverables for 14 days. Archive directory-based app bundles before upload,
disable redundant artifact compression for already-compressed archives and
mobile packages, and fail if a required deliverable is missing.

The workflow explicitly runs `flutter config --no-enable-swift-package-manager`
after Flutter setup. Keep the iOS CI path on CocoaPods while `image_cropper` and
`dkimagepickercontroller` resolve incompatible `TOCropViewController` Swift
package ranges; otherwise Flutter 3.44+ can fail before the simulator build
with an Xcode package dependency resolution error.

The iOS/macOS build workflows currently resolve `macos-latest` to GitHub's
macOS 26 ARM64 image with Xcode 26+. The former Xcode 16.4 compatibility pins
for `connectivity_plus` and `device_info_plus` are no longer required. Before
adding a future Apple-specific dependency pin, verify the active runner image
from a build log and reproduce the native build failure on that toolchain.

### Mobile store beta deployment

`mobile-deploy-stores.yaml` runs automatically on `production` pushes that touch
`apps/mobile/**`, `scripts/mobile-deployment/**`, the workflow file,
`ci-check.yml`, or `tuturuuu.ts`. It is a beta-store workflow only:

* Android builds the production flavor AAB from `apps/mobile/.env.github` and
  publishes it to the Google Play `internal` track.
* iOS builds the production flavor IPA from `apps/mobile/.env.github` and
  uploads it to TestFlight.
* CI requests a signed GitHub OIDC token for the
  `tuturuuu-mobile-deployment` audience, then fetches an Android or iOS bundle
  from `https://tuturuuu.com/api/v1/mobile-deployment/bundle` with the issued
  `MOBILE_DEPLOYMENT_CI_TOKEN`.
* If `MOBILE_DEPLOYMENT_CI_TOKEN` is not configured in the `mobile-store-beta`
  GitHub Environment yet, the credentials preflight emits a notice and skips the
  Android and iOS publish jobs instead of failing the workflow. A non-empty but
  invalid token still fails during the bundle fetch.
* The apps/web mobile deployment vault verifies the CI token, GitHub OIDC
  issuer, audience, repository, `production` ref, workflow file, and
  `mobile-store-beta` environment before returning any plaintext.
* CI hydrates ignored Firebase, signing, store, and `.env.github` files into
  fixed paths under `apps/mobile` and `$RUNNER_TEMP` with `umask 077`, validates
  plaintext SHA-256 hashes, masks secret values, and deletes generated files in
  `always()` cleanup steps.
* The workflow rejects any Google Play track other than `internal`, uploads only
  the AAB/IPA build artifacts, and uses TestFlight-only iOS upload.
* Release Please owns mobile version and build-number bumps. Duplicate store
  build numbers should fail in CI instead of being bumped by this workflow.

The workflow is bound to the `mobile-store-beta` GitHub Environment. Keep that
environment restricted to the `production` branch and store only
`MOBILE_DEPLOYMENT_CI_TOKEN` there. Mobile signing, Firebase, store API, and
build-time secrets live in the root workspace mobile deployment vault at
`/internal/mobile-deployment` on the infra app and require
`manage_mobile_deployment_vault`. Manage non-file values in the vault's
**Secrets** panel, then use the vault's Verify action before activating the draft. Legacy
base64 file payload env keys are intentionally blocked; Firebase, signing, and
store credential payloads must be uploaded as file resources.

Local release-build verification should run before relying on the workflow:

```sh theme={null}
bun test scripts/ci/check-workflow-config.test.js
ruby -e "require 'yaml'; YAML.load_file('.github/workflows/mobile-deploy-stores.yaml')"
git diff --check
bun check:mobile
(cd apps/mobile && flutter pub get)
(cd apps/mobile && flutter build appbundle --release --flavor production --target lib/main_production.dart --dart-define-from-file=.env.github)
```

iOS IPA verification requires full Xcode, not only Command Line Tools:

```sh theme={null}
xcodebuild -version
(cd apps/mobile && flutter config --no-enable-swift-package-manager)
(cd apps/mobile && flutter build ipa --release --flavor production --target lib/main_production.dart --dart-define-from-file=.env.github)
```

If `xcodebuild -version` reports that Command Line Tools are selected, switch to
full Xcode before claiming the iOS archive has been verified locally.

## Fast Triage Checklist

1. Check whether `ci-check.yml` disabled the workflow through `tuturuuu.ts`.
2. For Vercel workflows, inspect the `ci-check.yml` decision reason and matched paths.
3. Inspect the changed-file source, base SHA, head SHA, and path count emitted by
   `resolve-changed-files.ts`.
4. Check whether the workflow was canceled because a newer run superseded it,
   then follow the newest run in the same workflow-and-branch concurrency group.
5. Check whether the prior successful GitHub Deployment marker exists for that
   Vercel workflow and branch.
6. Check path filters to confirm GitHub should have started the lightweight workflow.
7. For database workflows, inspect the prerequisite evaluation job before the deploy job.
8. For Docker changes, verify `docker-setup-check.yaml` specifically.

## When You Add New Automation

1. Add the workflow file under `.github/workflows/`.
2. Add its key to `tuturuuu.ts` unless you intentionally want it always on by default.
3. Document the workflow in `apps/docs`.
4. If it changes a docs-visible page, add that page to `apps/docs/docs.json`.


# Hive Realtime Runbook
Source: https://docs.tuturuuu.com/build/devops/hive-realtime-runbook

Operating notes for the Hive WebSocket service and satellite app deployment.

Hive realtime lives in `apps/hive-realtime`. It is a Bun WebSocket service used
only by Hive; do not replace it with Supabase Realtime. The shared protocol and
Yjs helpers live in `@tuturuuu/realtime/hive` so `apps/hive`,
`apps/hive-realtime`, and `apps/web` use the same message schemas.

## Required Environment

* `HIVE_REALTIME_TOKEN_SECRET`: preferred shared HMAC secret used by `apps/web`
  to mint short-lived join tokens and by `apps/hive-realtime` to validate them.
  If this is not set, both services fall back to the existing platform
  Supabase service secret from the shared `apps/web` environment. This keeps
  Hive deployable with the same Supabase setup as `apps/web`, while still
  allowing operators to rotate Hive realtime signing independently later.
* `HIVE_REALTIME_URL`: internal server URL used by `apps/web` and `apps/hive`
  when they need the service-side endpoint.
* `NEXT_PUBLIC_HIVE_REALTIME_URL`: browser-facing WebSocket URL, normally
  `wss://hive.tuturuuu.com/realtime` in production.
* `HIVE_DATABASE_URL`: Postgres URL for the dedicated Hive product database.
  Realtime uses this database to load compacted CRDT snapshots, append Yjs
  update bytes, and persist audit events. Supabase is not the Hive product store
  after backfill.
* `INTERNAL_WEB_API_ORIGIN`: Docker-internal web gateway origin used by
  `apps/hive` API rewrites. In production Compose this should resolve to
  `http://web-proxy:7803` so editor saves do not leave the Docker network and
  re-enter through the public web origin.
* Supabase credentials already used by `apps/web`, especially
  `NEXT_PUBLIC_SUPABASE_URL` with `SUPABASE_SECRET_KEY`. `SUPABASE_SERVER_URL`
  may still override the server-side URL when the deployment needs a
  Docker-internal Supabase origin. These credentials are identity/session
  infrastructure only for Hive realtime token validation and web auth.

`apps/hive` shares the same Supabase setup as `apps/web`. Docker runtime env
comes from `.env.local` with the same `apps/web/.env.local` fallback, and the
production Hive image receives the `web_env` BuildKit secret during `next build`
so prerendered auth routes can resolve `NEXT_PUBLIC_SUPABASE_URL` and related
platform Supabase variables.

When Hive is exposed as `https://hive.tuturuuu.com` through a Cloudflare tunnel
to `http://localhost:7814`, keep browser-facing realtime URLs secure. Use
`NEXT_PUBLIC_HIVE_REALTIME_URL=wss://hive.tuturuuu.com/realtime` or leave it
unset so the client falls back to the same-origin `/realtime` route. Keep
Docker-internal or host-local forwarding in `HIVE_REALTIME_HTTP_URL` or
`HIVE_REALTIME_URL`; do not expose `ws://...` as the browser URL for an HTTPS
page.

## Local production-style servers (Turbo)

From the repo root, Turbo runs workspace dependency builds first, then starts
each process (see `turbo.json` tasks `@tuturuuu/hive#serve:hive` and
`@tuturuuu/hive-realtime#serve:hive-realtime`):

* `bun serve:hive` — production Next server for Hive on port `7814` (requires a
  prior `next build` output; Turbo schedules `build` before `serve:hive`).
* `bun serve:hive-realtime` — Bun WebSocket server (default port `7815` via
  `PORT`).

## Blue/Green Deployment

`docker-compose.web.prod.yml` runs `hive-blue`, `hive-green`, and
`hive-realtime` with the same production Supabase environment as `apps/web`.
`scripts/docker-web/blue-green.js` promotes Hive with the same active color as
web and waits for the target Hive color before proxy handoff.

The generated nginx config routes:

* `hive.tuturuuu.com/` to the active `hive-{color}` satellite app on port
  `7814`.
* `hive.tuturuuu.com/realtime` to `hive-realtime` on port `7815`.

The production proxy also listens on host port `7814`, so a Cloudflare tunnel
mapping `hive.tuturuuu.com` to `localhost:7814` still goes through the
blue/green proxy instead of bypassing it to a stale single Hive container.

`scripts/watch-blue-green-deploy.js` watches the Hive Dockerfiles, package
manifests, realtime source files, and `docker-compose.web.prod.yml`; changes to
these files trigger the watcher container refresh path.

## Protocol

Clients connect with a short-lived token from
`POST /api/v1/hive/servers/:serverId/realtime-token`. Tokens include user ID,
server ID, role, expiry, and event scopes.

Accepted client messages are CRDT sync, awareness, compatibility, and health
messages:

* `sync.hello`
* `sync.update`
* `sync.diff`
* `sync.compacted`
* `awareness.update`
* `presence`
* `server.status`
* `error`
* `world.event`
* `world.event.applied`

The durable shared world is a Yjs document per server. Clients send encoded Yjs
deltas as base64 in `sync.update`, and the realtime service appends those bytes
to `hive_crdt_updates`. State-vector sync lets a reconnecting client request
only missing updates, while periodic compaction stores merged snapshots in
`hive_world_states.crdt_snapshot`.

`revision` is a compatibility display value backed by `op_seq`; it is not a
write precondition for commutative CRDT world edits. Money, item ownership,
warehouses, trades, LLM spend, and bankruptcy still go through the `apps/web`
Hive APIs and Hive Postgres transactions. Realtime broadcasts only the committed
visual projections for those authoritative writes.

`world.event` and `world.event.applied` remain as temporary compatibility
wrappers for older full-world edit flows. The service converts accepted payloads
into CRDT updates before broadcasting them to the room.

Do not store full `world_data` snapshots in `hive_world_events` for compatibility
events. The current world snapshot belongs in `hive_world_states`; event rows
should keep compact metadata and payloads so high-frequency editor saves do not
double the amount of JSON written per operation.

Awareness is ephemeral and TTL-based. It includes user ID, display name, avatar
URL, role, color, active tool, selected entity, terrain cursor, camera position,
world avatar position, viewport focus, and `lastSeenAt`. Do not persist
awareness state into `hive_world_states`, `hive_crdt_updates`, or audit events.

Operationally, the client should expect token refresh on reconnect,
exponential backoff, heartbeat/TTL presence cleanup, actor echo suppression,
offline edit queue replay, cursor/position throttling, and slow-client
backpressure handling.


# Internal Log Drain and Observability
Source: https://docs.tuturuuu.com/build/devops/log-drain-observability

Operate the Postgres-backed log drain that powers web runtime logs, requests, deployments, analytics, cron, and observability views.

## Overview

`apps/web` stores request, cron, deployment, and runtime-monitoring events in the internal log drain where those wrappers are still wired. Application runtime logging uses the native console method that matches severity (`console.error`, `console.warn`, `console.info`, `console.log`, or `console.debug`); the drain preserves normal stdout/stderr output for deployment and monitoring views instead of requiring a custom app logger.

The monitoring navigation uses compact labels:

* Overview
* Deployments
* Logs
* Analytics
* Observability
* Cron
* Requests
* Resources
* Projects
* Stress Tests

## Runtime

Docker web runs a dedicated `log-drain-postgres` service. It is separate from Supabase and is owned by the Docker web runtime. Compose pins the visible container name to `${COMPOSE_PROJECT_NAME:-tuturuuu}-log-drain-postgres-1` so it stays grouped with the rest of the Tuturuuu stack in Docker Desktop.

Default connection inside Docker:

```txt theme={null}
postgres://platform_log_drain:platform_log_drain@log-drain-postgres:5432/platform_log_drain
```

Relevant environment variables:

* `PLATFORM_LOG_DRAIN_DATABASE_URL`: Postgres connection string.
* `PLATFORM_LOG_DRAIN_ENABLED`: set to `false` to disable persistence while preserving stdout/stderr.
* `PLATFORM_LOG_DRAIN_RAW_RETENTION_DAYS`: raw log retention, default `30`.
* `PLATFORM_LOG_DRAIN_SUMMARY_RETENTION_DAYS`: request, cron, deployment, and usage retention, default `90`.

## Logging Rules

Server runtime code should use the native console method that matches diagnostic severity:

```ts theme={null}
console.info('Processed job', { jobId });
console.error('Job failed', error);
```

Do not add `serverLogger` runtime imports or automatic console log-drain
installation. Prefer a single console call with a short message and a structured
metadata object so Docker, Vercel, and any retained drain views can keep the
event readable.

For route or cron handlers, wrap execution with `withRequestLogDrain(...)` or `withCronLogDrain(...)` when the handler should attach logs to a request or cron run id.

The drain is fail-open: if Postgres is unavailable, requests and cron jobs continue normally and logs still go to stdout/stderr.

## Legacy Compatibility

The monitoring UI reads both the Postgres drain and the pre-drain blue/green
files under `tmp/docker-web`. Before the Postgres log drain existed, the
blue/green watcher captured proxy traffic, watcher logs, and request console
lines as plain files. The Requests and Logs tabs still merge those legacy files
in, and Deployments are enriched from the watcher snapshot so commit subject,
full hash, short hash, stamp, active color, and runtime lane remain visible even
before the Postgres drain has a complete history.

Legacy Docker console capture coalesces timestamped continuation lines from the
same container write before persisting request console logs. This keeps object
dumps from old route console output attached to one function/request row instead
of turning every serialized property into a separate log row.

Request-archive console lenses store and return redacted summaries only. Both the
watcher ingestion path and the web-side archive normalization redact common
bearer tokens, JWTs, sensitive key/value fields, sensitive query parameters, and
email addresses, then cap each attached console message at 500 characters. Raw
app-container console payloads are never persisted in `blue-green-request-logs`.

## Projects

Infrastructure → Monitoring → Projects is the log-drain-owned project registry for Docker web deployments. The built-in project is seeded as:

* `id`: `platform`
* repository: `https://github.com/tutur3u/platform`
* default selected branch: `production`
* app root: `apps/web`
* environment: `production`
* addons: nginx proxy locked on, log drain on, Redis on, cron on

Project definitions live in the log-drain Postgres tables `infrastructure_projects` and `infrastructure_project_branches`, not Supabase. Existing log, request, deployment, cron, and resource records default to `project_id = 'platform'` so the current monitoring views keep showing the deployed platform while new projects are introduced.

V1 GitHub import supports public GitHub repositories only. The UI syncs repository metadata and branches through unauthenticated GitHub REST calls by default; set `GITHUB_TOKEN` only when the deployment host needs a higher GitHub API rate limit. New projects use the Next.js preset, default app root to the repository root, require hostname routing through the central nginx proxy, and start with log drain plus Redis enabled. Cron is disabled by default for imported projects until an operator enables it.

Imported projects can be deleted from the Projects tab. Deletion removes the log-drain project registry entry and its branch cache, but it does not purge retained request, log, deployment, cron, or resource records. The built-in `platform` project is locked and cannot be deleted from the UI or API.

Changing the selected branch queues the project for deployment. For the built-in `platform` project, the blue/green watcher reads the selected branch from the project registry. If the selected branch differs from the current checkout and the worktree is clean, the watcher fetches and checks out that branch before continuing. If the worktree is dirty, the project is marked blocked in watcher status instead of crashing or forcing a checkout. Manual deploy actions also write `deployment_status = 'queued'`; the watcher must consume that queued status whether Git is already up to date or the watcher first fast-forwards to a newer commit, then advance it through `building`, `deploying`, and `ready` or `failed`. Successful platform deploys must update the project row's latest commit fields at the same time as deployment history so the Projects tab cannot remain queued with an older commit after the runtime has advanced.

The project list also reconciles stale queued state for the built-in project from the blue/green runtime snapshot. If the active or latest successful deployment matches the queued commit, or was completed after the queue timestamp, the API clears `queued`, marks the project `ready`, and refreshes the latest commit fields from deployment history.

For imported projects, the same watcher polls enabled projects from the registry, keeps managed source checkouts under `tmp/docker-web/projects/<projectId>/repo`, and writes generated Next.js compose/runtime files under `tmp/docker-web/projects/<projectId>/runtime`. These services run with the shared `tuturuuu` Compose project name, attach to the central Docker network, and receive `PLATFORM_PROJECT_ID`, selected branch, log-drain, Redis, `PORT`, and `HOSTNAME=0.0.0.0` environment wiring. Hostname routes are merged into the central nginx proxy config so nginx remains the mandatory entrypoint. Managed project hostnames must be plain DNS names; the API rejects ports, wildcards, whitespace, nginx syntax, and reserved Tuturuuu platform hostnames, and the watcher defensively drops unsafe persisted values before rendering nginx.

The Logs tab serves grouped rows. Events with the same request id collapse into
one expandable row; legacy standalone logs fall back to route, source,
deployment, and minute bucket grouping. Operators can filter by route, status
family, source, level, request id, and deployment stamp, then expand a row to
see the child event timeline, metadata, error stack, client context, and
deployment context.

Legacy Docker console capture coalesces timestamped continuation lines from the
same container write before persisting request console logs. This keeps object
dumps from old route console output attached to one function/request row instead
of turning every serialized property into a separate log row.

Deployment rows keep historical failed attempts searchable, but failed and
successful attempts for the same commit are not merged into one current failed
state. The global deployment failure banner and current blocked-target summary
come only from the latest active deployment row; older failures remain visible
inside deployment history rows and filters.

The Requests tab intentionally freezes its result window when opened. New traffic is counted in the background and offered as an explicit "show new" action, while older pages are appended automatically as the operator scrolls. This prevents live traffic from shifting the visible rows during investigation. The frozen `since` and `until` cursor bounds must be applied by the Postgres log-drain query or legacy archive reader before any `ORDER BY ... LIMIT`, archive page size, or aggregate row cap so request floods after the freeze cannot evict older rows still inside the operator's investigation window.

Monitoring links preserve the selected `project` query parameter so Overview, Deployments, Logs, Analytics, Observability, Cron, Requests, and Resources stay scoped to the same project while an operator moves between tabs. The project scope card on each tab is the visible source of truth for the active project, branch, hostnames, commit, and addons.

Queued deployment rows only advance while the blue/green deployment watcher is live and connected to log-drain Postgres. If the Projects tab sees a queued project while the watcher is missing, offline, stale, or locked to a different branch than the built-in project, the UI queues a `blue-green-watcher-recovery.request.json` control request. The Docker cron runner reads that request from the shared control directory, clears stale watcher lock/status files, and recreates the `web-blue-green-watcher` service through Docker Compose so recovery does not depend on the stuck watcher process. The production watcher service must receive `PLATFORM_LOG_DRAIN_DATABASE_URL`, `DOCKER_WEB_FRONTEND`, optional `GITHUB_TOKEN`, and any addon env such as Redis from Compose so queued recovery recreates the same frontend family that production is serving.

Each drained request stores the client IP address and user agent when those headers are available. Console logs emitted inside an already-wrapped request or cron AsyncLocalStorage context can be scoped back to the same request id, so Requests can show related console lines next to the originating request without relying on terminal access.

## Cron Control

Infrastructure → Monitoring → Cron exposes the native Docker cron runner state, a global enable/disable switch, per-job enable/disable switches, manual run buttons, retained execution rows, and captured response/console output. Runtime overrides are stored in `tmp/docker-web/watch/control/cron-control.json`; they do not edit `apps/web/cron.config.json`, so Vercel cron config remains source-controlled while local Docker operations can pause individual jobs safely.

Cron snapshot and execution history reads are available to infrastructure
viewers, but cron mutations are operator-only. Manual run requests and global or
per-job runtime enablement changes must go through routes guarded by
`authorizeInfrastructureOperator` so roles with only `view_infrastructure`
cannot change scheduler behavior.

Cron log-drain wrappers must not persist unauthorized attempts. Keep
`withCronLogDrain` configured so 401 and 403 cron responses return to callers
without writing `requests`, `cron_runs`, or buffered `log_events`; attackers must
not be able to fill observability storage with unauthenticated cron probes.

Request-archive console lenses must store and return redacted summaries only.
Watcher ingestion and web-side archive normalization both redact common bearer
tokens, JWTs, sensitive key/value fields, sensitive query parameters, and email
addresses, then cap each attached console message at 500 characters. Do not
persist raw app-container console payloads in `blue-green-request-logs`.

Cron jobs should show both the raw expression and a natural description such as "Every 15 minutes", plus the previous and next scheduled run timestamps when the runtime snapshot provides them. Cron expressions are stored as runtime config, while visible daily schedule descriptions and run timestamps are rendered in the viewer's browser timezone.

The `infrastructure-sample-resources` job runs every minute through `/api/cron/infrastructure/sample-resources`. It is the automated source for retained resource charts; do not rely on opening the Resources page to create samples.

## Resources

Infrastructure → Monitoring → Resources reads the Docker runtime snapshot and displays container health, image/service identity, uptime, CPU, memory, compact network ingress/egress, and aggregate service counts. This is the operator view for Docker Desktop resource pressure without opening Docker Desktop directly.

The same tab also separates Docker build consumption from the generic container
inventory. Build resources are derived from BuildKit and builder containers
captured by `docker stats`; while a watcher deployment is `building` or
`deploying`, the `web-blue-green-watcher` container is also counted as builder
process pressure because it owns the Docker build command. This matters because
Docker Desktop can show an active Buildx record before the watcher captures a
fresh stats sample, and the Resources tab should still show that a build process
is active instead of claiming the build lane is idle. The sampled resource
metrics are charted as `docker.build.*` usage events so operators can
distinguish build pressure from runtime web, proxy, Redis, and sidecar pressure.

The internal resource sampler writes the current Docker snapshot into the log drain `usage_events` table at most once per minute. The UI charts that history across the supported resource windows: 1 hour, 6 hours, 12 hours, 24 hours, 3 days, and 7 days. If the log drain is disabled or unavailable, the tab still shows the live Docker snapshot and falls back to a single current sample.

Chart gaps on the Resources tab mean a retained sampler record is missing for that time bucket; they are not automatically downtime. The Resources tab now shows sampling continuity for runtime and build metrics, including sampled buckets, gap buckets, latest retained sample age, and a live-snapshot marker for the current bucket. If the live snapshot is healthy but historical charts have gaps, inspect the Cron tab and the `infrastructure-sample-resources` job before treating the gap as runtime unavailability.

Resource pressure uses the same thresholds as the dashboard: memory under 200 MB is green, 200-500 MB is amber, 500-1024 MB is orange, and anything above 1024 MB is red. CPU under 5% is green, 5-20% is amber, 20-40% is orange, and anything above 40% is red.

## Stress Tests

Infrastructure → Monitoring → Stress Tests queues controlled native load runs for root workspace infrastructure operators. The web app only validates permissions, writes a control request, and reads status. It must not generate load inside a Next.js route handler.

Allowed targets come from `PLATFORM_STRESS_TEST_TARGETS`, a JSON array of objects with `id`, `label`, `baseUrl`, optional `defaultPath`, and optional `description`. If the variable is absent, the dashboard exposes only the local web target at `http://127.0.0.1:7803`. Do not accept arbitrary operator-entered URLs; add production, staging, or canary targets explicitly to this allowlist.

Run the native worker with:

```bash theme={null}
node scripts/watch-stress-tests.js
```

The web container writes queued run and abort request files only under `PLATFORM_STRESS_TEST_CONTROL_DIR` or the default `tmp/docker-web/watch/control/stress-tests`, which should resolve to the writable blue/green control mount in production. The native worker consumes those control files, writes live run state under `PLATFORM_STRESS_TEST_MONITORING_DIR` or `tmp/docker-web/stress-tests`, and tags synthetic requests with `X-Tuturuuu-Stress-Test-Run` plus a stress-test user agent. Keep the runtime/monitoring tree read-only for web containers; run directories, samples, and result files are worker-owned.

Durable run summaries are stored in private Supabase tables and read only through `/api/v1/infrastructure/monitoring/stress-tests`. Completed runtime files are synced back to those private tables when the dashboard/API reads them, so rollout order stays fail-open if the migration or log-drain database is not available yet.

Per-run resource samples are also copied into log-drain `usage_events` with `stress.*` metrics and `metadata.runId`. This lets operators compare RPS, latency, CPU, memory, and network spikes against the existing Requests, Logs, Deployments, and Resources tabs for the same run window.

## Troubleshooting

If the UI is empty:

1. Confirm `log-drain-postgres` is healthy with Docker Compose.
2. Confirm `PLATFORM_LOG_DRAIN_DATABASE_URL` is present in the web container.
3. Check that the route or cron handler logs with the native console method matching severity and still runs inside a request or cron wrapper when retained correlation is required.
4. Use Infrastructure → Monitoring → Logs to search by message, route, request id, level, or source.

If `bun serve:web:docker:bg` fails with
`dependency failed to start: container ...-log-drain-postgres-1 exited (1)`,
the deploy helper now starts `log-drain-postgres` before promoting the web lane
and retries once after removing only the exited service container. The
`platform-log-drain-postgres` volume is intentionally left intact. Web and
watcher services do not declare Compose `depends_on` for this optional
Postgres service, so a failed retry is not reintroduced as a later dependency
startup failure. In current deploys, a failed retry is not a hard promotion
blocker unless
`DOCKER_WEB_LOG_DRAIN_REQUIRED=1` is set; the rollout continues for that run with
`PLATFORM_LOG_DRAIN_ENABLED=false`, so traffic can serve while persisted
request/server logs and Infrastructure monitoring are degraded. Inspect the
Postgres logs before deciding whether the volume needs migration or a reset:

```bash theme={null}
docker compose -f docker-compose.web.prod.yml --profile redis ps --all log-drain-postgres
docker compose -f docker-compose.web.prod.yml --profile redis logs --tail 200 log-drain-postgres
docker volume ls --filter label=com.docker.compose.volume=platform-log-drain-postgres
```

When the logs mention incompatible database files, a corrupted data directory,
or another persistent storage problem, back up or migrate the
`platform-log-drain-postgres` volume before retrying. Do not remove that volume
unless losing local observability history is an explicit operator decision.
Set `DOCKER_WEB_LOG_DRAIN_REQUIRED=1` only when blocking a rollout is preferable
to serving without persisted log-drain telemetry.

If logs are missing only for cron jobs, verify the cron route is wrapped with `withCronLogDrain(...)` and the cron runner is calling the expected web origin.


# Mobile Store Deployment Vault
Source: https://docs.tuturuuu.com/build/devops/mobile-store-deployment

What every Mobile Deployment vault field is, what it does in the store release workflow, and where to obtain its value.

This runbook explains each field on the **Infrastructure → Mobile Deployment**
settings page (root workspace, `manage_mobile_deployment_vault` permission). The
vault holds the secrets, signing files, and CI tokens consumed by the
`.github/workflows/mobile-deploy-stores.yaml` workflow that builds and publishes
the Flutter mobile app to the Google Play and Apple App stores.

Each field on the settings page has an inline help tooltip with a short summary
and the console URL; this page is the full reference with clickable links.

## How The Vault Is Organized

* **Secrets** — short scalar values (passwords, IDs, names) and preset
  environment variables baked into the build.
* **Files** — signing certificates, keystores, and Firebase/Play config files.
* **CI tokens** — bearer tokens the GitHub Actions workflow uses to read the
  vault. Each token value is shown only once, at issue time.
* **Overview** — readiness checks plus draft activation and rollback.

## Android Signing

| Field                                   | What it is                                                                           | Where to get it                                                                                                                                    |
| --------------------------------------- | ------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ANDROID_KEYSTORE_ALIAS`                | Alias of the signing key inside the upload keystore.                                 | Chosen when you run [`keytool -genkeypair -alias <alias>`](https://developer.android.com/studio/publish/app-signing).                              |
| `ANDROID_KEYSTORE_PASSWORD`             | Password protecting the keystore file.                                               | Set when generating the keystore with `keytool`.                                                                                                   |
| `ANDROID_KEYSTORE_PRIVATE_KEY_PASSWORD` | Password protecting the private key entry (often the same as the keystore password). | Set when generating the keystore with `keytool`.                                                                                                   |
| `android_upload_keystore` (file)        | The Java keystore (`.jks`) used to sign Android release builds.                      | Generate with [`keytool -genkeypair -v -keystore upload-keystore.jks ...`](https://developer.android.com/studio/publish/app-signing#generate-key). |

## Google Play

| Field                                     | What it is                                                                                    | Where to get it                                                                                                                                                                                                                                                  |
| ----------------------------------------- | --------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `GOOGLE_PLAY_PACKAGE_NAME`                | Play application ID (e.g. `com.tuturuuu.app.mobile`); must match the Android `applicationId`. | [Google Play Console](https://play.google.com/console) → App information.                                                                                                                                                                                        |
| `GOOGLE_PLAY_TRACK`                       | Release track (`internal`, `alpha`, `beta`, `production`).                                    | [Play release tracks](https://support.google.com/googleplay/android-developer/answer/9859348).                                                                                                                                                                   |
| `google_play_service_account_json` (file) | Service-account JSON with Play Developer API access for automated publishing.                 | [Google Cloud Console](https://console.cloud.google.com/iam-admin/serviceaccounts) → create JSON key, then grant access in Play Console → Users and permissions. See the [publisher API setup](https://developers.google.com/android-publisher/getting_started). |

## Apple Signing

| Field                                         | What it is                                                                                  | Where to get it                                                                                                                 |
| --------------------------------------------- | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `APPLE_BUNDLE_ID`                             | iOS bundle identifier (e.g. `com.tuturuuu.app.mobile`).                                     | [Apple Developer → Identifiers](https://developer.apple.com/account/resources/identifiers/list).                                |
| `APPLE_TEAM_ID`                               | 10-character Apple Developer Team ID.                                                       | [Apple Developer → Membership](https://developer.apple.com/account).                                                            |
| `APPLE_DISTRIBUTION_CERTIFICATE_PASSWORD`     | Password used when exporting the distribution certificate `.p12`.                           | Chosen by you during Keychain Access export.                                                                                    |
| `apple_distribution_certificate_p12` (file)   | Apple distribution certificate (with private key) exported as `.p12`.                       | [Apple Developer → Certificates](https://developer.apple.com/account/resources/certificates/list); export from Keychain Access. |
| `apple_app_store_provisioning_profile` (file) | App Store provisioning profile (`.mobileprovision`) tying the bundle ID to the certificate. | [Apple Developer → Profiles](https://developer.apple.com/account/resources/profiles/list).                                      |

## App Store Connect API

| Field                                     | What it is                                       | Where to get it                                                                                |
| ----------------------------------------- | ------------------------------------------------ | ---------------------------------------------------------------------------------------------- |
| `APP_STORE_CONNECT_API_KEY_ID`            | Key ID of the App Store Connect API key.         | [App Store Connect → Integrations](https://appstoreconnect.apple.com/access/integrations/api). |
| `APP_STORE_CONNECT_ISSUER_ID`             | Issuer ID that pairs with the API key.           | Same Integrations page (shown above the keys list).                                            |
| `app_store_connect_private_key_p8` (file) | API private key (`.p8`); downloadable only once. | Same Integrations page → generate key.                                                         |

## Firebase

| Field                                  | What it is                                        | Where to get it                                                                           |
| -------------------------------------- | ------------------------------------------------- | ----------------------------------------------------------------------------------------- |
| `android_google_services_json` (file)  | Firebase Android config (`google-services.json`). | [Firebase Console](https://console.firebase.google.com) → Project settings → Android app. |
| `ios_google_service_info_plist` (file) | Firebase iOS config (`GoogleService-Info.plist`). | Firebase Console → Project settings → iOS app.                                            |

## App Environment Variables

These preset env vars are baked into the build. Custom env vars can be added but
have no built-in guidance.

| Field                                     | What it is                                                       | Where to get it                                                                          |
| ----------------------------------------- | ---------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
| `NEXT_PUBLIC_SUPABASE_URL`                | Supabase project URL.                                            | [Supabase dashboard](https://supabase.com/dashboard) → Project Settings → Data API.      |
| `NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY`    | Supabase publishable (anon) key.                                 | Supabase dashboard → Project Settings → API Keys.                                        |
| `API_BASE_URL`                            | Base URL of the Tuturuuu platform API.                           | Your production web deployment URL (internal).                                           |
| `TURNSTILE_SITE_KEY`                      | Cloudflare Turnstile site key for bot protection.                | [Cloudflare → Turnstile](https://dash.cloudflare.com/?to=/:account/turnstile).           |
| `TURNSTILE_BASE_URL`                      | URL hosting the Turnstile challenge page.                        | Your production web app URL (internal).                                                  |
| `GOOGLE_WEB_CLIENT_ID`                    | Google OAuth 2.0 web client ID.                                  | [Google Cloud Console → Credentials](https://console.cloud.google.com/apis/credentials). |
| `GOOGLE_IOS_CLIENT_ID`                    | Google OAuth 2.0 iOS client ID.                                  | Same Credentials page (iOS client).                                                      |
| `MOBILE_TASK_DESCRIPTION_EDITING_ENABLED` | Feature flag for rich task-description editing (`true`/`false`). | Set manually (internal).                                                                 |
| `MOBILE_CALENDAR_INTEGRATIONS_ENABLED`    | Feature flag for calendar integrations (`true`/`false`).         | Set manually (internal).                                                                 |

## CI Tokens

| Field      | What it is                                                                                   | Where to get it                                             |
| ---------- | -------------------------------------------------------------------------------------------- | ----------------------------------------------------------- |
| Token name | A human-readable label for a CI token the deploy workflow uses to authenticate to the vault. | Chosen by you; the token value is shown once at issue time. |

## Activating Changes

Edits land in a **draft** version. Use **Verify** to re-run readiness checks,
**Activate draft** to promote it to the active bundle the workflow reads, and
**Roll back** to return to the previous active version. Fix any readiness issues
listed on the Overview tab before activating.


# DevOps & Deployment
Source: https://docs.tuturuuu.com/build/devops/overview

The operational map for how Tuturuuu is built, deployed, migrated, and validated.

This section is the runbook for shipping and operating Tuturuuu. It documents the
deployment surfaces that exist in this repository today, the workflows that own
them, and the commands the team should use when something needs to be built,
released, or recovered.

## Deployment Surfaces

| Surface                                                                                                                                                                                                                                                                                                                     | Source of truth                                                                                                                                          | Delivery target                                                                                                                                                                          |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Platform web app (`apps/web`)                                                                                                                                                                                                                                                                                               | `.github/workflows/vercel-preview-platform.yaml`, `.github/workflows/vercel-production-platform.yaml`                                                    | Vercel preview build validation and production deploy                                                                                                                                    |
| Satellite web apps (every app under `apps/*` with a `vercel-preview-<app>.yaml` / `vercel-production-<app>.yaml` pair: `apps`, `nova`, `rewise`, `calendar`, `finance`, `inventory`, `infrastructure`, `meet`, `tasks`, `track`, `shortener`, `qr`, `cms`, `mail`, `learn`, `teach`, `chat`, `drive`, `mind`, `storefront`) | `.github/workflows/vercel-preview-*.yaml`, `.github/workflows/vercel-production-*.yaml`                                                                  | Vercel preview and production deployments                                                                                                                                                |
| Database schema (`apps/database`)                                                                                                                                                                                                                                                                                           | `.github/workflows/supabase-staging.yaml`, `.github/workflows/supabase-production.yaml`                                                                  | Supabase staging and production projects                                                                                                                                                 |
| Self-hosted web runtime (`apps/web`)                                                                                                                                                                                                                                                                                        | `apps/web/Dockerfile`, `docker-compose.web.yml`, `docker-compose.web.prod.yml`, `scripts/docker-web.js`                                                  | Docker dev stacks and production blue/green deployments                                                                                                                                  |
| Migration web runtime (`apps/tanstack-web`)                                                                                                                                                                                                                                                                                 | `apps/tanstack-web/Dockerfile`, `apps/tanstack-web/wrangler.jsonc`, `.github/workflows/rust-backend.yml`, `.github/workflows/vercel-*-tanstack-web.yaml` | Docker sidecar + Cloudflare Worker (`tuturuuu-tanstack-web`) + opt-in Vercel build validation - see [TanStack/Rust Local And Deployment](/build/devops/tanstack-rust-local-deploy)       |
| Rust backend (`apps/backend`)                                                                                                                                                                                                                                                                                               | `apps/backend/Dockerfile`, `apps/backend/wrangler.jsonc`, `.github/workflows/rust-backend.yml`                                                           | Docker sidecar on port `7820` + manually dispatched Cloudflare Worker (`tuturuuu-backend`) with preflighted secrets — see [GitHub Actions Runbook](/build/devops/github-actions-runbook) |
| Discord utilities (`apps/discord`)                                                                                                                                                                                                                                                                                          | `.github/workflows/discord-modal-deploy.yml`                                                                                                             | Modal                                                                                                                                                                                    |
| Mobile artifacts (`apps/mobile`)                                                                                                                                                                                                                                                                                            | `.github/workflows/mobile-build-*.yaml`                                                                                                                  | Build artifacts for Android, iOS, macOS, Windows                                                                                                                                         |
| Shared packages (`packages/*`)                                                                                                                                                                                                                                                                                              | `.github/workflows/release-*.yaml`                                                                                                                       | npm                                                                                                                                                                                      |

## Read This In Order

1. [Environments & Release Flow](/build/devops/environments-release-flow)
2. [Web Docker Deployment](/build/devops/web-docker-deployment)
3. [TanStack/Rust Local And Deployment](/build/devops/tanstack-rust-local-deploy)
4. [GitHub Actions Runbook](/build/devops/github-actions-runbook)
5. [Secrets & Configuration](/build/devops/secrets-and-configuration)

## Core Principles

* GitHub Actions is the canonical automation layer for hosted deployments, platform build validation, and database migrations.
* `tuturuuu.ts` can disable individual workflows; `ci-check.yml` enforces that toggle before a job does real work.
* `bun check` includes path-sensitive Discord Python validation when the local
  diff touches `apps/discord/**` or `.github/workflows/discord-python-ci.yml`.
  That path runs the same blocking checks as Discord Python CI through
  `scripts/check-discord-python.js`.
* Vercel handles hosted satellite web deployments, opt-in TanStack frontend build validation, platform preview build validation, and the hosted platform production deploy. Supabase migrations run as separate workflows; `main` drives staging schema promotion and `production` drives production schema promotion.
* Self-hosted web deployment is Docker-based, and blue/green rollout is the supported rebuild-before-restart path.
* The TanStack/Rust migration runs in parallel with `apps/web`: `apps/tanstack-web` (TanStack Start) and `apps/backend` (Rust, port `7820`) ship as Docker sidecars and Cloudflare Workers, and the TanStack frontend has Vercel build validation when it points at an HTTPS backend origin. See [TanStack/Rust Local And Deployment](/build/devops/tanstack-rust-local-deploy), [Web Docker Deployment](/build/devops/web-docker-deployment), and the [TanStack/Rust migration](/platform/architecture/tanstack-rust-migration) plan.
* Secrets live in GitHub Actions secrets/variables or local env files such as `apps/web/.env.local`. They do not belong in the repo.

## Vercel Cost Controls

Start with measured usage instead of applying cache directives globally. The
following commands identify the expensive projects and inspect a bounded sample
of production traffic without enabling a paid observability add-on:

```bash theme={null}
vercel usage --scope tuturuuu --group-by project --format json
vercel logs --project <app> --scope tuturuuu --environment production --since 1h --json --no-branch
```

`vercel metrics` requires Observability Plus. A `payment_required` response is
an expected limitation when the add-on is disabled; do not enable it solely for
routine cost diagnosis.

Apply these controls in order:

1. Reduce request count and response size before adding cache writes. Prefer
   direct-to-storage signed uploads for large payloads and avoid routing public
   assets through application functions when a stable CDN URL is available.
2. Cache only public or safely scoped data. Never apply shared CDN caching to
   authenticated, user-specific, or workspace-private responses.
3. Shared Satellite and Nova React Query clients use a 30-second stale window
   and one retry. Override this only when a surface has a documented freshness
   or reliability requirement.
   Realtime-backed notification counts use a 15-minute fallback poll and a
   5-minute stale window. Active timers render elapsed time locally and use
   1-minute running / 5-minute idle reconciliation. Keep mutations and realtime
   events invalidating their query keys immediately instead of shortening these
   safety-net intervals.
   Versioned external-project asset reads return early from the global API proxy
   and rely on the asset route's publication/access checks, avoiding the global
   guard's cookie validation, suspicious-request checks, and rate-limit work per
   cache-busted media redirect. Mutations, unversioned reads, and WebGL delivery
   remain behind the global guard.
4. Dashboard sidebar links disable viewport prefetch and prefetch on hover or
   keyboard focus. This preserves responsive navigation without invoking every
   visible destination merely because the sidebar rendered.
5. After deployment, compare the same billing window and project grouping.
   Confirm error rates and latency remain healthy before keeping a cost change.

## Operational Flow

```mermaid theme={null}
flowchart LR
    Branch["Git branch or manual dispatch"]
    Preview["Platform preview build"]
    Staging["Supabase staging migration"]
    Production["Platform production deploy"]
    ProdDb["Supabase production migration"]
    Docker["Self-hosted Docker deploy"]

    Branch --> Preview
    Preview --> Staging
    Branch --> Production
    Production --> ProdDb
    Branch --> Docker
```

## What Changed Recently

* The TanStack/Rust migration runtimes are now first-class deployment surfaces: `apps/backend` (Rust) builds a native binary, a Docker image, and a Cloudflare Worker bundle via `.github/workflows/rust-backend.yml`; `apps/tanstack-web` validates type-checks/tests, deploys as a Cloudflare Worker (`tuturuuu-tanstack-web`) bound to the backend Worker (`tuturuuu-backend`), and has Vercel preview/production build workflows for frontend compatibility against a separate HTTPS backend origin. Cloudflare uploads are manual-dispatch only and preflight `CLOUDFLARE_API_TOKEN`, `CLOUDFLARE_ACCOUNT_ID`, and Worker runtime secret names before deploying.
* `apps/web` now supports both in-place Docker production deploys and blue/green deploys.
* `docker-setup-check.yaml` validates Docker parity, renders both compose files, and builds both the dev and production web images.
* Production Redis in Docker now requires a token, but `scripts/docker-web.js`
  satisfies that automatically by generating and injecting the value unless you
  explicitly opt out with `--without-redis`. Watcher-managed Infrastructure
  projects do not inherit that platform Redis token; they start with Redis
  disabled and require project-scoped `MANAGED_PROJECT_<PROJECT_ID>_UPSTASH_*`
  credentials when Redis is intentionally enabled.

If you are changing deployment behavior, update this section and add any new
page to `apps/docs/docs.json`.


# Polar storefront integration
Source: https://docs.tuturuuu.com/build/devops/polar-storefront-integration

Connect a workspace storefront to Polar, wire the payment webhook, and book sales into finance.

This runbook covers connecting an Inventory storefront to [Polar](https://polar.sh)
for real checkout, pointing Polar's webhook at Tuturuuu, and how a paid sale
flows into the workspace finance ledger.

<Warning>
  Never paste Polar tokens, client secrets, or webhook secrets into source,
  docs, or chat. They are supplied only through environment variables and the
  per-workspace integration panel, which stores them encrypted.
</Warning>

## How the flow works

1. A shopper checks out on a `checkoutMode: 'polar'` storefront. Tuturuuu creates
   a Polar checkout and stores `polar_checkout_id` on the
   `private.inventory_checkout_sessions` row (status `reserved`).
2. The shopper pays on Polar. Polar sends an `order.updated` webhook to Tuturuuu.
3. `syncInventoryPolarOrder` marks the checkout `completed` and, when the order
   is `paid`, books the revenue into the workspace finance ledger
   (`wallet_transactions`) using the product's finance category and the
   workspace default wallet. This is idempotent — a sale books at most one
   transaction.

## Money and currency

Inventory commerce money (storefront listing prices, bundle prices,
`compare_at_price`, checkout session/line amounts, settlement ledger entries,
and costing figures) is stored in **integer minor units** of the row's
currency — cents for USD/EUR, but whole units for zero-decimal currencies like
JPY/VND. This matches how Polar represents amounts, so the product/bundle/
checkout sync passes the stored value straight through without scaling.

Conversion is centralized in `@tuturuuu/utils/money`:

* `majorToMinor(amount, currency)` / `minorToMajor(minor, currency)` — convert
  at input/storage and read/display boundaries (currency-aware: USD ×100,
  JPY/VND ×1).
* `formatMoneyFromMinor(minor, currency)` — the canonical display formatter.
* The shared `MoneyInput` (`@tuturuuu/ui/money-input`) takes and emits minor
  units while editing in localized major units.

Two boundaries convert explicitly:

* The finance ledger (`wallet_transactions.amount`) stores **major** units, so
  `recordInventorySaleFinanceTransaction` converts the checkout's minor-unit
  total back to major units when booking revenue.
* Promotions (`workspace_promotions.value`) remain in major units (shared with
  finance invoices); `promotions-polar` multiplies by 100 at the Polar boundary.

> Inventory base prices use exact decimal major units, while Storefront listing,
> bundle, checkout, and Polar amounts use integer minor units. Convert only at
> the explicit provider boundary; never manually multiply a saved Inventory
> price before publishing it.

## Bundles and listings ↔ Polar products

Publishing is automatic: creating or updating a listing/bundle schedules a
best-effort push to Polar (a product with a fixed price per currency). Standalone
bundles with no storefront publish against the workspace-level Polar integration
and are priced in USD. Two-way sync:

* **App → Polar:** name, description, and price sync on every write. Archiving a
  listing/bundle (or deleting it) archives its Polar product so it is no longer
  buyable; re-publishing un-archives it.
* **Polar → App:** `product.created/updated` webhooks apply name, description,
  and price back onto the mapped inventory row.

## Environment variables

Set these on `apps/pay` (reference by name only). Inventory-only deployments
that create Polar products also need the access token and sandbox/currency
configuration in their owning runtime:

| Variable               | Purpose                                                                                                                |
| ---------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| `POLAR_SANDBOX`        | `true` to use Polar's sandbox; unset/`false` for production.                                                           |
| `POLAR_ACCESS_TOKEN`   | Platform-level Polar organization access token.                                                                        |
| `POLAR_WEBHOOK_SECRET` | Secret used to verify incoming Polar webhook signatures. Must match the value Polar shows when you create the webhook. |
| `POLAR_CURRENCIES`     | Optional allowlist of supported storefront currencies.                                                                 |

For sandbox testing, create the credentials at
`https://sandbox.polar.sh/dashboard/<org>/settings` and the OAuth app /
organization token under **User Settings → Developer**.

## Connect a workspace to Polar

1. Open **Inventory → Overview → Polar settings** in the workspace.
2. Choose the environment (sandbox or production) and paste the Polar
   **organization access token**. It is encrypted per workspace before storage;
   only the last 4 characters are ever shown again.
3. Save. Tuturuuu validates the token and provisions a private
   `inventory_checkout` product in your Polar org.

## Configure the Polar webhook

In the Polar dashboard for your org → **Settings → Webhooks → Add Endpoint**:

1. **URL** — the canonical Pay webhook endpoint:

   ```
   https://pay.tuturuuu.com/api/payment/webhooks
   ```

   For local development, expose `localhost` with a tunnel (e.g. `cloudflared`
   or `ngrok`) and use the tunnel's HTTPS URL with the same path.

2. **Format** — `Raw`.

3. **Events** — subscribe at minimum to:

   * `checkout.created`
   * `checkout.updated`
   * `order.created`
   * `order.updated`

4. Copy the webhook **secret** Polar generates and set it as
   `POLAR_WEBHOOK_SECRET` on `apps/pay`. Signature verification fails closed if
   it does not match.

<Tip>
  Sandbox changes never touch your live Polar account and never move real money
  — the dashboard shows a "Payments are not processed" banner.
</Tip>

## Verify a paid sale books finance

1. Place a sandbox checkout on a `polar` storefront and complete payment.
2. Confirm Polar delivered the `order.updated` event (Webhooks → Deliveries).
3. The checkout session flips to `completed` with `polar_status = paid`.
4. A `wallet_transactions` row appears in the workspace finance ledger for the
   sale total, linked back via `inventory_checkout_sessions.finance_transaction_id`.

If no transaction appears, check that the workspace has a **default wallet** set
(finance config `default_wallet_id`) — booking is skipped without one.


# Secrets & Configuration
Source: https://docs.tuturuuu.com/build/devops/secrets-and-configuration

Where deployment configuration lives, and which secrets matter for each delivery surface.

This page documents secret names and configuration boundaries. It does not contain
secret values.

## General Rules

* Store hosted deployment credentials in environment-scoped GitHub Actions
  secrets.
* Store Vercel app runtime and build-time configuration in the Vercel project
  environment, not workflow-wide GitHub Actions environment variables.
* Store local web runtime configuration in `apps/web/.env.local`.
* Do not commit tokens, keys, passwords, or rendered env dumps.
* Do not edit checked-in compose files to inject per-environment secrets.

## Local And Self-Hosted Web

| Location               | Purpose                                                                                                                                     |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `apps/web/.env.local`  | Docker build secret input and runtime env file for the web app                                                                              |
| Shell environment      | Optional overrides such as `DOCS_PORT`, `SUPABASE_SERVER_URL`, or `UPSTASH_REDIS_REST_*` when you intentionally override the Docker helpers |
| `tmp/docker-web/prod/` | Generated local deployment state for blue/green rollout                                                                                     |

## GitHub Actions Secrets By Area

### Vercel-hosted web apps

Vercel workflows use GitHub Environments named `vercel-preview-<app>` and
`vercel-production-<app>`. Keep the deployment secrets on those environments,
not as workflow-level `env:` entries. Production environments should require
reviewers and restrict deployment branches to `production`; preview environments
should require review whenever branch pushes can run repository-controlled code
with deployment credentials.

* `VERCEL_TOKEN`
* `VERCEL_ORG_ID`
* App-specific `VERCEL_PROJECT_ID` values such as `VERCEL_PLATFORM_PROJECT_ID`
  and `VERCEL_APPS_PROJECT_ID`
* Infrastructure deployments use `VERCEL_INFRASTRUCTURE_PROJECT_ID` in the
  `vercel-preview-infrastructure` and `vercel-production-infrastructure` GitHub
  Environments
* QR deployments use `VERCEL_QR_PROJECT_ID` in the `vercel-preview-qr` and
  `vercel-production-qr` GitHub Environments

### Turborepo remote cache

Remote-cache identity is repository-wide rather than app runtime
configuration:

* Store a dedicated, least-privilege Vercel team cache token as the repository
  secret `TURBO_TOKEN`. Rotate it independently from deployment tokens and
  revoke the previous token after trusted canaries pass.
* Store the Vercel team slug as the repository variable `TURBO_TEAM`. Workflows
  temporarily accept `secrets.TURBO_TEAM` as a migration fallback; remove that
  secret after the variable is confirmed.
* Leave `TURBO_API` unset for Vercel-managed remote caching.
* Do not configure `TURBO_REMOTE_CACHE_SIGNATURE_KEY` until artifact signing is
  deliberately enabled and rolled out.
* Optional repository variables `ACTIONS_CACHE_NOTICE_PERCENT`,
  `ACTIONS_CACHE_WARNING_PERCENT`, and `ACTIONS_CACHE_CRITICAL_PERCENT` override
  the weekly report's 80/90/100 thresholds. Cache size and retention are not
  variables; the report discovers both from GitHub's repository API.

Only pass these values as inputs to
`.github/actions/run-with-turbo-remote-cache/action.yml`. The action places them
on the wrapped command step, not the workflow, job, `GITHUB_ENV`, image layer,
or deployment artifact. Never pass `TURBO_TOKEN` to pull-request or Dependabot
jobs; secretless jobs use the task-family GitHub cache fallback.

### Production and preview app configuration

These values belong in the Vercel project environment for each app and target.
Do not export them from GitHub Actions workflows. The Vercel deploy workflows
run repository code during install and build, so workflow-wide production
runtime secrets are a supply-chain exposure path.

* `PRODUCTION_SUPABASE_URL`
* `PRODUCTION_SUPABASE_PUBLISHABLE_KEY`
* `PRODUCTION_SUPABASE_SECRET_KEY`
* `ENCRYPTION_MASTER_KEY`

Turborepo cache identity is the repository-level configuration described above,
not a Vercel app runtime secret. Do not duplicate it into every project's
runtime environment.

Individual workflows may also consume other application-specific secrets depending on
the deployed app.

### Integration-specific runtime secrets

* SePay OAuth requires `SEPAY_OAUTH_CLIENT_ID`, `SEPAY_OAUTH_CLIENT_SECRET`,
  `SEPAY_OAUTH_TOKEN_ENCRYPTION_SECRET`, and a webhook auth secret such as
  `SEPAY_WEBHOOK_API_KEY`.
* SePay web runtimes also require an app origin through `WEB_APP_URL`,
  `NEXT_PUBLIC_WEB_APP_URL`, or `NEXT_PUBLIC_APP_URL` so OAuth callbacks and
  webhook provisioning can generate stable platform URLs.
* SePay workspace enablement is controlled by the workspace secret
  `ENABLE_SEPAY_INTEGRATION=true`.
* SePay runtime overrides may optionally set `SEPAY_OAUTH_AUTHORIZE_URL`,
  `SEPAY_OAUTH_BASE_URL`, and `SEPAY_API_BASE_URL` when targeting non-default
  environments.
* SePay OAuth state is stored in a short-lived HttpOnly callback cookie and is
  HMAC-signed. The signer uses `SEPAY_OAUTH_STATE_SECRET` when set; otherwise it
  falls back to the required `SEPAY_OAUTH_CLIENT_SECRET`.
* Polar (inventory storefront checkout + workspace subscriptions) requires
  `POLAR_ACCESS_TOKEN` (platform-level org token) and `POLAR_WEBHOOK_SECRET`
  (webhook signature verification) on `apps/pay`. Set `POLAR_SANDBOX=true` to
  target Polar's sandbox, and the optional `POLAR_CURRENCIES` to allowlist
  storefront currencies. Configure Polar to deliver webhooks to
  `https://pay.tuturuuu.com/api/payment/webhooks`; `apps/web` no longer owns
  payment API or webhook routes. See the Polar storefront integration runbook
  for details.
* Square Terminal (Inventory + Storefront pay-at-terminal checkout) stores
  Square application credentials, OAuth/manual tokens, webhook signature keys,
  locations, terminal ids, and webhook notification URL overrides encrypted from
  Inventory settings. Do not configure Square credentials as deployment secrets.
  See the Square Terminal integration runbook for the complete setup and smoke
  checklist.

### Supabase migrations

* `SUPABASE_ACCESS_TOKEN`
* `STAGING_DB_PASSWORD`
* `STAGING_PROJECT_ID`
* `STAGING_DB_URL`
* `PRODUCTION_DB_PASSWORD`
* `PRODUCTION_PROJECT_ID`
* `PRODUCTION_DB_URL`

### Modal deployment

* `MODAL_TOKEN_ID`
* `MODAL_TOKEN_SECRET`
* `MODAL_ENVIRONMENT` as a GitHub Actions variable

### Mobile store beta deployment

`mobile-deploy-stores.yaml` uses the `mobile-store-beta` GitHub Environment and
runs only from `production` pushes that touch `apps/mobile/**`,
`scripts/mobile-deployment/**`, the workflow file, `ci-check.yml`, or
`tuturuuu.ts`. Keep this environment branch-restricted to `production`.

GitHub Environment secrets:

* `MOBILE_DEPLOYMENT_CI_TOKEN`: issued from the root workspace mobile deployment
  vault and scoped to `production` mobile deployment.

If `MOBILE_DEPLOYMENT_CI_TOKEN` is not set yet, the mobile store workflow's
credentials preflight emits a notice and skips the Android and iOS publish jobs.
Set the secret when the deployment vault is ready; invalid non-empty tokens still
fail during bundle fetch so real misconfiguration remains visible.

No Firebase, signing, store API, or mobile build secret values should be stored
in GitHub Environment secrets or variables. Those resources live in the
`apps/infrastructure` mobile deployment vault at `/internal/mobile-deployment`,
which is root-workspace-only and requires `manage_mobile_deployment_vault`.

apps/web deployment requirements:

* `ENCRYPTION_MASTER_KEY`: required before uploads, activation, and CI bundle
  fetches can decrypt the per-version deployment data key.
* Root workspace Drive/R2/Supabase storage must be available. File resources are
  stored as encrypted ciphertext blobs under the reserved
  `.tuturuuu/mobile-deployment-vault` prefix; normal Drive routes deny that
  prefix.

Vault resources required before activation:

* Manage all non-file values in the vault's **Secrets** panel. Build-time
  secrets are rendered into `apps/mobile/.env.github` during CI; built-in
  signing and store secrets are exported separately for the Android and iOS
  release steps. The expected production build-time keys are
  `NEXT_PUBLIC_SUPABASE_URL`, `NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY`,
  `API_BASE_URL`, `TURNSTILE_SITE_KEY`, `TURNSTILE_BASE_URL`,
  `GOOGLE_WEB_CLIENT_ID`, `GOOGLE_IOS_CLIENT_ID`,
  `MOBILE_TASK_DESCRIPTION_EDITING_ENABLED`, and
  `MOBILE_CALENDAR_INTEGRATIONS_ENABLED`. Custom secrets are allowed when they
  use uppercase `A-Z0-9_` names, do not collide with built-in secret names, and
  have single-line UTF-8 values.
* CI file payload keys such as `MOBILE_ANDROID_GOOGLE_SERVICES_JSON_B64` and
  `MOBILE_IOS_GOOGLE_SERVICE_INFO_PLIST_B64` are rejected as secrets; upload
  those payloads through the file resources below.
* Android files: production `google-services.json`, upload keystore, and Google
  Play service-account JSON.
* Built-in Android secrets: `ANDROID_KEYSTORE_ALIAS`,
  `ANDROID_KEYSTORE_PASSWORD`, `ANDROID_KEYSTORE_PRIVATE_KEY_PASSWORD`,
  `GOOGLE_PLAY_PACKAGE_NAME=com.tuturuuu.app.mobile`, and
  `GOOGLE_PLAY_TRACK=internal`.
* iOS files: production `GoogleService-Info.plist`, Apple distribution `.p12`,
  App Store provisioning profile, and App Store Connect `.p8` private key.
* Built-in iOS secrets: `APPLE_BUNDLE_ID=com.tuturuuu.app.mobile`,
  `APPLE_DISTRIBUTION_CERTIFICATE_PASSWORD`, `APPLE_TEAM_ID`,
  `APP_STORE_CONNECT_API_KEY_ID`, and `APP_STORE_CONNECT_ISSUER_ID`.

After every resource is uploaded, activate the ready draft version and issue a
CI token. Store only that token in the `mobile-store-beta` GitHub Environment as
`MOBILE_DEPLOYMENT_CI_TOKEN`.

### Package publishing

Package publishing uses **npm trusted publishing** (GitHub OIDC), so **no
`NPM_TOKEN` secret is stored**. The `publish-npm` job in each
`release-*-package.yaml` workflow requests `id-token: write`, downloads the
prepared tarball, and runs `npm publish` while npm exchanges the OIDC token for a
short-lived publish credential.

* Each publish job is bound to a per-package GitHub Environment
  (`ui-release-production` for `@tuturuuu/ui`, `types-release-production` for
  `@tuturuuu/types`), and the matching npm trusted publisher must reference this
  repository, the exact workflow filename, and that environment.
* No npm registry token (`NPM_TOKEN` or `NODE_AUTH_TOKEN`) is set on these
  environments. Adding one would be unnecessary and would weaken the
  build-vs-publish job split.

See the trusted-publishing details in the
[GitHub Actions runbook](/build/devops/github-actions-runbook).

## Docker-Specific Notes

* The Docker web helper auto-generates a stable local Redis token and injects
  `UPSTASH_REDIS_REST_TOKEN`, `UPSTASH_REDIS_REST_URL`, and the matching
  internal `SRH_TOKEN` value for the bundled `serverless-redis-http` container.
* Watcher-managed Infrastructure projects do not inherit the integrated Docker
  Redis runtime. They start with Redis disabled, strip generic
  `UPSTASH_REDIS_REST_*` and Docker-specific `DOCKER_UPSTASH_*` values, and
  receive Redis only from project-scoped
  `MANAGED_PROJECT_<PROJECT_ID>_UPSTASH_REDIS_REST_URL` and
  `MANAGED_PROJECT_<PROJECT_ID>_UPSTASH_REDIS_REST_TOKEN` variables.
* `SRH_TOKEN` is the container's internal environment variable. The user-facing
  override surface is `UPSTASH_REDIS_REST_TOKEN` if you intentionally replace
  the helper-generated value.
* The local dev compose file keeps a dev-only fallback token for direct local
  use, but production Redis compose requires `UPSTASH_REDIS_REST_TOKEN` during
  Compose interpolation. Use the Docker web helper or export a strong token
  before enabling the production `redis` profile directly.
* Redis and `serverless-redis-http` host ports must stay loopback-bound. Do not
  publish those sidecars on all host interfaces or through Cloudflare Tunnel.
* `apps/web` uses Redis for defense-in-depth one-time state such as CLI
  refresh-token replay protection. If `UPSTASH_REDIS_REST_URL` and
  `UPSTASH_REDIS_REST_TOKEN` are unavailable, CLI refresh requests continue
  after JWT validation and user lookup, while confirmed Redis-backed replays are
  still rejected.
* `docker compose config` expands env values; treat its output as sensitive.

## Supabase RPC Authorization Hardening

* Treat every new `SECURITY DEFINER` function in `public` as externally callable until proven otherwise.
* In the same migration that creates or replaces the function, enforce both:
  1. in-function authorization checks (`auth.uid()` plus workspace membership/permission gate), and
  2. explicit execute privileges (`revoke all ... from public`, then grant only required roles such as `authenticated`/`service_role`).
* Do not rely only on `apps/web` page or API RBAC checks for tenant isolation when an RPC is exposed through the Data API.
* During review, grep the migration for `security definer`, `auth.uid()`, `has_workspace_permission`, `revoke`, and `grant execute` before merge.

## Change Management

When a new deployment flow is added:

1. Add its secret names here.
2. Add the workflow or runtime page to the relevant devops doc.
3. Keep the boundary clear between repo config, GitHub Actions config, and machine-local config.


# SePay Testing Guide
Source: https://docs.tuturuuu.com/build/devops/sepay-testing-guide

End-to-end validation steps for OAuth, provisioning, and webhook ingestion.

## Prerequisites

* The web app is reachable locally.
* You have a target workspace id.
* `ENABLE_SEPAY_INTEGRATION=true` is set in `workspace_secrets`.
* The web runtime is configured with:
  * `SEPAY_OAUTH_CLIENT_ID`
  * `SEPAY_OAUTH_CLIENT_SECRET`
  * `SEPAY_OAUTH_TOKEN_ENCRYPTION_SECRET`
  * `SEPAY_WEBHOOK_API_KEY` or `SEPAY_WEBHOOK_SECRET`
  * `WEB_APP_URL` or `NEXT_PUBLIC_WEB_APP_URL` or `NEXT_PUBLIC_APP_URL`
* Optional overrides:
  * `SEPAY_OAUTH_AUTHORIZE_URL`
  * `SEPAY_OAUTH_BASE_URL`
  * `SEPAY_API_BASE_URL`

## Enable The Workspace Flag

```sql theme={null}
insert into workspace_secrets (ws_id, name, value)
values ('<WS_ID>', 'ENABLE_SEPAY_INTEGRATION', 'true')
on conflict (ws_id, name)
do update set value = excluded.value;
```

## Validate OAuth

1. Start OAuth from the same browser session that will receive the callback.
2. Call:

```bash theme={null}
curl -X POST \
  "http://localhost:7803/api/v1/workspaces/<WS_ID>/integrations/sepay/oauth/start" \
  -H "Authorization: Bearer <YOUR_APP_TOKEN>" \
  -c /tmp/sepay-oauth.cookies
```

3. Open the returned `authorizeUrl`.
4. Complete SePay consent.
5. Confirm the callback succeeds and the workspace receives a SePay connection.

## Validate Provisioning

```bash theme={null}
curl "http://localhost:7803/api/v1/workspaces/<WS_ID>/integrations/sepay/endpoints" \
  -H "Authorization: Bearer <YOUR_APP_TOKEN>"
```

Expected:

* At least one active endpoint.
* `token_prefix` is present.
* `sepay_webhook_id` is present after provisioning.

Database checks:

```sql theme={null}
select id, ws_id, status, access_token_expires_at, scopes
from sepay_connections
where ws_id = '<WS_ID>';

select id, ws_id, sepay_bank_account_id, sepay_sub_account_id, wallet_id, active
from sepay_wallet_links
where ws_id = '<WS_ID>';

select id, ws_id, active, deleted_at, token_prefix, sepay_webhook_id
from sepay_webhook_endpoints
where ws_id = '<WS_ID>'
order by created_at desc;
```

## Validate Webhook Ingestion

```bash theme={null}
curl -X POST \
  "http://localhost:7803/api/v1/webhooks/sepay/<ENDPOINT_TOKEN>" \
  -H "Authorization: Bearer <SEPAY_WEBHOOK_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "evt_test_001",
    "gateway": "VCB",
    "transactionDate": "2026-04-09T10:00:00+07:00",
    "accountNumber": "0071000888888",
    "subAccount": null,
    "content": "Thu tien don hang #1001",
    "description": "Thanh toan don hang",
    "transferType": "in",
    "transferAmount": 150000,
    "referenceCode": "REF1001",
    "code": "PAY1001"
  }'
```

Expected:

* The API returns success, or duplicate-safe success on replay.
* A `sepay_webhook_events` row exists for `evt_test_001`.
* A `wallet_transactions` row exists and is linked through
  `created_transaction_id`.
* `transactionDate` should always include an explicit timezone such as
  `+07:00`. Bare `YYYY-MM-DD HH:mm:ss` strings are interpreted as Vietnam time
  (UTC+7) for SePay compatibility; omitting the timezone in test payloads is a
  fixture bug, not a supported operator shortcut.

Verification query:

```sql theme={null}
select id, sepay_event_id, status, created_transaction_id, failure_reason
from sepay_webhook_events
where ws_id = '<WS_ID>'
order by received_at desc
limit 20;

select id, wallet_id, category_id, amount, creator_id, description, taken_at
from wallet_transactions
where creator_id in (
  select id
  from workspace_users
  where ws_id = '<WS_ID>'
    and full_name = 'SePay System'
)
order by created_at desc
limit 20;
```

## Idempotency

Resend the exact same payload with the same `id`.

Expected:

* No duplicate transaction is inserted.
* The event is treated as a duplicate/no-op.

## Expense Direction

Send a payload with `transferType: "out"` and a positive `transferAmount`.

Expected:

* `wallet_transactions.amount` is stored as a negative value.
* The transaction resolves against an expense category.

## Endpoint Lifecycle

1. Create an endpoint.
2. Rotate the endpoint.
3. Delete the endpoint.

Expected:

* Deleted endpoints have `active = false`.
* Deleted endpoints have `deleted_at is not null`.
* Listing routes exclude deleted endpoints.
* Token resolution ignores deleted endpoints.

## Disconnect

```bash theme={null}
curl -X POST \
  "http://localhost:7803/api/v1/workspaces/<WS_ID>/integrations/sepay/disconnect" \
  -H "Authorization: Bearer <YOUR_APP_TOKEN>"
```

Expected:

* `sepay_connections.status = 'revoked'`
* Active endpoints are marked inactive and soft-deleted.

## Failure Paths

* Invalid webhook auth header is rejected.
* Invalid webhook JSON body returns a validation error.
* Unknown endpoint token is rejected.
* Disabled feature flag blocks SePay workspace APIs.

## Troubleshooting

* OAuth start failures usually mean missing OAuth env vars or app-origin config.
* OAuth callback state failures usually mean the callback did not reuse the
  browser session or cookie jar that started OAuth.
* Provisioning failures usually mean SePay has no usable bank account or the
  webhook scopes were not granted.
* Missing transactions should be debugged from
  `sepay_webhook_events.failure_reason` first.


# Square Terminal integration
Source: https://docs.tuturuuu.com/build/devops/square-terminal-integration

Connect Inventory and Storefront checkout to Square Terminal, OAuth, catalog and stock sync, device pairing, and webhooks.

This runbook covers the Inventory and Storefront integration with
[Square Terminal](https://developer.squareup.com/docs/terminal-api/overview).
Use Square Terminal API for countertop terminal payments; the
[Square POS API](https://developer.squareup.com/docs/pos-api/what-it-does)
opens the mobile Square Point of Sale app and is not the right integration for
driving physical terminals from Tuturuuu.

For a store-owner-friendly walkthrough, use
[Set up a physical Square POS](/platform/applications/inventory-square-pos).

<Warning>
  Never paste Square access tokens, OAuth secrets, webhook signature keys, or
  device identifiers into source, docs, or chat. Store workspace credentials
  only through the Inventory Square settings panel, which encrypts them before
  private-schema storage.
</Warning>

## Customer guide map

<CardGroup>
  <Card title="Account and counter setup" icon="plug" href="/platform/applications/inventory-square-pos/customer-setup">
    Roles, credentials, OAuth, webhooks, location, and device setup.
  </Card>

  <Card title="Sandbox test plan" icon="flask" href="/platform/applications/inventory-square-pos/sandbox-testing">
    Success, cancel, timeout, offline, expiry, duplicate event, and stock tests.
  </Card>

  <Card title="Catalog synchronization" icon="arrows-rotate" href="/platform/applications/inventory-square-pos/catalog-sync">
    Direction selection, links, conflicts, prices, counts, and no-delete rules.
  </Card>

  <Card title="Production launch" icon="shield-check" href="/platform/applications/inventory-square-pos/production-launch">
    Physical pairing, first live sale, go/no-go gate, and customer handoff.
  </Card>

  <Card title="Operations" icon="chart-line" href="/platform/applications/inventory-square-pos/operations">
    Payments hub observability, lifecycle, reconciliation, and daily checks.
  </Card>

  <Card title="Troubleshooting" icon="life-ring" href="/platform/applications/inventory-square-pos/troubleshooting">
    Safe symptom-based recovery and escalation packets.
  </Card>
</CardGroup>

## How the flow works

1. A shopper checks out on a `checkoutMode: 'square_terminal'` storefront.
   Tuturuuu validates Square readiness, creates a local checkout reservation,
   stores the provider as `square_terminal`, and returns the buyer to the local
   order reference page.
2. A Square Terminal Storefront dispatches the reserved checkout immediately;
   an eligible reserved row can also be sent or canceled from the Inventory
   Commerce workflow. Tuturuuu creates a Square order, then creates a Terminal
   checkout for the selected location and device with the Square order id and
   itemized cart display enabled.
3. Square sends terminal checkout and payment webhooks. Tuturuuu verifies the
   raw webhook body signature before parsing, reconciles duplicate deliveries
   idempotently, and completes the checkout only after a verified paid payment.
4. On Square create failure, cancellation, expiry, or failed terminal checkout,
   Tuturuuu releases the local reservation so stock returns to availability. A
   five-minute expiry sweep materializes abandoned 15-minute reservations as
   `expired`; checkout reads and new checkout creation also reconcile stale rows.

Catalog sync supports Square to Tuturuuu, Tuturuuu to Square, and two-way
comparison. It is intentionally non-destructive on Square: Tuturuuu uses
Catalog Batch Upsert and physical inventory counts, never calls a Square catalog
delete endpoint, preserves Square-only variations when updating an item, and
turns simultaneous edits into conflicts for operator review. A Square deletion
marks the local link for review without deleting local product or stock data.
Inventory base prices use exact decimal major units, so Square Money amounts
round-trip at the currency exponent without rounding to whole dollars. Legacy
fractional-price holds clear on the next Square-to-Tuturuuu import after the
cent-level schema migration is applied.

## Workspace credentials

Square credentials are self-serve per workspace, like Inventory Polar settings.
Do not configure Square app credentials, access tokens, or webhook signature
keys as deployment secrets. Workspace admins save these values in **Inventory →
Payments → Connect & set up → Square POS**, where Tuturuuu encrypts secret
values before private-schema storage.

The Square REST client pins `Square-Version: 2026-05-20` and uses native
`fetch`. OAuth is the recommended connection method because Tuturuuu can refresh
tokens and validate granted scopes. Manual access-token configuration remains
available for controlled deployments and does not require saved Square OAuth app
credentials.

## Configure Square

1. Create or open a Square application in the Square Developer Dashboard.

2. Configure the OAuth redirect URL:

   ```
   https://<your-tuturuuu-domain>/api/v1/inventory/square/oauth/callback
   ```

3. Grant these OAuth scopes:

   * `MERCHANT_PROFILE_READ`
   * `ORDERS_READ`
   * `ORDERS_WRITE`
   * `PAYMENTS_READ`
   * `PAYMENTS_WRITE`
   * `DEVICE_CREDENTIAL_MANAGEMENT`
   * `ITEMS_READ`
   * `ITEMS_WRITE`
   * `INVENTORY_READ`
   * `INVENTORY_WRITE`

4. Create a webhook subscription for the Inventory Square endpoint:

   ```
   https://<your-tuturuuu-domain>/api/v1/inventory/square/webhook/<workspace-id>
   ```

   Subscribe to these required events:

   * `device.code.paired`
   * `terminal.checkout.created`
   * `terminal.checkout.updated`
   * `payment.updated`
   * `oauth.authorization.revoked`
   * `catalog.version.updated`
   * `inventory.count.updated`

   `payment.created` can be added for additional delivery visibility, but
   `payment.updated` is the required payment-state signal in the customer setup
   checklist.

5. Copy the webhook signature key into **Inventory → Payments → Connect & set
   up → Square POS** for the matching environment.

For local development, expose `apps/web` with an HTTPS tunnel and either use the
tunnel URL in Square or save that exact URL as the workspace webhook
notification URL so signature validation uses the same value.

## Connect a workspace

1. Open **Inventory → Payments → Connect & set up → Square POS**. Configuration
   changes open in a three-tab dialog; incomplete checklist steps deep-link to
   the required tab.
2. Choose `Sandbox` or `Production`.
3. Save the Square Application ID and Application Secret for that environment.
   If Square is configured with a tunnel or canonical URL that differs from the
   actual request URL, also save the exact webhook notification URL so HMAC
   validation uses the same URL Square signed.
4. Prefer **Connect OAuth**. For manual setup, paste an access token and save it
   with the matching environment.
5. Save the webhook signature key for the same environment.
6. Select a Square location.
7. Pair or select a terminal:
   * Production: create a device pairing code, enter it on the physical Square
     Terminal within five minutes, then select the paired device. The pairing
     request uses Square's `TERMINAL_API` product type. Create this code inside
     Tuturuuu; device codes from Square Dashboard are not compatible with
     Terminal API pairing.
   * Sandbox: use Square's sandbox terminal device id when device listing is not
     available.
8. Set a storefront's checkout mode to `Square Terminal`.
9. In **Catalog and stock sync**, import from Square first in Sandbox. Review
   counts and conflicts, then rehearse publish and two-way sync. Repeat in
   Production only after confirming the selected seller and location.

Readiness fails closed until the connection, required scopes, webhook signature
key, location, device, and environment all match. OAuth-backed connections also
require saved workspace Square app credentials so refresh can continue without
deployment secrets. Storefront checkout returns a configuration error instead of
reserving stock when Square is not ready.

The verified Tuturuuu launch path requires reliable connectivity. Square lists
Terminal API offline payments as an opt-in beta capability, but Tuturuuu does
not currently certify or depend on that flow. Operators should restore the
network and reconcile any uncertain checkout before retrying.

## Runtime ownership and endpoints

The Inventory satellite owns the customer-facing Square routes and delegates
provider orchestration to `@tuturuuu/inventory-core`. Client components use
`@tuturuuu/internal-api`; they must not call provider APIs or private database
tables directly.

| Method and route                                                                       | Purpose                                                                                  |
| -------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
| `GET/PUT /api/v1/workspaces/:wsId/inventory/square-settings`                           | Read masked readiness state or save the workspace Square configuration                   |
| `GET /api/v1/workspaces/:wsId/inventory/square/oauth/start`                            | Start environment-bound OAuth                                                            |
| `GET /api/v1/inventory/square/oauth/callback`                                          | Exchange the authorization and return to Inventory                                       |
| `GET /api/v1/workspaces/:wsId/inventory/square/locations`                              | List locations for the connected seller                                                  |
| `GET /api/v1/workspaces/:wsId/inventory/square/devices`                                | List paired Production Terminal API devices                                              |
| `POST /api/v1/workspaces/:wsId/inventory/square/device-codes`                          | Create a five-minute `TERMINAL_API` pairing code                                         |
| `GET/POST /api/v1/workspaces/:wsId/inventory/square/catalog-sync`                      | Inspect links or run import, publish, or two-way sync                                    |
| `POST /api/v1/workspaces/:wsId/inventory/square/terminal-checkouts`                    | Dispatch one reserved checkout to Square                                                 |
| `POST /api/v1/workspaces/:wsId/inventory/square/terminal-checkouts/:checkoutId/cancel` | Cancel the same Square Terminal checkout and reconcile release                           |
| `POST /api/v1/inventory/square/webhook/:wsId`                                          | Verify and process workspace-scoped Square events                                        |
| `POST /api/v1/inventory/storefronts/:slug/checkouts`                                   | Reserve the cart and dispatch provider checkout when the Storefront uses Square Terminal |

The environment, workspace, seller connection, location, and device are checked
again server-side. A client-visible control is not an authorization boundary.

## State and idempotency boundaries

```mermaid theme={null}
flowchart TD
  A["Public cart validation"] --> B["Private reservation RPC"]
  B --> C["Square order with idempotency key"]
  C --> D["Terminal checkout with idempotency key"]
  D --> E["Signed Square webhooks"]
  E --> F{"Verified paid payment?"}
  F -->|"Yes"| G["Complete once, consume stock, book at most one sale"]
  F -->|"Cancel, fail, or expire"| H["Release once"]
```

Provider IDs have unique database indexes, webhook events carry Square event
IDs, and reconciliation routines are safe to call repeatedly. Never weaken
those constraints to make a duplicate test pass.

The local checkout is reserved for 15 minutes. The database expiry function is
service-role only, concurrency-safe, and invoked by a five-minute cron plus lazy
reconciliation on reads and new checkout creation. Terminal cancellation and
Square final-state webhooks use the same release/complete boundaries.

## Focused verification commands

Run the narrow Square contract suites before the wider repository gate:

```bash theme={null}
bun --filter @tuturuuu/inventory-core test

bun x vitest run \
  'apps/inventory/src/app/api/v1/inventory/square/webhook/[wsId]/route.test.ts' \
  'apps/inventory/src/app/api/v1/inventory/storefronts/[slug]/checkouts/route.test.ts' \
  'apps/inventory/src/app/api/v1/workspaces/[wsId]/inventory/square-settings/route.test.ts' \
  'apps/inventory/src/app/api/v1/workspaces/[wsId]/inventory/square/catalog-sync/route.test.ts' \
  'apps/inventory/src/app/api/v1/workspaces/[wsId]/inventory/square/terminal-checkouts/route.test.ts' \
  'apps/inventory/src/app/api/v1/workspaces/[wsId]/inventory/square/terminal-checkouts/[checkoutId]/cancel/route.test.ts' \
  'apps/inventory/src/app/api/cron/inventory/checkout-expiry/route.test.ts' \
  apps/inventory/src/components/operator/payments-readiness.test.ts \
  apps/inventory/src/components/operator/square-setup-progress.test.ts

bun --filter @tuturuuu/inventory type-check
bun check
```

When implementation routes or app dependencies change, also run the real
Inventory build as required by the repository operating manual:

```bash theme={null}
cd apps/inventory
bun run build
```

Do not treat a passing build as physical hardware certification. The customer
must still complete the Production smoke test below.

## Hardware-free verification

No mocked test can prove that a specific production countertop terminal is
online, paired to the right Square seller account, assigned to the selected
location, has a working network path, and can complete a real card-present
payment. Without hardware, treat the automated suite as Square contract and
reconciliation verification, not physical-device certification.

The no-hardware suite must cover these Square contracts before release:

* OAuth authorization URL, token exchange, refresh, scope parsing, encrypted
  storage, and secret redaction.
* REST base URLs for sandbox and production, `Square-Version`, bearer auth,
  sanitized upstream errors, and idempotency keys.
* Catalog search, additive Batch Upsert, unknown-variation preservation,
  two-sided hash conflict detection, deleted-object preservation, and physical
  inventory count payloads that never contain a delete instruction.
* Orders API payloads before Terminal checkout creation.
* Terminal checkout payloads with `order_id`,
  `device_options.device_id`, and `device_options.show_itemized_cart`.
* Device Code creation with `product_type: TERMINAL_API` and paired-device
  webhook reconciliation.
* Raw-body webhook HMAC validation against the exact Square notification URL
  before JSON parsing.
* Terminal checkout, payment, OAuth revocation, cancellation, expiry, failure,
  duplicate delivery, and event-id reconciliation behavior.
* Reservation-first lifecycle: create local reservation before Square calls,
  release on Square create/cancel/failure/expiry, and complete stock/ledger
  state only after verified Square payment success.
* Scheduled and lazy checkout-expiry reconciliation, including concurrent
  sweeper safety and service-role-only database access.

## Physical-terminal smoke checklist

Complete the simulator matrix in Sandbox first. Square does not pair real
hardware to Sandbox, so physical-device certification requires a separately
approved Production test with a low-value item and real card-present processing.
Do not promise that a refund also refunds every processing fee; the Square owner
must approve the store's refund plan.

1. Pair a terminal for the selected Square location.
2. Create a small Storefront order and confirm Inventory shows it as reserved.
3. Use Inventory commerce actions to send it to the terminal.
4. Complete the payment on the terminal.
5. Confirm Square webhook delivery succeeded and Tuturuuu marked the checkout
   completed with Square order, terminal checkout, payment, and receipt URL
   metadata.
6. Confirm stock reservations were consumed and the finance ledger sale was
   booked once.
7. Repeat cancel, expiry/failure, duplicate webhook delivery, and transient
   Square failure cases in Sandbox. Cancel/failure/expiry must release
   inventory. Do not repeat destructive Production failure tests unless the
   owner explicitly approves their real-money and operational effects.

Use the customer-facing
[Production launch gate](/platform/applications/inventory-square-pos/production-launch)
for the exact owner, operator, receipt, stock, and go/no-go checklist.

## Refund and dispute reconciliation

Square connections created before Inventory–Finance reconciliation may not
include `DISPUTES_READ`. Existing payment capture remains usable without that
scope. Ask the Square owner to reconnect OAuth during a planned maintenance
window before enabling dispute history synchronization.

Subscribe the configured Square webhook endpoint to:

* `refund.created`
* `refund.updated`
* `dispute.created`
* `dispute.state.updated`

Refunds are recorded only when Square reports them completed. Dispute creation
creates a negative chargeback hold; `WON` creates a positive release, while
`LOST` and `ACCEPTED` leave the hold final. Webhook retries update the same
provider source key and must never create duplicate ledger rows.

After deployment, use the Finance reconciliation provider-sync action in
bounded pages. It reads Square refund and dispute history but does not create,
accept, challenge, or otherwise mutate a Square dispute. Validate these flows
in Square Sandbox; do not create or capture Production payments merely to test
reconciliation.


# TanStack/Rust Cutover Runbook
Source: https://docs.tuturuuu.com/build/devops/tanstack-rust-cutover-runbook

Bring up, verify, and gate the dual-stack TanStack frontend and Rust backend before cutover.

This runbook is the discoverable docs copy of the root cutover runbook for the
TanStack Start plus Rust backend migration. It focuses on operational checks and
does not replace the route ownership contract at
`platform/architecture/tanstack-rust-migration`.

For how to start the native services, run the dual-stack Docker stack, deploy
the Workers, validate the Vercel TanStack frontend build, or expose a VPS
through Cloudflare Tunnel, use
[TanStack/Rust Local And Deployment](/build/devops/tanstack-rust-local-deploy).

## Purpose

Use this runbook when proving the new production target is ready:

* `apps/tanstack-web` serves the frontend.
* `apps/backend` serves Rust-owned backend routes.
* the dual stack runs from production Docker artifacts.
* compare mode proves the legacy and new frontend paths can pass the same smoke
  suite before traffic moves.

## Local Dual-Stack Commands

Validate the compose file without starting anything:

```bash theme={null}
docker compose -f docker-compose.tanstack-dual.yml config
```

Run the minimal dual-stack TanStack/Rust E2E suite:

```bash theme={null}
bun test:e2e:tanstack:docker -- -- --project=chromium
```

The command starts `docker-compose.tanstack-dual.yml`, waits for `backend-dual`
and `tanstack-web-dual` to become healthy, runs Playwright in
`apps/tanstack-web`, and tears the stack down unless `--keep-up` is passed to
the runner.

Run the focused compare smoke used by CI:

```bash theme={null}
bun test:e2e:web:docker:compare -- public-marketing-routes.noauth.spec.ts --project=chromium-no-auth
```

Run a broader compare rehearsal by omitting the spec filter, but expect a much
longer full-stack run:

```bash theme={null}
bun test:e2e:web:docker:compare -- --project=chromium-no-auth
```

## Services And Ports

`docker-compose.tanstack-dual.yml` exposes only loopback ports by default:

| Service           | Container           | Default port |
| ----------------- | ------------------- | -----------: |
| Rust backend      | `backend-dual`      |       `7820` |
| TanStack frontend | `tanstack-web-dual` |       `7824` |

The frontend healthcheck must prove the root page renders and can reach the
backend. Keep real secret values in ignored env files or CI secrets; docs and
workflow files should reference environment variable names only.

## CI Coverage

The E2E workflow includes a migration matrix:

* `tanstack-dual-stack` runs the minimal dual-stack compose runner against
  `apps/tanstack-web/e2e`.
* `compare-smoke` runs `scripts/run-web-e2e-docker.js --frontend compare`
  against a focused public no-auth spec.

Both jobs upload Playwright and `tmp/e2e` artifacts for failure triage.

## Evidence For Gates

The final cutover gate consumes fresh evidence reports:

```bash theme={null}
bun migration:tanstack:gates -- \
  --benchmark-report <path/to/benchmark-report.json> \
  --e2e-report <path/to/e2e-compare-report.json> \
  --cloudflare-smoke-report <path/to/cloudflare-smoke-report.json> \
  --output tmp/tanstack-cutover-gates.json
```

Use diagnostic mode while legacy routes remain:

```bash theme={null}
bun migration:tanstack:gates -- --allow-legacy --skip-benchmark --skip-e2e --skip-cloudflare-smoke
```

For terminal cutover, do not pass any `--skip-*` evidence flags.

## Final Checklist

* `bun migration:tanstack:cutover-check` passes with zero `legacy-next`
  artifacts.
* dual-stack Docker E2E passes against `docker-compose.tanstack-dual.yml`.
* compare-mode Docker E2E passes for both Next and TanStack frontends.
* benchmark compare evidence is fresh and within thresholds.
* Cloudflare smoke probes pass for backend and TanStack origins.
* `bun migration:tanstack:gates` exits `0` with all evidence present.
* final `bun check` passes or has only documented unrelated blockers.

Keep `apps/web` available as rollback fallback until the cutover window is
complete and the post-cutover smoke has stayed green.


# TanStack/Rust Local And Deployment
Source: https://docs.tuturuuu.com/build/devops/tanstack-rust-local-deploy

Run apps/backend and apps/tanstack-web locally, deploy to Cloudflare Workers, validate the Vercel build, and self-host with Docker plus Cloudflare Tunnel.

This is the operator runbook for the migration stack:

* `apps/backend`: Rust API runtime, native on port `7820`, Docker sidecar, and
  Cloudflare Worker `tuturuuu-backend`.
* `apps/tanstack-web`: TanStack Start frontend, local dev on port `7824`,
  Docker sidecar, Cloudflare Worker `tuturuuu-tanstack-web`, and opt-in Vercel
  build validation.

<Warning>
  This runbook describes future deployment capability. `apps/backend` is not
  currently deployed or used by production, and `apps/web` remains the live API
  runtime. Do not run the deployment sections or infer a cutover without
  explicit migration approval.
</Warning>

Keep the legacy `apps/web` runtime available until the cutover gates pass. This
page explains how to start, validate, and deploy the new stack; route ownership
and cutover evidence stay in the
[TanStack/Rust migration contract](/platform/architecture/tanstack-rust-migration)
and [cutover runbook](/build/devops/tanstack-rust-cutover-runbook).

## Required Environment

Use real values only in ignored env files, shell variables, GitHub Environment
secrets, Cloudflare Worker secrets, Vercel Project Environment Variables, or VPS
secret stores. Do not commit values.

| Variable                           | Used by                                                  | Notes                                                                                                      |
| ---------------------------------- | -------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| `BACKEND_INTERNAL_TOKEN`           | backend and frontend server runtime                      | Shared bearer token for internal migration/status calls.                                                   |
| `BACKEND_INTERNAL_URL`             | `apps/tanstack-web` outside Cloudflare service bindings  | Server-only backend origin, such as `http://localhost:7820` or an HTTPS backend Worker/VPS origin.         |
| `BACKEND_PUBLIC_ORIGIN`            | `apps/tanstack-web` browser-safe backend origin fallback | Public backend origin when the frontend needs a browser-safe base URL.                                     |
| `SUPABASE_URL`                     | backend Worker                                           | Server-side Supabase REST origin.                                                                          |
| `SUPABASE_SERVICE_ROLE_KEY`        | backend Worker                                           | Server-side Supabase service key.                                                                          |
| `TUTURUUU_APP_COORDINATION_SECRET` | backend Worker                                           | App coordination token verification.                                                                       |
| `CRON_SECRET`                      | backend Worker                                           | Cron proxy parity.                                                                                         |
| `DISCORD_APP_DEPLOYMENT_URL`       | backend Worker                                           | Discord app deployment proxy.                                                                              |
| `AURORA_EXTERNAL_URL`              | backend Worker                                           | Aurora health and ingest upstream.                                                                         |
| `AURORA_EXTERNAL_WSID`             | backend Worker                                           | Aurora ingest workspace id.                                                                                |
| `TANSTACK_WEB_RUNTIME`             | frontend build/runtime selection                         | Use `node` for Docker/node output, `vercel` for Vercel build validation, and unset for Cloudflare Workers. |

## Local Native Run

Native local development is two processes: Rust backend first, then TanStack
Start. `apps/backend/.env.example` is a template; the native Rust binary reads
environment variables from the process environment.

1. From the repo root, export local-only backend values:

   ```bash theme={null}
   export BACKEND_ENV=development
   export BACKEND_INTERNAL_TOKEN="<local-only shared token>"
   export PORT=7820
   ```

2. Start the Rust backend:

   ```bash theme={null}
   cargo run --manifest-path apps/backend/Cargo.toml --features native --bin backend
   ```

3. In another shell, point TanStack Start at the backend and start the frontend:

   ```bash theme={null}
   BACKEND_INTERNAL_TOKEN="${BACKEND_INTERNAL_TOKEN:?set BACKEND_INTERNAL_TOKEN}" \
   BACKEND_INTERNAL_URL=http://localhost:7820 \
   BACKEND_PUBLIC_ORIGIN=http://localhost:7820 \
   bun dev:tanstack-web
   ```

4. Verify the backend:

   ```bash theme={null}
   curl -fsS http://127.0.0.1:7820/healthz
   curl -fsS http://127.0.0.1:7820/readyz
   curl -fsS \
     -H "Authorization: Bearer ${BACKEND_INTERNAL_TOKEN:?set BACKEND_INTERNAL_TOKEN}" \
     http://127.0.0.1:7820/api/migration/status
   ```

5. Open the frontend on port `7824`. The root migration shell should report the
   backend as reachable when the URL and token match.

Common local failures:

* `readyz` is not ready: `BACKEND_INTERNAL_TOKEN` is missing from the backend
  process.
* TanStack shows backend unreachable: the frontend shell does not have
  `BACKEND_INTERNAL_URL` or `BACKEND_INTERNAL_TOKEN`, or the backend is running
  on a different port.
* Rust starts but route calls fail: the route may require additional Supabase,
  Aurora, Discord, cron, or app coordination env values.

## Docker Dual-Stack Rehearsal

Use the minimal dual-stack compose file when you want production artifacts for
only the migration stack:

```bash theme={null}
docker compose -f docker-compose.tanstack-dual.yml config
docker compose -f docker-compose.tanstack-dual.yml up -d --build
```

The default loopback ports are:

| Service           | Container           | Host URL                |
| ----------------- | ------------------- | ----------------------- |
| Rust backend      | `backend-dual`      | `http://127.0.0.1:7820` |
| TanStack frontend | `tanstack-web-dual` | `http://127.0.0.1:7824` |

Run the minimal Playwright E2E rehearsal:

```bash theme={null}
bun test:e2e:tanstack:docker -- -- --project=chromium
```

Keep the stack up for manual debugging:

```bash theme={null}
bun test:e2e:tanstack:docker -- --keep-up -- --project=chromium
```

Shut it down when finished:

```bash theme={null}
docker compose -f docker-compose.tanstack-dual.yml down
```

Use the broader production web Docker path when the migration stack needs to run
behind `web-proxy`, blue/green cutover, watcher recovery, Redis, cron, or
Cloudflare Tunnel. That path is covered in
[Web Docker Deployment](/build/devops/web-docker-deployment).

## Cloudflare Workers Deployment

Cloudflare Workers is the edge preview path for both runtimes. The frontend
Worker uses the `BACKEND` service binding to call the backend Worker first, with
HTTP env fallback only for local and emergency non-binding runs. This follows
the current TanStack Start Cloudflare guidance for
`@cloudflare/vite-plugin` plus `wrangler`.

1. Authenticate and validate config:

   ```bash theme={null}
   bun wrangler whoami
   bun check:cloudflare
   ```

2. Install Rust Worker prerequisites if the machine has not built Workers
   before:

   ```bash theme={null}
   rustup target add wasm32-unknown-unknown
   cargo install worker-build --locked
   ```

3. Bootstrap backend Worker secrets in Cloudflare:

   ```bash theme={null}
   bun wrangler secret put BACKEND_INTERNAL_TOKEN --config apps/backend/wrangler.jsonc
   bun wrangler secret put TUTURUUU_APP_COORDINATION_SECRET --config apps/backend/wrangler.jsonc
   bun wrangler secret put SUPABASE_URL --config apps/backend/wrangler.jsonc
   bun wrangler secret put SUPABASE_SERVICE_ROLE_KEY --config apps/backend/wrangler.jsonc
   bun wrangler secret put CRON_SECRET --config apps/backend/wrangler.jsonc
   bun wrangler secret put DISCORD_APP_DEPLOYMENT_URL --config apps/backend/wrangler.jsonc
   bun wrangler secret put AURORA_EXTERNAL_URL --config apps/backend/wrangler.jsonc
   bun wrangler secret put AURORA_EXTERNAL_WSID --config apps/backend/wrangler.jsonc
   ```

4. Deploy the backend Worker first:

   ```bash theme={null}
   bun wrangler deploy --config apps/backend/wrangler.jsonc
   ```

5. Bootstrap TanStack Worker secrets:

   ```bash theme={null}
   bun wrangler secret put BACKEND_PUBLIC_ORIGIN --config apps/tanstack-web/wrangler.jsonc
   bun wrangler secret put BACKEND_INTERNAL_TOKEN --config apps/tanstack-web/wrangler.jsonc
   ```

6. Generate Worker types and deploy the TanStack Worker:

   ```bash theme={null}
   bun --cwd apps/tanstack-web run cf-typegen
   bun --cwd apps/tanstack-web run deploy:cloudflare
   ```

7. Smoke both Worker origins:

   ```bash theme={null}
   BACKEND_INTERNAL_TOKEN="${BACKEND_INTERNAL_TOKEN:?set BACKEND_INTERNAL_TOKEN}" \
   BACKEND_WORKER_ORIGIN=https://<backend-worker-origin> \
   TANSTACK_WEB_WORKER_ORIGIN=https://<tanstack-worker-origin> \
   bun smoke:cloudflare
   ```

For secret rotation on an already serving Worker, prefer the versions flow:

```bash theme={null}
bun wrangler versions secret put BACKEND_INTERNAL_TOKEN --config apps/backend/wrangler.jsonc
bun wrangler versions deploy --config apps/backend/wrangler.jsonc
```

Rollback is Worker-version or route/DNS based:

```bash theme={null}
bun wrangler deployments list --config apps/backend/wrangler.jsonc
bun wrangler rollback <VERSION_ID> --config apps/backend/wrangler.jsonc
bun wrangler deployments list --config apps/tanstack-web/wrangler.jsonc
bun wrangler rollback <VERSION_ID> --config apps/tanstack-web/wrangler.jsonc
```

External references: [TanStack Start hosting](https://tanstack.com/start/v0/docs/framework/react/guide/hosting),
[Cloudflare TanStack Start](https://developers.cloudflare.com/workers/framework-guides/web-apps/tanstack-start/),
[Wrangler configuration](https://developers.cloudflare.com/workers/wrangler/configuration/),
and [Cloudflare Worker secrets](https://developers.cloudflare.com/workers/configuration/secrets/).

## Vercel Frontend Build Validation

Vercel is used to validate that `apps/tanstack-web` can produce Vercel-compatible
TanStack Start output. This repository does not deploy or publish the TanStack
frontend to Vercel. The Rust backend must still be reachable over HTTPS during
the build, usually through the Cloudflare backend Worker or a self-hosted
backend origin. Vercel mode uses the app-local
`TANSTACK_WEB_RUNTIME=vercel` branch and Nitro, matching the current Vercel
TanStack Start guidance.

Configure the Vercel project:

| Setting          | Value                                                                                |
| ---------------- | ------------------------------------------------------------------------------------ |
| Project root     | `apps/tanstack-web`                                                                  |
| Build command    | `bun run build:vercel`                                                               |
| Framework preset | Other, unless Vercel auto-detects the TanStack/Nitro output correctly                |
| Git integration  | Disabled by `apps/tanstack-web/vercel.json`; GitHub Actions runs `vercel build` only |

Required Vercel Project Environment Variables:

| Variable                               | Value source                                                             |
| -------------------------------------- | ------------------------------------------------------------------------ |
| `TANSTACK_WEB_RUNTIME`                 | `vercel`                                                                 |
| `BACKEND_PUBLIC_ORIGIN`                | HTTPS backend origin                                                     |
| `BACKEND_INTERNAL_URL`                 | Same HTTPS backend origin unless a separate private origin exists        |
| `BACKEND_INTERNAL_TOKEN`               | Same token configured on the backend                                     |
| `NEXT_PUBLIC_SUPABASE_URL`             | Supabase project URL, if the rendered routes need Supabase client config |
| `NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY` | Supabase publishable key, if routes need browser Supabase config         |

Manual CLI sequence from the repo root:

```bash theme={null}
bash scripts/ci/run-with-backoff.sh bun install
bash scripts/ci/run-with-backoff.sh bun install --global vercel@latest

VERCEL_ORG_ID="${VERCEL_ORG_ID:?set VERCEL_ORG_ID}" \
VERCEL_PROJECT_ID="${VERCEL_TANSTACK_WEB_PROJECT_ID:?set VERCEL_TANSTACK_WEB_PROJECT_ID}" \
vercel pull --yes --environment=preview --token="${VERCEL_TOKEN:?set VERCEL_TOKEN}"

TANSTACK_WEB_RUNTIME=vercel \
bun turbo:local run build '--filter=@tuturuuu/tanstack-web^...'

bun run --silent scripts/ci/generate-build-metadata.ts

TANSTACK_WEB_RUNTIME=vercel \
VERCEL_ORG_ID="${VERCEL_ORG_ID:?set VERCEL_ORG_ID}" \
VERCEL_PROJECT_ID="${VERCEL_TANSTACK_WEB_PROJECT_ID:?set VERCEL_TANSTACK_WEB_PROJECT_ID}" \
vercel build --token="${VERCEL_TOKEN:?set VERCEL_TOKEN}"
```

Production uses the same sequence with `vercel pull --environment=production`
and `vercel build --prod`. It intentionally does not run `vercel deploy`.

GitHub Actions owns the normal path:

* `.github/workflows/vercel-preview-tanstack-web.yaml`
* `.github/workflows/vercel-production-tanstack-web.yaml`

The workflows use `VERCEL_TANSTACK_WEB_PROJECT_ID`, `VERCEL_ORG_ID`, and
`VERCEL_TOKEN` inside the build jobs only. Preview builds require
`workflow_dispatch` from protected `main` plus a trusted actor. Production builds
run from the `production` branch. They record build markers after `vercel build`
passes and do not create Vercel deployments.

External references: [Vercel TanStack Start](https://vercel.com/docs/frameworks/full-stack/tanstack-start),
[vercel pull](https://vercel.com/docs/cli/pull),
[vercel build](https://vercel.com/docs/cli/build).

## VPS Or Self-Hosting With Cloudflare Tunnel

Self-hosting uses the existing production Docker stack. Use this when the full
platform proxy, blue/green deployment history, watcher recovery, and
Cloudflare Tunnel container should own traffic.

1. Prepare the server:

   ```bash theme={null}
   git clone https://github.com/tutur3u/platform.git tuturuuu
   cd tuturuuu
   bun install
   ```

2. Put production env values in root `.env.local` or an explicit deployment env
   file. Set the frontend selector and backend token:

   ```bash theme={null}
   DOCKER_WEB_FRONTEND=tanstack
   BACKEND_INTERNAL_TOKEN=<shared backend token>
   ```

3. If using Cloudflare Tunnel, create a remotely managed tunnel in Cloudflare
   Zero Trust, add a public hostname for the desired domain, and route it to:

   ```text theme={null}
   http://localhost:7803
   ```

   Store the tunnel token as `CF_TUNNEL_TOKEN`, `CLOUDFLARED_TOKEN`, or
   `DOCKER_CLOUDFLARED_TOKEN` in the server env file. The Docker helper maps
   `CF_TUNNEL_TOKEN` to the Compose `CLOUDFLARED_TOKEN`.

4. Start the TanStack production stack without a tunnel:

   ```bash theme={null}
   DOCKER_WEB_FRONTEND=tanstack bun serve:web:docker:bg
   ```

   Start it with the bundled Cloudflare Tunnel sidecar:

   ```bash theme={null}
   DOCKER_WEB_FRONTEND=tanstack bun serve:web:docker:bg -- --with-cloudflared
   ```

   A non-empty `CF_TUNNEL_TOKEN` in root `.env.local` also auto-enables the
   tunnel sidecar unless the Docker helper is explicitly opted out.

5. Verify through the local proxy:

   ```bash theme={null}
   curl -fsS http://127.0.0.1:7803/__platform/drain-status
   ```

6. Verify through the public hostname after Tunnel reports healthy:

   ```bash theme={null}
   curl -fsS https://<public-hostname>/
   ```

7. Stop the stack:

   ```bash theme={null}
   DOCKER_WEB_FRONTEND=tanstack bun serve:web:docker:bg:down
   ```

Rollback options:

* Blue/green: use the existing cached rollback path documented in
  [Web Docker Deployment](/build/devops/web-docker-deployment).
* Git: check out the previous known-good commit and rerun
  `DOCKER_WEB_FRONTEND=tanstack bun serve:web:docker:bg`.
* Tunnel: remove or change the Cloudflare public hostname route while the local
  stack is repaired.

External references: [Cloudflare Tunnel setup](https://developers.cloudflare.com/tunnel/setup/)
and [Cloudflare remote tunnel creation](https://developers.cloudflare.com/cloudflare-one/networks/connectors/cloudflare-tunnel/get-started/create-remote-tunnel/).

## Verification Checklist

Run these before handing off a local or deployment-config change:

```bash theme={null}
python3 -m json.tool apps/docs/docs.json apps/tanstack-web/vercel.json
node --test scripts/check-cloudflare-workers.test.js scripts/ci/check-workflow-config.test.js scripts/ci/release-workflows.test.js
bun check:cloudflare
bun type-check:tanstack-web
git diff --check
bun check
```

Do not run deploy commands, production Supabase pushes, or long build commands
from an implementation session unless the user explicitly requested live
deployment or build execution.


# Web Docker Deployment
Source: https://docs.tuturuuu.com/build/devops/web-docker-deployment

Run the web app in Docker for development, production, and blue/green self-hosted rollout.

This is the operational guide for the Docker-based `apps/web` runtime and the
parallel `apps/tanstack-web` migration runtime.

## Files That Define The Stack

* `apps/web/Dockerfile`
* `apps/web/docker/blue-green-watcher.Dockerfile`
* `apps/web/docker/cron-runner.Dockerfile`
* `apps/web/cron.config.json`
* `apps/tanstack-web/Dockerfile`
* `apps/backend/Dockerfile`
* `apps/meet-realtime/Dockerfile`
* `apps/supermemory/Dockerfile`
* `docker-compose.web.yml`
* `docker-compose.web.prod.yml` (Compose `include` entry that merges `docker-compose/compose.web.prod.*.yml` fragments plus shared `secrets` / `volumes`)
* `scripts/sync-web-crons.js`
* `scripts/watch-web-crons.js`
* `scripts/docker-web.js`
* `scripts/check-docker-web.js`

## Supported Commands

| Command                                    | Purpose                                                                                                                                                 |
| ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `bun dev:web:docker`                       | Run the web dev workflow inside Docker                                                                                                                  |
| `bun devx:web:docker`                      | Explicitly start local Supabase, then the Docker dev workflow                                                                                           |
| `bun devrs:web:docker`                     | Explicitly start and reset local Supabase, then the Docker dev workflow                                                                                 |
| `bun dev:web:docker:down`                  | Stop the Docker dev workflow                                                                                                                            |
| `bun serve:web:docker`                     | Build and run the production web image in-place                                                                                                         |
| `bun serve:web:docker:bg`                  | Blue/green production deploy with health-checked cutover                                                                                                |
| `bun serve:web:docker:bg:watch`            | Recreate the watcher container, then tail its live logs while it polls the tracked branch and auto-runs blue/green after a successful fast-forward pull |
| `bun serve:web:docker:down`                | Stop the production Docker stack                                                                                                                        |
| `bun serve:web:docker:bg:down`             | Stop the blue/green stack and clear local runtime state                                                                                                 |
| `bun test:e2e` / `bun test:e2e:web:docker` | Start local Supabase, reset it, run the production blue/green Docker web stack, then run Playwright                                                     |
| `bun benchmark:web-setups`                 | Compare reachable Next.js, TanStack Start, and Rust backend routes and write reports under `tmp/benchmarks/web-migration/`                              |
| `bun migration:tanstack:gates`             | Validate route parity, Docker E2E evidence, and benchmark evidence before TanStack/Rust cutover                                                         |
| `bun check:docker`                         | Validate Dockerfile and compose parity rules                                                                                                            |
| `bun check:cloudflare`                     | Validate TanStack Start and Rust backend Wrangler deploy configs without contacting Cloudflare                                                          |

## Flags And Implicit Mappings

| Flag                                                | Meaning                                                                                     |
| --------------------------------------------------- | ------------------------------------------------------------------------------------------- |
| `--without-redis`                                   | Disable the bundled Redis profile and skip Docker-injected Redis env                        |
| `--with-cloudflared`                                | Enable the bundled Cloudflare Tunnel container profile                                      |
| `--with-supabase`                                   | Start local Supabase before the Docker web flow                                             |
| `--reset-supabase`                                  | Start and reset local Supabase before the Docker web flow                                   |
| `--env-file tmp/e2e/web.env`                        | Use an explicit Docker web env file for build secrets and runtime env files                 |
| `--mode prod`                                       | Use the production compose file instead of the dev stack                                    |
| `--strategy blue-green`                             | Use blue/green production deployment instead of in-place replacement                        |
| `--profile redis`                                   | Explicitly enable the Redis profile when calling the helper directly                        |
| `--profile cloudflared`                             | Explicitly enable the Cloudflare Tunnel profile when calling the helper directly            |
| `--build-memory 4g`                                 | Run builds through a capped Buildx builder with a memory ceiling                            |
| `--build-cpus 4`                                    | Run builds through a capped Buildx builder with an approximate CPU limit                    |
| `--build-max-parallelism 2`                         | Limit concurrent BuildKit solve steps for lower build pressure                              |
| `--build-builder-name tuturuuu`                     | Override the throttled Buildx builder name                                                  |
| `--resume-if-running`                               | If another watcher PID already holds the lock, mirror its live dashboard instead of failing |
| `--replace-existing`                                | If another watcher PID already holds the lock, stop it and take over                        |
| `--if-locked &lt;fail&#124;resume&#124;replace&gt;` | Explicit lock-conflict policy for the watcher                                               |

| Command                                 | Implicit flags                      |
| --------------------------------------- | ----------------------------------- |
| `bun dev:web:docker`                    | none                                |
| `bun devx:web:docker`                   | `--with-supabase`                   |
| `bun devrs:web:docker`                  | `--reset-supabase`                  |
| `bun serve:web:docker`                  | `--mode prod`                       |
| `bun serve:web:docker:bg`               | `--mode prod --strategy blue-green` |
| `bun dev:web:docker -- --without-redis` | `--without-redis`                   |

## Runtime Requirements

* `.env.local` should be the primary Docker env file. The helper still falls back to `apps/web/.env.local` for older hosts that have not moved their env yet.
* When `--env-file` is provided, the Docker helper uses that file for the
  Dockerfile secret and for the Compose runtime `env_file` entries. This keeps
  special-purpose runs such as E2E from accidentally inheriting a developer's
  cloud Supabase `.env.local`.
* Production Compose fragments live under `docker-compose/`, so their relative
  host paths must be written from that directory. Use `..` to reach the repo
  root for build contexts, env files, and bind mounts; otherwise Docker Compose
  resolves paths like `apps/...` as `docker-compose/apps/...` and the watcher
  image fails before the deployment loop starts.
* Docker BuildKit must be available. The helper sets
  `COMPOSE_DOCKER_CLI_BUILD=1`, `DOCKER_BUILDKIT=1`, and
  `BUILDX_NO_DEFAULT_ATTESTATIONS=1` so local blue/green image exports do not
  stall while resolving default provenance metadata.
* Web, Hive, and TanStack Docker builder stages mount `/workspace/.turbo` so
  local Turbo hits survive across Docker builds. They also read optional
  BuildKit secrets named `turbo_token`, `turbo_team`, `turbo_api`, and
  `turbo_remote_cache_signature_key` only for build `RUN` steps. When those
  secrets are absent, builds fall back to the mounted local cache.
* GitHub-hosted Docker verification and E2E use service-specific `type=gha`
  BuildKit scopes so the same backend or frontend layers can be reused across
  workflows. Every shard may restore. Only shard 1 on the default branch may
  export a true miss, with a bounded timeout and `ignore-error=true`, preventing
  parallel shards from competing to save the same scope. Use `mode=max` for the
  expensive web, TanStack, and backend scopes; use `mode=min` or restore-only
  caching for small leaf services.
* Manual `docker buildx` and Compose invocations do not receive the GitHub cache
  runtime variables automatically. Every CI job that uses `type=gha` outside
  `docker/build-push-action` must first run the pinned
  `crazy-max/ghaction-github-runtime` step so `ACTIONS_RUNTIME_TOKEN` and
  `ACTIONS_RESULTS_URL` are available to BuildKit. Keep the action pinned to a
  full commit SHA and covered by the CI cache-policy tests.
* Forward GitHub remote-cache identity to Docker only with BuildKit `--secret`
  mounts. Never pass Turbo tokens as build arguments, Compose environment baked
  into an image, labels, or files copied into a layer. Pull requests and
  Dependabot builds receive no remote token and continue with local BuildKit and
  Turbo fallback behavior.
* The production and TanStack-dual Compose files accept restore entries through
  `DOCKER_WEB_CACHE_<SERVICE>_FROM` and optional exporter entries through the
  matching `_TO` variable. Supported service tokens are `WEB`, `TANSTACK`,
  `BACKEND`, `HIVE`, `SUPERMEMORY`, `MARKITDOWN`, `STORAGE_UNZIP`,
  `CHAT_REALTIME`, `HIVE_REALTIME`, and `MEET_REALTIME`. CI configures shared
  `type=gha` scopes; local operators normally leave these variables unset.
* `DOCKER_WEB_TURBO_TEAM_SECRET_FILE` and
  `DOCKER_WEB_TURBO_TOKEN_SECRET_FILE` point Compose at short-lived files used
  as BuildKit secrets. With no configured credentials they resolve to the
  committed zero-byte `docker-compose/empty-secret`, so local and cross-platform
  Compose parsing remains inert. Never put a token in that placeholder.
* Rust backend cache cleanup is local maintenance, not a separate cache service.
  `bun rust-cache report` prints current `apps/backend/target` usage,
  `bun rust-cache prune --apply` removes stale or oversized target entries, and
  `bun rust-cache auto` runs at most once every 24 hours by default using
  `tmp/rust-cache/state.json`. The default policy is local-only, skips CI,
  keeps target entries newer than 14 days when possible, and starts pruning when
  the repo-owned target cache exceeds 20 GiB.
* The dependency stages in `apps/web/Dockerfile`, `apps/hive/Dockerfile`,
  `apps/hive-realtime/Dockerfile`, `apps/meet-realtime/Dockerfile`,
  `apps/chat-realtime/Dockerfile`, and `apps/supermemory/Dockerfile` must copy
  every `apps/*/package.json` and `packages/*/package.json` manifest before
  running any frozen Bun install. Filtered Bun installs in these production
  images are retry-wrapped and clear the Bun install cache before retry; keep
  those snippets in sync with `scripts/check-docker-web.js`. Adding a new
  workspace app or package without updating those lists makes Docker-only
  installs try to rewrite `bun.lock`. `bun check:docker` validates this manifest
  parity. `apps/backend` is an independent Rust crate, and `apps/meet-realtime`
  is intentionally not a workspace package; their Dockerfiles do not require
  `bun.lock` changes when service source changes.
* The Docker web flow does not start local Supabase unless you explicitly choose `bun devx:web:docker` or `bun devrs:web:docker`.
* Production Docker serving commands (`bun serve:web:docker`, `bun serve:web:docker:bg`, and `bun serve:web:docker:bg:watch`) prefer root `.env.local` when it exists, even if the shell inherited stale `DOCKER_WEB_ENV_FILE` or `DOCKER_WEB_COMPOSE_*ENV_FILE` values. Passing `--env-file <path>` is the explicit way to use another deployment env file.
* `ttr box setup` intentionally writes local Supabase values into app-local env files such as `apps/web/.env.local`. Those files are valid for devbox/local work but must not be the effective production watcher env. Keep root `.env.local` or the explicit deployment env file pointed at the cloud Supabase project.
* Production Docker serving refuses local Supabase origins (`localhost`, `127.0.0.1`, `::1`, `host.docker.internal`, and local Supabase ports) unless `DOCKER_WEB_ALLOW_LOCAL_SUPABASE=1` is set for a local production-image rehearsal.
* `log-drain-postgres` stores deployment telemetry only. Production startup
  explicitly starts it from `scripts/docker-web.js` and retries once after
  removing only the service container, but web and watcher services do not
  declare a Compose `depends_on` relationship to it. An unhealthy log-drain
  database no longer blocks web promotion by default: the helper continues with
  `PLATFORM_LOG_DRAIN_ENABLED=false`, prints recent service state/log
  diagnostics, and leaves the `platform-log-drain-postgres` volume intact. Set
  `DOCKER_WEB_LOG_DRAIN_REQUIRED=1` only when telemetry storage must be a hard
  promotion gate. If diagnostics mention incompatible database files or data
  directory corruption, back up or migrate the Compose volume first; do not run
  `docker compose down --volumes` or remove the volume without explicit
  operator approval.
* Non-production Docker helpers still rewrite an explicitly local server-side Supabase URL to `host.docker.internal` while leaving `NEXT_PUBLIC_SUPABASE_URL` alone for browsers.
* Dockerized web services set `__NEXT_PRIVATE_ORIGIN` from
  `DOCKER_WEB_NEXT_PRIVATE_ORIGIN`, defaulting to
  `http://127.0.0.1:7803`. This keeps Next.js Server Action forwarding on the
  in-container web listener even when nginx preserves an external `Host`.
  If logs show `failed to forward action response` or
  `UND_ERR_HEADERS_TIMEOUT`, verify the running web container has
  `__NEXT_PRIVATE_ORIGIN=http://127.0.0.1:7803` or an intentional internal
  override. Do not use `serverActions.allowedOrigins` as the primary fix for
  this symptom; that setting controls Server Action origin/host validation, not
  the forwarded-action fetch URL.
* If logs still show `Error checking if workspace is personal` with `[locale]`,
  verify the running image includes commit `b30d7e2b07` or newer plus the shared
  `@tuturuuu/utils` UUID guard.
* Dockerized web commands auto-enable the local Redis companion stack and inject `UPSTASH_REDIS_REST_URL` plus a generated `UPSTASH_REDIS_REST_TOKEN` into the web container.
* Dockerized production commands generate `BACKEND_INTERNAL_TOKEN` when one is
  not provided and inject `BACKEND_INTERNAL_URL=http://backend:7820` for the
  Rust backend service. Dev Compose uses the same internal URL with a local
  fallback token. The same Rust HTTP core is prepared for later Cloudflare
  Workers deployment through `apps/backend/wrangler.jsonc`; validate the Worker
  deploy contract with `bun check:cloudflare`.
* `apps/backend/Dockerfile` copies
  `apps/tanstack-web/migration/route-manifest.json` before `cargo build`
  because the Rust migration endpoints include that checked manifest at compile
  time. Regenerate the manifest before Docker validation when legacy route
  inventory changes.
* The TanStack migration services use `apps/tanstack-web/Dockerfile`, direct
  host port `7824`, and the Portless browser origin
  `https://tanstack.tuturuuu.localhost:1355`.
  Production Compose defines `tanstack-web`, `tanstack-web-blue`, and
  `tanstack-web-green` so benchmark and cutover checks can run beside the
  legacy Next.js lanes. Docker web E2E aliases the TanStack Portless route to
  the `web-proxy` host port `7803` in `DOCKER_WEB_FRONTEND=tanstack` mode,
  because the blue/green TanStack lanes are exposed through nginx rather than
  the standalone `tanstack-web` host port. Production TanStack services wait on
  the Rust
  backend `service_healthy` check before starting, because the Start runtime
  uses `BACKEND_INTERNAL_URL=http://backend:7820` for server-owned API calls.
  The TanStack image and production Compose healthchecks run
  `apps/tanstack-web/docker/healthcheck.mjs`, which requires the local
  TanStack HTTP runner to answer below `500` and the configured
  `BACKEND_INTERNAL_URL` to pass `/healthz`. The TanStack Node runner also
  answers `/__platform/drain-status` directly so the shared nginx
  `web-proxy` healthcheck can use the same internal readiness path in
  `DOCKER_WEB_FRONTEND=tanstack` mode. Host-side Docker E2E readiness probes
  the TanStack root route instead, because nginx denies external access to the
  internal drain-status path.
  Use `DOCKER_WEB_FRONTEND=next|tanstack` to select the default web frontend in
  migration-aware scripts. The default is still `next`; setting `tanstack`
  keeps nginx on the public `web-proxy:7803` listener but routes the active
  upstream to `tanstack-web-blue:7824` or `tanstack-web-green:7824`. Set the
  variable in the host/root deployment env before creating
  `web-blue-green-watcher`, `web-docker-control`, or `web-cron-runner`, because
  those containers inherit it for status probes, cached recovery, and service
  recreation. Cloudflare
  preview deploys use
  `apps/tanstack-web/wrangler.jsonc` plus the app-local
  `deploy:cloudflare`, `deploy:cloudflare:dry-run`, `preview:cloudflare`, and
  `cf-typegen` scripts, so incremental TanStack route ports can be validated on
  Workers before the full cutover gate passes.
* Cloudflare preview deployment is separate from the Docker blue/green
  production stack. Use it to prove Worker compatibility for
  `apps/tanstack-web` and `apps/backend`; do not route the production hostname
  to preview Workers until the TanStack/Rust manifest, compare-mode Docker E2E,
  benchmark report, and cutover gates pass.
* The production stack runs the first-party AI memory sidecar as an internal
  support service at `http://supermemory:8787`. The service name and
  `SUPERMEMORY_*` env names stay compatible with existing web runtime wiring,
  but `apps/supermemory/Dockerfile` builds Tuturuuu-owned pgvector memory code.
* Dockerized production commands auto-configure the memory sidecar unless explicitly
  disabled. `scripts/docker-web/env.js` generates and persists the internal
  `SUPERMEMORY_API_KEY`, `SUPERMEMORY_POSTGRES_PASSWORD`, and
  `SUPERMEMORY_DATABASE_URL`, and defaults `SUPERMEMORY_ENABLED=true`,
  `SUPERMEMORY_FAIL_OPEN=true`, and
  `SUPERMEMORY_TIMEOUT_MS=1500`.
* Operators can override generated values with `DOCKER_SUPERMEMORY_API_KEY`,
  `DOCKER_SUPERMEMORY_POSTGRES_PASSWORD`,
  `DOCKER_SUPERMEMORY_DATABASE_URL`,
  or `DOCKER_SUPERMEMORY_ENABLED`; standard `SUPERMEMORY_*` env still works.
* Blue/green promotion health-gates `supermemory` with the rest of the support
  services. Changing `apps/supermemory/`, the production Compose fragments, or
  the Docker bake file refreshes the support service set.
  Explicit `SUPERMEMORY_ENABLED=false` or `DOCKER_SUPERMEMORY_ENABLED=false`
  removes that support service from blue/green builds, starts, and health gates
  for local-only runs.

## Cloudflare Preview Path

Docker remains the production rollout and rollback mechanism while the
TanStack/Rust migration is incomplete. Cloudflare Workers are available now for
incremental preview validation:

1. Run the config preflight without contacting Cloudflare:

   ```bash theme={null}
   bun check:cloudflare
   ```

   Keep local Worker secret values in `apps/backend/.dev.vars` and
   `apps/tanstack-web/.dev.vars`; those files are ignored by `.gitignore`.
   `wrangler.jsonc` may name required secrets, but it must not contain secret
   values or account-specific private origins.

2. Deploy the Rust backend Worker first:

   ```bash theme={null}
   rustup target add wasm32-unknown-unknown
   cargo install worker-build --locked
   bun wrangler secret put BACKEND_INTERNAL_TOKEN --config apps/backend/wrangler.jsonc
   bun wrangler secret put TUTURUUU_APP_COORDINATION_SECRET --config apps/backend/wrangler.jsonc
   bun wrangler secret put SUPABASE_URL --config apps/backend/wrangler.jsonc
   bun wrangler secret put SUPABASE_SERVICE_ROLE_KEY --config apps/backend/wrangler.jsonc
   bun wrangler secret put CRON_SECRET --config apps/backend/wrangler.jsonc
   bun wrangler secret put DISCORD_APP_DEPLOYMENT_URL --config apps/backend/wrangler.jsonc
   bun wrangler secret put AURORA_EXTERNAL_URL --config apps/backend/wrangler.jsonc
   bun wrangler secret put AURORA_EXTERNAL_WSID --config apps/backend/wrangler.jsonc
   bun wrangler deploy --config apps/backend/wrangler.jsonc
   ```

   `SUPABASE_URL` and `SUPABASE_SERVICE_ROLE_KEY` are required for the
   Rust-owned contact/profile APIs. The backend uses them only server-side to
   read `users` and `user_private_details` and insert `support_inquiries`
   through Supabase REST.
   `CRON_SECRET` and `DISCORD_APP_DEPLOYMENT_URL` are required for Rust-owned
   Discord cron proxy preview readiness, and `AURORA_EXTERNAL_URL` with
   `AURORA_EXTERNAL_WSID` is required for the Rust-owned Aurora health and
   ingest probes; configure them even when the first smoke target is only
   `/healthz`.

   Use `wrangler secret put` for first preview bootstrap only. It creates and
   deploys a new active Worker version when the secret changes. For rotations or
   canary traffic, use:

   ```bash theme={null}
   bun wrangler versions secret put BACKEND_INTERNAL_TOKEN --config apps/backend/wrangler.jsonc
   bun wrangler versions secret put TUTURUUU_APP_COORDINATION_SECRET --config apps/backend/wrangler.jsonc
   bun wrangler versions secret put SUPABASE_URL --config apps/backend/wrangler.jsonc
   bun wrangler versions secret put SUPABASE_SERVICE_ROLE_KEY --config apps/backend/wrangler.jsonc
   bun wrangler versions secret put CRON_SECRET --config apps/backend/wrangler.jsonc
   bun wrangler versions secret put DISCORD_APP_DEPLOYMENT_URL --config apps/backend/wrangler.jsonc
   bun wrangler versions secret put AURORA_EXTERNAL_URL --config apps/backend/wrangler.jsonc
   bun wrangler versions secret put AURORA_EXTERNAL_WSID --config apps/backend/wrangler.jsonc
   bun wrangler versions deploy --config apps/backend/wrangler.jsonc
   ```

3. Bind the TanStack Worker to the backend Worker by service binding and keep
   secret values out of source. `apps/tanstack-web/wrangler.jsonc` declares the
   `BACKEND` service binding to `tuturuuu-backend`; `BACKEND_INTERNAL_URL` is
   only an optional HTTP fallback for local or emergency non-binding runs:

   ```bash theme={null}
   bun wrangler secret put BACKEND_PUBLIC_ORIGIN --config apps/tanstack-web/wrangler.jsonc
   bun wrangler secret put BACKEND_INTERNAL_TOKEN --config apps/tanstack-web/wrangler.jsonc
   ```

   Use the versions flow for TanStack Worker secret rotations too:

   ```bash theme={null}
   bun wrangler versions secret put BACKEND_PUBLIC_ORIGIN --config apps/tanstack-web/wrangler.jsonc
   bun wrangler versions secret put BACKEND_INTERNAL_TOKEN --config apps/tanstack-web/wrangler.jsonc
   bun wrangler versions deploy --config apps/tanstack-web/wrangler.jsonc
   ```

4. Deploy the TanStack Start Worker:

   ```bash theme={null}
   bun --cwd apps/tanstack-web run cf-typegen
   bun --cwd apps/tanstack-web run deploy:cloudflare
   ```

5. Smoke both returned Worker origins:

   ```bash theme={null}
   BACKEND_INTERNAL_TOKEN="${BACKEND_INTERNAL_TOKEN:?set BACKEND_INTERNAL_TOKEN}" \
   BACKEND_WORKER_ORIGIN=https://<backend-worker-origin> \
   TANSTACK_WEB_WORKER_ORIGIN=https://<tanstack-worker-origin> \
   bun smoke:cloudflare
   ```

   Keep `BACKEND_INTERNAL_TOKEN` in the shell, ignored local env, or Wrangler
   secret storage only. The smoke report must include the positive authenticated
   migration-status probe and the missing/invalid-token rejection probes before
   the Cloudflare cutover gate can pass.

Security expectations for this path:

* Keep `BACKEND_INTERNAL_TOKEN`, backend origins, and future service credentials
  in Wrangler/Cloudflare bindings or ignored local env only. `wrangler.jsonc`
  may list variable names and non-secret preview defaults, never secret values.
* Browser code must not receive backend bearer tokens. Protected workspace,
  private schema, cron, job, and admin routes stay server-owned through Rust
  endpoints and `packages/internal-api` / TanStack server functions.
* Re-check CORS, cookie domain, secure-cookie, `SameSite`, and session-origin
  behavior before adding a custom hostname; `workers.dev`, local Portless, and
  production hosts are different browser origins.
* Keep Cloudflare preview in `BACKEND_ENV=preview`; development-only migration
  bypasses are local-only.

Rollback from this preview path is DNS/routing-based: remove the Cloudflare
route or custom domain that points at the preview Worker, or redeploy the last
known-good Worker version, while the Docker blue/green `apps/web` production
stack keeps serving the canonical hostname. Do not delete Worker secrets unless
the secret value is compromised. Use Wrangler to inspect and roll back preview
Worker versions:

```bash theme={null}
bun wrangler deployments list --config apps/backend/wrangler.jsonc
bun wrangler deployments status --config apps/backend/wrangler.jsonc
bun wrangler rollback <VERSION_ID> --config apps/backend/wrangler.jsonc

bun wrangler deployments list --config apps/tanstack-web/wrangler.jsonc
bun wrangler deployments status --config apps/tanstack-web/wrangler.jsonc
bun wrangler rollback <VERSION_ID> --config apps/tanstack-web/wrangler.jsonc
```

Worker rollback does not revert external resources, bindings, routes, custom
domains, or secret values. Re-run `bun smoke:cloudflare` against the remaining
preview origins before resuming canary traffic.

## Dockerized E2E

`bun test:e2e` from the repo root and `bun test:e2e` in `apps/web` run through
`scripts/run-web-e2e-docker.js` instead of starting `next dev`. The runner:

1. writes `tmp/e2e/web.env` with local-only Supabase, local app-origin
   variables, app-session JWT values, and a local-only E2E auth bypass for
   Turnstile/dev-session,
2. starts and resets the Dockerized local Supabase stack,
3. boots `apps/web` through the production blue/green Docker flow,
4. starts Portless on unprivileged HTTPS port `1355` and registers the
   `https://tuturuuu.localhost:1355` route only after the direct Docker proxy is
   healthy,
5. waits for `https://tuturuuu.localhost:1355/login`, then runs Playwright
   against that shared-cookie origin, and
6. tears down Docker web plus local Supabase unless `E2E_KEEP_DOCKER_STACK=1`.

Full web E2E runs also start satellite apps on their native ports when the
selected Playwright tests exercise routes those apps own. The runner currently
registers Tasks, Forms, and Infrastructure as
`https://<app>.tuturuuu.localhost:1355` routes through the shared Portless proxy
and waits for each app on its direct loopback port before Playwright begins.
The direct readiness probe avoids trusting local TLS in the Node runner, while
the browser still exercises the shared HTTPS origins. This lets cross-app
scenarios use the same Apps picker, token exchange, shared-session cookie, and
satellite UI that users operate, while direct API coverage reaches the app that
actually owns the route.

Before starting a satellite, the runner builds its compiled workspace
dependencies so a fresh CI checkout matches a prepared local checkout. For
sharded runs, it asks Playwright which tests belong to the current shard and
starts only the satellites required by that shard, so suite redistribution
cannot strand a spec or make unrelated shards pay the startup cost. Set the
matching `E2E_TASKS_SATELLITE_ENABLED`, `E2E_FORMS_SATELLITE_ENABLED`, or
`E2E_INFRASTRUCTURE_SATELLITE_ENABLED` variable to `0` only when a focused local
run cannot reach that satellite and does not exercise its routes.

Pass `--frontend next`, `--frontend tanstack`, or `--frontend compare` to select
the legacy Next.js host, the TanStack host, or both sequentially:

```bash theme={null}
bun test:e2e:web:docker -- --frontend compare
```

The TanStack mode reuses the existing `apps/web/e2e` suite and points Playwright
at `https://tanstack.tuturuuu.localhost:1355`. In Docker web E2E, that Portless
host points at the `web-proxy` host port because the runner validates the
production blue/green TanStack lane selected by `DOCKER_WEB_FRONTEND=tanstack`.
Standalone TanStack checks such as `docker-compose.tanstack-dual.yml` still use
the direct TanStack Docker port `7824`.

Compare mode writes `tmp/e2e/web-migration/compare-report.json` after both
frontend runs complete. Set `E2E_COMPARE_REPORT_PATH` to redirect that evidence
file under another ignored `tmp/` location. The report records the normalized
Next and TanStack frontend origins used by the run plus per-frontend Playwright
test counts from JSON reporter output. The cutover gate rejects missing,
credentialed, invalid, or same-origin compare evidence, and it also rejects
reports that do not prove nonzero Playwright execution for both frontends before
they can satisfy terminal migration gates.

Before cutover, pair the compare-mode E2E evidence with a full benchmark report
and Cloudflare smoke report:

```bash theme={null}
BACKEND_INTERNAL_TOKEN="${BACKEND_INTERNAL_TOKEN:?set BACKEND_INTERNAL_TOKEN}" \
bun benchmark:web-setups -- \
  --setup compare \
  --profile full \
  --require-all \
  --next-origin https://<legacy-next-origin> \
  --tanstack-origin https://<tanstack-worker-origin> \
  --backend-origin https://<backend-worker-origin>
```

The benchmark report is cutover evidence, so the origins are part of the gate.
The benchmark command rejects same-origin Next/TanStack compare runs, and the
cutover gate rejects reports with missing origins or route/sample URLs that do
not match the recorded setup origin. This catches accidental proxy reuse before
the report can satisfy migration gates.

```bash theme={null}
bun migration:tanstack:gates -- \
  --e2e-report tmp/e2e/web-migration/compare-report.json \
  --benchmark-report tmp/benchmarks/web-migration/<timestamp>/report.json \
  --cloudflare-smoke-report tmp/benchmarks/web-migration/<timestamp>/cloudflare-smoke.json \
  --output tmp/benchmarks/web-migration/<timestamp>/cutover-gates.json
```

The gate command does not start Docker. It only validates explicit report files
so generated evidence remains under ignored `tmp/` paths. The output JSON is the
review/handoff artifact that links the Docker E2E, benchmark, and Cloudflare
smoke evidence for sign-off without committing generated reports.

Normal teardown passes `--volumes --rmi local` to Docker Compose and then removes
custom image tags for the current `ttr-e2e-*` project, so per-run containers,
Compose volumes, and baked blue/green images do not accumulate. E2E also sets
`DOCKER_WEB_BUILDKIT_PRUNE_AFTER_BUILD=1` and
`DOCKER_WEB_BUILDKIT_PRUNE_MODE=all` by default because the per-run BuildKit
cache/state is disposable; set `E2E_DOCKER_BUILDKIT_PRUNE_AFTER_BUILD=0` only
when debugging a local E2E build and you intentionally want to keep BuildKit
cache.
Local E2E also starts Supabase with `edge-runtime` excluded by default through
`DOCKER_WEB_SUPABASE_START_EXCLUDE=edge-runtime`. The platform E2E suite does not
serve local Edge Functions, and excluding that service keeps local runs from
failing when the Supabase Edge Runtime tries to resolve external JSR packages.
Set `E2E_SUPABASE_START_EXCLUDE=` when you intentionally need a full local
Supabase stack for debugging.
Local E2E also pins `DOCKER_SUPERMEMORY_ENABLED=false` and
`SUPERMEMORY_ENABLED=false`; the memory integration is not under test there.
E2E build caps default to `auto` for memory, CPU, and BuildKit max parallelism.
The runner reads Docker's current `MemTotal` before booting the stack, forwards
that value as `DOCKER_WEB_DOCKER_MEMORY_LIMIT`, and resolves the BuildKit memory
cap just under the active Docker Desktop allocation. On allocations below 10 GB,
the E2E runner keeps the inner Next build at one CPU, static generation
concurrency one, and a 4 GB Node heap so BuildKit keeps enough container
headroom. The Next build engine remains Turbopack. Do not switch local E2E runs
to the Webpack build path; the production and local Docker build paths are
expected to exercise the same Turbopack compiler.

For blue/green web deploys, the helper defaults to the Docker/BuildKit web image
build path so production builds keep their container isolation boundary. Set
`DOCKER_WEB_NATIVE_BUILD=1` only for an explicit operator-approved native host
build. That opt-in runs `bun run build:web:docker` on the host with
`DOCKER_WEB_STANDALONE=1`, packages `apps/web/.next/standalone` plus static
assets into the same Node runtime image shape, and continues with Docker Compose
startup and Playwright. Native builds derive their host-side build memory budget
from the machine's total memory, while leaving Next/Turbopack CPU and static
generation worker counts unset so the toolchain can auto-configure from the real
host. Set `DOCKER_WEB_NATIVE_BUILD_MEMORY=16g` or another explicit value only
when the host needs a different Node heap bucket. Native runner packaging uses
plain `docker build` by default so a remote BuildKit transport failure does not
block the host-built artifact path. It also strips builder-routing env such as
`BUILDX_BUILDER` for that packaging subprocess; set
`DOCKER_WEB_NATIVE_RUNNER_BUILDX=1` only when that packaging step must use the
configured buildx builder. Native mode skips support-service image builds by
default and reuses the existing support images; set
`DOCKER_WEB_NATIVE_SUPPORT_BUILD=1` to build support images locally with
`docker compose build`, or `DOCKER_WEB_NATIVE_SUPPORT_BUILDX=1` when those
support builds should use the configured buildx builder.

When a production blue/green web image was just built locally with
`bun serve:web:docker:bg`, Dockerized E2E can reuse that image instead of
building `apps/web` again:

```bash theme={null}
E2E_DOCKER_REUSE_WEB_IMAGE=1 bun test:e2e:web:docker -- e2e/multi-account.noauth.spec.ts --project=chromium-no-auth
```

The runner reads `tmp/docker-web/prod/active-color` and retags the matching
`tuturuuu-web-<color>` image into the isolated `ttr-e2e-*` Compose project for
both `web-blue` and `web-green`, then skips the web build stage. When the same
local blue/green build also left the support images behind, the runner retags
`hive-<color>`, `hive-realtime`, `backend`, `meet-realtime`, `markitdown`,
`storage-unzip-proxy`, `supermemory`, `web-docker-control`, and
`web-cron-runner` into the E2E project and skips those support builds too. If
any support image is missing, E2E falls back to the normal support-service build
path while still reusing the web image. Use this only when the source image was
built from the current checkout.
Set `E2E_DOCKER_REUSE_WEB_IMAGE_SOURCE=<image>` to reuse a specific web image
tag, or `E2E_DOCKER_REUSE_WEB_IMAGE_COLOR=blue|green|auto` when the active-color
file is not the lane you want.

GitHub Actions builds the same image set once per E2E workflow run and shares it
through the private `ghcr.io/tutur3u/platform-e2e` package. The producer starts
after the CI switchboard check, and the Playwright and migration matrices wait
for that job to finish before GitHub allocates their runners. The producer
publishes immutable tags under
`<run-id>-<run-attempt>-<commit-sha>-<service>` and pushes the `-ready` tag only
after every planned blue/green and TanStack image exists and the package has
been verified private. Consumers wait up to
`E2E_IMAGE_BUNDLE_WAIT_SECONDS` (ten seconds by default), pull the complete
frontend plan, retag it for their isolated Compose project, and skip web/support
image builds. Playwright shards request only Next plus support images, the
TanStack dual-stack mode requests only TanStack plus support images, and compare
mode requests both frontends. Consumer jobs use `always()` at the job boundary,
so a failed best-effort producer still starts the existing local cache-backed
build path.
Missing or partial bundles emit a notice and fall back without leaving matrix
runners idle for minutes.

The workflow exposes only three bundle controls:

* `E2E_IMAGE_BUNDLE_REPOSITORY` is the private two-segment GHCR repository.
* `E2E_IMAGE_BUNDLE_TAG_PREFIX` identifies one workflow run and attempt.
* `E2E_IMAGE_BUNDLE_WAIT_SECONDS` bounds how long a consumer may wait before
  falling back.

The producer uses deterministic E2E-only `PLATFORM_BUILD_*` metadata so commit
timestamps and messages do not invalidate otherwise reusable build work;
production release metadata remains unchanged. Published cache images carry the
official `org.opencontainers.image.source` config label, and run indexes retain
the corresponding OCI annotation, so GHCR links the package to this repository
and grants its workflow token package administration. The
privacy check retries briefly while GitHub's package metadata catches up. An
`always()` cleanup job deletes the exact run prefix after all shards and
migration modes finish, and the next producer removes abandoned bundle versions
older than 24 hours to cover canceled workflows. Before publishing run-scoped
tags, the producer creates a permanent `sentinel` image version when one does
not already exist. Later runs reuse it instead of producing untagged sentinel
versions. GHCR rejects deleting a package's final tagged version individually,
so the sentinel lets
exact-prefix cleanup remove every run tag without deleting the package or
touching another concurrent workflow. Bootstrap cleanup preserves one final
version when no sentinel exists yet; the next successful publish creates the
sentinel so a later stale sweep can remove it. Bundle publication is
best-effort, but cleanup is a required storage-safety gate. Investigate package
visibility, `packages` token permissions, or GHCR deletion errors when cleanup
fails; do not make the package public or replace these images with
long-retention Actions artifacts.

The producer also maintains one mutable `cache-<service>` tag per planned image.
These tags anchor the latest runnable layers in private GHCR after run-scoped
tags are deleted, so the next commit does not have to upload unchanged final
image layers again. Superseded cache versions become untagged and remain covered
by the 24-hour stale sweep. Buildx writes cache images directly to GHCR instead
of exporting them through the runner's local Docker image store. Each successful
build records its immutable digest; registry-side manifest promotion creates a
distinct annotated run index from that digest, even if another workflow updates
the mutable cache tag concurrently. Exact-prefix cleanup can therefore delete
run indexes without deleting persistent cache tags. The ready index remains
last, so consumers never observe a partial bundle. These registry-layer anchors
complement Turbo and BuildKit caches without adding Actions cache entries or
artifact storage.

Trusted `main` producers also expose the Turbo team and token secret files to
the native web artifact child process. This lets both Docker/BuildKit stages and
the host-side Next build reuse Turborepo remote cache entries. The values remain
file-scoped until that child starts, are not passed as Docker build arguments,
and are never persisted in an image layer. Pull requests and other untrusted
runs continue without remote-cache credentials.

Each GitHub-hosted E2E runner starts from an empty Supabase volume. In CI,
`E2E_DOCKER_SUPABASE_RESET=0` therefore asks the runner to start Supabase once
and trust that initial bootstrap, which already applies migrations and seed
data. This avoids immediately repeating the same reset while preserving a
separate database stack for every shard and migration mode. Local E2E keeps the
safer reset-by-default behavior because a developer may already have mutable
Supabase volumes.

On GitHub-hosted runners, the E2E workflow frees disk before restoring or
loading cached Supabase Docker images. Keep that cleanup ahead of the cache load:
running `docker system prune -af --volumes` after cached images are loaded would
remove the images the shard is about to use, while skipping the cleanup can leave
too little space for the web Docker image dependency layer.
The default push workflow keeps the existing `cache` transport. To benchmark
the cache archive against direct registry pulls without changing healthy main
runs, dispatch **E2E Tests** manually with **Supabase image transport benchmark
mode** set to `registry`. Compare the `Restore cached Docker images`, `Load
cached Docker images`, and `Run Playwright shard` step durations with an
otherwise equivalent `cache` dispatch. Do not replace the default until three
successful paired runs show a consistent critical-path improvement; migration
replay itself is only a small part of Supabase startup time.
When an E2E shard fails, the runner prints diagnostics before teardown while the
containers still exist. The job log includes the primary error, blue/green stage
state, the Playwright `.last-run.json` file when available, Docker containers
for the shard Compose project, production Compose status, recent logs for web,
Hive, proxy, and support services, the Portless route list, a probe against the
configured E2E `BASE_URL`, and `bun sb:status`. The workflow also has a
failure-only diagnostic step after `Run Playwright shard` as a backstop, so the
job output should show the failing service or stage even when Playwright report
artifacts are incomplete. Before upload, the workflow rewrites the diagnostics
directory to redact secret-shaped key/value pairs, bearer tokens, sensitive
query parameters, JWTs, and secret-like runner environment values. The workflow
uploads diagnostics, Playwright reports, and `apps/web/test-results` for every
non-cancelled shard so traces and screenshots stay available when the job output
is too short.

The Playwright global setup refuses non-local web origins and refuses Supabase
origins outside `localhost`, `127.0.0.1`, or `host.docker.internal` on port
`8001`. CI shards E2E with `--shard=x/4`; each shard gets its own Compose
project name, but all shards still use ephemeral local Supabase rather than any
cloud Supabase project. The generated E2E env sets
`DOCKER_WEB_ALLOW_LOCAL_SUPABASE=1` so the production-image rehearsal can use
that local Supabase origin without weakening production serving defaults.
Because the Docker web app runs with
`NODE_ENV=production`, the generated env file and Playwright process env also
pin `WEB_APP_URL`, `NEXT_PUBLIC_WEB_APP_URL`, and `NEXT_PUBLIC_APP_URL` to
the local shared-cookie origin; otherwise central-auth redirects can escape to
the real `tuturuuu.com` origin during setup. The auth bypass is guarded by the
local E2E web origin, the incoming request `Host` / forwarded host / `Origin`
headers, and both the public and server-side Supabase origins before
server-side auth code honors it, so it must not be used as a general production
configuration.

The blue/green proxy and `apps/web` runtime both allow 64 KB request headers.
That headroom lets the browser reach `/~recover-browser-state` or the normal
login flow when duplicated Supabase cookies make the default header limit too
small. If a request is still too large for the proxy to forward, nginx handles
431/494 directly with `Clear-Site-Data` and redirects to
`/login?browserStateReset=1`; this recovery must stay in the proxy because
Next.js middleware cannot run after nginx rejects the header.

The blue/green nginx proxy must forward the original `Host` header with its
port intact via `$http_host`. Local E2E auth setup posts to
`http://localhost:7803/api/auth/dev-session`, and the production-mode app
accepts the setup route only when the public request origin stays local. The
guard also tolerates production standalone/proxy normalization where `request.url`
or `Host` becomes an internal Docker web upstream, but only when the forwarded
public host is still the local E2E origin.

## Coolify

Coolify can provide enough default deployment metadata for Tuturuuu's Dockerfile
setup to derive the app origin even when you do not manually define the usual
app URL variables.

* During Dockerfile builds, `scripts/build-web-docker.js` now derives missing
  `WEB_APP_URL`, `NEXT_PUBLIC_WEB_APP_URL`, and `NEXT_PUBLIC_APP_URL` values
  from Coolify's `COOLIFY_URL` or `COOLIFY_FQDN` defaults before running
  `bun run build:web`.
* During production container startup, `apps/web/docker/prod-entrypoint.js`
  applies the same Coolify fallback so server-side runtime code sees the same
  derived values.
* The runtime URL resolvers used by the web proxy, internal API client, and
  drive export/auto-extract flows also fall back to `COOLIFY_URL` and
  `COOLIFY_FQDN`.

Recommended setup in Coolify:

* Still set explicit Tuturuuu env like `NEXT_PUBLIC_SUPABASE_URL`,
  `NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY`, `SUPABASE_SECRET_KEY`, and any email
  or storage secrets yourself.
* You can omit `WEB_APP_URL`, `NEXT_PUBLIC_WEB_APP_URL`, and
  `NEXT_PUBLIC_APP_URL` if Coolify already injects `COOLIFY_URL` or
  `COOLIFY_FQDN` for the deployment.
* If you need one specific canonical domain while Coolify exposes multiple
  domains, set the Tuturuuu app URL variables explicitly instead of relying on
  the automatic fallback.

## Development Mode

Development mode exists to preserve the normal root script contract while moving the
web runtime into containers.

* Container-managed `node_modules` are isolated from the host.
* Package-local `node_modules` and `dist` directories are also isolated so host installs do not shadow container artifacts.
* The root Docker context excludes generated app artifacts such as `.next`,
  `.turbo`, coverage output, and Flutter build directories. Keep these excludes
  intact so production builds do not stream multi-gigabyte local artifacts into
  BuildKit.
* A host `bun install` is not required just to boot the Dockerized web stack.

## Production Mode

The production compose file uses the `runner` target from `apps/web/Dockerfile`.

### In-Place

```bash theme={null}
bun serve:web:docker
```

Use this when a short restart is acceptable.

### Blue/Green

```bash theme={null}
bun serve:web:docker:bg
```

Blue/green deploy does this:

1. Reads the last active color from `tmp/docker-web/prod/active-color`.
2. Ignores that state if the corresponding container no longer exists.
3. Builds the target web image through Docker Buildx Bake using Compose-derived
   targets, then stops/removes only the old target web lane and starts the fresh
   replacement.
4. Starts the target web lane after its healthcheck passes and records
   `web-promote` as a staged target in
   `tmp/docker-web/prod/target-state.json`. The deploy does not reload
   `web-proxy` or write `tmp/docker-web/prod/active-color` yet.
5. Builds and runs Hive separately. `hive-db-migrate`, the target
   `hive-blue`/`hive-green` service, `hive-realtime`, and the Hive proxy check
   must pass before web can be publicly promoted. A migration or Hive health
   failure marks the Hive stage failed, leaves `active-color` on the previous
   web lane, and keeps the staged target web lane out of public routing.
6. Refreshes support services (`backend`, `meet-realtime`, `markitdown`,
   `storage-unzip-proxy`, `web-docker-control`, and `web-cron-runner`) after
   web/Hive target work.
   A support build or health failure also blocks `web-proxy` reload and leaves
   the previous active web lane serving.
   Their build step is scoped:
   ordinary web commits build only `web-blue` or `web-green`, while Hive and
   helper images rebuild only when their source, Dockerfile, compose wiring, or
   shared dependency inputs changed. Image-only services such as `redis`,
   `serverless-redis-http`, `web-proxy`, and `cloudflared` are never passed to
   Bake.
7. Injects Docker-internal helper URLs into `apps/web`:
   `BACKEND_INTERNAL_URL=http://backend:7820`,
   `MARKITDOWN_ENDPOINT_URL=http://markitdown:8000/markitdown`,
   `DISCORD_APP_DEPLOYMENT_URL=http://markitdown:8000`,
   `DRIVE_AUTO_EXTRACT_PROXY_URL=http://storage-unzip-proxy:8788/extract`, and
   `INTERNAL_WEB_API_ORIGIN=http://web-proxy:7803`.
8. Keeps the stable `web-proxy` container running in place during ordinary
   promotions instead of re-running `compose up` against the public `:7803`
   listener. If the running proxy is missing required host ports or its
   container image no longer matches the resolved Compose image, the deploy
   defers the forced proxy recreate until after the target web, Hive, and
   support gates have passed.
9. Validates the generated nginx config with `nginx -t`, then reloads or
   recreates the proxy only after every staging gate has passed.
10. Immediately verifies the proxy can serve the internal
    `/__platform/drain-status` endpoint through the newly routed color before
    writing `active-color` and marking the staged web target healthy. This
    avoids false deployment failures from public API middleware or rate limits.
11. Polls an internal drain-status endpoint on the old color and waits until it
    has no in-flight HTTP work left before demoting it to standby. This keeps
    long-running server actions, route handlers, and other open requests from
    being cut off mid-flight.
12. Falls back to the short fixed drain window only when the old image predates
    the drain-status endpoint and cannot report its active requests yet.
13. Keeps the demoted color online as a warm nginx backup target instead of
    removing it immediately, so stale keepalive workers and Cloudflare Tunnel
    connections can still fail over cleanly during the post-promotion window.
14. If the demoted standby color is still on the previous revision after 15
    minutes, the watcher automatically rebuilds that stale standby in place so
    both colors converge on the latest checked-out code without flipping the
    active port or promoting traffic again.

During blue/green deploys, the watcher supplies the version badge metadata via
`PLATFORM_BUILD_*` variables for both Docker image builds and runtime
containers. It infers `PLATFORM_BUILD_COMMIT_HASH`,
`PLATFORM_BUILD_COMMIT_SHORT_HASH`, `PLATFORM_BUILD_COMMIT_MESSAGE`,
`PLATFORM_BUILD_REF_NAME`, `PLATFORM_BUILD_ENVIRONMENT`,
`PLATFORM_BUILD_BUILT_AT`, `PLATFORM_BUILD_DEPLOYMENT_URL`, and
`PLATFORM_BUILD_DEPLOYMENT_STAMP` from the current checkout plus the deployment
context. `PLATFORM_BUILD_BUILT_AT` is the checked-out commit's source timestamp,
so rebuilding the same commit and environment produces identical metadata; it
is not the image-build or rollout time. Deployment stamps and the watcher's
`startedAt`, `finishedAt`, and `activatedAt` records remain the source of actual
deployment timing. The build helper strips deployment stamps and deployment
URLs from Compose, Bake, and native build environments, then supplies them only
to the runtime container; different rollouts of the same source therefore reuse
the same Turbo and image layers. The account-gated badge reads those runtime
values before falling back to generated Vercel/GitHub metadata, so on-prem
watcher deployments show the served commit instead of `local` / `Unknown`.

If those `PLATFORM_BUILD_*` values are missing or blank in a self-hosted
runtime, `apps/web` falls back to the mounted blue/green snapshot before using
generated/local defaults. The resolver reads only lightweight snapshot files:
`prod/target-state.json`, `prod/active-color`, `prod/deployment-stamp`,
`watch/blue-green-auto-deploy.status.json`, and
`watch/blue-green-auto-deploy.history.json` under
`PLATFORM_BLUE_GREEN_MONITORING_DIR`, with local `tmp/docker-web` candidates for
development. Selection prefers `targets.web` for the active color, then an
active deployment row, then the latest successful row for the active color, then
the latest successful row overall. `commitSubject` becomes the badge commit
message, `committedAt` (or an explicit source timestamp) becomes `builtAt`, and
deployment timestamps are used only to order deployment candidates. Legacy rows
without a source timestamp never relabel rollout time as source time. The
runtime deployment stamp file supplies the displayed deployment stamp. The
resolver does not invent deployment URL, ref, or environment from color or
commit data alone.

The helper writes support-image input hashes to
`tmp/docker-web/prod/build-input-hashes.json` and keeps recent decisions in
`tmp/docker-web/prod/build-input-hashes.history.json`. Infrastructure
monitoring reads that history so deployment rows can show which helper images
were rebuilt and which ones were served from the cached build inputs.

### Meet Realtime

`apps/meet-realtime` is the internal control-plane service for Meet calls,
webinars, and low-latency broadcast coordination. It is a Bun WebSocket service
started by production Compose as `meet-realtime` on container port `7816`.
`web-proxy` exposes `/realtime` for `meet.tuturuuu.com` and
forwards WebSocket upgrades to that service.

Production meeting logic stays on Tuturuuu infrastructure:

* `apps/web` owns protected meeting APIs, verifies workspace access, and mints
  short-lived `MEET_REALTIME_TOKEN_SECRET` join tokens.
* `apps/web` and `apps/meet-realtime` must share the same
  `MEET_REALTIME_TOKEN_SECRET`. Production Compose exposes
  `MEET_REALTIME_URL` and `NEXT_PUBLIC_MEET_REALTIME_URL` to Web, defaulting
  both to `wss://meet.tuturuuu.com/realtime` for browser join-token payloads.
* Browsers connect to `wss://meet.tuturuuu.com/realtime?token=...`.
* `apps/meet-realtime` validates the token, manages ephemeral room presence,
  chat, stage state, and reconnect resync, then calls Cloudflare Realtime SFU
  APIs with server-only `CLOUDFLARE_REALTIME_APP_ID` and
  `CLOUDFLARE_REALTIME_APP_SECRET`.
* Browser media flows to Cloudflare Realtime SFU. The control WebSocket can
  reconnect during watcher-managed service refreshes without creating a new
  meeting record.
* Broadcast streaming stays API-owned by `apps/web`: the meeting host calls
  `/api/v1/workspaces/:wsId/meetings/:meetingId/stream`, `apps/web` creates or
  resumes a Cloudflare Stream live input with server-only
  `CLOUDFLARE_ACCOUNT_ID` plus `CLOUDFLARE_STREAM_API_TOKEN` (or
  `CLOUDFLARE_API_TOKEN`), stores the live input UID and WHIP/WHEP URLs in
  `private.meet_stream_live_inputs`, and returns the WHIP publish URL only to
  the host response. Workspace viewers receive only the WHEP playback URL.

Cost controls are part of the signed token contract: camera defaults off,
video is capped at 720p/24fps, room limits are explicit, and webinar viewers do
not receive publish scope. Cloudflare Stream live inputs are created with
recording mode `off` and hidden viewer counts by default; set
`CLOUDFLARE_STREAM_ALLOWED_ORIGINS` to a comma-separated allowlist when Stream
playback should be origin-restricted. Do not add Cloudflare Workers or Durable
Objects for production Meet room logic; use the internal service and
blue/green watcher instead.

`scripts/docker-web/env.js` persists generated helper tokens under
`tmp/docker-web/markitdown-token`, `tmp/docker-web/storage-unzip-token`,
`tmp/docker-web/supermemory-api-key`,
and `tmp/docker-web/supermemory-postgres-password`. Override them with
`DOCKER_MARKITDOWN_ENDPOINT_SECRET`,
`DOCKER_DRIVE_UNZIP_PROXY_SHARED_TOKEN`, or the `DOCKER_SUPERMEMORY_*` env when
an operator needs fixed values.
Workspace ZIP auto-extract is enabled by the workspace-level
`DRIVE_AUTO_EXTRACT_ZIP` secret. Workspaces with `EXTERNAL_PROJECT_ENABLED=true`
also opt in automatically so CMS/WebGL workspaces can reuse the unzipper without
duplicating storage automation setup. The Docker-internal URL and token are
fallbacks for workspaces that have not supplied custom proxy secrets. If a
workspace supplies a custom `DRIVE_AUTO_EXTRACT_PROXY_URL`, it must also supply
its own `DRIVE_AUTO_EXTRACT_PROXY_TOKEN`; the process-wide fallback token must
not be sent to a workspace-controlled proxy URL.

CMS WebGL package uploads also use the `storage-unzip-proxy`, but they are a
first-class CMS upload path rather than generic Drive automation. They require a
configured unzip proxy URL and token, but they do not require the
`DRIVE_AUTO_EXTRACT_ZIP` workspace opt-in secret. The CMS finalize route unpacks
the ZIP into workspace Drive, detects the playable `index.html`, and stores the
same-origin artifact map on the CMS `webgl-package` asset. Browser uploads go
directly to the signed storage URL returned by the self-hosted web app's WebGL
upload-url route, so large ZIPs do not pass through the Vercel-hosted CMS app or
the web app proxy before reaching Supabase Storage or R2. The CMS client reports
per-file upload progress during the signed upload, then calls the WebGL finalize
route so the backend handles extraction and artifact-map persistence.

The unzip proxy fans out backend callbacks for extracted folders and asks the
callback route for per-file upload URLs. Before uploading extracted bytes, the
proxy verifies the callback response names a trusted provider and that the
signed upload URL belongs to hosted Supabase, Cloudflare R2, or an exact
operator-configured upload origin. It forwards only content type and generated
bearer-token headers to the upload URL. The storage auto-extract and CMS WebGL
extract callback routes still pass through the central API proxy guard before
they validate the shared unzip token, so malformed, rate-limited, or oversized
callback requests are rejected at the same cheap boundary as other API
mutations. Direct `file` callbacks are legacy/small-file only and enforce the
same 512 KiB body budget locally; large extracted files must use the
`file-upload-url` callback flow. The proxy currently buffers the downloaded
archive and each extracted file in memory, so the default caps stay
conservative: 100 MiB ZIP downloads, 50 MiB per extracted file, and 250 MiB
total extracted output.
Operators can tune those caps with
`DRIVE_UNZIP_PROXY_MAX_ARCHIVE_BYTES`,
`DRIVE_UNZIP_PROXY_MAX_ENTRY_BYTES`,
`DRIVE_UNZIP_PROXY_MAX_TOTAL_EXTRACTED_BYTES`, and
`DRIVE_UNZIP_PROXY_MAX_ARCHIVE_ENTRIES`; workspace Drive quota must still be
large enough for the uploaded archive and extracted files. Set
`DRIVE_UNZIP_PROXY_ALLOWED_UPLOAD_ORIGINS` for self-hosted Supabase or custom
R2/S3-compatible origins, and reserve
`DRIVE_UNZIP_PROXY_ALLOW_LOCAL_UPLOAD_ORIGINS=true` for local Supabase testing.

The MarkItDown endpoint is the conversion path for uploaded workspace files.
Do not route YouTube summaries through MarkItDown or Google Search. Google
Gemini chat requests attach one public or unlisted YouTube URL directly as a
native `video/mp4` file input, so the model can summarize the video through the
provider-supported video path. Playlist/query parameters are stripped before
the URL is attached so each request references only one video. Any legacy direct
URL conversion path that still reaches MarkItDown must reserve and commit the
fixed MarkItDown credit charge before the sidecar request is sent.

Interrupted Docker Compose recreates can leave temporary container names such
as `<hex>_platform-markitdown-1`. The Docker helper treats those as recoverable
only when the suffix matches one of the services in the current `compose up`
request, removes that stale temp container, and retries the same narrow up
operation.
Compose can also briefly report `dependency failed to start` with `No such
container: <id>` when a dependency was recreated between Docker's dependency
resolution and health wait. The helper treats that as a stale dependency
reference and retries the same narrow `compose up` without deleting unrelated
containers. Tune that retry budget with
`DOCKER_WEB_COMPOSE_UP_STALE_DEPENDENCY_RETRY_MAX_ATTEMPTS`.

The production `web-proxy` service is pinned to the official mainline Alpine
image `nginx:1.31.0-alpine`, and `scripts/check-docker-web.js` verifies that
pin in the merged production Compose config.

The long-lived nginx proxy also raises its request-header buffer limits so larger
session/auth cookies do not fail at the proxy layer with `400 Request Header Or
Cookie Too Large` before the active web container sees the request. It now also
raises its upstream response-header buffers (`proxy_buffer_size`,
`proxy_buffers`, and `proxy_busy_buffers_size`) so larger Supabase auth
responses with multiple `Set-Cookie` headers do not fail with `upstream sent too
big header while reading response header from upstream`. The proxy uses Docker
DNS re-resolution plus a shorter keepalive timeout so promotions are less
likely to produce transient `502 Host Error` responses for existing Cloudflare
Tunnel connections, while the previous color remains alive as a warm standby.
The proxy keeps both blue and green in the nginx upstream group during steady
state, with the active color as the primary upstream and the standby color as a
backup. The runtime DNS resolver is defined at the nginx include/http scope,
not just inside `server`, so Docker service-name resolution continues to work
for the blue/green upstream block at reload time.
Both the production web image healthcheck and the `web-proxy` compose
healthcheck now use the internal `/__platform/drain-status` endpoint too, so
raw `bun serve:web:docker:bg` waits on the same non-rate-limited readiness path
as the blue/green promotion gate. The proxy exposes that path as an exact
loopback-only nginx location and forwards a private internal probe header to
the active web lane, because the web request tracker intentionally answers the
drain-status endpoint only for local or explicitly trusted Docker-network
requests.

Every blue/green deployment also stamps the runtime with
`PLATFORM_DEPLOYMENT_STAMP` and `PLATFORM_BLUE_GREEN_COLOR`. Those values are
surfaced through both nginx response headers and the web process itself, and
the web layout appends the deployment stamp to the service-worker URL with
`updateViaCache: 'none'` so new deployments push browsers toward the latest
worker instead of lingering on stale cached state.

The local runtime state lives in:

* `tmp/docker-web/prod/active-color`
* `tmp/docker-web/prod/deployment-stamp`
* `tmp/docker-web/prod/nginx.conf`
* `tmp/docker-web/prod/target-state.json`

These files are intentionally local-only and safe to regenerate.
Infrastructure Monitoring → Deployments reads `target-state.json`, the watcher
deployment history, and the latest deployment stage handoff together, so
operators can see staged target work such as a prepared web color while Hive or
support gates still block public promotion. `active-color` and the generated
proxy config remain on the previous serving web lane until the final
`proxy-reload` stage passes. Watcher-managed deployments persist the
`web-build`, `web-promote`, `hive-migrate`, `hive-promote`,
`support-refresh`, and `proxy-reload` stage results into deployment history.
Modern rows that were recorded without a stage array are inferred from final
deployment status and build-cache metadata; truly pre-tracking rows still show
stage chips as not applicable. Active watcher deployments that only have
pending build/deploy status are surfaced with a synthetic current stage so
operators can see the build is in progress before full stage history is written.
When `TUTURUUU_CI_CHECKS_ENABLED=1`, the watcher also publishes one sanitized
GitHub Check Run per watched commit. The default check name is `Tuturuuu CI`;
override it with `TUTURUUU_CI_CHECK_NAME`. The managed production path is the
Infrastructure → GitHub Bot page in the root workspace: create and install a
Tuturuuu-owned GitHub App with repository `Checks: write` permission, then save
the App ID, installation ID, repository owner/name, and private key there. The
private key stays server-side and encrypted in the private-schema vault. After
the configuration validates, use **Enable watcher auto-pickup** on the same
page. apps/web issues a dedicated watcher-only client token, writes a small
credential request into the blue/green control directory, and the watcher moves
that credential into its local runtime directory on the next Check Run publish.
The watcher then discovers the apps/web installation-token endpoint without
requiring you to copy GitHub-related env into the watcher process. The queued
runtime credential is the Check Run opt-in signal for the watcher.

Manual generated-token setup remains available for local or emergency use:

```bash theme={null}
TUTURUUU_CI_CHECKS_ENABLED=1
TUTURUUU_CI_GITHUB_TOKEN_URL=https://<apps-web-origin>/api/v1/infrastructure/github-bot/installation-token
TUTURUUU_CI_GITHUB_TOKEN_CLIENT_TOKEN=<watcher-client-token>
```

The watcher exchanges that client token for repository-scoped GitHub App
installation tokens and refreshes them before expiry. Revoke and reissue the
watcher client from Infrastructure → GitHub Bot when rotating access. The
browser UI never displays generated GitHub installation tokens, and the
auto-pickup action does not display the watcher client token. Manual and
static-token paths still require `TUTURUUU_CI_CHECKS_ENABLED=1`; when enabled,
the publisher uses `TUTURUUU_CI_GITHUB_TOKEN` first, then an explicitly
configured generated token endpoint, then the watcher auto-pickup runtime
credential, then `GITHUB_TOKEN`. Static tokens must be able to create and
update Check Runs for the repository. The watcher stores the latest check-run
id per commit in
`tmp/docker-web/watch/blue-green-github-checks.json` so restarts update the
same GitHub row instead of creating duplicates. `TUTURUUU_CI_CHECK_DETAILS_URL`
is optional and omitted unless explicitly configured.

The GitHub-facing Check Run is intentionally not a log export. It includes only
allowlisted rollout metadata: commit SHA/short SHA, branch/upstream, deployment
kind, watcher status, current stage, aggregate stage counts, and safe
timestamps/durations. It must not include raw watcher logs, raw error messages,
environment values, local host paths, hostnames, emails, user ids, tokens, or
secret-shaped key/value text.

The watcher also uses GitHub workflow-run validation to avoid repeatedly
building a commit whose CI has already failed. When Check Run publishing is
enabled, `GITHUB_REPOSITORY` is present, or
`DOCKER_WEB_WATCHER_GITHUB_VALIDATION=1` is set, the watcher reads the latest
Actions workflow runs for the candidate commit's exact `head_sha`. If the
latest run for any workflow completed with `failure`, `cancelled`,
`timed_out`, `startup_failure`, or `action_required`, automatic deploy,
recovery handoff, reconciliation, and standby-refresh builds are suppressed
with watcher status `validation-blocked`. That state does not add a failed
deployment row or consume the retry budget; fix CI and let the watcher see a
new successful/latest run, or set
`DOCKER_WEB_WATCHER_GITHUB_VALIDATION_DISABLED=1` for an operator-approved
manual override.
After each Hive migration pass, the deploy helper runs
`docker compose rm --stop -f hive-db-migrate` so the completed one-shot
migration service is stopped if necessary and removed. This keeps
`hive-db-migrate` from lingering after `depends_on` starts it while Hive
services come up.

## Native Cron Runner

Self-hosted production cron jobs use `apps/web/cron.config.json` as the shared
source of truth. `apps/web/vercel.json.crons` should stay generated from that
file with:

```bash theme={null}
node scripts/sync-web-crons.js --check
node scripts/sync-web-crons.js
```

Use `--check` in CI and local verification when cron definitions change. The
sync script preserves Vercel behavior by copying each enabled job's `path` and
`schedule` from the shared config into `apps/web/vercel.json`.

In Docker production, the `web-cron-runner` service runs
`scripts/watch-web-crons.js` against `INTERNAL_WEB_API_ORIGIN`, defaulting to
`http://web-proxy:7803`. Requests include
`Authorization: Bearer ${CRON_SECRET || VERCEL_CRON_SECRET}` so the same route
auth gate can protect Vercel and native Docker executions.
The cron-runner image bundles the `cron-parser` dependency used by that script,
so runtime execution does not depend on `node_modules` existing in the mounted
host checkout.

When neither `CRON_SECRET` nor `VERCEL_CRON_SECRET` is set on the host, the
Docker environment generator creates a persisted internal secret at
`tmp/docker-web/cron-token` and injects it into both the web containers and the
`web-cron-runner` service as `CRON_SECRET`. This keeps native Docker cron auth
self-contained while preserving explicit host-provided secrets when present.

Watcher startup also keeps the Docker control sidecar and cron runner present.
`bun serve:web:docker:bg`, `bun serve:web:docker:bg:watch`, and watcher
recovery recreate or resume `web-blue-green-watcher` first, refresh
`web-docker-control`, then ensure `web-cron-runner` exists with a no-recreate
Compose start. A healthy existing cron runner is left running; a missing control
sidecar or runner fails watcher bootstrap instead of leaving the stack without
native cron recovery or execution.

`web-cron-runner` is the executor. The blue/green watcher is one recovery
consumer, not the owner of cron execution. Each watcher poll reconciles
cron-runner health before normal deploy work by checking the
`web-cron-runner` container state, Docker healthcheck result, and
`tmp/docker-web/cron/status.json.updatedAt`. If the container is missing,
unhealthy, or the heartbeat is stale, the watcher writes the existing
`tmp/docker-web/watch/control/cron-runner-recovery.request.json` request and
processes it immediately with a force-recreate of `web-cron-runner`. It then
waits for a fresh heartbeat before reporting `cron-runner-recovered`; if the
Compose restart fails, the request remains on disk with `lastError` and the
watcher backs off before retrying.

`web-docker-control` also owns an independent cron-runner watchdog. The watchdog
defaults on, reads the same cron runner heartbeat, inspects the
`web-cron-runner` container, ensures `web-blue-green-watcher`, and
force-recreates only `web-cron-runner` when the heartbeat is stale/missing or
the container is missing/unhealthy. This keeps cron recovery available even when
the blue/green watcher heartbeat is stale. The watchdog does not recover the
whole serving stack; route-origin failures such as an unreachable
`INTERNAL_WEB_API_ORIGIN` / `web-proxy` are reported in monitoring diagnostics
for an operator to fix separately.

Cron runner heartbeats refresh both runner liveness and schedule metadata. When
the runner starts a cycle or keeps a long execution alive, it recomputes each
enabled job's next future run from `apps/web/cron.config.json`, current runtime
control overrides, and UTC time. The monitoring API also derives future
`nextRunAt` values from config/control if an older persisted status file still
contains stale schedule fields, while preserving the separate stale/live runner
health signal from `status.json.updatedAt`.

`web-cron-runner` also protects itself. The entrypoint restarts the child
`scripts/watch-web-crons.js` process when the status heartbeat is missing,
invalid, or stale after startup grace, and the Docker healthcheck calls the same
entrypoint heartbeat check. This prevents a hung cron child from looking
healthy just because the process still exists.

Useful cron-runner recovery knobs:

* `DOCKER_WEB_WATCHER_CRON_RUNNER_STALE_AFTER_MS` controls watcher heartbeat
  staleness detection. Default: `120000`.
* `DOCKER_WEB_WATCHER_CRON_RUNNER_RECOVERY_WAIT_MS` controls how long the
  watcher waits for a fresh heartbeat after restart. Default: `90000`.
* `DOCKER_WEB_WATCHER_CRON_RUNNER_RECOVERY_POLL_MS` controls the heartbeat wait
  poll interval. Default: `2000`.
* `PLATFORM_CRON_RUNNER_STATUS_STALE_AFTER_MS` controls the entrypoint child
  watchdog. Default: `120000`.
* `PLATFORM_DOCKER_CONTROL_CRON_WATCHDOG_DISABLED` disables the
  `web-docker-control` cron-runner watchdog when set to `true`. Default:
  `false`.
* `PLATFORM_DOCKER_CONTROL_CRON_WATCHDOG_INTERVAL_MS` controls the
  `web-docker-control` watchdog polling interval. Default: `30000`.
* `PLATFORM_DOCKER_CONTROL_CRON_RUNNER_STALE_AFTER_MS` controls
  `web-docker-control` heartbeat staleness detection. Default: `120000`.
* `PLATFORM_DOCKER_CONTROL_CRON_RECOVERY_COOLDOWN_MS` controls
  `web-docker-control` recovery cooldown after a restart attempt. Default:
  `60000`.
* `PLATFORM_CRON_DOCKER_TELEMETRY_TIMEOUT_MS` bounds Docker `ps` / `logs`
  probes used for cron telemetry. Default: `10000`.

`web-docker-control` is an internal-only sidecar with the Docker CLI, Docker
socket, and host worktree mount. `apps/web` reaches it through
`PLATFORM_DOCKER_CONTROL_URL` and `PLATFORM_DOCKER_CONTROL_TOKEN` for hardcoded
watcher/cron-runner recovery actions only; it does not expose a general Docker
or shell interface. Its status file at
`tmp/docker-web/docker-control/status.json` includes both the latest manual or
watchdog recovery attempt and the latest watchdog check, which the cron
monitoring dashboard surfaces alongside watcher and runner heartbeat warnings.
When the runner heartbeat is stale, future cron times in the dashboard are
scheduled estimates derived from config/control, not proof that the runner will
execute them.

Runtime cron telemetry is intentionally file-based and local to the host:

* `tmp/docker-web/cron/status.json` for runner health, the current cycle, and
  the latest manual run lifecycle records. Manual runs move through `queued`,
  `processing`, and a final `success` / `failed` / `timeout` / `skipped` state.
  While any run is processing, the runner refreshes this heartbeat and, for
  manual runs, captured route console logs so the monitoring UI can show
  near-realtime status and log updates. Heartbeat refreshes also recompute
  future per-job and aggregate `nextRunAt` values so a recovered runner does not
  keep serving stale schedule badges.
* `tmp/docker-web/cron/state.json` for restart-safe last-run markers.
* `tmp/docker-web/cron/executions/*.jsonl` for per-run route response,
  duration, status, and captured web-container console logs.
* `tmp/docker-web/watch/control/cron-control.json` for the global enabled
  switch.
* `tmp/docker-web/watch/control/cron-run-requests/*.json` for queued manual
  runs created by the monitoring UI.

Disabling cron execution blocks scheduled jobs and leaves manual run requests
queued until cron execution is enabled again. The runner also supports
`--once`, which is used by script tests to verify due-run detection, queued
manual runs, restart-safe state, and log persistence without starting the
long-running loop.

Calendar cron routes should call workspace calendar APIs through
`INTERNAL_WEB_API_ORIGIN` when it is present. In Docker production this keeps
provider sync and smart scheduling traffic on the internal `web-proxy` origin
instead of accidentally depending on a public app URL from inside the container.
`calendar-provider-sync` intentionally calls the same
`/api/v1/workspaces/:wsId/calendar/sync` route that the calendar page uses, but
with cron auth and `source: "cron"` so dashboard runs stay manual and scheduled
runs stay auditable. The workspace sync route is responsible for provider
fan-out: Google connections are selected from active Google auth-token rows, and
Microsoft connections are selected from active Microsoft auth-token rows. Do not
reimplement provider-specific calendar fetching inside the cron wrapper.
The job should run every 15 minutes from `apps/web/cron.config.json`; Calendar
provider sync should not be scheduled through Trigger.dev in production.

## Auto-Deploy Watcher

`bun serve:web:docker:bg:watch` locks the current branch/upstream at startup,
polls every second, fast-forwards when GitHub has a newer commit, and runs the
blue/green deploy flow automatically.

When the watcher container starts on a host with no active blue/green runtime,
it treats that idle state as a missing active deployment and bootstraps the
current commit. This first-run recovery creates `web-proxy`, the active and
standby lanes, and `cloudflared` when the tunnel profile is enabled.

Run this command from a host-level process manager, not only from inside Docker.
The command starts and tails the `web-blue-green-watcher` container, but the
host process is the part that can recover after the Docker engine itself dies.
When Docker is unavailable or Docker CLI probes stop returning, the host
supervisor polls Docker with bounded probes; after
`DOCKER_WEB_WATCHER_DOCKER_RESTART_AFTER_MS` milliseconds of continuous failure
(default 30000), it attempts to restart Docker, waits for Docker probes to pass,
runs any configured host-level post-restart commands, then recreates the watcher
container. The recreated watcher reuses the existing cached blue/green recovery
path to bring `web-proxy` and the active/standby web lanes back to health.

During normal steady-state polling, after active build-lock and revert checks,
the watcher also reconciles the production Compose services that should already
be serving. It inspects the expected services with stopped containers included:
`web-proxy`, the active web or TanStack lane, Redis profile services, enabled
health-gated sidecars, active-color Hive/realtime services, and `cloudflared`
when its profile is enabled. Missing, exited, dead, or unhealthy services are
recovered with bounded no-build Compose operations: stopped or missing services
use `docker compose ... up --detach --no-build --remove-orphans`, unhealthy
services are force-recreated, and `starting` services are left alone until the
next poll. Image rebuilds remain owned by the normal blue/green deploy flow and
the cached/full active-runtime recovery fallback.

Before recreating the watcher after a suspected devbox/local Supabase mix-up,
inspect only origin classifications, not secrets. Root `.env.local` should
classify as cloud for `NEXT_PUBLIC_SUPABASE_URL` and `SUPABASE_SERVER_URL`;
`apps/web/.env.local` may classify as local after `ttr box setup`, but the
watcher must not select it while root `.env.local` exists. If local Supabase was
started accidentally on a production host and no other local workflow is using
it, stop it with `bun sb:stop`, then recreate the watcher with
`bun serve:web:docker:bg:watch`.

Docker restart command defaults:

* Linux: `systemctl restart docker`
* macOS: `open -ga Docker`
* Windows: `powershell.exe -NoProfile -Command Start-Process "Docker Desktop"`

Override the command with a JSON array when the host needs a different service
manager or a narrow sudo rule:

```bash theme={null}
DOCKER_WEB_WATCHER_DOCKER_RESTART_COMMAND='["sudo","systemctl","restart","docker"]' \
  bun serve:web:docker:bg:watch -- --if-locked replace
```

Useful host-supervisor knobs:

* `DOCKER_WEB_WATCHER_DOCKER_RESTART_AFTER_MS`: delay before the first Docker
  restart attempt while `docker info` is failing; set `0` to disable attempts.
* `DOCKER_WEB_WATCHER_DOCKER_RESTART_COOLDOWN_MS`: minimum time between restart
  attempts; default 300000.
* `DOCKER_WEB_WATCHER_DOCKER_RESTART_COMMAND`: command used to restart or open
  Docker. Prefer JSON array syntax for commands with quoted arguments.
* `DOCKER_WEB_WATCHER_DOCKER_RESTART_DISABLED=1`: hard-disable daemon restart
  attempts while still waiting for Docker to recover externally.
* `DOCKER_WEB_WATCHER_DOCKER_RECOVERY_TIMEOUT_MS`: optional maximum wait time
  for Docker recovery; unset or `0` means wait indefinitely.
* `DOCKER_WEB_WATCHER_DOCKER_PROBE_TIMEOUT_MS`: timeout for quick Docker CLI
  probes such as `docker info`, `docker compose version`, and watcher container
  state checks; default 10000.
* `DOCKER_WEB_WATCHER_LOG_STREAM_RECONNECT_MS`: maximum time to let the host
  wrapper follow watcher logs before reconnecting and checking watcher health;
  default 60000.
* `DOCKER_WEB_WATCHER_DOCKER_POST_RESTART_COMMAND_TIMEOUT_MS`: timeout for each
  additional host-level recovery command; default 600000.
* `DOCKER_WEB_WATCHER_DOCKER_POST_RESTART_COMMANDS`: JSON array of host-level
  commands to run after Docker is reachable again and before Tuturuuu recreates
  its watcher container. Each entry is an object with `command`, `args`, and an
  optional `cwd`.
* `DOCKER_WEB_WATCHER_MAX_REQUEST_LOG_BYTES`: maximum durable proxy
  request-log ledger size before the watcher rotates and prunes older JSONL
  chunks before appending new entries; default 268435456 bytes.

Timing, disable, and email alert values can be updated from Infrastructure
Monitoring in the web dashboard. The dashboard writes
`tmp/docker-web/watch/control/blue-green-docker-recovery-settings.json`, and
the host supervisor reads that file before each Docker recovery wait. Dashboard
settings override the environment defaults without restarting the supervisor.
Host-level executable commands are different: configure
`DOCKER_WEB_WATCHER_DOCKER_RESTART_COMMAND` and
`DOCKER_WEB_WATCHER_DOCKER_POST_RESTART_COMMANDS` only in the host supervisor
environment. The supervisor intentionally ignores command fields from
`blue-green-docker-recovery-settings.json` so dashboard viewers cannot persist
host commands for a later recovery event.

That settings file also owns Docker crash email alerts:

* `emailAlertsEnabled`: enables SES-backed Docker recovery alert emails from the
  web cron worker and watcher-side first-failure build/deploy incident emails.
* `emailAlertRecipients`: explicit recipient list. If this is empty, the cron
  and watcher fall back to `PLATFORM_DOCKER_RECOVERY_ALERT_EMAILS`, then the
  last operator email that saved the settings.
* `emailAlertCooldownMs`: minimum time between alert emails; default 1800000.

The host supervisor persists Docker crash/recovery events to the watcher log
archive as soon as it detects failed or timed-out Docker probes. If Docker had
to be restarted before services recovered, the watcher sends an immediate
force-restart recovery email to the configured recovery recipients and records
that incident as notified. If the watcher-side email is disabled or fails, the
infra app cron job `/api/cron/infrastructure/docker-recovery-alerts` can still
send a fallback SES email after Docker and the infra app are reachable again. Both paths
deduplicate by Docker recovery incident id using
`tmp/docker-web/watch/control/blue-green-docker-recovery-alert-state.json`.

The blue/green watcher sends its own build/deploy incident email when an
`apps/web` deployment attempt first fails for a commit. This runs from the
watcher process rather than the current web image, uses the same recipient
resolution as Docker recovery alerts, and only sends for the first failed
history row per `commitHash`. Later retries for that same commit still append
full failure history but do not spam operators. The incident email includes the
full and short commit hash, commit subject, branch/upstream, deployment kind,
host, timing, exit code or signal when available, the recorded `failureReason`,
and debugging pointers for watcher history/log files plus commands like
`git show --stat --oneline <hash>` and watcher container logs. Notification
send failures are logged and never block the watcher loop.
Watcher incident email code runs from the repo root inside the watcher
container, so any workspace package imported by `scripts/watch-blue-green/*`
must be root-resolvable through `package.json` and covered by a root-runtime
import test.

Example post-restart commands for colocated projects:

```json theme={null}
[
  {
    "command": "docker",
    "args": ["compose", "-f", "/srv/zeus/docker-compose.yml", "up", "-d"],
    "cwd": "/srv/zeus"
  },
  {
    "command": "docker",
    "args": ["compose", "-f", "/srv/upskii/docker-compose.yml", "up", "-d"],
    "cwd": "/srv/upskii"
  }
]
```

For Linux production hosts, install the command as a root-owned `systemd`
service or run it as an operator account with permission to execute only the
configured Docker restart command and the explicit post-restart commands needed
by colocated projects. Use `Restart=always` so the host supervisor itself comes
back after reboots or process crashes.

Example unit:

```ini theme={null}
[Unit]
Description=Tuturuuu blue/green watcher
After=docker.service network-online.target
Wants=docker.service network-online.target

[Service]
Type=simple
WorkingDirectory=/srv/tuturuuu
Environment=NODE_ENV=production
ExecStart=/usr/local/bin/bun serve:web:docker:bg:watch -- --if-locked resume
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target
```

Install it with the production checkout path and Bun path for the host, then
run `systemctl enable --now tuturuuu-blue-green-watcher.service`. Keep
deployment secrets in the checkout's root `.env.local` or an explicit env file,
not in the unit file.

Additional behavior:

* If the watcher script itself changed in the pulled revision, the current
  watcher process restarts first and the replacement process performs the
  deploy.
* If blue/green is already live and the standby color remains on an older
  revision for 15 minutes, the watcher rebuilds only the standby color in
  place. The active color remains primary for new traffic the whole time.
* If the watcher sees a degraded blue/green runtime with a proxy or runtime
  marker present but no active web color serving traffic, it immediately
  retags the latest retained successful image into the active web color and
  starts it with `--no-build`. It prefers a retained image for the current
  `main` commit, then falls back to the newest retained successful image so
  the runtime can recover first and reconcile to `main` afterward. It then
  retags the same cached image into the opposite color and starts that as the
  warm standby, creating two ready copies without waiting for a fresh build.
* Blue/green active and standby discovery uses Docker health, not just
  container presence. If the persisted active color is unhealthy but the
  opposite color is healthy, the watcher rewrites the active marker and proxy
  to the healthy color before building or refreshing another lane.
* Cached recoveries write a fresh nginx proxy config before the proxy is
  started, so recovery never boots nginx with a stale upstream that points at a
  missing or unhealthy color.
* That standby catch-up path also stops and removes the stale standby
  container before rebuilding it, so health checks target the fresh
  replacement container rather than an outdated standby instance.
* Standby catch-up rebuilds reuse the current deployment stamp so the warm
  backup matches the latest deployment state instead of serving an older build
  if nginx needs to fail over.
* The watcher dashboard surfaces the top 3 most relevant deployments from the
  recent history, prioritizing in-progress rollouts first, then the live
  promoted color, then the warm standby. Direct manual
  `bun serve:web:docker:bg` runs are written into that same history too.
* Cached recoveries write both the active recovery and the standby refresh into
  the same retained ledger, preserving the current two warm copies plus the
  prior successful deployment as the fastest rollback reference. If no retained
  image exists, the watcher falls back to the normal recovery build path.
* The infrastructure monitoring rollback controls show the latest retained
  cached recovery images separately from the general deployment history, so an
  operator can quickly select a known cache-backed commit before pinning it for
  rollback or smoke testing.
* Successful active and standby builds tag the service image as
  `{compose-project}-web-cache:{commit}` and prune older retained cache tags
  beyond the three newest successful deployments. Pruning is idempotent:
  already-removed cache tags are ignored instead of warning in the live watcher
  log.

### Deployment build lock

Blue/green deploys coordinate on a JSON lock file under
`tmp/docker-web/watch/blue-green-deployment-build.lock` (owner PID, command,
deployment kind, and a re-entrant token for nested helper calls).

* On **Linux**, the helper compares `/proc/<pid>/cmdline` to the recorded lock
  so a reused PID after a crash cannot masquerade as an in-flight deploy. The
  recorded command is the package script name (`bun serve:web:docker:bg`), but
  production deploys usually run as `node scripts/docker-web.js ...`; the
  matcher treats those as the same holder so a live `node` deploy is not cleared
  as a stale PID reuse. On **macOS and Windows**, the same age-based stale window
  (`DOCKER_WEB_DEPLOYMENT_LOCK_STALE_AFTER_MS`, default eight hours) still clears
  abandoned locks because `/proc` validation is unavailable. When no `web-proxy`
  / `web-blue` / `web-green` / `tanstack-web-blue` / `tanstack-web-green`
  containers exist, the auto-deploy watcher also runs the same stale-lock sweep
  before cached recovery.
* **`DOCKER_WEB_DEPLOYMENT_LOCK_STALE_AFTER_MS`**: optional override for the
  default eight-hour window used when `/proc` is unreadable but `kill(pid, 0)`
  still reports a process (for example permission quirks). Set to `0` to
  disable age-based assists.
* **`DOCKER_WEB_CANCEL_ACTIVE_BUILD=1`** or **`--cancel-active-build`** on a
  manual `bun serve:web:docker:bg` run stops the watcher/buildkit services,
  clears the lock, and records a canceled history row before starting fresh.
* The auto-deploy watcher treats an active deployment lock as a wait state, not
  a failed deploy attempt. Recovered pending handoffs, reconcile builds, standby
  refreshes, platform promotions, and imported Infrastructure project builds all
  defer behind the same lock so only one deployment build runs across the stack.
* The watcher also treats a build lock older than 30 minutes as a timed-out
  build. For another live deployment PID, it sends `SIGTERM` to the recorded
  owner. If the lock is owned by the watcher process itself and the watcher has
  already returned to the polling loop, the lock is treated as leaked
  `cached-recovery` state and cleared without signaling the watcher. In both
  cases, the watcher records a failed deployment history row with the timeout
  reason and waits until the next polling cycle before retrying. Override the
  window with `DOCKER_WEB_WATCHER_BUILD_TIMEOUT_MS`; set it to `0` only when an
  operator explicitly wants to disable watcher-side build termination.
* The **`apps/web` Dockerfile `deps` stage** retries `bun install --frozen-lockfile` up to three times with a Bun cache scrub between attempts.
  If the build still exits with `bun install --frozen-lockfile` **exit code 1**
  after a `git pull`, regenerate `bun.lock` in a development checkout, commit
  the reviewed lockfile update, and deploy that commit. Do not let the
  production host rewrite `bun.lock` as part of the auto-deploy path. If tarball
  extraction still fails (for example
  `@biomejs/cli-linux-x64`), the blue/green helper prunes BuildKit exec cache
  mounts, recreates the Compose-owned `buildkit` service, and retries once with
  `docker compose build --no-cache` so a cached failed deps stage is not reused.
  If BuildKit has already lost transport and the exec-cache prune command exits
  with EOF or `code = Unavailable`, that prune is treated as best-effort and the
  service is still recreated before retrying. The same one-time fresh retry is
  used for `CACHED ERROR ... COPY --from=deps` and for the build watchdog
  timeout.

### Monitoring Surfaces

The infrastructure monitoring UI in `apps/infrastructure` is intentionally split
into smaller pages instead of one oversized dashboard:

* `/{wsId}/monitoring` for the operator overview, runtime
  snapshot, cron health summary, and jump points into deeper surfaces.
* `/{wsId}/monitoring/cron` for cron job schedules, global
  enable/disable control, manual run requests, recent execution status, route
  responses, and captured web-container console logs.
* `/{wsId}/monitoring/rollouts` for rollout controls, deployment
  charts, event streams, and ledger history.
* `/{wsId}/monitoring/requests` for paginated proxy request
  history backed by the durable JSONL request store under
  `tmp/docker-web/watch/blue-green-request-logs/`.
* `/{wsId}/monitoring/watcher-logs` for paginated watcher log
  browsing backed by `tmp/docker-web/watch/blue-green-auto-deploy.logs.json`.

Operationally, keep the overview route lightweight and treat request/log
archives as dedicated drill-down pages. The summary snapshot is for quick
operator context; durable history should be paged from the persisted ledgers.

## Build Resource Caps

When build and serve run on the same machine, use the Docker web helper's
Buildx throttling options instead of letting BuildKit consume the full host.

Example:

```bash theme={null}
bun serve:web:docker:bg -- --build-memory auto --build-cpus 4 --build-max-parallelism 1
```

Current root-script defaults:

* `bun serve:web:docker` defaults to `--build-memory auto --build-cpus 4 --build-max-parallelism 1`
* `bun serve:web:docker:bg` defaults to `--build-memory auto --build-cpus 4 --build-max-parallelism 1`

The helper resolves `auto` from Docker's reported memory limit before starting,
restarting, or recreating the Compose-owned BuildKit service. On a Docker
Desktop allocation of 28 GiB, that means the BuildKit memory cap resolves to
about 21 GiB: the helper keeps a real reserve for the Docker VM and other
containers instead of assigning nearly the full Docker allocation to BuildKit.
Direct Compose use still has a concrete `mem_limit` fallback of **12g** and
`cpus` **4** when `DOCKER_WEB_BUILD_MEMORY` and `DOCKER_WEB_BUILD_CPUS` are
unset, because Compose cannot resolve the helper's `auto` value by itself. Raise
or lower the caps with env vars or helper flags when your machine is tighter or
has spare capacity.

For blue/green runs that use the root-script defaults, the helper also keeps a
machine-local adaptive profile at
`tmp/docker-web/buildkit/resource-profile.json`. If BuildKit fails with a
transport or resource-pressure signature such as `code = Unavailable`,
`closing transport`, `error reading from server: EOF`, `received prior goaway`,
`ResourceExhausted`, `cannot allocate memory`, `context deadline exceeded`, or
`[internal] waiting for connection`, the deploy keeps retrying lower profiles in
the same command until the build succeeds or the budget-aware retry ladder is
exhausted. Each retry persists the selected profile for later runs, skips fixed
profiles that exceed the effective Docker memory budget during normal
selection, and can use a larger hard-limit rescue profile after conservative
profiles are exhausted if Docker's reported memory limit still has headroom.
For explicit memory-exhaustion signatures such as `cannot allocate memory` or
exit code 137, the helper can prefer that hard-limit rescue before smaller
profiles that are unlikely to help.
When a later default run sees stale persisted fallback state, it promotes that
state back to the largest Docker-hard-limit rescue profile, preferring lower CPU
at equal memory, before starting BuildKit.
The helper recreates the Compose-owned BuildKit service even if the cleanup
prune command itself fails with the same transport signature, then recreates the
remote Buildx builder if `docker buildx inspect tuturuuu` reports
`Status: inactive`. The profile ladder is:

* `default`: `auto`, 4 CPUs, max parallelism 1
* `stable`: `16g`, 2 CPUs, max parallelism 1
* `low`: `10g`, 2 CPUs, max parallelism 1
* `serial`: `10g`, 1 CPU, max parallelism 1
* `minimal`: `8g`, 1 CPU, max parallelism 1
* `floor`: `6g`, 1 CPU, max parallelism 1

The `serial` profile intentionally keeps the `low` memory cap while reducing
Next/Turbo concurrency. Prefer that retry before shrinking the BuildKit memory
cap when `low` gets through compilation or page-data work but exits with code
137\.

If the floor profile still fails with the same BuildKit infrastructure
signature, the helper resets the machine-local profile back to the
budget-derived `default` profile. If that profile also fails and Docker's
reported memory limit can safely fit a larger fixed profile, the helper can
retry `low` (`10g`) before surfacing the failure. This prevents a machine from
getting stuck starting every future deploy at `floor` while still allowing
memory-starved Next builds to recover on Docker VMs with enough real capacity.
Delete `tmp/docker-web/buildkit/resource-profile.json` only as an emergency
manual reset back to the default profile. Explicit build cap flags or
`DOCKER_WEB_BUILD_MEMORY`, `DOCKER_WEB_BUILD_CPUS`, or
`DOCKER_WEB_BUILD_MAX_PARALLELISM` opt out of the adaptive profile for that run.

You can still override those defaults per run by appending your own flags after
`--`, for example:

```bash theme={null}
bun serve:web:docker:bg -- --build-memory 16g --build-cpus 4 --build-max-parallelism 2
```

Equivalent environment variables:

* `DOCKER_WEB_BUILD_MEMORY=16g`
* `DOCKER_WEB_BUILD_CPUS=4`
* `DOCKER_WEB_BUILD_MAX_PARALLELISM=2`
* `DOCKER_WEB_BUILD_BUILDER_NAME=tuturuuu`
* `DOCKER_WEB_BUILDKIT_PORT=7914`
* `DOCKER_WEB_BUILDKIT_ENDPOINT=tcp://127.0.0.1:7914`
* `DOCKER_WEB_BUILDKIT_PRUNE_AFTER_BUILD=0` for blue/green watcher handoffs
* `DOCKER_WEB_BUILDKIT_PRUNE_MODE=bounded|all|off` (`bounded` is the default)
* `DOCKER_WEB_BUILDKIT_PRUNE_UNTIL=168h`
* `DOCKER_WEB_BUILDKIT_PRUNE_KEEP_STORAGE=50gb`
* `DOCKER_WEB_BUILDKIT_STOP_AFTER_BUILD=0` to keep the `buildkit` container
  warm after a build
* `DOCKER_WEB_DOCKER_MEMORY_LIMIT=<bytes from docker info>`
* `DOCKER_WEB_STATIC_PAGE_GENERATION_TIMEOUT=180`
* `DOCKER_WEB_STATIC_GENERATION_MAX_CONCURRENCY=auto`
* `DOCKER_WEB_NEXT_BUILD_CPUS=auto`
* `DOCKER_WEB_NEXT_APP_ONLY=1`
* `DOCKER_WEB_NODE_MAX_OLD_SPACE_SIZE=auto`
* `DOCKER_WEB_NEXT_BUILD_ENGINE=turbopack`
* `DOCKER_WEB_REACT_COMPILER=1`

How it works:

* The helper starts the Compose-owned `buildkit` service and then creates or
  reuses the remote Buildx builder named by `DOCKER_WEB_BUILD_BUILDER_NAME`.
  The container is named `${COMPOSE_PROJECT_NAME:-tuturuuu}-buildkit-1`, so it
  stays visually grouped under the `tuturuuu` Docker Desktop stack.
* The BuildKit caps accept `auto`. Auto memory uses Docker's reported memory
  limit minus a small host overhead buffer, rounded down to MiB precision; auto
  CPU uses 1 CPU below 10 GB, 2 CPUs below 16 GB, and 4 CPUs on larger Docker
  allocations; auto max parallelism uses 1 below 16 GB and 2 above that. The
  E2E runner and production web serve scripts use auto memory by default so
  local Playwright verification and watcher builds adapt to the current Docker
  Desktop setting without requiring one-off env overrides.
* `DOCKER_WEB_BUILD_MEMORY` caps the Compose-owned BuildKit service's memory
  budget.
* `DOCKER_WEB_BUILD_CPUS` sets the BuildKit service CPU budget.
* `DOCKER_WEB_BUILD_MAX_PARALLELISM` writes a BuildKit config that limits
  concurrent solve steps, which is often the most effective way to reduce
  CPU spikes on smaller machines.
* Host-side helper runs point Buildx at
  `DOCKER_WEB_BUILDKIT_ENDPOINT` (default
  `tcp://127.0.0.1:${DOCKER_WEB_BUILDKIT_PORT:-7914}`). The watcher container
  uses `tcp://buildkit:1234` on the Compose network.
* Blue/green watcher handoffs preserve the Compose-owned BuildKit cache volume
  by default (`DOCKER_WEB_BUILDKIT_PRUNE_AFTER_BUILD=0`), but stop and remove
  the `buildkit` container after the build/deploy phase
  (`DOCKER_WEB_BUILDKIT_STOP_AFTER_BUILD=1`). This frees idle CPU and memory
  while keeping layer state for the next deployment. Set
  `DOCKER_WEB_BUILDKIT_STOP_AFTER_BUILD=0` only when an operator intentionally
  wants BuildKit to stay warm after a handoff.
* When BuildKit pruning is enabled, the default mode is bounded: the helper runs
  `docker buildx prune --filter until=168h --keep-storage 50gb` for the active
  builder. Use `DOCKER_WEB_BUILDKIT_PRUNE_MODE=all` only for disposable build
  state, or `DOCKER_WEB_BUILDKIT_PRUNE_MODE=off` to skip pruning without
  changing older `DOCKER_WEB_BUILDKIT_PRUNE_AFTER_BUILD` callers.
* Dockerized E2E is the exception: its per-run BuildKit state is disposable and
  `scripts/run-web-e2e-docker.js` sets
  `DOCKER_WEB_BUILDKIT_PRUNE_AFTER_BUILD=1` and
  `DOCKER_WEB_BUILDKIT_PRUNE_MODE=all` unless explicitly overridden.
* The same max-parallelism value is also forwarded as `COMPOSE_PARALLEL_LIMIT`
  when that variable is not already set. When the limit is `1`, the blue/green
  workflow builds each Bake target group separately so image export and web
  compilation do not overlap on memory-constrained hosts.
* When Docker reports less than 10 GB of total memory for a blue/green run, the
  helper also restarts the Compose-owned `buildkit` service immediately before
  the build batch. This clears long-lived BuildKit RSS before the replacement
  web image builds while the active lane is still running. Set
  `DOCKER_WEB_BUILDKIT_RESTART_BEFORE_BUILD=0` to skip that low-memory
  restart, or `1` to force it on a larger host.
* Docker web builds use `bun run build:web:docker`, which keeps the normal web
  build dependency graph, sets `NODE_OPTIONS=--max-old-space-size` to at least
  4 GB on Docker allocations below 10 GB, then scales to 8 GB, 12 GB, or 16 GB
  based on the lower of Docker's reported memory limit and the selected BuildKit
  memory cap, falling back to `DOCKER_WEB_BUILD_MEMORY` for environments where
  Docker memory cannot be detected. The helper reads Docker's `MemTotal` and
  forwards it as `DOCKER_WEB_DOCKER_MEMORY_LIMIT`; auto buckets reserve 1 GB of
  effective Docker build memory for BuildKit, the active runtime lane, and
  sidecar overhead before selecting the Node heap bucket on larger allocations.
  Docker production builds use Turbopack under the real Node 24 runtime with App
  Router-only compilation and React Compiler enabled. This avoids Bun runtime
  crashes while loading native Next SWC modules and keeps local E2E aligned with
  production Docker builds.
  The Docker `builder` stage is based on
  `node:24-bookworm-slim` and copies the Bun binary in only for workspace script
  orchestration, so the actual `next build` process runs under real Node instead
  of Bun's `node` shim. The `@tuturuuu/web` `build:docker` script delegates to
  `scripts/run-web-docker-next-build.js`, which spawns `DOCKER_WEB_NODE_BINARY`
  (pinned by the Dockerfile to `/usr/local/bin/node`) for the Next CLI and
  honors `DOCKER_WEB_NODE_MAX_OLD_SPACE_SIZE=auto` by default. Set a numeric
  heap value only when you need to override the bucket selection; values below
  4096 MB are rejected. Set `DOCKER_WEB_NEXT_APP_ONLY=0` only when you need to
  compare a full-app build.
  Keep `DOCKER_WEB_NEXT_BUILD_ENGINE` on its default Turbopack value for
  production watcher hosts and local E2E runs. The wrapper also passes
  Turbo's `--concurrency` flag inside the Dockerfile build. It uses
  `DOCKER_WEB_TURBO_CONCURRENCY` when explicitly set, otherwise it follows the
  current `DOCKER_WEB_BUILD_MAX_PARALLELISM` profile value and defaults to `1`.
  BuildKit max parallelism limits Docker build graph execution; this inner
  Turbo cap limits concurrent workspace package builds such as
  `@tuturuuu/types`, `@tuturuuu/devbox`, and `@tuturuuu/masonry`.
* Docker standalone Next builds default static page generation to a 180 second
  timeout. Legacy all-in-Docker builds auto-scale the inner Next build CPU count
  plus static generation concurrency from Docker memory. Docker allocations
  below 10 GB use 1 Next build CPU and static generation concurrency 1; 10-16 GB
  allocations use 2 for both; 16 GB and larger allocations use 4 for both. The
  Compose-owned BuildKit service still defaults to a 4 CPU budget, while the
  inner Next workers stay lower on smaller hosts to avoid OOM kills when the
  same machine is also running the active blue/green lane and sidecars. Native
  host builds do not set `DOCKER_WEB_STATIC_GENERATION_MAX_CONCURRENCY` or
  `DOCKER_WEB_NEXT_BUILD_CPUS` unless the operator explicitly provides them.
  Override those with `DOCKER_WEB_STATIC_PAGE_GENERATION_TIMEOUT`,
  `DOCKER_WEB_STATIC_GENERATION_MAX_CONCURRENCY`, and
  `DOCKER_WEB_NEXT_BUILD_CPUS` only when a host needs a fixed worker count.
* Hive Docker images use a filtered workspace install and a Next standalone
  runner. Before `apps/hive` runs `next build`, the image must build
  `@tuturuuu/types`, `@tuturuuu/internal-api`, and `@tuturuuu/supabase` because
  those packages expose production `dist/*` subpath exports that Turbopack
  resolves during the standalone build. Hive realtime installs its filtered
  production workspace with Bun's hoisted linker so the direct
  `bun apps/hive-realtime/src/index.ts` runtime can resolve top-level production
  packages such as `postgres` and `@tuturuuu/realtime`. Keep `.dockerignore`
  explicit about recursive generated directories such as `**/.next/**`,
  `tmp/**`, and `apps/mobile/build/**`; otherwise previous local builds can be
  copied into the next Docker context and inflate small sidecar images by
  several gigabytes.

Operational notes:

* These caps affect image builds, not the runtime `apps/web` container after it
  has started.
* If no build caps are configured, the helper continues using Docker's default
  builder behavior.
* Do not switch capped builds back to the Buildx `docker-container` driver. It
  creates Docker-managed containers named like `buildx_buildkit_*` outside the
  Compose project, which makes Docker Desktop grouping and health reporting
  confusing.
* During capped-build setup, the helper removes known legacy Buildx builders
  such as `platform-web-capped-builder` before creating or reusing the
  Compose-owned remote `tuturuuu` builder. If `docker buildx ls` still shows
  that legacy builder, run the capped web deploy helper once so it can clean up
  the stale Buildx record.
* A lower parallelism setting usually trades build speed for host stability.
* If BuildKit fails with `ResourceExhausted`, `cannot allocate memory`, or exit
  code 137 while host memory still appears available, Docker's VM/cgroup budget
  is the relevant build budget. Prefer the default `--build-memory auto` path:
  it now uses a conservative budget and still lets the adaptive profile lower
  pressure automatically. Raise `DOCKER_WEB_BUILD_MEMORY`/`--build-memory` only
  when `docker info` shows enough Docker memory and host swap is not saturated.
* Docker Desktop resource graphs can show memory near the configured maximum
  because the Docker VM and file cache are preallocated or cached. Treat
  `docker info --format '{{json .MemTotal}}'` as the build budget source of
  truth, then use process/container RSS and BuildKit errors to decide whether
  the build is truly exhausting memory.
* If `docker compose` reports `services[buildkit].mem_limit invalid size:
  'auto'`, the command path is bypassing the Docker web helper's Compose env
  resolver or the host is running an older commit. The helper-only `auto` value
  must be converted to a concrete MiB value before any `docker compose up`,
  `restart`, `stop`, `rm`, or health-check call reads the BuildKit service.
* If host memory or swap is saturated, lower `--build-max-parallelism` first
  and stop unrelated containers before raising the builder memory cap.
* If the build loops on exit code 137 or `SIGSEGV (Address boundary error)`
  inside `@tuturuuu/*:build` package tasks, treat it as inner Turbo concurrency
  pressure in addition to BuildKit pressure. Keep the default Docker web helper
  profile so `DOCKER_WEB_BUILD_MAX_PARALLELISM=1` reaches the Dockerfile build,
  or set `DOCKER_WEB_TURBO_CONCURRENCY=1` explicitly for a one-off recovery.
* If the default blue/green deploy keeps failing with BuildKit transport EOFs,
  `context deadline exceeded`, `[internal] waiting for connection`, or
  graceful-stop messages, leave the root-script defaults in place and let the
  adaptive profile step down through the lower profiles automatically. Use
  `docker buildx ls` or
  `docker buildx inspect tuturuuu` to confirm whether the remote builder is
  inactive. Use explicit caps only when you want to bypass the remembered local
  profile for a one-off run.
* If Bun fails during an image install with a tarball extraction error such as
  `Fail extracting tarball for "@biomejs/cli-linux-x64"`, the blue/green helper
  treats it as BuildKit exec-cache corruption once per deployment attempt. It
  prunes BuildKit exec cache mounts, recreates the Compose-owned `buildkit`
  service, and retries the build once with `--no-cache`. If the prune command
  fails because BuildKit has already dropped transport, recovery still proceeds
  to service recreation. A second failure is recorded as a real deployment
  failure with the original command context preserved in logs.
* If BuildKit reports `CACHED ERROR` after a failed deps stage, or if the
  compose build exceeds `DOCKER_WEB_BUILD_TIMEOUT_MS` (default 45 minutes), the
  helper uses the same one-time cache recovery and fresh `--no-cache` retry.
* If a deployment fails during the build, the watcher captures the actionable
  failure lines into the retained deployment history as `failureReason`. The
  Infrastructure → Monitoring → Deployments page and rollout ledger display that
  reason inline so operators do not need to reconstruct failures from a terminal
  scrollback.

## Redis Profile

Redis is enabled by default in both dev and production-style Docker web stacks.
The Redis and `serverless-redis-http` host ports bind to `127.0.0.1` only; do
not expose them through Cloudflare Tunnel, public firewall rules, or
all-interface Docker port mappings.

The helper persists the generated token in:

* `tmp/docker-web/redis-token`

and injects these values into `apps/web` automatically:

* `UPSTASH_REDIS_REST_URL=http://serverless-redis-http:80`
* `UPSTASH_REDIS_REST_TOKEN=&lt;generated local token&gt;`

The production Redis compose fragment requires `UPSTASH_REDIS_REST_TOKEN` during
Compose interpolation. Use the Docker web helper, which injects the generated
token automatically, or export a strong token before running direct
`docker compose --profile redis ...` commands. Service `env_file` entries do
not satisfy Compose interpolation for the Redis HTTP bridge token.

Docker Redis mode intentionally ignores generic `UPSTASH_REDIS_REST_URL` and
`UPSTASH_REDIS_REST_TOKEN` values from the host shell. This prevents old Upstash
REST URLs from leaking into self-hosted Docker containers after the Upstash
instance is shut down. If a Docker host must override the bundled Redis sidecar,
use the Docker-specific `DOCKER_UPSTASH_REDIS_REST_URL` and
`DOCKER_UPSTASH_REDIS_REST_TOKEN` variables.

Watcher-managed Infrastructure projects do not receive the integrated platform
Docker Redis token. New managed projects start with `redis_enabled=false`, and a
project with Redis enabled receives `UPSTASH_REDIS_REST_URL`,
`UPSTASH_REDIS_REST_TOKEN`, and `SRH_TOKEN` only when project-scoped credentials
are set with `MANAGED_PROJECT_<PROJECT_ID>_UPSTASH_REDIS_REST_URL` and
`MANAGED_PROJECT_<PROJECT_ID>_UPSTASH_REDIS_REST_TOKEN`, where `<PROJECT_ID>` is
the normalized project id uppercased with dashes converted to underscores.
Generic host `UPSTASH_REDIS_REST_*` and Docker-specific `DOCKER_UPSTASH_*`
values are stripped from managed project compose runs so untrusted project code
cannot access platform Redis credentials.

If you intentionally want to exercise Redis-unavailable fail-open behavior, opt
out:

```bash theme={null}
bun dev:web:docker -- --without-redis
```

That opt-out disables both the bundled Redis companion services and the
Docker-injected `UPSTASH_REDIS_REST_URL` / `UPSTASH_REDIS_REST_TOKEN`
variables. `apps/web` treats Redis-backed route rate limits, abuse counters, and
IP blocks as fail-open availability guardrails in this mode: requests continue
through normal auth, authorization, payload-size, Turnstile, suspension, and
validation checks, but rate-limit buckets and IP-block enforcement are skipped.
Defense-in-depth one-time state such as CLI refresh-token replay protection also
continues without Redis after JWT validation and user lookup. Confirmed
Redis-backed replay attempts are still rejected when Redis is available.

Vercel-hosted satellite apps such as CMS, Calendar, Finance, Learn, Teach, and
Tasks cannot reach Docker-private Redis hosts such as `serverless-redis-http`.
Do not point their Vercel `UPSTASH_REDIS_REST_URL` at the Docker sidecar or
expose Redis through Cloudflare Tunnel. Satellite proxy guards should run
without Redis when Upstash is retired; protected product APIs continue to flow
through `apps/web`, where Docker Redis is available.

## Cloudflare Tunnel Profile

The Docker compose files include an optional `cloudflared` service. Enable it
when the same host should publish the Dockerized web proxy through Cloudflare
Tunnel:

```bash theme={null}
bun serve:web:docker:bg -- --with-cloudflared
```

Required env:

* `CF_TUNNEL_TOKEN`, `CLOUDFLARED_TOKEN`, or `DOCKER_CLOUDFLARED_TOKEN`

When root `.env.local` contains a non-empty `CF_TUNNEL_TOKEN`, Docker web
helpers automatically enable the `cloudflared` profile and pass the value to
Compose as `CLOUDFLARED_TOKEN`. If `--env-file` is passed, the helper applies
the same auto-detection to that explicit file. Set
`DOCKER_WEB_WITH_CLOUDFLARED=0` to keep a configured tunnel token available
without starting the `cloudflared` container; an explicit `--with-cloudflared`
or `--profile cloudflared` still enables the profile.

For a remotely managed Cloudflare Tunnel, configure the public hostname route in
Cloudflare to point at the Docker service or the local proxy loopback:

* Production blue/green: `https://tuturuuu.com` -> `http://localhost:7803` or
  `http://web-proxy:7803`
* Dev stack: `https://dev.tuturuuu.com` or a temporary hostname ->
  `http://localhost:7803` or `http://web:7803`

The tunnel container shares the web/proxy network namespace, so existing
Cloudflare routes that use `localhost:7803` resolve to the Docker web service
instead of the tunnel container itself. Keep `cms.tuturuuu.com` and other
satellite app hostnames on Vercel unless those apps are explicitly moved into
this Docker stack.

Production compose binds host-published web, Hive, Meet, and Redis ports to
`127.0.0.1` only. Do not remove that loopback prefix during blue/green
migration; public exposure should go through Cloudflare Tunnel or another
controlled frontend, not the staged Docker host ports.

When blue/green is deployed with `--with-cloudflared`, the watcher receives
`DOCKER_WEB_WITH_CLOUDFLARED=1` so future auto-deploys keep the tunnel profile
active and do not remove the `cloudflared` container as an orphan.

## Auto-Pull Blue/Green Watcher

For simple self-hosted boxes that deploy directly from a Git branch, the repo
also provides a long-running auto-deploy watcher:

```bash theme={null}
bun serve:web:docker:bg:watch
```

That command now bootstraps Docker instead of running the watcher loop as a
host PID. Each invocation:

1. Writes the forwarded watcher CLI args to `tmp/docker-web/watch/blue-green-auto-deploy.args.json`.
2. Rebuilds and force-recreates the dedicated `web-blue-green-watcher` service.
3. Builds and force-recreates `web-docker-control` so direct admin recovery
   uses the current sidecar code.
4. Builds and starts `web-cron-runner` with `--no-recreate` so native Docker
   cron stays available without interrupting a healthy runner.
5. Tails the watcher container's live logs so the terminal still shows the
   watcher dashboard.

The watcher container mounts:

* the repo worktree at `/workspace`
* the same repo again at the real host checkout path via
  `PLATFORM_HOST_WORKSPACE_DIR`, so host Docker bind mounts resolve against
  the host filesystem when the watcher shells into `docker compose ...`
* the linked-worktree common Git directory through `DOCKER_WEB_GIT_COMMON_DIR`
  when `.git` is a file, so in-container Git commands can resolve
  `.git/worktrees/...` metadata from Docker-mounted checkouts
* `/var/run/docker.sock` so it can manage the blue/green compose stack itself
* the shared Bun install cache volume
* a dedicated watcher `node_modules` volume so the frozen dependency install
  stays container-local

Behavior:

1. Reads the built-in `platform` project from the log-drain Postgres project registry. The production watcher service is wired with `PLATFORM_LOG_DRAIN_DATABASE_URL` so a live watcher can consume queued Infrastructure project deployments instead of falling back to the legacy single-branch loop.
2. The seeded branch is `production`, but operators can change it from Infrastructure → Monitoring → Projects. If the selected project branch differs from the current checkout, the watcher restarts its child process, resets tracked changes, removes untracked files, fetches, and checks out that branch. Set `DOCKER_WEB_WATCHER_WORKTREE_RESET_DISABLED=1` to restore the protective dirty-worktree block instead. If the watcher is already stuck or missing, the monitoring UI asks `web-docker-control` to ensure the watcher before ensuring or restarting `web-cron-runner`. If direct control is unavailable, the UI keeps the stalled request visible so host supervisor recovery can be diagnosed instead of appearing queued forever.
3. Locks the selected local branch and tracked upstream at startup.
4. Writes a PID-backed lock file at `tmp/docker-web/watch/blue-green-auto-deploy.lock`.
5. Renders a live terminal dashboard with the locked branch, tracked upstream,
   latest local commit, relative commit age, last check time, next poll time,
   current blue/green runtime state, and recent watcher events.
6. Polls the tracked upstream every `1000ms` by default.
7. Auto-clears and redraws the dashboard in place on each state change when
   attached to a TTY.
8. Runs the Git and deploy subprocesses quietly so the dashboard is not
   disrupted by `git fetch`, `git reset`, or Docker build output during normal
   watcher operation.
9. Treats the watcher-managed checkout as disposable by default. Before each
   upstream comparison it runs `git reset --hard HEAD`, `git clean -fd`,
   fetches the locked upstream, and hard-resets to the tracked upstream when
   local `HEAD` is behind, ahead, or diverged. Ignored files are left alone.
10. Set `DOCKER_WEB_WATCHER_WORKTREE_RESET_DISABLED=1` only when you need to
    preserve manual edits in a deployment clone. With that escape hatch, dirty
    worktrees block polling, ahead/diverged branches are skipped, and only
    fast-forward pulls are attempted.
11. Runs `bun install --frozen-lockfile` automatically after every successful
    upstream sync so installed dependencies match the reviewed `bun.lock`
    before the deploy handoff continues. The watcher does not run `bun upgrade`
    or a non-frozen install on the production host.
12. Resets dirty `bun.lock` changes by default with the rest of the disposable
    checkout. When `DOCKER_WEB_WATCHER_WORKTREE_RESET_DISABLED=1` is set,
    dirty `bun.lock` remains a blocking worktree change.
13. Runs `bun serve:web:docker:bg` automatically after a successful upstream
    sync.
14. Polls imported Infrastructure projects from log-drain Postgres, synchronizes enabled public GitHub projects into `tmp/docker-web/projects/<projectId>/repo`, deploys them through generated Next.js compose files under the shared `tuturuuu` Compose project, and merges hostname routes into the central nginx proxy.
    The imported-project and manual deployment queue cadence is independent
    from the normal Git polling interval, so a watcher configured with a long
    Git interval such as 1000 seconds still wakes on the shorter project queue
    interval to advance queued Deploy actions.
    Platform project state is updated on both queue-only deploys and normal
    upstream deploys, so a successful sync/deploy clears `queued` and
    refreshes the latest commit columns instead of relying only on deployment
    history.
    Imported project builds share the same deployment build lock as platform
    blue/green builds. If platform, standby, recovery, or another imported
    project build is already active, the project poll is deferred instead of
    starting a second Docker build.
15. The watcher no longer prebuilds `main` or advances `production` on its own.
    Advance production outside the watcher through the release process, then
    let the watcher deploy the locked branch that is already checked out on the
    host.
16. Rollback pins intentionally pause normal upstream sync for the pinned
    deployment state. Remove the pin when the locked branch contains the
    corrective commit that should resume normal deployment.
17. Infrastructure operators can queue
    `tmp/docker-web/watch/control/blue-green-deployment-revert.request.json`
    to revert production to a retained successful deployment. The watcher keeps
    the 5 newest unique successful deployed image tags for instant revert; a
    cached revert verifies the cached target first, cancels any active
    blue/green build,
    retags the selected image, starts active/standby with `--no-build`,
    health-checks through the normal proxy path, records deployment kind
    `instant-revert`, and writes a deployment pin so normal upstream
    deployment does not immediately overwrite the rollback. Older retained deployments remain
    revertable through the existing rollback pin path, which may rebuild
    because no cached image is available and still respects the active build
    lock.
18. After forward database migrations finish, blue/green workflows remove
    completed `hive-db-migrate` and `supermemory-db-migrate` containers by
    Compose service labels. This catches stopped one-off `docker compose run`
    containers such as `tuturuuu-hive-db-migrate-*` that can otherwise make the
    Docker cluster look unhealthy even after the migration succeeded.
19. If watcher runtime code such as `scripts/watch-blue-green-deploy.js`,
    `scripts/docker-web/blue-green.js`, or `scripts/docker-web/env.js` changed
    in the pulled revision, the current watcher does not deploy from the old
    process. It releases its lock, spawns a replacement watcher with the same
    CLI args, and exits first.
20. The replacement watcher refreshes the live `web-proxy` nginx config and
    workers in place if blue/green is already serving traffic, verifies proxy
    routing through `/__platform/drain-status`, and only then starts the new
    blue/green build/promotion.
21. If compose or helper-image wiring changed, including
    `docker-compose.web.prod.yml`, Hive service files, MarkItDown service files,
    `apps/storage-unzip-proxy` package/source files, or
    `apps/web/docker/cron-runner*`, the containerized watcher recreates its own
    compose service before the pending deploy handoff. The deploy then includes
    only the affected buildable helper images in the blue/green build command
    instead of rebuilding every service on every commit.
22. Retries recoverable Git command failures instead of exiting. The first retry
    waits 1 minute, then the watcher backs off exponentially on consecutive Git
    failures up to a 15 minute ceiling.
23. Caps deployment attempts at 3 failures per commit. A recovered pending
    handoff failure is recorded, the pending request is cleared, and the
    watcher keeps polling; once the cap is reached, that commit reports
    `retry-limited` until a new commit is available or an operator pins a
    different deployment.
24. Stops immediately if the checked-out branch changes while the watcher is
    running.
25. If another watcher already owns the lock, a new invocation can fail with
    guidance, mirror the active watcher with `--resume-if-running`, or replace
    it with `--replace-existing`.

Operational notes for the containerized watcher:

* Manual `bun serve:web:docker:bg` and watcher-triggered deploys share a
  deployment-build lock at
  `tmp/docker-web/watch/blue-green-deployment-build.lock`. This lock is
  separate from `blue-green-auto-deploy.lock`: the watcher may remain alive, but
  only one build/deploy phase can be active across manual deploys, watcher
  upstream sync, standby refreshes, rollback pins, cached recovery, and
  reconcile deploys.
* If a manual deploy sees that lock or a live watcher status of `building` or
  `deploying`, an interactive terminal prompts before it interrupts the active
  deployment. Confirming stops `web-blue-green-watcher`, stops/resets the
  Compose-owned BuildKit work, clears the active build lock/status, records the
  interrupted entry as `canceled`, then starts the requested deployment alone.
* Non-interactive manual automation fails fast on an active deployment unless
  `--cancel-active-build` or `DOCKER_WEB_CANCEL_ACTIVE_BUILD=1` is provided.
  Use that override only when it is acceptable to interrupt all BuildKit work
  owned by the platform deployment stack.
* Re-running `bun serve:web:docker:bg:watch` intentionally recreates the
  watcher container so it picks up local repo changes, new CLI args, and
  watcher-image updates in one path.
* The host log follower treats Docker's `143` exit from an intentionally
  recreated watcher container as a reconnect signal, then reattaches to the
  replacement service instead of leaving the terminal dark.
* If the followed watcher logs explicitly request host-supervised watcher
  service recreation, the host wrapper force-recreates `web-blue-green-watcher`
  before reattaching. Do not rely only on Docker's restart policy in this path:
  the old container can briefly report healthy while still running the stale
  image/runtime.
* Git fetch/pull credentials now need to be usable inside the watcher
  container because the watcher no longer runs directly on the host.
* Full Docker daemon or Docker Desktop crashes cannot be recovered by a watcher
  that is itself running inside Docker. Keep `bun serve:web:docker:bg:watch`
  running from the host, ideally under `systemd`, `launchd`, or another host
  process supervisor. That host command waits for the Docker daemon to respond
  again, reruns the watcher compose `up --build --detach --force-recreate`, and
  then resumes tailing logs. Every hosted project with its own Docker watcher
  needs its own host-side watch process; container `restart:` policies only help
  after Docker is already healthy again.
* The host Docker recovery loop polls bounded Docker CLI probes every 5 seconds
  by default. Override with `DOCKER_WEB_WATCHER_DOCKER_RECOVERY_POLL_MS`; tune
  each quick probe with `DOCKER_WEB_WATCHER_DOCKER_PROBE_TIMEOUT_MS`. By default
  it waits indefinitely because a host process manager is expected to own the
  terminal process; set `DOCKER_WEB_WATCHER_DOCKER_RECOVERY_TIMEOUT_MS` to a
  positive value to fail after a bounded recovery window.
* The watcher image lives at `apps/web/docker/blue-green-watcher.Dockerfile`.
* Its entrypoint wrapper relaunches the watcher in-place when
  `scripts/watch-blue-green-deploy.js` requests a self-restart after pulling a
  new watcher revision.
* The entrypoint is also the watcher supervisor. It restarts the child process
  after crashes, after the status snapshot fails to appear during startup, or
  after `blue-green-auto-deploy.status.json` becomes stale. The compose service
  uses `restart: unless-stopped` so Docker also brings the watcher back after a
  daemon or container failure.
* A stale status snapshot is tolerated while the snapshot already shows an
  active `building` or `deploying` deployment. During a long `docker compose
  build`, the watcher child is intentionally busy inside the deploy command and
  may not rewrite the status file until the command exits. The wrapper keeps the
  child alive until `DOCKER_WEB_WATCHER_BUILD_TIMEOUT_MS` plus a short grace
  window, then treats the stale snapshot as unhealthy.
* `bun serve:web:docker:bg:down` also stops the watcher service because it is
  part of the production compose stack now.

Dashboard details:

* Shows the current active blue/green color when `web-proxy` is serving live
  traffic.

* Docker resource rows use the running containers directly as a fallback when
  `docker compose ps` cannot inspect the prod stack because of env
  interpolation issues, so watcher metrics can still appear on an already-live
  deployment.

* Docker stats are read with an explicit field format instead of Docker's
  version-dependent JSON object shape, which avoids bogus `0` CPU/memory
  readings when the watcher is running against a different Docker release.

* The watcher parser also normalizes locale-style decimal commas from
  `docker stats`, so hosts that emit values like `0,10%` or `24,0MiB` no
  longer collapse into zeroed metrics.

* Each watcher snapshot now includes `docker ps` metadata for every running
  container visible through the host Docker socket, plus compose service health
  for containers in the production project. The monitoring overview uses that
  persisted snapshot to show service health and a full running-container
  inventory without mounting the Docker socket into `apps/web`.

* The request archive view computes route summaries, status totals, RSC counts,
  and error totals across the selected timeframe instead of only the visible
  page. The default timeframe is seven days, the API rejects unbounded or
  oversized windows, and operators can query at most 30 days of retained request
  logs at a time. The web API keeps a short in-process aggregate cache keyed by
  bounded timeframe plus telemetry log file stats, but the cache stores only
  aggregate analytics so request rows are not retained in memory between page
  reads.

* Drive ZIP extraction does not stream extracted file bytes back through the web
  app proxy. The unzip worker requests a per-entry signed upload URL from the
  callback route and uploads extracted files directly to trusted storage
  origins only, which avoids nginx body-size limits for large WebGL artifacts
  while keeping folder creation and auth checks in the backend callback.

* Hive is promoted with the web blue/green color: `hive-blue` and `hive-green`
  are routed from `hive.tuturuuu.com`, and `hive-realtime` serves `/realtime` with
  `HIVE_REALTIME_TOKEN_SECRET`, `HIVE_REALTIME_URL`, and
  `NEXT_PUBLIC_HIVE_REALTIME_URL` configured in the same production stack.
  Hive product data is stored in the Docker-managed `hive-postgres` service via
  `HIVE_DATABASE_URL`; Supabase remains the identity/session source only. The
  `web`, `web-cron-runner`, `hive-{color}`, and `hive-realtime` services must
  all receive that URL so API routes, disabled-by-default simulation cron, the
  editor, and the CRDT realtime service share the same Hive product database.
  Optional local LLM support runs behind the `hive-ollama` profile and is
  disabled unless operators enable the profile and Hive settings enable the
  exact `gemma4` model.
  Production compose publishes **`127.0.0.1:7814:7814`** from `web-proxy`, not
  from a direct Hive container, so host-local or Cloudflare tunnel traffic to
  `localhost:7814` always reaches the currently promoted Hive color without
  exposing staged migration ports on every host interface.
  Deploys verify that the running `web-proxy` container has the required
  loopback host bindings (`7803`, `7814`, and `7816`) and that its running image
  matches the resolved Compose image before reusing it; if an older proxy was
  created before Hive moved behind blue/green or before the nginx image pin
  changed, the next deploy force-recreates the proxy so the host-level
  Cloudflare Tunnel route can reach Hive on the expected proxy runtime.
  The Hive color services use the same Supabase env source as `apps/web`:
  runtime env files are shared, and production image builds mount the `web_env`
  BuildKit secret so hidden-locale auth pages can prerender with the platform
  Supabase URL.
  **Deploy coordination:** `scripts/docker-web/blue-green.js` still scopes prod
  builds by changed service group, but runtime promotion happens in staged
  order: first the target `web-{color}`, then `hive-{color}` and
  `hive-realtime`, then refreshed support services such as backend,
  MarkItDown, storage-unzip-proxy, `web-cron-runner`, and optional Redis-backed
  helpers. If `web-proxy` or `cloudflared` must be bootstrapped or recreated for
  host-port changes, they start only after target web, Hive, and support
  services are healthy, so `hive.tuturuuu.com` is not exposed with an empty
  `hive_app_upstream` and web is not publicly switched before dependent gates
  finish. Promotion waits for the final proxy route check before writing
  `active-color`.

* Every service owned by `docker-compose.web.prod.yml` should declare a
  healthcheck, either directly in compose or in the image. The resources
  inventory treats an `Up` container without Docker health metadata as healthy
  for cross-project runtime visibility, but first-party prod services and
  sidecars still need explicit probes so deploy gates can fail before promotion.

* The MarkItDown sidecar needs `SUPABASE_URL` set to the same Docker-internal
  Supabase URL used by the web container. The service validates signed Storage
  URLs before downloading attachments, and local Docker runs may use
  `host.docker.internal` over HTTP.

* MarkItDown source changes and storage-unzip-proxy package/source changes are
  part of the watcher refresh globs. Keep those globs in sync with any future
  sidecar entrypoints so a running watcher refreshes helper containers during
  the next deploy handoff, not just the web app container.

* Host dependency refreshes must not rewrite `bun.lock` on the production host.
  The watcher resets a dirty lockfile by default with the rest of the disposable
  deployment checkout. With `DOCKER_WEB_WATCHER_WORKTREE_RESET_DISABLED=1`, a
  dirty lockfile remains a blocking worktree change. Automatic dependency sync
  uses `bun install --frozen-lockfile` only.

* Runtime upgrades are an explicit operator action. The watcher does not run
  `bun upgrade`; update the host Bun runtime only after reviewing the pinned
  version in the repository and the watcher image.

* Recoverable Git poll failures stay visible in the dashboard as a retrying
  watcher state instead of terminating the process, and the next-check timer
  reflects the active backoff delay.

* If `git reset`, `git fetch`, `git checkout`, or the reset-disabled
  `git pull --ff-only` path fails only because a Git lock already exists, the
  watcher inspects the lock age. Fresh locks are polled inside the watcher
  process, then removed automatically only when they are stale (older than 2
  minutes). This covers linked-worktree `index.lock` files,
  `.git/packed-refs.lock`, and remote-ref locks such as
  `.git/refs/remotes/origin/staging.lock`.

* Build/deploy failures also stay inside the watcher loop. The watcher records
  failed attempts in deployment history, clears stale pending handoff files
  after recovery failures, and stops retrying the same commit after the third
  failed deployment attempt. Once that cap is reached, it reports the
  retry-limited state once for that commit instead of logging the same skip on
  every poll.

* Normal promotions keep the long-lived `web-proxy` container and bound port
  stable, which avoids transient listener drops for upstreams such as
  Cloudflare Tunnel that are connected to `:7803`. Proxy container recreates are
  reserved for required host-port or image drift and happen only after the
  replacement web/Hive lane is healthy.

* Persists recent deployment history, including manual
  `bun serve:web:docker:bg` runs, and renders the top 3 most operationally
  relevant entries as stacked terminal cards that favor vertical scanability
  over very wide lines.

* Each deployment card now uses a stronger header with status/color badges plus
  grouped metric bands, so active traffic state, rollout intent, and
  request-rate data are easier to scan while multiple cards are stacked.

* As soon as a new commit starts rolling out, the recent deployment section
  shows it immediately as `DEPLOYING` instead of waiting for the rollout to
  finish.

* Each deployment block includes:
  * deploy status (`ACTIVE`, `ENDED`, or `FAILED`)
  * build time
  * activation/finish time
  * deployment lifetime while it served traffic
  * total requests served during that deployment window
  * average requests per minute
  * peak requests per minute
  * `day`: requests served on the current day for the active deployment, or the
    final active day for an ended deployment
  * `davg`: average requests per day across that deployment's serving lifetime
  * `dpeak`: busiest single-day request count across that deployment's serving
    lifetime

* The live blue/green summary uses the same traffic metrics as the deployment
  history cards, with consistent color coding for build/lifetime/traffic/age
  metrics so the dashboard is easier to scan quickly.

* A dedicated Docker resources row summarizes aggregate CPU, memory, and
  network usage across the live blue/green containers, followed by a
  per-container row for `proxy`, `green`, and `blue` when those services are
  running. This is sampled from `docker stats --no-stream`, so it stays local
  to the host and is appropriate for self-hosted operator monitoring.

* The infrastructure dashboard's Docker Runtime Inventory uses the watcher
  snapshot as the source of truth for every running Compose container and
  derives total CPU and memory from those rows when present, so the summary
  cards stay aligned with the detailed container inventory.

* The bundled `serverless-redis-http` companion uses an in-container `wget`
  health check that posts `["PING"]` to `/` with the generated `SRH_TOKEN`;
  do not use a Node-based probe for that image because it is an Erlang release
  image, and do not probe `/ping` because SRH does not expose that route.

* Production Redis compose requires `UPSTASH_REDIS_REST_TOKEN` and binds Redis
  host ports to `127.0.0.1`. Do not reintroduce the
  `platform-local-redis-token` fallback in production fragments or remove the
  loopback host bind; direct Compose users must export a strong token before
  enabling the `redis` profile.

* After a successful host-triggered `serve:web:docker:bg` rollout, the Docker
  helper starts or resumes the containerized `web-blue-green-watcher` with
  `--resume-if-running`. Deploys that are already running inside the watcher
  skip that handoff via `PLATFORM_BLUE_GREEN_WATCHER_CONTAINER=1`, which avoids
  recursive watcher starts while still leaving a poller alive for future Git
  commits.

* The watcher wrapper and child process must agree on runtime files. If
  `PLATFORM_BLUE_GREEN_WATCH_ARGS_FILE`,
  `PLATFORM_BLUE_GREEN_WATCH_RUNTIME_DIR`, or
  `PLATFORM_BLUE_GREEN_WATCH_STATUS_FILE` are set, both the wrapper and child
  use those paths so the wrapper does not restart a healthy child for a missing
  status snapshot.

* Request counters now come from a persisted local proxy-log drain under
  `tmp/docker-web/watch/blue-green-request-telemetry.*`, not from one-off
  `docker logs` scrapes in the dashboard. The watcher continuously drains
  structured `web-proxy` access logs into a local ledger, so request metrics
  survive watcher restarts and do not require any external analytics service.

* Internal proxy health checks for `/api/health` and
  `/__platform/drain-status` are excluded from the request totals so the
  numbers reflect real served traffic more closely.

* The proxy now emits structured JSON access logs that include the upstream
  deployment stamp and blue/green color. That lets the watcher link requests
  back to the correct deployment instead of only estimating by time window.

* For each newly drained proxy request, the watcher also reads recent
  stdout/stderr from the selected frontend lanes (`web-blue` / `web-green` for
  `DOCKER_WEB_FRONTEND=next`, or `tanstack-web-blue` / `tanstack-web-green` for
  `DOCKER_WEB_FRONTEND=tanstack`) and stores up to 20 route console lines that
  fall inside the request latency window. Those captured lines are persisted on
  the request-log record itself so the request explorer can show request-scoped
  server console output after the live Docker logs have moved on.

* The watcher retains up to 10,000 deployment history entries and up to
  100,000,000 recent drained request-log records on disk, bounded by a 256 MiB
  durable request-log byte cap by default. When the next request record would
  exceed the byte cap, the watcher rotates the current JSONL chunk if needed
  and prunes older chunks before appending, so public request URIs cannot grow
  the host-backed ledger without an aggregate limit. Rolling
  daily/weekly/monthly/yearly metric buckets plus a recent-request excerpt still
  feed the monitoring dashboard.

* The watcher also persists a separate latest-log ledger under
  `tmp/docker-web/watch/blue-green-auto-deploy.logs.json`, which captures the
  high-level poll/pull/build/deploy watcher messages with deployment stamps and
  commit hashes when available. The infrastructure dashboard uses that ledger
  for a deployment-scoped latest-log view without needing live `docker logs`
  access.

* The watcher uses the same Docker runtime env resolution as the real deploy
  flow, so blue/green status probes still work when the Redis profile is part
  of the production compose file.

* The active watcher also persists a live status snapshot under
  `tmp/docker-web/watch/`, which is what `--resume-if-running` uses to mirror
  the dashboard without taking over the PID lock.

* The infrastructure dashboard at
  `/{ROOT_WORKSPACE_ID}/infrastructure/monitoring` reads the same watcher
  status snapshot and renders it as a Next.js control room with rollout,
  request-rate, container-resource, and event-feed views.

* The monitoring dashboard now exposes paginated request and watcher-log
  explorers. Route filters come from normalized request paths, the raw request
  URI still surfaces query signatures, and `?_rsc=*` requests are called out so
  React Server Component traffic is inspectable separately from document hits.

* Deployment-facing dashboard surfaces deduplicate successful blue/green rows
  for the same commit so active and standby colors do not appear as separate
  rollouts. Failed attempts remain separate because the retry cap and recovery
  debugging depend on seeing each failed build/deploy attempt. Large deployment,
  rollback-candidate, Docker-service, and container lists are paginated in the
  UI instead of rendering every retained row at once.

* Production `web`, `web-blue`, and `web-green` containers mount
  `./tmp/docker-web` read-only at `/app/runtime/docker-web` and use
  `PLATFORM_BLUE_GREEN_MONITORING_DIR` to find the watcher snapshot. Keep that
  mount/env pair in sync if the runtime path changes, or the dashboard will
  degrade to an empty offline state even while blue/green deployments still
  work.

* Production `web`, `web-blue`, and `web-green` also mount the narrower
  `./tmp/docker-web/watch/control` path read-write at
  `/app/runtime/docker-web-control` via `PLATFORM_BLUE_GREEN_CONTROL_DIR`.
  Keep operator command files in that control directory so the broader watcher
  runtime and telemetry mount can stay read-only.

* The monitoring dashboard's "Sync Standby Now" action writes
  `tmp/docker-web/watch/control/blue-green-instant-rollout.request.json`. The
  watcher consumes that file on its next poll, clears it after a success,
  failure, or no-op, and uses it to rebuild the standby color immediately so
  blue and green can converge on the same commit without waiting for the stale
  standby window.

* The dashboard reads that pending instant-rollout request back from the
  watcher control directory. While the request is queued, or while the latest
  standby refresh is building/deploying, the sync button stays disabled and
  shows a queued/building status instead of allowing duplicate control files.

* The monitoring dashboard's rollback pin action writes
  `tmp/docker-web/watch/control/blue-green-deployment-pin.json`. The watcher
  treats that file as authoritative: it skips normal fetch/pull work, checks out
  the pinned commit in detached mode, deploys it if the latest successful
  deployment is different, and keeps production on that commit until the pin is
  removed from the dashboard. Removing the pin lets the watcher check out its
  locked branch again and resume normal fast-forward polling.

* In-container watcher child restarts preserve the locked branch/upstream
  metadata even when the child is killed while Git is detached for a rollback or
  parent-fallback build. The replacement child can recover `production` from the
  target-only lock instead of trying to poll detached `HEAD`. If an older child
  already removed the lock, a clean detached startup falls back to the selected
  platform branch (`production` by default) before locking and polling.

* When the watcher receives a shutdown signal while it is temporarily detached,
  it attempts to check out the locked branch again before exiting, as long as
  the worktree is clean. This keeps manual operator commands such as
  `git pull && bun serve:web:docker:bg` from inheriting a detached checkout
  after a stopped watcher.

* The watcher image must also include both the Docker Compose and Buildx CLI
  plugins (`docker-cli-compose` and `docker-cli-buildx` on Alpine) because the
  rollout handoff shells into `docker compose ...`, and capped production
  builds create/use the remote `tuturuuu` Buildx builder from inside the watcher
  container. The watcher reaches the Compose-owned BuildKit daemon at
  `tcp://buildkit:1234`.

* When the watcher drives Docker Desktop through `/var/run/docker.sock`, it
  must run the deploy handoff from the mirrored host-path mount, not a
  container-only path like `/workspace`. Otherwise Docker Desktop rejects bind
  mounts such as `./tmp/docker-web/prod/nginx.conf` with "mounts denied"
  because `/workspace/...` is not a real shared host path.

* The watcher compose environment preserves `PLATFORM_HOST_WORKSPACE_DIR` and
  pins `COMPOSE_PROJECT_NAME` from that host checkout path unless
  `DOCKER_WEB_COMPOSE_PROJECT_NAME` is explicitly set. For linked worktrees, the
  same compose env injects `DOCKER_WEB_GIT_COMMON_DIR` and the watcher service
  mounts that directory at the same absolute path inside the container. This
  prevents `fatal: not a git repository` failures for `.git/worktrees/<name>`
  paths when `.git` points outside the worktree mount. A canonical checkout
  directory named `platform` maps to the `tuturuuu` Compose project so Docker
  Desktop groups the stack under the product name on clean startups. During
  self-refresh from an already-running legacy `platform` Compose project, the
  legacy watcher starts a staged `tuturuuu` watcher with non-conflicting host
  ports, then stops only the old watcher service. The target watcher builds or
  recovers the `tuturuuu` stack before it touches the public proxy port. When
  the target proxy is healthy on the staged port, it stops the legacy
  `platform` proxy, recreates the `tuturuuu` proxy on port `7803`, and verifies
  the internal drain-status route within 3 seconds. If that handoff exceeds
  3 seconds or the target proxy health check fails, the watcher stops the
  target proxy, restores the legacy `platform` proxy, and leaves the legacy
  project intact for another retry. After a successful handoff, it removes the
  old `platform` Compose project with `docker compose down --remove-orphans`.
  Once the legacy project is absent, a watcher that lacks inherited Compose
  project env is treated as the fully migrated `tuturuuu` watcher and remains in
  the normal Git poll/build loop instead of starting another migration handoff.
  Do not inherit arbitrary container-scoped Compose project names from the
  watcher container; doing so can create duplicate service names such as nested
  `tuturuuu-markitdown-1` containers during self-refresh.

* If Docker reports `container name ... is already in use` for a requested
  production service, the helper removes only the exact expected container name
  for the current Compose project, then retries `docker compose up`. This handles
  stale names left by interrupted rollouts without pruning unrelated containers.

* If `docker compose up` hits a transient Docker registry or Docker Hub auth
  timeout while pulling support images, the helper retries the Compose start
  without treating it as a deployment failure. Tune the bounded backoff with
  `DOCKER_WEB_COMPOSE_UP_RETRY_MAX_ATTEMPTS`,
  `DOCKER_WEB_COMPOSE_UP_RETRY_INITIAL_DELAY_MS`, and
  `DOCKER_WEB_COMPOSE_UP_RETRY_MAX_DELAY_MS`. Stale dependency container
  references use `DOCKER_WEB_COMPOSE_UP_STALE_DEPENDENCY_RETRY_MAX_ATTEMPTS`,
  so registry retry tuning cannot accidentally disable recovery from Compose
  referencing a removed dependency container. Non-transient Compose errors still
  fail immediately.

* If `log-drain-postgres` starts but remains unhealthy before promotion, the
  helper removes and recreates only that service container once, collects
  `docker compose ps`, container inspect state, recent service logs, and
  matching Compose volume names, then continues the rollout with
  `PLATFORM_LOG_DRAIN_ENABLED=false` for that run. The production `web` and
  `web-blue-green-watcher` services intentionally do not use Compose
  `depends_on` for log-drain; the script-owned preflight is the only log-drain
  gate. Platform traffic can promote while telemetry and Infrastructure project
  automation are degraded.

* Set `DOCKER_WEB_LOG_DRAIN_REQUIRED=1` when an operator wants
  `log-drain-postgres` to remain a hard deployment gate. Use that only when the
  log-drain database is part of the deployment objective and a blocked rollout
  is preferable to serving without persisted request/server logs.

* To inspect a degraded log-drain startup without changing data, run:

  ```bash theme={null}
  docker compose -f docker-compose.web.prod.yml --profile redis ps --all log-drain-postgres
  docker compose -f docker-compose.web.prod.yml --profile redis logs --tail 200 log-drain-postgres
  docker volume ls --filter label=com.docker.compose.volume=platform-log-drain-postgres
  ```

  If those logs mention incompatible database files, data-directory corruption,
  or an invalid checkpoint, back up or migrate the matching Compose volume
  before retrying. Do not run `docker compose down --volumes`,
  `docker volume rm`, or any other volume-clearing command for log-drain data
  unless an operator has explicitly approved a backed-up reset.

* Starting `bun serve:web:docker:bg:watch` now clears the persisted watcher
  status snapshot and active PID before the watcher service is force-recreated,
  but preserves any complete branch/upstream target metadata. A stale lock from
  the previous container cannot block the replacement watcher, and a detached
  checkout still has enough metadata to reattach to `production`.

* If the watcher pulls a revision that changes its own Dockerfile or baked
  entrypoint, it now rebuilds and recreates the `web-blue-green-watcher`
  service automatically before handing off to the next deployment cycle.

* When that container-refresh request is emitted from inside the followed
  watcher logs, `bun serve:web:docker:bg:watch` treats the log text itself as
  the recreate signal, then rebuilds/recreates and resumes tailing. This keeps
  the service from getting stuck in a Docker-restarted but operationally offline
  state.

* Recovery handoffs now persist a pending-deploy request under
  `tmp/docker-web/watch/` and reconcile it against the latest successful
  deployment history entry on startup. If `HEAD` is newer than the last
  successful built/deployed commit after a watcher restart or container
  recreate, the watcher builds the current `HEAD` before settling back into
  normal polling.

* The same reconciliation now also runs during steady-state polling: if Git is
  already up to date but the latest successful deployment record still points
  at an older commit, the watcher rebuilds/deploys the current `HEAD` instead
  of incorrectly reporting `up-to-date`.

* Blue/green deploys build the replacement lane before stopping or removing any
  existing blue/green container. A failed `docker compose build` must leave the
  currently serving lane and any warm standby untouched; only after the build
  succeeds may the target lane be recreated with `--no-build`.

* After a watcher-owned child deploy command fails, the watcher prunes
  failed-build residue before returning to the poll loop: it prunes the
  configured Buildx builder when `BUILDX_BUILDER` or
  `DOCKER_WEB_BUILD_BUILDER_NAME` is available, then runs
  `docker image prune --force --filter dangling=true`. Set
  `DOCKER_WEB_WATCHER_PRUNE_FAILED_BUILD_RESIDUE=0` only when an operator needs
  to preserve failed build layers for debugging. When the child deploy failed
  with a BuildKit transport/resource signature, the watcher also runs the
  best-effort exec-cache cleanup and recreates the Compose-owned `buildkit`
  service so the next poll does not inherit the dead builder endpoint.

* If `tmp/docker-web/prod/active-color` is missing or stale, the deployer and
  watcher recover the serving lane from the generated nginx proxy config before
  deciding what to rebuild. Treat the proxy config as the runtime source of
  truth during drift so a failed reconciliation cannot misclassify and clear a
  stable deployment.

## Browser-State 502 Recovery

If some normal browsers still return Cloudflare `502 Host Error`, `431`, or
Chrome `ERR_INVALID_RESPONSE` while incognito works, treat it as stale client
state or an auth-cookie/header-size problem before assuming the tunnel itself is
broken. Normal browser-state recovery should use the app route: GET is a
no-store confirmation page only, and the destructive `Clear-Site-Data` response
happens only after a same-origin POST.

Oversized request headers are different: the request may never reach Next.js.
The production `web-proxy` therefore gives web, Hive, and Meet 64 KB request
header headroom, maps Nginx `431`/`494` oversized-header failures to a local
browser-state recovery response, and the Docker web app server starts with
`--max-http-header-size=65536` so ordinary Supabase auth-cookie chunking has
matching headroom after proxying.

How to recognize each failure mode:

* `upstream sent too big header while reading response header from upstream`
  means nginx response-header buffers were too small for the auth response.
* `web-green could not be resolved` or `web-blue could not be resolved` means a
  stale nginx worker or keepalive connection still tried to reach a color that
  no longer existed. The current warm-standby model is designed to avoid that.
* A browser that fails only in regular mode but works in incognito usually has
  stale Supabase auth cookies, stale service-worker state, or both.

Recovery path:

* Send affected users to the recovery route on the affected origin:
  `https://tuturuuu.com/~recover-browser-state` for the main app, or
  `https://hive.tuturuuu.com/~recover-browser-state` for Hive.
* That route is public and bypasses auth/onboarding middleware. When the
  request can reach the app, use the confirmation form so the cookie-clearing
  POST explicitly expires Supabase auth cookie variants for the current host.
* If the browser is already sending too many stale cookies, the proxy catches
  the `431`/`494` before Next.js and returns
  `Clear-Site-Data: "cache", "cookies", "storage", "executionContexts"` while
  redirecting the browser back to `/login?browserStateReset=1`.

Operational signals:

* Inspect `X-Platform-Deployment-Stamp`, `X-Platform-Blue-Green-Primary`, and
  `X-Platform-Blue-Green-Color` response headers to confirm which rollout is
  currently serving a request.
* If the recovery URL fixes the issue for a user, the likely root cause was
  stale browser state rather than an active deploy outage.
* If recovery does not help and proxy logs still show `too big header`, focus
  on auth redirect size or additional cookie bloat.

Operational notes:

* This is intended for disposable deployment clones on a server, not for active
  developer worktrees or manual hotfix edits.
* By default the watcher resets tracked changes, deletes untracked files and
  directories, fetches, and hard-resets to the locked upstream when the local
  checkout is behind, ahead, or diverged.
* Set `DOCKER_WEB_WATCHER_WORKTREE_RESET_DISABLED=1` before starting the
  watcher to preserve the old protective behavior: dirty worktrees block,
  ahead/diverged branches are skipped, and only fast-forward pulls are
  attempted.
* The self-restart path only triggers when the watcher script itself changed in
  the fetched revision; normal app-code deploys keep the current watcher
  process alive.
* During that self-restart path, nginx keeps the assigned proxy port up the
  whole time because the replacement watcher refreshes the existing proxy
  container in place before it starts the new build.
* The watcher inherits the default blue/green build caps from
  `bun serve:web:docker:bg`, so the current defaults still apply during
  auto-deploys.
* Deployment history is watcher-managed. Manual blue/green rollouts still show
  up in the live runtime status if the stack is active, but they do not
  backfill the watcher’s last-3 deployment list unless they were performed
  through the watcher itself.
* Rollback pins are intended for bad latest deployments or failed reconciliation
  builds. Pin only a known successful deployment from the retained ledger, then
  remove the pin after `main` contains the corrective commit you want the
  watcher to resume deploying.

## Validation And CI

`docker-setup-check.yaml` now validates all of the following:

* `node scripts/check-docker-web.js`
* `node --test scripts/check-docker-web.test.js scripts/docker-web.test.js scripts/run-tanstack-e2e-docker.test.js`
* `docker compose -f docker-compose.web.yml config`
* `docker compose -f docker-compose.web.yml --profile redis config`
* `docker compose -f docker-compose.web.yml --profile cloudflared config`
* `docker compose -f docker-compose.web.prod.yml config`
* `docker compose -f docker-compose.web.prod.yml --profile redis config`
* `docker compose -f docker-compose.web.prod.yml --profile cloudflared config`
* `docker compose -f docker-compose.tanstack-dual.yml config`
* `docker buildx build --load --cache-from type=gha,scope=docker-backend --cache-to type=gha,scope=docker-backend,mode=max -f apps/backend/Dockerfile .`
* `docker buildx build --load --target dev --cache-from type=gha,scope=docker-web-dev --cache-to type=gha,scope=docker-web-dev,mode=max -f apps/web/Dockerfile .`
* `docker buildx build --load --target runner --secret id=web_env,src=apps/web/.env.local --cache-from type=gha,scope=docker-web-prod --cache-to type=gha,scope=docker-web-prod,mode=max -f apps/web/Dockerfile .`
* `docker buildx build --load --target runner --cache-from type=gha,scope=docker-tanstack-web-prod --cache-to type=gha,scope=docker-tanstack-web-prod,mode=max -f apps/tanstack-web/Dockerfile .`

That means Docker CI now covers the dev image, the Next.js production image,
the TanStack production image, the dual-stack compose file, and the optional
Cloudflare Tunnel profile rendering.

For focused watcher-script checks, run the root Node test file directly, for
example `node --test --test-name-pattern "pullTrackedBranch"
scripts/watch-blue-green-deploy.test.js`. Running `bun test scripts/...` from
the repo root invokes the package test script and can expand into the full Turbo
test suite.

When `scripts/check-docker-web.js` or similar root validators need to assert a
literal Dockerfile template placeholder like `${process.env.PORT || 7803}`,
prefer a regex or another explicitly escaped matcher instead of a plain string
literal. Biome treats raw `${...}` text inside normal strings as
`lint/suspicious/noTemplateCurlyInString`, which can break CI even when the
runtime behavior is unchanged.

## Operator Notes

* Do not paste `docker compose config` output into chat or tickets; it expands env values.
* If you need rebuild-before-restart on a server, use `bun serve:web:docker:bg`.
* If the latest blue/green deployment is bad, use the infrastructure monitoring dashboard to pin a previous successful deployment before debugging forward.
* If a blue/green deploy is interrupted, rerunning the same command from the intended commit is the normal recovery path.


# Build & Ship
Source: https://docs.tuturuuu.com/build/overview

Set up your environment, work with the monorepo, and ship confidently.

This section aggregates everything you need to contribute to Tuturuuu—from local setup to CI/CD.

## Start Here

1. **Environment Setup** – Follow the [Development Guide](/build/development-tools/development) to install Bun, Supabase, and required tooling.
2. **Understand the Monorepo** – Dive into our [Monorepo Architecture](/build/development-tools/monorepo-architecture) for workspace conventions and dependency flows.
3. **Ship and Operate** – Review [DevOps & Deployment](/build/devops/overview) before touching infrastructure, workflows, or release paths.

## Build Toolkit

```mermaid theme={null}
flowchart LR
    DevSetup[Local Development]
    Monorepo[Monorepo Architecture]
    Supabase[Local Supabase]
    CICD[CI/CD Pipelines]
    Docs[Documentation Standards]

    DevSetup --> Monorepo
    DevSetup --> Supabase
    Monorepo --> CICD
    Supabase --> CICD
    CICD --> Docs
    Docs --> DevSetup
```

* **Clean Environments** – Use the [Cleaning Clone](/build/development-tools/cleaning-clone) guide when local builds misbehave.
* **Deployment Runbooks** – Use the [DevOps & Deployment](/build/devops/overview) section for GitHub Actions, Docker rollout, environments, and secrets.
* **Documenting** – Keep docs current with the [Documenting Workflow](/build/development-tools/documenting).

When you are ready to explore the product experience, head over to the [Platform section](/platform/overview). To sharpen AI and experimentation skills, continue to [Learn](/learn/overview).


# Skills Installation
Source: https://docs.tuturuuu.com/build/skills/installation

Install Tuturuuu skills from the public platform repository.

## Install A Focused Skill

Use the `skills` CLI from the project where the agent should load the skill.
For Codex, install one focused skill like this:

```bash theme={null}
npx skills add tutur3u/platform --agent codex --copy -y \
  --skill tuturuuu-platform
```

Replace `tuturuuu-platform` with any skill from the catalog. Common starting
points:

* `tuturuuu-platform` for general platform repo work.
* `tuturuuu-agent-coordination` for shared or dirty worktrees and short
  5-10-minute commit-window coordination.
* `tuturuuu-commit` for scoped commit follow-through with exact staging and
  commit-window claim/wait/release.
* `tuturuuu-pr-merge-sync` for quiet-window PR merge follow-through, main-green
  verification before `bun git-sync`, and production checks.
* `tuturuuu-cli` for `ttr` and SDK workflows.
* `tuturuuu-database` for Supabase migrations, RLS, and protected data access.

## Install The Full Tuturuuu Set

Install all public Tuturuuu skills for Codex with explicit skill names:

```bash theme={null}
npx skills add tutur3u/platform --agent codex --copy -y \
  --skill tuturuuu-agent-coordination \
  --skill tuturuuu-ci-docs \
  --skill tuturuuu-cli \
  --skill tuturuuu-cli-finance \
  --skill tuturuuu-cli-tasks \
  --skill tuturuuu-cms-studio \
  --skill tuturuuu-commit \
  --skill tuturuuu-database \
  --skill tuturuuu-devbox-ops \
  --skill tuturuuu-development-tooling \
  --skill tuturuuu-e2e-auth-debugging \
  --skill tuturuuu-external-apps \
  --skill tuturuuu-mobile-task-board \
  --skill tuturuuu-platform \
  --skill tuturuuu-pr-merge-sync \
  --skill tuturuuu-review-comments \
  --skill tuturuuu-satellite-app-ux \
  --skill tuturuuu-validation-offload \
  --skill tuturuuu-web-release
```

Run the command from the target project checkout. For a one-time skills.sh
discovery trigger, run it from a disposable directory after the metadata commit
has been pushed to GitHub.

## Verify Discovery

Before pushing metadata changes, validate local repo-root discovery:

```bash theme={null}
npx skills add . --list
```

The output should include all `tuturuuu-*` skills. After the metadata is pushed
and the public install trigger has run, check the cached public page after it
refreshes:

```text theme={null}
https://skills.sh/tutur3u/platform
```


# Skills
Source: https://docs.tuturuuu.com/build/skills/overview

Install and publish Tuturuuu agent skills for platform work.

## Overview

Tuturuuu agent skills package repo-specific operating knowledge for coding
agents. They help agents load focused guidance for platform work without
copying long instructions into every prompt.

The source skills live in `plugins/tuturuuu/skills`. The platform repo exposes
them to public skill installers through `.claude-plugin/marketplace.json`, and
the public skills.sh page is grouped with `skills.sh.json`.

## Skill Groups

The public catalog groups the Tuturuuu skills by workflow:

* Platform: monorepo, Supabase, CI/docs, release metadata, and mobile task-board
  work.
* Agent Workflow: shared-worktree coordination, short 5-10-minute commit-window
  claim/wait/release, scoped commits, review comments, quiet-window PR merge
  sync, validation offload, and tooling improvements.
* CLI And Ops: core `ttr` workflows, task capture, finance commands, and remote
  devbox operations.
* Product Surfaces: CMS studio, satellite app UX, and local E2E authentication
  debugging.

## Maintenance

When a skill is added, renamed, or removed, keep these files aligned:

* `plugins/tuturuuu/skills/<skill>/SKILL.md`
* `.claude-plugin/marketplace.json`
* `skills.sh.json`
* `apps/docs/build/skills/installation.mdx`
* `apps/docs/build/development-tools/codex-plugin.mdx`

Run the plugin validator after changing skill metadata:

```bash theme={null}
python3 plugins/tuturuuu/scripts/validate_plugin.py
```

Use the [installation guide](/build/skills/installation) to install skills from
the public repo or trigger skills.sh discovery after a metadata push.


# Examples
Source: https://docs.tuturuuu.com/learn/examples/overview

Practical examples and code samples for the Tuturuuu platform

This section contains practical examples and code samples demonstrating how to use various components and features of the Tuturuuu platform.

## Component Examples

### WorkspaceWrapper

Examples showing how to use the WorkspaceWrapper component in different scenarios.

The main [WorkspaceWrapper documentation](/platform/components/workspace-wrapper) includes comprehensive code examples demonstrating various usage patterns.

## Usage Patterns

### Server Components

```tsx theme={null}
// Basic server component with WorkspaceWrapper
export default async function MyPage({ 
  params 
}: { 
  params: Promise<{ wsId: string }> 
}) {
  return (
    <WorkspaceWrapper params={params}>
      {({ workspace, wsId }) => (
        <div>{workspace.name}</div>
      )}
    </WorkspaceWrapper>
  );
}
```

### Client Components

```tsx theme={null}
'use client';

interface MyComponentProps {
  workspace: Workspace & { joined: boolean };
  wsId: string;
}

export function MyComponent({ workspace, wsId }: MyComponentProps) {
  return <div>{workspace.name}</div>;
}
```

### API Routes

```tsx theme={null}
// API route with workspace validation
export async function GET(
  request: Request,
  { params }: { params: Promise<{ wsId: string }> }
) {
  const { wsId } = await params;
  const workspace = await getWorkspace(wsId);
  
  if (!workspace) {
    return Response.json({ error: 'Workspace not found' }, { status: 404 });
  }
  
  return Response.json({ workspace });
}
```

## Best Practices

### Error Handling

```tsx theme={null}
// Proper error handling in components
export default async function MyPage({ params }) {
  return (
    <WorkspaceWrapper 
      params={params}
      fallback={<ErrorBoundary />}
    >
      {({ workspace, wsId }) => {
        try {
          return <MyComponent workspace={workspace} wsId={wsId} />;
        } catch (error) {
          return <ErrorMessage error={error} />;
        }
      }}
    </WorkspaceWrapper>
  );
}
```

### Loading States

```tsx theme={null}
// Proper loading state handling
export default async function MyPage({ params }) {
  return (
    <WorkspaceWrapper 
      params={params}
      fallback={<LoadingSkeleton />}
    >
      {({ workspace, wsId }) => (
        <Suspense fallback={<LoadingSpinner />}>
          <AsyncContent workspace={workspace} wsId={wsId} />
        </Suspense>
      )}
    </WorkspaceWrapper>
  );
}
```

### Type Safety

```tsx theme={null}
// Proper TypeScript usage
interface PageProps {
  params: Promise<{ wsId: string }>;
}

interface WorkspaceData {
  workspace: Workspace & { joined: boolean };
  wsId: string;
}

export default async function MyPage({ params }: PageProps) {
  return (
    <WorkspaceWrapper params={params}>
      {({ workspace, wsId }: WorkspaceData) => (
        <MyComponent workspace={workspace} wsId={wsId} />
      )}
    </WorkspaceWrapper>
  );
}
```

## Common Patterns

### Dashboard Pages

Most dashboard pages follow this pattern:

1. Use WorkspaceWrapper for workspace resolution
2. Fetch additional data based on workspace
3. Render components with proper loading states
4. Handle permissions and access control

### Settings Pages

Settings pages typically:

1. Validate user permissions
2. Show different UI based on user role
3. Handle form submissions with proper validation
4. Provide clear feedback to users

### API Endpoints

API endpoints should:

1. Validate workspace access
2. Handle errors gracefully
3. Return appropriate HTTP status codes
4. Include proper error messages

## Contributing Examples

When adding new examples:

1. Use realistic, practical scenarios
2. Include proper TypeScript types
3. Show error handling
4. Include both server and client examples
5. Update this index page


# AI Chat
Source: https://docs.tuturuuu.com/learn/experiments/ai-chat

Talk to an AI-powered assistant that understands your workspace and helps you get things done, faster and easier.

## Mobile live mode

The mobile assistant now has two distinct interaction modes:

* Standard chat is the default assistant surface. Typed turns continue to use the normal text-model selection in the mobile shell.
* Live mode is a dedicated fullscreen Gemini Live experience. It is entered from the assistant mic control or the assistant chrome action and binds the session to `gemini-3.1-flash-live-preview`.

### Mobile cache warmup

The mobile assistant shell restores core metadata from `AssistantRepository`
cache helpers before revalidating: personal workspace resolution, Mira soul,
task and calendar insight, workspace credits, model catalog, recent chat
history, and restored chat detail. The `assistant_metadata` warmup task should
remain the entry point for preloading this data after boot, home resume, or
workspace changes.

### What fullscreen live mode does

* Immediately switches the assistant route into a live-first surface instead of silently preparing a background session.
* Auto-starts the microphone when the user enters live mode, so the transition feels responsive.
* Shows large voice-activity blobs for both the user and the assistant, plus a live transcript lane for drafts and synced turns.
* Shows the current live-session status detail inline in the fullscreen header, plus a contextual status panel with recovery actions for reconnecting and failure states.
* Keeps voice, camera, and typed turns inside the same assistant thread, so persisted live turns still appear in the standard chat history after leaving fullscreen live mode.

### Model split

* Mobile typed chat keeps the normal text-model path managed by `AssistantChatCubit` and the workspace-selected shell model.
* Mobile live mode always uses Gemini 3.1 Flash Live. Restoring a live-backed chat must not overwrite the normal text-model selection.

### Backend dependencies

The mobile app still uses the existing internal APIs for Live sessions:

* `/api/v1/assistant/live/token`
* `/api/v1/live/session`
* `/api/v1/live/tools/execute`
* `/api/v1/assistant/live/turns`

These routes mint constrained ephemeral Gemini Live tokens, persist resumable session handles, execute synchronous tool calls, and sync completed live turns back into the chat thread.

The token route now returns the latest resumable session handle together with the ephemeral token. Mobile uses that bundled handle to skip a follow-up read before opening the socket, and only falls back to loading seed chat history when there is no resumable handle or the user explicitly starts a fresh live conversation.

Gemini 3.1 Flash Live should stay on a single `AUDIO` response modality for the live session config. The mobile UI relies on input/output audio transcription streams for inline text instead of requesting simultaneous `TEXT` and `AUDIO` outputs.

The ephemeral token request should match Google’s current `v1alpha` auth-token shape: send `httpOptions.apiVersion = 'v1alpha'` on the token request itself, keep `uses` aligned with the default single-session flow, and prefer `lockAdditionalFields: []` so only the explicitly constrained setup fields are locked while client-side setup details like history/session resumption can still merge at connect time. When bootstrapping a fresh live assistant chat, omit `ai_chats.id` entirely unless a specific chat id is being resumed so Postgres can apply the default UUID.

Browser AI chat surfaces that use the shared `/api/ai/chat` streaming route must
create a durable `ai_chats` row through `/api/ai/chat/new` before the first
streaming turn. Chat identifiers are UUID database identifiers, not local UI
session keys; the streaming route verifies requested chat ownership before model
invocation so persistence, observability, and AI-credit deduction stay coupled.

## Web Chat and Live modes

The web dashboard presents Chat and Live as one assistant surface. Chat is the
default and remains mounted while Live is selected so draft text is preserved.
Entering Live requests microphone access and connects automatically; switching
back to Chat or pressing Escape closes media and returns focus to the composer.

Web Live access is credit-gated on every product tier. `/api/v1/live/token`
reserves the active Chat credit source and returns a single-use Gemini token
that expires after five minutes. The browser reports cumulative provider usage
to `/api/v1/live/usage`; private database functions reject regressing snapshots,
price each modality against the effective Gemini rate, and release unused held
credits when the session closes or expires. Keep provider prices versioned so
historical transactions remain auditable when Google changes its rates.

### Verification

For mobile-only live-mode changes, the required verification path is:

1. Update both ARB files when live-mode copy changes.
2. Run `flutter gen-l10n`.
3. Run `bun check:mobile`.


# Calendar
Source: https://docs.tuturuuu.com/learn/experiments/calendar

Manage your schedule and events without leaving your workspace.

<Warning>This page is under construction.</Warning>


# Finance
Source: https://docs.tuturuuu.com/learn/experiments/finance

Manage your workspace finances with ease.

<Warning>This page is under construction.</Warning>


# Form Builder
Source: https://docs.tuturuuu.com/learn/experiments/form-builder

Build forms with ease, integrated with all Tuturuuu services.

<Warning>This page is under construction.</Warning>


# Project Management
Source: https://docs.tuturuuu.com/learn/experiments/project-management

Manage tasks and monitor progress without any hassle.

<Warning>This page is under construction.</Warning>


# Introduction to Prompt Engineering
Source: https://docs.tuturuuu.com/learn/guides/prompt-engineering/introduction

A foundational guide for NEO LEAGUE: Prompt the Future — empowering students to master the art of prompting and unlock AI’s full creative potential.

## What is a prompt

A **prompt** is a natural language input that instructs a generative AI on the task at hand. These AI models can create a variety of content like stories, conversations, videos, and more. The quality of the output depends on the prompt's clarity and context, as AI models need accurate details to produce meaningful and precise responses.

### Prompt content types

A prompt can include one or more of the following elements:

* [**Input** (required)](#input)
* [**Context**](#context)
* [**Examples**](#examples)

### Input

The input is the core part of a prompt. It tells the model what task to perform or what question to answer. Inputs come in different forms:

#### Question input

A **question input** asks the model for an answer, usually in the form of a direct question.

**Prompt Example:**

```prompt theme={null}
What's a good name for a flower shop that specializes in selling bouquets of dried flowers? Create a list of 10 options with just the names.
```

**Response:**

```response theme={null}
Here are 10 names for a flower shop specializing in dried flowers:

1. Everlasting Blooms
2. Dried & Delightful
3. The Petal Preserve
4. Whispers of Wildflowers
5. Forever Blooms
6. The Botanical Muse
7. Timeless Blooms
8. Dried Flower Co.
9. Bloom & Co.
10. The Sun-Kissed Petals
```

#### Task Input

A **task input** asks the model to perform a specific action—like generating ideas, making a list, writing a summary, or offering suggestions.

**Prompt Example:**

```prompt theme={null}
Give me a simple list of just the things that I must bring on a camping trip. The list should have 10 items.
```

**Response:**

```response theme={null}
Here's a list of 10 essential items for a camping trip:

1. **Tent:** Your shelter from the elements.
2. **Sleeping Bag:** Stay warm and comfortable.
3. **Sleeping Pad:** Insulation and cushioning for a good night's sleep.
4. **Headlamp or Flashlight:** Light for nighttime activities.
5. **First Aid Kit:** Be prepared for minor injuries.
6. **Water Bottle/Hydration Pack:** Stay hydrated.
7. **Food and Snacks:** Fuel for your adventures.
8. **Cooking Gear:** Camp stove, fuel, utensils, etc.
9. **Knife and Multitool:** Essential for various tasks.
10. **Camp Chair:** Enjoy your campfire and meals comfortably.
```

#### Entity Input

An **entity input** is when the prompt gives the model a specific piece of content to act on—like summarizing a paragraph, classifying a sentence, or translating a passage. It’s often paired with clear instructions on what to do with that content.

**Prompt Example:**

```prompt theme={null}
Classify the following items as [large, small].
Elephant
Mouse
Snail
```

**Response:**

```response theme={null}
Here's the classification:

* **Elephant:** Large
* **Mouse:** Small
* **Snail:** Small
```

#### Completion Input

**Prompt Example:**

```prompt theme={null}
Complete the following prompt: Some simple strategies for overcoming writer's block include...
```

**Response:**

```response theme={null}
Some simple strategies for overcoming writer's block include:

* **Freewriting:** Write non-stop for a set amount of time (5-10 minutes) without worrying about grammar, spelling, or even making sense. Just keep your pen moving and let your thoughts flow freely. This can help you loosen up and access ideas you might not have considered otherwise.
* **Brainstorming:** Make a list of everything that comes to mind related to your topic, no matter how silly or unrelated it seems. You can also use mind mapping or other visual brainstorming techniques.
* **Changing your environment:** Sometimes a change of scenery can be all you need to get the creative juices flowing. Go for a walk, work in a coffee shop, or even just move to a different room in your house.
* **Reading:** Immerse yourself in the work of other writers, especially those who inspire you. Pay attention to their style, their structure, and their use of language.
* **Taking a break:** Sometimes the best way to overcome writer's block is to simply step away from the project for a while. Go for a walk, watch a movie, listen to music, or do something else that you enjoy. You might be surprised at how much clearer your head feels when you return to your writing.
* **Focusing on a single element:** Instead of tackling the entire project, focus on a single sentence, paragraph, or scene. Once you get something down on paper, it can be easier to build from there.
* **Starting with the ending:** If you're stuck on the beginning, try writing the ending first. This can help you to clarify your overall vision for the project and provide a framework for your ideas.
* **Talking it out:** Share your ideas and challenges with a friend, a writing group, or a writing coach. Discussing your project with someone else can help you to see it from a new perspective and find solutions to your writing problems.

Remember, writer's block is a common experience, and it's not a sign that you're a bad writer. Just be patient with yourself, try some of these strategies, and keep writing!
```

### Context

The **context** section gives the model helpful background or specific instructions that shape how it responds. You can use context to:

* Direct the model’s behavior.
* Supply relevant information it should refer to.
* Limit the model’s answers to specific data or rules.

Use context when you want to guide the model more clearly or restrict it to the facts you've provided.

**Prompt Example:**

```prompt theme={null}
Marbles:
Color: red
Number: 12
Color: blue
Number: 28
Color: yellow
Number: 15
Color: green
Number: 17

How many green marbles are there?
```

**Response:**

```response theme={null}
There are 17 green marbles.
```

In this case, the context is the list of marble colors and quantities, and the model uses that information to answer accurately.

### Examples

**Examples** are pairs of inputs and expected outputs you include in your prompt to show the model what kind of response you're looking for. This technique is especially useful when you want the output to follow a certain format or logic.

**Prompt Example:**

```prompt theme={null}
Classify the following.
Options:
- red wine
- white wine

Text: Chardonnay
The answer is: white wine
Text: Cabernet
The answer is: red wine
Text: Moscato
The answer is: white wine

Text: Riesling
The answer is:
```

**Response:**

```response theme={null}
The answer is: white wine
```

By including a few classification examples before the final input, you're teaching the model how to respond.

***

### References

* Some sections in this guide are paraphrased or inspired by Google’s [Gemini API documentation on prompting](https://ai.google.dev/gemini-api/docs/prompting-intro#prompt-content-types).


# Clear Instructions
Source: https://docs.tuturuuu.com/learn/guides/prompt-engineering/prompt-design-strategies/clear-instructions

Learn how to design prompts with clear tasks, constraints, and formatting guidance for more accurate AI responses.

## Explain the Task Clearly

To effectively guide the model's behavior, it's important to provide instructions that are both direct and specific. Whether you're asking for a simple summary or building a more complex user experience, the clearer your guidance, the better the model can deliver the result you want.

**Prompt Example:**

```prompt theme={null}
Create a summary of the following content:
Text: A quantum computer operates using principles of quantum physics, enabling it to process data at speeds far beyond that of conventional machines. At microscopic levels, particles exhibit both wave and particle characteristics, and quantum systems are engineered to take advantage of this. Their inner workings defy traditional physics. When developed at scale, quantum machines could have vast applications—from decoding modern encryption to boosting weather prediction accuracy. However, today’s quantum tech remains mostly experimental and not yet suitable for real-world deployment.
```

**Response:**

```response theme={null}
Quantum computers tap into the dual nature of matter—both wave and particle—at microscopic levels to execute tasks far faster than conventional machines. By utilizing quantum effects that classical physics can’t explain, they gain a significant speed advantage. Although they show strong potential in areas like cybersecurity and meteorology, these systems are still in early development and not ready for mainstream deployment.
```

## Specify any constraints

Define any rules or limitations the model should follow while interpreting the prompt or creating a response. For instance, if you want a more concise version of the original text, make that clear by stating a word or sentence limit. In the earlier example, the summary was shorter than the source content—but you can explicitly direct the model to keep it brief by setting a specific length constraint.

**Prompt Example:**

```prompt theme={null}
Summarize this text in two sentences:
Text: A quantum computer operates using principles of quantum physics, enabling it to process data at speeds far beyond that of conventional machines. At microscopic levels, particles exhibit both wave and particle characteristics, and quantum systems are engineered to take advantage of this. Their inner workings defy traditional physics. When developed at scale, quantum machines could have vast applications—from decoding modern encryption to boosting weather prediction accuracy. However, today’s quantum tech remains mostly experimental and not yet suitable for real-world deployment.
```

**Response:**

```response theme={null}
Quantum machines utilize strange particle behaviors at the quantum level to achieve processing speeds that leave regular computers behind. Despite their huge promise in areas like cybersecurity and climate modeling, they’re still in early development and not yet viable for everyday tasks.
```

## Set the Desired Output Format

You can guide how the model should present its answer by specifying a format. Whether you want the response in bullet points, a short paragraph, a table, a list of keywords, or even as an elevator pitch—you can simply include that in your instructions. For instance, you might ask the model to respond in a more casual, conversational tone by stating that directly in your prompt.

**System message:**

```message theme={null}
Respond to all prompts using clear and structured bullet points, unless the user explicitly requests a different format. Each bullet should be concise yet informative, helping break down complex information into easily digestible parts.
```

**Example Prompt:**

```prompt theme={null}
What’s an effective way to run a DVD-selling business in 2025?
```

**Response:**

```response theme={null}
Running a DVD-focused business in 2025 is challenging due to the rise of streaming and digital formats. However, it's not entirely out of reach. Here's a strategic way to approach it:

- Niche Targeting: Focus on collectors, retro lovers, or areas with low internet access.

- Product Differentiation: Sell special edition DVDs, box sets, or director’s cuts not available digitally.

- Experience-Based Selling: Open pop-up nostalgia stores or host DVD movie nights to create a community experience.

- Bundle Offers: Combine DVDs with themed merchandise (posters, T-shirts) to increase perceived value.
```

Another example about setting desired format.

**System message:**

```message theme={null}
Respond using a numbered list format by default. Each number should represent a main idea or step. Keep the explanations concise and informative. Only switch to another format if the user requests it.
```

**Example Prompt:**

```prompt theme={null}
How can a student better manage their time while studying for exams?
```

**Response:**

```response theme={null}
1. Set clear goals
  Define what you need to study each day based on your exam schedule.

2. Prioritize tasks
  Focus first on subjects or topics you're weakest in or those that carry the most weight in the exam.

3. Use time blocks
  Study in focused intervals (e.g., Pomodoro method: 25 minutes study, 5 minutes break).

4. Eliminate distractions
  Turn off notifications, put your phone away, and create a quiet study environment.

5. Review consistently
  Instead of cramming, revisit key topics regularly to  strengthen memory.

6. Track your progress
  Use a checklist or planner to mark completed topics and stay motivated.
```

**📝 Summary:**

* Clearly tell the model what task you want it to perform.
* Make sure your instructions are detailed and easy to understand.
* If there are any limits or formatting preferences for the response, be sure to include them.


# Context Strategies
Source: https://docs.tuturuuu.com/learn/guides/prompt-engineering/prompt-design-strategies/context-strategies

Add background details, references, or brand-specific data to help the model generate more targeted responses.

Don’t assume the model knows everything it needs. Instead, add helpful background details or instructions directly in the prompt. Supplying context gives the model a better understanding of your goals, limitations, and the specific problem it needs to solve.

For example, the following prompt asks the model to provide router troubleshooting advice:

**Example Prompt:**

```prompt theme={null}
My printer won’t print even though it’s connected. The display says “Paper Jam”, but I checked and there’s no paper stuck inside. What should I do?
```

**Response:**

```response theme={null}
If your printer shows a “Paper Jam” error but there’s no visible jam, it could be due to a false sensor trigger or small bits of paper stuck inside. Here are steps you can take to troubleshoot:
1. Power off and unplug the printer.
2. Open all accessible panels and trays.
  - Remove any paper and carefully check inside using a flashlight.
  - Look for tiny scraps of paper or dust near rollers or sensors.
3. Clean the rollers.
  - Use a lint-free cloth slightly dampened with water to clean the feed rollers.
4. Let it rest for a few minutes, then restart.
   - Plug the printer back in and turn it on.
5. Try a test print.
  - If the issue persists, consult the printer’s manual or support site for advanced help.
```

The response provided sounds like general advice and doesn’t directly address this specific printer model or its error message behavior. To make the response more accurate and relevant, you could include details from the printer’s official troubleshooting guide—such as how it handles “Paper Jam” alerts or what might trigger them falsely. Providing that context helps the model give targeted, brand-specific instructions rather than just standard tips.

**Example Prompt:**

```prompt theme={null}
Answer the question using the text below. Respond with only the text provided.
Question: What should I do if my Epson printer shows an error with blinking red and orange lights?

Text:
Light Pattern: Blinking red and orange
What it means: A fatal printer error has occurred.
What to do:
- Turn off the printer.
- Unplug the power cord and wait for at least 60 seconds.
- Plug the printer back in and power it on.
- If the error persists, contact Epson support for service.

Light Pattern: Blinking green
What it means: The printer is receiving data or printing.
What to do: No action needed.

Light Pattern: Solid red
What it means: The printer is out of paper or has a paper jam.
What to do: Check for jammed paper and reload the paper tray properly.
```

**Response:**

```response theme={null}
Turn off the printer. Unplug the power cord and wait for at least 60 seconds. Plug the printer back in and power it on. If the error persists, contact Epson support for service.
```

**📝 Summary:**

* Add any relevant background or reference material directly into the prompt to guide the model’s response.
* Also, be sure to clearly explain how the model should apply that context when generating its answer.


# Fallback and Caution
Source: https://docs.tuturuuu.com/learn/guides/prompt-engineering/prompt-design-strategies/fallback-caution

Handle fallback messages and understand the model’s limitations with factual content, logic, and math.

## Fallback Responses

A fallback response is what the model returns when the prompt or generated content activates a safety mechanism. A common fallback message might be: "I'm sorry, but I can't help with that."

If you encounter a fallback response, try raising the temperature setting to encourage a different outcome.

## Cautionary Notes

* Avoid using the model as a reliable source for factual information.
* Be cautious when using it for math or logic-related tasks, as the output may not always be accurate.


# Few-Shot Examples
Source: https://docs.tuturuuu.com/learn/guides/prompt-engineering/prompt-design-strategies/few-shot-examples

Explore zero-shot vs few-shot prompting, and how to use examples to teach the model desired output patterns and styles.

You can guide the model by including examples in your prompt that demonstrate the ideal response. The model learns from these examples by recognizing patterns and structures, then applies that understanding to generate its own output. Prompts with a few examples are known as few-shot prompts, while those with none are called zero-shot prompts. Few-shot prompts are particularly useful for shaping the tone, format, scope, and overall structure of the model’s replies. Using clear, diverse examples helps the model stay focused and deliver more accurate results.

It’s generally best to include a few examples in your prompt. Without them, the model’s responses may be less precise. In fact, if your examples are well-chosen and illustrative, you may not even need additional instructions at all.

## Zero-shot vs few-shot prompts

The zero-shot prompt below instructs the model to select the most suitable explanation.

**Example Prompt:**

```prompt theme={null}
Select the most accurate explanation for the following question:

Question: What causes earthquakes?
Option 1: Earthquakes occur when tectonic plates shift suddenly along fault lines, releasing energy in the form of seismic waves.
Option 2: Earthquakes happen due to strong winds and storms shaking the ground.
Your Answer:
```

**Response:**

```response theme={null}
Option 1 is the most accurate explanation.
```

If your goal is to get brief responses from the model, you can add examples in your prompt that highlight concise answers.

In the next prompt, two sample explanations are given, showing a clear preference for shorter responses. As a result, the model is influenced by these examples and selects the more concise explanation (Explanation 2), unlike the earlier case where it chose the longer one (Explanation 1).

**Example Prompt:**

```prompt theme={null}
Below are some examples showing a question, explanation, and answer format:

Question: Why do leaves change color in the fall?
Explanation1: Leaves change color due to a combination of factors like temperature, light, and the reduction of chlorophyll production, which causes other pigments like carotenoids and anthocyanins to become more visible.
Explanation2: Because chlorophyll fades, other colors in the leaves show through.
Answer: Explanation2

Question: Why do tides occur?
Explanation1: Tides are caused primarily by the gravitational pull of the moon and the sun on Earth’s oceans.
Explanation2: The moon’s gravity pulls ocean water, causing tides.
Answer: Explanation2

Now, using the same format and logic, answer the following:

Question: Why do we see lightning before we hear thunder?
Explanation1: Lightning travels at the speed of light, which is much faster than the speed of sound. That’s why we see the flash before we hear the thunderclap, even though they happen at the same time.
Explanation2: Light moves faster than sound, so we see it first.
Answer:
```

**Response:**

```response theme={null}
Answer: Explanation2
```

## Determine the Right Number of Examples

To get the best outcome, try different numbers of examples in your prompt. Models like Gemini can usually recognize patterns with just a few examples, but you might need to test how many are needed to achieve the result you want. Be cautious though—adding too many can cause the model to mimic the examples too closely instead of generalizing properly.

**Use examples to show patterns instead of antipatterns:**

It’s more effective to include examples that demonstrate the kind of response you want, rather than showing what not to do. Highlighting good examples helps the model follow the intended pattern more accurately.

**🚫 Negative pattern:**

```prompt theme={null}
Don’t start formal emails too casually:
Hey there!
Just checking in on that report.
Let me know, okay?
```

**✅ Positive pattern:**

```prompt theme={null}
Begin formal emails with a professional greeting:
Dear Team,
I’m writing to follow up on the report.
Please let me know your updates by Friday.
```

## Keep Formatting Consistent Across Examples

To ensure the model produces the desired output, your few-shot examples should all follow the same structure and formatting. Since the purpose of few-shot prompting is to guide the model's response format, it’s important to maintain uniformity in elements like XML tags, line breaks, whitespace, and separators between examples. Inconsistencies might lead to unpredictable results.

**📝 Summary:**

Use prompt-response examples to teach the model how to respond.

Focus on showing clear examples of what you want, not what to avoid.

Test different numbers of examples to see what works best—too few may not help, while too many could limit the model’s flexibility.

Always keep the formatting consistent across all examples to guide the model accurately.


# Modular Prompts
Source: https://docs.tuturuuu.com/learn/guides/prompt-engineering/prompt-design-strategies/modular-prompts

Simplify complex tasks using modular instructions, chaining prompts step-by-step, or aggregating outputs.

When dealing with complex tasks, simplify them by dividing the prompt into smaller, more focused parts. This makes it easier for the model to follow and process your instructions accurately.

## Simplify Instruction

Rather than packing multiple instructions into a single prompt, create separate prompts for each one. Choose the appropriate prompt to run based on the user’s input or situation.

## Use Chained Prompts

For tasks that follow a specific order of steps, use one prompt per step and pass the output from one step into the next. This sequence allows the model to build on its responses and reach a final result.

## Aggregate Outputs

When you need to perform several tasks on different parts of your data, handle them separately and then combine the outputs. For instance, analyze the beginning of a document in one way, process the rest differently, and then merge the results for a complete answer.

**📝 Summary:**

* Break down complex prompts into individual instructions and select the right one based on the user’s needs.
* For multi-step workflows, treat each step as its own prompt and pass outputs forward in sequence.
* For parallel tasks, process each part independently and combine the results to produce a complete answer.


# Prompt Design Strategies
Source: https://docs.tuturuuu.com/learn/guides/prompt-engineering/prompt-design-strategies/overview

Master the art of prompt crafting with strategic techniques to guide AI responses, structure output, and enhance clarity.

Prompt design is more than just asking a question — it’s about structuring information, setting the right context, and guiding AI to respond exactly how you want.

In this section, you'll explore tactical strategies for writing effective prompts, such as:

* Giving clear and specific instructions
* Including few-shot examples
* Providing relevant context
* Using smart prefixes and formats
* Structuring complex prompts into manageable parts
* Tuning model behavior through parameters
* Handling fallback cases and avoiding common pitfalls

Each strategy is broken down into its own focused lesson. Ready to level up your prompting game?

👇 Start exploring the strategies below:

* [Give Clear and Specific Instructions](./clear-instructions)
* [Use Few-Shot Examples Effectively](./few-shot-examples)
* [Include Relevant Context](./context-strategies)
* [Guide with Prefixes and Partial Patterns](./prefixes-patterns)
* [Break Down Prompts into Manageable Parts](./modular-prompts)
* [Tune Parameters and Iterate on Prompts](./parameters-iteration)
* [Fallback Responses and Cautionary Tips](./fallback-caution)


# Parameters and Iteration
Source: https://docs.tuturuuu.com/learn/guides/prompt-engineering/prompt-design-strategies/parameters-iteration

Understand temperature, top-p, and max token settings. Learn how to refine your prompt through experimentation.

## Experiment with different parameter values

Each time you send a prompt to a model, it uses certain parameters that influence how the response is generated. Adjusting these values can help you fine-tune the output to better fit your task. Different models may offer different parameter options, but here are the most commonly used ones:

### Max Output Tokens

This limits the maximum length of the response. One token is roughly 4 characters or ¾ of a word.

* Use a lower value for short answers
* Use a higher value for longer, more detailed responses

### Temperature

Controls how creative or random the response is.

* **Lower values (e.g., 0.2)** make outputs more focused and consistent
* **Higher values (e.g., 0.7+)** lead to more varied, creative responses
* A temperature of **0** always picks the most likely next word (deterministic)

Start with **0.2** and increase if the output feels generic, repetitive, or too short.

### Top-K

Limits the model’s choices for the next word to the top K most likely tokens.

* **Top-K = 1** gives the most predictable result

* **Top-K = 3** or more allows more randomness and variation Top-K is often used with temperature and top-P together.

### Top-P

Instead of picking from a fixed number of top options like Top-K, Top-P chooses from the smallest set of words whose total probability exceeds the specified threshold.

* **Lower top-P (e.g., 0.5)** = safer, more focused responses
* **Higher top-P (e.g., 0.95)** = more variety and creativity

## Prompt Iteration Strategies

Designing effective prompts is a trial-and-error process, and it often takes several attempts to consistently get the results you want. This section offers tips on how to improve your prompts through iteration.

### Use different phrasing

Designing effective prompts is a trial-and-error process, and it often takes several attempts to consistently get the results you want. This section offers tips on how to improve your prompts through iteration.

```prompt theme={null}
Version 1:
How can I improve my sleep quality?

Version 2:
Give me tips for getting better sleep.

Version 3:
What are some effective ways to sleep better?
```

### Switch to an analogous task

If the model isn’t responding well to your original instructions, consider reframing the task as a similar one that leads to the same outcome.

For example, instead of directly asking the model to label a book, you might instruct it to sort the book into one of several predefined categories.

**Example Prompt:**

```prompt theme={null}
Which category does `1984` belong to:
- romance
- dystopian
- fantasy
- biography
```

**Response:**

```response theme={null}
1984 belongs to the category of dystopian.
Here’s why:
- Dystopian: 1984 is set in a totalitarian future society where the government controls every aspect of life, including thoughts and language. It explores themes of surveillance, propaganda, and loss of freedom—hallmarks of dystopian fiction.
```

The answer is accurate, but the model went beyond the list of provided choices and responded in full sentences. If you want the model to stick strictly to the given options and respond with just one of them, you can reword the prompt as a multiple-choice question and instruct the model to select only one answer.

**Example Prompt:**

```prompt theme={null}
Multiple choice problem: Which of the following options describes the book `1984`?
Options:
- romance
- dystopian
- fantasy
- biography
```

**Response:**

```response theme={null}
The correct answer is dystopian.
```

### Change the order of prompt content

Rearranging the elements in your prompt can influence how the model responds. Try altering the sequence of the content to see if it changes or improves the outcome.

```prompt theme={null}
Format Option 1:
- Sample responses
- Background information
- User input

Format Option 2:
- User input
- Sample responses
- Background information

Format Option 3:
- Sample responses
- User input
- Background details
```


# Prefixes and Patterns
Source: https://docs.tuturuuu.com/learn/guides/prompt-engineering/prompt-design-strategies/prefixes-patterns

Use labeled prefixes and incomplete structures to guide the model’s response format and intent.

## Add prefixes

Prefixes are short phrases or labels you can attach to parts of a prompt to guide the model’s understanding and output. They serve different roles based on where they’re placed:

* **Input prefix**: This helps the model interpret sections of the input by labeling them. For instance, using “English:” and “French:” can indicate that different languages are being used.

* **Output prefix**: Even though the model generates the output, you can lead with a prefix like “JSON:” to show that the response should follow a specific format.

* **Example prefix**: In few-shot prompts, labeling examples with prefixes makes it easier for the model to recognize patterns and generate consistent, easy-to-understand results.

For example, in the prompt:
Text: signals the input section, and
The answer is: signals the beginning of the expected output.

**Example Prompt:**

```prompt theme={null}
Classify the text as one of the following categories:
- fruit
- vegetable
Text: Apple
The answer is: fruit
Text: Carrot
The answer is: vegetable
Text: Banana
The answer is: fruit
Text: Broccoli
The answer is:
```

**Response:**

```response theme={null}
The answer is: vegetable
```

## Let the model complete partial input

Language models function similarly to powerful autocomplete systems. When you supply the beginning of a sentence, structure, or task, the model can predict and continue the rest based on that starting point. If your prompt includes examples or additional context, the model can use that information to generate a more relevant and accurate continuation.

**Example Prompt:**

```prompt theme={null}
Convert the following temperature report into a JSON object with fields for city, temperature (in Celsius), and condition.

Report: It’s 18 degrees and cloudy in Hanoi.
```

**Response:**

```response theme={null}
{
  "city": "Hanoi",
  "temperature": 18,
  "condition": "cloudy"
}
```

Although the model followed the instructions, describing the task in plain language can sometimes be tricky and may lead to varied interpretations. For instance, if someone says “Can I get two bananas and an orange?”, the model should generate a JSON object that includes only those items—banana and orange—and exclude fields like apple or grapes that weren’t mentioned. To make the task clearer and guide the output structure, it’s more effective to include a few-shot example with a response prefix like Output: so the model can complete the response by following the pattern shown.

**Example Prompt:**

```prompt theme={null}
Valid fields are apple, banana, orange, and grapes.
Order: I'd like an apple and some grapes.
Output:
{
  "apple": 1,
  "grapes": 1
}
Order: Can I get two bananas and an orange?
Output:
```

**Response:**

```response theme={null}
{
  "banana": 2,
  "orange": 1
}
```

Notice how "grapes" was excluded from the output because it wasn't a part of the order.

## **Prompt the model to format its response**

You can also guide the model to structure its output by using a completion-based approach. For example, the prompt below asks the model to generate an outline for an essay.

**Example Prompt:**

```prompt theme={null}
Create an outline for an essay about volcanoes.
```

**Response:**

```response theme={null}
Volcanoes: Earth’s Fiery Power
I. Introduction
A. What volcanoes are and how they form
B. Thesis: Volcanoes shape the Earth through both destruction and creation

II. Types of Volcanoes
A. Stratovolcanoes, shield, and cinder cones
B. Key features and eruption styles

III. Effects on People and Nature
A. Hazards: lava, ash, tsunamis
B. Benefits: fertile soil, geothermal energy

IV. Monitoring and Safety
A. How eruptions are predicted
B. Importance of early warning systems

V. Conclusion
A. Volcanoes’ role in shaping Earth and human history
```

The prompt didn’t include instructions about how the outline should be structured, so the model selected a format on its own. If you want the model to follow a specific structure, you can provide the beginning of the outline in your desired format. The model will then continue generating the rest to match the pattern you've started.

**Example Prompt:**

```prompt theme={null}
Create an outline for an essay about volcanoes.
I. Introduction
*
```

**Response:**

```response theme={null}
Volcanoes: Earth’s Fiery Sculptors
I. Introduction
- Hook: Start with a dramatic description of a volcanic eruption, capturing the raw power and impact on the landscape.
- Background: Introduce what volcanoes are and how they form as openings in the Earth's crust.
- Thesis: Present the central idea of the essay. Examples:
  - Volcanoes are both destructive and creative forces that shape ecosystems and human life.
  - Understanding volcanic activity is key to reducing disaster risks and appreciating Earth’s dynamic nature.
  - Despite their dangers, volcanoes offer valuable scientific, ecological, and cultural insights.
```

**📝 Summary:**

* When you provide the model with an incomplete input, it can finish it by recognizing patterns from any examples or context you've included.
* In many cases, letting the model complete a partially written prompt is simpler and more effective than explaining the task in full.
* By starting the answer yourself, you can guide the model to generate responses in the specific structure or style you want.


# Learn & Experiment
Source: https://docs.tuturuuu.com/learn/overview

Examples, experiments, and prompt engineering techniques for Tuturuuu.

Level up your Tuturuuu expertise through curated examples, experiments, and prompt engineering playbooks.

## Learning Paths

* **Examples** – Browse practical snippets and starter code in the [Examples Library](/learn/examples/overview).
* **Experiments** – Explore in-progress ideas in [Experiments](/learn/experiments/form-builder) to understand what is coming next.
* **Prompt Engineering** – Master AI collaboration with the [Prompt Engineering Guides](/learn/guides/prompt-engineering/introduction).

## Experimentation Flow

```mermaid theme={null}
graph LR
    A[Idea] -->|Rapid build| B[Prototype]
    B -->|Share| C[Feedback]
    C -->|Promote| D[Product]
    D -->|Document| A

    style A fill:#4f46e5,stroke:#3730a3,color:#fff
    style D fill:#4f46e5,stroke:#3730a3,color:#fff
```

Stay curious—share findings, improve docs, and help us expand what the Tuturuuu ecosystem can do. For detailed platform architecture, visit the [Platform section](/platform/overview). Need local tooling help? Return to [Build](/build/overview).


# Part 1: Web Fundamentals
Source: https://docs.tuturuuu.com/learn/workshops/nextjs-workshop/01-web-fundamentals

HTML, CSS, and JavaScript - The building blocks of the web

<Info>
  ⏱️ **Duration**: 15 minutes | This section covers the absolute basics of web development.
</Info>

## What is a Website?

Every website you visit—from Netflix to TikTok to your university portal—is built with just **three technologies**:

```mermaid theme={null}
graph LR
    A["🦴 HTML"] --> D["🌐 Website"]
    B["🎨 CSS"] --> D
    C["🧠 JavaScript"] --> D

    style A fill:#e34c26,color:#fff
    style B fill:#264de4,color:#fff
    style C fill:#f7df1e,color:#000
    style D fill:#22c55e,color:#fff
```

**Think of a website like a human body:**

| Technology        | What it does        | Human analogy       |
| ----------------- | ------------------- | ------------------- |
| 🦴 **HTML**       | Structure & content | Skeleton + organs   |
| 🎨 **CSS**        | Appearance & style  | Skin, hair, clothes |
| 🧠 **JavaScript** | Behavior & logic    | Brain + muscles     |

<Note>
  **🤯 Did you know?** The first website ever created is still online! Visit [info.cern.ch](http://info.cern.ch/hypertext/WWW/TheProject.html)—it was made in 1991 by Tim Berners-Lee. No CSS, no JavaScript, just pure HTML!
</Note>

***

## HTML: The Structure

HTML (HyperText Markup Language) defines the content and structure of web pages.

### Your First HTML Page

```html theme={null}
<!DOCTYPE html>
<html>
  <head>
    <title>My First Page</title>
  </head>
  <body>
    <h1>Hello, World!</h1>
    <p>Welcome to web development!</p>
  </body>
</html>
```

<Tip>
  **Beginner Tip**: Every HTML element has an opening tag `<tag>` and a closing tag `</tag>`. The content goes between them.
</Tip>

### Common HTML Elements

| Element          | Purpose   | Example                                   |
| ---------------- | --------- | ----------------------------------------- |
| `<h1>` to `<h6>` | Headings  | `<h1>Title</h1>`                          |
| `<p>`            | Paragraph | `<p>Some text</p>`                        |
| `<a>`            | Link      | `<a href="url">Click me</a>`              |
| `<img>`          | Image     | `<img src="photo.jpg" alt="Description">` |
| `<div>`          | Container | `<div>Group of elements</div>`            |
| `<button>`       | Button    | `<button>Click</button>`                  |

***

## CSS: The Style

CSS (Cascading Style Sheets) controls how HTML elements look.

### Adding Styles

```html theme={null}
<style>
  h1 {
    color: blue;
    font-size: 32px;
  }

  p {
    color: gray;
    line-height: 1.5;
  }
</style>
```

### CSS Selectors

```css theme={null}
/* Select by element */
h1 { color: blue; }

/* Select by class */
.card { background: white; }

/* Select by ID */
#header { height: 60px; }
```

<Tip>
  **Beginner Tip**: Use **classes** (`.classname`) for styles you'll reuse. Use **IDs** (`#idname`) for unique elements.
</Tip>

### The Box Model

Every HTML element is a box with **4 layers**. Think of it like a package:

```mermaid theme={null}
graph LR
    subgraph Box["📦 The Box Model"]
        direction LR
        M["Margin"] --> B["Border"] --> P["Padding"] --> C["Content"]
    end

    style M fill:#fef3c7,stroke:#f59e0b,color:#000
    style B fill:#dbeafe,stroke:#3b82f6,color:#000
    style P fill:#dcfce7,stroke:#22c55e,color:#000
    style C fill:#fce7f3,stroke:#ec4899,color:#000
```

<img alt="The CSS Box Model" />

| Layer          | What it is               | CSS Example               |
| -------------- | ------------------------ | ------------------------- |
| 📝 **Content** | Your text, images, etc.  | `width: 200px`            |
| 🧸 **Padding** | Space inside the border  | `padding: 20px`           |
| 🖼️ **Border** | The visible edge         | `border: 2px solid black` |
| 📦 **Margin**  | Space outside the border | `margin: 10px`            |

**Real-world analogy:**

* 📝 **Content** = The gift inside the box
* 🧸 **Padding** = Bubble wrap protecting the gift
* 🖼️ **Border** = The cardboard box itself
* 📦 **Margin** = Space between boxes on the shelf

***

## JavaScript: The Behavior

JavaScript makes websites interactive.

### Your First Script

```html theme={null}
<button onclick="sayHello()">Click Me!</button>

<script>
  function sayHello() {
    alert('Hello, World!');
  }
</script>
```

### JavaScript Basics

```javascript theme={null}
// Variables
let name = 'Alice';
const age = 20;

// Functions
function greet(person) {
  return `Hello, ${person}!`;
}

// Calling a function
console.log(greet(name)); // "Hello, Alice!"
```

<Tip>
  **Beginner Tip**: Use `const` for values that don't change, and `let` for values that might change. Avoid using `var`.
</Tip>

### DOM Manipulation

JavaScript can change HTML elements:

```javascript theme={null}
// Find an element
const heading = document.querySelector('h1');

// Change its content
heading.textContent = 'New Title!';

// Change its style
heading.style.color = 'red';
```

***

## Putting It All Together

```html theme={null}
<!DOCTYPE html>
<html>
  <head>
    <title>My Interactive Page</title>
    <style>
      .highlight {
        background-color: yellow;
        padding: 10px;
      }
    </style>
  </head>
  <body>
    <h1>Welcome!</h1>
    <p id="message">Click the button below.</p>
    <button onclick="changeMessage()">Click Me</button>

    <script>
      function changeMessage() {
        const message = document.getElementById('message');
        message.textContent = 'You clicked the button!';
        message.classList.add('highlight');
      }
    </script>
  </body>
</html>
```

***

## Key Takeaways

<CardGroup>
  <Card title="HTML = Structure" icon="code">
    Defines what content appears on the page
  </Card>

  <Card title="CSS = Style" icon="palette">
    Controls how content looks
  </Card>

  <Card title="JS = Behavior" icon="bolt">
    Makes content interactive
  </Card>
</CardGroup>

***

## Learn More

<CardGroup>
  <Card title="HTML Tutorial" icon="code" href="https://www.w3schools.com/html/">
    W3Schools HTML Guide
  </Card>

  <Card title="CSS Tutorial" icon="palette" href="https://www.w3schools.com/css/">
    W3Schools CSS Guide
  </Card>

  <Card title="JavaScript Tutorial" icon="bolt" href="https://www.w3schools.com/Js/">
    W3Schools JS Guide
  </Card>
</CardGroup>

***

**Next up**: [Tailwind CSS →](/learn/workshops/nextjs-workshop/02-tailwind-css)


# Part 2: Tailwind CSS
Source: https://docs.tuturuuu.com/learn/workshops/nextjs-workshop/02-tailwind-css

Modern, utility-first CSS for rapid UI development

<Info>
  ⏱️ **Duration**: 15 minutes | Learn how to build beautiful UIs without writing custom CSS.
</Info>

## What is Tailwind CSS?

Tailwind CSS is a **utility-first CSS framework**. Instead of writing custom CSS, you apply pre-built classes directly in your HTML.

**It's like building with LEGO instead of carving from scratch! 🧱**

```mermaid theme={null}
graph LR
    A["😫 Traditional CSS"] --> B["Write .card class"]
    B --> C["Switch to CSS file"]
    C --> D["Write styles"]
    D --> E["Back to HTML"]
    E --> F["Repeat forever..."]

    G["😎 Tailwind"] --> H["Write classes inline"]
    H --> I["Done! ✅"]

    style A fill:#fee2e2,stroke:#ef4444,color:#000
    style G fill:#dcfce7,stroke:#22c55e,color:#000
```

### Traditional CSS vs Tailwind

<CodeGroup>
  ```css Traditional CSS theme={null}
  .card {
    background-color: white;
    border-radius: 8px;
    padding: 24px;
    box-shadow: 0 4px 6px rgba(0, 0, 0, 0.1);
  }

  .card-title {
    font-size: 20px;
    font-weight: bold;
    color: #1f2937;
  }
  ```

  ```html Tailwind CSS theme={null}
  <div class="bg-white rounded-lg p-6 shadow-md">
    <h2 class="text-xl font-bold text-gray-800">
      Card Title
    </h2>
  </div>
  ```
</CodeGroup>

<Tip>
  **Why do developers love Tailwind?** You never leave your HTML file. No more context-switching, no more inventing class names like `.card-wrapper-container-inner-box` 😅
</Tip>

<Note>
  **🤯 Did you know?** Tailwind CSS has over **80,000+ GitHub stars** and is used by Netflix, OpenAI, Shopify, and NASA!
</Note>

***

## Core Utilities

### Spacing (Padding & Margin)

Tailwind uses a simple numbering system for spacing:

| Class | Size | Example             |
| ----- | ---- | ------------------- |
| `p-1` | 4px  | `<div class="p-1">` |
| `p-2` | 8px  | `<div class="p-2">` |
| `p-4` | 16px | `<div class="p-4">` |
| `p-6` | 24px | `<div class="p-6">` |
| `p-8` | 32px | `<div class="p-8">` |

**Variants:**

* `p-4` = padding on all sides
* `px-4` = padding left and right
* `py-4` = padding top and bottom
* `pt-4` = padding top only
* `m-4` = margin (same pattern)

### Colors

Tailwind provides a beautiful color palette:

```html theme={null}
<!-- Text colors -->
<p class="text-gray-500">Gray text</p>
<p class="text-blue-600">Blue text</p>
<p class="text-red-500">Red text</p>

<!-- Background colors -->
<div class="bg-white">White background</div>
<div class="bg-gray-100">Light gray</div>
<div class="bg-blue-500">Blue background</div>
```

**Try it! 👇** Mix and match Tailwind classes:

<TailwindPlayground />

### Typography

```html theme={null}
<!-- Font sizes -->
<p class="text-sm">Small</p>
<p class="text-base">Base (default)</p>
<p class="text-lg">Large</p>
<p class="text-xl">Extra large</p>
<p class="text-2xl">2X large</p>

<!-- Font weight -->
<p class="font-normal">Normal</p>
<p class="font-medium">Medium</p>
<p class="font-semibold">Semibold</p>
<p class="font-bold">Bold</p>
```

***

## Layout with Flexbox

Flexbox is incredibly easy with Tailwind:

```html theme={null}
<!-- Horizontal layout with gap -->
<div class="flex gap-4">
  <div>Item 1</div>
  <div>Item 2</div>
  <div>Item 3</div>
</div>

<!-- Centered content -->
<div class="flex items-center justify-center h-screen">
  <p>I'm centered!</p>
</div>

<!-- Space between items -->
<div class="flex justify-between">
  <div>Left</div>
  <div>Right</div>
</div>
```

***

## Building a Card Component

Let's build a beautiful card step by step:

```html theme={null}
<div class="max-w-sm rounded-xl bg-white p-6 shadow-lg">
  <!-- Image -->
  <img
    class="h-48 w-full rounded-lg object-cover"
    src="https://picsum.photos/400/300"
    alt="Card image"
  />

  <!-- Content -->
  <div class="mt-4">
    <h3 class="text-xl font-semibold text-gray-900">
      Card Title
    </h3>
    <p class="mt-2 text-gray-600">
      This is a beautiful card built with Tailwind CSS.
      No custom CSS needed!
    </p>
  </div>

  <!-- Button -->
  <button class="mt-4 w-full rounded-lg bg-blue-600 px-4 py-2 font-medium text-white hover:bg-blue-700">
    Learn More
  </button>
</div>
```

**Try it! 👇** Click the like button:

<LiveCard />

***

## Responsive Design

Add breakpoint prefixes for responsive styles:

| Prefix | Screen Width |
| ------ | ------------ |
| `sm:`  | 640px+       |
| `md:`  | 768px+       |
| `lg:`  | 1024px+      |
| `xl:`  | 1280px+      |

```html theme={null}
<div class="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-4">
  <!-- 1 column on mobile, 2 on tablet, 3 on desktop -->
  <div class="bg-white p-4 rounded-lg">Card 1</div>
  <div class="bg-white p-4 rounded-lg">Card 2</div>
  <div class="bg-white p-4 rounded-lg">Card 3</div>
</div>
```

<Tip>
  **Beginner Tip**: Tailwind is "mobile-first". Write styles for mobile, then add `md:` or `lg:` for larger screens.
</Tip>

***

## Hover and Focus States

Add interactivity with state prefixes:

```html theme={null}
<!-- Hover effects -->
<button class="bg-blue-500 hover:bg-blue-600 transition-colors">
  Hover me
</button>

<!-- Focus states -->
<input
  class="border border-gray-300 focus:border-blue-500 focus:ring-2 focus:ring-blue-200 rounded-lg px-4 py-2"
  placeholder="Focus me"
/>
```

***

## Quick Reference

| What you want       | Tailwind class                |
| ------------------- | ----------------------------- |
| Rounded corners     | `rounded-lg`                  |
| Shadow              | `shadow-md`                   |
| Flex row            | `flex`                        |
| Flex column         | `flex flex-col`               |
| Center items        | `items-center justify-center` |
| Full width          | `w-full`                      |
| Fixed height        | `h-64` (256px)                |
| Hide on mobile      | `hidden md:block`             |
| Show only on mobile | `block md:hidden`             |

***

## Learn More

<Card title="Tailwind CSS Docs" icon="book" href="https://tailwindcss.com">
  The official Tailwind CSS documentation with all utilities.
</Card>

***

**Next up**: [TypeScript →](/learn/workshops/nextjs-workshop/03-typescript)


# Part 3: TypeScript
Source: https://docs.tuturuuu.com/learn/workshops/nextjs-workshop/03-typescript

JavaScript with superpowers - catch bugs before they happen

<Info>
  ⏱️ **Duration**: 15 minutes | Learn how TypeScript helps you write safer, more reliable code.
</Info>

## Why TypeScript?

TypeScript is **JavaScript with types**. It helps you catch errors before running your code.

**Think of it as spell-check for your code! 📝✅**

```mermaid theme={null}
graph LR
    A["You write code"] --> B{"TypeScript checks it"}
    B -->|"❌ Error found"| C["Fix before running"]
    B -->|"✅ All good"| D["Run with confidence!"]

    style B fill:#4f46e5,stroke:#3730a3,color:#fff
    style C fill:#fef3c7,stroke:#f59e0b,color:#000
    style D fill:#dcfce7,stroke:#22c55e,color:#000
```

<Note>
  **Fun Facts**:

  * TypeScript was created by **Microsoft** and is used by Google, Airbnb, and Slack
  * TypeScript is **built with TypeScript** (it compiles itself! 🤯)
  * **TypeScript Native v7** is coming soon—rewritten in **Golang** for \~10x faster performance!
</Note>

### The Problem with JavaScript

```javascript theme={null}
// JavaScript - no error until runtime! 💥
function greet(user) {
  return "Hello, " + user.name;
}

greet("Alice"); // Runtime error: user.name is undefined
```

### The TypeScript Solution

```typescript theme={null}
// TypeScript - error caught immediately! ✅
function greet(user: { name: string }) {
  return "Hello, " + user.name;
}

greet("Alice"); // ❌ Error: string is not assignable to { name: string }
greet({ name: "Alice" }); // ✅ Works!
```

<Tip>
  **Beginner Tip**: TypeScript acts like a spell-checker for your code. It catches mistakes as you type!
</Tip>

***

## Basic Types

### Primitive Types

```typescript theme={null}
// String
let name: string = "Alice";

// Number
let age: number = 20;

// Boolean
let isStudent: boolean = true;

// Array of strings
let hobbies: string[] = ["coding", "gaming", "reading"];

// Array of numbers
let scores: number[] = [95, 87, 92];
```

### Type Inference

TypeScript is smart! It can often figure out types automatically:

```typescript theme={null}
// TypeScript knows these types automatically
let name = "Alice"; // string
let age = 20; // number
let isActive = true; // boolean

// But you can still add types for clarity
let email: string = "alice@example.com";
```

***

## Objects and Interfaces

### Typing Objects

```typescript theme={null}
// Inline object type
let user: { name: string; age: number } = {
  name: "Alice",
  age: 20,
};
```

### Using Interfaces (Recommended)

```typescript theme={null}
// Define a reusable type
interface User {
  name: string;
  age: number;
  email: string;
}

// Use it
const alice: User = {
  name: "Alice",
  age: 20,
  email: "alice@example.com",
};

const bob: User = {
  name: "Bob",
  age: 22,
  email: "bob@example.com",
};
```

### Optional Properties

```typescript theme={null}
interface User {
  name: string;
  age: number;
  email?: string; // Optional (the ? makes it optional)
}

// Valid - email is optional
const user: User = {
  name: "Alice",
  age: 20,
};
```

***

## Functions

### Typed Parameters and Return Values

```typescript theme={null}
// Parameters and return type
function add(a: number, b: number): number {
  return a + b;
}

// Arrow function
const multiply = (a: number, b: number): number => {
  return a * b;
};

// Usage
add(5, 3); // ✅ Returns 8
add("5", 3); // ❌ Error: string is not a number
```

### Functions with Objects

```typescript theme={null}
interface Product {
  name: string;
  price: number;
}

function getTotal(products: Product[]): number {
  return products.reduce((sum, p) => sum + p.price, 0);
}

const cart = [
  { name: "Book", price: 15 },
  { name: "Pen", price: 2 },
];

console.log(getTotal(cart)); // 17
```

***

## Union Types

A variable can be one of several types:

```typescript theme={null}
// Can be string or number
let id: string | number;
id = "abc123"; // ✅
id = 123; // ✅
id = true; // ❌ Error

// Useful for optional values
let username: string | null = null;
username = "alice"; // ✅
```

***

## Type Aliases

Create custom type names:

```typescript theme={null}
// Simple alias
type ID = string | number;

// Object alias
type Point = {
  x: number;
  y: number;
};

// Usage
const userId: ID = "user_123";
const location: Point = { x: 10, y: 20 };
```

<Note>
  **Interface vs Type**: Both can define object shapes. Use `interface` for objects you might extend later, `type` for everything else.
</Note>

***

## Real-World Example

```typescript theme={null}
// Define types for a todo app
interface Todo {
  id: number;
  title: string;
  completed: boolean;
  dueDate?: string;
}

// Type-safe function
function toggleTodo(todo: Todo): Todo {
  return {
    ...todo,
    completed: !todo.completed,
  };
}

// Type-safe array operations
function getCompletedTodos(todos: Todo[]): Todo[] {
  return todos.filter((todo) => todo.completed);
}

// Usage
const myTodos: Todo[] = [
  { id: 1, title: "Learn TypeScript", completed: true },
  { id: 2, title: "Build an app", completed: false },
];

const completed = getCompletedTodos(myTodos);
console.log(completed); // [{ id: 1, title: "Learn TypeScript", completed: true }]
```

***

## TypeScript in 60 Seconds

| Concept    | Syntax             | Example                           |
| ---------- | ------------------ | --------------------------------- |
| Basic type | `: type`           | `let x: number = 5`               |
| Array      | `type[]`           | `let arr: string[]`               |
| Object     | `interface`        | `interface User { name: string }` |
| Optional   | `?`                | `email?: string`                  |
| Union      | `\|`               | `string \| number`                |
| Function   | `(params): return` | `(x: number): number`             |

***

## Key Takeaways

<CardGroup>
  <Card title="Catch Bugs Early" icon="bug">
    TypeScript finds errors before you run your code
  </Card>

  <Card title="Better Autocomplete" icon="keyboard">
    Your editor knows what properties and methods are available
  </Card>

  <Card title="Self-Documenting" icon="book">
    Types act as documentation for your code
  </Card>

  <Card title="Refactor Safely" icon="shield">
    Change code confidently - TypeScript tells you what breaks
  </Card>
</CardGroup>

***

## ☕ Break Time!

Great job making it this far! Take a 5-minute break before we dive into React.

***

**Next up**: [React Basics →](/learn/workshops/nextjs-workshop/04-react)


# Part 4: React Basics
Source: https://docs.tuturuuu.com/learn/workshops/nextjs-workshop/04-react

Component-based UI development with the most popular JavaScript library

<Info>
  ⏱️ **Duration**: 20 minutes | Learn how React revolutionizes UI development.
</Info>

## What is React?

React is a JavaScript library for building user interfaces. It lets you create **reusable components** that manage their own state.

**Ever noticed how Netflix updates smoothly without reloading the whole page?** That's React! 🎬

<Note>
  **Fun Fact**: React was created by **Meta (Facebook)** in 2013 and now powers billions of users on Facebook, Instagram, and WhatsApp! The engineer who created it, Jordan Walke, built the first version in just a few weeks!
</Note>

### Why React?

```mermaid theme={null}
graph LR
    subgraph Traditional["❌ Traditional"]
        direction TB
        A[Write HTML] --> B[Write JS]
        B --> C[Manually Sync]
        C --> D[🐛 Bugs!]
    end
    
    subgraph React["✅ React"]
        direction TB
        E[Write Component] --> F[State Changes]
        F --> G[Auto Update!]
        G --> H[🎉 It Works!]
    end

    Traditional ~~~ React

    style Traditional fill:#fee2e2,stroke:#ef4444,color:#000
    style React fill:#dcfce7,stroke:#22c55e,color:#000
```

| Traditional Approach | React Approach                  |
| -------------------- | ------------------------------- |
| Manually update HTML | Components update automatically |
| Copy-paste code      | Reusable components             |
| Hard to track state  | Clear state management          |
| DOM manipulation     | Declarative UI                  |

<Card title="React Official Tutorial" icon="graduation-cap" href="https://react.dev/learn">
  Learn React step-by-step with the official interactive tutorial
</Card>

***

## Components

Components are the building blocks of React apps. Think of them as custom HTML elements.

### Your First Component

```tsx theme={null}
// A simple component
function Greeting() {
  return <h1>Hello, World!</h1>;
}

// Using the component
function App() {
  return (
    <div>
      <Greeting />
      <Greeting />
      <Greeting />
    </div>
  );
}
```

<Tip>
  **Beginner Tip**: Component names must start with a capital letter! `Greeting` not `greeting`.
</Tip>

***

## JSX: HTML in JavaScript

JSX lets you write HTML-like code in JavaScript:

```tsx theme={null}
function WelcomeCard() {
  const name = "Alice";
  const isStudent = true;

  return (
    <div className="card">
      <h2>Welcome, {name}!</h2>
      {isStudent && <p>Student discount available!</p>}
    </div>
  );
}
```

### JSX Rules

| HTML                  | JSX                        |
| --------------------- | -------------------------- |
| `class`               | `className`                |
| `for`                 | `htmlFor`                  |
| `style="color: red"`  | `style={{ color: 'red' }}` |
| Self-closing: `<img>` | Must close: `<img />`      |

***

## Props: Passing Data

Props let you pass data to components:

```tsx theme={null}
// Component that accepts props
interface UserCardProps {
  name: string;
  age: number;
  isActive?: boolean;
}

function UserCard({ name, age, isActive = false }: UserCardProps) {
  return (
    <div className="p-4 bg-white rounded-lg shadow">
      <h3 className="font-bold">{name}</h3>
      <p>Age: {age}</p>
      {isActive && <span className="text-green-500">● Online</span>}
    </div>
  );
}

// Using the component with props
function App() {
  return (
    <div className="space-y-4">
      <UserCard name="Alice" age={20} isActive />
      <UserCard name="Bob" age={22} />
      <UserCard name="Charlie" age={19} isActive />
    </div>
  );
}
```

***

## State: Making Things Interactive

State is data that changes over time. Use `useState` to add state:

```tsx theme={null}
import { useState } from 'react';

function Counter() {
  // Declare state: [value, setterFunction]
  const [count, setCount] = useState(0);

  return (
    <div className="text-center">
      <p className="text-4xl font-bold">{count}</p>
      <div className="flex gap-2 justify-center mt-4">
        <button
          onClick={() => setCount(count - 1)}
          className="px-4 py-2 bg-red-500 text-white rounded"
        >
          -1
        </button>
        <button
          onClick={() => setCount(count + 1)}
          className="px-4 py-2 bg-green-500 text-white rounded"
        >
          +1
        </button>
      </div>
    </div>
  );
}
```

**Try it yourself! 👇**

<Counter />

<Warning>
  **Important**: Never modify state directly! Always use the setter function.

  ```tsx theme={null}
  // ❌ Wrong
  count = count + 1;

  // ✅ Correct
  setCount(count + 1);
  ```
</Warning>

***

## Handling Events

React makes event handling easy:

```tsx theme={null}
function LoginForm() {
  const [email, setEmail] = useState('');
  const [password, setPassword] = useState('');

  const handleSubmit = (e: React.FormEvent) => {
    e.preventDefault(); // Prevent page refresh
    console.log('Logging in:', email);
  };

  return (
    <form onSubmit={handleSubmit} className="space-y-4">
      <input
        type="email"
        value={email}
        onChange={(e) => setEmail(e.target.value)}
        placeholder="Email"
        className="w-full p-2 border rounded"
      />
      <input
        type="password"
        value={password}
        onChange={(e) => setPassword(e.target.value)}
        placeholder="Password"
        className="w-full p-2 border rounded"
      />
      <button
        type="submit"
        className="w-full p-2 bg-blue-500 text-white rounded"
      >
        Login
      </button>
    </form>
  );
}
```

***

## Rendering Lists

Use `.map()` to render arrays of components:

```tsx theme={null}
interface Todo {
  id: number;
  title: string;
  completed: boolean;
}

function TodoList() {
  const [todos, setTodos] = useState<Todo[]>([
    { id: 1, title: 'Learn React', completed: true },
    { id: 2, title: 'Build an app', completed: false },
    { id: 3, title: 'Deploy to Vercel', completed: false },
  ]);

  return (
    <ul className="space-y-2">
      {todos.map((todo) => (
        <li
          key={todo.id}
          className={`p-3 rounded ${
            todo.completed ? 'bg-green-100' : 'bg-gray-100'
          }`}
        >
          {todo.completed ? '✅' : '⬜'} {todo.title}
        </li>
      ))}
    </ul>
  );
}
```

<Tip>
  **Beginner Tip**: Always add a unique `key` prop when rendering lists. Use IDs, not array indices.
</Tip>

***

## Conditional Rendering

Show different content based on conditions:

```tsx theme={null}
function UserStatus({ isLoggedIn }: { isLoggedIn: boolean }) {
  // Method 1: Ternary operator
  return (
    <div>
      {isLoggedIn ? (
        <p>Welcome back!</p>
      ) : (
        <p>Please log in.</p>
      )}
    </div>
  );
}

function Notification({ count }: { count: number }) {
  // Method 2: && operator (render if true)
  return (
    <div>
      {count > 0 && (
        <span className="bg-red-500 text-white px-2 rounded-full">
          {count}
        </span>
      )}
    </div>
  );
}
```

**Try it! 👇** Toggle login state:

<LoginToggle />

***

## Complete Example: Task Manager

```tsx theme={null}
import { useState } from 'react';

interface Task {
  id: number;
  text: string;
  done: boolean;
}

function TaskManager() {
  const [tasks, setTasks] = useState<Task[]>([]);
  const [input, setInput] = useState('');

  const addTask = () => {
    if (!input.trim()) return;
    setTasks([
      ...tasks,
      { id: Date.now(), text: input, done: false }
    ]);
    setInput('');
  };

  const toggleTask = (id: number) => {
    setTasks(tasks.map(task =>
      task.id === id ? { ...task, done: !task.done } : task
    ));
  };

  return (
    <div className="max-w-md mx-auto p-6">
      <h1 className="text-2xl font-bold mb-4">Tasks</h1>

      {/* Add task */}
      <div className="flex gap-2 mb-4">
        <input
          value={input}
          onChange={(e) => setInput(e.target.value)}
          onKeyDown={(e) => e.key === 'Enter' && addTask()}
          placeholder="New task..."
          className="flex-1 p-2 border rounded"
        />
        <button
          onClick={addTask}
          className="px-4 py-2 bg-blue-500 text-white rounded"
        >
          Add
        </button>
      </div>

      {/* Task list */}
      <ul className="space-y-2">
        {tasks.map((task) => (
          <li
            key={task.id}
            onClick={() => toggleTask(task.id)}
            className={`p-3 rounded cursor-pointer ${
              task.done
                ? 'bg-green-100 line-through text-gray-500'
                : 'bg-gray-100'
            }`}
          >
            {task.text}
          </li>
        ))}
      </ul>
    </div>
  );
}
```

**Try it! 👇** Add tasks and click to toggle:

<MiniTaskManager />

***

## React Cheat Sheet

| Concept     | Syntax                                            |
| ----------- | ------------------------------------------------- |
| Component   | `function Name() { return <div>...</div> }`       |
| Props       | `function Card({ title }: { title: string })`     |
| State       | `const [value, setValue] = useState(initial)`     |
| Event       | `onClick={() => doSomething()}`                   |
| List        | `{items.map(item => <li key={item.id}>...</li>)}` |
| Conditional | `{condition && <Component />}`                    |

***

**Next up**: [Next.js →](/learn/workshops/nextjs-workshop/05-nextjs)


# Part 5: Next.js
Source: https://docs.tuturuuu.com/learn/workshops/nextjs-workshop/05-nextjs

The React framework for production - build full-stack web applications

<Info>
  ⏱️ **Duration**: 25 minutes | This is the core technology powering rmitnct.club!
</Info>

## What is Next.js?

Next.js is a **React framework** that gives you everything you need for production.

**If React is a sword, Next.js is the entire armory! ⚔️🛡️**

| What you get                  | Benefit                       |
| ----------------------------- | ----------------------------- |
| 🗂️ **File-based routing**    | Create a file = create a page |
| ⚡ **Server-side rendering**   | SEO-friendly, fast loads      |
| 🔄 **API routes**             | Backend in the same project   |
| 📦 **Built-in optimizations** | Images, fonts, scripts        |

<Note>
  **Fun Fact**: Next.js was created by **Vercel** and is used by TikTok, Nike, Notion, Anthropic, LG, and Tuturuuu. It powers both [rmitnct.club](https://rmitnct.club) and [Neo League 2025](https://nova.ai.vn/competitions/neo-league/prompt-the-future/about)!
</Note>

***

## Creating a Next.js Project

The fastest way to create a Next.js app:

```bash theme={null}
# Option 1: Using npx (Node.js)
npx create-next-app@latest my-app

# Option 2: Using bunx (Bun - faster!)
bunx create-next-app@latest my-app

# Navigate into the project
cd my-app

# Start the development server
bun dev   # or: npm run dev
```

When prompted, select these options for this workshop:

* ✅ TypeScript
* ✅ Tailwind CSS
* ✅ App Router
* ❌ src/ directory (optional)

<Tip>
  Open [http://localhost:3000](http://localhost:3000) to see your app!
</Tip>

<Card title="Next.js Templates" icon="rocket" href="https://vercel.com/templates/next.js">
  Browse 100+ ready-to-use templates for blogs, e-commerce, dashboards, and more!
</Card>

***

## Project Structure

```
my-app/
├── app/                  # 👈 Your pages and layouts
│   ├── layout.tsx        # Root layout (shared UI)
│   ├── page.tsx          # Home page (/)
│   └── globals.css       # Global styles
├── public/               # Static files (images, etc.)
├── package.json          # Dependencies
└── tailwind.config.ts    # Tailwind configuration
```

***

## File-Based Routing

In Next.js, **files become pages**. Create a file, get a route!

| File Path                  | URL                 |
| -------------------------- | ------------------- |
| `app/page.tsx`             | `/`                 |
| `app/about/page.tsx`       | `/about`            |
| `app/blog/page.tsx`        | `/blog`             |
| `app/blog/[slug]/page.tsx` | `/blog/hello-world` |

<img alt="How page.tsx creates routes" />

### Creating Your First Page

Create `app/about/page.tsx`:

```tsx theme={null}
export default function AboutPage() {
  return (
    <div className="p-8">
      <h1 className="text-3xl font-bold">About Us</h1>
      <p className="mt-4 text-gray-600">
        Welcome to our Next.js app!
      </p>
    </div>
  );
}
```

Now visit [http://localhost:3000/about](http://localhost:3000/about)!

***

## Layouts

Layouts wrap pages with shared UI (navbars, footers, etc.).

### Root Layout (`app/layout.tsx`)

```tsx theme={null}
import './globals.css';

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="en">
      <body>
        {/* Navigation bar */}
        <nav className="bg-gray-900 text-white p-4">
          <div className="container mx-auto flex gap-6">
            <a href="/" className="font-bold">Home</a>
            <a href="/about">About</a>
            <a href="/blog">Blog</a>
          </div>
        </nav>

        {/* Page content */}
        <main>{children}</main>

        {/* Footer */}
        <footer className="bg-gray-100 p-4 text-center mt-8">
          © 2025 My App
        </footer>
      </body>
    </html>
  );
}
```

<img alt="How layouts wrap pages" />

***

## Server vs Client Components

Next.js has two types of components:

| Server Components             | Client Components               |
| ----------------------------- | ------------------------------- |
| Run on the server             | Run in the browser              |
| Can access databases directly | Can use `useState`, `useEffect` |
| Default in Next.js            | Add `'use client'` at top       |
| Great for static content      | Great for interactivity         |

### Server Component (Default)

```tsx theme={null}
// app/users/page.tsx
// This runs on the server!

async function getUsers() {
  const res = await fetch('https://api.example.com/users');
  return res.json();
}

export default async function UsersPage() {
  const users = await getUsers();

  return (
    <div className="p-8">
      <h1 className="text-2xl font-bold">Users</h1>
      <ul className="mt-4 space-y-2">
        {users.map((user: { id: number; name: string }) => (
          <li key={user.id}>{user.name}</li>
        ))}
      </ul>
    </div>
  );
}
```

### Client Component

```tsx theme={null}
'use client'; // 👈 This makes it a client component

import { useState } from 'react';

export default function Counter() {
  const [count, setCount] = useState(0);

  return (
    <button
      onClick={() => setCount(count + 1)}
      className="px-4 py-2 bg-blue-500 text-white rounded"
    >
      Count: {count}
    </button>
  );
}
```

<Warning>
  **Rule of Thumb**: Keep components as Server Components unless they need interactivity (`onClick`, `useState`, etc.).
</Warning>

***

## Navigation with Links

Use the `Link` component for navigation:

```tsx theme={null}
import Link from 'next/link';

export default function Navbar() {
  return (
    <nav className="flex gap-4">
      <Link href="/" className="hover:underline">
        Home
      </Link>
      <Link href="/about" className="hover:underline">
        About
      </Link>
      <Link href="/blog" className="hover:underline">
        Blog
      </Link>
    </nav>
  );
}
```

<Tip>
  **Why Link?** It enables client-side navigation without full page reloads - much faster!
</Tip>

***

## Dynamic Routes

Create pages with dynamic parameters:

### File: `app/blog/[slug]/page.tsx`

```tsx theme={null}
interface BlogPostProps {
  params: Promise<{ slug: string }>;
}

export default async function BlogPost({ params }: BlogPostProps) {
  const { slug } = await params;

  return (
    <div className="p-8">
      <h1 className="text-3xl font-bold">
        Blog Post: {slug}
      </h1>
      <p className="mt-4">
        Content for {slug}...
      </p>
    </div>
  );
}
```

Now `/blog/hello-world` will show "Blog Post: hello-world"!

***

## API Routes

Build your API in the same project:

### File: `app/api/hello/route.ts`

```typescript theme={null}
import { NextResponse } from 'next/server';

export async function GET() {
  return NextResponse.json({
    message: 'Hello from the API!',
    timestamp: new Date().toISOString(),
  });
}

export async function POST(request: Request) {
  const body = await request.json();

  return NextResponse.json({
    received: body,
    status: 'success',
  });
}
```

Now visit [http://localhost:3000/api/hello](http://localhost:3000/api/hello)!

***

## Building for Production

```bash theme={null}
# Build the app
bun run build

# Start production server
bun start
```

Or deploy to **Vercel** with zero configuration:

```bash theme={null}
# Install Vercel CLI
bun add -g vercel

# Deploy
vercel
```

***

## Complete Example: Blog

```tsx theme={null}
// app/page.tsx
import Link from 'next/link';

const posts = [
  { slug: 'getting-started', title: 'Getting Started with Next.js' },
  { slug: 'react-basics', title: 'React Basics for Beginners' },
  { slug: 'tailwind-tips', title: 'Tailwind CSS Tips and Tricks' },
];

export default function HomePage() {
  return (
    <div className="max-w-2xl mx-auto p-8">
      <h1 className="text-4xl font-bold mb-8">My Blog</h1>

      <div className="space-y-4">
        {posts.map((post) => (
          <Link
            key={post.slug}
            href={`/blog/${post.slug}`}
            className="block p-6 bg-white rounded-lg shadow hover:shadow-lg transition-shadow"
          >
            <h2 className="text-xl font-semibold">{post.title}</h2>
            <p className="text-gray-500 mt-1">Read more →</p>
          </Link>
        ))}
      </div>
    </div>
  );
}
```

***

## Next.js Cheat Sheet

| Feature          | Syntax                                              |
| ---------------- | --------------------------------------------------- |
| Create page      | `app/[path]/page.tsx`                               |
| Create layout    | `app/[path]/layout.tsx`                             |
| Client component | `'use client'` at top of file                       |
| Navigation       | `<Link href="/path">`                               |
| Dynamic route    | `app/blog/[slug]/page.tsx`                          |
| API route        | `app/api/[path]/route.ts`                           |
| Use params       | `{ params }: { params: Promise<{ slug: string }> }` |

***

## Learn More

<CardGroup>
  <Card title="Next.js Docs" icon="book" href="https://nextjs.org/docs">
    Complete documentation
  </Card>

  <Card title="Next.js Learn" icon="graduation-cap" href="https://nextjs.org/learn">
    Free interactive course
  </Card>
</CardGroup>

***

**Next up**: [Vercel AI SDK →](/learn/workshops/nextjs-workshop/06-ai-sdk)


# Part 6: Vercel AI SDK
Source: https://docs.tuturuuu.com/learn/workshops/nextjs-workshop/06-ai-sdk

Build AI-powered features with text and structured data generation

<Info>
  ⏱️ **Duration**: 10 minutes | Add AI superpowers to your Next.js apps!
</Info>

## What is Vercel AI SDK?

The **Vercel AI SDK** is a TypeScript library for building AI-powered applications. It works with multiple AI providers and makes it easy to integrate AI into your apps.

<Card title="AI SDK Documentation" icon="robot" href="https://ai-sdk.dev">
  Official documentation for the Vercel AI SDK
</Card>

***

## The Journey of AI: From Games to Gemini

Before we dive into code, let's understand how AI got here. It's a fascinating story!

```mermaid theme={null}
graph LR
    A["🎮 1980s: Pacman AI"] --> B["♟️ 1997: Deep Blue"]
    B --> C["🎯 2016: AlphaGo"]
    C --> D["💬 2022: ChatGPT"]
    D --> E["✨ 2024: Gemini"]

    style A fill:#fef3c7,stroke:#f59e0b,color:#000
    style B fill:#dbeafe,stroke:#3b82f6,color:#000
    style C fill:#dcfce7,stroke:#22c55e,color:#000
    style D fill:#fce7f3,stroke:#ec4899,color:#000
    style E fill:#4285f4,stroke:#2d6bce,color:#fff
```

**The foundation of AI is search.** Think about it:

* 🎮 **Pacman ghosts** search for the best path to catch you
* ♟️ **Chess AI** searches millions of moves to find the best one
* 💬 **ChatGPT** searches through patterns in language
* ✨ **Gemini** searches across text, images, video, and code

<Note>
  **Why Google leads AI**: Google is the world's best at **search**—the foundation of AI. This is why they're state-of-the-art across text generation, math reasoning, image generation, video generation, and more. When you use Gemini, you're using decades of search innovation!
</Note>

### 🎬 Want to Learn More? Watch These!

<CardGroup>
  <Card title="AlphaGo - The Movie" icon="play" href="https://youtu.be/WXuK6gekU1Y">
    The documentary that shows how AI beat the world's best Go player
  </Card>

  <Card title="The Thinking Game" icon="brain" href="https://youtu.be/d95J8yzvjbQ">
    Google DeepMind's journey to create AI that thinks
  </Card>

  <Card title="Hacking Google" icon="shield" href="https://youtu.be/aOGFY1R4QQ4">
    How Google protects billions of users (cybersecurity series)
  </Card>

  <Card title="Google Gemini History" icon="book" href="https://en.wikipedia.org/wiki/Google_Gemini">
    The full story of Gemini's development
  </Card>
</CardGroup>

### AI Providers Today

```mermaid theme={null}
graph LR
    A["Your App"] --> B["AI SDK"]
    B --> C["Google Gemini"]
    B --> D["OpenAI"]
    B --> E["Anthropic"]
    B --> F["And More..."]

    style A fill:#000,stroke:#333,color:#fff
    style B fill:#4f46e5,stroke:#3730a3,color:#fff
    style C fill:#4285f4,stroke:#2d6bce,color:#fff
    style D fill:#10a37f,stroke:#0d8a6a,color:#fff
    style E fill:#d97706,stroke:#b45309,color:#fff
```

***

## Getting Started

### Install Dependencies

```bash theme={null}
bun add ai @ai-sdk/google zod
```

### Get Your API Key (Free!)

<Card title="Google AI Studio" icon="key" href="https://aistudio.google.com/apikey">
  Get a free API key with generous usage limits
</Card>

### Environment Variables

Create `.env.local` in your project root:

```bash theme={null}
GOOGLE_GENERATIVE_AI_API_KEY=your-api-key-here
```

<Warning>
  **Never commit API keys!** Add `.env.local` to your `.gitignore` file.
</Warning>

***

## Text Generation

The simplest way to use AI is generating text. Let's start here!

```mermaid theme={null}
graph LR
    A["📝 Prompt"] --> B["🤖 AI Model"]
    B --> C["💬 Text Response"]

    style A fill:#dbeafe,stroke:#3b82f6,color:#000
    style B fill:#4f46e5,stroke:#3730a3,color:#fff
    style C fill:#dcfce7,stroke:#22c55e,color:#000
```

### Your First AI Call

```typescript theme={null}
import { generateText } from 'ai';
import { google } from "@ai-sdk/google";

const { text } = await generateText({
  model: google("gemini-2.5-flash"),
  system:
    'You are a professional writer. ' +
    'You write simple, clear, and concise content.',
  prompt: `Summarize the following article in 3-5 sentences: ${article}`,
});

console.log(text);
```

<Tip>
  **Why Gemini?** Google offers **free API access** with generous limits—perfect for learning and prototyping!
</Tip>

<Card title="Text Generation Docs" icon="book" href="https://ai-sdk.dev/docs/ai-sdk-core/generating-text">
  Learn more about text generation options
</Card>

***

## Structured Data Generation

Text is great, but what if you need **data** you can use programmatically?

### The Problem with Plain Text

```mermaid theme={null}
graph LR
    A["Ask AI for recipe"] --> B["Get text blob"]
    B --> C["Parse manually? 😰"]
    C --> D["Regex nightmares 💀"]

    style A fill:#dbeafe,stroke:#3b82f6,color:#000
    style B fill:#fef3c7,stroke:#f59e0b,color:#000
    style C fill:#fee2e2,stroke:#ef4444,color:#000
    style D fill:#fee2e2,stroke:#ef4444,color:#000
```

```typescript theme={null}
// ❌ Unstructured text - hard to use programmatically
const response = "Here's a recipe: Lasagna. You'll need pasta, cheese, sauce...";

// How do you extract the ingredients? The steps? 🤔
```

### The Solution: Structured Output

```mermaid theme={null}
graph LR
    A["Ask AI for recipe"] --> B["Define schema"]
    B --> C["Get typed data ✨"]
    C --> D["Use directly! 🎉"]

    style A fill:#dbeafe,stroke:#3b82f6,color:#000
    style B fill:#fef3c7,stroke:#f59e0b,color:#000
    style C fill:#dcfce7,stroke:#22c55e,color:#000
    style D fill:#dcfce7,stroke:#22c55e,color:#000
```

```typescript theme={null}
// ✅ Structured data - easy to use!
const recipe = {
  name: "Lasagna",
  ingredients: [
    { name: "pasta sheets", amount: "12 sheets" },
    { name: "ricotta cheese", amount: "2 cups" },
    { name: "tomato sauce", amount: "3 cups" },
  ],
  steps: [
    "Preheat oven to 375°F",
    "Layer sauce, pasta, and cheese",
    "Bake for 45 minutes",
  ],
};
```

***

## Using `generateObject`

The `generateObject` function generates structured data from a prompt:

```typescript theme={null}
import { generateObject } from 'ai';
import { google } from '@ai-sdk/google';
import { z } from 'zod';

// Define the shape of your data with Zod
const recipeSchema = z.object({
  name: z.string(),
  ingredients: z.array(
    z.object({
      name: z.string(),
      amount: z.string(),
    })
  ),
  steps: z.array(z.string()),
  prepTime: z.string(),
});

// Generate structured data
const { object: recipe } = await generateObject({
  model: google('gemini-2.5-flash'),
  schema: recipeSchema,
  prompt: 'Generate a recipe for chocolate chip cookies.',
});

// TypeScript knows the exact shape!
console.log(recipe.name); // "Chocolate Chip Cookies"
console.log(recipe.ingredients[0].name); // "flour"
```

***

## Zod Schemas

[Zod](https://zod.dev) defines the shape of your data with TypeScript-first validation.

```mermaid theme={null}
graph TB
    subgraph Zod["Zod Schema"]
        A["z.object()"] --> B["z.string()"]
        A --> C["z.number()"]
        A --> D["z.array()"]
        A --> E["z.boolean()"]
    end

    style Zod fill:#fef3c7,stroke:#f59e0b,color:#000
```

### Common Schema Types

```typescript theme={null}
import { z } from 'zod';

// Basic types
const stringSchema = z.string();
const numberSchema = z.number();
const booleanSchema = z.boolean();

// Arrays
const arraySchema = z.array(z.string());

// Objects
const userSchema = z.object({
  name: z.string(),
  age: z.number(),
  email: z.string().email(),
});
```

### Adding Descriptions (Important!)

Descriptions help the AI understand what you want:

```typescript theme={null}
const flashcardSchema = z.object({
  flashcards: z.array(
    z.object({
      front: z.string().describe('The question on the flashcard'),
      back: z.string().describe('The answer on the flashcard'),
    })
  ).describe('Array of 10 flashcards'),
});
```

***

## Complete Example: AI Flashcard Generator

### API Route: `app/api/flashcards/route.ts`

```typescript theme={null}
import { generateObject } from 'ai';
import { google } from '@ai-sdk/google';
import { z } from 'zod';
import { NextResponse } from 'next/server';

const flashcardSchema = z.object({
  flashcards: z.array(
    z.object({
      front: z.string().describe('Question'),
      back: z.string().describe('Answer'),
    })
  ),
});

export async function POST(request: Request) {
  const { topic } = await request.json();

  const { object } = await generateObject({
    model: google('gemini-2.5-flash'),
    schema: flashcardSchema,
    prompt: `Generate 5 flashcards about: ${topic}`,
  });

  return NextResponse.json(object);
}
```

### Frontend Component

```tsx theme={null}
'use client';

import { useState } from 'react';

export default function FlashcardGenerator() {
  const [topic, setTopic] = useState('');
  const [flashcards, setFlashcards] = useState([]);
  const [loading, setLoading] = useState(false);

  const generate = async () => {
    setLoading(true);
    const res = await fetch('/api/flashcards', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ topic }),
    });
    const data = await res.json();
    setFlashcards(data.flashcards);
    setLoading(false);
  };

  return (
    <div className="p-8 max-w-2xl mx-auto">
      <h1 className="text-2xl font-bold mb-4">AI Flashcard Generator</h1>

      <div className="flex gap-2 mb-6">
        <input
          value={topic}
          onChange={(e) => setTopic(e.target.value)}
          placeholder="Enter a topic..."
          className="flex-1 p-2 border rounded"
        />
        <button
          onClick={generate}
          disabled={loading}
          className="px-4 py-2 bg-blue-500 text-white rounded"
        >
          {loading ? 'Generating...' : 'Generate'}
        </button>
      </div>

      <div className="grid gap-4">
        {flashcards.map((card, i) => (
          <div key={i} className="p-4 bg-white rounded-lg shadow">
            <p className="font-semibold">{card.front}</p>
            <p className="text-gray-600 mt-2">{card.back}</p>
          </div>
        ))}
      </div>
    </div>
  );
}
```

***

## Key Takeaways

<CardGroup>
  <Card title="Start with Text" icon="message">
    Use `generateText` for simple AI responses
  </Card>

  <Card title="Level Up with Schemas" icon="shapes">
    Use `generateObject` for structured data
  </Card>

  <Card title="Google Gemini" icon="google">
    Free API access for learning and prototyping
  </Card>

  <Card title="Type-Safe AI" icon="shield">
    Zod schemas give you TypeScript types automatically
  </Card>
</CardGroup>

***

## Learn More

<CardGroup>
  <Card title="Text Generation" icon="message" href="https://ai-sdk.dev/docs/ai-sdk-core/generating-text">
    Complete text generation guide
  </Card>

  <Card title="Structured Data" icon="shapes" href="https://ai-sdk.dev/docs/ai-sdk-core/generating-structured-data">
    Complete structured data guide
  </Card>
</CardGroup>

***

**Next up**: [Next Steps & Resources →](/learn/workshops/nextjs-workshop/07-next-steps)


# Part 7: Next Steps
Source: https://docs.tuturuuu.com/learn/workshops/nextjs-workshop/07-next-steps

Continue your learning journey and contribute to NCT Club projects

<Info>
  ⏱️ **Duration**: 5 minutes | Congratulations on completing the workshop! 🎉
</Info>

## 🎉 What You've Learned

In just 2 hours, you've covered:

| Topic                | What You Learned                                         |
| -------------------- | -------------------------------------------------------- |
| **Web Fundamentals** | HTML structure, CSS styling, JavaScript interactivity    |
| **Tailwind CSS**     | Utility-first styling, responsive design                 |
| **TypeScript**       | Type safety, interfaces, catching bugs early             |
| **React**            | Components, props, state, event handling                 |
| **Next.js**          | File-based routing, server/client components, API routes |
| **AI SDK**           | Structured data generation with Zod schemas              |

***

## 📚 Continue Learning

<CardGroup>
  <Card title="Next.js Learn" icon="graduation-cap" href="https://nextjs.org/learn">
    Free, interactive course - highly recommended!
  </Card>

  <Card title="Next.js Docs" icon="book" href="https://nextjs.org/docs">
    Complete reference documentation
  </Card>

  <Card title="Tailwind CSS" icon="palette" href="https://tailwindcss.com/docs">
    All utilities and components
  </Card>

  <Card title="AI SDK Guide" icon="robot" href="https://ai-sdk.dev/docs">
    Build more AI-powered features
  </Card>

  <Card title="React Docs" icon="atom" href="https://react.dev">
    Official React documentation
  </Card>

  <Card title="TypeScript Handbook" icon="code" href="https://www.typescriptlang.org/docs/handbook/">
    Deep dive into TypeScript
  </Card>
</CardGroup>

***

## 🛠️ Tools & Resources

### Development Tools

| Tool        | Purpose                                   | Link                                                   |
| ----------- | ----------------------------------------- | ------------------------------------------------------ |
| **Bun**     | Fast JavaScript runtime & package manager | [bun.sh](https://bun.sh)                               |
| **VS Code** | Recommended code editor                   | [code.visualstudio.com](https://code.visualstudio.com) |
| **Vercel**  | Deploy Next.js apps easily                | [vercel.com](https://vercel.com)                       |

### Recommended VS Code Extensions

* [Tailwind CSS IntelliSense](https://marketplace.visualstudio.com/items?itemName=bradlc.vscode-tailwindcss)
* [ESLint](https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint)
* [Prettier](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode)
* [TypeScript Hero](https://marketplace.visualstudio.com/items?itemName=rbbit.typescript-hero)

***

## 🚀 Contribute to Open Source

Ready to apply your skills? Both RMIT NCT and Tuturuuu are open for contributions!

### RMIT NCT Hub

<Card title="RMIT NCT Hub" icon="github" href="https://github.com/rmit-nct/hub">
  The official NCT Club platform repository
</Card>

```bash theme={null}
# Clone NCT Hub
git clone https://github.com/rmit-nct/hub.git
cd hub && bun install && bun dev
```

<Note>
  **Our Mission**: Help NCT become the **best technology club at RMIT**. Every contribution you make helps fellow students learn, grow, and become the best versions of themselves. Together, we're building something that matters!
</Note>

***

### Tuturuuu Platform

<Card title="Tuturuuu Platform" icon="github" href="https://github.com/tutur3u/platform">
  The platform that powers tuturuuu.com
</Card>

```bash theme={null}
# Clone Tuturuuu Platform
git clone https://github.com/tutur3u/platform.git
cd platform && bun install && bun dev
```

<Note>
  **Our Vision**: Tuturuuu aims to **build a better world for everyone, everywhere**—starting with how you work. By contributing, you're not just writing code; you're helping shape the future of productivity and collaboration. 🌏
</Note>

***

### Good First Issues

Look for issues labeled `good first issue` on GitHub - these are perfect for newcomers!

<CardGroup>
  <Card title="NCT Hub Issues" icon="github" href="https://github.com/rmit-nct/hub/issues">
    Find issues on NCT Hub
  </Card>

  <Card title="Tuturuuu Issues" icon="github" href="https://github.com/tutur3u/platform/issues">
    Find issues on Tuturuuu
  </Card>
</CardGroup>

***

## 🏗️ Project Ideas

Build these to practice your skills:

<CardGroup>
  <Card title="Personal Portfolio" icon="user">
    Showcase your projects with Next.js and Tailwind
  </Card>

  <Card title="To-Do App" icon="check">
    Practice React state management
  </Card>

  <Card title="Blog" icon="newspaper">
    Build with Next.js file-based routing
  </Card>

  <Card title="AI Flashcard Generator" icon="robot">
    Combine AI SDK with structured data
  </Card>
</CardGroup>

***

## 📢 Stay Connected

### RMIT SGS Neo Culture Technology Club

<CardGroup>
  <Card title="Website" icon="globe" href="https://rmitnct.club">
    Visit our platform
  </Card>

  <Card title="GitHub" icon="github" href="https://github.com/rmit-nct">
    Follow our open-source work
  </Card>
</CardGroup>

### Tuturuuu

<CardGroup>
  <Card title="Website" icon="globe" href="https://tuturuuu.com">
    Learn more about Tuturuuu
  </Card>

  <Card title="GitHub" icon="github" href="https://github.com/tutur3u/platform">
    Explore the codebase
  </Card>
</CardGroup>

***

## 💡 Quick Reference Card

Save this for later:

```
# Create a Next.js app
bunx create-next-app@latest my-app

# Start development
cd my-app && bun dev

# Project structure
app/page.tsx        → Home page
app/about/page.tsx  → /about page
app/api/*/route.ts  → API routes

# Key packages
bun add tailwindcss  → Styling
bun add ai zod       → AI SDK
```

***

## 💼 Join Tuturuuu

Interested in what we're building for the future of work?

<Card title="Tuturuuu Careers" icon="briefcase" href="https://tuturuuu.com/careers">
  Explore open positions and join our team
</Card>

Send your CV to **[careers@tuturuuu.com](mailto:careers@tuturuuu.com)**. We can't wait to see what's next for you, Tuturuuu, and potentially, **us**. ✨

***

## 🙏 Thank You!

Thank you for joining this workshop! Remember:

> **"The best way to learn is by building."**

Start with small projects, make mistakes, learn from them, and keep building. We can't wait to see what you create!

***

<Note>
  **Questions?** Reach out to your club officers or join the community Discord. We're here to help!
</Note>

**[← Back to Workshop Overview](/learn/workshops/nextjs-workshop/overview)**


# Master Modern Web Development with Next.js
Source: https://docs.tuturuuu.com/learn/workshops/nextjs-workshop/overview

A 2-hour beginner-friendly workshop by Tuturuuu × RMIT SGS Neo Culture Technology Club

<Info>
  📅 **Tuesday, December 16, 2025** | ⏰ **1:45 PM – 4:00 PM**

  **Duration**: \~2 hours of content + time for Q\&A and free exploration | **Level**: Beginner-friendly
</Info>

## 🤝 A Collaboration

This workshop is a collaboration between **[Tuturuuu](https://tuturuuu.com)** and **[RMIT SGS Neo Culture Technology Club](https://rmitnct.club)**.

Next.js is the core technology powering the club's digital infrastructure. This workshop is an essential step for any member who wishes to dive deep into advanced web development and eventually contribute to the club's open-source projects.

## 🏆 Powered by Next.js

Next.js is trusted by industry leaders worldwide:

<CardGroup>
  <Card title="Global Brands" icon="building" href="https://nextjs.org/showcase">
    TikTok, Nike, Notion, Anthropic, LG, and many more.
  </Card>

  <Card title="Tuturuuu" icon="rocket" href="https://tuturuuu.com">
    Extensively uses Next.js across all its products and platforms.
  </Card>

  <Card title="rmitnct.club" icon="globe" href="https://rmitnct.club">
    NCT Club's official platform—a fork of [tutur3u/platform](https://github.com/tutur3u/platform).
  </Card>

  <Card title="Neo League 2025" icon="trophy" href="https://nova.ai.vn/competitions/neo-league/prompt-the-future/about">
    NCT Club's **first-ever scale-3 event** on Nova.
  </Card>
</CardGroup>

## 👨‍🏫 Your Instructor

<img alt="Vo Hoang Phuc with NCT Club" />

**Vo Hoang Phuc**

* Chairman, Founder & CEO @ [Tuturuuu](https://tuturuuu.com)
* Former Technical Vice President (Generation 6) @ RMIT SGS Neo Culture Technology Club

<Note>
  **A Personal Story**: *"I started my journey the hard way—jumping straight into Next.js, skipping HTML, CSS, and JavaScript entirely! I built my first personal website [vohoangphuc.com](https://vohoangphuc.com), which slowly inspired me to build something for everyone else: [tuturuuu.com](https://tuturuuu.com). By the end of my first year, what started as humble steps turned into a platform. Today, you're learning the foundations I wish I had learned first!"*
</Note>

## 🎯 What You'll Learn

By the end of this 2-hour session, you'll understand:

* **Web fundamentals**: How HTML, CSS, and JavaScript work together
* **Modern styling**: Building beautiful UIs with Tailwind CSS
* **Type safety**: Writing reliable code with TypeScript
* **Component-based development**: Building UIs with React
* **Full-stack framework**: Creating production-ready apps with Next.js
* **AI integration**: Generating structured data with Vercel AI SDK

## ⏱️ Session Timeline

| Actual Time | Topic                                                                    | Offset | Duration |
| ----------- | ------------------------------------------------------------------------ | ------ | -------- |
| 1:45 PM     | Welcome & Setup                                                          | 0:00   | 10 min   |
| 1:55 PM     | [Web Fundamentals](/learn/workshops/nextjs-workshop/01-web-fundamentals) | 0:10   | 15 min   |
| 2:10 PM     | [Tailwind CSS](/learn/workshops/nextjs-workshop/02-tailwind-css)         | 0:25   | 15 min   |
| 2:25 PM     | [TypeScript](/learn/workshops/nextjs-workshop/03-typescript)             | 0:40   | 15 min   |
| 2:40 PM     | ☕ Break                                                                  | 0:55   | 5 min    |
| 2:45 PM     | [React Basics](/learn/workshops/nextjs-workshop/04-react)                | 1:00   | 20 min   |
| 3:05 PM     | [Next.js](/learn/workshops/nextjs-workshop/05-nextjs)                    | 1:20   | 25 min   |
| 3:30 PM     | [AI SDK](/learn/workshops/nextjs-workshop/06-ai-sdk)                     | 1:45   | 10 min   |
| 3:40 PM     | [Next Steps](/learn/workshops/nextjs-workshop/07-next-steps)             | 1:55   | 5 min    |
| 3:45 PM     | 🎯 Q\&A & Free Exploration                                               | 2:00   | 15 min   |

```mermaid theme={null}
graph LR
    A["🌐 Web Basics"] --> B["🎨 Tailwind"]
    B --> C["📝 TypeScript"]
    C --> D["☕ Break"]
    D --> E["⚛️ React"]
    E --> F["▲ Next.js"]
    F --> G["🤖 AI SDK"]
    G --> H["🚀 Next Steps"]

    style A fill:#e34c26,color:#fff
    style B fill:#38bdf8,color:#fff
    style C fill:#3178c6,color:#fff
    style E fill:#61dafb,color:#000
    style F fill:#000,color:#fff
    style G fill:#4f46e5,color:#fff
    style H fill:#22c55e,color:#fff
```

## 🛠️ Prerequisites

**All you need is a laptop!** We'll guide you through everything else.

### Recommended Setup

Before the workshop, please install:

1. **[Bun](https://bun.sh)** - A fast JavaScript runtime and package manager
   ```bash theme={null}
   curl -fsSL https://bun.sh/install | bash
   ```

2. **[Visual Studio Code](https://code.visualstudio.com)** - Our recommended code editor

3. **VS Code Extensions** (optional but helpful):
   * [Tailwind CSS IntelliSense](https://marketplace.visualstudio.com/items?itemName=bradlc.vscode-tailwindcss)
   * [ESLint](https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint)
   * [Prettier](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode)

## 📚 Resources

Throughout this workshop, we'll reference these resources:

### Beginner Tutorials (W3Schools)

| Technology | Tutorial                                              |
| ---------- | ----------------------------------------------------- |
| HTML       | [w3schools.com/html](https://www.w3schools.com/html/) |
| CSS        | [w3schools.com/css](https://www.w3schools.com/css/)   |
| JavaScript | [w3schools.com/js](https://www.w3schools.com/Js/)     |

### Official Documentation

| Technology    | Documentation                                                                  |
| ------------- | ------------------------------------------------------------------------------ |
| TypeScript    | [TypeScript Handbook](https://www.typescriptlang.org/docs/handbook/intro.html) |
| Next.js       | [nextjs.org/docs](https://nextjs.org/docs)                                     |
| Tailwind CSS  | [tailwindcss.com](https://tailwindcss.com)                                     |
| Vercel AI SDK | [ai-sdk.dev](https://ai-sdk.dev)                                               |
| Bun           | [bun.sh](https://bun.sh)                                                       |

## 🚀 Ready?

Let's begin with [Web Fundamentals →](/learn/workshops/nextjs-workshop/01-web-fundamentals)


# Agent Operating Manual
Source: https://docs.tuturuuu.com/overview/agent-operating-manual

Field guide summarizing the AGENTS.md policies for autonomous contributors inside the Tuturuuu monorepo.

This page distills the canonical rules defined in [AGENTS.md](https://github.com/tutur3u/platform/blob/main/AGENTS.md). Treat the original document as the source of truth. The root file is now a hard-policy index; detailed reusable implementation patterns live in the repo-local Tuturuuu Codex plugin skills under `plugins/tuturuuu/skills/*/references/`.

## Core Principles

* **Least privilege** – Touch only the files required for the task and keep changes scoped.
* **Shared worktree discipline** – Assume humans or other agents may have dirty files in the same checkout; inspect before editing and never clean up work you do not own.
* **Deterministic & reproducible** – Generated artefacts must come from scripted commands; rerunning the workflow should produce the same result.
* **Security first** – Never surface secret values. Reference environment variables by name and keep sensitive flows audited.
* **Document intent** – When behaviour changes, update tests and docs alongside the code so the platform stays explainable.
* **Human-in-the-loop** – Escalate when work exceeds the documented boundaries (e.g., major refactors, new third-party services, complex data backfills).
* **Focused knowledge** – Add durable gotchas to the narrowest plugin skill reference instead of expanding the root operating manual by default.

## Capability Matrix

| Domain                  | You May                                                                          | You Must                                        | Never                                                      |
| ----------------------- | -------------------------------------------------------------------------------- | ----------------------------------------------- | ---------------------------------------------------------- |
| **Code (TS/JS)**        | Build Next.js App Router routes, React server/client components, shared packages | Add/adjust tests & types, update related docs   | Ship breaking public API changes without a `BREAKING` note |
| **Code (Python)**       | Modify apps under `apps/*` (python) with env isolation                           | Maintain pinned requirements / lockfiles        | Blend unrelated refactors into feature work                |
| **Database (Supabase)** | Author migrations in `apps/database/supabase/migrations`, run typegen            | Commit regenerated `@tuturuuu/types` output     | Hand-edit generated type files                             |
| **AI Endpoints**        | Add handlers under `app/api/...` using Vercel AI SDK                             | Enforce auth + feature flags, validate payloads | Expose provider keys or skip validation                    |
| **Tooling**             | Adjust configs (`biome.json`, `turbo.json`, etc.)                                | Document the rationale                          | Remove caching or security settings silently               |
| **Docs**                | Update `.md`/`.mdx` for accuracy                                                 | Cross-link neighbouring guides                  | Invent behaviour that is not implemented                   |
| **Dependencies**        | `cd <app-or-package> && bun add <pkg>` / remove deps                             | Prefer `workspace:*` for internal packages      | Add duplicate versions already satisfied                   |

## Mandatory Guardrails

1. Do not run long-lived dev/build commands unless a human requests it (e.g., `bun dev`, `bun run build`).
2. **Supabase apply is user-only** – prepare migrations, but the user runs `bun sb:push` / `bun sb:linkpush`.
3. Run formatters and checks required for files you changed, but keep auto-fixes scoped to your owned paths.
4. Avoid committing noisy logs; add diagnostics only when they materially aid debugging.
5. Never commit credentials, tokens, destructive migrations, or unrelated worktree changes.
6. Do not stage, rename, delete, or format unknown dirty/untracked files; treat them as human-owned or other-agent-owned until confirmed.
7. Do not manually bump release versions for ordinary authored work. Release Please owns package versions, changelogs, and the account-gated web badge version. Keep release-please annotations intact.

## Escalate When…

* A migration needs >30 lines of backfill logic.
* A refactor would touch more than three apps or five packages.
* Introducing a new external service, adjusting auth flows, or changing env-var contracts.

## Canonical Workflows (Cheat Sheet)

* **Add/Update dependency** – scope → `cd <app-or-package> && bun add <pkg>` → ensure types/docs → run targeted build.
* **New shared package** – scaffold under `packages/`, add `package.json` + `tsconfig`, export via `src/index.ts`, add tests & README, then build/test.
* **Next.js API route** – implement under `app/api/.../route.ts`, enforce auth, validate with Zod, add tests or docs.
* **AI structured endpoint** – define schema in `packages/ai`, use `generateObject`/`streamObject`, guard feature flags, redact secrets, handle errors gracefully.
* **Supabase migration** – run `bun sb:new`, author additive SQL, request user to apply and regenerate types via `bun sb:typegen`, commit regenerated files together.

See AGENTS.md §4 for full step-by-step instructions across all workflows.

## Focused Skill References

Use the repo-local Tuturuuu Codex plugin for detailed pattern catalogs:

* `$tuturuuu-platform` for web/API/shared UI patterns.
* `$tuturuuu-web-release` for version badge metadata, `PLATFORM_BUILD_*`, and release-please-managed `TUTURUUU_PLATFORM_VERSION` updates.
* `$tuturuuu-database` for Supabase, protected-table API, and storage patterns.
* `$tuturuuu-ci-docs` for docs, CI, and Docker blue/green deployment runbooks.
* `$tuturuuu-development-tooling` for root scripts, plugin validation, and CI/tooling behavior.
* `$tuturuuu-agent-coordination` for shared worktrees, active notes, handoffs, and commit-window coordination.
* `$tuturuuu-commit` for scoped commits, exact staging, and commit-window claim/wait/release.
* `$tuturuuu-mobile-task-board` for Flutter mobile task-board and mobile UX patterns.

## Collaboration Protocol

* Roles: Execution (ship code/docs), Review (verify lint/type/test/build), Architecture (cross-cutting improvements), Knowledge (docs & schema sync).
* Only one agent modifies a file set at a time; reviewers work read-only unless paired.
* Prefer linear history (rebases) and group commits by concern (schema vs code vs docs).

### Open Pull Request Worktrees

Every open Tuturuuu pull request must be reviewed, fixed, validated, and prepared
for merge in an isolated checkout under `.worktrees/`. Do not switch the shared
main checkout onto the PR branch. Immediately run `bun setup` after creating the
worktree so dependencies and required workspace builds are ready. In a
non-interactive environment where Portless would require sudo to bind port 443,
run `SKIP_PORTLESS_SETUP=1 bun setup` so only the interactive proxy step is
skipped.

Keep the worktree and its local task branch for as long as the PR remains open.
After GitHub confirms the PR merge is present on `main` and required post-merge
verification is complete, remove the completed worktree and delete its local
task branch. Do not use that cleanup as permission to remove unrelated
worktrees, branches, or unmerged work.

When a user authorizes ongoing integration rather than a single PR, checkpoint
completed lanes periodically. Integrate a scoped commit onto current `main`,
wait until every workflow for that exact main SHA is green, run `bun git-sync`,
and verify production before removing the completed worktree and its local task
branch. Retain dirty, blocked, unmerged, user-owned, and other-agent-owned
lanes.

Rust build output is rebuildable but can be large in retained worktrees. Use
`bun rust-cache report` to measure it and only the repository-owned bounded
`prune`/`auto` commands to reclaim `apps/backend/target` space. Inspect the
worktree first and never delete source or an unmerged worktree as cache cleanup.

### Shared Worktree Coordination

Use `tmp/agent-coordination/` as the ignored, in-worktree conversation space for agent-to-agent coordination. This is not source-controlled and should not be committed.

Before editing, run `git status --short`. If dirty or untracked files already exist, record which ones are unrelated and leave them alone. If `tmp/agent-coordination/` exists, inspect top-level notes marked `working`, `blocked`, or `handoff` before choosing files. Stale active notes still count as ownership signals until checked against the current worktree.

Use exact `Status:` values in coordination notes: `working`, `blocked`, `handoff`, or `done`. Put details such as `committed`, `done with concerns`, or follow-up context in `Needs`, `Verification`, or `Risks`. Treat missing or noncanonical statuses as active until resolved.

Completed context should move out of the active scan path. Use `tmp/agent-coordination/archive/<YYYY>/<original-note-name>.md` for notes that are already marked `done` and no longer need top-level visibility. Search the archive with targeted keywords when a task mentions prior work or a workflow decision needs history; archived notes explain context, verification, and residual risks, but they are not active ownership claims.

Create a note named `tmp/agent-coordination/<YYYYMMDD-HHMMSS>-<agent-or-task>.md` when the worktree is dirty, active notes touch a nearby area, the task is long-running, or the task changes coordination, commit, validation, CI, deployment, plugin, or skill behavior.

Each note should include:

* `Agent`: stable name or session id if available.
* `Intent`: one-line task summary.
* `Owned paths`: files or directories the agent expects to edit.
* `Observed dirty paths`: relevant pre-existing paths the agent will not touch.
* `Status`: `working`, `blocked`, `handoff`, or `done`.
* `Needs`: specific question or response requested from other agents.
* `Commit window`: `not needed`, `claimed`, `waiting`, `blocked`, or `released` when a commit may be needed.
* `Verification`: commands already run, when available.
* `Risks`: remaining overlap or validation risk, when relevant.

If two agents need the same file set, do not race. Reply in `tmp/agent-coordination/`, choose a disjoint slice, or ask the human partner to arbitrate. Do not edit another agent's note unless explicitly asked. Before the final response or handoff, update your own note to `done`, `handoff`, or `blocked` with verification and residual risks. Archive only your own completed `done` note unless the human partner explicitly requests broader cleanup. When committing, stage explicit paths only and never stage coordination notes or archived coordination notes. If a repo-wide check or commit hook fails because of another agent's files, do not fix those files just to satisfy the hook; report the blocker and keep your own diff scoped.

For parallel subagent work, split lanes before spawning workers. Each worker
needs a narrow owned path set, forbidden overlap, validation commands, and a
handoff contract; workers should not stage or commit unless that is their
explicit lane. Make the lane contract explicit: owner, mode, owned paths,
excluded paths, generated outputs, validation, handoff shape, lifecycle
(`pending`, `active`, `handoff`, `integrated`, or `closed`), and commit
authority. Do not overlap implementation worker write paths unless the parent
note records an explicit takeover or continuation. In Codex, use either a typed
worker/explorer prompt with explicit lane context or a full-history fork without
a role override; combining both is rejected by the subagent harness. The
coordinator owns integration: review
worker diffs, regenerate
shared artifacts such as route trees, route manifests, route overrides, OpenAPI
snapshots, docs navigation, sorted translations, or generated DB types after
inputs are stable, then stage exact paths. After each integrated slice, refresh
status, close completed subagents in the harness, mark their lanes integrated or
closed in the parent note, list validation and unrelated blockers, and choose the
next lane from current worktree state. Existing staged files belong to the
staging agent or coordinator until explicitly reassigned; if a path is `MM`,
review both staged and unstaged portions before committing.

When unrelated dirty files touch shared generated inputs or outputs such as route
trees, migration manifests, `packages/internal-api/src/index.ts`, generated DB
types, message bundles, or `bun.lock`, default new implementation work to an
isolated worktree or read-only audit unless the write set is clearly disjoint
and no generator or root formatter will scan those files. If you must generate
from a dirty shared checkout, use a clean tree or explicit input/output paths and
record the base commit, scanned globs, copied lane inputs, generator command,
copied-back artifacts, cleanup, and proof that no untracked or other-lane files
leaked into the output.

### Git Commit Window

Use `bun git-commit-window` to serialize Git index and commit operations in a shared checkout. The lock lives at `tmp/agent-coordination/git-commit-window.lock.json`, which is ignored by Git. It is advisory: it does not grant ownership of files and does not allow broad staging. Claims default to 10 minutes, may only be 5-10 minutes, and should be held only for focused staging and commit work.

Claim the window immediately before staging, unstaging, committing, amending, rebasing, or commit-and-push work:

```bash theme={null}
bun git-commit-window claim --owner "<agent/task>" --scope "<commit scope>"
```

If another agent owns the window and waiting is appropriate, use `wait`. It sleeps until the current lock is released or expires, then atomically claims the window before notifying the waiting agent. The wait timeout can be longer than the claim TTL, but the claim received after waking is still limited to 5-10 minutes:

```bash theme={null}
bun git-commit-window wait --owner "<agent/task>" --scope "<commit scope>"
```

Use `status` to inspect, `check --token <token>` before committing if needed, and `release --token <token>` after the commit operation succeeds or aborts. Do not put tokens in coordination notes.

For commits made in a dirty shared checkout, record a closeout packet in the
parent note: staged path list, validation results for the staged set, hook result
or proof-gated `--no-verify` rationale, commit hash, release confirmation, and
remaining dirty-path summary.

## Tooling & Environment Rules

* Single package manager: **Bun**. Use workspace filters (`bun --filter ...`) to target apps/packages.
* Use `bun check:now` when you need to cancel queued or running repo-root `bun check` invocations for the current workspace and start a fresh pass immediately.
* Supabase lifecycle via scripts: `sb:start`, `sb:stop`, `sb:new`, `sb:up`, `sb:typegen` (user applies pushes).
* Do not invent new cache stores; rely on Turborepo, Bun, BuildKit, and Cargo
  caches plus the documented bounded cleanup wrappers.
* Python services (`apps/discord/`) maintain their own pinned dependencies and README instructions.

## Testing & Quality Expectations

* Add happy-path and edge-case coverage where feasible; default to Vitest via `bun run test` or filtered scope.
* For DB changes, provide migrations, request the user apply them, then verify regenerated types.
* Performance-sensitive changes should document rationale in-code (≤3 lines) plus PR notes.
* For `html2canvas`-based preview exports, inline critical SVG brand marks (or use raster assets) and provide a solid export background color so downloaded images do not lose logos or pick up transparent-edge artifacts.

For deeper detail—such as React Query policy, toast usage rules, or Tailwind dynamic color guidance—refer directly to [AGENTS.md](https://github.com/tutur3u/platform/blob/main/AGENTS.md#readme).


# Documentation Organization Guide
Source: https://docs.tuturuuu.com/overview/organization-guide

Understand the Tuturuuu documentation structure and how to extend it.

# Documentation Organization Guide

Welcome to the reorganized Tuturuuu documentation space. This guide explains the new structure so you can find information quickly and add new content with confidence.

## 🧭 Top-Level Map

| Section       | Purpose                                                            | Key Entry Points                                                                                 |
| ------------- | ------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------ |
| **Overview**  | Vision, mission, and company playbooks                             | [Vision & Mission](/overview/vision), [Agent Operating Manual](/overview/agent-operating-manual) |
| **Platform**  | Product experience, AI systems, shared components, personalization | [Platform Overview](/platform/overview)                                                          |
| **Build**     | Local setup, monorepo workflows, CI/CD                             | [Build & Ship](/build/overview)                                                                  |
| **Learn**     | Examples, experiments, prompt engineering                          | [Learn & Experiment](/learn/overview)                                                            |
| **Reference** | Stable APIs and integration contracts                              | [Reference Home](/reference/overview)                                                            |

Each section contains focused subpages that keep related content together. Navigation in the sidebar follows this same hierarchy.

## 📂 Directory Layout

```text theme={null}
apps/docs/
├── overview/             # Company vision and organizational guides
├── platform/             # Product experience, AI, components, personalization
├── build/                # Development tooling and workflows
├── learn/                # Examples, experiments, prompt engineering
└── reference/            # API contracts and schemas
```

Assets such as images remain in `apps/docs/images/`. Shared assets for navigation (logo, favicon) sit alongside `docs.json`, which is the single source of truth for sidebar navigation, theme, and grouping (Mintlify reads it on build). Adding a file to one of the directories above does **not** publish it until you also register it in `docs.json`.

## ✍️ Adding New Content

1. **Pick a Section** – Choose the directory that matches your topic. When in doubt, align with how end users will search for the information.
2. **Create the File** – Use front matter with `title`, `description`, and `updatedAt` fields. Example:

   ```mdx theme={null}
   ---
   title: 'My Guide'
   description: 'Brief purpose statement.'
   updatedAt: '2026-06-21'
   ---
   ```

   Set `updatedAt` to the date you last meaningfully changed the page (`YYYY-MM-DD`). Keep the single-quote style to match the rest of the docs set.
3. **Cross-Link Thoughtfully** – Prefer absolute links such as `/platform/features/command-center-dashboard` so moves do not break references.
4. **Update Navigation** – Add the new page to `apps/docs/docs.json` in the appropriate group.

## ✅ Conventions to Remember

* **Navigation** is defined in `apps/docs/docs.json` and should mirror the directory layout; keep related pages together.
* **Diagrams** use Mermaid syntax (rendered by Mintlify).
* **Images** belong in `apps/docs/images/` and are referenced with absolute paths (`/images/...`).
* **Internal links** use absolute documentation paths (for example `/build/overview`, not `/overview`) so moving files does not break references.
* **Linting** — Markdown and MDX are explicitly excluded from Biome (`biome.json` ignores `**/*.md` and `**/*.mdx`), so `bun check` does not lint these pages. Validate docs by previewing them with the Mintlify CLI and checking that links resolve and front matter is present, rather than relying on Biome formatting.

Need inspiration for structuring a new guide? Browse the [Platform Overview](/platform/overview) and [Build & Ship](/build/overview) pages—they demonstrate the preferred narrative pattern (context → diagrams → next steps).

If anything feels missing or confusing, open an issue with the `docs` label so we can continue improving the experience together.


# Vision & Mission
Source: https://docs.tuturuuu.com/overview/vision

The north star for Tuturuuu—why we exist and the future we are building.

<img alt="Hero" />

# Tuturuuu: Official Company & Product Documentation

### Executive Summary: The Third Era of Technology

Tuturuuu is not merely another productivity startup; it is our answer to a fundamental question: **What if technology existed to serve human potential instead of harvesting attention?** We are building the world's first intelligent, open-source operating system for modern work and life, with the ambition to become the "Google" of Vietnam and a global benchmark for transformative technology. Powered by Mira—our proactive AI companion and the JARVIS we envisioned—the Tuturuuu platform unifies calendars, tasks, communications, and knowledge to eliminate digital friction and return focus to the people doing the work. This is the dawn of the **Third Era of technology: the Age of Partners**, where the impossible becomes possible for everyone, everywhere.

* **Vision Slogan:** Unlocking Human Potential.
* **User-Benefit Slogan:** Your Life, In Sync.
* **Product Category Slogan:** The Intelligent OS for Modern Work.

### Our Manifesto: Core Beliefs Driving Tuturuuu

* **Focus is the new superpower.** In a world engineered for distraction, the ability to sustain deep work is the defining competitive advantage.
* **Technology must be an extension of human will, not a cage for our attention.** Engagement-driven platforms erode our best selves; we build software to reverse that trend.
* **Radical transparency and open communities win.** Foundational technology should never be a black box. Our open-source philosophy creates trust, improves security, and accelerates innovation.
* **Impact over activity.** Productivity is not about doing more; it is about creating more value. Tuturuuu exists to give people the mental space for their next breakthrough idea.
* **Potential has no postcode.** We champion a future in which brilliant ideas can emerge from any street, village, or classroom—because access to world-class tools should never be limited by geography or status.

### Mission and Vision

* **Mission (What):** Wage war on digital noise by building an intelligent, unified, and open platform that automates administrative work and eliminates context-switching friction.
* **Vision (Why):** Create a future where technology unlocks humanity's potential—liberating our collective focus so we can solve the world's most important challenges while making world-class innovation accessible to everyone, everywhere.

### The Problem We Solve: The Costs of Digital Friction

Modern professionals are hired for their minds but trapped in low-value administrative work—a silent epidemic we call the Great Betrayal of Modern Work. Digital friction exacts three distinct costs:

1. **Financial Cost:** Over **21 hours per knowledge worker each week** vanish into "work about work"—a trillion-dollar drag on global productivity.
2. **Cognitive Cost:** Fragmented tools force constant context-switching, imposing a mental tax that slashes productive output by **up to 40%** and fuels burnout.
3. **Innovation Cost:** The next breakthrough is suffocated by inboxes, status meetings, and spreadsheets. Our collective future is lost to noise.

### The Tuturuuu Solution: Entering the Age of Partners

The First Era produced passive tools; the Second Era birthed attention-harvesting platforms. Tuturuuu inaugurates the Third Era: proactive ecosystems that amplify human potential. In this paradigm the user becomes the **Visionary**, and AI acts as the intelligent **Partner**—anticipating needs, automating busywork, and protecting focus.

### Competitive Landscape: A Category of One

|                     | **Fragmented & Reactive (Era 2)**                                                         | **Integrated & Proactive (Era 3)**                                                 |
| :------------------ | :---------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------- |
| **Description**     | A "Frankenstein stack" of separate apps requiring manual stitching and constant commands. | A unified nervous system where AI anticipates needs and orchestrates workflows.    |
| **Examples**        | Slack + Asana + Google Drive + Notion                                                     | **Tuturuuu**                                                                       |
| **User Experience** | High cognitive load, relentless context-switching.                                        | Seamless flow state with preserved focus.                                          |
| **Our Moat**        | Point solutions compete feature-by-feature.                                               | We deliver a 10× integrated experience anchored by Aurora's growing context graph. |

### Product & AI Ecosystem: How We Deliver the Future

#### Application Layer — Tools for Flow

A cohesive suite that behaves like one organism:

* **Tuturuuu Calendar (Smart Calendar):** AI auto-scheduling that allocates time by deadlines, priorities, and personal work rhythms.
* **Tuturuuu Tasks (Smart Tasks):** Centralized task hub capturing actions from email, chat, and meetings, then scheduling them in Tuturuuu Calendar.
* **Tuturuuu Meet (Smart Meetings):** End-to-end meeting solution featuring collaborative planning, location voting, and AI-generated summaries with tracked actions.
* **TuMail & TuChat (Smart Communications):** Integrated communications hub where AI surfaces commitments and routes them to Tuturuuu Tasks and Tuturuuu Calendar.
* **TuDrive (Unified Storage):** Secure cloud storage woven through tasks, documents, and conversations for effortless knowledge flow.
* **TuTrack (Mindful Time Tracking):** Lightweight tracking with Pomodoro rhythms to encourage focused work and healthy breaks.

For a deep dive into our GTD-aligned daily experience, explore the [Command Center Dashboard](/platform/features/command-center-dashboard).

#### AI Core — Architecture of Intelligence

* **Mira (Soul & Voice):** The empathetic conversational interface—translating complex capabilities into a warm, trustworthy partner.
* **Aurora (Nervous System):** The contextual engine that links related emails, tasks, files, and events, creating our primary data moat.
* **Rewise (Collective Mind):** Aggregator of leading AI models (OpenAI, Gemini, Anthropic, and more) to ensure Mira always draws from the best knowledge.
* **Nova (Conscience & Forge):** Our prompt-engineering and alignment platform, shaping how Mira reasons and guarantees safety.
* **Crystal (Bridge to Humanity):** Multi-modal embodiment of Mira enabling real-time collaboration via voice, video, and screen sharing.

### Long-Term Vision: The Tuturuuu Ecosystem

Our roadmap stretches far beyond productivity checklists. We are assembling an ecosystem where every component—people, agents, data, and services—cooperates to help anyone transform ambition into reality.

#### Mira (Codename Jarvis): The Life Operating System

* **Mira** is the next-generation companion we envisioned as JARVIS—an autonomous guardian that plans, reasons, and acts on your behalf so you can simplify life and accomplish more.
* Mira synchronizes calendars, goals, finances, communications, and personal knowledge, surfacing proactive recommendations instead of passive reminders.
* She learns from context, understands intent, and orchestrates the right Tuturuuu tools—or external services—without requiring manual hand-offs.

#### Multi-Agent Intelligence Fabric

* Specialized agents (planning, finance, research, wellness, creative) collaborate through Mira to deliver end-to-end outcomes.
* Agents talk to each other via shared context graphs, ensuring that insights collected in one domain (e.g., research) immediately inform actions in another (e.g., scheduling or budgeting).
* The ecosystem adapts dynamically, deploying the minimal number of agents necessary to solve a problem while maintaining full user oversight.

#### Learning Loops & Continuous Improvement

* **AI memories** capture outcomes, preferences, and feedback, allowing the system to anticipate needs with greater precision over time.
* A **data crawler** and **internal knowledge base** ingest documents, conversations, and educational content, grounding every action in trusted information.
* **Reinforcement learning playgrounds** and Nova's prompt-engineering workflows close the loop between customer challenges and product enhancements, turning every interaction into a learning opportunity.
* Metrics, scoring, and feedback dashboards quantify impact, guiding both automated improvements and human-crafted iteration.

#### Execution & Automation Layer

* **Aurora** coordinates cloud code execution, Cron jobs, and real-time integrations so agents can take decisive, auditable actions.
* External APIs, partner platforms, and even physical devices connect through unified orchestration, ensuring Mira (our Jarvis) can reach beyond Tuturuuu when a task demands it.
* Guardrails keep automation transparent and reversible, reinforcing trust while delivering tangible outcomes.

#### Democratizing Breakthroughs

* Educational pathways and community programs share the system's capabilities with schools, startups, and enterprises, nurturing the next generation of builders.
* By lowering the barrier to world-class technology, Tuturuuu enables creators everywhere—from Ho Chi Minh City to remote villages—to solve local problems with global-grade tools.
* This long-term vision is how we intend to make the impossible possible for everyone, everywhere.

### Visualizing the Tuturuuu Ecosystem

#### End-to-End Interaction Lifecycle

```mermaid theme={null}
graph LR
    A[Visionary] -->|State goal| B[Mira]
    B -->|Plan & delegate| C[Agent Mesh]
    C -->|Fetch context| D[Aurora]
    D -->|Get knowledge| E[Rewise]
    C -->|Validate| F[Nova]
    C -->|Execute| G[Apps]
    G -->|Updates| A
    C -->|Log outcomes| H[Feedback Loop]
    H -->|Improve| B

    style B fill:#4f46e5,stroke:#3730a3,color:#fff
    style C fill:#4f46e5,stroke:#3730a3,color:#fff
```

#### Continuous Learning Loop

```mermaid theme={null}
graph TD
    Start([Start]) --> Capture[Capture Intent]
    Capture --> Contextualize[Contextualize]
    Contextualize --> Plan[Plan Strategy]
    Plan --> Execute[Execute Actions]
    Execute --> Reflect[Reflect on Results]
    Reflect --> Improve[Improve Models]
    Improve --> Capture
    Reflect --> End([Goal Satisfied])

    style Capture fill:#4f46e5,stroke:#3730a3,color:#fff
    style Plan fill:#4f46e5,stroke:#3730a3,color:#fff
    style Improve fill:#4f46e5,stroke:#3730a3,color:#fff
```

#### Layered Architecture Overview

```mermaid theme={null}
graph TB
    subgraph Experience["Experience Layer"]
        Mira["Mira & Crystal"]
        Apps["Tuturuuu Apps"]
    end

    subgraph Intelligence["Intelligence Layer"]
        Agents["Agent Mesh"]
        Aurora["Aurora Context"]
        Nova["Nova Alignment"]
        Rewise["Rewise Knowledge"]
    end

    subgraph Data["Data Layer"]
        Memory["AI Memories"]
        KB["Knowledge Base"]
    end

    subgraph Infra["Infrastructure"]
        Cloud["Cloud Execution"]
        Integrations["Integrations"]
    end

    Mira --> Agents
    Apps --> Agents
    Agents --> Aurora
    Aurora --> Rewise
    Aurora --> Nova
    Nova --> Agents
    Aurora --> Memory
    Memory --> KB
    KB --> Agents
    Cloud --> Agents
    Integrations --> Cloud

    style Agents fill:#4f46e5,stroke:#3730a3,color:#fff
    style Aurora fill:#4f46e5,stroke:#3730a3,color:#fff
```

### Technology Stack & Architecture

* **Frontend:** Next.js, React, TypeScript, Tailwind CSS.
* **Backend & Database:** Postgres, Supabase.
* **Infrastructure & Deployment:** Vercel.
* **Architecture:** Turborepo + Bun monorepo that accelerates collaboration, code sharing, and deterministic deployments. Browse the source at [https://github.com/tutur3u/platform](https://github.com/tutur3u/platform).

### Business Model & Growth Strategy: The Community Flywheel

1. **Open-Source Core:** Publishing our codebase invites global contributors, builds trust, and establishes transparent security practices.
2. **Bottom-Up Adoption (Free Tier):** A generous individual plan seeds Tuturuuu organically inside thousands of organizations.
3. **Product-Led Expansion (Pro & Business Tiers):** Teams upgrade to unlock pooled resources, expanded AI usage, and advanced controls.
4. **Top-Down Value (Enterprise & Platform API):** Broad adoption paves the way for enterprise engagements and a high-margin API exposing Nova, Rewise, and future services.

Plan tiers at a glance:

* **Free:** Mass adoption and community growth.
* **Pro:** Power users and freelancers with increased AI allowances and storage.
* **Business:** Team-centric controls, pooled usage, and enhanced security.
* **Platform API (Future):** B2B access for companies building on Tuturuuu's AI primitives.

### Team & Culture: Building for the Third Era

* **Builders, not employees.** Each teammate acts like a founder within their domain.
* **Pragmatic optimism.** We pair bold ambition with rigorous execution.
* **Relentless ownership.** Decisions come with accountability for outcomes.
* **Transparency by default.** Internal operations mirror our open-source ethos.
* **Vietnam-rooted, globally ambitious.** We build from Southeast Asia with the conviction that world-class technology can originate anywhere.

### Company Information

* **Legal Name:** CÔNG TY CỔ PHẦN TUTURUUU (TUTURUUU JOINT STOCK COMPANY).
* **Abbreviated Name:** TUTURUUU JSC.
* **Tax Code:** 0318898402.
* **Date of Operation:** 02 April 2025.
* **Registered Address:** Tầng 14, Tòa Nhà HM Town, 412 Nguyễn Thị Minh Khai, Phường 05, Quận 3, Thành phố Hồ Chí Minh, Việt Nam.
* **Tax Address:** Tầng 14, Tòa Nhà HM Town, 412 Nguyễn Thị Minh Khai, Phường Bàn Cờ, TP Hồ Chí Minh, Việt Nam.
* **Founder, CEO & Chairman:** Võ Hoàng Phúc.
* **Website:** [https://tuturuuu.com](https://tuturuuu.com).
* **Contact:** [contact@tuturuuu.com](mailto:contact@tuturuuu.com).
* **GitHub:** [https://github.com/tutur3u/platform](https://github.com/tutur3u/platform).

## Setting up

The first step to getting started with Tuturuuu is to set up your development environment.

<CardGroup>
  <Card title="Development Setup" icon="gear" href="/build/development-tools/development">
    Learn how to set up your development environment.
  </Card>
</CardGroup>


# AI Agent Deployment
Source: https://docs.tuturuuu.com/platform/ai/ai-agent-deployment

Operate apps/web-hosted Discord and Zalo AI agents backed by Chat SDK and AI SDK.

The internal Infrastructure → AI Agents module manages root-only agent configs
that are served by `apps/web` webhook routes. It is the first production path
for bidirectional agent presence across Discord and Zalo.

## Runtime Boundary

Deploying an agent enables an `apps/web` webhook endpoint:

```txt theme={null}
/api/v1/webhooks/ai-agents/:adapter/:channelId
```

`apps/web` loads the channel config from root `workspace_secrets`, creates a
Chat SDK runtime through `@tuturuuu/ai/chat-sdk`, and runs the response loop with
AI SDK `ToolLoopAgent`.

Production deployments use Redis so thread subscriptions, dedupe, and locks
survive cold starts and multiple instances. Runtime resolution checks, in order:

1. Root workspace secret `AI_AGENT_CHAT_SDK_STATE_REDIS_URL`.
2. Environment variables `AI_AGENT_CHAT_SDK_STATE_REDIS_URL`, `REDIS_URL`, or
   `DOCKER_WEB_REDIS_URL`.
3. The bundled blue/green Docker Redis service at `redis://redis:6379` when a
   blue/green runtime mount or Docker SRH URL is present.

Local development may use the Chat SDK memory state adapter when no durable
Redis runtime is configured.

Agent response loops and manual external-chat draft generation use the shared
Tuturuuu AI memory layer. Memory is scoped to the operator or channel actor plus
the channel workspace, then stored through the first-party memory sidecar using
the `ai_agents` product metadata. Do not add agent-specific browser memory
calls; all recall, writes, and deletes must stay behind the server-owned
`@tuturuuu/ai/memory` boundary and workspace memory APIs.

Webhook URLs are generated from the canonical public platform origin, not the
incoming request host. Set `AI_AGENT_WEBHOOK_ORIGIN` for an explicit override;
otherwise `WEB_APP_URL`, `NEXT_PUBLIC_WEB_APP_URL`, `NEXT_PUBLIC_APP_URL`,
`PLATFORM_BUILD_DEPLOYMENT_URL`, and production fallback `https://tuturuuu.com`
are used before local request-origin fallback.

## Configuration Storage

Agent configuration stays under root workspace secrets:

```txt theme={null}
AI_AGENT_REGISTRY:<agentId>:meta
AI_AGENT_REGISTRY:<agentId>:instructions
AI_AGENT_REGISTRY:<agentId>:channel:<channelId>:meta
AI_AGENT_REGISTRY:<agentId>:channel:<channelId>:secret:<name>
AI_AGENT_IDENTITY:<wsId>:zalo:<oaId>:<zaloUserId>
AI_AGENT_ZALO_PERSONAL_ENABLED
```

Admin APIs redact channel secrets. One-time generated values are shown only
after rotation.

Feature flags for this surface are also root workspace secrets. Experimental
personal Zalo account support is enabled by default only for the internal root
workspace. Other workspaces require `AI_AGENT_ZALO_PERSONAL_ENABLED = true`;
do not gate it with process environment variables. Phone-history transfer
sends one approval request and uses deliberately low-cadence, cancellable
polling to avoid notification and API spam.

External chat history is mirrored separately in the `private` schema:

```txt theme={null}
private.ai_agent_external_threads
private.ai_agent_external_messages
```

Only server-owned `apps/web` routes call the private RPCs for listing,
syncing, drafting, and sending. Browser clients never read these private tables
directly.

## Chat Discovery

The shared chat UI displays mirrored external AI-agent threads as read-only AI
conversations in the workspace selected for the agent channel. This works in
`apps/web` and the standalone `apps/chat` app. Chat users can inspect mirrored
history there, while root AI-agent admins can use the setup, operations, and
manual-response controls from Infrastructure > AI Agents or the `apps/chat`
agent details sidebar.

The root workspace may still show enabled agent channel setup entries so
operators can jump to channel configuration. Those setup entries are not the
message mirror; mirrored external threads use `ai-agent-thread-<uuid>`
conversation IDs.

Root AI-agent admins can also manage those setup entries from the standalone
`apps/chat` internal workspace. The `internal` workspace resolves to
`ROOT_WORKSPACE_ID`, and admin-visible setup conversations include the minimum
agent/channel IDs needed by the sidebar operations panel. Non-admin chat
viewers still receive scrubbed setup metadata.

## Manual Response Console

Infrastructure > AI Agents is the full setup and operations surface:

* Configure Discord and Zalo credentials, workspace mapping, auto-response, and
  history sync per channel.
* Inspect mirrored external threads and messages.
* Trigger an on-demand external history sync when the adapter supports it,
  including phone-approved transfer sync for personal Zalo accounts.
* Generate a draft with a custom operator prompt and mirrored history context.
* Send the reviewed draft back to the external platform exactly as edited.

Discord can fetch recent thread/channel history through the Chat SDK adapter
when the bot token has the required scopes. Official Zalo channels still rely on
webhook/runtime events. Personal Zalo channels can import Zalo Web-visible
history through **Sync history** and can request phone-approved mobile transfer
history through **Sync phone** when older messages are only present on the
paired mobile device.

The same external-thread operations are available from `apps/chat` for root
AI-agent admins when an external AI-agent thread is selected: sync external
history, draft a manual response, send the reviewed response, and refresh the
mirrored conversation.

## Testing From Apps/Chat

Use `apps/chat` as the operator smoke-test surface after deployment:

1. Open the `internal` workspace and select the AI-agent setup conversation.
2. Confirm setup data loads instead of the metadata-hidden notice.
3. Run **Test** as a readiness check for required credentials and channel
   status. The diagnostics list should pass for agent enabled, channel enabled,
   deployed status, required secrets, webhook URL, workspace mapping, adapter
   account mapping, and recent error state. This does not replace a live
   external-platform round trip.
4. For Discord, set the generated webhook URL as the Interactions Endpoint URL
   so Discord performs its endpoint verification. Then install the app and send
   a live mention/message in the mapped channel. The official references are
   [Discord interactions](https://docs.discord.com/developers/interactions/overview)
   and the
   [Discord quickstart](https://docs.discord.com/developers/quick-start/getting-started).
5. For personal Zalo, set the channel to `Personal account`, open the
   operations tab, run **Pair QR**, scan the QR code from the Zalo mobile app,
   then run **Validate**, **Sync history**, **Sync phone**, **Deploy**, and
   **Start**. Approve the transfer-sync prompt on the phone when **Sync phone**
   requests it. Use a second Zalo account or group sender for the live
   inbound-message test.
6. From the setup conversation, open the **Thread** tab to list recent mirrored
   external threads for the selected agent channel. Use **Sync external thread**
   from that list when a mirrored thread exists.
7. Select a mirrored `ai-agent-thread-<uuid>` conversation and use **Sync
   external thread**. A zero-message result means the adapter found no newer
   messages.
8. Draft and send a manual response from the thread panel, then confirm the
   mirrored conversation refreshes.

## Discord And Zalo Setup

For Discord, configure the app with the generated webhook URL, then store the
application ID, public key, bot token, guild ID, and optional mention role IDs
on the Discord channel.

Discord message events require Gateway delivery. For a self-hosted watcher,
run `apps/discord/ai_agent_gateway_watcher.py` with:

```txt theme={null}
DISCORD_AI_AGENT_GATEWAY_BOT_TOKEN=<the AI-agent Discord bot token>
DISCORD_AI_AGENT_GATEWAY_PLATFORM_URL=https://<platform>
DISCORD_AI_AGENT_GATEWAY_WATCHER_SECRET=<root watcher secret>
```

Store the same `AI_AGENT_DISCORD_GATEWAY_WATCHER_SECRET` value as a root
workspace secret in apps/web. The watcher calls the deployed apps/web watcher
config endpoint to discover enabled, deployed Discord channel webhooks, and
apps/web only returns channels mapped to `ROOT_WORKSPACE_ID`. Set
`DISCORD_AI_AGENT_GATEWAY_CHANNEL_ID` when one watcher should pin a single
root-internal Discord channel.

The watcher forwards raw Gateway packets using the Chat SDK Discord forwarding
contract (`GATEWAY_<event>` JSON plus `x-discord-gateway-token`) so apps/web
continues to own AI-agent runtime, identity mapping, mirroring, and responses.
Gateway-token forwarded webhook requests are rejected for non-root workspaces;
normal Discord HTTP interactions still use the configured channel webhook path.
Keep the bot token value in runtime secrets only.

For local smoke tests, `DISCORD_AI_AGENT_GATEWAY_WEBHOOK_URL` may be set to one
generated Discord channel webhook URL instead of using auto-discovery.

For Zalo, configure the bot webhook URL in the Zalo Bot dashboard, set the
secret token to the channel's `webhookSecret`, and store the bot token plus OA ID
on the Zalo channel.

For experimental personal Zalo account testing, set the Zalo account mode to
`Personal account`, then use **Pair QR** from the `apps/chat` setup
conversation or the shared AI-agent operations panel. The QR flow runs
`zca-js` `loginQR()` server-side, stores `personalCookieJson`, `personalImei`,
and `personalUserAgent` as channel secrets, and records `zaloPersonalOwnId`
after confirmation. The browser receives only QR/session status, never raw
cookies, IMEI, or user agent values.

Manual cookie JSON, IMEI, and user agent entry remains a fallback for local
debugging. After either setup path, use **Validate** to confirm login, then
use **Sync history** to import Zalo Web-visible personal user and group threads
into Tuturuuu Chat. When the mobile device owns additional history, use
**Sync phone** and approve the transfer-sync request in the Zalo mobile app.
The phone-transfer action is owned by `apps/web`; `apps/chat` reaches it only
through the internal API proxy, and the browser never receives cookies, IMEI,
user agent values, private transfer keys, or raw transfer payloads. Historical
sync walks the available Zalo user and group history and upserts it
idempotently, so operators can rerun it to resume older imports without
duplicating conversations or messages. It never triggers AI auto-responses for
old messages. Supported image, video, audio, and file attachments are copied to
the channel workspace's configured Drive provider under `AI Agent Imports`.
Chat exposes those files through its authenticated attachment route instead of
retaining expiring Zalo CDN links. Apply the corresponding private-schema media
migration before enabling attachment imports in production. Deploy the channel
and use **Start**/**Stop** for the live listener lifecycle.
Personal Zalo channels do not receive webhooks, and only one Zalo Web listener
can be active per personal account at a time. Use test accounts only; the
upstream `zca-js` package is an unofficial Zalo Web automation API and can
trigger account locks or bans.

For experimental root-internal external chatbots, choose the explicit
`Internal` workspace option in the AI-agent workspace picker. It stores
`workspaceId = ROOT_WORKSPACE_ID` on the channel and keeps the runtime, test,
deploy, and mirror paths scoped to the internal workspace.

## Mapped User Requirement

Agents never write as a global service user in v1. Each inbound external user
must map to a Tuturuuu workspace user before task or calendar tools can run.

Discord uses the existing `discord_guild_members` mapping for the configured
guild. Zalo uses root secret identity links:

```txt theme={null}
AI_AGENT_IDENTITY:<wsId>:zalo:<oaId>:<zaloUserId> = <platformUserId>
```

The mapped Tuturuuu user's permissions are enforced. Task writes require
`manage_projects`; calendar writes require `manage_calendar`. If permissions are
missing, the agent replies with a permission-aware message instead of writing.

## Tool Allowlist

V1 exposes only workspace context, members, task handoff, and calendar tools.
Finance, time tracking, memory, image generation, web search, delete tools, and
broad marketplace tool selection stay out of scope until there is a separate
approval and audit model.


# AI Studio
Source: https://docs.tuturuuu.com/platform/ai/ai-studio

Operate Tuturuuu AI Studio policies, credentials, traces, and workspace credit metering.

AI Studio is the workspace-scoped development surface at
`https://ai.tuturuuu.com`. It is a registered satellite app and uses the same
workspace session, permissions, settings, and billing context as other Tuturuuu
apps.

## Workspace sections

Each section is its own route under `/<wsId>`; there is no catch-all section
route.

| Group      | Section                   | Route                              | Requires                                                |
| ---------- | ------------------------- | ---------------------------------- | ------------------------------------------------------- |
| —          | Overview                  | `/`                                | `use_ai_studio`                                         |
| Build      | Playground                | `/playground`                      | `use_ai_studio`                                         |
| Build      | Prompts, Agents, Datasets | `/prompts`, `/agents`, `/datasets` | `use_ai_studio`                                         |
| Governance | API keys                  | `/api-keys`                        | `manage_ai_keys`                                        |
| Governance | Model policy              | `/model-policy`                    | read with `use_ai_studio`, edit with `manage_ai_policy` |
| Observe    | Runs                      | `/runs`                            | `use_ai_studio`                                         |
| Observe    | Usage                     | `/usage`                           | `use_ai_studio`                                         |
| Observe    | Credits                   | `/credits`                         | `use_ai_studio`                                         |
| —          | Developer docs            | `/developer-docs`                  | `use_ai_studio`                                         |

`/logs` used to render the same activity explorer as `/runs` and now
permanently redirects there. Every observability filter — range, custom
from/to, model, feature, status, and the expanded run — is stored in the URL,
so a filtered view can be shared or bookmarked.

Evaluations and experiments are not shipped. They are absent from navigation
and routing until they have a backing implementation, rather than rendering a
placeholder.

## Access and issuance controls

Workspace members with `use_ai_studio` can review settled credit deductions,
Studio-metered runs, provider cost, and the applicable personal or workspace
credit status. Observability and execution do not depend on a global or
workspace Studio enablement switch.

Model execution still requires the requested model to be enabled and granted by
the global catalog, workspace policy, plan, and credential scope. Ordinary
callers must also have enough workspace credits and remain within request,
budget, rate, payload, and abuse limits. Verified registered external apps keep
their temporary zero-credit integration policy while remaining fully audited.

Root administrators configure global defaults and workspace overrides in
Infrastructure → AI Studio. Workspace administrators manage existing keys,
retention, and model restrictions from AI Studio. Creating or rotating a
`ttr_ai_` key additionally requires a standing workspace grant from a platform
administrator. Removing that grant blocks new issuance and rotation but does
not revoke existing keys.

## Model policy

`/<wsId>/model-policy` is the self-serve editor for the workspace row in
`private.workspace_ai_studio_policies`. Members with `use_ai_studio` see the
current policy read-only; `manage_ai_policy` is required to save.

* **Allowed models** — empty means "no workspace allow list"; every model the
  platform catalog and the workspace plan permit stays callable. A non-empty
  list restricts execution to exactly those model ids.
* **Denied models** — evaluated before the allow list, so a denied model is
  blocked even when it is also allowed.
* **Requests per minute** and **monthly credit budget** — per-credential
  ceilings; leave empty for unlimited.
* **Capture**, **content retention**, and **metadata retention** — leave on
  *Inherit* to follow `private.ai_studio_global_settings`. The editor shows the
  current platform default beside each field.
* **No training** — keep enabled unless a signed agreement says otherwise.

The form enforces the same bounds as the `PATCH` schema (content retention
1–365 days, metadata retention 30–2555 days, rate 1–10000/min, budget above
zero), so an out-of-range value is rejected before the request is sent.

## AI-only keys

Studio keys use the `ttr_ai_` prefix. The plaintext key is revealed once; only
its SHA-256 digest is stored. A key is a workspace service credential, not a
human session, and it cannot authorize non-AI Tuturuuu APIs.

Keys can be limited by environment, model, expiry, request rate, and credit
budget. Rotate or revoke a key immediately when its value may have been
exposed. Never write plaintext keys to logs, database columns, issue trackers,
or committed configuration.

The key page remains available to workspace key managers when issuance is not
approved so they can inspect and revoke existing credentials. Rotation is
treated as new key issuance and is therefore approval-gated.

Approved key managers can quick-create a development key from either the key
page or Playground. The one-time secret can be handed to Playground through
browser session storage; it is removed when read and is never sent through a
dashboard URL or persisted by the Studio application.

## Production Playground

Playground calls `https://ai.tuturuuu.com/v1/models`, `/v1/responses`, and
`/v1/chat/completions` with the supplied AI-only key. It therefore exercises
the same authentication, model policy, credit reservation and settlement,
budgets, rate limits, abuse controls, and logging as an external production
client. It does not use a privileged dashboard proxy.

Text generation uses the AI SDK Google provider and the
`GOOGLE_GENERATIVE_AI_API_KEY` configured on the AI Studio deployment. Public
API, policy, and observability records keep the canonical `google/...` model
ID; only the provider adapter receives the bare Gemini model name. Vercel AI
Gateway credentials and routing are not used for this execution path.

The workbench supports bounded AI SDK tool loops with the safe calculator and
current-time demonstration tools. Tool loops are limited to eight model steps.
The response shows a sanitized execution trace; the observability run table can
expand that trace after settlement.

## Metering lifecycle

Ordinary Studio keys and non-external callers follow one transactionally
guarded lifecycle:

1. authenticate the session or AI-only key;
2. resolve the global, workspace, plan, and key policy intersection;
3. reserve the maximum permitted credits;
4. execute the provider call;
5. persist the run and trace metadata; and
6. settle exact provider usage and release unused credits.

Provider failures and aborted streams still settle billable usage. Runs record
model, key, prompt or agent version, latency, first-token latency, token or
media units, provider cost, billed credits, status, and a stable request ID.
The dashboards combine these Studio runs with unmatched deductions from the
shared AI credit ledger, so AI features outside Studio remain visible without
double-counting deductions already linked to a run. Logs expose only sanitized
metering fields, never raw prompts, outputs, tool payloads, or provider errors.
AI SDK model and tool lifecycle callbacks additionally write ordered run steps.
Each step stores its type, safe tool or model name, status, latency, token
counts, and settled cost. Inputs, tool arguments, tool results, generated text,
provider metadata, and unredacted errors are excluded from the step record.

Registered external apps are the only temporary billing exception. Their
short-lived token must include `workspace:session` plus `ai:use` or `tts:use`,
the app must remain enabled and linked to the requested workspace, and the user
must still be a current workspace member. These calls reserve no workspace
credits, but they still enforce model and workspace policy, workspace request
limits, abuse controls, payload limits, and full run/provider-cost auditing.

## Trace retention

Run metadata is retained for 365 days by default. Prompt content, model output,
tool arguments, and tool results are not captured unless the workspace
explicitly enables content capture. Captured content defaults to 30 days and
must be redacted before persistence.

Customer AI content is not used for general-purpose model training by default.
Provider-specific no-training and data-control options should be enabled when
the provider supports them.

## Curated tools

Agents can use only tools declared in the root tool catalog and explicitly
enabled for the workspace. Tools must enforce workspace scope and normal
Tuturuuu permissions. Arbitrary HTTP requests, undeclared data access, and code
execution are not supported.

## Local verification

Apply and test the private-schema migrations before running the app:

```bash theme={null}
bun sb:up
cd apps/database
node scripts/run-supabase.js test db supabase/tests/ai-studio-foundations.sql
```

Then run the focused checks:

```bash theme={null}
bun --filter @tuturuuu/ai-studio test
bun --filter @tuturuuu/ai-studio type-check
bun --filter @tuturuuu/ai-studio build
```

Keep model grants, budgets, rates, capture policy, and legal publication
controls conservative while expanding API-key issuance workspace by workspace.


# AI Memory Service
Source: https://docs.tuturuuu.com/platform/ai/memory-service

How Tuturuuu uses first-party pgvector memory for cross-product AI memory.

Tuturuuu AI memory is backed by an internal Postgres/pgvector sidecar through
the server-only `@tuturuuu/ai/memory` boundary. Product routes must not call the
sidecar from the browser and must not create product-specific memory stores.

## Scope

Memory scope is always `user + workspace`. The shared helper builds a stable
container tag from those two identifiers and stores product, surface, route,
locale, timezone, conversation, and workspace metadata on each write.

Default recall is cross-product within that `user + workspace` container. Use
metadata filters only when a route needs a narrower product or surface view.

## Runtime

Use `withAiMemory` for AI SDK calls when the route has a user and workspace.
Use `ingestAiMemoryEvent`, `buildAiMemoryContext`, and the Mira-compatible tool
executors for explicit memory reads and writes.

Reads fail open by default, and writes are best effort. Every embedding used for
memory add/search is generated through the metered `@tuturuuu/ai` embedding
helper before the sidecar is called. If credits, pricing, token counting, or
billable attribution cannot be verified, the memory operation skips before
calling Google. Structural metering failures disable memory for the user scope.

Keep `SUPERMEMORY_FAIL_OPEN=true` unless a product explicitly requires strict
persistence.

Required server-side env:

```txt theme={null}
SUPERMEMORY_ENABLED=true
SUPERMEMORY_BASE_URL=http://supermemory:8787
SUPERMEMORY_API_KEY=...
SUPERMEMORY_TIMEOUT_MS=1500
SUPERMEMORY_FAIL_OPEN=true
SUPERMEMORY_DATABASE_URL=postgres://...
```

For Docker blue/green and watcher deployments, the Docker helper auto-generates
and injects the internal API key, bundled Postgres password, database URL,
internal base URL, fail-open setting, and timeout. Use
`DOCKER_SUPERMEMORY_API_KEY`, `DOCKER_SUPERMEMORY_POSTGRES_PASSWORD`,
`DOCKER_SUPERMEMORY_DATABASE_URL`, or `DOCKER_SUPERMEMORY_ENABLED=false` only
when an operator needs to override that generated runtime. An explicit false
value also removes the sidecar from Docker blue/green support builds and health
gates.

`SUPERMEMORY_API_KEY` is internal infrastructure configuration. Never expose it
through browser-visible env vars or client responses.

## User Controls

Workspace settings live behind:

```txt theme={null}
GET/PATCH /api/v1/workspaces/:wsId/ai/memory/settings
GET /api/v1/workspaces/:wsId/ai/memory/items
DELETE /api/v1/workspaces/:wsId/ai/memory/items/:memoryId
POST /api/v1/workspaces/:wsId/ai/memory/export
```

The settings dialog exposes enable/disable, product toggles, search/list,
delete, and export controls. API routes call private schema RPCs through the
server-side Supabase admin client.

## Migration

Legacy `mira_memories` rows are imported with the admin-only backfill endpoint:

```txt theme={null}
POST /api/v1/admin/ai/memory/backfill-mira
```

Backfill is idempotent through stable `customId` values. Rows without a legacy
workspace are imported into the user's default or personal workspace and tagged
with `legacy_mira` metadata.

## Self-Hosting

The Docker fleet runs the first-party memory sidecar as an internal support
service named `supermemory` for compatibility with existing base URL, API key,
watcher, and Compose wiring. The sidecar stores 3072-dimensional
`gemini-embedding-2` vectors in `extensions.halfvec(3072)` with HNSW cosine
indexes, plus GIN indexes for metadata and full-text hybrid search. The
`supermemory-db-migrate` service applies `apps/supermemory/db` schema changes
before the runtime starts.

The watcher and cron recovery path use the same generated Docker env, so
recreating `web-blue-green-watcher` does not require manually exporting memory
service secrets. There is no `SUPERMEMORY_IMAGE` enterprise-image contract.

Connectors such as Google Drive, OneDrive, and Notion are disabled for the first
rollout. Product ingestion should persist concise summaries only; do not ingest
raw files or binaries unless the source is user-owned, enabled, and explicitly
appropriate for memory.


# Model Catalog
Source: https://docs.tuturuuu.com/platform/ai/model-catalog

How Tuturuuu publishes, browses, and syncs AI gateway model metadata.

The public model catalog is served from `apps/web` at:

```txt theme={null}
GET /api/v1/infrastructure/ai/models
```

Without pagination parameters, the route keeps the legacy response shape and returns an array of language models. For catalog pages and sync jobs, prefer the paginated contract:

```txt theme={null}
GET /api/v1/infrastructure/ai/models?format=paginated&type=all&page=1&limit=60
```

The paginated response is:

```ts theme={null}
{
  data: Model[];
  pagination: {
    page: number;
    limit: number;
    total: number;
  };
}
```

Supported filters include `type`, `provider`, `tag`, `enabled`, `ids`, `q`, and `search`. Use `type=all` when a caller needs language, image, embedding, and video models. Selection UIs must use server-side search plus paginated "load more" behavior instead of preloading a fixed first page and filtering locally.

The root-admin AI credits route has the same paginated model browsing contract:

```txt theme={null}
GET /api/v1/admin/ai-credits/models?page=1&limit=50&q=flash&type=language&enabled=true
```

Use `ids=provider/model-a,provider/model-b` to pin selected defaults or allowlist rows while the visible search page changes.

In development, the AI credits admin model sync defaults to the Tuturuuu production public catalog before falling back to the Vercel AI SDK model source. This keeps local catalogs close to production while preserving the explicit Vercel source for refreshing upstream gateway metadata.

Gemini 3.1 Flash Lite is stable under `gemini-3.1-flash-lite` and `google/gemini-3.1-flash-lite`. Runtime callers should normalize the retired `gemini-3.1-flash-lite-preview` aliases before model resolution so stored preferences and older clients keep working without sending the preview ID to providers.

`private.ai_gateway_models` stores provider-owned catalog metadata, so its text fields are exempt from the global strict text-field length trigger and generated text check constraints. JSON payload fields on the same table still keep the standard payload-size checks.


# Omni-Channel Chat SDK
Source: https://docs.tuturuuu.com/platform/ai/omni-channel-chat-sdk

How packages/ai wires Chat SDK adapters for agentic presence workflows.

`packages/ai` exposes the Vercel Chat SDK through
`@tuturuuu/ai/chat-sdk`. Use it when a Tuturuuu agent needs to operate across
external channels and internal product surfaces with one normalized thread and
message contract.

The target workflow is:

```txt theme={null}
Input <-> Omni-channel <-> Tuturuuu Digest <-> Coordinator <-> Internal Apps <-> End users
```

## Package Boundary

Import the Chat SDK boundary from:

```ts theme={null}
import { createChatSdkRuntime, createChatTools } from "@tuturuuu/ai/chat-sdk";
```

The boundary re-exports Chat SDK core types and the `chat/ai` tool helpers, then
adds Tuturuuu registry helpers for platform and state adapters.

## Adapter Coverage

The adapter registry mirrors the Chat SDK adapter directory.

Official platform adapters:

* Slack: `@chat-adapter/slack`
* Microsoft Teams: `@chat-adapter/teams`
* Google Chat: `@chat-adapter/gchat`
* Discord: `@chat-adapter/discord`
* GitHub: `@chat-adapter/github`
* Linear: `@chat-adapter/linear`
* Telegram: `@chat-adapter/telegram`
* WhatsApp Business Cloud: `@chat-adapter/whatsapp`
* Messenger: `@chat-adapter/messenger`
* Web: `@chat-adapter/web`

Vendor-official platform adapters:

* Beeper Matrix: `@beeper/chat-adapter-matrix`
* Photon iMessage: `chat-adapter-imessage`
* Resend: `@resend/chat-sdk-adapter`
* Zernio: `@zernio/chat-sdk-adapter`
* Liveblocks: `@liveblocks/chat-sdk-adapter`

Community platform adapters:

* Webex: `@bitbasti/chat-adapter-webex`
* Baileys WhatsApp: `chat-adapter-baileys`
* Sendblue iMessage: `chat-adapter-sendblue`
* Blooio iMessage/RCS/SMS: `chat-adapter-blooio`
* Zalo: `chat-adapter-zalo`
* Mattermost: `chat-adapter-mattermost`

State adapters:

* Memory: `@chat-adapter/state-memory`
* Redis: `@chat-adapter/state-redis`
* ioredis: `@chat-adapter/state-ioredis`
* PostgreSQL: `@chat-adapter/state-pg`
* Cloudflare Durable Objects: `chat-state-cloudflare-do`
* MySQL: `chat-state-mysql`

## Runtime Construction

Create a runtime by selecting only the adapters a route or worker owns. Passing
`true` means the adapter should read credentials from its documented
environment variables. Passing an object forwards that object to the adapter
factory.

```ts theme={null}
const chat = await createChatSdkRuntime({
  userName: "mira",
  adapters: {
    slack: true,
    zalo: {
      botToken: process.env.ZALO_BOT_TOKEN,
      webhookSecret: process.env.ZALO_WEBHOOK_SECRET,
    },
  },
  state: {
    id: "redis",
    config: { url: process.env.REDIS_URL },
  },
});
```

Always choose a production state adapter for deployed bots. Chat SDK state
persists thread subscriptions, webhook dedupe, cache entries, and distributed
locks. The memory adapter is only appropriate for local development and tests.

Cloudflare Durable Objects state is declared in the registry, but its package
imports `cloudflare:workers`; load it only in a Cloudflare Workers runtime.

## Agent Tools

Expose the selected chat runtime to AI SDK calls with Chat SDK tools:

```ts theme={null}
const tools = createChatTools({
  chat,
  preset: "messenger",
});
```

Use the `reader` preset for analysis-only agents, `messenger` for normal
posting and DM workflows, and `moderator` for destructive operations such as
editing and deleting messages. Keep approval gates enabled by default for
visible writes unless the workflow has an explicit unattended execution policy.

## External Chat Mirror

Apps/web AI agents mirror inbound and outbound Discord/Zalo messages through
server-owned private RPCs. Runtime handlers persist webhook events as soon as
they arrive, then persist any automatic or manual outbound response after the
Chat SDK adapter accepts the post.

When an operator clicks sync in Infrastructure > AI Agents, apps/web creates
the configured Chat SDK runtime, opens the external thread handle, and consumes
recent `thread.messages` when the adapter supports history fetch. Discord can
return recent messages with the right bot scopes. Official Zalo behaves as a
webhook-first adapter, so the mirror is populated by received events. Personal
Zalo channels use the experimental `zca-js` listener and can fetch group chat
history when the personal account session supports it. The personal adapter
also normalizes supported media messages into Chat SDK attachments. The mirror
stores those binaries in the workspace Drive provider, records only private
attachment metadata, and serves authenticated links from the same conversation
API used by native Chat attachments.


# AI Structured Data
Source: https://docs.tuturuuu.com/platform/ai/structured-data

Learn how to use Vercel AI SDK for structured data generation in Tuturuuu.

<Info>
  **Prerequisite**: You should have followed the [Development](/build/development-tools/development) and
  [Local Supabase Development](/build/development-tools/local-supabase-development) setup guides.
</Info>

## Overview

Tuturuuu leverages the [Vercel AI SDK](https://sdk.vercel.ai/docs/foundations/overview) to generate structured data from large language models (LLMs). This approach enables type-safe AI responses, improved reliability, and consistent data structures for features like flashcards, quizzes, and learning plans.

This guide covers how to use AI structured data generation in the Tuturuuu development workflow.

## Key Concepts

### What is Structured Data Generation?

While text generation can be useful, many applications require generating structured data. For example, you might want to:

* Extract specific information from text
* Generate quizzes or flashcards from learning material
* Create complex objects like learning plans or task lists
* Ensure AI responses follow a consistent format

The AI SDK standardizes structured object generation across model providers with the `generateObject` and `streamObject` functions. You can use Zod schemas to specify the shape of the data that you want, and the AI model will generate data that conforms to that structure.

## Architecture in Tuturuuu

Tuturuuu's AI features follow this high-level architecture:

1. **Frontend UI** - React components that display and interact with AI-generated content
2. **API Routes** - Next.js routes that handle AI requests and responses
3. **AI SDK** - Vercel AI SDK that manages model providers and generates structured data
4. **Supabase** - Backend database for authentication, authorization, and storing AI-generated content

### Mira Chat Attachments

Dashboard chat attachments are uploaded to Supabase Storage before the user
message is sent. New chats may first place files under
`{wsId}/chats/ai/resources/temp/{userId}` and then move them into
`{wsId}/chats/ai/resources/{chatId}` once the chat exists.

Tools that read those attachments, such as `convert_file_to_markdown`, should
resolve bare filenames and stale same-workspace attachment paths against the
current chat folder. They must still reject full paths from another workspace.

### Mira Dashboard Chat Agent Loop

The dashboard Mira chat keeps the main assistant in fast mode by default. New
sessions should ignore stale stored `thinking` preferences unless the user
manually opts into the toolbar's deep-check mode for that active session.

Assistant text should stream as soon as it is useful, then tool calls may run
inline, followed by more assistant text in the same response. Keep every
assistant text surface on the shared Streamdown wrapper, including text rendered
inside compact tool UIs, so code blocks, tables, Mermaid, math, and CJK spacing
stay consistent.

Mira enables Streamdown math with `singleDollarTextMath` because model output
commonly uses `$...$` inline LaTeX. Keep `@streamdown/math` in the Tailwind
source scan alongside the base Streamdown dist files, and keep
`katex/dist/katex.min.css` imported from the chat renderer path.

While the request is submitted but no assistant text has arrived yet, the chat
should render a lightweight assistant activity bubble with rotating status copy.
Hide that placeholder as soon as real assistant text streams, and keep it
separate from markdown/tool rendering so status cycling does not re-render heavy
message content.

Keep the first optional-tool model step lean. Unless a workflow must force a
specific tool before answering, expose only `select_tools` and
`no_action_needed` on the first step so the model can stream direct answers
without carrying every tool schema. Stream smoothing should not add artificial
per-chunk delay on the dashboard chat path; perceived smoothness belongs in the
client activity state, not in delayed server chunks.

Do not force `select_tools` as the universal first step. Force tool selection
only when the workflow cannot answer safely before a tool runs, such as current
web lookups, workspace context switching, workspace member lookups, file
conversion, or writes. Complex verification, risk review, planning checks, or
conflicting evidence should use `run_parallel_checks`, which delegates to
bounded `ToolLoopAgent` subagents in parallel and returns a compact summary to
the main assistant. Any Mira tool that spawns additional model calls must use
`MiraToolContext.creditWsId ?? wsId`, resolve the plan model for that billed
workspace, preflight AI credits, apply the workspace output-token cap, and
deduct the subcall usage before exposing the generated result.

## Schema Definitions

Schemas define the structure of the data that will be generated by the AI models. In Tuturuuu, these are defined in `packages/ai/src/object/types.ts` using [Zod](https://github.com/colinhacks/zod).

Here are some examples of schemas used in Tuturuuu:

### Flashcard Schema

```typescript theme={null}
export const flashcardSchema = z.object({
  flashcards: z.array(
    z.object({
      front: z.string().describe('Question. Do not use emojis or links.'),
      back: z.string().describe('Answer. Do not use emojis or links.'),
    })
  ),
});
```

### Quiz Schema

```typescript theme={null}
export const quizSchema = z.object({
  quizzes: z.array(
    z.object({
      question: z.string().describe('Question. Do not use emojis or links.'),
      quiz_options: z.array(
        z.object({
          value: z.string().describe('Option. Do not use emojis or links.'),
          explanation: z
            .string()
            .describe(
              'Explain why this option is correct or incorrect, if it is incorrect, explain possible misconceptions and what made the option wrong with respect to the question, if it is correct, explain why it is correct. Be as detailed as possible.'
            ),
          is_correct: z.boolean().describe('This option is a correct answer.'),
        })
      ),
    })
  ),
});
```

### Year Plan Schema

```typescript theme={null}
export const yearPlanSchema = z.object({
  yearPlan: z.object({
    overview: z
      .string()
      .describe(
        'A high-level overview of the year plan and how the goals will be achieved'
      ),
    quarters: z
      .array(quarterSchema)
      .describe('List of quarters in the year plan'),
    recommendations: z
      .array(z.string())
      .describe('Additional recommendations, tips, or considerations'),
    start_date: z
      .string()
      .describe('Start date of the year plan (ISO date string)'),
    end_date: z
      .string()
      .describe('End date of the year plan (ISO date string)'),
  }),
});
```

## Creating an API Endpoint

To create an API endpoint that generates structured data, follow these steps:

### 1. Create a new route file

Create a new route file in the appropriate Next.js app, for example:

```typescript theme={null}
// app/api/ai/flashcards/route.ts
import { google } from '@ai-sdk/google';
import { flashcardSchema } from '@tuturuuu/ai/object/types';
import {
  createAdminClient,
  createClient,
} from '@tuturuuu/supabase/next/server';
import { streamObject } from 'ai';

export async function POST(req: Request) {
  // Implementation...
}
```

### 2. Implement authentication and validation

Use Supabase to authenticate the user and validate their permissions:

```typescript theme={null}
// createAdminClient() is synchronous; do not await it.
const sbAdmin = createAdminClient();
const { wsId, context } = await req.json();

// Validate input
if (!wsId) return new Response('Missing workspace ID', { status: 400 });
if (!context) return new Response('Missing context', { status: 400 });

// Authenticate user
const supabase = await createClient();
const { data: { user } } = await supabase.auth.getUser();
if (!user) return new Response('Unauthorized', { status: 401 });

// Check feature flag
const { count, error } = await sbAdmin
  .from('workspace_secrets')
  .select('*', { count: 'exact', head: true })
  .eq('ws_id', wsId)
  .eq('name', 'ENABLE_CHAT')
  .eq('value', 'true');

if (error) return new Response(error.message, { status: 500 });
if (count === 0)
  return new Response('You are not allowed to use this feature.', { status: 401 });
```

#### Fast session auth for Mira and assistant routes

Session-authenticated AI routes may accept the `x-tuturuuu-ai-temp-auth` header as an optimization before falling back to Supabase `getUser()`. The browser mints this token through `POST /api/ai/temp-auth/token` after the normal session, workspace normalization, membership, and selected billing workspace checks succeed. Tokens live only in memory on the client, expire after 60 seconds, and are stored in Redis only as SHA-256 digests.

Revocation is version-based: `ai:temp-auth:user-version:{userId}` is bumped before logout or account removal, so any token minted under the old version is rejected. Redis is not authoritative for security; when Redis is unavailable or a token is missing/invalid, routes fall back to the existing Supabase session path. A revoked token returns `401` and does not fall back.

Credit availability snapshots are also Redis-backed under `ai:credits:snapshot:{billingWsId}:{userId}`. They are UI/status hints only and must not authorize model execution. AI preflight must call the authoritative Postgres allowance RPC so daily credit limits, daily request limits, and feature-specific request limits are enforced before every model run. Actual reservations, deductions, and ledger writes remain in Postgres, and successful commits invalidate the snapshot.

### 3. Generate structured data

Use the AI SDK to generate structured data based on the schema:

```typescript theme={null}
const result = streamObject({
  // Use a current default model ID. Active callers in `packages/ai/src`
  // (calendar, chat title generation, search wrapper) use
  // `gemini-3.1-flash-lite`. See "Supported Models" below for how the
  // catalog is resolved dynamically at runtime.
  model: google('gemini-3.1-flash-lite', {
    safetySettings: [
      {
        category: 'HARM_CATEGORY_DANGEROUS_CONTENT',
        threshold: 'BLOCK_NONE',
      },
      // Other safety settings...
    ],
  }),
  prompt: `Generate 10 flashcards with the following context: ${context}`,
  schema: flashcardSchema,
});

// Stream the response to the client
return result.toTextStreamResponse();
```

## Supported Models

Tuturuuu supports multiple AI models through the Vercel AI SDK. There is **no
static model array** anymore — the catalog is sourced dynamically from the AI
gateway and stored in the `ai_gateway_models` table (synced by
`packages/ai/src/credits/sync-gateway-models.ts`). The browsable catalog is
served from `apps/infrastructure`:

* **API**: `GET /api/v1/infrastructure/ai/models`
  (`apps/infrastructure/src/app/api/v1/infrastructure/ai/models/route.ts`)
* **Docs**: see [Model Catalog](/platform/ai/model-catalog) for how metadata is
  published, browsed, and synced.

The set of provider integrations the SDK can wire up lives in
`packages/ai/src/supported-providers.ts`:

```typescript theme={null}
export const supportedProviders = [
  'google',
  'google-vertex',
  'openai',
  'anthropic',
] as const;
```

For per-workspace plan resolution (which model a billed workspace is allowed to
run), use the helpers under `packages/ai/src/credits/` such as
`resolve-plan-model.ts` and `cap-output-tokens.ts`, rather than hard-coding a
model ID.

To use a different model in your endpoint, change the model reference. Active
callers default to `gemini-3.1-flash-lite`:

```typescript theme={null}
const result = streamObject({
  model: google('gemini-3.1-flash-lite', {
    // Configuration...
  }),
  // Other parameters...
});
```

## Calling from the Frontend

To call your AI endpoint from the frontend, you can use the appropriate hooks or fetch API:

```typescript theme={null}
// Example using fetch
async function generateFlashcards(workspaceId: string, context: string) {
  const response = await fetch('/api/ai/flashcards', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      wsId: workspaceId,
      context,
    }),
  });

  if (!response.ok) {
    const error = await response.text();
    throw new Error(error);
  }

  // For streaming responses
  const reader = response.body?.getReader();
  const decoder = new TextDecoder();

  while (reader) {
    const { done, value } = await reader.read();
    if (done) break;

    const chunk = decoder.decode(value);
    // Process the chunk (partial object)
    console.log(JSON.parse(chunk));
  }
}
```

## Integration with Supabase

Tuturuuu's AI features are tightly integrated with Supabase for several purposes:

### TypeScript Types

Supabase-generated TypeScript types are available at `packages/types/src/supabase.ts`. These types are automatically generated when you run `bun sb:typegen` or `bun sb:reset` and are accessible to all apps that have the `@tuturuuu/types` package installed.

You can use these types to ensure type safety when working with Supabase data in your AI features:

```typescript theme={null}
import type { Database } from '@tuturuuu/types';

// Type-safe access to workspace_secrets table
const { data, error } = await supabase
  .from<
    Database['public']['Tables']['workspace_secrets']['Row']
  >('workspace_secrets')
  .select('*')
  .eq('ws_id', wsId)
  .eq('name', 'ENABLE_AI');

// Type-safe access to specific columns
const { data: workspace } = await supabase
  .from('workspaces')
  .select('id, name, handle')
  .eq('id', wsId)
  .single();

// TypeScript knows the structure of 'workspace' with proper types
const workspaceName: string = workspace?.name;
```

### Short-hand Type Access

For more convenient access to common table types in your AI features, Tuturuuu also provides short-hand type definitions in `packages/types/src/db.ts`. These are easier to use and remember than the full database type paths:

```typescript theme={null}
import type { AIChat, AIPrompt, WorkspaceDocument } from '@tuturuuu/types';

// Use short-hand types directly for AI-related tables
const { data: chats } = await supabase
  .from('ai_chats')
  .select('*')
  .eq('creator_id', user.id);

// Types are properly inferred
chats?.forEach((chat: AIChat) => {
  console.log(chat.id, chat.title);
});

// Store AI-generated content with proper types
const document: WorkspaceDocument = {
  id: uuidv4(),
  ws_id: wsId,
  name: 'AI Generated Document',
  content: generatedContent,
  created_at: new Date().toISOString(),
  creator_id: user.id,
};

await supabase.from('workspace_documents').insert(document);
```

The short-hand types can also include extended client-side properties that aren't in the database schema, making them perfect for your AI feature implementations.

This ensures that your AI features correctly interact with the database schema, reducing runtime errors and improving development experience.

### Authentication and Authorization

Before making AI requests, ensure the user is authenticated and authorized to use the feature:

```typescript theme={null}
// Get the current user
const { data: { user } } = await supabase.auth.getUser();
if (!user) return new Response('Unauthorized', { status: 401 });

// Check workspace membership
const { data: member, error: memberError } = await sbAdmin
  .from('workspace_members')
  .select('*')
  .eq('ws_id', wsId)
  .eq('user_id', user.id)
  .single();

if (memberError || !member)
  return new Response('You are not a member of this workspace', { status: 403 });
```

### Feature Flags

Use the `workspace_secrets` table to enable or disable AI features for specific workspaces:

```typescript theme={null}
// Check if the AI feature is enabled for this workspace
const { count, error } = await sbAdmin
  .from('workspace_secrets')
  .select('*', { count: 'exact', head: true })
  .eq('ws_id', wsId)
  .eq('name', 'ENABLE_AI')
  .eq('value', 'true');

if (error) return new Response(error.message, { status: 500 });
if (count === 0)
  return new Response('AI features are not enabled for this workspace', { status: 403 });
```

### Storing Results

You can store AI-generated content in Supabase for future use:

```typescript theme={null}
// Store the generated flashcards
const { error } = await sbAdmin
  .from('flashcard_sets')
  .insert({
    ws_id: wsId,
    creator_id: user.id,
    name: 'Generated Flashcards',
    description: context.substring(0, 100) + '...',
    cards: result.object.flashcards,
  });

if (error) return new Response(error.message, { status: 500 });
```

## Best Practices

### Schema Design

When designing schemas for AI-generated content:

1. **Be specific** - Use the `.describe()` method to provide clear instructions to the AI model
2. **Keep it simple** - Break complex schemas into smaller, nested objects
3. **Add validations** - Use Zod's validation methods (`.min()`, `.max()`, `.regex()`, etc.)
4. **Use enums** - For fields with a fixed set of values, use `.enum()`

Example of a well-designed schema:

```typescript theme={null}
const taskSchema = z.object({
  title: z.string().min(3).max(100).describe('A concise title for the task'),
  description: z
    .string()
    .min(10)
    .describe('Detailed description of what needs to be done'),
  priority: z
    .enum(['high', 'medium', 'low'])
    .describe('Priority level of the task'),
  due_date: z.string().describe('Due date in ISO format (YYYY-MM-DD)'),
  estimated_hours: z
    .number()
    .min(0)
    .max(100)
    .describe('Estimated hours to complete'),
});
```

### Error Handling

Implement robust error handling for AI-generated content:

```typescript theme={null}
try {
  const result = streamObject({
    // Configuration...
  });

  return result.toTextStreamResponse();
} catch (error) {
  console.error('AI generation error:', error);

  // Return a friendly error message
  return NextResponse.json(
    {
      message: 'Failed to generate content. Please try again later.',
      error: error.message,
    },
    { status: 500 }
  );
}
```

### Response Processing

For complex AI-generated content, you may need to post-process the response:

```typescript theme={null}
// Example: Filtering out inappropriate content
const filteredFlashcards = result.object.flashcards.filter((card) => {
  // Remove cards containing inappropriate words
  const inappropriateWords = ['inappropriate1', 'inappropriate2'];
  return !inappropriateWords.some(
    (word) => card.front.includes(word) || card.back.includes(word)
  );
});
```

## Local Development and Testing

### Setting Up API Keys

To test AI features locally, you need to set up the appropriate API keys in your environment:

1. Create a `.env.local` file in the root of your Next.js app
2. Add the necessary API keys:

```
GOOGLE_GENERATIVE_AI_API_KEY=your-google-ai-key
OPENAI_API_KEY=your-openai-key
```

3. Restart your development server

### Testing AI Endpoints

You can test your AI endpoints using tools like Postman or simple cURL commands:

```bash theme={null}
curl -X POST http://localhost:3000/api/ai/flashcards \
  -H "Content-Type: application/json" \
  -d '{"wsId":"00000000-0000-0000-0000-000000000000","context":"The process of photosynthesis converts light energy into chemical energy that can be used by plants and other organisms."}'
```

## Troubleshooting

### Common Issues

1. **API Key Issues**: Ensure your API keys are correctly set in your environment
2. **Model Unavailability**: Some models may be unavailable in certain regions
3. **Token Limits**: Large prompts may exceed token limits
4. **Schema Validation Errors**: The AI might generate content that doesn't match your schema

### Debugging Tips

1. **Log the prompt**: Print the full prompt being sent to the AI model
2. **Start with simple schemas**: Begin with simple schemas and gradually increase complexity
3. **Check response format**: Verify the raw response from the AI model before schema validation

## Further Resources

* [Vercel AI SDK Documentation](https://sdk.vercel.ai/docs/foundations/overview)
* [Zod Documentation](https://zod.dev/)
* [Supabase Documentation](https://supabase.com/docs)
* [Google Generative AI Documentation](https://ai.google.dev/docs)


# Apps Gateway
Source: https://docs.tuturuuu.com/platform/applications/apps

Central launcher and redirect gateway for routable Tuturuuu web apps.

## Overview

`apps/apps` serves `apps.tuturuuu.com`, the central public gateway for routable
Tuturuuu web apps. It is a launcher and redirect layer, not a reverse proxy.

The gateway exposes app cards for the routable web apps in `apps/` and redirects
users to each app's canonical domain:

* `/calendar` redirects to `calendar.tuturuuu.com`
* `/qr` redirects to `qr.tuturuuu.com`
* `/tasks/personal/tasks` redirects to `tasks.tuturuuu.com/personal/tasks`
* query strings are preserved during redirects

It intentionally excludes infrastructure-only or non-web app directories such as
`apps/database`, `apps/mobile`, `apps/redis`, `apps/discord`,
`apps/storage-unzip-proxy`, and `apps/hive-realtime`.

## Routing Contract

* `/`: public app directory.
* `/{appSlug}`: redirect to the target app root.
* `/{appSlug}/{path...}`: redirect to the same path on the target app.

`apps.tuturuuu.com` must not own auth callbacks, protected APIs, cross-app token
exchange, or app-session cookies. Those flows remain owned by the canonical app
or by `apps/web` for central login.

The gateway layout uses `@tuturuuu/satellite/providers` so the public launcher
supports `system`, `light`, and `dark` theme switching through the shared
`next-themes` shell.

## Local Development

* `bun dev:apps` starts the gateway through Portless.
* Local app origin: `https://apps.tuturuuu.localhost`.
* Direct fallback port: `7818`.

The gateway uses hidden locale routing, so old locale-prefixed paths such as
`/vi/calendar` should canonicalize to `/calendar` while storing `NEXT_LOCALE`.

## CI/CD

Preview and production deployments use dedicated Vercel workflows:

* `.github/workflows/vercel-preview-apps.yaml`
* `.github/workflows/vercel-production-apps.yaml`

Both workflows are registered in `tuturuuu.ts` and use the shared
`ci-check.yml` switchboard with affected-path gating. They require
environment-scoped Vercel credentials:

* preview environment: `vercel-preview-apps`
* production environment: `vercel-production-apps`
* project secret: `VERCEL_APPS_PROJECT_ID`
* shared secrets: `VERCEL_TOKEN` and `VERCEL_ORG_ID`

The app-specific project secret should live in those GitHub Environments, not in
workflow-level `env`.

## Validation

Use these focused checks when changing the gateway:

```bash theme={null}
bun type-check:apps
bun --cwd packages/utils test src/__tests__/app-url.test.ts
node --test scripts/portless-config.test.js
node --test scripts/ci/check-workflow-config.test.js scripts/ci/release-workflows.test.js
```

Because the gateway touches TypeScript, workflow config, docs navigation, and
translations, finish gateway changes with `bun check` when the shared worktree
state allows it.


# Calendar
Source: https://docs.tuturuuu.com/platform/applications/calendar

Shared Calendar product surface across apps/web and apps/calendar.

## Overview

`apps/calendar` and the Calendar experience inside `apps/web` are paired
Calendar hosts. They must stay 1:1 for product features, data behavior,
mutations, permissions, and user-facing workflow updates.

* Calendar UI and logic should live in shared packages, primarily
  `@tuturuuu/ui/calendar-app/*`, with app route files acting as thin auth and
  workspace-context wrappers.
* Task-aware Calendar controls (task creation, task scheduling, habits, and
  task time tracking) live in `@tuturuuu/tasks-ui/calendar/*`. The generic
  Calendar shell accepts those controls through typed component seams, keeping
  `@tuturuuu/ui` independent from task-only code and preserving narrow Turbo
  rebuilds.
* `apps/calendar` owns its standalone workspace shell, local `/login`, and
  local `/verify-token` completion route.
* `apps/web /{wsId}/calendar` renders the same shared Calendar product surface
  inside the normal platform dashboard shell.
* Dashboard navigation in `apps/web` should link to the local
  `/{wsId}/calendar` route, not to the standalone Calendar origin.

## Auth Model

Calendar does not create local Supabase Auth sessions. It uses central
`apps/web` login plus a Calendar app-session cookie:

1. `/login` in `apps/calendar` normalizes a safe `next` path.
2. If both the Calendar app-session cookie and Web-issued app-session cookie are
   already present, `/login` redirects to that local `next` path immediately.
3. Otherwise `/login` redirects to `apps/web /login` with a return URL pointing
   back to Calendar `/verify-token?nextUrl=...`.
4. `/verify-token` posts the handoff token to the Calendar-local verifier, which
   validates through central Web and sets host-local app-session cookies.

Calendar proxy responses should clear stale `sb-*-auth-token` cookies. A valid
Calendar session is represented by Tuturuuu app-session cookies, not by a local
Supabase browser session.

## API Ownership

`apps/calendar` owns the Calendar product APIs. Its local handlers cover events
and calendars, categories and preferences, hours and default sources,
scheduling and sync, Calendar connections, Google and Microsoft provider OAuth,
Calendar media/generation helpers, and Calendar-owned cron work. Host-local
auth/session and build-info routes are local as well.

* Exact local handlers win before the fallback `/api/:path*` rewrite. The
  fallback remains for cross-product routes that Calendar uses but does not
  own, including workspace encryption and task, board, habit, and time-tracking
  families; typed task helpers may target the Tasks app directly.
* Central platform login, social-provider callbacks, and cross-app token
  issuance remain Web-owned. Calendar-provider OAuth initiation and callbacks
  are Calendar-local, even though their configured redirect origins retain Web
  compatibility for existing provider registrations.
* Calendar-only routes use `targetApp: 'calendar'`. Shared cross-product routes
  must name the exact accepted app audiences, such as
  `targetApp: ['calendar', 'tasks']`, rather than accepting generic satellite
  sessions.
* Keep workspace membership checks and Calendar/task permissions on the owning
  route before admin-backed reads or writes. The Calendar proxy guard and
  app-session refresh do not replace route-level authorization.
* Prefer typed `packages/internal-api` helpers. Browser calls remain
  same-origin so Calendar-local handlers are selected first; server calls to a
  different owning app must use its configured API base URL with forwarded
  authentication.

## OAuth Token Safety

Calendar OAuth credentials live in `calendar_auth_tokens`. RLS restricts
selects to `user_id = auth.uid()`, but admin/service-role reads bypass RLS.

Calendar server pages must therefore:

* Check `manage_calendar` before loading calendar integration state.
* Scope token reads to both `ws_id` and the authenticated `user_id`.
* Never pass `access_token` or `refresh_token` into client components. SSR
  props should use the shared
  `fetchUserWorkspaceCalendarGoogleTokenForClient()` helper from
  `@tuturuuu/utils/calendar-auth-token`, which projects only connection
  metadata (`id`, account email/name, provider, active state, expiry).
* Keep token refresh and provider API calls on Calendar-local server routes;
  never expose provider credentials to client components.

When adding a new Calendar host route, reuse the helper instead of
`select('*')` on `calendar_auth_tokens`.

When adding new Calendar UI that needs protected data, update the shared
Calendar component or helper first, then wire both host wrappers in the same
change. Extend the route family in its owning app and expose a typed
`packages/internal-api` seam instead of creating a host-local product API fork
or adding direct client Supabase reads.

## Calendar OAuth And Connections

Google Calendar OAuth initiation and callback handlers are owned by
`apps/calendar`. The local `/api/v1/calendar/auth` route builds its callback URL
from a browser-safe configured origin and ignores wildcard listener addresses
such as `0.0.0.0` or `::`. Existing provider registrations may still configure
the central Web origin; if no safe configured origin is available, the fallback
origin is `https://tuturuuu.com`.

After Google returns to the callback, the flow always sends the user to the
central Web Calendar page at
`https://tuturuuu.com/{wsId}/calendar?provider=google&connected=true`. Valid
local development callback URLs such as
`http://localhost:7803/api/v1/calendar/auth/callback` may still be configured
through `GOOGLE_REDIRECT_URI`, but wildcard listener URLs must never be emitted
as Google `redirect_uri` values or browser redirects.

Normal Google Calendar connect and reconnect URLs request
`access_type=offline` and `include_granted_scopes=true`, but they must not force
`prompt=consent` by default. Google may return a refresh token only during the
first authorization, so the callback must preserve an existing stored
`refresh_token` when a reconnect returns only a new access token. If neither the
callback nor the existing token row has a refresh token, the flow must fail
before saving an active Google connection because provider sync cannot refresh
offline.

Standalone `apps/calendar` also exposes the shared Calendar connections manager
inside its settings dialog under Calendar -> Integrations. It should fetch the
initial connection state through `@tuturuuu/internal-api/calendar` and render the
shared Calendar connections UI inside `CalendarSyncProvider` rather than
forking host-local connection controls.

## CI And Deployment

Calendar deploys through dedicated GitHub Actions workflows, not Vercel-owned
GitHub auto-builds:

* Preview deployments use `.github/workflows/vercel-preview-calendar.yaml`.
* Production deployments use `.github/workflows/vercel-production-calendar.yaml`.
* The Vercel project id is provided through the environment-scoped
  `VERCEL_CALENDAR_PROJECT_ID` secret.
* `apps/calendar/vercel.json` must keep `git.deploymentEnabled` and
  `github.enabled` set to `false` so GitHub Actions builds with `vercel build`
  and deploys prebuilt artifacts with `vercel deploy --prebuilt`.

Keep Calendar cron definitions in `apps/calendar/vercel.json`; disabling Vercel
GitHub builds must not remove the app-owned cron schedules.

## Provider Sync

Calendar provider sync is scheduled by `apps/web` cron, not Trigger.dev. The
shared source of truth is `apps/web/cron.config.json`; `calendar-provider-sync`
must stay at `*/15 * * * *` and `apps/web/vercel.json` must be regenerated from
that file with `node scripts/sync-web-crons.js`.

The cron wrapper at `/api/cron/calendar/provider-sync` must keep calling
`/api/v1/workspaces/:wsId/calendar/sync` through `INTERNAL_WEB_API_ORIGIN` when
available. The workspace sync route owns Google and Microsoft fan-out, running
locks, cron cooldown behavior, and `calendar_sync_dashboard` audit rows. Do not
add provider-specific fetch logic or Trigger.dev scheduled calendar jobs outside
that route family.

## Two-Way Sync Controls

Calendar sync has two layers of user control:

* Workspace-user preferences in
  `private.calendar_user_workspace_preferences` enable or disable inbound
  imports, outbound Tuturuuu-to-provider mirroring, the default outbound
  provider calendar, and the conflict policy.
* `calendar_connections` controls each external calendar's import, outbound
  write, and provider-delete behavior.

Outbound mirroring is opt-in. When enabled, native Tuturuuu event creates and
edits mirror to the selected writable Google or Microsoft connection, and the
local event stores provider identity so future updates and deletes propagate
externally. Manual or cron sync with `direction: "outbound"` or `"both"` may
also catch up local-only or previously failed Tuturuuu events in the active sync
window.

Inbound provider deletes are controlled per connection through
`sync_delete_enabled`. User-initiated deletion of a synced external event still
deletes the provider event directly because it is explicit CRUD, not passive
provider import cleanup.

After adding or changing two-way sync columns, prepare migrations in
`apps/database`; do not run production Supabase push commands from agent
sessions. Apply locally with `bun sb:up` when feasible, then regenerate database
types only after the local schema reflects the migration.


# Chat
Source: https://docs.tuturuuu.com/platform/applications/chat

Private-schema workspace messaging for direct messages, groups, channels, AI conversations, and Drive-backed attachments.

Chat is implemented in two hosts:

* `apps/web` owns protected APIs, workspace authorization, storage signing, and
  private Supabase RPC execution.
* `apps/chat` is the standalone satellite UI at
  `https://chat.tuturuuu.com`, with local Portless origin
  `https://chat.tuturuuu.localhost` and direct fallback
  `http://localhost:7821`.

Both hosts render the same shared UI from `@tuturuuu/ui/chat/chat-workspace`
and call the same `@tuturuuu/internal-api` chat client. Do not add direct
browser Supabase reads, client-local raw `fetch('/api/...')`, or host-specific
chat business logic.

## API Ownership

`apps/chat` forwards `/api/v1/*` and `/api/ai/*` to `apps/web`. The standalone
app authenticates through the cross-app session target `chat`; `apps/web`
accepts that target only on the chat API surface and still performs normal
request-scoped user validation before protected work.

Chat consumes `/verify-token` in the proxy before rendering pages. The verifier
sets both the Chat-local app-session cookie and the Web-issued app-session
cookie pair used by forwarded central APIs. Protected Chat routes require both
cookies; if an older local-only cookie is present, Chat sends the user through
the local `/login` recovery path so the platform handoff refreshes the full
cookie pair. Access-token refresh must stay same-origin through
`/api/auth/refresh-app-session` instead of sending the browser back to
`apps/web` while a valid refresh cookie exists.

Chat routes must follow this order:

1. Authenticate the request user or app-session user.
2. Normalize workspace aliases such as `personal`.
3. Verify workspace membership and the required chat permission.
4. Call private-schema RPCs through a service-role admin client with
   `.schema('private').rpc(...)`.
5. Return only JSON DTOs that are safe for participants of the conversation.

## Private Schema Contract

Durable chat data lives in private tables only:

* `private.chat_conversations`
* `private.chat_conversation_members`
* `private.chat_messages`
* `private.chat_message_attachments`
* `private.chat_message_reactions`
* `private.chat_conversation_ai_settings`
* `private.chat_audit_events`

The migration revokes private schema, table, and function access from `public`,
`anon`, and `authenticated`; grants execution only to `service_role`; and keeps
RLS enabled with no permissive direct-access policies. Browser clients must
recover durable state by refetching the `apps/web` API, never by reading private
or legacy public chat tables directly.

RPCs enforce participant access, workspace membership, direct-chat uniqueness,
attachment path ownership, message ownership, reaction limits, search scoping,
read state, and audit metadata. When adding behavior, extend the private RPC
surface first and keep the web route as a thin auth/validation wrapper.

## Attachments

Chat attachments use the existing workspace storage provider rather than a
separate chat bucket. The upload flow is:

1. Client requests
   `/api/v1/workspaces/:wsId/chat/conversations/:conversationId/attachments/upload-url`.
2. `apps/web` verifies the participant through `private.chat_prepare_attachment`.
3. `apps/web` creates a Drive-backed signed upload payload under
   `:wsId/chats/:conversationId/*`.
4. The client uploads to the signed URL and sends the returned attachment draft
   with the message.
5. `private.chat_send_message` finalizes records and links attachments to the
   message.

Downloads use the attachment signing route. It calls `private.chat_get_attachment`
first, then issues a short-lived storage read URL only after the caller is
confirmed as a participant.

## Permissions

The chat permission set is:

* `view_chat`: read conversations where the actor is a participant.
* `create_chat`: create direct messages, groups, channels, and AI chats.
* `manage_chat`: manage chat membership, state, and AI settings.
* `moderate_chat`: moderate messages and reactions.

Member defaults include `view_chat` and `create_chat`. The dashboard navigation
should hide or disable Chat when `view_chat` is missing.

## AI Conversations

AI conversations are normal private chat conversations with
`ai_enabled = true` plus private AI settings. Existing AI audit or billing
tables can remain for provider usage tracking, but human chat access must not
depend on public AI chat tables. Persist generated assistant messages through
private chat RPCs so conversation history, read state, attachments, and audit
events remain in one protected chat domain.


# CMS
Source: https://docs.tuturuuu.com/platform/applications/cms

Dedicated Tuturuuu CMS app for site editing, preview, publishing, media, and team access.

## Overview

`apps/cms` is the dedicated home for Tuturuuu CMS. It should feel like a
consumer-grade site editing product for nontechnical editors, even though it
continues to use the existing external-project implementation contracts behind
the scenes.

* It owns the CMS UI, routing, workspace picker, and root-level `/{wsId}/projects` linking console.
* It remains a satellite frontend with mixed API ownership: CMS-local handlers
  own root administration and commerce integration, while the larger
  external-project content API remains in `apps/web`.
* Unmatched CMS `/api/*` traffic falls back to `apps/web`; an exact local route
  is served by `apps/cms` before that fallback is considered.

## Product Vocabulary

Normal CMS product UI should use editor-friendly terms: site, site template,
connection, content, section, URL path, custom details, media, publishing,
preview, and team access. Avoid exposing implementation terms such as external
project, canonical, adapter, binding, slug, schema, metadata, profile data,
payload, or JSON in the primary UI.

When staff genuinely need exact implementation values, place them behind a
collapsed "Developer details" or internal root-console advanced panel. Code,
database names, API paths, tests, and operational docs can keep the existing
`external-project*` names so route and data contracts remain stable.

## Routing

* `/{wsId}`: overview
* `/{wsId}/games`: game-focused content library, visible only when CMS Games is enabled
* `/{wsId}/landing`: landing-page builder for hero/profile/page-section edits
* `/{wsId}/library`: content operations library for non-landing, non-game content
* `/{wsId}/library/entries/{entryId}`: compatibility redirect that opens the library fullscreen editor dialog
* `/{wsId}/library/collections/{collectionId}`: collection detail
* `/{wsId}/members`: workspace member and role management
* `/{wsId}/preview`: delivered-content preview
* `/{wsId}/settings`: legacy compatibility redirect to `/{wsId}/members`
* `/internal/projects`: internal site-template registry and workspace linking console
* `/play/{wsId}/webgl/{assetId}`: public WebGL package player. This route does not require a CMS login, but the proxied WebGL asset API still only serves the package when the owning CMS entry is published. WebGL player iframes must stay sandboxed without `allow-same-origin`.

When `wsId` resolves to the internal/root workspace, `/{wsId}` and other workspace-local routes should bounce to `/internal/projects` instead of trying to render the bound-workspace CMS surfaces.

The previous `/{wsId}/content`, `/{wsId}/collections/...`, and `/{wsId}/admin` CMS routes are removed. New entry points should link directly to the CMS-native route map above.

## Access Model

* Only workspaces with CMS access enabled appear in the CMS workspace picker.
* A workspace must still satisfy the existing external-project permissions to open CMS workspace routes.
* CMS Games is disabled by default for every workspace. Enable it from the CMS settings dialog, which writes `ENABLE_CMS_GAMES=true` to workspace configs and reveals the `/{wsId}/games` sidebar route.
* Only platform admins can open `/internal/projects`.
* Workspace member and role management lives on `/{wsId}/members`. Read paths resolve through CMS workspace access so editors with CMS access can load people, invites, roles, member defaults, and guest defaults without requiring direct workspace settings-route access. Write paths still respect member and role management permissions.

## API Ownership

* `apps/cms` owns host-local auth/session and build-info routes. It also owns
  the root administration handlers for external-project audits, bindings, and
  project templates under `/api/v1/admin/*`, plus commerce overview, insights,
  products, and storefront under `/api/v1/commerce/*`.
* The workspace external-project families for content models, collections,
  entries, blocks, assets, publishing and delivery, sync, and CMS-aware team
  access remain in `apps/web`. Requests with no CMS-local handler reach them
  through the fallback `/api/:path*` rewrite.
* Keep clients on typed `@tuturuuu/internal-api` helpers. Browser calls should
  stay same-origin so local routes win and fallback routes are forwarded;
  request-scoped server calls must preserve forwarded authentication.
* CMS-local protected handlers resolve the CMS app-session actor and then apply
  `getCmsWorkspaceAccess` or the root-admin gate. Forwarded Web handlers still
  require the coordinated Web-issued session and enforce their own workspace
  permissions; the proxy guard is not a replacement for route authorization.
* The rewrite target must resolve to the central web app, not the CMS app origin. Prefer `INTERNAL_WEB_API_ORIGIN`, `NEXT_PUBLIC_WEB_APP_URL`, or `WEB_APP_URL` for the central origin. If a deployment-level `NEXT_PUBLIC_APP_URL` points at `cms.tuturuuu.com` or the current CMS Vercel preview URL, the CMS config ignores it and falls back to `https://tuturuuu.com` to avoid self-rewriting `/api/*` requests.
* Add new behavior to the host that owns its route family. Extend the CMS-local
  admin or commerce handler for those families; extend the Web-owned
  external-project handler for content, media, publishing, sync, or team
  behavior, and expose shared access through `packages/internal-api`.
* The root linking console reads the workspace-indexed binding summary from the
  CMS-local `GET /api/v1/admin/external-project-bindings` handler.
* The root linking console may load its initial server-render payload directly with the request-scoped CMS Supabase admin path after `getCmsWorkspaceAccess` proves root admin access. Avoid server-to-server Internal API fetches during that initial render, because production auth/origin forwarding failures turn `/internal/projects` into a hard RSC error page. Keep workspace-secret lookups batched; one `.in('ws_id', allWorkspaceIds)` query can exceed PostgREST/proxy URL limits and return `400 Bad Request` in production.
* Backend naming stays on `external-project*` contracts even though the product surface is branded as Tuturuuu CMS.
* Add or update the CMS product-copy hygiene test whenever new visible CMS
  strings are introduced. The test should protect the consumer vocabulary while
  allowing collapsed developer-detail and internal-only exceptions.

## Content Model

* Collections remain the content-type container. Field definitions live in `workspace_external_project_field_definitions`, while entry values continue to be stored in the existing `profile_data` and `metadata` JSON payloads so delivery and sync payloads stay backward-compatible.
* Field definitions support the manifest field contract: `string`, `markdown`, `number`, `boolean`, `date`, `datetime`, `json`, and `string-array`. Scope controls whether the value is saved under `profile_data` or `metadata`.
* The CMS Library has a `Content model` section with reusable templates for Profile, Blog Posts, Gallery, Shop Products, Writing Worlds, and Social Links. Applying a template creates the collection if needed, stores the collection schema, and creates any missing field definitions without deleting CMS-only fields.
* Landing and Library must stay visibly distinct. Landing is a page-builder surface for landing-only sections, preview-first actions, and page readiness. Library is a content operations surface for search, status, bulk publishing, collection health, and non-landing/non-game content. Keep `landing`, `library`, and `games` capability scopes mutually distinct in tests.
* The Library command center is the consolidated authoring entry point for content, content models, workflow queues, and settings. Keep new CMS operations reachable from that surface before adding another isolated toolbar or settings panel.
* Entry detail forms render schema-aware controls for the active collection field definitions. Authors should edit those typed controls instead of hand-editing raw `profile_data` or `metadata` JSON for modeled fields.
* Body and asset affordances should be driven by the collection schema when available. Naming heuristics for legacy Yoola collections remain as compatibility fallback only.
* External-project setup and sync import manifest `profileFields` and `metadataFields` into DB field definitions. Sync snapshots are built from DB-managed field definitions, and field removals should only be applied during an explicit destructive sync.

## Yashie Bridge

* Yashie is the proof case for the generic content model. Its manifest seeds profile, blog post, gallery, shop product, writing world, and social-link collections and field definitions.
* This phase does not change `../yashie` runtime pages. Yashie can be seeded and managed from CMS, but the public Yashie app continues to read its local static data until a later integration pass consumes CMS delivery payloads.
* Shop product entries are catalog-only in this phase. No checkout, payment, inventory, or commerce fulfillment behavior is implied by the template.

## Client Architecture

* Keep route pages server-side only for auth and access gates, then hand off interactive CMS surfaces to client modules backed by TanStack Query.
* Keep `cms-studio-client.tsx` focused on query state, mutations, and routing. Library rendering should stay split across dedicated gallery, workflow, and settings modules rather than growing back into one large TSX file.
* Keep CMS team access clients on `@tuturuuu/internal-api` helpers that target external-project-aware `apps/web` routes. Do not call the standard workspace members or roles settings endpoints directly from `apps/cms`.
* Entry detail now opens as a fullscreen dialog from the library route so the CMS keeps the library cache warm instead of forcing a separate navigation for each entry.
* The Games route reuses the library client with a game-like collection scope and only exposes WebGL ZIP upload controls when `ENABLE_CMS_GAMES` is explicitly enabled.
* When a user creates the first Games entry, CMS should automatically create the workspace `Games` collection and then open the new game entry instead of requiring a manual collection setup step.
* Published game entries expose a public `/play/{wsId}/webgl/{assetId}` link from the WebGL package card. Keep this route login-free in the CMS proxy, and keep publication checks in the central `apps/web` WebGL asset route so drafts and archived entries do not leak assets. The player iframe and the served WebGL document must both use sandboxing that allows scripts but does not allow same-origin access.
* CMS media uploads show per-file progress for cover images, gallery media, and WebGL ZIP packages. Cover and gallery media must use the external-project asset app-server upload route so Tuturuuu measures the actual bytes before writing storage objects, then store the returned Drive path on the CMS asset row. WebGL ZIP package uploads still upload directly to the signed storage URL returned by the self-hosted web API, then call the WebGL package finalize route so the ZIP can be extracted and mapped to a playable artifact. The WebGL asset-serving route must infer browser content types from the requested WebGL filename for known outputs such as `index.html`, `.js`, `.jpg`, `.wasm`, `.data`, and compressed `.gz`/`.br` files, because extracted storage metadata can be too generic or incorrectly recorded as `text/plain`. Served WebGL files must include a CSP `sandbox` header that omits `allow-same-origin`; served HTML is also adjusted for the CMS player so Unity canvases fill the iframe viewport instead of keeping the default fixed-size template layout, hide the stock Unity footer chrome, resize the canvas backing buffer to the iframe viewport, inject a route-local `<base>` and artifact-map URL resolver so `Build/*` and `TemplateData/*` load through the same WebGL package API route even when the Unity template creates scripts dynamically, and show in-frame resource download progress when the runtime fetches package assets.
* CMS asset delivery must respect the workspace Drive provider. Supabase assets may use signed image transforms, while R2-backed assets should resolve through the workspace storage provider signed-read path and ignore Supabase-only transform parameters.
* CMS asset rows may only store workspace storage paths under `external-projects/`; asset delivery and cleanup must not operate on paths from other workspace modules such as Drive or finance.
* CMS does not register the shared offline service worker or emit the shared web app manifest. It is a Vercel-hosted satellite whose unmatched, Web-owned protected API families fall back to `apps/web`, so PWA routes owned by `apps/web` must not be advertised from `cms.tuturuuu.com`.
* Library taxonomy edits should stay lightweight: category/tag assignment, creation, and removal can happen directly from the library dialog, while deeper editorial changes still live in the entry sidebar taxonomy card.

## Local Development

* Use `bun dev:cms` to run the CMS app with the shared packages and `apps/web`.
* Use `bun devx:cms` or `bun devrs:cms` when you also need a reset local Supabase environment.

## CI/CD

* Preview deployments run through `.github/workflows/vercel-preview-cms.yaml`.
* Production deployments run through `.github/workflows/vercel-production-cms.yaml`.
* Both workflows are gated through `ci-check.yml` and the `tuturuuu.ts` workflow allowlist.
* The Vercel project must be configured through the `VERCEL_CMS_PROJECT_ID` repository secret.


# Drive
Source: https://docs.tuturuuu.com/platform/applications/drive

Standalone Drive app with centralized workspace storage APIs.

## Overview

`apps/drive` is the canonical Tuturuuu Drive application. Production Drive
traffic should use `https://drive.tuturuuu.com/{wsId}` instead of rendering the
Drive explorer inside `apps/web`.

* `apps/drive` owns the workspace shell, Drive explorer UI, local
  `/verify-token` handoff, and local app-session logout.
* `apps/web /{wsId}/drive` remains a compatibility route. It checks
  `manage_drive`, preserves the query string, and redirects to the Drive app.
* Drive uses local port `7817` and Portless host `drive.tuturuuu.localhost`.

## API Ownership

Protected storage APIs remain centralized in `apps/web`:

* `apps/drive` forwards `/api/*` traffic to `apps/web`.
* Client Drive data flows must use `@tuturuuu/internal-api` helpers with
  TanStack Query.
* Do not create direct Supabase browser reads or storage mutations in
  `apps/drive`.
* `apps/web` storage routes authenticate normal web sessions and Drive
  app-session cookies through the shared storage route auth helper, then enforce
  `manage_drive` or the route-specific permission fallback.

When adding new Drive behavior, add the protected route in `apps/web`, expose it
from `packages/internal-api`, and consume it from `apps/drive`.

## CI/CD

Preview and production deployments use dedicated Vercel workflows:

* `.github/workflows/vercel-preview-drive.yaml`
* `.github/workflows/vercel-production-drive.yaml`

Both workflows are registered in `tuturuuu.ts` and use the shared
`ci-check.yml` switchboard with affected-path gating. They require
environment-scoped Vercel credentials:

* preview environment: `vercel-preview-drive`
* production environment: `vercel-production-drive`
* project secret: `VERCEL_DRIVE_PROJECT_ID`
* shared secrets: `VERCEL_TOKEN` and `VERCEL_ORG_ID`

The app-specific project secret should live in those GitHub Environments, not in
workflow-level `env`.

## Validation

Use these focused checks when changing Drive deployment wiring:

```bash theme={null}
node --test scripts/ci/check-workflow-config.test.js scripts/ci/release-workflows.test.js
```

Because Drive CI changes touch root TypeScript workflow config, finish with
`bun check` when the shared worktree state allows it.


# Finance
Source: https://docs.tuturuuu.com/platform/applications/finance

Shared Finance product surface across apps/web and apps/finance.

## Overview

`apps/finance` and the Finance experience inside `apps/web` are paired Finance
hosts. They must stay 1:1 for product features, data behavior, mutations,
permissions, route behavior, and user-facing workflow updates.

Canonical workspace routes include:

* `/{wsId}`
* `/{wsId}/transactions`
* `/{wsId}/wallets`
* `/{wsId}/invoices`
* `/{wsId}/categories`
* `/{wsId}/tags`
* `/{wsId}/recurring`
* `/{wsId}/budgets`
* `/{wsId}/analytics`
* `/{wsId}/debts`

`apps/web /{wsId}/finance/*` routes render the same shared Finance product
surface inside the normal platform dashboard shell. `apps/finance` keeps the
shorter standalone route shape without the `/finance` segment.

Use route prefixes instead of forks:

* `apps/web`: `financePrefix="/finance"` and
  `FinanceRouteProvider prefix="/finance"`.
* `apps/finance`: `financePrefix=""` and `FinanceRouteProvider prefix=""`.

Legacy nested category paths, such as
`/{wsId}/finance/transactions/categories`, should redirect inside `apps/web` to
`/{wsId}/finance/categories` while preserving query strings.

## API Ownership

* `apps/finance` owns the standalone workspace shell, Finance UI route wrappers,
  local `/verify-token` handoff, host-local auth/session routes, and build-info.
* `apps/web` owns platform-shell Finance route wrappers under
  `/{wsId}/finance/*`.
* `apps/finance` owns the hard-cutover product handlers for transactions and
  categories, wallets and checkpoints, budgets, debts, recurring transactions,
  invoices, charts and overview reporting, and Inventory reconciliation. It
  also has local supporting handlers for promotions, inventory products,
  settings, linked products/promotions, and workspace/user lookup needs.
* The local recurring, invoice, and wallet examples include
  `/api/v1/workspaces/:wsId/finance/recurring-transactions`,
  `/api/v1/workspaces/:wsId/finance/invoices`, and
  `/api/workspaces/:wsId/wallets`. Exact local handlers win before the
  `/api/:path*` fallback rewrite is considered.
* Deliberately central exceptions remain in `apps/web`: the legacy
  `/api/v1/workspaces/:wsId/wallets` list/create route, wallet-role whitelist
  routes, shared workspace storage routes used by transaction attachments, and
  the Finance exchange-rate cron. Unmatched requests reach Web through the
  fallback rewrite.
* Keep shared callers on `@tuturuuu/internal-api`. Finance-owned helpers use the
  Finance API base URL for server calls, while helpers for the deliberate Web
  exceptions remain on the central API origin; browser calls stay same-origin.
* Finance-local protected handlers accept the Finance app-session actor and
  enforce route-level workspace and product permissions. Forwarded Web
  exceptions require the coordinated Web-issued session and retain their own
  authorization checks.
* Finance transaction attachment reads must authorize through the same
  authenticated transaction visibility path as normal transaction reads. Do not
  grant storage list, metadata, or signed-read URL access from coarse
  `view_transactions` or `update_transactions` permissions alone; reuse
  `get_wallet_transactions_with_permissions` with `p_transaction_ids` so wallet
  whitelists, viewing windows, and granular income/expense permissions stay
  aligned.
* Finance transaction attachment uploads have server-side limits: 10 files per
  transaction and 50 MB per file. The signed-upload route must reject
  over-limit declared sizes before issuing a URL, and finalize must inspect the
  actual stored object size/count and delete over-limit uploads before any
  follow-up processing.
* Finance transaction type filters must not classify confidential amount signs
  for callers without `view_confidential_amount`. RPCs that accept
  `p_transaction_type` should apply income/expense predicates only when the row
  is non-confidential or the caller can view confidential amounts; otherwise
  typed filters should omit those redacted rows instead of using the raw amount
  sign.
* Finance invoice customer IDs must be validated against `workspace_users`
  with the route workspace before insert, and admin-backed invoice reads should
  resolve customer display fields with an explicit `ws_id` filter instead of a
  nested service-role join on `customer_id`.

When adding new Finance behavior, update the shared Finance UI/helper first,
then wire both host wrappers in the same change. Add or extend the route in
`apps/finance` when it belongs to a hard-cutover family; preserve the explicit
Web exceptions until their dependent platform callers migrate. Expose shared
access in `packages/internal-api` and consume it through TanStack Query or
shared server components.

## Inventory sales reconciliation

Finance owns the Inventory reconciliation inbox and its protected API under
`/api/workspaces/:wsId/finance/inventory-reconciliation`. Access to pending
entries, provider mappings, provider history synchronization, manual
adjustments, and bulk link/unlink actions requires `manage_finance`.

Every provider-confirmed Polar, Square POS, or Square Terminal event is first
stored as an immutable `private.inventory_finance_entries` source row. The
source row affects balances only after an atomic database RPC links it to a
currency-compatible wallet transaction. Missing wallets stay pending and are
never included in income, wallet, or net-total calculations.

Provider-and-currency mappings take precedence over the Inventory revenue
wallet fallback and the Finance default wallet. A wallet must use the entry
currency. Category resolution uses the unanimous product category first, then
the provider mapping, the Inventory default, and finally uncategorized.

Deleting or explicitly unlinking a provider transaction removes only the
ledger row and returns the immutable source entry to pending. Provider,
reference, signed amount, and occurrence date remain provider-controlled;
wallet, category, tags, description, and confidentiality remain editable.

For rollout and recovery:

1. Deploy the database migration before Inventory, Finance, or shared-package
   consumers.
2. Verify historical completed provider sales appear in the pending inbox.
   The migration never auto-posts unmatched historical sales.
3. Configure provider and currency mappings, inspect pending counts by
   currency, and only then use bulk linking.
4. Run the bounded provider-history sync explicitly to discover historical
   refunds and Square disputes.
5. If a ledger row was deleted accidentally, relink the still-present source
   entry. Do not recreate provider events manually.
6. Use audited manual adjustments only when the provider has no supported
   event, such as a Polar chargeback.


# Git
Source: https://docs.tuturuuu.com/platform/applications/git

Fast, read-only GitHub repository browsing through the Tuturuuu Git satellite.

Git is the public repository browser at `https://git.tuturuuu.com`. It renders
repository metadata, source trees, files, commits, issues, pull requests,
Actions, releases, refs, and contributors with a server-first Next.js 16.3
satellite. The initial registry always includes `tutur3u/platform`.

## URL model

Public repositories use short, GitHub-compatible paths:

* `/{owner}/{repository}` for the overview
* `/{owner}/{repository}/tree/{ref}/{path}` and `/blob/{ref}/{path}`
* `/{owner}/{repository}/commits`, `/commit/{sha}`, `/issues`, `/pulls`,
  `/actions`, `/releases`, `/contributors`, `/branches`, and `/tags`

The reserved `/-/internal` area uses the shared Tuturuuu satellite shell and
app-session authentication. There is no dashboard catch-all route, so `/api/*`
fallback rewrites remain safe.

## Repository registry

Only explicitly registered public repositories are displayed. Adding,
disabling, or refreshing a repository requires the root-workspace
`manage_git_repositories` permission. The server verifies that a repository is
public and belongs to the configured GitHub App installation before saving it.
Private repositories are rejected by both application checks and the database
constraint.

Registry and credential rows live in the Supabase `private` schema and are
accessible only through the service-role client.

## GitHub App

Use a dedicated organization-owned GitHub App named `Tuturuuu Git`. Do not
extend the existing deployment app.

Configure:

* Homepage URL: `https://git.tuturuuu.com`
* Webhooks, user authorization, and device flow: disabled
* Repository permissions: read-only Actions, Checks, Commit statuses,
  Contents, Issues, Metadata, and Pull requests
* Organization permissions: none
* Installation: the `tutur3u` organization, all repositories

Generate a private key only when an administrator can immediately store it
through `/-/internal/github-app`. The private key is envelope-encrypted with
`ENCRYPTION_MASTER_KEY`; plaintext is never returned after submission. Runtime
installation tokens are restricted to one approved repository ID.

## Deployment

The Vercel workflows expect `VERCEL_GIT_PROJECT_ID`, `VERCEL_ORG_ID`, and
`VERCEL_TOKEN`. Project creation and Git linkage are a one-time Vercel console
step. Configure the production domain as `git.tuturuuu.com`, set
`ENCRYPTION_MASTER_KEY` in protected environments, then use the admin page to
save the GitHub App ID, installation ID, and private key.

The public GitHub API remains a bootstrap fallback for registered public
repositories until the app credentials are configured. Mutable repository data
uses short cache lifetimes; immutable commit-addressed content uses long-lived
cache entries.


# Hive
Source: https://docs.tuturuuu.com/platform/applications/hive

Voxel research playground for CRDT worlds, farming simulation, NPC economies, and manual or autonomous society experiments.

Hive is the Tuturuuu research satellite app at `https://hive.tuturuuu.com`.
It uses the centralized Tuturuuu login handoff and keeps protected product APIs
inside `apps/web` under `/api/v1/hive/*`.

Hive consumes cross-app login tokens through `/verify-token`. That verifier
posts the handoff token to `/api/auth/verify-app-token`, trusts the returned
HttpOnly app-session cookies, and then redirects to the requested Hive path.
Protected routes require both the Hive-local app-session cookie and the
Web-issued app-session cookie used for forwarded central APIs. If only the
Hive-local cookie remains, Hive sends the browser through local `/login` to
recover the full cookie pair. Expired access tokens should rotate through
same-origin `/api/auth/refresh-app-session` while refresh cookies remain valid.
Hive must not create or refresh a Hive-domain Supabase Auth session. Hive local
logout is intentionally app-local: `/api/auth/logout` clears
`tuturuuu_app_session`, expires stale Supabase Auth cookies on the Hive host, and
redirects browser form submissions back to `/login`. Keep that route outside the
generic API proxy guard path so logout does not wait on product API rate-limit
checks.

## Dual-Host Parity

Hive is available through both the standalone satellite host and the main web
dashboard. The standalone route shape stays `/` and `/not-whitelisted`. Inside
`apps/web`, the route shape is `/{wsId}/hive` and
`/{wsId}/hive/not-whitelisted`; the `wsId` segment is only the surrounding web
dashboard context and must not filter Hive servers, snapshots, realtime
membership, or world data.

Both hosts must render the same shared Studio UI, engine, realtime client, data
hooks, and access-request card from `@tuturuuu/hive-ui`. Keep `apps/hive` and
the `apps/web` Hive routes as thin host wrappers for auth, access resolution,
build metadata, and forwarded API context only. Future Hive feature work belongs
in `packages/hive-ui`, `@tuturuuu/realtime/hive`, or the centralized Hive APIs
so the standalone app and web-hosted app stay 1:1.

## Access Model

* Production access is resolved from Supabase `public.hive_members` with
  `enabled = true` plus platform-admin roles. The dedicated Hive Postgres
  `hive_members` table is still synchronized for product data workflows, but
  app access gates must not require `HIVE_DATABASE_URL` just to decide whether a
  signed-in user can open Hive.
* Researchers who authenticate successfully but are not enabled land on
  `/not-whitelisted`, where they can create or refresh a
  `hive_access_requests` row. That page polls
  `/api/v1/hive/access-requests/me` every 5 seconds and opens Hive automatically
  after the request reaches the approved/access-enabled state.
* Platform admins are users whose `platform_user_roles.allow_role_management`
  value is `true`; they can create and manage Hive servers and Hive members.
* Root workspace admins can enable or disable Hive access from
  `/{rootWorkspaceId}/platform/roles` without opening the Hive satellite app.
* Pending Hive requests appear in the same platform roles panel. Approving a
  request writes both the dedicated Hive Postgres `hive_members` row and the
  Supabase `public.hive_members` row that the Hive satellite uses for its local
  server gate and that `apps/web` uses for embedded Hive routes. Do not update
  only one store, or users can authenticate through Tuturuuu and then loop back
  to the restricted page or fail an embedded Hive preload.
* V1 server policy is intentionally broad: every enabled Hive member can join
  every enabled Hive server.
* Hive servers are global research worlds. Workspace selection inside the Hive
  editor is only an AI context and billing control; it must not filter server
  lists, snapshots, realtime membership, or world data.
* `apps/web` remains the login authority and verifies platform roles through
  internal APIs. Hive itself uses the app-session JWT as the local identity
  cookie. Hive product data is split across two databases (see
  [Data Model](#data-model)): the authoritative world-event, CRDT, and research
  tables live in the main Supabase `public` schema, while a parallel Docker-managed
  Hive Postgres baseline accessed through `HIVE_DATABASE_URL` carries the
  dedicated-store mirror used by backfill and product-data workflows.

## Data Model

Hive product state spans **two physical databases**, and it matters which one is
authoritative for any given table when you operate or debug the app.

### Authoritative store: main Supabase `public` schema

The live world-event, CRDT, economy, NPC, and research tables that the running
`/api/v1/hive/*` routes read and write are in the **main Supabase project**
(`public.hive_*`). All apps share one Supabase project, so these tables are
managed by the standard Supabase migration flow in
`apps/database/supabase/migrations/`, not by the Hive Postgres migrator. This is
where the audited world-event path actually runs:

* `hive_servers`
* `hive_world_states` — authoritative full-world snapshots
* `hive_world_events` — event metadata and compact payloads
* `hive_npcs`, `hive_npc_runs`, `hive_npc_memories`
* `hive_workflows`, `hive_workflow_runs`
* `hive_research_sessions`, `hive_research_session_events`
* `hive_members`, `hive_access_requests`

The `apply_hive_world_event()` Postgres function is defined as
`public.apply_hive_world_event(...)` in the Supabase migrations
(`20260510143500_add_hive_research_engine.sql`, then hardened by
`20260511160200_fix_hive_world_event_ambiguity.sql`,
`20260512151000_make_hive_revision_conflicts_non_exceptional.sql`, and
`20260512204028_secure_hive_world_event_actor.sql`). It inserts/updates
`public.hive_world_states` and appends to `public.hive_world_events` in one
transaction. It is **not** a Hive-Postgres migration. If a world save returns
`hive_event_failed`, debug it against Supabase — see
[Hive world event troubleshooting](/platform/applications/hive-world-event-troubleshooting).

### Dedicated Hive Postgres mirror (`HIVE_DATABASE_URL`)

A separate Docker-managed Hive Postgres database holds a parallel
dedicated-store baseline (`apps/hive/db/001_schema.sql`) that the one-shot
backfill path populates from legacy Supabase Hive rows. Its `001_schema.sql`
baseline declares its own copies of `hive_members`, `hive_access_requests`,
`hive_servers`, `hive_world_states`, `hive_world_events`,
`hive_research_sessions`, `hive_research_session_events`, `hive_crdt_updates`,
`hive_npcs`, `hive_npc_needs`, `hive_npc_wallets`, `hive_npc_memories`,
`hive_npc_runs`, `hive_ledger_entries`, `hive_inventory_items`,
`hive_warehouses`, `hive_trade_offers`, `hive_crop_instances`, and
`hive_simulation_ticks`. The `apply_hive_world_event` function and the
world-event/actor-security logic are **not** present in this baseline; that path
lives only in Supabase.

Because the dedicated baseline mirrors many of the same table names, do not
assume a fix applied to one database is visible to the other. App access gates
read Supabase `public.hive_members` (and platform-admin roles), and approving a
request writes **both** stores (see [Access Model](#access-model)).

## Database Migrations

Hive Postgres is forward-migrated by the `hive-db-migrate` Docker Compose job
before web, Hive, Hive realtime, or Hive cron processes are allowed to start.
The deployment watcher also runs that job explicitly with
`docker compose run --rm --no-build hive-db-migrate` on every blue/green
deployment so an already-completed migration container cannot silently satisfy a
new deploy.
After the explicit run and after Hive services start, the watcher removes the
one-shot migrator by Docker Compose project and service labels, including
stopped containers named like `tuturuuu-hive-db-migrate-*`, so the migration
job does not stay around consuming host resources or making the cluster look
unhealthy.

The migration runner records successful work in `hive_schema_migrations` with a
timestamp version, filename, checksum, `applied_at`, and `applied_by`. The
current `apps/hive/db/001_schema.sql` file is the immutable baseline; future
changes belong in `apps/hive/db/migrations/YYYYMMDDHHMMSS_description.sql`.
Deployment fails when a pending migration checksum disagrees with history, when
its timestamp is not newer than the last recorded migration version, or when its
timestamp is not newer than the last recorded `applied_at` time at deployment
start.

The runner rejects reset-style SQL such as `DROP DATABASE`, `DROP SCHEMA`,
`DROP TABLE`, `TRUNCATE`, `ALTER TABLE ... DROP COLUMN`, and mutation of
`hive_schema_migrations`. A destructive Hive DB operation requires an explicit
DevOps-admin override by setting `HIVE_DB_OPERATOR_ROLE=devops-admin`,
`HIVE_DB_ALLOW_DESTRUCTIVE_RESET=1`, and
`HIVE_DB_DEVOPS_ADMIN_APPROVED=1`; do not set those values in normal deploy
environments.

When the migration runner finds an older Hive DB that already has runtime tables
but no `hive_schema_migrations` history, it performs a forward-only compatibility
pass before recording the baseline. That pass creates the research-session table
when needed and adds missing nullable `research_session_id` columns to legacy
event, NPC run, and simulation tick tables so the immutable baseline can replay
without failing on partial indexes.

Shared editor state is a Yjs CRDT document per Hive server. Terrain blocks,
objects, public NPC projections, farm tiles, and visual warehouse/crop
projections live in keyed CRDT maps. Money, item ownership, trade settlement,
warehouse transfers, LLM spend, and bankrupt elimination stay relational and
transactional in Postgres so currency and inventory cannot be duplicated by CRDT
merge behavior.

`revision` is now a compatibility display value backed by the monotonic `op_seq`
audit counter. It is not a write precondition for normal CRDT world edits.
Authoritative economy writes must use SQL transactions, idempotency keys where
available, and ledger rows.

The one-shot Hive backfill path copies legacy Hive rows into the dedicated Hive
Postgres baseline so the dedicated store mirrors prior product data. Note that
the authoritative live world-event, CRDT, economy, NPC, and research writes
performed by `/api/v1/hive/*` run against the main Supabase `public` schema (see
[Data Model](#data-model)); the dedicated Hive Postgres is the mirrored
dedicated store, not the runtime authority for the world-event path. In all
cases, `apps/web` internal APIs use the forwarded app-session cookie to resolve
the caller and platform-admin status.

In Docker production, Hive satellite API rewrites must target the web service
through `INTERNAL_WEB_API_ORIGIN=http://web-proxy:7803`. If that value is empty,
the Hive Next.js rewrite can fall back to the public web origin and turn every
editor save into a browser-to-Hive-to-public-Web round trip.

Hive Docker production builds run the Next.js build through
`scripts/run-hive-docker-next-build.js` under the real `node:24` builder stage.
The builder still copies Bun from the dependency stage for workspace package
builds, but the final Hive `next build --turbopack` step must be launched with
Node and `/tmp/web.env` instead of `bun --env-file` so production E2E image
bakes do not depend on Bun's Next.js process shim.

Hive graph workflows are server-scoped product data. Platform admins author
shared workflow definitions in `hive_workflows`; enabled Hive members can run
enabled, unarchived workflows manually, and every run writes a row in
`hive_workflow_runs` with the input, output, step trace, status, and error
message. Workflow definitions are JSON graphs with typed nodes and edges. V1
manual execution disallows cycles, caps graphs at 80 nodes / 120 edges, and
uses restricted `{{steps.nodeId.output.path}}` or `{{input.path}}` references
only. Do not add arbitrary JavaScript evaluation to workflow config. Workflow
`world_event` nodes can also include a `worldPatch` object with `blocks`,
`objects`, `removeBlockIds`, `removeObjectIds`, or `clear: true`; the engine
applies that patch to the latest server snapshot and persists the result through
the same audited world-event path as manual editor saves.

Workflow `agent_interaction` nodes run configured NPC pairs through the same
LLM-backed interaction path as Agent Studio pair queues, with deterministic
fallback behavior when provider access is unavailable. Mind imports use
`/api/v1/hive/servers/:serverId/mind-simulations` to create NPC agents from a
Mind board, create source graph interaction pairs, and save a Hive workflow that
stamps the Mind source context before running those pairs. That import route is
an admin operation because it creates shared Hive server state.

Research sessions are the shared audit spine for multi-agent experiments. A
running `hive_research_sessions` row can be attached to NPC runs, workflow
runs, world events, and simulation ticks through nullable `research_session_id`
columns. When a run payload omits `researchSessionId`, the backend attaches the
active running session for that server when one exists. Session events in
`hive_research_session_events` record operational actions such as session
creation/update and pair queue start/complete markers. Session exports are
available from
`/api/v1/hive/servers/:serverId/research-sessions/:sessionId/export` as JSON or
JSONL and should preserve enough identifiers to replay research timelines
outside the app.

Shared realtime payloads and Hive CRDT helpers live in
`@tuturuuu/realtime/hive`. Keep protocol schemas there when both `apps/hive`,
`apps/hive-realtime`, or `apps/web` need the same message or document contract.

## AI Credit Context

Hive uses the same AI credit and model contracts as the main dashboard. The
editor top bar owns the workspace picker, personal/workspace credit source
toggle, credit meter, and model picker. The selected workspace is the credit
context only; it does not scope Hive servers.

Manual NPC runs and manual NPC-to-NPC interactions send `creditSource`,
`creditWsId`, and `model` through the Hive internal API. The web route verifies
that the signed-in Hive user can access the selected workspace, resolves the
requested model against the workspace plan, preflights AI credits, runs the LLM,
and deducts credits only after successful model usage. A failed post-generation
credit deduction is a request failure: the provider output is not persisted or
returned to the caller. If model access is not configured, the route can still
persist a deterministic NPC decision for inspectable simulation history.

Autonomous NPC interactions use server settings instead of the current browser
selection. `defaultCreditSource`, `defaultCreditWsId`, and `defaultModel` define
the billing/model context for scheduled simulation work. If the billing
workspace is missing or unauthorized, scheduled LLM autonomy is skipped and the
normal simulation tick continues.

`hive_npc_runs` stores grouped interaction metadata for manual pair queues,
one-shot manual runs, autonomous runs, and workflow-triggered decisions:
`interaction_id`, source/target NPCs, trigger, status, model, provider, token
counts, credit source/workspace, deducted credits, errors, and optional
`research_session_id`. Timeline surfaces should group or filter from this
persisted run history plus world events, workflow runs, simulation ticks, and
session events rather than recomputing transcripts from transient client state.

## Editor Surface

`apps/hive` is a hidden-locale Next.js satellite app. The editor uses a
full-bleed React Three Fiber viewport, compact top status chips, a bottom tool
dock with build/settings controls, an Agent Studio rail, a research timeline
drawer, and selected-detail overlays. The 3D world remains mounted while users
open agent setup, workflow authoring, timeline observability, AI context, or
operations controls.

The editor is built on the shared `@tuturuuu/satellite` workspace shell. Hive
uses that shell for collapsible left/right rails, top research overlays, and the
bottom tool dock so satellite apps can share layout mechanics while keeping
Hive-specific tool density and viewport behavior.

Collapsed editor slots must remove hit targets as well as opacity. Hidden Hive
toolbars use the satellite shell's collapsed `visibility` and pointer-event
gating so invisible dock buttons cannot still receive hover, focus, or tooltip
events.

Hive keeps one editable CRDT world per server. Admins manage that world through
server controls: creating a server creates its world, deleting a server deletes
the world through database cascade, and clear/reseed actions persist typed audit
events plus CRDT updates against the current server document.

Manual editor changes persist through the web gateway world-event API, which
calls the Supabase `public.apply_hive_world_event()` function. That function
stores the authoritative `world_data` and the matching event metadata in the
same Supabase transaction, then the Hive client only broadcasts the already
applied event through `hive-realtime`. Do not add a second client-side
`sync.update` persistence write after the gateway event succeeds; duplicate
writes can churn `op_seq`, slow visible save completion, and let older world
snapshots overwrite newer local edits. Realtime and snapshot consumers must
also ignore equal or older revisions so delayed broadcasts cannot revert an
optimistic edit that already advanced locally.

Keep full-world snapshots in `hive_world_states` only. `hive_world_events`
should store event metadata and the compact event payload, not another copy of
`world_data`, because normal editor saves can otherwise rewrite and insert the
entire voxel world twice on every operation.

The 3D editor treats the voxel grid as the source of truth. Perspective comes
from the camera and controls, not from rotating the editable world group. World
edits should commit only after click/drag threshold handling so orbit, pan,
zoom, placement, erasing, moving, and rotating do not conflict with each other.
The bottom dock uses explicit persistent panel toggles instead of hover-only
expansion. Build catalog, editor settings, and live operations each have a
visible icon control. Minimal tile gaps are the default terrain presentation;
gapless rendering is an explicit settings toggle. The Settings dock tab owns the
continuous 24-hour time slider, auto-time speed, season, weather, camera
presets, and simulation/server toggles. Do not restore the older five fixed
visible time buttons as the primary time control.

Live operations in the dock must use existing Hive snapshot state rather than a
new route: world counts, crops, warehouses, server currency, events, online
users, realtime status, revision, and the last sync notice. Agent Studio owns
multi-agent setup and ordered pair queues: multi-select NPCs, batch role/memory
/autonomy edits, round-robin pairs, all-to-all pairs, custom target pairs, run
prompt, turn count, and current AI context. NPC Lab remains the selected-agent
detail editor only. When no NPC is selected, it should show a selection prompt
instead of silently mutating the first NPC in the server.

The editor uses a single Research Studio panel state instead of separate
full-screen World / Workflow graph / Timeline destinations. Workflow graph is a
focused overlay on top of the persistent world viewport. Timeline is a drawer
that reads `/api/v1/hive/servers/:serverId/timeline`, filters by research
session and run metadata, and expands rows into input/output context, status,
model/provider, credits, and export identifiers. Workflow mode is still a 2D
React Flow graph builder for manual Hive automations, but it must reuse the same
AI context, run trace, and research timeline contracts as NPC pair queues.
Embedded `apps/web` Hive routes should load `@xyflow/react/dist/style.css` from
the Hive route segment layout rather than the root web layout, so React Flow
styles are available for workflow mode without adding that CSS to unrelated
dashboard routes.
Admins can drag nodes from the palette, use starter templates, edit JSON config
in the inspector, save shared workflows, and run them against the selected
server. Members see the same graph read-only and can manually run saved
workflows. Workflow runs apply live effects through the same gateway-backed Hive
actions used elsewhere: world events, simulation ticks, NPC decision records,
farming, warehouses, and trades. Effects are audited through the workflow run
trace, research session timeline, and existing Hive event/economy tables; v1 has
no schedule, webhook trigger, retry queue, credential vault, or rollback
approval layer.

Starter workflow templates should demonstrate a real server-side use case, not
just create trace rows. The farm cycle template plants a relational crop, then
uses a `world_event.worldPatch` step to stamp a visible crop plot into the Hive
world. The cleanup template removes that starter plot by id and records the
maintenance event.

Keep manual and autonomous interaction rows grouped by `interaction_id` whenever
a deeper transcript view is added. Pair queue runs must execute pairs in request
order and return partial failures without dropping successful earlier pairs.

NPC Lab is a draft editor for the selected NPC only. Identity, brain/model,
behavior/autonomy, memory/prompt flags, system prompt, and interaction controls
belong in the lab tabs. Save/Reset should protect large text and settings edits
from accidental persistence, while manual run buttons can launch one-shot
decisions or targeted NPC-to-NPC interactions using the current AI credit
context.

The chat composer is opt-in from the editor chrome button, and the mini-map is
a collapsible viewport overlay. If all Hive servers are deleted, the editor must
clear local world, NPC, revision, selection, presence, and awareness state so it
does not keep rendering the last server snapshot.

Time of day still maps to authored scene backdrops and lerped lighting, fog,
background, and cloud tint. Weather and season controls layer visual atmosphere
over that time base without changing the durable CRDT world snapshot.
Realtime multiplayer awareness is ephemeral. Avatar badges, terrain cursors,
selection rings, active tool state, camera focus, and in-world user markers are
sent as TTL-based awareness updates and must not be persisted into durable
world snapshots.

Offline world edits are queued as CRDT updates and replayed on reconnect. The
client uses token refresh, exponential backoff, state-vector resync, throttled
cursor/position updates, and local actor echo suppression to keep the research
surface responsive during reconnects and slow-client conditions.

Client data access must go through `@tuturuuu/internal-api` helpers and
TanStack Query. Do not add raw client `fetch()` calls in the satellite app.

## Testing

Hive has app-local Playwright coverage in `apps/hive/e2e`. The suite assumes
the local web app on `https://tuturuuu.localhost` and Hive app on
`https://hive.tuturuuu.localhost` are already running through Portless; it does
not auto-start dev servers. Root `bun test:e2e` intentionally runs the
self-contained Dockerized web E2E suite instead; after starting the Portless
services for Hive, run Hive coverage with:

```bash theme={null}
bun --filter @tuturuuu/hive test:e2e
```

The authenticated setup uses the web app's development session endpoint for the
seeded `local@tuturuuu.com` account before opening Hive. Override
`WEB_BASE_URL` or `HIVE_BASE_URL` when bypassing Portless or using direct
fallback ports.

## Economy And Farming

Each Hive server has a total currency pool, NPC wallets, inventories,
warehouses, trade offers, crops, and ledger-backed transfers. NPCs have hunger,
energy, morale, upkeep, and optional LLM spend budgets. Crop rules cover
soil/water/fertilizer state, growth stages, harvest yields, and day-cycle
simulation.

Manual tools can plant, water, harvest, deposit, withdraw, and settle trades.
Autonomous ticks can advance crops, choose NPC jobs, apply upkeep, record LLM
run costs, credit earnings, and eliminate NPCs whose wallets cannot cover
required costs.

Cron-backed Hive simulation is intentionally disabled by default. Enable global
Hive cron and per-server autonomous simulation through Hive settings only after
budget limits, tick interval, and max LLM spend have been reviewed.

## LLM Providers

Ollama is optional and disabled by default. Docker can start the
`hive-ollama` profile, and Hive settings can enable the local model id exactly
as `gemma4`. The app loads the model through Ollama's generate API, generates
through `/api/generate`, and unloads by sending `keep_alive: 0`.

Every Mira-powered LLM path must be gated by an exact `@tuturuuu.com` email
check. Subdomains such as `@xwf.tuturuuu.com` are not Tuturuuu-internal for
Mira access.


# Hive world event troubleshooting
Source: https://docs.tuturuuu.com/platform/applications/hive-world-event-troubleshooting

Fix ambiguous server_id errors when applying Hive world events.

## Symptoms

When creating a Hive world event, the API can return:

```
column reference "server_id" is ambiguous
```

This surfaces as `hive_event_failed` in the client with a 400 error.

## Cause

`apply_hive_world_event` returns a `table` signature that includes `server_id`.
In PL/pgSQL, output columns are variables. Unqualified references to
`server_id` inside the function can become ambiguous and fail at runtime.

## Fix

Use a constraint-based conflict target in the insert that bootstraps
`hive_world_states` so the SQL does not rely on a bare `server_id` identifier:

```
insert into public.hive_world_states (server_id, revision, world_data, updated_by)
values (p_server_id, 0, '{}'::jsonb, p_actor_user_id)
on conflict on constraint hive_world_states_pkey do nothing;
```

Apply the migration and re-run Hive event creation after the updated function is live.

## Actor Authorization

The actor-accepting `apply_hive_world_event(uuid, uuid, bigint, text, jsonb,
jsonb)` overload should not be exposed to browser roles. Keep direct execution
revoked from `public`, `anon`, and `authenticated`; server-side API and realtime
paths call it with `service_role` after validating the user session or signed
Hive realtime token. If a non-service role ever reaches the function, it must
derive the actor from `auth.uid()` and reject mismatched `p_actor_user_id`
values with `hive_actor_mismatch`.


# Inventory
Source: https://docs.tuturuuu.com/platform/applications/inventory

How inventory.tuturuuu.com is wired as the inventory satellite app, operator console, public storefront, checkout reservation, and audit operations surface.

Inventory lives in `apps/inventory` and runs locally through Portless at
`https://inventory.tuturuuu.localhost`. Production is intended for
`https://inventory.tuturuuu.com`.

The app is a registered Tuturuuu satellite app. It uses Tuturuuu app-session
auth for `targetApp: 'inventory'`, exposes local `/verify-token` and
`/api/auth/verify-app-token` handoff routes, and forwards fallback `/api/*`
traffic to centralized `apps/web` APIs. Keep protected inventory, payment,
Stripe Connect, checkout, Square Terminal, and audit mutations behind `apps/web` so provider
secrets, bot protection, request logging, and Observability stay centralized.
Workspace-scoped Inventory APIs in `apps/web` must authorize through
`authorizeInventoryWorkspace`, which accepts the Inventory app-session cookie
and then performs workspace membership and permission checks. Authenticated
dashboard and workspace API access is permission-driven; do not hide these
routes behind the `ENABLE_INVENTORY` workspace config. Keep public storefront
delivery separate, since published storefront behavior may still apply
storefront-specific rollout gates. Do not use `resolveAuthenticatedSessionUser`,
`supabase.auth.getUser()`, or request-scoped Supabase clients as the primary auth
gate for these routes, because the satellite clears local Supabase cookies and
forwards app-session cookies instead.
The operator console uses the same collapsible Tuturuuu satellite workspace
structure as the Tasks, Finance, Calendar, and CMS apps: dashboard layouts should
keep server work to auth/workspace gating, then render client-side views backed
by TanStack Query and `@tuturuuu/internal-api`. Do not reintroduce a separate
Inventory-only app shell or direct client Supabase reads for protected workspace
data.
The local token verifier must call the central Web verifier with
`verificationBaseUrl: WEB_APP_URL`; Inventory protected routes require both the
host-only Inventory app-session cookie and the Web-issued app-session cookie
used by rewritten `apps/web` API requests. Local-only token validation will
create a redirect loop back to platform login. Current-user bootstrap APIs such
as `/api/v1/users/me/default-workspace` and `/api/v1/users/me/profile` must keep
`inventory` in their app-session audience allowlist, or `/dashboard` will accept
the local handoff cookies and then bounce back to Web auth after the bootstrap
request returns `401`.

Public storefront routes live at `/store/[storeSlug]` inside `apps/inventory`
and are intentionally exempt from the operator auth proxy. They should only
read published storefront data through `apps/web` public APIs and should create
checkout reservations through the central `apps/web` RPC wrapper. Do not add
storefront CRUD, reservation writes, invoice finalization, or settlement writes
directly to `apps/inventory`.

## Local Development

Use:

```bash theme={null}
bun dev:inventory
```

The package `dev` script runs Portless. For direct port debugging, run
`apps/inventory` with `bun dev:app`, which falls back to port `7815`.

## Product Boundary

Inventory starts with workspace-scoped surfaces for:

* product catalog categorization by type, owner, manufacturer, talent,
  supplier, channel, and fulfillment policy
* stock movement and reservation ledgers
* bundle and promotion availability controls
* checkout fee visibility for processing fees, Tuturuuu platform fees,
  conversion fees, settlement estimates, and net payout
* payment and inventory audit streams
* Stripe Connect readiness for B2B2C sellers who link their own Stripe account

The commerce storefront extension adds:

* operator routes for overview, catalog, stock, bundles, storefronts,
  checkouts, sales, setup readiness, and audits
* public routes for `/store/[storeSlug]`,
  `/store/[storeSlug]/products/[listingId]`, cart, checkout, and order status
* private-schema tables for storefronts, listings, bundles, checkout sessions,
  checkout lines, reservations, Square connection state, terminal checkout
  identifiers, and settlement ledger entries
* commerce money (listing/bundle prices, checkout amounts, settlement, and
  costing) stored in integer minor units of the row currency (cents for USD,
  whole units for JPY/VND); convert with `@tuturuuu/utils/money` and enter with
  the shared `MoneyInput`. See the Polar storefront and Square Terminal
  integration runbooks.
* Square Terminal settings for workspace app credentials, OAuth/manual tokens,
  location selection, device pairing, webhook verification, and commerce actions
  that send, cancel, and reconcile terminal payments after local stock is
  reserved. The same settings surface provides guarded Square catalog and stock
  import, additive publish, and conflict-aware two-way sync. Provider deletion
  is deliberately unsupported.
* service-role-only RPCs for creating reservations, releasing or expiring
  reservations, materializing checkout TTL expiry, and linking a completed
  checkout to a `finance_invoice`
* private sales periods that group both invoice-backed and completed checkout
  sales into seasons, conventions, campaigns, or other operating windows. A
  sale has at most one period assignment, while archived periods keep their
  historical assignments and remain available for reporting.
* durable Finance source entries for every completed real-provider checkout,
  refund, Square chargeback hold/release, and audited provider-unavailable
  adjustment. Simulated checkouts are excluded. Manual Inventory sales continue
  using their existing Finance invoice path.

The Inventory Sales list shows whether a provider checkout is linked, pending,
refunded, or disputed and links to the corresponding Finance transaction or
reconciliation entry. Unlinked entries are operationally visible but do not
affect Finance ledger totals.

New commerce tables belong in the `private` schema, not `public`. Public and
satellite clients must go through Inventory-owned `apps/inventory` APIs plus
`@tuturuuu/internal-api`; direct Supabase client access to these tables is not
part of the contract. Protected workspace routes must authenticate and normalize
the workspace with the request-scoped client before any private-table read or
write, then use server-only database access or service-role RPCs behind
`apps/inventory`.

Sales-period clients use the Inventory-owned routes below. Keep these paths in
the Flutter API mapping check whenever the mobile catalog changes:

* `GET/POST /api/v1/workspaces/:wsId/inventory/sales-periods`
* `PATCH/DELETE /api/v1/workspaces/:wsId/inventory/sales-periods/:periodId`
* `PUT /api/v1/workspaces/:wsId/inventory/sales/:saleId/period`
* `GET /api/v1/workspaces/:wsId/inventory/sales?period_id=:periodId`

Core stock and setup data lives in private inventory tables:
`private.inventory_products`, `private.inventory_units`,
`private.inventory_warehouses`, `private.inventory_suppliers`,
`private.inventory_batches`, `private.inventory_batch_products`,
`private.inventory_owners`, `private.inventory_audit_logs`, and
`private.inventory_manufacturers`. Dashboard pages and APIs should access them
through server-owned `apps/web` routes. Prefer private-schema RPCs for product
catalog, low-stock, and other repeated join-heavy reads; call them with
`createAdminClient().schema('private').rpc(...)` from server code.

Manufacturers are a normalized workspace setup entity matching the
supplier-style management model. Products store only
`workspace_products.manufacturer_id`; API responses may still include
`manufacturer` as a display name for older clients. Legacy imports that send
package/product manufacturer text should upsert the trimmed name into
`private.inventory_manufacturers`, assign the resulting `manufacturer_id`, and
avoid writing manufacturer text back to `workspace_products`.

Bundle components are a workspace-scoped stock contract. When creating or
updating a bundle, every component's product, unit, warehouse, and stock row
must belong to the same workspace as the bundle. The database trigger on
`private.inventory_bundle_components` enforces that invariant for direct writes,
and the checkout reservation RPC re-checks the same workspace before locking
stock. Do not trust stored bundle component UUIDs as already authorized input.

Do not hardcode Stripe fee schedules as durable truth. The checkout estimator is
for quoting and operator review; production reconciliation should persist the
estimate shown to the seller and then reconcile it against actual Stripe balance
transaction fee rows after settlement.

## Deployment

Inventory has dedicated Vercel workflows:

* `.github/workflows/vercel-preview-inventory.yaml`
* `.github/workflows/vercel-production-inventory.yaml`

These workflows use `VERCEL_INVENTORY_PROJECT_ID`. Add that secret before
enabling hosted deployments for `inventory.tuturuuu.com`.


# Square POS with Tuturuuu Inventory
Source: https://docs.tuturuuu.com/platform/applications/inventory-square-pos

Start here to connect Square Terminal, synchronize catalog and stock, rehearse safely, and launch in-person payments.

Tuturuuu connects a Storefront order to a physical **Square Terminal** through
Square's Terminal API. Customers shop in the Tuturuuu Storefront, Inventory
reserves the stock, and the Square checkout is dispatched to the selected
Terminal. An authorized operator can also send or cancel an eligible reserved
checkout from Commerce. Square processes the card-present payment and reports
the result back to Tuturuuu.

<Info>
  This integration uses Square Terminal in Connected Mode. It does not launch
  the Square Point of Sale mobile app, and connecting an account never creates
  a charge by itself.
</Info>

## Choose your guide

<CardGroup>
  <Card title="Set up the account and counter" icon="plug" href="/platform/applications/inventory-square-pos/customer-setup">
    A non-technical walkthrough for the Square owner, Inventory admin, and
    counter operator.
  </Card>

  <Card title="Rehearse in Sandbox" icon="flask" href="/platform/applications/inventory-square-pos/sandbox-testing">
    Test success, cancellation, timeout, offline behavior, stock release, and
    duplicate webhooks without moving real money.
  </Card>

  <Card title="Synchronize catalog and stock" icon="arrows-rotate" href="/platform/applications/inventory-square-pos/catalog-sync">
    Import from Square, publish from Tuturuuu, compare both sides, and resolve
    conflicts without deleting Square objects.
  </Card>

  <Card title="Launch Production safely" icon="shield-check" href="/platform/applications/inventory-square-pos/production-launch">
    Pair the physical Terminal, run one owner-approved live sale, and apply the
    go/no-go gate.
  </Card>

  <Card title="Operate and verify payments" icon="chart-line" href="/platform/applications/inventory-square-pos/operations">
    Read the Payments hub, reconcile transactions, and understand reservation
    and webhook behavior.
  </Card>

  <Card title="Troubleshoot safely" icon="life-ring" href="/platform/applications/inventory-square-pos/troubleshooting">
    Follow symptom-based recovery steps without double-charging or corrupting
    stock.
  </Card>
</CardGroup>

## How one payment travels

```mermaid theme={null}
sequenceDiagram
  autonumber
  actor Buyer
  participant Store as Tuturuuu Storefront
  participant Inv as Inventory
  participant Sq as Square
  participant Term as Square Terminal

  Buyer->>Store: Submit the cart
  Store->>Inv: Create checkout and reserve stock
  Inv->>Sq: Create Square order and Terminal checkout
  Sq->>Term: Show the itemized payment request
  Buyer->>Term: Complete or cancel payment
  Term-->>Sq: Report the result
  Sq-->>Inv: Deliver signed webhooks
  Inv->>Inv: Complete sale or release reservation
  Inv-->>Store: Show final order status and receipt evidence
```

Tuturuuu finishes a sale only after it can reconcile a verified Square payment.
If checkout creation fails, the buyer cancels, Square reports failure or expiry,
or the local reservation expires, Tuturuuu releases the reserved stock.

## The Payments control center

Open:

```text theme={null}
https://inventory.tuturuuu.com/<workspace-id>/payments
```

The page is read-only by default. Use the compact edit control only when you
intend to change settings or start a catalog synchronization.

| Payments section     | What it answers                                                                                   |
| -------------------- | ------------------------------------------------------------------------------------------------- |
| **Connect & set up** | Is the selected Square environment connected, signed, located, and routed to a device?            |
| **Catalog sync**     | Which products and variations are linked, where they originated, and which conflicts need review? |
| **Test & verify**    | Did a provider checkout create one transaction with the expected amount, status, and evidence?    |

## Sandbox and Production stay separate

```mermaid theme={null}
flowchart LR
  A["Square Sandbox seller"] --> B["Sandbox token, webhook, location, simulator ID"]
  B --> C["Tuturuuu Sandbox rehearsal"]
  C -->|"All exit checks pass"| D["Create a separate Production connection"]
  D --> E["Production token, webhook, location, physical device"]
  E --> F["One approved low-value live sale"]
```

| Sandbox                                                        | Production                                                         |
| -------------------------------------------------------------- | ------------------------------------------------------------------ |
| Test seller, credentials, objects, and simulator device IDs    | Real seller, credentials, catalog, location, and physical Terminal |
| No real card or Square hardware                                | Real card-present processing and possible fees                     |
| Safe place for demo CRUD, retries, cancellations, and timeouts | Change only approved records and run only approved payments        |
| No physical receipt                                            | Verify the actual Terminal and printed or digital receipt          |

<Warning>
  Never copy a Sandbox token, object ID, location ID, webhook signature key, or
  simulator device ID into Production. Square keeps the environments isolated,
  and Tuturuuu checks that the saved connection matches the selected
  environment.
</Warning>

## Safety contract

Tuturuuu provides these protections:

* Square settings and synchronization controls start in read-only mode.
* Checkout readiness fails closed when the connection, webhook key, location,
  or device is missing.
* Square catalog synchronization is additive and never deletes or archives
  Square catalog objects.
* Duplicate and out-of-order Square webhooks are reconciled idempotently.
* A reserved checkout expires after 15 minutes; cancellation, failure, and
  expiry release its stock.
* A Production charge requires a person to send a real order and a buyer to
  finish payment on the Terminal.

People still own these decisions:

* which Square seller, location, catalog records, and device belong to the
  workspace;
* whether a Production sync or payment is authorized;
* the amount, card, refund policy, and staff member for the first live test;
* business, banking, tax, tip, receipt, and hardware configuration in Square.

## Definition of fully working

Call the integration ready only when all of these are true:

1. Sandbox connection shows all five setup checks complete.
2. The Sandbox test matrix passes for success, cancel, timeout, and offline
   simulation, with stock changing exactly once in every path.
3. Catalog links are visible and have no unexplained conflict or error state.
4. Production uses its own OAuth connection, webhook subscription, location,
   and paired Terminal.
5. One owner-approved low-value Production sale matches in Tuturuuu, Square,
   the Terminal receipt, stock, and finance exactly once.
6. Counter staff know the stop-and-reconcile procedure for an uncertain payment.

For implementation details and automated coverage, use the
[Square Terminal engineering runbook](/build/devops/square-terminal-integration).


# Synchronize Square catalog and stock
Source: https://docs.tuturuuu.com/platform/applications/inventory-square-pos/catalog-sync

Import, publish, and compare products, variations, prices, and physical counts without deleting Square catalog objects.

Tuturuuu links an Inventory product/unit/warehouse combination to a Square item
variation at the selected Square location. The link stores both sides' last
known state so two-way sync can distinguish a safe one-sided change from a
conflict.

<Info>
  Synchronization controls are locked by default. Open **Payments → Catalog
  sync**, review the selected environment and linked records, then use the
  compact edit control to enable an intentional sync action.
</Info>

## Choose the right direction

```mermaid theme={null}
flowchart TD
  Q{"Where is the trusted change?"}
  Q -->|"Square only"| A["Import from Square"]
  Q -->|"Tuturuuu only"| B["Publish to Square"]
  Q -->|"Unsure or both systems are active"| C["Two-way sync"]
  C --> D{"Both sides changed the same link?"}
  D -->|"No"| E["Apply the one-sided change"]
  D -->|"Yes"| F["Pause as review conflict"]
```

| Action                 | Use it when                                                                  | Result                                                                                            |
| ---------------------- | ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
| **Import from Square** | Square is the current source of truth or this is the first Sandbox discovery | Imports items, variations, prices, and physical counts; creates or updates local links            |
| **Publish to Square**  | The approved change was made in Tuturuuu                                     | Batch-upserts Tuturuuu items and variations, then writes physical counts at the selected location |
| **Two-way sync**       | Staff use both systems or the source is uncertain                            | Applies safe one-sided changes and marks simultaneous edits for review                            |

<Warning>
  Confirm **Sandbox** or **Production** before every sync. A Production catalog
  sync changes the real seller catalog and inventory counts even though it does
  not charge a card.
</Warning>

## Non-destructive Square behavior

Tuturuuu deliberately does not call a Square catalog delete endpoint and does
not archive Square catalog objects as part of sync.

* Square-only variations remain attached when Tuturuuu updates a known item.
* A Square-side deletion marks the local link as **Square deletion preserved**
  for review; it does not delete the local product or stock.
* A simultaneous local and remote edit becomes **Review conflict**.
* A failed row stays visible as **Sync error** with its last error.
* Only records that the operator explicitly synchronizes are created or
  updated.

```mermaid theme={null}
flowchart LR
  Local["Tuturuuu product + unit + warehouse"] <-->|"link hashes"| Link["Catalog link"]
  Link <-->|"Square item variation"| Remote["Square catalog"]
  Remote -. "remote deletion" .-> Review["Preserve link and request review"]
  Review -. "never cascades" .-> Local
```

## What is synchronized

| Tuturuuu                     | Square                                        | Notes                                                                                                  |
| ---------------------------- | --------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
| Product name and description | Catalog item name and description             | Trimmed display data; review branding before Production publish                                        |
| Unit or sellable variant     | Item variation                                | One product can have several variation links                                                           |
| SKU                          | Variation SKU                                 | Use stable, unique SKUs where possible                                                                 |
| Price and currency           | Square Money amount and currency              | Exact sub-unit prices import directly, including USD 8.10 and three-decimal currencies such as BHD     |
| Warehouse stock row          | Physical inventory count at selected location | The chosen Square location is part of the routing context; Tuturuuu Inventory stores whole-unit counts |
| Link origin and last hashes  | Link metadata in Tuturuuu                     | Supports conflict detection and observability                                                          |

Do not manually multiply or divide prices before sync. Enter and review the
human-readable amount in Tuturuuu; the integration converts it to Square's
currency-aware integer Money representation. If USD 10.00 appears as USD 0.10
or USD 1,000.00, stop and investigate before another sync.

<Note>
  Tuturuuu Inventory stores major-unit prices with exact decimal precision and
  converts them to Square's currency-aware integer Money amount at the provider
  boundary. Physical stock remains whole-unit inventory. A fractional stock
  count is still held for review instead of rounded.
</Note>

<Accordion title="Why do older rows say Ready to retry?">
  Those links were imported before cent-level Inventory prices were supported.
  Square was not changed and the previous local price was preserved. Open
  **Manage sync**, choose **Import from Square**, and run one read-only import.
  Tuturuuu applies the exact Square price and clears the legacy hold.
</Accordion>

## Safe first synchronization

<Steps>
  <Step title="Verify the environment and location">
    Open **Payments → Connect & set up** and read the Square summary. Confirm the
    environment, seller connection, and location. Return to **Catalog sync** and
    confirm the same environment badge.
  </Step>

  <Step title="Start with one clearly labeled demo item">
    In Sandbox, use a unique demo name and SKU. In Production, use an owner-
    approved item and review its current Square record before any action.
  </Step>

  <Step title="Import from Square first">
    For a seller with an existing Square catalog, choose **Import from Square**.
    Review the summary and linked record list before publishing anything back.
  </Step>

  <Step title="Inspect every linked row">
    Match the Tuturuuu product, Square item and variation name, SKU, shortened
    variation ID, origin, status, and last synchronized date. A processed count
    is not proof; the visible linked row is the evidence.
  </Step>

  <Step title="Publish a controlled Tuturuuu change">
    Change one field on the demo record, then choose **Publish to Square**.
    Verify the exact field and physical count in the Square Dashboard.
  </Step>

  <Step title="Run two-way comparison">
    After both one-way directions work, choose **Two-way sync**. Review any
    conflict rather than repeatedly syncing until it disappears.
  </Step>
</Steps>

## Read the sync summary

| Metric                     | Meaning                                                         |
| -------------------------- | --------------------------------------------------------------- |
| Products processed         | Item-level records inspected or changed in the run              |
| Products created           | New Tuturuuu products created from Square                       |
| Variations changed         | Variation links imported or published                           |
| Stock rows changed         | Physical inventory counts imported or published                 |
| Needs review               | Simultaneous edits or records that require an operator decision |
| Square deletions preserved | Remote deletions detected without local deletion                |

Counts describe operations, not unique products. One imported product can update
both its variation and its physical stock row, so five linked products can
legitimately produce ten imported changes. Use the linked-record list to count
actual relationships.

## Link statuses

| Status                        | Meaning                                               | Safe next action                                                                                                  |
| ----------------------------- | ----------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| **Linked**                    | The last known states agree                           | No action unless a new business change is approved                                                                |
| **Ready to retry**            | A legacy import safely held a cent-level Square price | Run **Import from Square** once; Square remains read-only and the exact price is applied locally                  |
| **Review conflict**           | Both sides changed since the last shared state        | Compare Square and Tuturuuu, choose the authoritative value, then run one directional sync                        |
| **Sync error**                | A Square or validation request failed                 | Read the row error, fix credentials/data, and retry only that intended direction                                  |
| **Square deletion preserved** | The linked Square object is absent or deleted         | Ask the owner whether to recreate/publish or intentionally leave it disconnected; do not delete the local product |

## Webhook-driven updates

The webhook subscription includes:

* `catalog.version.updated`, which asks Tuturuuu to reconcile catalog changes;
* `inventory.count.updated`, which asks Tuturuuu to reconcile physical counts.

Square might not emit an inventory event when a count is written to the same
value it already had. To verify this path in Sandbox, change a demo count to a
different value and then restore it intentionally.

Webhooks can be duplicated or delivered out of order. A duplicate event should
not create a duplicate product, link, stock change, or checkout.

## Conflict-resolution worksheet

For each conflict, record:

```text theme={null}
Tuturuuu product and unit:
Square item and variation ID:
Environment and location:
Last synchronized at:
Tuturuuu name / SKU / price / count:
Square name / SKU / price / count:
Approved source of truth:
Approver:
One-way sync selected:
Final values verified in both systems:
```

Never solve a price or stock conflict by deleting the Square object. Preserve
the audit trail and apply one approved direction.

## Production catalog gate

Before enabling Production sync actions:

* the Square owner confirms the seller and location;
* Sandbox import, publish, two-way, and conflict tests pass;
* all demo names and SKUs are unmistakable;
* the visible price and currency match exactly on both sides;
* the physical count belongs to the selected location;
* every linked row is **Linked** or has a documented review decision;
* the operator understands that Production sync changes real catalog and stock
  data but never deletes Square objects.


# Set up the Square account and counter
Source: https://docs.tuturuuu.com/platform/applications/inventory-square-pos/customer-setup

A non-technical, role-based walkthrough for connecting a Square seller to Tuturuuu Inventory before accepting payments.

This guide prepares the Square account, Tuturuuu workspace, webhook, location,
and in-person hardware route. Start with the safe Sandbox checks even when the
store already owns a Square Terminal, Square Reader, or Tap to Pay device.

<Warning>
  Do not paste credentials, tokens, application secrets, or webhook signature
  keys into chat, tickets, or documents. Enter them only in the Square settings
  editor inside the intended Inventory workspace.
</Warning>

## Who should be present

| Role                          | Owns                                                                                                             | Does not need                                       |
| ----------------------------- | ---------------------------------------------------------------------------------------------------------------- | --------------------------------------------------- |
| **Square account owner**      | Seller authorization, business settings, locations, banking, taxes, tips, receipts, and approval for a live test | Tuturuuu engineering access                         |
| **Inventory workspace admin** | Payments setup, environment selection, catalog links, Storefront checkout mode, and transaction verification     | The owner's Square password after OAuth is approved |
| **Counter operator**          | POS app sign-in, Reader or Terminal connectivity, paper, and the controlled first sale                           | Developer Console access                            |
| **Technical helper**          | Square application, OAuth redirect, webhook subscription, and diagnosing rejected events                         | Permission to run a live charge                     |

One person can hold several roles, but the Square owner should explicitly approve
the Production seller, location, item, amount, and payment card.

```mermaid theme={null}
flowchart TD
  Owner["Square owner authorizes the seller"] --> Admin["Inventory admin saves the connection"]
  Helper["Technical helper configures OAuth and webhooks"] --> Admin
  Admin --> Choice{"Counter hardware"}
  Choice --> Reader["Phone / tablet + Reader: Square POS app"]
  Choice --> Terminal["Standalone Terminal: Terminal API pairing"]
  Reader --> Operator["Counter operator prepares the device"]
  Terminal --> Operator
  Operator --> Gate["Owner approves one controlled live sale"]
```

## Prepare the account and hardware

Have these items ready before opening the setup editor:

* a Square seller in a country and currency supported by Square;
* owner access to the [Square Developer Console](https://developer.squareup.com/apps);
* an Inventory workspace where you can manage Payments and Storefronts;
* a Square location dedicated to or clearly associated with this counter;
* either a phone or tablet with the latest Square POS app and a connected Square
  Reader/Tap to Pay, or a standalone Square Terminal with current software;
* reliable Wi-Fi or Ethernet without a browser-based captive portal;
* a clearly named Sandbox demo product with known price and stock;
* a clearly named, low-value Production test item for the later go-live check.

Review Square's official
[Terminal setup guide](https://squareup.com/help/us/en/article/6535-set-up-square-terminal)
and
[hardware network requirements](https://squareup.com/help/us/en/article/8348-set-up-network-requirements-for-square-hardware)
before the launch day when using standalone Terminal hardware. For a phone or
tablet, review Square's
[Point of Sale mobile web guide](https://developer.squareup.com/docs/pos-api/build-mobile-web).

## Choose the correct hardware path

Square exposes these devices through different APIs. Choosing the correct path
prevents the most common setup failure.

| What the customer has                                                  | Tuturuuu checkout mode      | Setup in Inventory                                                                                           | Does it appear under Refresh terminals?                  |
| ---------------------------------------------------------------------- | --------------------------- | ------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------- |
| Phone/tablet running Square POS with Bluetooth Reader or Tap to Pay    | **Square POS app + Reader** | Register the displayed POS callback URL, save the Production location, and open the Storefront on that phone | **No.** The phone's name and device ID are informational |
| Standalone Square Terminal or Square Handheld receiving remote prompts | **Square Terminal**         | Create a Tuturuuu Terminal API pairing code and save the paired device                                       | **Yes**                                                  |

<Info>
  A Square POS device ID such as a phone installation ID is not a Terminal API
  device ID. Do not paste it into the Terminal dropdown. Tuturuuu opens Square
  POS on the phone instead, then verifies the returned Square Order and card
  Payment before completing inventory.
</Info>

## Prepare event staff access

Do not share a full workspace administrator account at the counter. In
**Settings → Members & roles**, choose **Invite member**, then select **POS
operator — start payments only**.

The first limited POS invitation performs one confirmed, atomic access
migration:

1. every current workspace member receives the explicit **Workspace Admin
   (preserved)** role;
2. the member-wide default **Admin** permission is disabled so new members do
   not inherit it;
3. Tuturuuu creates a **POS Operator** role containing only **Start POS
   checkout**; and
4. the pending invitation records that role so it is assigned as soon as the
   invited person accepts.

The confirmation panel lists the number of current members being protected and
explains the resulting access. A POS operator can start an approved Square
payment, but cannot edit products, stock, sales, payment settings, members, or
roles.

For multiple standalone Terminals, staff choose the **Payment station** in the
Storefront checkout form. Tuturuuu validates that the selected device is a
paired Terminal API device at the configured selling location before it
reserves stock. Square POS App + Reader remains a same-device flow: open the
Storefront on the compatible phone or tablet that should launch Square POS.

<Warning>
  Never use a public shopper account as event staff. The checkout API enforces
  the POS permission server-side and rate-limits repeated dispatches; hiding the
  button is not the security boundary.
</Warning>

## Open the correct Tuturuuu workspace

1. Sign in to [Inventory](https://inventory.tuturuuu.com).
2. Select the customer's workspace.
3. Open **Payments** in the sidebar.
4. Stay on **Connect & set up**.
5. Choose **Square POS**.
6. Confirm the environment badge before changing anything.

The page shows five detected checks:

```mermaid theme={null}
flowchart LR
  A["Application"] --> B["Connection"] --> C["Webhook"] --> D["Location"] --> E["Device"]
```

Use the compact **Edit Square settings** button only when you are ready to
complete the next check. Stop editing afterward so accidental changes are less
likely.

## Fast handoff when Production is preconfigured

If a technical helper already prepared Production, do not paste or rotate the
credentials again. Keep the page read-only and verify these visible facts with
the Square account owner:

* the environment is **Production**;
* the masked connection and webhook checks are complete;
* the location is the real owner-approved selling location;
* **Catalog sync** shows the expected Production links and no unexplained
  conflicts;
* the intended hardware path is clear. A phone/Reader path does not require a
  Terminal API device or Terminal webhook key; a standalone Terminal does.

The customer can then skip credential entry and continue directly to the
[Production hardware path](/platform/applications/inventory-square-pos/production-launch#choose-the-production-hardware-path).
The owner still needs to confirm business, bank, tax, tip, and receipt settings
inside Square. Tuturuuu cannot safely choose those business settings on the
customer's behalf.

## Part 1: configure Sandbox

<Steps>
  <Step title="Create or select the Square application">
    Open the [Square Developer Console](https://developer.squareup.com/apps),
    create an application for the Tuturuuu integration, and keep the environment
    toggle on **Sandbox**. Use a recognizable name such as `Tuturuuu Sandbox`.

    In Inventory, choose **Sandbox**, enable editing, and copy the Sandbox
    Application ID and Application secret into **Square app credentials**.
    Save them before starting OAuth.
  </Step>

  <Step title="Register the OAuth redirect URL">
    Copy the **OAuth redirect URL** displayed by Inventory. In the Square
    application's Sandbox OAuth settings, add that exact HTTPS URL as an
    authorized redirect.

    Do not type the URL from memory. The scheme, domain, path, and trailing
    characters must match what Inventory displays.
  </Step>

  <Step title="Authorize the Sandbox seller">
    Choose **Connect OAuth** in Inventory. Sign in to or select the intended
    Sandbox test seller and approve the requested permissions. Return to
    Inventory and confirm the read-only connection summary shows a token ending
    in four characters.

    OAuth is preferred because the connection can refresh and the seller can
    revoke it. A manual Sandbox token is available for a controlled rehearsal,
    but it must still belong to the same application and environment.
  </Step>

  <Step title="Create the Sandbox webhook subscription">
    Copy the **Webhook notification URL** shown in Inventory. In the Square
    application's **Webhooks** section, create a Sandbox subscription with that
    exact URL and these seven events:

    * `device.code.paired`
    * `terminal.checkout.created`
    * `terminal.checkout.updated`
    * `payment.updated`
    * `oauth.authorization.revoked`
    * `catalog.version.updated`
    * `inventory.count.updated`

    Copy the subscription's signature key into Inventory and save. Send a Square
    test event and confirm its delivery returns a `2xx` response. Square can
    deliver the same event more than once, so duplicate delivery is expected and
    handled idempotently.
  </Step>

  <Step title="Select the Sandbox location">
    Refresh locations in Inventory and choose the test location owned by the
    Sandbox seller. Confirm its country and currency match the rehearsal.
    Catalog stock counts are associated with this selected Square location.
  </Step>

  <Step title="Select a Sandbox simulator device">
    Square Sandbox cannot pair real hardware through the Devices API. Paste a
    supported Terminal simulator device ID into the Sandbox device field and
    save it as the default. Start with the success simulator from Square's
    [current Sandbox test values](https://developer.squareup.com/docs/devtools/sandbox/testing#terminal-api-checkouts).
  </Step>
</Steps>

<Check>
  The Sandbox guide should now show **5/5 checks complete**. Continue with the
  [Sandbox test plan](/platform/applications/inventory-square-pos/sandbox-testing)
  before creating any Production connection.
</Check>

## OAuth permissions

Tuturuuu requests only the permissions needed for the Terminal, orders,
payments, catalog, and inventory workflows:

| Workflow            | Square permissions                                      |
| ------------------- | ------------------------------------------------------- |
| Seller and Terminal | `MERCHANT_PROFILE_READ`, `DEVICE_CREDENTIAL_MANAGEMENT` |
| Orders              | `ORDERS_READ`, `ORDERS_WRITE`                           |
| Payments            | `PAYMENTS_READ`, `PAYMENTS_WRITE`                       |
| Catalog             | `ITEMS_READ`, `ITEMS_WRITE`                             |
| Inventory counts    | `INVENTORY_READ`, `INVENTORY_WRITE`                     |

If the customer declines a required permission, the corresponding readiness
check or API action fails closed. Re-authorize the correct seller instead of
adding a second unrelated token.

## Part 2: create a separate Production connection

Do this only after Sandbox exit criteria pass.

<Steps>
  <Step title="Switch both systems to Production">
    In Square Developer Console, switch the application to **Production**. In
    Inventory, switch the Square setup guide to **Production**. Verify both
    environment labels before copying anything.
  </Step>

  <Step title="Repeat credentials, OAuth, and webhook setup">
    Save the Production Application ID and secret, register the Production OAuth
    redirect URL, authorize the real seller, and create a separate Production
    webhook subscription using the URL shown in Inventory. Save the Production
    signature key. Never reuse a Sandbox credential or key.
  </Step>

  <Step title="Choose the real selling location">
    Select the Square location that owns the counter, currency, receipts, tax,
    and reporting. Ask the Square owner to verify the location name before
    saving.
  </Step>

  <Step title="Prepare the in-person hardware">
    For Square POS app + Reader, install or update Square POS, sign in to the
    selected location, and connect the Reader or enable Tap to Pay. For a
    standalone Terminal, power it, install updates, load paper, and connect to
    the final counter network. Continue with the matching Production path.
  </Step>
</Steps>

## Connection review

Before pairing, the read-only Production summary should show:

| Field                | Expected                                                                               |
| -------------------- | -------------------------------------------------------------------------------------- |
| Environment          | Production                                                                             |
| Connection           | Token ending in four characters                                                        |
| Square application   | The Production Application ID                                                          |
| Location             | The owner-approved counter location                                                    |
| In-person device     | POS app/Reader needs no Terminal ID; standalone Terminal is unconfigured until pairing |
| Webhook verification | Signature key ending in four characters                                                |

If any row is unexpected, stop and correct it before creating a device code.
Continue with the
[Production launch guide](/platform/applications/inventory-square-pos/production-launch).

## Official Square references

* [Square Sandbox overview](https://developer.squareup.com/docs/devtools/sandbox/overview)
* [OAuth API overview](https://developer.squareup.com/docs/oauth-api/overview)
* [Square webhooks overview](https://developer.squareup.com/docs/webhooks/overview)
* [Connect Square Terminal to a POS application](https://developer.squareup.com/docs/terminal-api/integrate-square-terminal)
* [Build a Point of Sale mobile web integration](https://developer.squareup.com/docs/pos-api/build-mobile-web)
* [Point of Sale mobile web technical reference](https://developer.squareup.com/docs/pos-api/web-technical-reference)
* [Square hardware network requirements](https://squareup.com/help/us/en/article/8348-set-up-network-requirements-for-square-hardware)


# Operate and verify Square payments
Source: https://docs.tuturuuu.com/platform/applications/inventory-square-pos/operations

Use the Inventory Payments hub to monitor readiness, catalog links, transactions, reservations, and safe reconciliation.

The Payments hub is the customer's control center for Square and Polar. It
combines provider readiness, catalog-link observability, and recent transaction
evidence without exposing secret values.

Open:

```text theme={null}
https://inventory.tuturuuu.com/<workspace-id>/payments
```

## Read the overview first

```mermaid theme={null}
flowchart LR
  A["Readiness score and next action"] --> B["Square links"]
  B --> C["Square tests"]
  C --> D["Verified webhook configurations"]
  D --> E["Connect & set up"]
  D --> F["Catalog sync"]
  D --> G["Test & verify"]
```

| Overview signal   | What it means                                             | What it does not mean                                                           |
| ----------------- | --------------------------------------------------------- | ------------------------------------------------------------------------------- |
| Square links      | Visible Tuturuuu-to-Square variation links                | Every linked value is correct; inspect status and values                        |
| Square tests      | Recent checkouts have Square status evidence              | The physical Production Terminal is certified                                   |
| Verified webhooks | A Square connection has a saved signature key             | Every Square delivery succeeded; check Square delivery history during incidents |
| Readiness score   | The detected setup and test prerequisites are progressing | The owner has approved a Production charge                                      |

## Connect & set up

The settings summary is intentionally read-only. It displays the environment,
masked connection, application, location, default device, and masked webhook
signature state.

Use **Edit Square settings** only to perform an approved change. Tuturuuu opens
a focused dialog with **App & OAuth**, **Connection & webhook**, and **Location
& terminal** tabs. Before saving, read the environment label again. Close the
dialog and verify the read-only summary after every change. Each incomplete
setup accordion also opens the exact tab required for that step.

The five setup checks are:

1. Square application credentials, or a ready manual connection.
2. A ready OAuth or manual token connection.
3. A saved webhook signature key.
4. A selected Square location.
5. A Sandbox simulator ID or Production paired device.

Readiness fails closed when a required check is missing.

## Catalog sync

The catalog panel shows:

* selected Square environment;
* last run status and time;
* products, variations, stock, conflict, and preservation metrics;
* every visible linked variation, including its Tuturuuu product, Square item,
  variation, SKU, shortened variation ID, origin, state, and last sync date;
* row-specific errors when a link cannot synchronize.

Sync actions remain locked until an operator chooses **Enable sync actions**.
See [Catalog and stock synchronization](/platform/applications/inventory-square-pos/catalog-sync)
before running a Production action.

## Test & verify

Each recent provider row shows the customer or public order reference, provider,
environment, provider status, observed time, amount, failure reason when
available, and a receipt link when Square supplies one.

The transaction view intentionally mixes Square and Polar evidence so a seller
can verify all payment providers in one place. Use the provider badge and
environment label before interpreting a status.

## Checkout and stock lifecycle

```mermaid theme={null}
flowchart TD
  Cart["Cart submitted"] --> Reserve["Local checkout reserved for 15 minutes"]
  Reserve --> Dispatch["Square order and Terminal checkout created"]
  Dispatch --> Pending["Terminal checkout pending"]
  Pending --> Paid["Verified Square payment"]
  Pending --> Cancel["Buyer or operator cancels"]
  Pending --> Fail["Square failure"]
  Pending --> Expire["Terminal or local expiry"]
  Paid --> Consume["Reservation consumed, stock reduced once, sale booked once"]
  Cancel --> Release["Reservation released, no sale"]
  Fail --> Release
  Expire --> Release
```

| State                       | Operator interpretation                                                | Stock behavior                                          |
| --------------------------- | ---------------------------------------------------------------------- | ------------------------------------------------------- |
| Reserved                    | Tuturuuu is holding sellable quantity while checkout starts            | Available stock is temporarily reduced                  |
| Pending                     | Square has not produced a final result                                 | Keep the reservation; do not create a replacement order |
| Cancel requested            | Square accepted cancellation but a final webhook may still be arriving | Wait and reconcile the same checkout                    |
| Completed / paid            | A verified Square payment completed                                    | Reservation is consumed and stock changes once          |
| Canceled / failed / expired | No successful sale should be booked                                    | Reservation releases and stock returns once             |

Checkout reads, new checkout creation, and the scheduled expiry sweep reconcile
stale 15-minute reservations. Operators can also cancel an eligible Square
checkout from the Inventory Commerce surface.

## Transaction reconciliation

Use this procedure whenever the customer or operator is unsure whether a payment
finished:

<Steps>
  <Step title="Stop new attempts">
    Do not resend, reload into a new order, accept a second card, or manually
    restore stock. Preserve the current checkout for investigation.
  </Step>

  <Step title="Read Tuturuuu evidence">
    Note the public order reference, provider, environment, status, observed
    time, total, failure reason, and receipt link. Record the current stock and
    reservation state.
  </Step>

  <Step title="Read Square evidence">
    In the matching Sandbox or Production Square Dashboard, search the same
    time, location, amount, and receipt. Determine whether a payment was
    completed, canceled, or absent.
  </Step>

  <Step title="Check webhook delivery">
    In Square Developer Console, inspect the matching environment's webhook
    delivery. A successful delivery receives `2xx`. A duplicate delivery is
    acceptable; different final business state is not.
  </Step>

  <Step title="Choose one final path">
    If Square shows a completed payment, reconcile that payment and do not retry.
    If Square proves no payment and the checkout is pending, cancel it or allow
    it to expire. Verify stock after the final status arrives.
  </Step>
</Steps>

## Duplicate and out-of-order webhooks

Square may deliver the same webhook more than once and may deliver related
events out of order. Tuturuuu verifies the signature against the exact webhook
URL and raw request body, stores provider identifiers, and reconciles the event
idempotently.

A healthy duplicate-delivery result looks like this:

| Evidence                                                | Expected count |
| ------------------------------------------------------- | -------------- |
| Square webhook delivery rows                            | One or more    |
| Tuturuuu checkout                                       | One            |
| Square order / Terminal checkout / payment linked to it | One each       |
| Completion transition                                   | One            |
| Stock consumption or release                            | One            |
| Finance sale                                            | At most one    |

## Opening, daily, and weekly checks

### Before opening the counter

* Terminal is online, charged, updated, and has paper.
* Payments shows the intended Production seller, location, and default device.
* The latest Production webhook test or recent delivery is healthy.
* No prior checkout is pending or uncertain.
* High-risk catalog links have no conflict, error, or remote-deleted state.
* The operator knows who owns refunds and incident escalation.

### During the day

* Submit each order once.
* Match the Terminal amount before the buyer taps a card.
* Stop after any uncertain result; reconcile before another attempt.
* Use Square's normal receipt and refund process.
* Never change Production environment, location, or device during an active
  checkout.

### End of day

* Compare completed Tuturuuu Square rows with Square Payments for the location.
* Investigate pending, canceled, failed, and expired rows.
* Compare sold quantities with Inventory stock and reservations.
* Confirm finance entries are not duplicated.
* Record any refund or chargeback workflow separately.

### Weekly

* Review OAuth connection health and Square authorization status.
* Check webhook delivery failures and retries.
* Review catalog conflict, error, and remote-deleted links.
* Confirm the selected Terminal and location still match the counter.
* Re-run Sandbox regression tests after material app, catalog, or workflow
  changes.

## Escalation packet

Send support this information without secrets:

```text theme={null}
Workspace name and ID:
Sandbox or Production:
Square seller and location name:
Terminal name:
Tuturuuu order reference:
Date, time, and timezone:
Amount and currency:
Tuturuuu status and failure reason:
Square payment status and receipt URL, if present:
Webhook event type, event ID, response code, and retry number:
Stock before and after:
Actions already taken:
Screenshot with tokens and customer PII redacted:
```

For symptom-specific recovery, continue to
[Troubleshooting Square POS](/platform/applications/inventory-square-pos/troubleshooting).


# Launch Square POS or a physical Terminal
Source: https://docs.tuturuuu.com/platform/applications/inventory-square-pos/production-launch

Configure the correct Production hardware path, run one owner-approved card-present sale, and decide whether the counter is ready.

Production launch is the only part of this guide that can move real money. It
requires the Square account owner, an Inventory workspace admin, the intended
Square hardware, and the counter operator to work through the same checklist.

<Warning>
  A Production payment can incur Square processing fees. Get explicit approval
  for the seller, location, item, amount, card, operator, and refund owner before
  creating the checkout. Tuturuuu never runs this test automatically.
</Warning>

## Launch gates

```mermaid theme={null}
flowchart LR
  A["Sandbox exit criteria"] --> B["Production 4/5 preconfiguration"]
  B --> C{"Hardware path ready"}
  C -->|"Phone + Reader"| C1["POS callback registered"]
  C -->|"Standalone Terminal"| C2["Terminal paired: 5/5"]
  C1 --> D["Catalog, price, tax, stock reviewed"]
  C2 --> D
  C --> D["Catalog, price, tax, stock reviewed"]
  D --> E["Owner approves one live sale"]
  E --> F["Payment, receipt, stock, finance match"]
  F --> G["Open the counter"]
```

Do not skip a gate because the Sandbox test passed. Sandbox cannot prove the
real seller, physical device, counter network, or receipt behavior.

## Preflight checklist

### Square owner

* [ ] Legal business and bank details are complete in Square.
* [ ] The intended selling location, currency, taxes, tips, and receipt settings
  are correct.
* [ ] The Square application is in Production and authorizes this seller.
* [ ] The owner approves one clearly named low-value test item and exact amount.
* [ ] The owner decides whether and how the test will be refunded afterward.

### Inventory admin

* [ ] The Payments page shows **Production**.
* [ ] Application, connection, webhook, and location checks are complete.
* [ ] The selected location matches the owner's intended counter.
* [ ] The Production webhook has the required seven events and its test delivery
  returns `2xx`.
* [ ] Catalog links, price, currency, tax, and stock are reviewed.
* [ ] The intended Storefront uses **Square POS app + Reader** or **Square Terminal**, matching the physical hardware.

### Counter operator

* [ ] The phone/Reader or standalone Terminal is powered, charged, updated, and ready for receipts.
* [ ] Wi-Fi or Ethernet is stable and does not require a browser sign-in page.
* [ ] A backup connection and Square login are available if the network fails.
* [ ] The operator knows not to retry an uncertain payment.

## Choose the Production hardware path

<Tabs>
  <Tab title="Phone or tablet + Reader">
    Use this path for the customer's Square POS app, Bluetooth/contactless and
    chip Reader, or Tap to Pay. The phone never appears in **Refresh terminals**.

    <Steps>
      <Step title="Select Phone or tablet with Reader">
        Open **Payments → Connect & set up → Square POS → Edit Square settings →
        Hardware & POS**, choose **Production**, then select **Phone or tablet
        with Reader**.
      </Step>

      <Step title="Save the selling location">
        Select the same Production location currently signed in on Square POS.
        A location mismatch is rejected by Square and by Tuturuuu verification.
      </Step>

      <Step title="Register the exact callback URL">
        Copy the read-only callback URL from Inventory. In
        [Square Developer Console](https://developer.squareup.com/apps), open the
        Production application, choose **Point of Sale API**, paste it into
        **Web Callback URL**, and save. Do not add, remove, or infer a trailing
        slash.
      </Step>

      <Step title="Prepare Square POS">
        Install or update Square POS on the phone, sign in to the saved location,
        and connect the Reader or enable Tap to Pay. The displayed phone name and
        Square device ID are only support evidence; they are not entered into
        Tuturuuu Terminal routing.
      </Step>

      <Step title="Enable the Storefront">
        Set the Storefront checkout mode to **Square POS app + Reader**. Open the
        Storefront on that same phone. When submitted, Tuturuuu opens Square POS
        with the exact minor-unit amount and card tender selected.
      </Step>
    </Steps>

    Tuturuuu accepts the callback only when its random request state matches the
    reserved order. It then retrieves the returned Square Order and Payment and
    verifies completed status, card tender, location, currency, and exact amount
    before consuming stock. Cancellation releases the reservation. A missing or
    unverifiable online transaction ID stays in review and never reduces stock.
  </Tab>

  <Tab title="Standalone Square Terminal">
    Use this path only for a Terminal or Handheld that receives a remote
    Terminal API checkout prompt.

    ## Pair the physical Terminal

    <Steps>
      <Step title="Open the Production setup">
        In the correct workspace, open **Payments → Connect & set up → Square POS**
        and select **Production**. Choose **Edit Square settings**, then open
        **Location & terminal**. The dialog separates physical Production pairing
        from the Sandbox simulator route and presents the four pairing steps in
        order.
      </Step>

      <Step title="Choose the location and name the counter">
        In step 1, choose the Square location that will receive this counter's
        in-person payments. In step 2, use a durable name such as `Front counter`,
        `Convention booth A`, or `Warehouse pickup`.

        The name should tell support which physical Terminal is receiving an order.
      </Step>

      <Step title="Create the pairing code in Tuturuuu">
        Choose **Create pairing code**. Tuturuuu asks Square's Devices API for a code
        with product type `TERMINAL_API` at the selected location.

        <Warning>
          Do not create a generic device code in Square Dashboard. Dashboard codes
          are not compatible with Terminal API Connected Mode.
        </Warning>
      </Step>

      <Step title="Enter the code on the Terminal">
        Tuturuuu displays the code and its exact expiry. On the physical Terminal
        sign-in screen, choose **Use a device code**, then enter the code before it
        expires. If it expires, generate a new code in Tuturuuu; do not keep
        retrying the old one.
      </Step>

      <Step title="Wait for paired status">
        Square sends `device.code.paired`. In step 4, choose **Refresh terminals**,
        select the newly paired Terminal, and choose **Save as default terminal**.
        The Production setup should now show **5/5 checks complete**.
      </Step>
    </Steps>
  </Tab>
</Tabs>

Square's official pairing sequence is documented in
[Connect a Square Terminal to a POS application](https://developer.squareup.com/docs/terminal-api/integrate-square-terminal).

## Activate the selling path

1. In **Settings → Members & roles**, invite each counter volunteer as **POS
   operator — start payments only**. Confirm the one-time preservation of
   existing member Admin access before sending the first limited invitation.
2. Open **Storefronts** in Inventory and select the intended storefront.
3. Confirm it belongs to the same workspace as the Square connection.
4. Select the checkout mode matching the hardware: **Square POS app + Reader**
   on the same phone, or **Square Terminal** for the paired standalone device.
5. Publish only the approved listings and bundles.
6. Place one non-payment test cart and verify the name, variant, quantity, tax,
   discount, currency, and total.
7. Keep **Payments → Test & verify**, Square Payments, and the physical Terminal
   visible during the first sale.

For standalone Terminal, the signed-in operator chooses the intended payment
station and Tuturuuu verifies its pairing and location before reserving stock
and dispatching a Square Order and Terminal checkout. For POS app + Reader,
Tuturuuu reserves stock, opens the Square POS app on the same compatible device,
and verifies the returned provider records before completion.
Never create a replacement order until the existing one is reconciled.

## Run one controlled live sale

<Steps>
  <Step title="Read the approval aloud">
    Confirm the seller, location, item, quantity, amount, currency, card owner,
    operator, and refund decision. Stop if any detail differs from the owner's
    approval.
  </Step>

  <Step title="Record the starting evidence">
    Write down the product's available stock, the Tuturuuu time, and the
    intended total. Open Square Payments before submitting the checkout.
  </Step>

  <Step title="Submit exactly once">
    Submit the Storefront checkout once. Wait for the itemized request on the
    selected Terminal. Do not double-click, reload into another order, or send a
    second request while the status is pending.
  </Step>

  <Step title="Complete the card-present payment">
    Use the owner-approved card and follow the Terminal prompts. Capture the
    printed or digital receipt according to the store's policy.
  </Step>

  <Step title="Match both systems">
    Compare the amount, currency, location, status, Square order ID, Terminal
    checkout ID, payment ID, and receipt evidence in Tuturuuu and Square.
  </Step>

  <Step title="Verify stock and finance exactly once">
    The checkout should be completed, its reservation consumed, available stock
    reduced once, and the finance sale recorded at most once. A duplicate
    webhook delivery must not repeat any of those changes.
  </Step>

  <Step title="Apply the approved refund decision">
    If the owner planned to reverse the test, use the store's normal approved
    Square refund process and reconcile the refund in both systems. Do not make
    a second charge to offset an uncertain first charge.
  </Step>
</Steps>

## First-sale evidence

| Evidence          | Pass condition                                                                                     |
| ----------------- | -------------------------------------------------------------------------------------------------- |
| Tuturuuu checkout | One completed checkout for the approved cart                                                       |
| Square order      | One order with the matching items, tax, currency, and total                                        |
| Hardware evidence | One completed POS app order/payment, or one completed Terminal checkout, for the approved location |
| Square payment    | One completed payment for the exact amount                                                         |
| Receipt           | Printed or digital receipt matches the payment and location                                        |
| Inventory         | Reservation consumed and on-hand changed once                                                      |
| Finance           | One sale entry when finance booking is configured                                                  |
| Webhooks          | Signed deliveries accepted; duplicates cause no duplicate state                                    |

## Go/no-go decision

```mermaid theme={null}
flowchart TD
  A{"Do all eight evidence rows match?"}
  A -->|"Yes"| B["Mark the counter ready"]
  A -->|"No"| C["Stop new Square orders"]
  C --> D["Reconcile the existing checkout"]
  D --> E{"Was money captured?"}
  E -->|"Yes or uncertain"| F["Use Square payment evidence; do not retry"]
  E -->|"No"| G["Cancel or allow the checkout to expire"]
  F --> H["Escalate with IDs and timestamps"]
  G --> H
```

The counter is **no-go** when any of these are true:

* the Production environment or seller is uncertain;
* the location, device, price, currency, or tax is wrong;
* the webhook test is not accepted;
* the Terminal is offline or shows a different account;
* the prior checkout is still pending or its payment result is unknown;
* stock or finance changed more than once;
* staff do not know who owns reconciliation and refunds.

Follow the
[troubleshooting guide](/platform/applications/inventory-square-pos/troubleshooting)
before accepting another order.

## Counter handoff message

Copy this into the customer's Discord channel and replace the brackets:

```text theme={null}
Square Terminal launch handoff

Workspace: [workspace name]
Square seller and location: [seller / location]
Physical Terminal: [counter name]
Launch owner: [name]
Counter operator: [name]

Completed:
- Sandbox 5/5 setup checks
- Success, cancel, timeout, offline, expiry, and duplicate-webhook tests
- Catalog links and stock reviewed with no unexplained conflicts
- Production OAuth, webhook, location, and Terminal pairing

Customer action:
1. Confirm business, bank, tax, tip, receipt, and location settings in Square.
2. Approve one low-value item, exact amount, card, operator, and refund plan.
3. Keep Tuturuuu Payments and Square Payments open.
4. Submit the checkout once and complete it on the paired Terminal.
5. Reply with the Tuturuuu checkout ID, Square payment ID, amount, status, receipt result, stock result, and any error.

Safety rule: if the status is pending or uncertain, do not retry. Stop and reconcile the existing checkout first.
```

After launch, give counter staff the
[operations and verification guide](/platform/applications/inventory-square-pos/operations).


# Rehearse Square Terminal in Sandbox
Source: https://docs.tuturuuu.com/platform/applications/inventory-square-pos/sandbox-testing

A complete, no-money test plan for connection, catalog, checkout, webhook, stock, cancellation, timeout, and offline behavior.

Square Sandbox simulates Terminal API checkouts without a physical Terminal or
real card. Use it to prove the workflow and failure recovery before any
Production credential is saved.

<Info>
  Square hardware cannot be paired to Sandbox. Tuturuuu uses Square's special
  Sandbox Terminal device IDs to produce deterministic results. Sandbox
  payments do not reach a bank and do not incur processing fees.
</Info>

## What Sandbox can and cannot prove

| Sandbox proves                                                                                                                                          | Sandbox does not prove                                                                                                  |
| ------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| Credentials, scopes, environment routing, Orders API, Terminal checkout payloads, webhook signatures, idempotency, catalog links, and stock transitions | The customer's physical Terminal, counter network, receipt printer, real seller configuration, or card-present approval |
| Success, buyer cancellation, Square timeout, and an unresponsive Terminal simulation                                                                    | A live refund, physical receipt, or bank settlement                                                                     |
| Isolation from Production data and money                                                                                                                | That Production credentials or object IDs are correct                                                                   |

## Create isolated demo data

Use records that are unmistakably temporary and owned by the test:

```text theme={null}
Product: [Tuturuuu Sandbox] Terminal checkout test YYYY-MM-DD
SKU: TTR-SBX-YYYYMMDD
Price: USD 1.00
Opening stock: 4
```

Use a fictional customer name and email, or omit customer details. Square warns
against storing personal information in Sandbox. Do not reuse a real customer's
name, phone number, address, or card data.

<Warning>
  Do not delete or archive pre-existing Square records. Import or modify only
  the clearly labeled demo item. Tuturuuu catalog sync never deletes Square
  objects; any later manual cleanup in Square requires the account owner's
  separate approval.
</Warning>

## Simulator device IDs

Copy these from Square's current
[Terminal API Sandbox test values](https://developer.squareup.com/docs/devtools/sandbox/testing#terminal-api-checkouts)
into the **Sandbox device ID** field one scenario at a time:

| Scenario             | Device ID                              | Square result                                                |
| -------------------- | -------------------------------------- | ------------------------------------------------------------ |
| Approved card        | `9fa747a2-25ff-48ee-b078-04381f7c828f` | Completes a card payment up to USD 25                        |
| Buyer cancels        | `841100b9-ee60-4537-9bcf-e30b2ba5e215` | Reports a canceled checkout                                  |
| Square timeout       | `0a956d49-619a-4530-8e5e-8eac603ffc5e` | Immediately simulates checkout timeout                       |
| Terminal unavailable | `da40d603-c2ea-4a65-8cfd-f42e36dab0c7` | Leaves the request unclaimed so it can be canceled or expire |

Keep the test total at or below USD 25 for the standard success simulator.
Square deliberately leaves larger attempts pending rather than treating them as
an ordinary approval.

## Test flow

```mermaid theme={null}
flowchart TD
  A["Save one simulator device ID"] --> B["Create one demo checkout"]
  B --> C["Observe Square Sandbox"]
  C --> D["Observe Payments > Test & verify"]
  D --> E["Verify reservation and stock"]
  E --> F{"Result matches the test matrix?"}
  F -->|"Yes"| G["Record evidence and continue"]
  F -->|"No"| H["Stop, reconcile, and troubleshoot"]
```

For every scenario:

1. Open **Payments → Connect & set up → Square POS → Sandbox** and save the
   intended simulator ID.
2. Confirm all five Sandbox checks are complete.
3. Confirm the demo Storefront uses **Square Terminal** checkout.
4. Open **Payments → Test & verify** in one tab and the Sandbox Square Dashboard
   in another.
5. Submit one checkout only. Do not double-click or start a second checkout
   while the first is pending.
6. Match the checkout ID, amount, currency, status, and timestamps across both
   systems.
7. Record the final stock and reservation result before changing the simulator.

## Required checkout matrix

| Test                     | Expected Square evidence                           | Expected Tuturuuu evidence                                                                                 | Expected stock                                         |
| ------------------------ | -------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | ------------------------------------------------------ |
| **Approved card**        | One completed Terminal checkout and payment        | One completed checkout with Square order, Terminal checkout, payment, and receipt reference when available | Reservation consumed once; on-hand decreases once      |
| **Buyer cancels**        | Terminal checkout becomes canceled                 | Checkout becomes canceled or released with the Square result recorded                                      | Reservation released; available stock returns once     |
| **Square timeout**       | Terminal checkout reports timed out                | Checkout becomes expired/failed and is not recorded as paid                                                | Reservation released; no sale ledger entry             |
| **Terminal unavailable** | Checkout stays pending until canceled or timed out | The same checkout remains traceable; operator can cancel rather than resend                                | Stock stays reserved while pending, then releases once |

<Warning>
  A pending result is not permission to send the order again. First cancel or
  reconcile the existing Terminal checkout. Re-sending an uncertain order can
  create a second payment request.
</Warning>

## Reservation expiry test

Tuturuuu checkout reservations expire 15 minutes after creation. Expiry is
materialized by the scheduled sweep and also reconciled during checkout reads
and new checkout creation.

1. Use the unavailable Terminal simulator.
2. Create one checkout and verify the item becomes reserved.
3. Do not create a replacement checkout.
4. Cancel it through the Inventory Commerce action for a fast test, or allow the
   reservation to expire for the full expiry-path test.
5. Verify the checkout is no longer sellable as pending, the reservation is
   released, and stock returns exactly once.

## Duplicate webhook test

Square can retry webhooks and does not guarantee delivery order. Tuturuuu uses
Square event IDs and provider identifiers to reconcile duplicates safely.

<Steps>
  <Step title="Complete one successful Sandbox checkout">
    Record its Tuturuuu checkout ID, Square Terminal checkout ID, payment ID,
    stock before and after, and finance transaction if the workspace records
    one.
  </Step>

  <Step title="Resend a Square webhook delivery">
    In the Square Developer Console, open the relevant Sandbox webhook delivery
    and resend it once. Use the same event; do not create a second payment.
  </Step>

  <Step title="Verify idempotency">
    The webhook may appear twice in delivery history, but Tuturuuu must still
    show one checkout, one payment link, one completion transition, one stock
    change, and at most one finance sale.
  </Step>
</Steps>

## Catalog and stock rehearsal

Run this after the checkout matrix so the payment flow and catalog flow can be
diagnosed separately.

1. Open **Payments → Catalog sync**.
2. Enable sync actions with the compact edit control.
3. Choose **Import from Square** and verify the demo item appears as one linked
   Square variation.
4. Change only the demo item's name, price, or physical count on one side.
5. Run the matching one-way sync and verify the other side once.
6. Make different changes on both sides, run **Two-way sync**, and confirm the
   item becomes a review conflict instead of silently overwriting either side.
7. Restore the demo item through an intentional one-way sync after deciding
   which side is authoritative.

An unchanged Square inventory count might not emit an
`inventory.count.updated` event. Use an actual demo count change when validating
that webhook, then restore the count deliberately.

For the full data model and conflict rules, see
[Catalog and stock synchronization](/platform/applications/inventory-square-pos/catalog-sync).

## Exit criteria

Sandbox is complete only when:

* all five connection checks are ready;
* the seven webhook events are subscribed and a test delivery returns `2xx`;
* approved, canceled, timed-out, and unavailable-device scenarios match the
  matrix;
* duplicate webhook delivery does not duplicate payment, stock, or finance;
* a 15-minute or explicitly canceled reservation releases correctly;
* the demo catalog item is visible as a linked variation;
* a two-sided edit becomes a review conflict;
* no Production token, object, device, or payment was touched.

## Test evidence template

```text theme={null}
Workspace:
Square application and Sandbox seller:
Square location:
Tuturuuu demo product and SKU:
Test date and operator:

Approved checkout ID / payment ID / result:
Canceled checkout ID / result:
Timed-out checkout ID / result:
Unavailable checkout ID / cancel-or-expiry result:
Duplicate webhook event ID / final record count:

Stock before:
Stock after successful payment:
Stock after cancel, timeout, and expiry:
Catalog link count:
Conflicts requiring review:
Unexpected errors:
```

When every exit criterion passes, continue with
[Production launch](/platform/applications/inventory-square-pos/production-launch).


# Troubleshoot Square POS safely
Source: https://docs.tuturuuu.com/platform/applications/inventory-square-pos/troubleshooting

Diagnose connection, webhook, catalog, Terminal, checkout, and stock problems without deleting data or risking duplicate charges.

The first rule is simple: if a Production payment is pending or uncertain, do
not send it again. Reconcile the existing checkout before changing settings,
stock, device, or Storefront configuration.

## Start here

```mermaid theme={null}
flowchart TD
  A{"Was this Production?"}
  A -->|"No, Sandbox"| B["Record simulator ID and expected scenario"]
  A -->|"Yes"| C["Stop new payment attempts"]
  B --> D{"Is Square setup 5/5?"}
  C --> E{"Does Square show a completed payment?"}
  D -->|"No"| F["Fix the first incomplete setup check"]
  D -->|"Yes"| G["Inspect Square and Tuturuuu status"]
  E -->|"Yes"| H["Reconcile that payment; do not retry"]
  E -->|"No"| I{"Is the Terminal checkout pending?"}
  E -->|"Uncertain"| J["Inspect Square payment and webhook evidence"]
  I -->|"Yes"| K["Cancel or let the same checkout expire"]
  I -->|"No"| L["Verify reservation release and stock"]
  J --> H
  J --> K
```

## Five-minute operator triage

1. Record the workspace, environment, location, Terminal name, order reference,
   time, timezone, amount, currency, and visible status.
2. Stop submitting new checkouts for the affected order.
3. Compare **Payments → Test & verify** with the matching Square Dashboard.
4. If Square shows a completed payment, treat it as paid and reconcile it.
5. If Square proves no payment and the Terminal checkout is pending, cancel the
   same checkout or allow it to expire.
6. Verify the reservation and stock after the final event.
7. Escalate with IDs, timestamps, and redacted screenshots if the systems still
   disagree.

## Connection and readiness

<AccordionGroup>
  <Accordion title="Production shows 0/5 or 'No Square token saved'">
    This is expected for an unconfigured environment. Select Production, enable
    editing, save the Production application credentials, connect the real
    seller through OAuth, add the Production webhook signature key, choose the
    location, and pair the Terminal. Do not copy the Sandbox token.
  </Accordion>

  <Accordion title="Connect OAuth is unavailable or fails before Square opens">
    Save the Square Application ID and Application secret for the selected
    environment first. Copy the OAuth redirect URL from Inventory into that
    environment's Square application settings. Confirm the URL matches exactly.
  </Accordion>

  <Accordion title="Square returns Unauthorized">
    The access token commonly belongs to the other environment, was revoked, or
    lacks a required scope. Confirm the environment badge, seller, and
    application. Re-authorize the intended seller instead of adding unrelated
    manual tokens.
  </Accordion>

  <Accordion title="Locations are empty or the wrong business appears">
    Verify the OAuth seller and `MERCHANT_PROFILE_READ` permission. A location
    cannot be borrowed from another seller or from Sandbox. Reconnect the
    correct account, refresh locations, and ask the Square owner to confirm the
    location name.
  </Accordion>

  <Accordion title="The connection was revoked">
    Square sends `oauth.authorization.revoked`, and Tuturuuu marks the
    connection unavailable. Stop checkouts, ask the owner why access was
    revoked, then re-authorize only if the owner approves it.
  </Accordion>
</AccordionGroup>

## Webhooks

<AccordionGroup>
  <Accordion title="Square test delivery is rejected">
    Confirm the subscription environment, notification URL, signature key, and
    event type. Copy the workspace webhook URL from Inventory; do not rebuild it
    manually. The exact URL used by Square is part of signature verification.
  </Accordion>

  <Accordion title="Signature verification fails after a domain or tunnel change">
    Square signs the configured notification URL plus the raw body. Update the
    Square subscription and Inventory's advanced notification URL to the same
    exact HTTPS value, then replace the matching environment's signature key.
  </Accordion>

  <Accordion title="Square sent the same event more than once">
    Duplicate delivery is normal when an acknowledgement is delayed or Square
    retries. Compare the `event_id`. Tuturuuu should keep one checkout, payment,
    stock transition, and finance entry. Escalate only if business state is
    duplicated.
  </Accordion>

  <Accordion title="Events arrive in an unexpected order">
    Square does not guarantee delivery order. Reconcile by provider object and
    final payment status rather than arrival time. Do not edit checkout state
    manually to match the first event you saw.
  </Accordion>

  <Accordion title="Inventory count webhook did not appear">
    Square may not emit `inventory.count.updated` when the written count equals
    the existing value. In Sandbox, change the demo count to a distinct value,
    verify the event, then restore it intentionally.
  </Accordion>
</AccordionGroup>

## Terminal and pairing

<Warning>
  A phone or tablet running Square POS with a connected Reader is not a
  Terminal API device. It will not appear after **Refresh terminals**. Select
  **Phone or tablet with Reader**, register the POS callback URL, and use the
  **Square POS app + Reader** Storefront mode instead.
</Warning>

| Symptom                           | Check                                                                                 | Safe action                                                                        |
| --------------------------------- | ------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
| Pairing code expired              | It was not entered within five minutes                                                | Create a new code in Tuturuuu                                                      |
| Dashboard code does not pair      | Generic Dashboard codes are not Terminal API codes                                    | Discard it and create the code in Tuturuuu                                         |
| Paired device does not appear     | `device.code.paired` delivery, seller, environment, and location                      | Refresh devices after the webhook succeeds                                         |
| Terminal shows no payment prompt  | Device online state, selected default device, location, and existing pending checkout | Reconcile the current checkout; do not send a second one                           |
| Wrong Terminal receives the order | Saved default device and counter name                                                 | Stop checkouts, select the correct paired device, then test with an approved order |
| Terminal is offline               | Network indicator, software updates, Wi-Fi/Ethernet, captive portal                   | Restore connectivity and reconcile the existing checkout                           |

## Square POS app and Reader

| Symptom                                       | Check                                                                                                 | Safe action                                                                                          |
| --------------------------------------------- | ----------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
| Phone/Reader does not appear in terminal list | Hardware is connected inside Square POS, not Terminal API                                             | Do not paste its device ID; switch to the phone/Reader setup path                                    |
| Square POS does not open                      | Request is on Android/iOS, latest Square POS is installed, and browser permits app links              | Return to the same reserved order; install/update Square POS before trying a new checkout            |
| `UNAUTHORIZED_CLIENT_ID` or callback error    | Production Application ID and exact Point of Sale API Web Callback URL                                | Copy the URL from Inventory and save it in the Production Square application                         |
| `ILLEGAL_LOCATION_ID` / user mismatch         | Square POS is signed into the same location saved in Inventory                                        | Sign in to the approved location; do not remove the location safeguard                               |
| Payment returns but order stays pending       | Square Order/Payment may still be synchronizing, or amount/currency/location/card verification failed | Keep the order open and inspect its failure reason plus Square payment evidence; do not charge again |
| No server transaction ID                      | Payment was offline or no supported online card order was returned                                    | Tuturuuu leaves stock unchanged for manual review; reconcile Square before any retry                 |

The Point of Sale API callback is not treated as payment proof by itself.
Tuturuuu uses the returned transaction ID as a Square Order ID, retrieves its
Payment, and verifies the exact reserved amount, currency, location, completed
status, and card tender. This is why cash and offline returns are not
automatically finalized.

Square Terminal cannot use browser-based captive-portal networks. Review
[Square's network requirements](https://squareup.com/help/us/en/article/8348-set-up-network-requirements-for-square-hardware)
and
[Terminal network troubleshooting](https://squareup.com/help/us/en/article/8350-troubleshoot-network-connection-on-square-terminal).

## Checkout, payment, and stock

<AccordionGroup>
  <Accordion title="The checkout is pending">
    Keep the same order. Check Square Payments and the Terminal checkout. If no
    payment completed, cancel that checkout from Inventory Commerce or let it
    expire. Tuturuuu reservations expire after 15 minutes and release stock when
    final reconciliation runs.
  </Accordion>

  <Accordion title="The buyer says they paid but Tuturuuu is not completed">
    Search Square by location, time, amount, and receipt. If Square shows a
    completed payment, do not retry. Record the Square evidence and inspect the
    `payment.updated` and `terminal.checkout.updated` webhook deliveries.
  </Accordion>

  <Accordion title="Tuturuuu says completed but Square evidence is missing">
    Confirm you are viewing the same Sandbox or Production seller and location.
    Record all evidence and stop new attempts. This mismatch requires support
    investigation; do not create a balancing payment or manual stock change.
  </Accordion>

  <Accordion title="Canceled or expired checkout still holds stock">
    Refresh the Commerce and Payments views after the final Square event. Allow
    the scheduled expiry reconciliation to run. If the reservation remains,
    escalate with the order reference, final Square status, timestamps, and
    stock values. Do not compensate by increasing on-hand stock manually.
  </Accordion>

  <Accordion title="Stock or finance changed twice">
    Stop processing the item, preserve the rows, and compare Square event IDs
    and provider IDs. Duplicate webhooks must be idempotent. Do not delete a
    duplicate-looking record before support confirms which row is authoritative.
  </Accordion>

  <Accordion title="No receipt link appears">
    Confirm the payment is completed and inspect the Square payment directly.
    Sandbox has receipt limitations, while Production receipt behavior depends
    on Square and the seller's receipt settings.
  </Accordion>
</AccordionGroup>

## Catalog and stock sync

<AccordionGroup>
  <Accordion title="The summary says products synchronized, but I cannot see them">
    Open the **Linked catalog records** list, clear any UI filter, and verify the
    environment. Metrics count item, variation, and stock operations, so the
    total can exceed the number of unique products. One visible link row is the
    reliable evidence for one Square variation relationship.
  </Accordion>

  <Accordion title="A price is 100 times too small or large">
    Stop all sync and checkout actions for that item. Record the human-readable
    amount and currency on both sides. Do not manually multiply or divide and
    sync again. Confirm the current Tuturuuu release, then correct the approved
    source once and verify a one-way sync with a demo item first.
  </Accordion>

  <Accordion title="Two-way sync reports a conflict">
    This is protective behavior. Compare the Tuturuuu and Square values, get an
    owner decision, and run one directional sync from the approved source. Do
    not alternate directions or delete the Square item.
  </Accordion>

  <Accordion title="A Square deletion is preserved">
    Tuturuuu intentionally keeps the local product and link for review. Ask the
    owner whether to republish the item or leave it disconnected. Synchronization
    never deletes Square objects or local product data to resolve this status.
  </Accordion>

  <Accordion title="A link shows Sync error">
    Read the row's error, then check environment, token scopes, location,
    currency, SKU, and Square object availability. Retry only the intended
    direction after fixing the cause.
  </Accordion>
</AccordionGroup>

## Storefront issues

| Symptom                                       | Safe check                                                                                                                                         |
| --------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| Storefront not found                          | Verify the published slug and use the Inventory Storefront URL generated by the workspace; do not infer a slug on another host                     |
| Square option is missing                      | Confirm the Storefront mode matches the hardware: **Square POS app + Reader** or **Square Terminal**, and the matching readiness check is complete |
| Checkout returns a readiness error            | Open Payments and fix the named connection, webhook, location, or device check                                                                     |
| Two checkout tabs or prompts appear           | Stop and inspect whether two requests were submitted; reconcile both provider records before any new attempt                                       |
| Cart reserves but no provider request appears | Inspect the same checkout in Commerce and Payments; cancel/release it if Square creation failed                                                    |

## Never do these during an incident

* Do not send the same Production order again while the first is pending or
  uncertain.
* Do not create a second charge to cancel out an uncertain charge.
* Do not copy Sandbox tokens, IDs, device simulators, or webhook keys into
  Production.
* Do not delete or archive Square catalog objects to force synchronization.
* Do not manually increase stock while an unresolved reservation exists.
* Do not paste secrets or customer personal data into an escalation message.
* Do not factory-reset a Terminal until the Square owner understands the impact
  and the current checkout has been reconciled.

## Escalate with evidence

Include the packet from the
[operations guide](/platform/applications/inventory-square-pos/operations#escalation-packet)
and check [Square system status](https://www.issquareup.com/) for provider-wide
incidents. Redact tokens, application secrets, signature keys, full card data,
and customer personal information.

For implementation-level failures, use the
[Square Terminal engineering runbook](/build/devops/square-terminal-integration).


# Learn learner app
Source: https://docs.tuturuuu.com/platform/applications/learn

Student and parent-facing education app for Tuturuuu workspaces.

Learn lives in `apps/learn` and runs locally on port `7812`. It is the learner-facing companion to the main Tuturuuu web platform: students and parents use Learn for lessons, practice, assignments, reports, marks, XP, streaks, and hearts, while teachers and admins manage education data in Teach.

## Ownership model

Learn does not render its own login portal. Its `/login` route first checks for an existing Learn app-session JWT. If the app session is already present, it redirects inside Learn to the requested `next` path, usually `/dashboard`. Otherwise it redirects to the platform login at `apps/web` with a `returnUrl` pointing back to `/verify-token`. Learn stores a host-only `tuturuuu_app_session` cookie after token verification, not a Learn-local Supabase Auth session.

The `/dashboard` entry route must only send users to `/login` when the Learn app-session is missing. If the app-session exists but the Learn bootstrap API returns no eligible education workspace, render the empty workspace state instead of redirecting back to login.

Social auth providers still run on `apps/web` because OAuth provider callbacks are registered for `tuturuuu.com`. After the platform login confirms the current account, `apps/web` generates a cross-app token for the `learn` target app and redirects back to `/verify-token`. Learn's local `POST /api/auth/verify-app-token` route only completes the host-only cookie handoff; token validation is delegated back to the central web app so Learn does not depend on a Learn-local Supabase Auth project. The handoff stores a Learn-local app-session cookie for satellite route guards and shared session material used when a retained platform service must be called. If older session material cannot be refreshed, Learn sends the user back through the platform handoff so the coordinated cookies are renewed without manual deletion.

Learn owns learner and parent-facing v1 API contracts, including bootstrap,
courses, modules, tests, practice, assignments, reports, marks, parent links,
and vocabulary support. These handlers live under `apps/learn/src/app/api/v1`.
Next.js fallback rewrites send only unmatched `/api/v1/*` and `/api/ai/*` paths
to Web; they do not proxy a path that Learn implements locally.

`packages/education-core` contains reusable server-only education domain logic;
it does not own HTTP traffic. The Tulearn helpers in
`packages/internal-api/src/tulearn.ts` select the Learn origin for learner
contracts. Explicit exceptions such as platform profile updates keep the Web
origin.

Learn-local logout clears the host-only app-session cookies and stale Supabase Auth cookies on `learn.tuturuuu.*`, then redirects browser form submissions to the central `apps/web` `/logout?from=Learn` continuation. JSON callers can still POST `/api/auth/logout` and receive `{ success: true }`.

Learn also exposes a learner-focused AI Chat surface at `/[wsId]/ai-chat`. The UI stays inside `apps/learn`, while its unmatched `/api/ai/*` requests use the Web fallback so model routing, credits, logging, and chat persistence remain centralized.

## Workspace access

Every Learn workspace API requires both:

* the authenticated user has student access or an explicit active parent-student link; and
* `workspace_secrets.name = ENABLE_EDUCATION` is set to the canonical value `true` for that workspace.

The bootstrap route only returns eligible education workspaces and linked students:

```txt theme={null}
GET /api/v1/tulearn/bootstrap
```

Workspace-scoped learner routes use the normalized workspace id so aliases like `personal` do not diverge between selection and final reads. Linked learners in `workspace_user_linked_users` count as eligible student access even when the platform user is not a direct workspace member, so course lists and learner dashboard bootstrap must agree on the same workspace set.

## Parent links

Parent access is explicit and read-only in v1. The existing Tulearn schema adds:

* `tulearn_parent_student_links` for accepted parent to student links;
* `tulearn_parent_invites` for invite-based parent linking;
* admin-managed parent-link APIs under `/api/v1/workspaces/[wsId]/tulearn/parent-links`.

Parents can switch between linked students in Learn. Parent requests may read home, courses, assignments, reports, marks, and practice context for linked students, but mutation routes reject parent writes.

## Gamification

Learn-owned gamification behavior is backed by the existing Tulearn tables, separate from teacher-owned course data:

* `tulearn_gamification_events` stores XP events with an idempotency key per workspace and learner.
* `tulearn_learner_state` stores hearts, max hearts, total XP, streaks, freezes, selected workspace, and UI preferences. Direct authenticated writes are limited by RLS to the learner's own row in workspaces where that learner is a member; non-null `selected_workspace_id` values must also point to a workspace the learner can access.

XP awards and heart loss must go through the database RPCs `award_tulearn_xp` and `lose_tulearn_heart`. Those functions lock the learner state row and keep event insertion, streak updates, XP totals, heart decrements, and refill timer resets atomic under concurrent practice or assignment submissions. Streak dates currently use UTC day boundaries until Learn stores learner or workspace time zones.

Courses, modules, quiz sets, flashcards, assignments, monthly reports, and marks continue to reuse existing education and user-group tables.

## Code organization

Learn learner pages keep the public `apps/learn/src/components/learner-pages.tsx` entrypoint as a thin barrel export. Route-level screens live under `apps/learn/src/components/learner-pages/*`, with shared page motion, loading, empty state, and section primitives in `shared.tsx`.

The home dashboard should be a real learner workspace, not a landing page. Keep daily plan, quest board, learner toolkit, course path, assignments, marks, reports, practice, and AI Chat entrypoints visible as responsive Neobrutalist panels. Secondary rails should stack below the main grid until there is enough width for readable cards, and color should use dynamic theme tokens rather than a single accent.

Keep Learn learner files under 400 LOC and individual components under 200 LOC. When a screen grows, split reusable cards, rows, panels, and route-specific helpers into adjacent modules before final verification instead of letting `learner-pages.tsx` or any route screen become a monolith again.

Language switching is handled inside Learn with `next-intl`, but locale prefixes are hidden from URLs. Legacy locale-prefixed paths such as `/vi/dashboard` are canonicalized back to `/dashboard` while preserving the selected locale in `NEXT_LOCALE`. Keep English and Vietnamese strings in `apps/learn/messages/en.json` and `apps/learn/messages/vi.json`, then run `bun i18n:sort`.

Learn metadata and auth return URLs must resolve to absolute HTTP(S) app URLs. Prefer `LEARN_APP_URL` or `NEXT_PUBLIC_LEARN_APP_URL` for the app origin. A valid absolute `BASE_URL` can be used as a fallback, but non-URL environment values such as `development` are ignored so local development falls back to `https://learn.tuturuuu.localhost` through Portless.

Do not configure Learn return URLs with the retired `tulearn.tuturuuu.com` origin. Production learner redirects should use `https://learn.tuturuuu.com`, and teacher-facing redirects should use `https://teach.tuturuuu.com`.

## Verification

After changing Learn routes, run focused route tests first. Finish Learn API or
UI changes with the app typecheck, repository checks, and the owning app build:

```bash theme={null}
bun type-check:learn
bun check
bun run --cwd apps/learn build
```

Schema changes additionally require `bun sb:up` and `bun sb:typegen`; message
changes require `bun i18n:sort`. Run focused route or component tests around
parent read-only access, student-only writes, XP idempotency, assignment
completion, marks, and reports when those behaviors change.

## CI and deployment

Learn has dedicated Vercel workflows:

* `.github/workflows/vercel-preview-learn.yaml`
* `.github/workflows/vercel-production-learn.yaml`

Both workflows are registered in `tuturuuu.ts` and use the shared `ci-check.yml` switchboard. They require environment-scoped Vercel credentials plus `VERCEL_LEARN_PROJECT_ID`; production Supabase values should live in the Vercel project environment rather than GitHub Actions.

Deployment credentials must stay environment-scoped in GitHub Actions. The preview job is bound to the `vercel-preview-learn` GitHub Environment, and the production job is bound to `vercel-production-learn`. Store `VERCEL_TOKEN`, `VERCEL_ORG_ID`, and `VERCEL_LEARN_PROJECT_ID` in those environments instead of repository-wide or organization-wide secrets. Production Supabase values remain in the Vercel project environment pulled by `vercel pull`. The repository-level `TURBO_TOKEN` and `TURBO_TEAM` variable are passed only to the wrapped `vercel build` step; never place them at workflow or job scope, and never expose the token to pull-request or Dependabot code.

Preview dispatch is manual-only. Run `vercel-preview-learn.yaml` from `main`, set `preview_ref` to the reviewed branch, tag, or SHA, and keep `TRUSTED_PREVIEW_DEPLOY_ACTORS` limited to maintainers approved to run secret-backed preview builds. Manual production dispatch is only valid from `refs/heads/production`.

`apps/learn/vercel.json` disables Vercel Git deployments and GitHub integration so preview and production deploys only happen through the CI workflows.


# Tuturuuu Mail
Source: https://docs.tuturuuu.com/platform/applications/mail

Multi-mailbox client with permanent SES and Cloudflare transports.

`apps/mail` is the standalone Tuturuuu mailbox app. It runs on
`https://mail.tuturuuu.com` in production and port `7820` locally, delegates
auth to `apps/web`, and preserves Tuturuuu workspace and mailbox-role checks.
Platform operators may configure additional managed domains; a mailbox address
must match its linked `private.mail_domains` row.

## Architecture

* `apps/mail` owns the mailbox UI and protected app-local APIs under
  `/api/v1/workspaces/:wsId/mail/*`.
* The mailbox mirror is stored in service-only `private.mail_*` tables. Browser
  code never reads those tables directly; routes verify workspace membership
  and mailbox roles before using an admin client.
* SES and Cloudflare Email Service are permanent outbound transports. The
  domain default comes from `mail_domains.outbound_provider`; an optional
  mailbox override wins. Shared abuse, rate-limit, and audit controls in
  `@tuturuuu/email-service` still run for both providers.
* Inbound transport is domain-wide. SES receipt/S3/SNS ingestion remains
  supported, while Cloudflare Email Routing invokes the Worker at
  `apps/mail/src/email-worker/index.ts`.
* Supabase is authoritative for domains, authorization, audit, threads, search,
  AI state, and MCP credentials. The private R2 bucket contains raw MIME, body
  objects, and attachment bytes; callers receive authorized short-lived access,
  never raw keys or R2 credentials.
* Thread resolution checks `Message-ID`, `In-Reply-To`, and `References` first.
  Normalized subject is only a recent-reply fallback and is not unique.

Mail consumes `/verify-token` in the proxy before centralized auth handling so
local Portless handoffs set cookies on `mail.tuturuuu.localhost`. The app keeps
token refresh same-origin through `/api/auth/refresh-app-session`; a valid
refresh cookie should rotate the Mail-local and Web-issued app-session cookies
without sending the browser back through `apps/web` login.

## SES Receiving Setup

Do not change DNS from code or migrations. The current public MX for `tuturuuu.com` is Google-routed, so real `@tuturuuu.com` receiving requires an explicit staged MX cutover or a pilot subdomain first.

1. Verify the domain or pilot subdomain in the SES receiving region.
2. Create an S3 bucket for raw MIME objects.
3. Create an SNS topic for receipt notifications and subscribe the web webhook:
   `POST /api/v1/webhooks/mail/ses`.
4. Create an SES receipt rule that stores raw MIME in S3 and publishes the SNS notification.
5. Configure `MAIL_SES_INBOUND_TOPIC_ARN`, `MAIL_SES_INBOUND_BUCKET`, `MAIL_SES_INBOUND_KEY_PREFIX`, and `MAIL_SES_REGION`.
6. Only after validation, stage the MX/DNS change outside the app repository.

For local SNS fixture tests, set `MAIL_SES_SNS_SIGNATURE_VERIFICATION=disabled`. Do not use that setting in production.

## Cloudflare onboarding

Cloudflare must already manage DNS for an onboarded domain. Arbitrary-recipient
sending also requires Email Sending to be enabled for the account. Configure a
staging domain before changing a production domain.

1. Create a private R2 bucket (the checked-in Worker configuration uses
   `tuturuuu-mail`) and bind it as `MAIL_R2_BUCKET` in
   `apps/mail/wrangler.email-routing.jsonc`.
2. Configure the Mail app server with `MAIL_R2_ACCOUNT_ID`,
   `MAIL_R2_ACCESS_KEY_ID`, `MAIL_R2_SECRET_ACCESS_KEY`, and
   `MAIL_R2_BUCKET_NAME`. The bucket name must match the Worker binding.
   `MAIL_R2_ENDPOINT` is only needed for an R2-compatible development or test
   endpoint. Object keys are private implementation details and must not be
   returned to clients. See `apps/mail/.env.example` for the complete contract.
3. Set the Worker secret with
   `bunx wrangler secret put MAIL_INGEST_SECRET --config apps/mail/wrangler.email-routing.jsonc`.
4. Configure the same value as `MAIL_CLOUDFLARE_INGEST_SECRET` in the Mail
   Vercel environment. Signed events include the request body and a timestamp;
   the API rejects invalid or older-than-five-minute signatures.
5. Set `MAIL_INGEST_URL` to the deployed Mail endpoint
   `/api/v1/webhooks/mail/cloudflare`, then deploy with
   `bunx wrangler deploy --config apps/mail/wrangler.email-routing.jsonc`.
6. In Cloudflare Email Routing, onboard the domain and route its intended
   address patterns to `tuturuuu-mail-email-routing`.
7. Configure the domain row through `GET/PUT /api/v1/mail/domains`. Only root
   workspace operators may use this endpoint. Move the domain from `verifying`
   to `active` only after DNS and routing checks pass.
8. For outbound Cloudflare sends, set `MAIL_CLOUDFLARE_API_TOKEN` with Email
   Sending permission and either store the managed account ID on the domain or
   set `MAIL_CLOUDFLARE_ACCOUNT_ID` as the fallback.

The Worker checks domain/provider status before reading and parsing the MIME
stream, uses `postal-mime`, stores deterministic R2 objects, and submits a signed
idempotent delivery event. Malformed or spam/virus-signaled deliveries are
recorded as quarantined. Transient API failures are thrown so Email Routing can
retry without creating duplicate messages.

Cloudflare controls the outbound `Message-ID` header and rejects clients that
set it. Mail therefore sends only `In-Reply-To` and `References` through the
Cloudflare API. SES raw MIME sends retain a deterministic `Message-ID`. Store
Cloudflare's returned provider identifier separately; do not substitute it for
an RFC message identifier unless the provider explicitly returns one in that
format.

## Mailbox API foundation

Mailbox routes require workspace membership and a mailbox role on every
request. The API provides chronological thread retrieval and thread-level state
changes, label and custom-folder CRUD, bulk message mutations, and private
attachment upload/download/delete routes. Attachment downloads stream through
an authorized route with byte-range support; clients never receive an R2 object
key.

Message listing accepts the structured search operators `from:`, `to:`,
`cc:`, `bcc:`, `subject:`, `is:`, `has:attachment`, `before:`, `after:`, and
`label:`. Quote values containing spaces. Structured filters are combined with
remaining free text and mailbox/folder state filters. Client applications
should call these routes through `packages/internal-api/src/mail.ts`.

Cloudflare currently permits 50 combined `to`/`cc`/`bcc` recipients and a
normal outbound size of 5 MiB including attachments. Email Routing accepts up
to 25 MiB inbound. The provider enforces outbound limits before making the API
request; the Worker rejects inbound events above the routing limit. Reconfirm
current quotas in the
[Cloudflare Email Service limits](https://developers.cloudflare.com/email-service/platform/limits/)
before changing these constants.

The managed staging baseline uses `tutur3u.com` for Email Routing and Email
Sending and the private `tuturuuu-mail` R2 bucket. Do not attach a routing rule
to the inbound Worker until the Mail deployment has the matching ingestion
secret and Supabase has an enabled `ingest.tutur3u.com` domain row linked to
the canonical `tuturuuu.com` row. Email Sending and R2 can be verified
independently before that inbound cutover.

## Google Workspace shadow-ingestion migration

Do not onboard `tuturuuu.com` into Cloudflare Email Routing while Google
Workspace still owns its apex MX records. Email Routing is enabled at the zone
level before Cloudflare allows routing subdomains, so onboarding the production
zone would replace and lock the Google MX records too early. Use the already
onboarded staging zone as the shadow bridge instead:

* Cloudflare Email Routing is enabled for `ingest.tutur3u.com`; its routing DNS
  records are managed and locked by Cloudflare.
* A temporary exact-address routing rule may forward a pilot shadow address to
  a verified test inbox. Replace this action with the deployed ingestion Worker
  before starting a parity run.
* Google Workspace has a recipient-address-map setting named
  `Cloudflare shadow ingestion pilot`. Keep it disabled between tests. It must
  map each selected `@tuturuuu.com` address to the same local part at
  `@ingest.tutur3u.com`, retain the original Gmail destination, and add
  `X-Gm-Original-To`.
* The public `tuturuuu.com` MX records remain Google-only throughout the shadow
  phase. Never publish Google and Cloudflare MX records together as a substitute
  for dual delivery.

### Activation gates

Complete all of these before changing the temporary Cloudflare forwarding rule
to the ingestion Worker or enabling the Google pilot:

1. Canonicalize a trusted shadow recipient such as
   `user@ingest.tutur3u.com` to `user@tuturuuu.com`. Preserve both addresses in
   the ingestion event and accept `X-Gm-Original-To` only on the configured
   shadow domain.
2. Configure the same HMAC secret as `MAIL_INGEST_SECRET` on the Worker and
   `MAIL_CLOUDFLARE_INGEST_SECRET` on the Mail deployment.
3. Deploy the Worker with the private `tuturuuu-mail` R2 binding and confirm a
   signed domain check and ingestion event reach the Mail webhook.
4. Ensure Supabase has enabled domain metadata for the shadow and canonical
   domains, including their explicit relationship. Do not infer an arbitrary
   production domain from an inbound subdomain.
5. Prove direct shadow delivery, raw MIME storage, body and attachment storage,
   quarantine behavior, and duplicate retry before enabling Google delivery.

The additive `add_mail_domain_canonical_relationship` migration installs this
exact staging relationship. Apply it through the normal database release path;
do not push it ad hoc from a workstation. The Worker derives the canonical
recipient only after a signed domain check, and the webhook independently
validates the ingress domain, canonical domain, observed recipient, and local
part. Duplicate transport deliveries with the same mailbox and RFC
`Message-ID` reuse the existing message instead of incrementing thread counts.

### Rollout plan

1. **Single-address pilot:** point one exact Cloudflare shadow rule at the
   Worker, enable only the matching Google address-map entry, and send external
   and internal test messages. The original Gmail delivery must remain enabled.
2. **Shadow parity:** expand the explicit map to the active user, group, and
   alias inventory. Run for at least three days and preferably seven. Compare
   Google Email Log Search with Supabase ingestion records by authoritative
   `Message-ID`, recipient, timestamp, raw MIME hash, attachment count, and
   quarantine result.
3. **Cutover readiness:** require no unexplained missing messages, idempotent
   duplicate handling, correct canonical recipients, attachment parity, and an
   alertable ingestion-latency baseline. Snapshot the Google MX records and
   lower or verify their DNS TTL at least 24 hours before the change.
4. **Apex cutover:** during a low-traffic window, onboard `tuturuuu.com` in
   Cloudflare and route its intended addresses to the same Worker. Keep Google
   Workspace and the shadow address map available for at least seven days so
   senders using cached Google MX records still feed the Cloudflare ingestion
   path.
5. **Stabilization:** remove the temporary test forwarding destination only
   after the Worker route is verified. Retire the Google shadow map after the
   cached-MX window and parity checks are complete; migrate outbound transport
   separately.

### Rollback

Restore the saved Google MX records first and wait for DNS confirmation. Keep
the Google shadow map and Cloudflare staging subdomain available during
rollback so messages delivered through either cached MX path still reach the
same idempotent ingestion boundary. Change the Supabase inbound-provider flag
only after DNS is serving the intended provider. A rollback must not delete R2
objects, mail metadata, Google accounts, or the disabled pilot configuration.

The initial transport smoke test used distinct subjects for Google outbound and
Google-to-Cloudflare shadow delivery. Google delivered the original inbound
message to the Workspace inbox, and Cloudflare recorded the mapped shadow copy
as forwarded. After the test, the Google pilot setting was returned to its
disabled state.

## Catch-all delivery

Catch-all routing is platform-operated because it affects an entire inbound
domain. The destination is relational metadata on `private.mail_domains`, not a
workspace secret: `catch_all_mailbox_id` must reference an active mailbox on the
canonical domain, and `catch_all_enabled` defaults to `false`. Automatic drafts
for catch-all deliveries have a separate opt-in and remain disabled unless a
platform operator explicitly enables them.

Activate the bridge in this order:

1. Apply the additive `mail_catch_all_delivery` migration through the normal
   database release process and deploy the matching Mail app and Email Routing
   Worker.
2. Open Mail settings as a root workspace operator, select
   `ingest.tutur3u.com`, choose the destination mailbox, and enable the logical
   catch-all route. The initial pilot destination is
   `phucvo@tuturuuu.com` when that mailbox exists.
3. In Cloudflare Email Routing, select the already-onboarded
   `ingest.tutur3u.com` subdomain and set its catch-all action to the
   `tuturuuu-mail-email-routing` Worker. Keep explicit rules enabled; they take
   precedence over catch-all.
4. Send a unique random local part directly to the ingress subdomain. Confirm
   the original recipient is visible in Mail, raw MIME and attachments are in
   R2, and a retry does not create another message.
5. In Google Admin, add a rule named `Tuturuuu Mail catch-all bridge` for
   inbound **Unrecognized/Catch-all** recipients only. Replace only the
   recipient domain with `ingest.tutur3u.com`, add `X-Gm-Original-To`, and leave
   Users and Groups unchecked. This keeps recognized Google Workspace delivery
   unchanged while preserving the unknown local part for Mail.

Do not enable Cloudflare Email Routing on the `tuturuuu.com` apex while Google
owns its MX records. To roll back, disable the Google unrecognized-recipient
rule first, disable the Cloudflare subdomain catch-all second, and disable the
logical Mail route last. Do not delete ingested metadata or R2 objects.

## Provider rollout and rollback

Provider selection is independent in each direction. Change only one direction
at a time on the staging domain, complete inbound delivery, outbound delivery,
attachment, threading, duplicate retry, and bounce/throttle smoke tests, then
enable the production domain. A mailbox override may be used for a narrow
outbound canary.

To roll back outbound delivery, clear the mailbox override and set the domain
outbound provider to `ses`. To roll back inbound delivery, restore the domain's
SES MX/receipt-rule configuration first, then set `inbound_provider` to `ses`.
Do not change the database flag before DNS is serving the intended provider.
Existing SES jobs, raw S3 metadata, and credentials remain supported throughout
the rollback.

## Operations

### Smart labels and AI-assisted drafting

Apply the `mail_smart_labels` migration before deploying the matching settings
UI. It adds a description, mailbox-scoped AI instructions, an enable flag, and
an auto-apply flag to each private custom label. The migration is additive and
defaults every AI option to disabled. Label CRUD remains limited to mailbox
owners and admins; senders may apply configured labels but cannot redefine the
taxonomy.

Mail exposes AI drafting and smart-label classification only through
mailbox-authorized app routes and `packages/internal-api`. Drafting supports new
messages, rewrites, and follow-ups with bounded thread context. Message content
is treated as untrusted reference material so instructions embedded in an
email cannot override the system prompt. Generated text is returned to the
composer as an editable draft; the AI route has no send, schedule, or transport
tool.

Smart-label suggestions help owners/admins create a taxonomy from recent
mailbox patterns. Classification accepts explicit thread IDs, validates every
thread and label against the active mailbox, and applies labels only after an
authorized user invokes the workflow. `ai_auto_apply` records whether a label
may be applied by an authorized automatic workflow; it does not grant AI any
additional mailbox role or send capability.

The `repair_mail_thread_subjects` migration backfills blank legacy thread
subjects from the newest meaningful message. Runtime thread hydration also
falls back to the newest message so sent mail remains accurate when application
deployment precedes the migration.

* Run `bun sb:up` locally after mail schema changes, then `bun sb:typegen`.
* Keep new mail route access checks in `apps/mail`; do not add direct client
  Supabase reads.
* Use `packages/internal-api/src/mail.ts` for client helpers and TanStack Query in the app UI.
* Unknown inbound recipients are retained as `quarantined` jobs for administrator review instead of being delivered to a user inbox.
* Keep generated public assets such as `/manifest.webmanifest`, `/sw.js`, and
  offline worker files out of the auth proxy matcher. Redirecting those files to
  central Web login breaks standalone Mail startup and PWA registration.
* Keep `apps/mail/src/proxy.ts` `config.matcher` entries as inline string
  literals. Next.js statically parses proxy matcher config during Vercel builds
  and rejects imported constants even when they resolve to strings.

## CI and deployment

Mail has dedicated Vercel workflows:

* `.github/workflows/vercel-preview-mail.yaml`
* `.github/workflows/vercel-production-mail.yaml`

Both workflows are registered in `tuturuuu.ts` and use the shared
`ci-check.yml` switchboard. They require environment-scoped Vercel credentials
plus `VERCEL_MAIL_PROJECT_ID`; production Supabase and SES values should live in
the Vercel project environment rather than GitHub Actions.

The preview workflow builds and deploys prebuilt artifacts through Vercel CLI.
The production workflow also uses workflow concurrency so stale production runs
are canceled instead of deploying after a newer production commit is pushed.

Deployment credentials must stay environment-scoped in GitHub Actions. The
preview job is bound to the `vercel-preview-mail` GitHub Environment, and the
production job is bound to `vercel-production-mail`. Store `VERCEL_TOKEN`,
`VERCEL_ORG_ID`, and `VERCEL_MAIL_PROJECT_ID` in those environments instead of
repository-wide or organization-wide secrets. Do not add `TURBO_TOKEN`,
`TURBO_TEAM`, production Supabase service keys, or SES credentials to
workflow-level `env`; Mail deploys should rely on Vercel project environment
variables pulled by `vercel pull`. Manual production dispatch is only valid from
`refs/heads/production`.

`apps/mail/vercel.json` disables Vercel Git deployments and GitHub integration
so preview and production deploys only happen through the CI workflows.


# Mind
Source: https://docs.tuturuuu.com/platform/applications/mind

Mindboard satellite app for long-horizon planning, knowledge graphs, and AI-aided graph patches.

Mind lives in `apps/mind`, runs locally on port `7816`, and is served in
production from `https://mind.tuturuuu.com`. Local development should use
Portless at `https://mind.tuturuuu.localhost`; the legacy direct fallback is
`http://localhost:7816`.

Mind is available to signed-in Tuturuuu users, not only internal
`@tuturuuu.com` accounts. The satellite app accepts the Tuturuuu cross-app login
handoff through `/verify-token`, stores a host-local `tuturuuu_app_session`
cookie for the `mind` app target, and keeps workspace data behind membership
checks. Mind must not create a local Supabase Auth session.

Mind consumes `/verify-token` in the proxy and requires the coordinated cookie
pair on protected routes: the Mind-local app-session cookie for route guards and
the Web-issued app-session cookie for forwarded central APIs. If only the
Mind-local cookie remains, route users through local `/login` to refresh the
pair. Expired access tokens should rotate through
`/api/auth/refresh-app-session` on the Mind origin while refresh cookies are
valid.

Mind AI also follows the shared AI credit contract instead of an employee-only
allowlist. The `/api/ai/mind` route resolves the selected personal or workspace
credit source, checks the caller's membership for workspace credits, preflights
model availability and remaining credits, and deducts usage from that same
billing workspace after a successful stream.

Mind AI uses the stable `google/gemini-3.1-flash-lite` model entry for its
Flash Lite default/fallback surface. Stored preferences and old clients that
still send `google/gemini-3.1-flash-lite-preview` are normalized to the stable
ID before credit model resolution and provider streaming.

The model selector reads from the paginated infrastructure model catalog with
server-side search and "load more" pages. Do not reintroduce first-page-only
catalog fetches or local-only filtering; matching models must remain reachable
even when they are outside the initial response.

## Dual-Host Parity

Mind is available through both the standalone satellite host and the main web
dashboard. The standalone route shape stays `/{wsId}` and
`/{wsId}/boards/{boardId}`. Inside `apps/web`, the route shape is
`/{wsId}/mind` and `/{wsId}/mind/boards/{boardId}`.

Both hosts must render the same shared UI and use the same client logic from
`@tuturuuu/mind-ui`. Keep `apps/mind` and the `apps/web` Mind routes as thin
host wrappers for auth, workspace resolution, and route prefixing only. Future
Mind feature work belongs in `packages/mind-ui` or the centralized Mind APIs so
the standalone app and web-hosted app stay 1:1.

Board route-segment layouts that render Mind board routes must load
`@xyflow/react/dist/style.css`, and the shared Mind shell must keep a concrete
dashboard embed height. Keep that stylesheet out of root app layouts and the
Mind index so it is only loaded when users enter a canvas route. Without both
pieces, React Flow can mount but render as a blank or collapsed canvas inside
embedded dashboard routes.

## Board library vs studio

The workspace index route is a **board library**, not the canvas studio:

* **Web**: `/{wsId}/mind` lists boards (search, create, pick). Selecting or
  creating a board navigates to `/{wsId}/mind/boards/{boardId}` for the studio.
* **Satellite**: `/{wsId}` is the same board library; `/{wsId}/boards/{boardId}`
  is the studio.

`MindBoardIndex` from `@tuturuuu/mind-ui` owns the index experience. Do not
auto-select the first board on the index route. `MindDashboard` only mounts on
board routes and receives `initialBoardId`; it must not fall back to
`boards[0]`. If a board route loads without a selected board, prompt the user to
return to the index instead of showing an infinite loading state.

## API Ownership

`apps/mind` owns its protected Mind product handlers:

* `/api/v1/workspaces/:wsId/mind/boards`
* `/api/v1/workspaces/:wsId/mind/boards/:boardId`
* `/api/v1/workspaces/:wsId/mind/boards/:boardId/graph`
* `/api/v1/workspaces/:wsId/mind/boards/:boardId/patches`
* `/api/v1/workspaces/:wsId/mind/search`
* `/api/v1/workspaces/:wsId/mind/ai/patches/:patchId/apply`
* `/api/ai/mind`

Exact local handlers win before the fallback rewrites for `/api/v1/*` and
`/api/ai/*`. The shared AI attachment endpoints have no Mind-local handler and
are therefore forwarded to `apps/web`:

* `/api/ai/chat/upload-url`, `/api/ai/chat/delete-file`, and
  `/api/ai/chat/file-urls`, which provide shared Mind chat attachments

The separate `/api/v1/hive/servers/:serverId/mind-simulations` integration is
Hive-owned in `apps/hive`, not a Mind product handler. It imports a Mind board
as Hive agents plus a saved interaction workflow.

Consume local Mind, Web fallback, and Hive integration families through their
typed `@tuturuuu/internal-api` helpers. Browser requests for the first two stay
same-origin so the Mind rewrite boundary remains transparent. Mind-local
protected handlers resolve the Mind app-session actor and enforce workspace
membership; forwarded Web exceptions require the coordinated Web-issued
session and keep their own product permissions. Do not add direct client
Supabase reads or client-local raw `fetch('/api/...')` calls for protected Mind
data.

Workspace routes must normalize aliases such as `personal`, verify workspace
membership with the request-scoped auth context, and then perform private-schema
reads or writes through the centralized server repository.

Mind repositories must not use ad-hoc raw SQL from application code. Keep data
operations in private-schema Postgres RPCs and call them through a
service-role Supabase admin client with `.schema('private').rpc(...)`.
`apps/database/supabase/config.toml` exposes the `private` schema to PostgREST
so these RPCs are callable, but table/function grants stay service-role-only.
Changing that config requires a local Supabase restart or `bun sb:up` before the
Mind APIs stop returning `Invalid schema: private`.

The canvas should load from the graph-only snapshot path, while generated draft
patch artifacts load from the patch-list path. Do not couple canvas rendering to
recent AI patch serialization: a failed patch-artifact refresh should stay
inside the assistant panel and must not replace the board canvas with a board
load error. The legacy full snapshot can still return graph data plus patches
for backward compatibility.

Mind graph handles use loose React Flow connections with one visible connection
point per side. Cluster and children frames are synthetic canvas nodes used only
for interaction: manual links to a frame persist as normal node edges with frame
endpoint metadata, so saved graph payloads still satisfy the node-only edge
schema while rendering the relationship to the group boundary.
Nodes, relationships, clusters, and child-group frames should all be selectable
from the canvas. Node and relationship selections open editable properties,
while synthetic group or cluster frame selections open a compact read-only
properties island that identifies the anchor node and child count.

## Hive Integration

A Mind board can be sent to Hive from the compact top-right canvas controls.
The Hive-owned import API reads the saved Mind graph, verifies workspace
membership through the request-scoped client, requires Hive admin access, and
creates Hive NPC agents from the highest-signal Mind nodes. Mind edges become
Hive agent interaction pairs, and the generated Hive workflow first stamps the
Mind source context into the world before running the agent-interaction node.

Keep the mutation in `apps/hive`; the shared Mind canvas should not duplicate
Hive server logic. Client code should call `createHiveMindSimulation()` from
`@tuturuuu/internal-api/hive`; do not add client-local raw fetch calls or
duplicate graph-to-agent conversion logic.

## Data Model

Mind product tables live in the `private` schema. User access goes through the
Mind-local product APIs, while only the explicit fallback families above go to
the central Web API. Direct table access is service-role only.

* `private.mind_boards`
* `private.mind_nodes`
* `private.mind_edges`
* `private.mind_tags`
* `private.mind_node_tags`
* `private.mind_groups`
* `private.mind_group_nodes`
* `private.mind_node_links`
* `private.mind_ai_threads`
* `private.mind_ai_messages`
* `private.mind_ai_patches`

`mind_node_links` is the first integration seam for Tasks, Calendar, documents,
projects, and external URLs. Live pickers can attach to this link contract later
without changing the core graph schema.

Nodes carry a first-class workflow status: `backlog`, `planned`,
`in_progress`, `in_review`, `blocked`, `completed`, `deferred`, and
`cancelled`. The canvas and AI tools should treat status as a planning signal,
not just decoration: blocked nodes need dependencies, in-review nodes need
validation criteria, and completed nodes should remain available for historical
context and dependency tracing.

## AI Patch Safety

Mind AI chats default to review mode. In review mode, tools can inspect
mindboards, load graph chunks, search nodes, and store proposed patches, but the
user applies the patch explicitly from the Mind UI.

Direct-write mode is scoped to the current chat. In direct-write mode, the
`apply_mind_patch` tool can write the structured patch transactionally and the
repository records the patch status, `applied_at`, and applying user for audit.

Structured patches should stay small enough to review. Prefer multiple focused
patches over a single broad rewrite when consolidating large graphs.
For normal structure-generation requests, a patch should still be complete
enough to be useful: include the major clusters, concrete child nodes, and the
relationship edges that connect them to the root goal or to each other. Avoid
AI drafts that expand only one branch while leaving related top-level systems as
isolated nodes.
The existing board is authoritative. AI drafts should reuse and extend relevant
existing node IDs first, then create missing child nodes and relationships
around those anchors. Do not draft a detached replacement root when the current
mindboard already contains a matching goal, system, cluster, or milestone.
The patch tool normalizes generated aliases and stores operations in apply-safe
order: newly-created parent and child nodes are inserted before relationship
edges or updates that reference them. Existing draft patches are normalized
again just before application so older edge-first drafts do not fail foreign-key
checks.

For large boards, the assistant should inspect structure first, then search or
load neighborhoods/chunks instead of requesting a full graph by default. Keep
responses action-oriented: suggest follow-up passes, propose draft patches when
they are useful, and only implement graph writes when the chat is explicitly in
Implement mode.

After a draft patch is applied from the Mind UI, the client closes the
assistant panel, reloads the board, runs the smart canvas organizer, saves the
resulting positions, and refreshes board queries. The organizer should keep
true same-level sequence nodes in a compact horizontal lane, place explicit
children under their parent, and anchor supporting or dependency nodes near the
higher-level node they affect.
Applying a draft and refreshing layout are separate phases: once the patch
application RPC returns, patch artifacts should show `Applied` immediately. If
the follow-up auto-layout save fails, keep the patch applied and show a retryable
layout-refresh warning instead of treating the graph patch as failed.

Mind boards auto-save canvas edits. The board title, canvas tools, tag filter,
and save status live in one compact top-left island. The title is editable from
that island, the tag filter uses an icon-only ghost dropdown, and the save icon
shows saved, saving, unsaved, or retryable error state and can be clicked to
force a save. In the web-hosted board route, the compact top-right island owns
the Hive simulation launcher and the assistant toggle.
Autosave signatures, tag indexing, group-frame layout, and relationship routing
obstacle scans are intentionally debounced so dragging stays responsive on dense
boards; keep direct node movement immediate and move only derived calculations
onto short debounce windows.

React Flow canvas routes should pan with two-finger trackpad movement while
preserving pinch-to-zoom. Do not switch trackpad scrolling back to zoom-only
behavior; use explicit canvas controls or pinch gestures for zoom.

Generated plans and patch drafts should be treated as artifacts. The newest
artifact can open in the proposal island, while every message keeps a compact
artifact row for reopening it. When a generated visual plan and a draft patch
belong to the same assistant response, render them as one centralized draft
proposal pending approval: the structured patch preview is the review context,
and the single Apply action belongs to the proposal shell. Do not show the
visual plan and draft patch as duplicated stacked content. Tool-call and
artifact sections default to
collapsed compact rows; while the assistant is working, the row should show a
spinner and the latest tool or artifact name without expanding the full debug
list. When a draft is applied, the applied patch should render as `Applied` in
those artifact views instead of staying visually draft-only.

The canvas toolbar can copy the current board as Markdown or JSON. This export
uses the local in-canvas graph state, including unsaved position edits, so it is
useful for sharing a planning snapshot or debugging AI patch output.

## Deployment

Mind has dedicated Vercel workflows:

* `.github/workflows/vercel-preview-mind.yaml`
* `.github/workflows/vercel-production-mind.yaml`

Store `VERCEL_TOKEN`, `VERCEL_ORG_ID`, and `VERCEL_MIND_PROJECT_ID` in the
workflow environments `vercel-preview-mind` and `vercel-production-mind`.
Deployment should rely on Vercel project environment variables pulled by
`vercel pull`; do not add provider AI keys or production Supabase service keys
to GitHub Actions. The repository-level `TURBO_TOKEN` and `TURBO_TEAM` variable
are passed only to the wrapped `vercel build` step, never at workflow/job scope
and never to pull-request or Dependabot code.

## Verification

After changing Mind schema, API, or UI code, run the most relevant focused
checks first, then the repo-required checks:

```bash theme={null}
bunx vitest run packages/internal-api/src/mind.test.ts packages/ai/src/mind/patch.test.ts
bun i18n:sort
bun type-check:mind
bun check
```

After applying the local Supabase migration, run `bun sb:typegen` and consume
database shapes through `@tuturuuu/types/db`.


# Nova - Prompt Engineering Platform
Source: https://docs.tuturuuu.com/platform/applications/nova

Architecture and implementation of the Nova prompt engineering platform

Nova is Tuturuuu's prompt engineering platform designed to help users learn, practice, and compete in AI prompt engineering challenges.

## Overview

Nova provides an interactive environment where users can:

* Learn prompt engineering through structured problems
* Practice against problem test cases (some public, some hidden)
* Compete in timed, attempt-limited challenges
* Submit prompts for automated, criteria-based evaluation
* Track progress through sessions and leaderboards (individual and team)

<Note>
  Nova is a **standalone satellite app** that lives at `apps/nova`, not inside
  `apps/web`. It runs on port `7805` locally (`nova.tuturuuu` via Portless) and
  delegates authentication to `apps/web` through the shared cross-app login
  handoff, the same satellite pattern used by
  [mail](/platform/applications/mail), [learn](/platform/applications/learn),
  [teach](/platform/applications/teach), [mind](/platform/applications/mind),
  [hive](/platform/applications/hive), and [tasks](/platform/applications/tasks).
</Note>

## Architecture / Satellite Auth

Nova is a Next.js App Router app under `apps/nova` that owns the prompt
engineering UI and its own `/api/v1/*` route handlers. Authentication is
delegated to `apps/web`, and Nova-specific data lives in the shared Supabase
project under the `private` schema, accessed with the service-role admin client.

### Cross-app login handoff

* `apps/nova/src/proxy.ts` runs a centralized auth proxy created with
  `createCentralizedAuthProxy({ targetApp: 'nova', sessionMode: 'supabase-first', mfa: { enabled: false } })`.
  MFA is disabled in the satellite because `apps/web` already enforces `aal2`
  before issuing a cross-app token.
* For browser navigation, the proxy first calls `consumeVerifyTokenRequest`,
  which handles the `/verify-token` handoff so a local Portless login can set
  cookies on `nova.tuturuuu.localhost`. It then runs the auth proxy and locale
  handling.
* `POST /api/auth/verify-app-token` is generated by
  `createPOST('nova', { verificationBaseUrl: TTR_URL })` from
  `@tuturuuu/auth/cross-app/server`. It exchanges a one-time cross-app token from
  `apps/web` for Nova's local app-session.
* Token refresh stays same-origin through
  `POST /api/auth/refresh-app-session`; the proxy refreshes the app session for
  `/api/*` requests via `refreshAppSessionForRequest` and clears Supabase auth
  cookies on failure.

### App-session helpers

`apps/nova/src/lib/app-session.ts` is the single source of truth for resolving
the current Nova user and their platform role:

* `getNovaAppSessionUserFromRequest(request)` resolves the app-session user
  from a `Request` inside a route handler (`targetApp: 'nova'`).
* `getNovaAppSessionUserFromHeaders()` / `requireNovaAppSessionUser()` resolve
  the user in Server Components and redirect to `/login` when absent.
* `getNovaPlatformRole(userId, sbAdmin?)` reads the caller's row from the shared
  `platform_user_roles` table (`enabled`, `allow_challenge_management`,
  `allow_manage_all_challenges`, `allow_role_management`).
* `requireNovaEnabledRole(user)` redirects to `/not-whitelisted` when the role
  is not enabled.

<Warning>
  There is **no Nova tRPC router** and no Nova server-action data layer in
  `apps/web`. Nova route handlers authenticate the caller, then read and write the
  `private.nova_*` tables directly with the service-role admin client. Use
  `packages/internal-api` helpers and the Nova `/api/v1/*` routes for client data
  access; do not add direct client-side Supabase reads of Nova tables.
</Warning>

## Database Schema

All Nova tables live in the `private` schema of the shared Supabase project and
are reachable only through the service-role admin client
(`createAdminClient({ noCookie: true })`). The shapes below are derived from the
generated types in `packages/types/src/supabase.ts` — treat that file as the
source of truth and never hand-edit generated DB types.

### Challenges and problems

A **challenge** is the top-level unit. **Problems** belong to a challenge
(`nova_problems.challenge_id`), and **test cases** belong to a problem
(`nova_problem_test_cases.problem_id`). Note the relationship direction:
problems reference their parent challenge, not the other way around.

#### `nova_challenges`

```sql theme={null}
CREATE TABLE private.nova_challenges (
  id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
  title text NOT NULL,
  description text NOT NULL,
  duration integer NOT NULL,            -- session duration in seconds
  enabled boolean NOT NULL DEFAULT false,
  max_attempts integer NOT NULL,
  max_daily_attempts integer NOT NULL,
  open_at timestamptz,
  close_at timestamptz,
  previewable_at timestamptz,
  whitelisted_only boolean NOT NULL DEFAULT false,
  password_hash text,
  password_salt text,
  created_at timestamptz NOT NULL DEFAULT now()
);
```

#### `nova_problems`

```sql theme={null}
CREATE TABLE private.nova_problems (
  id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
  challenge_id uuid NOT NULL REFERENCES private.nova_challenges(id),
  title text NOT NULL,
  description text NOT NULL,
  example_input text NOT NULL,
  example_output text NOT NULL,
  max_prompt_length integer NOT NULL,   -- caps how long a submitted prompt may be
  created_at timestamptz NOT NULL DEFAULT now()
);
```

#### `nova_problem_test_cases`

```sql theme={null}
CREATE TABLE private.nova_problem_test_cases (
  id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
  problem_id uuid NOT NULL REFERENCES private.nova_problems(id),
  input text NOT NULL,
  output text NOT NULL,
  hidden boolean NOT NULL DEFAULT false, -- hidden test cases are not exposed to participants
  created_at timestamptz NOT NULL DEFAULT now()
);
```

#### `nova_challenge_criteria`

Free-form scoring criteria attached to a challenge. Submissions are graded
against these criteria.

```sql theme={null}
CREATE TABLE private.nova_challenge_criteria (
  id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
  challenge_id uuid NOT NULL REFERENCES private.nova_challenges(id),
  name text NOT NULL,
  description text NOT NULL,
  created_at timestamptz NOT NULL DEFAULT now()
);
```

### Sessions and submissions

#### `nova_sessions`

A timed attempt at a challenge.

```sql theme={null}
CREATE TABLE private.nova_sessions (
  id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
  challenge_id uuid NOT NULL REFERENCES private.nova_challenges(id),
  user_id uuid NOT NULL,
  status text NOT NULL,
  start_time timestamptz NOT NULL,
  end_time timestamptz,
  created_at timestamptz NOT NULL DEFAULT now()
);
```

#### `nova_submissions`

A submitted prompt for a problem. The aggregate score is **not** stored on this
row; per-criterion and per-test-case results live in child tables (see below)
and are aggregated by the `nova_submissions_with_scores` view.

```sql theme={null}
CREATE TABLE private.nova_submissions (
  id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
  problem_id uuid NOT NULL REFERENCES private.nova_problems(id),
  session_id uuid REFERENCES private.nova_sessions(id),
  user_id uuid NOT NULL,
  prompt text NOT NULL,
  overall_assessment text,
  created_at timestamptz NOT NULL DEFAULT now()
);
```

#### `nova_submission_criteria`

Per-criterion grading results for a submission.

```sql theme={null}
CREATE TABLE private.nova_submission_criteria (
  submission_id uuid NOT NULL REFERENCES private.nova_submissions(id),
  criteria_id uuid NOT NULL REFERENCES private.nova_challenge_criteria(id),
  score numeric NOT NULL,
  feedback text NOT NULL,
  strengths text[],
  improvements text[],
  created_at timestamptz NOT NULL DEFAULT now()
);
```

#### `nova_submission_test_cases`

Per-test-case results for a submission, including whether the model output
matched and the grader's confidence/reasoning.

```sql theme={null}
CREATE TABLE private.nova_submission_test_cases (
  submission_id uuid NOT NULL REFERENCES private.nova_submissions(id),
  test_case_id uuid NOT NULL REFERENCES private.nova_problem_test_cases(id),
  output text NOT NULL,
  matched boolean NOT NULL DEFAULT false,
  confidence numeric,
  reasoning text,
  created_at timestamptz NOT NULL DEFAULT now()
);
```

### Teams

Nova supports team-based participation through three tables (not a single
"team management" table):

```sql theme={null}
CREATE TABLE private.nova_teams (
  id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
  name text NOT NULL,
  description text,
  goals text,
  created_at timestamptz NOT NULL DEFAULT now()
);

CREATE TABLE private.nova_team_members (
  team_id uuid NOT NULL REFERENCES private.nova_teams(id),
  user_id uuid NOT NULL,
  created_at timestamptz NOT NULL DEFAULT now()
);

-- Invite-by-email roster for a team
CREATE TABLE private.nova_team_emails (
  team_id uuid NOT NULL REFERENCES private.nova_teams(id),
  email text NOT NULL,
  created_at timestamptz NOT NULL DEFAULT now()
);
```

### Access control tables

Per-challenge whitelisting and manager assignment are keyed by email:

```sql theme={null}
-- Emails allowed to participate when a challenge is whitelisted_only
CREATE TABLE private.nova_challenge_whitelisted_emails (
  challenge_id uuid NOT NULL REFERENCES private.nova_challenges(id),
  email text NOT NULL,
  created_at timestamptz NOT NULL DEFAULT now()
);

-- Emails granted management rights over a specific challenge
CREATE TABLE private.nova_challenge_manager_emails (
  challenge_id uuid NOT NULL REFERENCES private.nova_challenges(id),
  email text NOT NULL,
  created_at timestamptz NOT NULL DEFAULT now()
);
```

Platform-wide Nova permissions are **not** stored in a dedicated `nova_*` roles
table. They come from the shared `public.platform_user_roles` table (`enabled`,
`allow_challenge_management`, `allow_manage_all_challenges`,
`allow_role_management`), exposed to Nova through
`getNovaPlatformRole()`. The `is_nova_role_manager()` RPC reflects the
`allow_role_management` flag.

## Data Access Patterns

Nova route handlers follow a consistent shape: resolve the app-session user,
authorize against the caller's platform role and (for management writes) the
challenge they are touching, then read or write the `private` schema with the
admin client.

### Listing problems for a challenge

```typescript theme={null}
// apps/nova/src/app/api/v1/problems/route.ts (simplified)
import { createAdminClient } from '@tuturuuu/supabase/next/server';
import { NextResponse } from 'next/server';
import { getNovaAppSessionUserFromRequest } from '@/lib/app-session';

export async function GET(request: Request) {
  const { searchParams } = new URL(request.url);
  const challengeId = searchParams.get('challengeId');

  // App-session resolution is synchronous; do NOT await it.
  const user = getNovaAppSessionUserFromRequest(request);
  if (!user?.id) {
    return NextResponse.json({ message: 'Unauthorized' }, { status: 401 });
  }

  // createAdminClient is synchronous, but { noCookie: true } returns a promise
  // in this entrypoint, so await it here.
  const sbAdmin = await createAdminClient({ noCookie: true });

  let query = sbAdmin
    .schema('private')
    .from('nova_problems')
    .select('*')
    .order('created_at', { ascending: false });

  if (challengeId) {
    query = query.eq('challenge_id', challengeId);
  }

  const { data: problems, error } = await query;
  if (error) {
    return NextResponse.json(
      { message: 'Error fetching problems' },
      { status: 500 }
    );
  }

  return NextResponse.json(problems, { status: 200 });
}
```

### Creating a problem (authorized write)

A problem belongs to a challenge, so the caller must be allowed to manage that
specific challenge before the service-role insert runs.

```typescript theme={null}
// apps/nova/src/app/api/v1/problems/route.ts (simplified)
import { createAdminClient } from '@tuturuuu/supabase/next/server';
import { NextResponse } from 'next/server';
import { getNovaAppSessionUserFromRequest } from '@/lib/app-session';
import { canManageNovaChallenge } from '@/lib/challenge-management-auth';
import { createProblemSchema } from '../schemas';

export async function POST(request: Request) {
  const user = getNovaAppSessionUserFromRequest(request);
  if (!user?.id) {
    return NextResponse.json({ message: 'Unauthorized' }, { status: 401 });
  }

  const validatedData = createProblemSchema.parse(await request.json());
  const sbAdmin = await createAdminClient({ noCookie: true });

  // Authorize against the target challenge before the privileged write.
  if (!(await canManageNovaChallenge(user, validatedData.challengeId, sbAdmin))) {
    return NextResponse.json({ message: 'Forbidden' }, { status: 403 });
  }

  const { data: problem, error } = await sbAdmin
    .schema('private')
    .from('nova_problems')
    .insert({
      title: validatedData.title,
      description: validatedData.description,
      max_prompt_length: validatedData.maxPromptLength,
      example_input: validatedData.exampleInput,
      example_output: validatedData.exampleOutput,
      challenge_id: validatedData.challengeId,
    })
    .select()
    .single();

  if (error) {
    return NextResponse.json(
      { message: 'Error creating problem' },
      { status: 500 }
    );
  }

  return NextResponse.json(problem, { status: 201 });
}
```

<Note>
  Supabase client constructors from `@tuturuuu/supabase/next/server` differ:
  `createClient()` and `createDynamicClient()` are async (`await` them), while
  `createAdminClient()` is the sync admin client. Nova's `{ noCookie: true }`
  admin entrypoint is awaited as shown above.
</Note>

## Authorization Helpers

`apps/nova/src/lib/challenge-management-auth.ts` centralizes management checks so
service-role writes are never gated by app-session presence alone:

* `canManageNovaChallenge(user, challengeId, sbAdmin?)` — true when the caller
  can manage all challenges, or has `allow_challenge_management` and is listed in
  `nova_challenge_manager_emails` for that challenge.
* `canManageNovaChallengesGlobally(user, sbAdmin?)` — true when the caller can
  manage all challenges (`allow_manage_all_challenges` or `allow_role_management`).
* `canManageNovaRolesGlobally(user, sbAdmin?)` — true when the caller has
  `allow_role_management`.
* Synchronous predicates `canManageNovaChallenges`, `canManageAllNovaChallenges`,
  and `canManageNovaRoles` evaluate an already-fetched `NovaPlatformRole`.
* Resolver helpers `getNovaProblemChallengeId`, `getNovaTestCaseChallengeId`, and
  `getNovaCriterionChallengeId` walk child rows back to their owning challenge so
  a single `canManageNovaChallenge` check can guard nested mutations.

## Best Practices

### ✅ DO

1. **Authorize service-role writes explicitly.**

   `getNovaAppSessionUserFromRequest()` only proves a valid Nova app-session.
   Any route that mutates Nova management data through
   `createAdminClient({ noCookie: true })` must also check the relevant
   `platform_user_roles` permission before the write, using the shared helpers in
   `apps/nova/src/lib/challenge-management-auth.ts`
   (`canManageNovaChallenge()`, `canManageNovaChallengesGlobally()`,
   `canManageNovaRolesGlobally()`). For nested resources (problems, test cases,
   criteria), resolve the owning `challenge_id` first via the resolver helpers and
   then authorize against that challenge.

2. **Keep hidden test cases hidden.** Never return `nova_problem_test_cases`
   rows where `hidden = true` to participants. Filter on the server with
   `.eq('hidden', false)` for participant-facing reads.

3. **Validate challenge timing and attempt limits.** Respect `open_at`,
   `close_at`, `previewable_at`, `max_attempts`, and `max_daily_attempts` before
   accepting a submission or starting a session.

4. **Honor whitelisting.** When `whitelisted_only` is set, only admit emails
   present in `nova_challenge_whitelisted_emails`.

5. **Read scores from the aggregate view.** Use `nova_submissions_with_scores`
   instead of recomputing from `nova_submission_criteria` /
   `nova_submission_test_cases` in application code.

### ❌ DON'T

1. **Don't add a Nova tRPC router or `@/lib/nova` server-action layer.** Nova
   has neither; product data flows through the Nova `/api/v1/*` routes and
   `packages/internal-api` helpers.

2. **Don't read Nova tables directly from the client.** All `private.nova_*`
   access goes through service-role route handlers after authorization.

3. **Don't invent score columns on `nova_submissions`.** Scores are derived from
   the per-criterion and per-test-case child tables.

## Related Documentation

* [TanStack + Rust migration](/platform/architecture/tanstack-rust-migration) - the broader move away from `apps/web`
* [Mail satellite app](/platform/applications/mail) - the canonical satellite auth pattern
* [Authentication](/platform/architecture/authentication) - cross-app login and sessions
* [Database overview](/reference/database/schema-overview) - shared schema conventions

## Future Enhancements

* **Richer team challenges** - deeper collaborative prompt engineering flows
* **Live leaderboards** - real-time ranking surfaced from the leaderboard views
* **Prompt history** - version control for participant submissions
* **Advanced metrics** - token usage and latency analysis per submission
* **Custom evaluation** - configurable, criterion-weighted scoring functions


# QR
Source: https://docs.tuturuuu.com/platform/applications/qr

Public QR generator app hosted at qr.tuturuuu.com.

## Overview

`apps/qr` serves the public Tuturuuu QR generator at
`https://qr.tuturuuu.com`. It owns the QR generator UI and reuses the shared
`@tuturuuu/ui/custom/qr/qr` component.

The app is public and does not own workspace auth, app-session cookies, or
protected APIs. Existing `apps/web` QR generator routes are compatibility
redirects to the QR app root.

The root layout uses `@tuturuuu/satellite/providers` so the public QR surface
still supports `system`, `light`, and `dark` theme switching through the shared
`next-themes` shell.

## Routing Contract

* `/`: canonical QR generator.
* `/en` and `/vi`: canonicalize back to `/` while storing `NEXT_LOCALE`.
* `apps/web /qr-generator`: redirects to `qr.tuturuuu.com/`.
* `apps/web /{wsId}/qr-generator`: redirects to `qr.tuturuuu.com/` without
  forwarding the workspace ID.

Query strings are preserved during compatibility redirects.

## Local Development

* `bun dev:qr` starts the app through Portless.
* Local app origin: `https://qr.tuturuuu.localhost`.
* Direct fallback port: `7819`.
* App URL overrides: `QR_APP_URL` or `NEXT_PUBLIC_QR_APP_URL`.

## CI/CD

Preview and production deployments use dedicated Vercel workflows:

* `.github/workflows/vercel-preview-qr.yaml`
* `.github/workflows/vercel-production-qr.yaml`

Both workflows are registered in `tuturuuu.ts` and use the shared
`ci-check.yml` switchboard with affected-path gating. They require
environment-scoped Vercel credentials:

* preview environment: `vercel-preview-qr`
* production environment: `vercel-production-qr`
* project secret: `VERCEL_QR_PROJECT_ID`
* shared secrets: `VERCEL_TOKEN` and `VERCEL_ORG_ID`

The app-specific project secret should live in those GitHub Environments, not in
workflow-level `env`.

## Validation

Use these focused checks when changing QR app routing or deployment wiring:

```bash theme={null}
bun type-check:qr
bun --cwd apps/web vitest run src/lib/qr-app-url.test.ts 'src/app/[locale]/(dashboard)/[wsId]/qr-generator/page.test.ts' 'src/app/[locale]/(marketing)/qr-generator/page.test.ts'
bun --cwd packages/utils test src/__tests__/app-url.test.ts
node --test scripts/portless-config.test.js
node --test scripts/ci/check-workflow-config.test.js scripts/ci/release-workflows.test.js
```

Because QR touches TypeScript, workflow config, docs navigation, and
translations, finish QR changes with `bun check` when the shared worktree state
allows it.


# Daily and Periodic Reports
Source: https://docs.tuturuuu.com/platform/applications/reports

Configure, approve, deliver, and troubleshoot daily, weekly, monthly, quarterly, and yearly workspace reports.

The Contacts Reports hub at `/{wsId}/reports` is the canonical workspace surface
for operational reporting. It keeps two established data models separate while
giving managers one consistent workflow:

* **Daily reports** are existing user-group posts. Their permissions and email
  behavior remain unchanged.
* **Periodic reports** extend the existing monthly-report records to weekly,
  monthly, quarterly, and yearly cadences. Monthly is the default.
* **Automations** configure workspace schedules, optional group overrides,
  generation runs, sender readiness, and delivery history.

Legacy `/posts` and `/users/reports` links redirect into the corresponding hub
tab and preserve their filters. The canonical hub opens **Daily** by default
when the actor can view daily reports; explicit Periodic and Automations links
still open their requested tab.

```mermaid theme={null}
flowchart LR
  history["Scoped workspace history"] --> draft["Editable report draft"]
  manual["Manager-authored content"] --> draft
  ai["AI-authored narrative"] --> draft
  draft --> review["Explicit manager review"]
  review -->|Approved| gates["Email safety gates"]
  review -->|Rejected| draft
  gates --> queue["Idempotent email queue"]
  queue --> audit["Delivery attempt and sent-email audit"]
```

## Calendar periods

Periods are calculated in the workspace timezone:

| Cadence   | Boundary              | Scheduled draft behavior       |
| --------- | --------------------- | ------------------------------ |
| Weekly    | Monday through Sunday | AI draft after Sunday closes   |
| Monthly   | Calendar month        | Default cadence                |
| Quarterly | Q1 through Q4         | Draft after the quarter closes |
| Yearly    | Calendar year         | Draft after December 31 closes |

Manual schedules create an editable draft at the start of the period. AI
schedules generate after the period closes. The default delivery target is
09:00 on the first day after close. Automation remains disabled until a valid
IANA timezone and an enabled schedule are saved.

## Generation and approval

Managers can create a periodic report at any time. An AI generation request is
scoped to the report subject and group, including configured metrics, relevant
history, profile notes, a previous report, and an editable manager instruction.
Unrelated workspace users and groups must never enter the prompt.

Deterministic scores and structured metrics are stored independently from the
generated narrative. Every AI-generated report starts in a reviewable state and
must be explicitly approved before delivery can be queued. Regeneration never
bypasses that approval boundary.

The principal permissions are:

* `view_user_groups_reports` — view daily and periodic reporting.
* `manage_user_report_automation` — configure schedules and initiate
  generation.
* `send_user_group_report_emails` — preview and control periodic email
  delivery.

Existing group-post permissions continue to govern Daily reports.

## Email safety

Periodic report email requires all of the following:

1. The report is approved.
2. The report subject has a workspace-profile email.
3. Workspace secret `ENABLE_EMAIL_SENDING=true`.
4. Workspace secret `ENABLE_REPORT_EMAIL_SENDING=true`.
5. A valid workspace sender is configured.
6. The actor has `send_user_group_report_emails`.

The dedicated report gate defaults to disabled and does not change Daily report
delivery. It is discoverable by platform admins in **Settings → Secrets**, where
the readiness card shows both gates and sender state and offers a prefilled
action for the periodic gate.

Delivery goes exclusively to the subject workspace-profile email. The system
does not infer an alternate address. Preview never queues an email. Test send,
send, retry, and cancel are explicit actions, and each transition remains
auditable.

## Automation processor

Vercel calls `/api/cron/process-report-automation` every 15 minutes. Private
Postgres RPCs claim due work idempotently. The processor uses:

* bounded concurrency;
* unique period/schedule claims;
* retry backoff and next-attempt timestamps;
* stale-lock recovery;
* permanent-failure diagnostics;
* separate generation-run and email-attempt histories.

The Next.js API remains the production source of truth. New reporting paths are
registered in the TanStack migration manifest until the Rust backend is ready
for an explicit cutover.

## Operating checklist

Before enabling a workspace:

1. Set a valid workspace timezone.
2. Confirm the intended managers have automation and delivery permissions.
3. Configure and verify the workspace email sender.
4. Enable the general email gate.
5. Create a manual schedule first and inspect its draft.
6. Enable the periodic-report gate.
7. Preview and test-send one approved report.
8. Confirm the recipient, sent-email record, and delivery-attempt history.
9. Enable AI generation only after the manual path is understood.

<Warning>
  Never enable either gate merely to make a readiness badge green. Confirm the
  workspace recipient data and sender first. AI-generated content must still be
  reviewed for accuracy and appropriateness.
</Warning>

## Troubleshooting

### A report cannot send

Open the Automations tab and inspect delivery readiness. Common blockers are a
pending approval, missing subject email, disabled gate, missing sender, or
insufficient permission. The report retains the last delivery error.

### A scheduled report did not appear

Verify the schedule is enabled, the timezone is valid, and the expected period
has closed for AI mode. Check recent generation runs for a failed or recovered
claim. Manual schedules create drafts at period start rather than after close.

### Delivery is queued for too long

Inspect the email queue attempt history and processor logs. A stale processing
claim is recoverable; repeated permanent failures preserve their error instead
of silently retrying forever. Confirm global email infrastructure, blacklist,
unsubscribe, rate-limit, and sender diagnostics.

### Recipient is unexpected

Cancel the queued delivery immediately. Periodic delivery must use only the
subject's workspace-profile email. Correct that profile, then preview again
before retrying.

### Daily and periodic totals differ

Daily reports count group-post completion and delivery. Periodic reports count
subject reports by cadence and approval/delivery state. They intentionally use
different underlying models and should not be summed as the same metric.

Periodic summary cards use a private aggregate RPC rather than materializing
report rows in the application. This keeps totals exact beyond PostgREST's
default row limit. The report list remains independently paginated and can load
every matching record without using the summary result as a page.

## Verification

Schema changes must be prepared as additive migrations and validated locally;
do not push production migrations from an agent session. Minimum release
validation includes:

* pgTAP coverage for the compatibility defaults, private tables, RLS, claims,
  and permissions;
* timezone boundary tests for every cadence;
* route/service tests for permission and email-gate combinations;
* component tests for hub tabs, mobile dialogs, filters, and error states;
* E2E coverage for manual and AI approval flows, blocked delivery, retry, audit
  history, and legacy redirects;
* Contacts and Web builds plus `bun check`.


# Shiraoki
Source: https://docs.tuturuuu.com/platform/applications/shiraoki

How Shiraoki is wired as a Shopify-backed external storefront through Tuturuuu CMS and app coordination.

Shiraoki is a standalone headless Shopify storefront in the sibling
`../shiraoki` repository. Tuturuuu does not own Shiraoki commerce records.
Tuturuuu owns the external-project binding, CMS configuration, launch gate,
central login handoff, and app-token access used by Shiraoki admin/account
surfaces.

## Ownership Boundary

Keep the data split explicit:

* Shopify owns products, variants, inventory availability, cart checkout URLs,
  payment completion, customer addresses, and order history.
* Shiraoki owns the storefront runtime, local server helpers, route transitions,
  cart UI, product gallery, account center, and owner admin workflow.
* Tuturuuu owns CMS configuration, workspace binding, external app
  registration, app-token exchange, launch-gate content, navigation, editorial
  sections, and shopper-only data that is not naturally Shopify-owned.

Do not duplicate Shopify products into Tuturuuu CMS records for normal catalog
operation. CMS records should only hold presentation/configuration metadata.

## Platform Adapter

The platform adapter ID is `shiraoki`.

The adapter is registered in:

* `apps/web/src/lib/external-projects/constants.ts`
* `apps/web/src/lib/external-projects/fixtures.ts`
* `apps/cms/src/features/cms-studio/constants.ts`
* `packages/types/src/supabase.ts`
* `apps/database/supabase/migrations/20260517141000_add_shiraoki_external_project_adapter.sql`

The canonical project created by setup routes should be `shiraoki-main`.
Workspace bindings must point at a canonical project whose adapter is
`shiraoki`, or app-token exchanges for Shiraoki external-project scopes will
be rejected.

## CMS Collections

Shiraoki's default CMS collection slugs are:

* `site-config`: brand name and portable storefront identity
* `launch-gate`: password screen state, copy, and early-access passphrase
* `navigation`: storefront nav labels and hrefs
* `editorial-sections`: minimal home-page supporting sections
* `shopify-settings`: active Shopify presentation settings, such as featured
  collection handle

These collection slugs are defined in both `apps/web` and `apps/cms` so the
root platform console and standalone CMS app agree on adapter defaults.

## External App Registration

Register Shiraoki from the Infrastructure external-app registry before using
live auth:

1. Create external app ID `shiraoki`.
2. Add every allowed Shiraoki origin, for example
   `http://localhost:3000`, staging origins, and the production storefront
   domain.
3. Allow only the scopes Shiraoki needs. For admin/CMS setup use
   `external-projects:*`; for preview or read-only storefront access prefer
   `external-projects:read`.
4. Issue an app secret and store it in Shiraoki as `TUTURUUU_APP_SECRET`.

The secret is shown once. Tuturuuu stores only the hash in root workspace
secrets.

## Auth Flow

Shiraoki sends users to `apps/web` login with a return URL pointing back to
`/verify-token?nextUrl=...` on the Shiraoki origin.

After login, `apps/web` validates that the return origin belongs to the
registered Shiraoki external app and adds a short-lived cross-app token to the
return URL. Shiraoki then calls:

```http theme={null}
POST /api/v1/auth/app-token/exchange
```

with `appId: "shiraoki"`, the app secret, the handoff token, requested scopes,
and the bound workspace ID when external-project scopes are requested.

The exchange succeeds only when:

* the Shiraoki app secret is valid
* the cross-app token targets `shiraoki`
* the workspace has external projects enabled
* the workspace binding's canonical adapter is `shiraoki`
* the user has the permission required by the requested external-project scope

If the user is invited to the bound workspace but has not accepted yet, the
exchange returns `403` with `code: "PENDING_WORKSPACE_INVITE"`, the normalized
`workspaceId`, and an `invitationUrl`. Shiraoki should route the user to that
URL, or show an action that opens it, before displaying generic no-access copy.
After the invitation is accepted, Shiraoki should retry the exchange; normal
workspace and external-project permission checks still apply.

Shiraoki should store the returned bearer token in its own HttpOnly session
cookie and call Tuturuuu APIs with that token. Do not give Shiraoki production
Supabase service-role credentials.

## Environment

Shiraoki expects these runtime variables:

```bash theme={null}
SHOPIFY_STORE_DOMAIN=your-shop.myshopify.com
SHOPIFY_STOREFRONT_ACCESS_TOKEN=...
SHOPIFY_ADMIN_ACCESS_TOKEN=...
SHOPIFY_API_VERSION=2026-01
TUTURUUU_WEB_APP_URL=https://tuturuuu.com
TUTURUUU_APP_ID=shiraoki
TUTURUUU_APP_SECRET=...
TUTURUUU_CMS_WORKSPACE_ID=...
NEXT_PUBLIC_SHIRAOKI_SITE_URL=https://shiraoki.example
SHIRAOKI_STOREFRONT_PASSWORD=...
```

Store Shopify Admin API credentials only on trusted server runtimes or platform
workspace secrets. Never expose Admin API tokens to client code.

## Local Development

From the Shiraoki repo:

```bash theme={null}
bun run lint
bun run build
bun run dev -- -p 3000
```

When Shopify credentials are absent, Shiraoki falls back to demo products and a
demo cart so product pages, dark mode, responsive catalog layout, and cart UI
remain testable.

For local Tuturuuu auth, run the central platform app and register the local
Shiraoki origin as an external app:

```bash theme={null}
TUTURUUU_WEB_APP_URL=http://localhost:7803
NEXT_PUBLIC_SHIRAOKI_SITE_URL=http://localhost:3000
TUTURUUU_APP_ID=shiraoki
```

## Operational Checks

After platform adapter changes, run focused checks first:

```bash theme={null}
cd apps/web
bun run test src/lib/external-projects/fixtures.test.ts src/lib/external-projects/access.test.ts
bun run test src/app/api/v1/auth/app-token/exchange/route.test.ts
bun run type-check

cd ../cms
bun run type-check
```

Run `bun check` from the platform root before landing the change when the
worktree is not blocked by unrelated dirty files.


# Storefront
Source: https://docs.tuturuuu.com/platform/applications/storefront

Public and private inventory storefronts with Polar and Square Terminal checkout.

`apps/storefront` is the buyer-facing Inventory commerce app. Operators manage
catalog, stock, storefront visibility, and checkout-provider settings in
`apps/inventory`; buyers browse, cart, and start checkout from
`storefront.tuturuuu.com`.

## Hosts

* Production: `https://storefront.tuturuuu.com`
* Local Portless: `https://storefront.tuturuuu.localhost`
* Local fallback port: `7822`

The Storefront app rewrites `/api/*` to `apps/web`, matching other satellite
apps. It does not read Supabase directly from client code.

## Access

Published public storefronts are readable anonymously. Published private
storefronts require a Tuturuuu app session and workspace membership; guest-type
workspace members are accepted.

## Theme and lifecycle

The Inventory storefront editor offers a **Native** accent mode as the safe
default. Native mode leaves `accent_color` unset so Storefront inherits its
theme-aware primary, focus, and contrast tokens in both light and dark mode.
Choose **Custom** only when a fixed hexadecimal brand color must override those
tokens.

Removing a storefront is deliberately non-destructive. Inventory marks the
storefront as removed, releases its former public slug for reuse, invalidates
the old public cache entry, and hides it from operator and buyer discovery.
Checkout sessions, order history, stock movements, and audit references keep
their original storefront row. Archiving remains the reversible choice for a
storefront that may return later.

## Polar Checkout

Each workspace can save sandbox and production Polar organization tokens from
Inventory settings. Tokens are encrypted server-side and only masked metadata is
returned to clients.

Storefront checkout reserves inventory first, creates a Polar checkout session
with the workspace-owned private one-time product, and redirects the buyer to
Polar. If Polar checkout creation fails after reservation, the reservation is
released immediately.

## Square Terminal Checkout

Square Terminal checkout is a staff-only pay-at-terminal handoff. A signed-in
member needs the dedicated **Start POS checkout** permission (or Admin), then
selects the paired payment station that should receive the order. Storefront
validates the member, device, and selling location before creating a local
reservation and sending the Square request. Repeated dispatches are rate
limited before reservation.

Square POS App + Reader uses a different same-device handoff: it opens Square
POS on the compatible phone or tablet currently running the Storefront and
cannot target another reader remotely. The checkout UI states this distinction
instead of presenting phone installation IDs as routable Terminal devices.

Square payment success is accepted only from verified Square webhook or status
data. Cancellation, failure, or expiry releases the local reservation so stock
returns to availability. Abandoned reserved sessions are materialized as expired
by the Inventory sweeper as well as lazy checkout reconciliation. Catalog and
physical stock can be synchronized in either direction from Inventory settings;
Square-side updates are additive and never delete or archive Square objects.

## Cache and invalidation contract

Published storefront payloads use Next.js Cache Components with a cache tag per
storefront slug. The data cache has a long safety-net lifetime and is refreshed
by events rather than by polling. Any operation that changes shopper-visible
catalog data or availability must invalidate the affected tag before returning
success. This includes product and stock edits, reservations, reservation
release or expiry, completed sales, provider reconciliation, and inbound Square
catalog sync.

Checkout reservation code must continue to read fresh stock directly. A cached
browse response is only a presentation optimization and must never be used as
the source of truth for reserving or consuming inventory.

Storefront routes stream `loading.tsx` and explicit Suspense fallbacks while
request-specific buyer and access data resolves. Server data seeds the TanStack
Query cache, internal links use Next.js navigation, and the browser must not
repeat the initial storefront request on mount.

## Cache E2E test

Start local Supabase, then run the Inventory-owned cross-app Playwright suite:

```bash theme={null}
bun sb:start
bun --cwd apps/inventory test:e2e
```

The test creates a disposable public storefront, warms the cached API payload,
changes stock through the authenticated Inventory API, and verifies the next
public read sees the new quantity. It also confirms the product route streams a
skeleton, uses Next's `@next/playwright` `instant()` helper to prove that the
prefetched loading shell commits before dynamic data resumes, keeps Storefront
navigation client-side, and removes the entire fixture in cleanup. Keep both
Inventory (`7815`) and Storefront (`7822`) server entries in
`apps/inventory/playwright.config.ts` whenever either app's local host or
startup command changes. The `Inventory / Storefront cache contract` job in
`.github/workflows/e2e-tests.yaml` runs this suite in parallel with the broader
platform E2E matrix and uploads Playwright traces and the HTML report when it
fails.


# Tasks - Task Management
Source: https://docs.tuturuuu.com/platform/applications/tasks

Hierarchical task management with bucket dump and cross-board coordination

# Tasks - Smart Task Management

Tasks is Tuturuuu's intelligent task management system featuring a 6-level hierarchy, bucket dump for rapid capture, and cross-board project coordination.

## Overview

Tasks provides:

* **Hierarchical organization** - 6 levels from workspaces to individual tasks
* **Bucket dump** - Capture notes and convert to tasks/projects
* **Cross-board projects** - Coordinate tasks across multiple boards
* **Task cycles** - Sprint/iteration management
* **Smart estimation** - Fibonacci, exponential, linear, and t-shirt sizing
* **Custom statuses** - Per-board status workflows
* **Labels & priorities** - Flexible categorization

## Board And List Name Uniqueness

* Active and archived task board names are unique per workspace using `lower(btrim(name))`; only trashed boards with `deleted_at` set release the name.
* Non-deleted task list names are unique per board using `lower(btrim(name))`, regardless of status/category.
* Duplicate board writes return `409` with `code: "TASK_BOARD_NAME_EXISTS"`. Duplicate list writes return `409` with `code: "TASK_LIST_NAME_EXISTS"`.
* Existing duplicate rows are preserved by the forward migration that renames older duplicates with a deterministic ` (duplicate <id>)` suffix before the unique indexes are created. The migration does not move or delete tasks.

## Satellite Auth And API Ownership

`apps/tasks` is registered internally as the `tasks` app. App-session checks,
cross-app token verification, and Web API allowlists should use
`targetApp: 'tasks'` unless a route explicitly accepts another first-party
audience such as the CLI's Web-minted `targetApp: 'platform'` task tokens.

`apps/tasks` is also the canonical owner for authenticated task product pages
and task-owned APIs. Do not add new task UI or task API behavior to `apps/web`.
Old authenticated Web task URLs should stay as redirects to the Tasks origin,
while `/products/tasks` remains Web-owned marketing content. Task-owned API
families include tasks, task boards, board aliases, labels, templates,
projects, initiatives, cycles, drafts, task progress, plans, shared task links,
admin task embeddings, task webhooks, task cron routes, Mira task endpoints,
habits, and habit trackers.

First-party task clients should resolve the Tasks origin through
`TASKS_APP_URL`, `NEXT_PUBLIC_TASKS_APP_URL`, or `TUTURUUU_TASKS_BASE_URL`.
Legacy `TUDO_APP_URL` and `NEXT_PUBLIC_TUDO_APP_URL` are accepted only as
compatibility aliases. Local development falls back to the Tasks app origin
(`http://localhost:7809` or the matching portless Tasks domain). SDK, CLI,
mobile, and `packages/internal-api` task-domain helpers should use that Tasks
origin outside `apps/tasks`; inside `apps/tasks`, relative API calls are still
preferred.

Tasks may serve credentialed browser API traffic from first-party Web/platform
origins, but CORS must stay origin-specific. Do not use wildcard credentialed
CORS for task APIs.

### Task Embedding Webhook Operations

The Supabase task embedding webhook must send its configured shared secret in
the `x-webhook-secret` header. Set `SUPABASE_WEBHOOK_SECRET` in the Tasks
deployment and use the same value in the Supabase Database Webhook header
configuration. Use a secret placeholder in local examples and operational
documentation; never record the deployed value.

The route fails closed before parsing the payload or creating an admin Supabase
client. Missing or empty server configuration returns a server configuration
error, while an absent or mismatched request header returns `401 Unauthorized`.

CLI task commands call the Tasks origin with bearer app-session tokens minted by
`apps/web`. The Tasks proxy must pass `ttr_app_...` bearer tokens to route-level
`withSessionAuth` so the route can verify CLI scope, expiry, and target-app
allowlists. Production `apps/web` and `apps/tasks` must share
`TUTURUUU_APP_COORDINATION_SECRET`, or the same accepted fallback signing
secret, or freshly minted CLI tokens will be rejected as `Unauthorized`.

The local `/api/auth/verify-app-token` route must delegate token validation to
the central Web verifier with `verificationBaseUrl: TTR_URL`. That handoff sets
both the host-only Tasks app-session cookie and the Web-issued app-session
cookie used by central API requests. Do not reintroduce Tasks-local Supabase
session validation for cross-app login.

Tasks must also keep a local `/login` page. It is a redirect-only route: valid
Tasks app-session cookies continue to `/personal/tasks` or the safe `next`
path, while missing or stale cookies redirect to `apps/web` login with a
`/verify-token` return URL. Without this route, a successful Web handoff can set
cookies and still leave the browser on a Next.js 404.

The Tasks app should not authenticate protected product APIs with local
Supabase Auth cookies. Fallback `/api/*` traffic is proxied through the local
catch-all API route, which strips `sb-*-auth-token` cookies before forwarding to
Web. Keep the corresponding Web routes app-session aware for
`targetApp: 'tasks'`; otherwise the browser can have valid Tasks cookies while
the data layer still loops through `401` and proxy-side `429` responses.

Task board/list count endpoints must compute counts in the database, preferably
through private service-role RPCs, and return one aggregate row per board/list.
Do not hydrate every matching `tasks` row in an API route just to count them.

## Board Capacity Rules

Board capacity rules provide reusable work-in-progress controls for task queues.
Rules can select lists, labels, and projects; selector dimensions combine with
AND, while labels and projects can use Any or All matching. A matching task is
counted once even when several relations match. Rules can measure task count or
estimation points and can count active tasks (the default) or all non-deleted
tasks.

Authenticated clients use these Tasks-owned routes:

* `GET/POST /api/v1/workspaces/{wsId}/task-boards/{boardId}/capacity-rules`
* `PATCH/DELETE /api/v1/workspaces/{wsId}/task-boards/{boardId}/capacity-rules/{ruleId}`

Joined workspace members and direct board guests may read capacity status. Only
joined members with `manage_projects` may configure rules. Hard limits are
enforced in PostgreSQL under a board-scoped transaction lock so browser, CLI,
guest, bulk, and API writes share the same admission decision. Rejected writes
return `409` with `code: "TASK_CAPACITY_EXCEEDED"` and structured rule usage.
Successful task writes may include `capacityWarnings` for exceeded soft rules.

Active tasks are non-deleted, not completed or closed, and outside `done` and
`closed` lists. Missing estimation points contribute zero. A rule whose selected
list, label, or project is deleted is disabled automatically, preventing an
empty selector from accidentally broadening its scope.

## Rich Text Editor Notes

The task editor includes isolated React roots inside some Tiptap node views, especially task mention chips.

* Do not mount `next-themes` `ThemeProvider` inside those isolated `createRoot(...)` islands. `next-themes` injects an inline script, and Next.js 16 will warn or fail when that script is rendered from a client subtree instead of the app root.
* Resolve theme for those islands from `document.documentElement` and `prefers-color-scheme`, then pass that resolved value through local component state instead of re-creating app-wide providers.
* Add `referrerPolicy="strict-origin-when-cross-origin"` to every YouTube iframe path used by the task editor or its previews. Missing referrer policy can surface as YouTube `Error 153` even when the video URL itself is valid.

## Task Link Notes

* Canonical deep links for board tasks should use the board route with the task query parameter: `/{wsId}/tasks/boards/{boardId}?task={taskId}`.
* Tuturuuu Mobile normalizes production web links from `https://tuturuuu.com` into native routes for task boards, board task details, task estimates, task portfolio/project routes, and common workspace modules. Mobile accepts both `?task={taskId}` from web and `?taskId={taskId}` from native routes.
* Links can opt out of native app opening with `native=0` or `openInBrowser=1`. Use this for flows that must stay in the browser, such as debugging, web-only admin surfaces, or temporary compatibility issues.
* Avoid generating or persisting modal-only URLs such as `/{wsId}/tasks/{taskId}` for share/copy flows unless the dedicated task detail page is the explicit target. The board-backed URL is the reliable reloadable path used by the dashboard task dialog.
* When reloading or recovering a task deep link, resolve the task through the workspace-scoped task API (`/api/v1/workspaces/{wsId}/tasks/{taskId}`) rather than the current-user task dialog API. The current-user endpoint can 404 for valid board tasks because it is optimized for dialog hydration, not route recovery.
* Android opens supported links by default only after App Links verification succeeds. Keep `apps/web/public/.well-known/assetlinks.json` in sync with the production Android signing certificate fingerprint; if Play App Signing uses a different app-signing certificate than the repo release keystore, add the Play Console SHA-256 fingerprint before release.
* Keep `GoRouter.overridePlatformDefaultLocation` enabled in mobile. iOS can provide a universal link URL as Flutter's platform default route on cold start, and GoRouter will show a no-route page unless `app_links` is allowed to normalize that URL first.

## Mobile Board List Mode Notes

* Mobile board list mode hides `documents`, `done`, and `closed` task lists by default when no explicit list or status filter is selected.
* The filter sheet must disclose that default exclusion and indicate when a selected list/status filter overrides it, because those filters intentionally reveal otherwise hidden list categories.
* Moving a task between lists, including marking it done or closed, should refresh the affected source and destination lists instead of relying on a full board reload.

## Task Board Realtime And Cache Notes

* Successful task mutations must update visible TanStack Query caches in place before broadcasting. Patch all visible task shapes that can render the same card: `['tasks', boardId]`, every `['tasks-full', boardId, ...]` query, `['task', taskId]`, matching `['workspaceTask', wsId, taskId]`, and personal task buckets when present.
* Relation-only updates for labels, projects, and assignees should broadcast `task:relations-changed` and call the active board refresh with `{ invalidateTasks: false }`. Do not invalidate `['tasks', boardId]` or `['tasks-full', boardId]` after successful relation-only changes; refetching those visible arrays causes card flicker while the optimistic cache already has the relation data.
* Scalar task changes such as priority, dates, estimate, name, and list should patch visible task caches and broadcast `task:upsert` with the changed fields. Rollbacks should restore snapshots of the touched task ids instead of invalidating the whole board task cache.
* Realtime receivers may reconcile task detail, history, counts, and personal task queries in the background. The board page should revalidate loaded progressive-list data without invalidating visible task arrays so shared boards stay current without remounting cards.
* Task edit dialogs should keep dropdowns and popovers controlled from a single active overlay id within each dialog section. Opening another menu must close the previous one, and outside-click/Escape close behavior should flow through the same `onOpenChange` path.

## AI Journal Capture Notes

* The quick-journal endpoint at `/api/v1/workspaces/{wsId}/tasks/journal` is a two-step flow: preview requests may invoke AI, but save requests that already include reviewed `tasks` plus a `listId` must persist directly.
* Do not re-resolve the AI model, re-check credits, or regenerate tasks during that save step. A successful preview must be able to save even if model allocation changes afterward.
* When the destination picker allows switching workspaces, clear the currently selected board/list immediately in the same UI event before loading the new workspace boards. Effect-only cleanup is too late for save flows and can send a stale `listId` that belongs to a different workspace.
* If the final create request fails, reopen the destination-selection step with the reviewed tasks still in memory. Do not clear the journal draft optimistically before the insert succeeds, or users can lose the prompt they just refined.
* Any workspace alias accepted by the board/list bootstrap endpoints, such as `personal`, must also be normalized by the journal save route before membership and list checks. Otherwise the picker can show valid destinations while the final save still rejects the same workspace context.
* The journal save route should verify workspace membership first with the request-scoped client, then validate the chosen list against that normalized workspace. Admin-backed list checks are fine for consistency with selector data, but they must never bypass the caller's workspace access gate.
* Any workspace-scoped project validation in that same save route should follow the same pattern: verify membership with the request-scoped client first, then resolve valid `task_projects` IDs through the admin client scoped to the normalized workspace. Do not read protected workspace project tables directly from the caller-scoped client after access has already been established.
* Any top-level `labelIds` or reviewed task `labels[].id` in that save route must be checked against `workspace_task_labels.ws_id` for the normalized workspace before task rows are inserted. Foreign workspace label IDs must fail the request instead of being carried into `task_labels`; labels created by name can still be upserted through the admin-backed workspace path after membership passes.
* After membership passes, persist the journal-created `tasks` rows and their relation-table writes (`task_labels`, `task_project_tasks`, `task_assignees`, label upserts) through the same admin-backed workspace path, and stamp actor-owned columns such as `creator_id` explicitly. Do not mix admin-backed validation with caller-scoped writes or the save step can still fail with table-level permission errors.

## Task Hierarchy

```
Workspaces (Top Level)
└── Task Initiatives (Strategic grouping)
    └── Task Projects (Cross-board coordination)
        └── Workspace Boards (Kanban boards)
            └── Task Lists (Columns)
                └── Workspace Tasks (Individual items)
```

### 1. Workspaces

Container for all workspace resources.

```typescript theme={null}
// Get workspace
const { data: workspace } = await supabase
  .from("workspaces")
  .select("*")
  .eq("id", wsId)
  .single();
```

### 2. Task Initiatives

Strategic initiatives grouping related projects.

```sql theme={null}
CREATE TABLE task_initiatives (
  id text PRIMARY KEY,
  ws_id text REFERENCES workspaces(id) ON DELETE CASCADE,
  name text NOT NULL,
  description text,
  start_date date,
  end_date date,
  created_at timestamptz DEFAULT now()
);
```

**Usage:**

```typescript theme={null}
"use server";

import { createClient } from "@tuturuuu/supabase/next/server";

export async function createInitiative(data: {
  wsId: string;
  name: string;
  description?: string;
  startDate?: Date;
  endDate?: Date;
}) {
  const supabase = await createClient();

  const { data: initiative, error } = await supabase
    .from("task_initiatives")
    .insert({
      ws_id: data.wsId,
      name: data.name,
      description: data.description,
      start_date: data.startDate?.toISOString().split("T")[0],
      end_date: data.endDate?.toISOString().split("T")[0],
    })
    .select()
    .single();

  if (error) throw error;
  return initiative;
}
```

### 3. Task Projects

Cross-functional projects coordinating tasks across boards.

```sql theme={null}
CREATE TABLE task_projects (
  id text PRIMARY KEY,
  ws_id text REFERENCES workspaces(id) ON DELETE CASCADE,
  name text NOT NULL,
  description text,
  created_at timestamptz DEFAULT now()
);

-- Link projects to initiatives
CREATE TABLE task_project_initiatives (
  project_id text REFERENCES task_projects(id) ON DELETE CASCADE,
  initiative_id text REFERENCES task_initiatives(id) ON DELETE CASCADE,
  PRIMARY KEY (project_id, initiative_id)
);

-- Link tasks to projects (cross-board)
CREATE TABLE task_project_tasks (
  project_id text REFERENCES task_projects(id) ON DELETE CASCADE,
  task_id text REFERENCES workspace_tasks(id) ON DELETE CASCADE,
  PRIMARY KEY (project_id, task_id)
);
```

**Usage:**

```typescript theme={null}
"use server";

import { createClient } from "@tuturuuu/supabase/next/server";

export async function createProject(data: {
  wsId: string;
  name: string;
  description?: string;
  initiativeIds?: string[];
}) {
  const supabase = await createClient();

  // Create project
  const { data: project, error } = await supabase
    .from("task_projects")
    .insert({
      ws_id: data.wsId,
      name: data.name,
      description: data.description,
    })
    .select()
    .single();

  if (error) throw error;

  // Link to initiatives
  if (data.initiativeIds && data.initiativeIds.length > 0) {
    await supabase.from("task_project_initiatives").insert(
      data.initiativeIds.map((initiativeId) => ({
        project_id: project.id,
        initiative_id: initiativeId,
      })),
    );
  }

  return project;
}

export async function addTaskToProject(projectId: string, taskId: string) {
  const supabase = await createClient();

  const { error } = await supabase.from("task_project_tasks").insert({
    project_id: projectId,
    task_id: taskId,
  });

  if (error) throw error;
}
```

### 4. Workspace Boards

Kanban-style task boards.

Personal workspaces should always have a default active task board named
`Tasks`. Web and mobile task-board listing APIs ensure that board exists before
returning board data, so users should not see a prompt just to bootstrap their
personal task workflow. Mobile opens that default board directly from both the
Tasks and Boards surfaces unless the user disables default task-board navigation
in mobile Settings. The web settings dialog exposes the same preference for the
Boards page, keeping the board picker available for users who prefer the
previous flow.

The Tasks board header also exposes a global create action. It lists only
workspaces where the caller has `manage_projects`, including workspaces that do
not yet contain a board, and opens the newly created board immediately. In the
Tasks settings dialog, each workspace can store a per-user
`TASK_DEFAULT_BOARD_ID`. The Tasks root/proxy entrypoint validates that saved ID
against active accessible boards before redirecting and falls back to the first
active board when the preference is empty or stale.

#### Task list status semantics

Task list `status` is a workflow category, not the list display name. The
`review` status sits between `active` and `done`: moving a task into a review
list resolves the task for deadline/reminder filtering, but it must not set
`completed`, `completed_at`, or `closed_at`. Review tasks should keep the same
unchecked checkbox and non-completed visual treatment used by active tasks.

Review lists are for walkthrough or acceptance queues. Task cards in `review`,
`done`, or `closed` lists should not show due-date or overdue treatment because
those tasks are already resolved for deadline purposes. Mobile list mode still
shows `review` lists by default; only `documents`, `done`, and `closed` are
hidden when no explicit list or status filter is selected.

#### Task description realtime

Task descriptions use a Yjs CRDT document stored in
`tasks.description_yjs_state`. Once that state exists, treat it as the
authoritative collaborative source. The JSON `tasks.description` field is the
read/search/cache projection and must not overwrite a valid Yjs state just
because it differs; board caches and recently opened dialogs can hold stale
description JSON while another collaborator has newer Yjs edits.

Initialization or repair writes that seed the local Yjs document from persisted
state must use the provider sync origin so those changes are not broadcast as
fresh user edits. Persistence should serialize the description projection from
the Yjs update being saved, keeping `description` and `description_yjs_state`
from diverging under multi-user edit churn.

The `ttr` CLI uses the same description endpoint and TipTap/Yjs codec as the web
editor. Prefer first-class description commands over raw task update payloads:

```bash theme={null}
ttr tasks description get <task-id>
ttr tasks description set <task-id> --file notes.md --format markdown
ttr tasks description append <task-id> --text "Follow-up note"
ttr tasks description edit <task-id>
```

For local conversion or debugging, use the login-free codec commands:

```bash theme={null}
ttr tiptap parse --input notes.md --format markdown --output json
ttr tiptap encode --input description.json --format json --output yjs-base64
ttr tiptap decode --input state.txt --format yjs-base64 --output text
```

#### Task templates

Task templates are reusable single-task starters and are intentionally separate
from board templates. Store workspace templates in `task_templates` with
creator ownership, `private` or `workspace` visibility, archived timestamps,
default board/list ids, priority, dates, estimate, labels, assignees, projects,
and optional TipTap/Yjs description state.

Template API routes live under
`/api/v1/workspaces/{wsId}/task-templates`. They must accept authenticated
workspace members and `tasks` app-session JWTs from `ttr`, reject direct
task-board guests, and keep private templates readable only by their creator.
Workspace-visible template mutation should follow the task/project management
permission used by task-board management flows; private template mutation stays
scoped to the member owner.

The web templates hub at `/{locale}/{wsId}/tasks/templates` should default to
the Task Templates tab while preserving Board Templates as the secondary tab and
keeping existing board-template detail links stable.

The CLI supports both workspace-stored and local markdown templates:

```bash theme={null}
ttr task-templates list --no-update-check
ttr task-templates create "Bug report" --key bug-report --title "Investigate bug"
ttr task-templates export bug-report --file .tuturuuu/task-templates/bug-report.md
ttr task-templates import .tuturuuu/task-templates/bug-report.md
ttr tasks create --template bug-report --list <list-id> --name "Investigate checkout bug"
```

Local files under `.tuturuuu/task-templates/*.md` use YAML frontmatter for
template fields and the markdown body as the task description. Explicit
`ttr tasks create` flags must override template defaults so users can reuse a
starter without losing the current task context.

#### Mobile board caching

The mobile task-board flow restores workspace boards, board metadata, and per-list
task pages from `CacheStore` before network revalidation. Board detail pages
prefetch the first three lists on open and the focused Kanban list plus the next
two lists on horizontal page changes, so column swipes should not wait for one
on-demand request at a time. Cached task-page payloads must preserve the display
metadata used by cards, including assignees, labels, projects, and relationship
summaries.

The mobile board List tab hides tasks in `done` and `closed` lists by default.
Explicit status filters or list filters are treated as user intent and can show
those terminal lists again.

Mobile task details open description in a read-first fullscreen surface. Keep
that surface borderless and height-bounded under the task title, with editing
entered only from the edit FAB and save actions kept inside the editor chrome.

Task create/update API routes silently drop assignee ids that no longer belong
to the workspace. This lets stale task assignments be cleaned up during the next
save instead of blocking unrelated edits such as description updates.

#### Timeline board view

The task board Timeline is task-first: `TimelineBoard` keeps its public props
stable for board and project views, while the internal model renders one
scheduled task per readable row grouped by task list. Task titles and source
metadata belong in the sticky left column; timeline bars should communicate the
date range only, so narrow zoom levels never hide task names behind clipped bar
labels.

Keep drag, resize, schedule-from-unscheduled, edit, delete, and context-menu
actions routed through the same board mutation path used by the other views.
The row model must preserve personal and external task metadata and keep
unknown-list tasks grouped under the virtual unknown-list section instead of
dropping them from the schedule.

#### Personal external tasks

Personal task boards can reference tasks from other workspaces without cloning
or moving the source task. Assigned tasks from accessible source workspaces
appear by default in a virtual `External tasks` lane on each personal board.
Explicit personal-board placements can also reference tasks from another board
inside the same personal workspace; those cards are external to the destination
board even though the source workspace is personal. Native tasks from the same
personal board must still move through the normal workspace task route instead
of the personal-placement route.
The tasks API may use the server-side admin client to hydrate candidate source
tasks, but it must filter those rows through the current user's source
`workspace_members` rows with `type = 'MEMBER'` before returning personal
default or placed external cards. A guest row in the source workspace is not
enough to reveal task data through the personal board.

The virtual lane is presentation-only: it has no `task_lists` row, no list
actions, no create-task form, no list reordering, and can be collapsed per board
when the user wants to focus on planned lists. Personal boards default the lane
to collapsed when the board has no assigned external task references; once
assigned external tasks exist, the lane opens by default unless the user has
saved an explicit collapsed or expanded preference for that board.

By default the external lane shows only open source tasks from normal task
lists. Source tasks in `documents`, `review`, `done`, or `closed` lists are
filtered out unless the lane-level compact filters explicitly include resolved
tasks. Lane sorting is
also local to the external lane, so changing it does not reorder the user's real
personal lists.

External task cards should show the source workspace and the source board's
ticket identifier. Opening an external task must resolve the task by id through
the current-user task route so the dialog receives the source workspace, source
board, and source lists instead of the personal board context.

Per-user placement lives on `task_user_overrides` with `personal_board_id`,
`personal_list_id`, `personal_sort_key`, `personal_added_at`, and
`personal_placed_at`.

Placement writes must go through `upsert_personal_task_placement`. Drag clients
should pass the previous and next visible task ids when available, and the RPC
uses `calculate_personal_task_placement_sort_key` to compute a sort key against
the combined personal list of native personal tasks and placed external task
references.

Per-list task loading for personal boards must include the personal `boardId`
alongside `listId`; the API needs both values to load placed external
references for real personal lists and to keep already-placed external tasks out
of the virtual external lane.

Optimistic personal-placement moves must keep a fresh `_localMutationAt` marker
after the placement API response is merged. Loaded-list revalidation may still
return a pre-move page briefly, and the marker prevents that stale response from
evicting the placed external task until the server view catches up.
Optimistic placement writes should upsert the task into both the progressive
board task cache and any full-board cache that is already mounted, because stale
list reloads can briefly remove the card before the destination list refetches.
The card renderer should hide only the active pre-drop drag source; once a
placement mutation is optimistic, the real destination card must stay visible
even if the sortable layer still reports that task id as dragging.
Native task reorders and external personal-placement moves should both stamp a
fresh `_localMutationAt` marker on optimistic writes and on the server-confirmed
cache merge. Progressive list loading treats that marker as authority for
movement fields such as `list_id`, `sort_key`, `personal_list_id`, and
`personal_sort_key`, which prevents stale list pages from flashing a card back
to its previous position while the mutation response is still settling.

Personal-board list badges must use exact `includeCount` responses, not a
page-size estimate from progressive loading. External reference counts should be
resolved through `get_personal_task_board_external_counts` so placed external
tasks, default external-lane tasks, source-workspace access, and external-lane
filters stay aligned with the records the board can actually show.

Board source filters use `TaskFilters.sourceScope` to decide which task source
set is visible. `all_visible` preserves the existing board behavior,
`current_board` returns only tasks from the active board, and the two external
scopes return assigned-to-me tasks whose source board is not the active board.
`external_current_workspace` stays inside the current workspace, while
`external_specific` requires selected source workspace ids or source board ids;
when nothing is selected, the client should show an empty prompt instead of
running an unbounded external query.

Source-filtered list and timeline reads must go through the tasks API route,
which normalizes the route workspace, verifies request-scoped membership, then
uses the server-side Supabase admin client to call the
`private.list_task_source_filter_ids` RPC. The RPC rechecks target workspace
membership and source workspace access before returning paginated task ids plus
`total_count` for API-side hydration. Client UI must not call the private RPC
directly or trust client-provided source ids as authorization.

* `personal_board_id` points to the destination personal board after an
  external task is planned there.
* `personal_list_id` points to the real personal list that owns the planning
  position.
* Dragging from the virtual lane into a real personal list creates or updates
  the personal placement.
* Dragging a placed external task back to the virtual lane removes the personal
  placement so the task returns to the default external view.
* Personal-only label and project overlays live in
  `task_user_override_labels` and `task_user_override_projects`. Those rows
  reference labels/projects owned by the user's personal workspace and are
  loaded only for that owner.

Source task fields, including `tasks.list_id`, `task_labels`, and
`task_project_tasks`, must not be changed when a task appears in the external
lane, is planned into a personal list, is moved within the personal board, or
returns to the external lane unless the personal move changes the task's
workflow status. Routes that read personal board tasks should keep filtering
inaccessible source tasks out instead of surfacing stale placements to users who
no longer have source-workspace access.

When a placed external task moves to a personal list with a different workflow
status, the source task must also move to the first matching list on its original
board. `done` and `closed` targets require the matching terminal source list.
Non-terminal targets first try the same source status, then fall back to
`active` and `not_started` lists so tasks moved out of source `done` or `closed`
queues do not keep completed or closed card state.

```sql theme={null}
CREATE TABLE workspace_boards (
  id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
  ws_id text REFERENCES workspaces(id) ON DELETE CASCADE,
  name text NOT NULL,
  description text,
  created_at timestamptz DEFAULT now()
);
```

**Usage:**

```typescript theme={null}
"use server";

import { createClient } from "@tuturuuu/supabase/next/server";

export async function createBoard(wsId: string, name: string) {
  const supabase = await createClient();

  const { data: board, error } = await supabase
    .from("workspace_boards")
    .insert({
      ws_id: wsId,
      name,
    })
    .select()
    .single();

  if (error) throw error;

  // Create default lists
  const defaultLists = ["To Do", "In Progress", "Done"];

  await supabase.from("task_lists").insert(
    defaultLists.map((listName, index) => ({
      board_id: board.id,
      name: listName,
      position: index,
    })),
  );

  return board;
}
```

### 5. Task Lists

Columns within boards (e.g., "To Do", "In Progress", "Done").

Task boards may contain multiple `closed` lists when teams need distinct terminal buckets such as `Abandoned`, `Not Planned`, or `Duplicate`. Treat `closed` as a status group for sorting/reporting, not a singleton board column.

```sql theme={null}
CREATE TABLE task_lists (
  id text PRIMARY KEY,
  board_id uuid REFERENCES workspace_boards(id) ON DELETE CASCADE,
  name text NOT NULL,
  position integer NOT NULL,
  created_at timestamptz DEFAULT now()
);
```

**Usage:**

```typescript theme={null}
"use server";

import { createClient } from "@tuturuuu/supabase/next/server";

export async function reorderLists(boardId: string, listIds: string[]) {
  const supabase = await createClient();

  // Update positions based on array order
  const updates = listIds.map((listId, index) => ({
    id: listId,
    position: index,
  }));

  for (const update of updates) {
    await supabase
      .from("task_lists")
      .update({ position: update.position })
      .eq("id", update.id);
  }
}
```

### 6. Workspace Tasks

Individual work items.

Task titles support up to `1024` characters. Keep task-only validation on the dedicated task-title limit rather than the generic `name` limit so task routes, drafts, and database checks stay aligned.

```sql theme={null}
CREATE TABLE workspace_tasks (
  id text PRIMARY KEY,
  ws_id text REFERENCES workspaces(id) ON DELETE CASCADE,
  list_id text REFERENCES task_lists(id) ON DELETE SET NULL,
  name text NOT NULL,
  description text,
  priority integer CHECK (priority BETWEEN 0 AND 5),
  completed boolean DEFAULT false,
  start_date date,
  due_date date,
  created_by uuid REFERENCES workspace_users(id),
  created_at timestamptz DEFAULT now(),
  updated_at timestamptz DEFAULT now()
);
```

## Bucket Dump Feature

Rapidly capture thoughts as notes, then convert to tasks or projects.

### Notes Table

```sql theme={null}
CREATE TABLE notes (
  id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
  ws_id text REFERENCES workspaces(id) ON DELETE CASCADE,
  title text NOT NULL,
  content text,
  created_by uuid REFERENCES workspace_users(id),
  created_at timestamptz DEFAULT now()
);
```

### Convert Note to Task

```typescript theme={null}
"use server";

import { createClient } from "@tuturuuu/supabase/next/server";

export async function convertNoteToTask(data: {
  noteId: string;
  listId: string;
  priority?: number;
}) {
  const supabase = await createClient();

  // Get note
  const { data: note } = await supabase
    .from("notes")
    .select("*")
    .eq("id", data.noteId)
    .single();

  if (!note) throw new Error("Note not found");

  // Create task from note
  const { data: task, error } = await supabase
    .from("workspace_tasks")
    .insert({
      ws_id: note.ws_id,
      list_id: data.listId,
      name: note.title,
      description: note.content,
      priority: data.priority,
      created_by: note.created_by,
    })
    .select()
    .single();

  if (error) throw error;

  // Optionally delete note
  await supabase.from("notes").delete().eq("id", data.noteId);

  return task;
}
```

### Convert Note to Project

```typescript theme={null}
"use server";

import { createClient } from "@tuturuuu/supabase/next/server";

export async function convertNoteToProject(data: {
  noteId: string;
  initiativeId?: string;
}) {
  const supabase = await createClient();

  const { data: note } = await supabase
    .from("notes")
    .select("*")
    .eq("id", data.noteId)
    .single();

  if (!note) throw new Error("Note not found");

  // Create project from note
  const { data: project, error } = await supabase
    .from("task_projects")
    .insert({
      ws_id: note.ws_id,
      name: note.title,
      description: note.content,
    })
    .select()
    .single();

  if (error) throw error;

  // Link to initiative if provided
  if (data.initiativeId) {
    await supabase.from("task_project_initiatives").insert({
      project_id: project.id,
      initiative_id: data.initiativeId,
    });
  }

  // Delete note
  await supabase.from("notes").delete().eq("id", data.noteId);

  return project;
}
```

## Task Cycles (Sprints)

```sql theme={null}
CREATE TABLE task_cycles (
  id text PRIMARY KEY,
  ws_id text REFERENCES workspaces(id) ON DELETE CASCADE,
  name text NOT NULL,
  start_date date NOT NULL,
  end_date date NOT NULL,
  created_at timestamptz DEFAULT now()
);

-- Link tasks to cycles
ALTER TABLE workspace_tasks
ADD COLUMN cycle_id text REFERENCES task_cycles(id) ON DELETE SET NULL;
```

**Usage:**

```typescript theme={null}
"use server";

import { createClient } from "@tuturuuu/supabase/next/server";

export async function createCycle(data: {
  wsId: string;
  name: string;
  startDate: Date;
  endDate: Date;
}) {
  const supabase = await createClient();

  const { data: cycle, error } = await supabase
    .from("task_cycles")
    .insert({
      ws_id: data.wsId,
      name: data.name,
      start_date: data.startDate.toISOString().split("T")[0],
      end_date: data.endDate.toISOString().split("T")[0],
    })
    .select()
    .single();

  if (error) throw error;
  return cycle;
}

export async function getActiveCycle(wsId: string) {
  const supabase = await createClient();
  const today = new Date().toISOString().split("T")[0];

  const { data: cycle } = await supabase
    .from("task_cycles")
    .select("*")
    .eq("ws_id", wsId)
    .lte("start_date", today)
    .gte("end_date", today)
    .single();

  return cycle;
}
```

## Task Estimation

```sql theme={null}
CREATE TABLE task_estimates (
  task_id text PRIMARY KEY REFERENCES workspace_tasks(id) ON DELETE CASCADE,
  type text NOT NULL, -- fibonacci, exponential, linear, tshirt
  value numeric NOT NULL,
  created_at timestamptz DEFAULT now()
);
```

**Estimation Types:**

* **Fibonacci**: 1, 2, 3, 5, 8, 13, 21
* **Exponential**: 1, 2, 4, 8, 16, 32
* **Linear**: 1, 2, 3, 4, 5, 6, 7, 8, 9, 10
* **T-Shirt**: XS (1), S (2), M (3), L (5), XL (8), XXL (13)

```typescript theme={null}
"use server";

import { createClient } from "@tuturuuu/supabase/next/server";

export async function estimateTask(
  taskId: string,
  estimationType: "fibonacci" | "exponential" | "linear" | "tshirt",
  value: number,
) {
  const supabase = await createClient();

  const { error } = await supabase.from("task_estimates").upsert({
    task_id: taskId,
    type: estimationType,
    value,
  });

  if (error) throw error;
}
```

## Task Labels

```sql theme={null}
CREATE TABLE task_labels (
  id text PRIMARY KEY,
  ws_id text REFERENCES workspaces(id) ON DELETE CASCADE,
  name text NOT NULL,
  color text,
  created_at timestamptz DEFAULT now()
);

-- Link tasks to labels (many-to-many)
CREATE TABLE task_label_assignments (
  task_id text REFERENCES workspace_tasks(id) ON DELETE CASCADE,
  label_id text REFERENCES task_labels(id) ON DELETE CASCADE,
  PRIMARY KEY (task_id, label_id)
);
```

**Usage:**

```typescript theme={null}
"use server";

import { createClient } from "@tuturuuu/supabase/next/server";

export async function createLabel(wsId: string, name: string, color: string) {
  const supabase = await createClient();

  const { data: label, error } = await supabase
    .from("task_labels")
    .insert({ ws_id: wsId, name, color })
    .select()
    .single();

  if (error) throw error;
  return label;
}

export async function assignLabel(taskId: string, labelId: string) {
  const supabase = await createClient();

  const { error } = await supabase
    .from("task_label_assignments")
    .insert({ task_id: taskId, label_id: labelId });

  if (error) throw error;
}
```

## Custom Task Statuses

```sql theme={null}
CREATE TABLE task_statuses (
  id text PRIMARY KEY,
  board_id uuid REFERENCES workspace_boards(id) ON DELETE CASCADE,
  name text NOT NULL,
  color text,
  position integer NOT NULL,
  is_completed boolean DEFAULT false,
  created_at timestamptz DEFAULT now()
);

-- Link tasks to statuses
ALTER TABLE workspace_tasks
ADD COLUMN status_id text REFERENCES task_statuses(id) ON DELETE SET NULL;
```

**Usage:**

```typescript theme={null}
"use server";

import { createClient } from "@tuturuuu/supabase/next/server";

export async function createBoardWithStatuses(wsId: string, boardName: string) {
  const supabase = await createClient();

  // Create board
  const { data: board } = await supabase
    .from("workspace_boards")
    .insert({ ws_id: wsId, name: boardName })
    .select()
    .single();

  if (!board) throw new Error("Failed to create board");

  // Create default statuses
  const statuses = [
    { name: "Backlog", color: "#gray", position: 0, is_completed: false },
    { name: "To Do", color: "#blue", position: 1, is_completed: false },
    { name: "In Progress", color: "#yellow", position: 2, is_completed: false },
    { name: "Review", color: "#purple", position: 3, is_completed: false },
    { name: "Done", color: "#green", position: 4, is_completed: true },
  ];

  await supabase.from("task_statuses").insert(
    statuses.map((status) => ({
      board_id: board.id,
      ...status,
    })),
  );

  return board;
}
```

## Task Dependencies

Track task relationships and blockers.

```sql theme={null}
CREATE TABLE task_dependencies (
  task_id text REFERENCES workspace_tasks(id) ON DELETE CASCADE,
  depends_on_task_id text REFERENCES workspace_tasks(id) ON DELETE CASCADE,
  PRIMARY KEY (task_id, depends_on_task_id),
  CHECK (task_id != depends_on_task_id)
);
```

**Usage:**

```typescript theme={null}
"use server";

import { createClient } from "@tuturuuu/supabase/next/server";

export async function addDependency(taskId: string, dependsOnTaskId: string) {
  const supabase = await createClient();

  const { error } = await supabase.from("task_dependencies").insert({
    task_id: taskId,
    depends_on_task_id: dependsOnTaskId,
  });

  if (error) throw error;
}

export async function getBlockedTasks(wsId: string) {
  const supabase = await createClient();

  const { data: tasks } = await supabase
    .from("workspace_tasks")
    .select(
      `
      *,
      task_dependencies!task_id (
        depends_on:workspace_tasks!depends_on_task_id (
          id,
          name,
          completed
        )
      )
    `,
    )
    .eq("ws_id", wsId)
    .eq("completed", false);

  // Filter tasks with incomplete dependencies
  return tasks?.filter((task) =>
    task.task_dependencies.some((dep: any) => !dep.depends_on.completed),
  );
}
```

## User Interface Components

### Board View

```tsx theme={null}
"use client";

import { trpc } from "@/trpc/client";
import { DragDropContext, Droppable, Draggable } from "@hello-pangea/dnd";

export function BoardView({
  wsId,
  boardId,
}: {
  wsId: string;
  boardId: string;
}) {
  const { data: lists } = trpc.boards.lists.useQuery({ boardId });
  const moveTask = trpc.tasks.move.useMutation();

  function handleDragEnd(result: any) {
    if (!result.destination) return;

    moveTask.mutate({
      taskId: result.draggableId,
      listId: result.destination.droppableId,
      position: result.destination.index,
    });
  }

  return (
    <DragDropContext onDragEnd={handleDragEnd}>
      <div className="flex gap-4">
        {lists?.map((list) => (
          <Droppable key={list.id} droppableId={list.id}>
            {(provided) => (
              <div
                ref={provided.innerRef}
                {...provided.droppableProps}
                className="min-w-75 bg-dynamic-gray/5 p-4 rounded-lg"
              >
                <h3>{list.name}</h3>
                {/* Task cards */}
                {provided.placeholder}
              </div>
            )}
          </Droppable>
        ))}
      </div>
    </DragDropContext>
  );
}
```

## Best Practices

### ✅ DO

1. **Use hierarchy appropriately**

   ```typescript theme={null}
   // Strategic: Initiative
   // Tactical: Project
   // Operational: Board → List → Task
   ```

2. **Leverage bucket dump**

   ```typescript theme={null}
   // Capture quickly, organize later
   await createNote({ title, content });
   ```

3. **Set task estimates**

   ```typescript theme={null}
   await estimateTask(taskId, "fibonacci", 8);
   ```

4. **Use labels for categorization**

   ```typescript theme={null}
   await assignLabel(taskId, "bug");
   await assignLabel(taskId, "high-priority");
   ```

5. **Track dependencies**
   ```typescript theme={null}
   await addDependency(taskId, blockerTaskId);
   ```

### ❌ DON'T

1. **Don't create deep hierarchies**

   ```typescript theme={null}
   // ❌ Bad: Too many nested levels
   ```

2. **Don't skip workspace isolation**

   ```typescript theme={null}
   // ❌ Bad
   .eq('id', taskId)

   // ✅ Good
   .eq('id', taskId).eq('ws_id', wsId)
   ```

## Related Documentation

* [Database Schema](/reference/database/schema-overview)
* [Data Fetching](/platform/architecture/data-fetching)
* [Authorization](/platform/architecture/authorization)


# Teach teacher companion app
Source: https://docs.tuturuuu.com/platform/applications/teach

Teacher-facing education companion app for Tuturuuu workspaces.

Teach lives in `apps/teach` and runs locally on port `7813`. It is the teacher-facing operations app for Tuturuuu education workspaces. Teachers create and publish courses, enroll existing workspace users, author modules, save attendance, write posts and reports, and enter metrics through Teach-owned APIs.

## Ownership model

Teach owns teacher authoring, administration, and shared education v1 API
contracts. Its handlers cover courses, modules, quiz sets, flashcards,
enrollment, attendance, posts, reports, metrics, attempts, grading, and related
teacher workflows under `apps/teach/src/app/api/v1`. Teach also implements
selected education AI handlers locally.

Local handlers run before the Next.js fallback rewrites. Only unmatched
`/api/v1/*` and `/api/ai/*` paths go to Web, which remains responsible for
platform login, cross-app token issuance, and explicitly retained platform or
central AI services. New Teach-owned flows should add typed helpers in
`@tuturuuu/internal-api` and consume those helpers from Teach client components
with TanStack Query.

`packages/education-core` owns reusable server-only domain logic, not HTTP
traffic. `packages/internal-api/src/teach.ts` and `education.ts` select the Teach
origin for teacher and shared education contracts; explicit platform
exceptions such as storage operations retain the Web origin.

When a Teach route uses an admin client to write rows keyed by request-body IDs, the route must validate those body IDs against the URL workspace and course before writing. Workspace permission plus course existence is not enough, because the admin client bypasses RLS; score writes such as `indicator_id` and `user_id` must prove that the indicator belongs to the URL course/workspace and the user is an active course member in the same workspace.

Courses are stored as `workspace_user_groups`. The course-level Learn visibility switch is `workspace_user_groups.is_course_published`; module visibility remains `workspace_course_modules.is_published`. New courses default to unpublished drafts, non-guest, active, and empty. Teach can enroll existing workspace users into a course, but this self-serve pass does not create or invite new users.

Teach-owned attendance uses the course schedule fields on `workspace_user_groups`: `sessions`, `starting_date`, and `ending_date`. Teachers can generate recurring class sessions inside Teach, and the attendance calendar should mark unscheduled days, scheduled unchecked days, partial days, complete days, late days, and absent days without linking back to the web user-group schedule page.

Teach-local logout clears the host-only app-session cookies and stale Supabase Auth cookies on `teach.tuturuuu.*`, then redirects browser form submissions to the central `apps/web` `/logout?from=Teach` continuation. JSON callers can still POST `/api/auth/logout` and receive `{ success: true }`.

Teach does not render its own login portal. Its `/login` route first checks for an existing Teach app-session JWT. If the app session is already present, it redirects inside Teach to the requested `next` path, usually `/dashboard`. Otherwise it redirects to the platform login at `apps/web` with a `returnUrl` pointing back to `/verify-token`. After the platform login confirms the account, `apps/web` generates a cross-app token for the `teach` target app and redirects back. Teach's local `POST /api/auth/verify-app-token` route only completes the host-only cookie handoff; token validation is delegated back to the central web app, and Teach does not create a Teach-local Supabase Auth session. The handoff stores a Teach-local app-session cookie for satellite route guards and shared session material used when a retained platform service must be called. If older session material cannot be refreshed, Teach sends the user back through the platform handoff so the coordinated cookies are renewed without manual deletion.

The `/dashboard` entry route must only send users to `/login` when the Teach app-session is missing. If the app-session exists but the Teach bootstrap API returns no eligible education workspace, render an empty teacher state instead of redirecting back to login.

Learn follows the same platform-login pattern: the learner app keeps `/verify-token` for cross-app session completion, but `/login` delegates account selection to `apps/web`.

Teach and Learn both hide locale prefixes from public and protected URLs. Legacy locale-prefixed paths such as `/vi/dashboard` redirect to the unprefixed canonical path while preserving the selected locale in `NEXT_LOCALE`.

Teach proxy locale detection must sanitize `Accept-Language` before it reaches `intl-localematcher`. Wildcard or malformed locale tokens can throw a `RangeError` in the proxy and surface as a broken `/login` or protected course page even when the route itself still exists.

Teach metadata and auth return URLs must resolve to absolute HTTP(S) app URLs. Prefer `TEACH_APP_URL` or `NEXT_PUBLIC_TEACH_APP_URL` for the Teach origin and `LEARN_APP_URL` or `NEXT_PUBLIC_LEARN_APP_URL` for Learn handoffs. A valid absolute `BASE_URL` can be used as a fallback for Teach, but non-URL environment values such as `development` are ignored so local development falls back to `https://teach.tuturuuu.localhost` through Portless.

## Visual direction

All non-`apps/web` education apps use the shared Neobrutalist design language from `apps/learn/DESIGN.md`: heavy foreground borders, offset shadows, paper-like surfaces, compact responsive grids, and theme-adaptive dynamic accents. Teach uses this language for public teacher orientation surfaces and protected dashboards.

Teach should read as a teacher operations dashboard, not a landing page. The protected surface should keep courses, module authoring, learner enrollment, schedule-aware attendance, posts, report previews, score metrics, settings, and learner-preview handoffs visible as first-class paths. Use multiple dynamic accent roles across these work loops and keep rails readable in light, dark, and system themes.

Teach module generation now accepts optional teacher context in the AI modal. Teachers can add class level, learning goals, or other constraints before uploading source material; the Teach-owned course-generation route passes that context into the AI prompt alongside the document content.

Report authoring should include a Teach-local preview before save. The preview should show learner identity, course context, score, report body, feedback, and a metric snapshot so teachers do not need to open `apps/web` report pages for normal course reporting. When a learner-facing check is useful, link intentionally to `apps/learn` course, assignment, report, or marks pages.

Teach reads and mutates course groups and module data through its local API
handlers. Those routes resolve the Teach app-session actor and verify workspace,
course, and resource access before using admin-backed data clients.

## Verification

After changing Teach routes, run focused route tests first. Finish Teach API or
UI changes with the app typecheck, repository checks, and the owning app build:

```bash theme={null}
bun i18n:sort
bun type-check:teach
bun check
bun run --cwd apps/teach build
```

Run focused route or component tests when login bridging, cross-app token
handling, local API authorization, or fallback forwarding changes.

## CI and deployment

Teach has dedicated Vercel workflows:

* `.github/workflows/vercel-preview-teach.yaml`
* `.github/workflows/vercel-production-teach.yaml`

Both workflows are registered in `tuturuuu.ts` and use the shared `ci-check.yml` switchboard. They require environment-scoped Vercel credentials plus `VERCEL_TEACH_PROJECT_ID`; production Supabase values should live in the Vercel project environment rather than GitHub Actions.

Deployment credentials must stay environment-scoped in GitHub Actions. The preview job is bound to the `vercel-preview-teach` GitHub Environment, and the production job is bound to `vercel-production-teach`. Store `VERCEL_TOKEN`, `VERCEL_ORG_ID`, and `VERCEL_TEACH_PROJECT_ID` in those environments instead of repository-wide or organization-wide secrets. Production Supabase values remain in the Vercel project environment pulled by `vercel pull`. The repository-level `TURBO_TOKEN` and `TURBO_TEAM` variable are passed only to the wrapped `vercel build` step; never place them at workflow or job scope, and never expose the token to pull-request or Dependabot code.

Preview dispatch is manual-only. Run `vercel-preview-teach.yaml` from `main`, set `preview_ref` to the reviewed branch, tag, or SHA, and keep `TRUSTED_PREVIEW_DEPLOY_ACTORS` limited to maintainers approved to run secret-backed preview builds. Manual production dispatch is only valid from `refs/heads/production`.


# API Route Patterns
Source: https://docs.tuturuuu.com/platform/architecture/api-routes

Implementing and organizing API routes in the Tuturuuu platform

The Tuturuuu platform uses Next.js App Router API routes with consistent patterns for versioning, authentication, error handling, and workspace isolation.

During the TanStack Start migration, new backend API ownership should move to
`apps/backend` instead of adding more long-lived `apps/web` route handlers. See
`platform/architecture/tanstack-rust-migration` for the route manifest, OpenAPI,
Docker, E2E, and benchmark gates.

## Route Organization

### Directory Structure

```
apps/web/src/app/api/
├── v1/                    # Versioned public API
│   ├── workspaces/
│   │   └── route.ts
│   └── users/
│       └── route.ts
├── ai/                    # AI-specific endpoints
│   ├── chat/
│   │   └── route.ts
│   └── generate/
│       └── route.ts
├── [wsId]/               # Workspace-scoped endpoints
│   ├── tasks/
│   │   └── route.ts
│   └── members/
│       └── route.ts
├── auth/                 # Authentication endpoints
│   ├── otp/
│   │   └── route.ts
│   └── mfa/
│       └── route.ts
└── workspaces/           # Workspace management
    └── route.ts
```

## Upstream Proxy Routes

When an `apps/web` route proxies requests to an upstream service and needs
low-level Undici transport controls such as a custom `dispatcher` or larger
`maxHeaderSize`, prefer `undici.request(...)` over the global server `fetch`.

On Next.js 16, the wrapped route-handler `fetch` can reject custom Undici
dispatchers with `UND_ERR_INVALID_ARG` / `invalid onRequestStart method`. Keep
custom transport configuration on the direct Undici request instead of passing
it through `fetch`.

## Authentication Wrappers

`apps/web` routes do not hand-roll `try/catch` + `supabase.auth.getUser()`
membership checks. Two wrappers in `apps/web/src/lib` centralize IP blocking,
pre-auth rate limiting, payload-size limits, suspension checks, and adaptive
abuse controls so handlers only contain business logic.

| Wrapper           | Module                 | Auth source                                                                         | Handler context                                                 |
| ----------------- | ---------------------- | ----------------------------------------------------------------------------------- | --------------------------------------------------------------- |
| `withSessionAuth` | `@/lib/api-auth`       | Signed-in Supabase session (cookie/Bearer JWT, optional AI temp auth / app-session) | `{ user, supabase }`                                            |
| `withApiAuth`     | `@/lib/api-middleware` | Workspace API key (`Authorization: Bearer ttr_...`)                                 | `{ context, params }` where `context` is the `WorkspaceContext` |

Both wrappers receive route params as a **Promise** (Next.js App Router
behavior) and resolve them before invoking the handler. The session wrapper
exposes a `TypedSupabaseClient` already scoped to the authenticated user, so
RLS stays intact.

> The older `authorizeRequest`/`authorize` helpers in `@/lib/api-auth` are
> `@deprecated`. Prefer `withSessionAuth` for new routes.

## Versioned Public API

### Pattern: `/api/v1/*`

Use for product and public-facing APIs. For session-authenticated dashboard
surfaces, wrap the handler with `withSessionAuth`. The wrapper provides the
authenticated `user` and a request-scoped `supabase` client; the third handler
argument is the resolved route params.

```typescript theme={null}
// app/api/v1/workspaces/route.ts
import { withSessionAuth } from '@/lib/api-auth';
import { NextResponse } from 'next/server';
import { z } from 'zod';

// GET /api/v1/workspaces
export const GET = withSessionAuth(async (_request, { user, supabase }) => {
  // Fetch the caller's workspaces (RLS-scoped via `supabase`)
  const { data: workspaces, error } = await supabase
    .from('workspace_members')
    .select(
      `
      ws_id,
      role,
      workspaces (
        id,
        name,
        logo_url
      )
    `
    )
    .eq('user_id', user.id)
    .eq('pending', false);

  if (error) {
    return NextResponse.json({ error: error.message }, { status: 500 });
  }

  return NextResponse.json({
    data: workspaces?.map((w) => w.workspaces),
  });
});

// POST /api/v1/workspaces
const createWorkspaceSchema = z.object({
  name: z.string().min(1).max(100),
  logo_url: z.url().optional(),
});

export const POST = withSessionAuth(async (request, { user, supabase }) => {
  // Validate request body
  const body = await request.json();
  const parsed = createWorkspaceSchema.safeParse(body);

  if (!parsed.success) {
    return NextResponse.json(
      { error: 'Invalid input', details: parsed.error.issues },
      { status: 400 }
    );
  }

  // Create workspace
  const { data: workspace, error } = await supabase
    .from('workspaces')
    .insert({
      name: parsed.data.name,
      logo_url: parsed.data.logo_url,
    })
    .select()
    .single();

  if (error) {
    return NextResponse.json({ error: error.message }, { status: 500 });
  }

  // Add creator as owner
  await supabase.from('workspace_members').insert({
    ws_id: workspace.id,
    user_id: user.id,
    role: 'owner',
  });

  return NextResponse.json({ data: workspace }, { status: 201 });
});
```

> When you do need a Supabase client outside a wrapper (Server Components,
> background jobs), remember the factory async-ness in
> `@tuturuuu/supabase/next/server`: `createClient()` and `createDynamicClient()`
> are async and must be awaited; `createAdminClient()` is synchronous (do not
> `await` it unless you pass it through another async helper).

## Workspace-Scoped API

### Pattern: `/api/v1/workspaces/[wsId]/*`

Use for workspace-scoped operations. Route params are a Promise; the wrapper
resolves them and passes them as the third handler argument. Authorize with the
workspace helpers from `@tuturuuu/utils/workspace-helper`:

* `normalizeWorkspaceId(wsId, supabase)` — resolves `personal`/handle aliases to
  a concrete UUID.
* `getPermissions({ wsId, user })` — returns a `PermissionsResult` with
  `containsPermission(permissionId)` / `withoutPermission(permissionId)`. It
  returns `null` when the caller is not a member, which doubles as the
  membership check.

```typescript theme={null}
// app/api/v1/workspaces/[wsId]/tasks/route.ts
import { withSessionAuth } from '@/lib/api-auth';
import {
  getPermissions,
  normalizeWorkspaceId,
} from '@tuturuuu/utils/workspace-helper';
import { NextResponse } from 'next/server';
import { z } from 'zod';

type Params = { wsId: string };

// GET /api/v1/workspaces/[wsId]/tasks
export const GET = withSessionAuth<Params>(
  async (request, { user, supabase }, { wsId }) => {
    const workspaceId = await normalizeWorkspaceId(wsId, supabase);

    // getPermissions returns null for non-members → 403
    const permissions = await getPermissions({ wsId: workspaceId, user });
    if (!permissions) {
      return NextResponse.json({ error: 'Forbidden' }, { status: 403 });
    }

    const searchParams = new URL(request.url).searchParams;
    const listId = searchParams.get('listId');
    const completed = searchParams.get('completed');

    let query = supabase
      .from('workspace_tasks')
      .select('*')
      .eq('ws_id', workspaceId);

    if (listId) query = query.eq('list_id', listId);
    if (completed !== null) query = query.eq('completed', completed === 'true');

    const { data: tasks, error } = await query;

    if (error) {
      return NextResponse.json({ error: error.message }, { status: 500 });
    }

    return NextResponse.json({ data: tasks });
  }
);

// POST /api/v1/workspaces/[wsId]/tasks
const createTaskSchema = z.object({
  name: z.string().min(1).max(255),
  description: z.string().optional(),
  listId: z.string(),
  priority: z.number().int().min(0).max(5).optional(),
  dueDate: z.string().datetime().optional(),
});

export const POST = withSessionAuth<Params>(
  async (request, { user, supabase }, { wsId }) => {
    const workspaceId = await normalizeWorkspaceId(wsId, supabase);

    const permissions = await getPermissions({ wsId: workspaceId, user });
    if (!permissions?.containsPermission('manage_projects')) {
      return NextResponse.json({ error: 'Forbidden' }, { status: 403 });
    }

    const body = await request.json();
    const parsed = createTaskSchema.safeParse(body);

    if (!parsed.success) {
      return NextResponse.json(
        { error: 'Invalid input', details: parsed.error.issues },
        { status: 400 }
      );
    }

    const { data: task, error } = await supabase
      .from('workspace_tasks')
      .insert({
        name: parsed.data.name,
        description: parsed.data.description,
        list_id: parsed.data.listId,
        priority: parsed.data.priority,
        end_date: parsed.data.dueDate,
        creator_id: user.id,
      })
      .select()
      .single();

    if (error) {
      return NextResponse.json({ error: error.message }, { status: 500 });
    }

    return NextResponse.json({ data: task }, { status: 201 });
  }
);
```

> Real task-board routes (for example
> `apps/web/src/app/api/v1/workspaces/[wsId]/tasks/route.ts`) keep handler logic
> in `@tuturuuu/tasks-api/server/tasks/route` and only wire the adapter in the
> route file. Task-specific request clients and types live in
> `@tuturuuu/tasks-api/progress`, while task-only React surfaces live in
> `@tuturuuu/tasks-ui`. This includes board UI, task dialogs and settings,
> task-aware rich-text mention renderers, realtime board hooks, and task
> scheduling controls used by Calendar. Generic editors and Calendar shells
> expose component or renderer interfaces from `@tuturuuu/ui`; the task
> package supplies their implementations. Keep this dependency one-way:
> `@tuturuuu/tasks-ui` may depend on `@tuturuuu/ui`, but shared UI must not
> import task UI. Keep generic modules in `@tuturuuu/apis`,
> `@tuturuuu/internal-api`, and `@tuturuuu/ui` free of new task-only
> implementations so Turbo can cache and rebuild the task packages
> independently. Apps must import task modules directly from
> `@tuturuuu/tasks-ui`; do not re-export them through `@tuturuuu/ui`, because
> that broadens the affected build graph again. Direct consumer apps must also
> import `@tuturuuu/tasks-ui/globals.css` instead of the generic globals so
> Tailwind compiles the UI foundation and task-owned utilities together;
> keep that source registration out of generic UI globals so task-only changes
> do not invalidate unrelated apps. Extract shared handler logic the same way when a route grows
> past a simple CRUD shape. Use `containsPermission()` with a real `PermissionId` (such
> as `'manage_projects'`); there is no `manage_tasks` permission and no
> `@/lib/permissions` module.

## AI Endpoints

### Pattern: `/api/ai/*`

Use for AI-specific operations with model selection and token tracking.

The repo uses **AI SDK v6** (`ai` ^6.x, `@ai-sdk/google` ^3.x). On v6,
`streamText` results expose `result.toUIMessageStreamResponse()` (the v4/v5
`toDataStreamResponse()` no longer exists), and `onFinish` usage is reported as
`usage.inputTokens` / `usage.outputTokens` (not `promptTokens` /
`completionTokens`). Wrap the route with `withSessionAuth` and pass
`allowAiTempAuth` if the endpoint must accept short-lived AI temp tokens.

```typescript theme={null}
// app/api/ai/chat/route.ts
import { withSessionAuth } from '@/lib/api-auth';
import { createGoogleGenerativeAI } from '@ai-sdk/google';
import { streamText } from 'ai';
import { z } from 'zod';

const chatRequestSchema = z.object({
  wsId: z.string(),
  messages: z.array(
    z.object({
      role: z.enum(['user', 'assistant', 'system']),
      content: z.string(),
    })
  ),
  model: z.string().optional(),
});

export const POST = withSessionAuth(async (request, { supabase }) => {
  // Validate input
  const body = await request.json();
  const parsed = chatRequestSchema.safeParse(body);

  if (!parsed.success) {
    return new Response('Invalid input', { status: 400 });
  }

  // Check AI feature flag
  const { data: secret } = await supabase
    .from('workspace_secrets')
    .select('value')
    .eq('ws_id', parsed.data.wsId)
    .eq('name', 'ENABLE_AI')
    .single();

  if (secret?.value !== 'true') {
    return new Response('AI not enabled for workspace', { status: 403 });
  }

  const google = createGoogleGenerativeAI({
    apiKey: process.env.GOOGLE_GENERATIVE_AI_API_KEY,
  });

  const model = parsed.data.model || 'gemini-2.0-flash';

  const result = streamText({
    model: google(model),
    messages: parsed.data.messages,
    onFinish: async ({ usage }) => {
      // Track token usage (AI SDK v6 field names)
      await supabase.from('workspace_ai_executions').insert({
        ws_id: parsed.data.wsId,
        model,
        input_tokens: usage.inputTokens ?? 0,
        output_tokens: usage.outputTokens ?? 0,
      });
    },
  });

  return result.toUIMessageStreamResponse();
});
```

Token-usage persistence across the live AI routes (chat, task journal,
suggestions, quizzes) consistently reads `usage.inputTokens ?? 0` and
`usage.outputTokens ?? 0` — mirror that when adding new AI endpoints.

## Authentication Endpoints

### Pattern: `/api/auth/*`

Use edge runtime for auth endpoints.

```typescript theme={null}
// app/api/auth/otp/route.ts
import { createClient } from '@tuturuuu/supabase/next/server';
import { NextRequest, NextResponse } from 'next/server';
import { z } from 'zod';

const otpRequestSchema = z.object({
  email: z.email(),
});

export async function POST(request: NextRequest) {
  try {
    const supabase = await createClient();

    const body = await request.json();
    const parsed = otpRequestSchema.safeParse(body);

    if (!parsed.success) {
      return NextResponse.json(
        { error: 'Invalid email' },
        { status: 400 }
      );
    }

    const { error } = await supabase.auth.signInWithOtp({
      email: parsed.data.email,
      options: {
        emailRedirectTo: `${process.env.NEXT_PUBLIC_APP_URL}/auth/callback`,
      },
    });

    if (error) {
      return NextResponse.json({ error: error.message }, { status: 400 });
    }

    return NextResponse.json({ success: true });
  } catch (error) {
    return NextResponse.json(
      { error: 'Internal server error' },
      { status: 500 }
    );
  }
}
```

## Error Response Standards

### Standard Error Format

```typescript theme={null}
interface ErrorResponse {
  error: string;
  details?: any;
  code?: string;
}
```

### HTTP Status Codes

* `200` - Success
* `201` - Created
* `204` - No Content
* `400` - Bad Request (validation errors)
* `401` - Unauthorized (not authenticated)
* `403` - Forbidden (not authorized)
* `404` - Not Found
* `409` - Conflict
* `422` - Unprocessable Entity
* `429` - Too Many Requests
* `500` - Internal Server Error

### Error Handling Pattern

```typescript theme={null}
export async function POST(request: NextRequest) {
  try {
    // Implementation
  } catch (error) {
    console.error('API error:', error);

    if (error instanceof z.ZodError) {
      return NextResponse.json(
        { error: 'Validation failed', details: error.issues },
        { status: 400 }
      );
    }

    return NextResponse.json(
      { error: 'Internal server error' },
      { status: 500 }
    );
  }
}
```

## API-Key Authenticated Routes

### Pattern: `withApiAuth`

External SDK clients authenticate with a workspace API key
(`Authorization: Bearer ttr_...`) instead of a Supabase session. Wrap those
routes with `withApiAuth` from `@/lib/api-middleware`. It validates the key,
enforces IP blocks, applies pre-auth and adaptive rate limits, logs API key
usage, optionally checks workspace permissions, and passes the resolved
`WorkspaceContext` plus route params to the handler.

```typescript theme={null}
// app/api/v1/workspaces/[wsId]/storage/route.ts
import { withApiAuth } from '@/lib/api-middleware';
import { NextResponse } from 'next/server';

type Params = { wsId: string };

export const GET = withApiAuth<Params>(
  async (_request, { params, context }) => {
    // `context.wsId` is the validated workspace from the API key
    const { wsId } = context;
    // params.wsId is the resolved (awaited) route segment
    return NextResponse.json({ wsId, route: params.wsId });
  },
  {
    permissions: ['manage_drive'], // checked via the API key's permission set
    rateLimit: { windowMs: 60000, maxRequests: 100 },
  }
);
```

Key points that differ from `withSessionAuth`:

* Permissions are declared in the wrapper `options.permissions` (a
  `PermissionId[]`) and checked against the API key's granted scopes via
  `hasAnyPermission` / `hasAllPermissions`. Set `requireAll: true` to require
  every listed permission.
* The handler context is `{ context, params }` (not `{ user, supabase }`); the
  API-key path does not hand you a session-scoped Supabase client.
* Rate-limit defaults: GET/HEAD reads are open, mutations default to 100
  req/min, and workspace-specific overrides from `workspace_secrets` take
  precedence.

The helper module also exports `validateQueryParams(request, schema)` and
`validateRequestBody(request, schema, maxBytes)` for Zod-validated, byte-size-capped
input handling.

## CORS Configuration

```typescript theme={null}
// app/api/v1/workspaces/route.ts
export async function OPTIONS(request: NextRequest) {
  return new NextResponse(null, {
    status: 200,
    headers: {
      'Access-Control-Allow-Origin': process.env.ALLOWED_ORIGIN || '*',
      'Access-Control-Allow-Methods': 'GET, POST, PUT, DELETE, OPTIONS',
      'Access-Control-Allow-Headers': 'Content-Type, Authorization',
    },
  });
}
```

## Rate Limiting

For signed-in product APIs, prefer `withSessionAuth(...)` over manual
`supabase.auth.getUser()` calls. The wrapper resolves the session through local
JWT claims first and only falls back to `getUser()` when claims are unavailable,
which avoids exhausting Supabase Auth limits on request-heavy dashboard surfaces
such as task boards. Default GET/HEAD requests are not rate-limited by the
session wrapper; default mutations use the shared mutation budget unless the
route provides an explicit `rateLimit` option.

The API proxy still protects request-heavy dashboard reads before route auth is
validated. High-fanout task-board reads use a dedicated `task-board-read` proxy
bucket so normal board loading, per-list pagination, and focused revalidation do
not exhaust the generic anonymous read budget. The defaults are 600 requests per
minute, 12000 per hour, and 80000 per day, and can be tuned with
`API_PROXY_TASK_BOARD_READ_LIMIT_MINUTE`,
`API_PROXY_TASK_BOARD_READ_LIMIT_HOUR`, and
`API_PROXY_TASK_BOARD_READ_LIMIT_DAY`.

Proxy-side `429` responses include support diagnostics when available:
`X-RateLimit-Client-IP`, `X-RateLimit-User-Id`, and
`X-RateLimit-User-Email`, plus the selected policy/window headers emitted by the
proxy guard. Exact server-verified browser sessions ending in `@tuturuuu.com`
are allowed through proxy-side rate-limit blocks for debugging with
`X-RateLimit-Warning: staff-debug-bypass`,
`X-RateLimit-Debug-Bypass: tuturuuu-staff`, and
`X-RateLimit-Original-Status: 429`. This bypass only applies after the server
revalidates the Supabase session, only to proxy guard rate-limit blocks, and does
not bypass malformed auth, permissions, payload-size checks, route-handler
errors, or non-staff/anonymous requests.

Finance invoice creation support reads use a separate
`finance-invoice-create-read` proxy bucket for the shared-IP burst created by
the new invoice flow. It covers GET/HEAD reads for customer search, products,
wallets, transaction categories, promotions, invoice default settings, linked
products, user group data, user promotion data, invoice history, and
subscription context. Invoice creation mutations remain on the default mutation
policy. The defaults are 600 requests per minute, 6000 per hour, and 40000 per
day, and can be tuned with
`API_PROXY_FINANCE_INVOICE_CREATE_READ_LIMIT_MINUTE`,
`API_PROXY_FINANCE_INVOICE_CREATE_READ_LIMIT_HOUR`, and
`API_PROXY_FINANCE_INVOICE_CREATE_READ_LIMIT_DAY`.

### Verified sessions and trusted read uplift

Proxy limits default to per-IP anonymous buckets because auth headers and
cookies are forgeable at the edge — their presence alone must never raise a
budget. To separate genuinely signed-in browser sessions and give legitimate
teams (often many people behind one office NAT/VPN IP) higher read throughput,
the proxy consults a server-written **trust cache** in Redis, keyed by the same
subject keys as the abuse-reputation system (`session:<hash>`,
`cidr:<network>`, `ip:<addr>`):

* A genuinely trusted **session** (its key is a hash of the real auth cookie, so
  it cannot be forged) gets its own per-session read and mutation buckets, so
  signed-in teammates behind one shared IP no longer collide on the pre-auth
  proxy budget.
* A trusted **location** (office `cidr`/`ip`, learned automatically from organic
  reputation or set explicitly via an `abuse_trust_overrides` `cidr` entry in the
  abuse-intelligence admin API) uplifts the shared per-IP read limit for the
  whole team.

Untrusted traffic keeps the legacy per-IP limits, preserving single-IP abuse
caps. The cache only ever uplifts read limits (never mutation limits, and never
lowers limits — restrictive decisions stay server-side) and fails open to
neutral when Redis is unavailable. It is populated by the session write-through
in `recordResponseAbuseSignal` and direct session-auth helpers, and reconciled
every 10 minutes by the `/api/cron/infrastructure/sync-trust-cache` cron (which
also propagates admin trusted-location overrides). Set
`API_PROXY_EDGE_TRUST_ENABLED=0` to disable the edge trust cache and fall back to
per-IP keying; tune the cache lifetime with `EDGE_TRUST_CACHE_TTL_SECONDS`.

```typescript theme={null}
import { Ratelimit } from '@upstash/ratelimit';
import { Redis } from '@upstash/redis';

const ratelimit = new Ratelimit({
  redis: Redis.fromEnv(),
  limiter: Ratelimit.slidingWindow(10, '10 s'), // 10 requests per 10 seconds
});

export async function POST(request: NextRequest) {
  const identifier = request.headers.get('x-forwarded-for') || 'anonymous';
  const { success } = await ratelimit.limit(identifier);

  if (!success) {
    return NextResponse.json(
      { error: 'Rate limit exceeded' },
      { status: 429 }
    );
  }

  // Continue with request
}
```

## Best Practices

### ✅ DO

1. **Wrap handlers with the auth wrapper**
   ```typescript theme={null}
   // Session routes: getUser/membership/rate limits handled for you
   export const POST = withSessionAuth(async (request, { user, supabase }) => {
     /* ... */
   });
   // API-key routes: key validation + permission scopes
   export const GET = withApiAuth(handler, { permissions: ['manage_drive'] });
   ```

2. **Always validate input**
   ```typescript theme={null}
   const parsed = schema.safeParse(body);
   if (!parsed.success) return error(400);
   ```

3. **Verify workspace permissions**
   ```typescript theme={null}
   const workspaceId = await normalizeWorkspaceId(wsId, supabase);
   const permissions = await getPermissions({ wsId: workspaceId, user });
   if (!permissions?.containsPermission('manage_projects')) return error(403);
   ```

### ❌ DON'T

1. **Don't expose sensitive errors**
   ```typescript theme={null}
   // ❌ Bad
   return NextResponse.json({ error: error.stack });
   ```

2. **Don't skip workspace isolation**
   ```typescript theme={null}
   // ❌ Bad: Can access any workspace
   .delete().eq('id', taskId)

   // ✅ Good: Workspace-scoped
   .delete().eq('id', taskId).eq('ws_id', wsId)
   ```

3. **Don't reach for the admin client to skip authorization**
   ```typescript theme={null}
   // ❌ Bad: bypasses RLS and the caller's permission set
   const sbAdmin = createAdminClient(); // sync — do not await
   await sbAdmin.from('workspace_tasks').delete().eq('id', taskId);

   // ✅ Good: use the session-scoped `supabase` from withSessionAuth so RLS
   //         and getPermissions() still gate the write
   await supabase
     .from('workspace_tasks')
     .delete()
     .eq('id', taskId)
     .eq('ws_id', workspaceId);
   ```
   Use the admin client only for trusted server-side work that has already
   performed its own authorization (e.g. inside `getPermissions`), and remember
   it is synchronous.

## Related Documentation

* [Authentication](/platform/architecture/authentication)
* [Authorization](/platform/architecture/authorization)
* [tRPC](/platform/architecture/trpc)
* [Data Fetching](/platform/architecture/data-fetching)


# App Coordination
Source: https://docs.tuturuuu.com/platform/architecture/app-coordination

How Tuturuuu coordinates central login and API access for internal and external apps.

Tuturuuu apps should not share production Supabase service-role keys or browser
sessions. Apps coordinate through web-owned auth routes:

* Registered internal apps consume cross-app login tokens generated by
  `apps/web`, then store a Tuturuuu-managed app-session JWT cookie. They must
  not create app-local Supabase Auth sessions.
* The `ttr` CLI also exchanges central-login handoff tokens for Tuturuuu-managed
  gateway JWTs. It must not store Supabase Auth access or refresh tokens.
* External apps must be registered in the Infrastructure dashboard before they
  can exchange a central-login token for API access.
* App coordination bearer tokens are never minted from a cross-app token alone.
  The exchange route requires a registered `appId` plus app secret, and
  external-project APIs require explicit API scopes.
* Platform admins issue or rotate external app secrets from
  `Infrastructure -> External Apps`. The secret is shown once; Tuturuuu stores
  only a hash in root workspace secrets.

## Registered internal app flow

Registered internal apps are the apps listed in
`packages/utils/src/internal-domains.ts`, such as `cms`, `calendar`, `nova`,
`rewise`, `tasks`, `drive`, `finance`, `inventory`, `track`, `learn`, `teach`,
`chat`, `mail`, `mind`, `meet`, and `hive`.

1. The app redirects unauthenticated users to `apps/web` login with a
   `returnUrl` pointing back to the app's `/verify-token?nextUrl=...` route.
   That return URL must resolve to the satellite app origin, not the central
   web origin. Registered apps should use `resolveInternalAppUrl()` for their
   `BASE_URL`/app URL constants so shared environment variables such as
   `BASE_URL=https://tuturuuu.com` are rejected for satellite hosts instead of
   minting the host-only app-session cookie on the wrong domain.
   If `apps/web` receives a registered internal app `returnUrl` that points at
   `/login` or a protected product route, it must normalize the token handoff
   back through that app's `/verify-token` route before redirecting.
2. `apps/web` validates the return target and mints the normal one-time
   cross-app handoff token.
3. The app `/verify-token` route posts only that handoff token to
   `/api/auth/verify-app-token`. Registered app proxies should perform this
   step with `consumeVerifyTokenRequest()` before page rendering; the shared
   React verifier page is only a fallback.
4. The app-local verifier validates the handoff token and sets host-only
   `tuturuuu_app_session` and `tuturuuu_app_session_refresh` cookies.
   Satellites that require rewritten `apps/web` API access must call
   `createPOST('<app>', { verificationBaseUrl: WEB_APP_URL })` so the central
   verifier also returns the Web-issued `tuturuuu_web_app_session` and
   `tuturuuu_web_app_session_refresh` cookies. The cookies are `HttpOnly`,
   `SameSite=Lax`, `Path=/`, and `Secure` in production.
5. The verifier trusts the `Set-Cookie` response and redirects to `nextUrl`.
   It must not call `supabase.auth.setSession()` and must not receive Supabase
   access or refresh tokens.

The app-session JWT reuses the app-coordination claim shape: `sub`, `email`,
`origin_app`, `target_app`, `scopes`, `iat`, `exp`, and `jti`. Verification
rejects expired tokens. Target app and scope checks are enforced by the caller,
so every API route that opts into app-session auth must bind the token to the
audience and scope it expects. Access tokens carry `internal-app:session`.
Refresh tokens carry only `internal-app:refresh`; they are rotation material and
must not be accepted as API credentials or bearer access tokens.

For internal API calls, apps forward the app-session cookie to `apps/web`.
Routes that opt into app-session auth use the verified claims as the actor and
must keep authorization explicit. Do not pass `ttr_app_...` HS256 JWTs to
Supabase as user access tokens.
Satellite API proxies should treat the host-only `tuturuuu_app_session` cookie
as an authenticated API signal before applying anonymous proxy rate limits; a
signed-in app user doing normal dashboard work must not share anonymous
read/mutation buckets with public traffic.

Every central `apps/web` API consumed by a registered internal app must accept
`tuturuuu_app_session` before falling back to Supabase Auth. Routes using
`withSessionAuth` should opt into app-session auth; legacy route handlers should
use `resolveSessionAuthContext(request, { allowAppSessionAuth: true })` so
local satellite apps do not loop between `/login` and product pages or
accumulate `api_auth_failed` IP blocks.

`apps/drive` follows the centralized-API satellite model: the standalone Drive
app owns the workspace shell and Drive explorer UI, while storage list,
analytics, upload, delete, share, export, and migration APIs remain in
`apps/web /api/v1/workspaces/:wsId/storage/*`. Those routes authenticate
Drive's app-session cookie through the shared storage route auth helper before
checking `manage_drive`.

Use route-specific app-session constraints instead of accepting any registered
internal app token. The legacy `allowAppSessionAuth: true` shorthand is
audience-bound in `apps/web/src/lib/api-auth.ts`: it maps known internal API
path prefixes to their expected satellite app audience and falls back to the
`platform` audience for unmapped routes. For example, CLI-only platform APIs
should configure `withSessionAuth` with `targetApp: 'platform'` and
`requiredScope: 'cli:access'`; satellite APIs should use that satellite's
target app and only the scopes intended for that route. When adding a new
boolean app-session route for a satellite API, update the shared audience map or
use an explicit `{ targetApp, requiredScope }` object in the route.

When a registered app forwards request cookies to `apps/web`, it must strip
stale `sb-*-auth-token` Supabase cookies whenever `tuturuuu_app_session` is
present. Registered app proxies should also call the shared
`clearSupabaseAuthCookies()` helper on API, redirect, and normal middleware
responses so stale Supabase session cookies are expired on the satellite host.
If both `tuturuuu_app_session` and `tuturuuu_web_app_session` are forwarded, the
Web-issued cookie is the preferred actor for central `apps/web` API auth; the
local app cookie remains the fallback for routes that cannot verify the Web
cookie.

Registered app proxies must consume `/verify-token` handoff requests before page
rendering. Use the shared `consumeVerifyTokenRequest()` helper from
`@tuturuuu/auth/proxy` so the proxy validates the handoff token through the
app-local `/api/auth/verify-app-token` route, copies the verifier's
`Set-Cookie` headers onto the redirect, and sends the browser directly to the
safe `nextUrl`. The shared React verifier page remains a fallback for runtimes
where proxy middleware is unavailable; it should not be part of the normal
registered-app login path.

Registered app proxies must run app-session refresh before page redirects and
before API proxy guards. When access is close to expiry, or already expired but
a refresh cookie is still valid, the proxy posts to the app-local
`/api/auth/refresh-app-session` endpoint. The app-local endpoint asks
`apps/web` to validate and rotate the Web-issued refresh token, then sets fresh
local and Web-issued cookie pairs. The proxy must forward those refreshed cookie
values into the current request headers before the API route or page handler
runs.

A valid refresh cookie must recover an expired access token on the satellite
origin. Do not redirect the browser back to `apps/web` for a new cross-app
handoff unless both local refresh credentials and Web-issued refresh credentials
are missing or invalid.

Gateway API routes for registered apps should resolve the app-session actor
before any central-web Supabase Auth fallback, and admin-backed checks must use
no-cookie admin clients so satellite responses do not inject Supabase Auth
cookies back onto the app host. Shared Supabase server-client helpers must treat
requests carrying `tuturuuu_app_session` or `Authorization: Bearer ttr_app_...`
as app-session requests and avoid constructing cookie-backed Supabase clients for
those requests.

When an app-session or CLI route needs an admin-backed Supabase client for
shared helpers such as `normalizeWorkspaceId()`, wrap that admin client with
`attachSupabaseAuthUser()` from `@tuturuuu/auth/app-session` using the verified
actor first. This keeps `personal` workspace resolution, permission checks, and
shared route helpers on the same authenticated path without duplicating
per-route personal-workspace fallback queries.

## CLI app-session flow

The native `ttr` CLI uses the same gateway JWT model without a browser cookie:

1. `ttr login` opens `apps/web` at `/api/cli/auth/start`, or prints that URL in
   `--copy` mode.
2. The authenticated web session mints the normal short-lived cross-app handoff
   token for target app `platform` and origin `cli`.
3. The CLI posts the handoff token to `/api/cli/auth/verify`.
4. The verify route returns a Tuturuuu-managed access JWT plus a longer-lived
   refresh JWT. It does not call Supabase magic-link, OTP, or refresh-session
   APIs.
5. CLI API requests send the access JWT as `Authorization: Bearer ttr_app_...`.
   App-session-aware internal API routes resolve the actor from verified claims
   and use explicit authorization.
6. The CLI refreshes shortly before access-token expiry and retries once after a
   `401`. Refresh rotates both JWTs and updates the saved config.

CLI access JWTs include the app-session scope and can authenticate gateway API
requests. CLI refresh JWTs include only the CLI refresh scope, so they cannot be
used directly as API bearer tokens. Refresh also resolves the user through an
admin-backed lookup before minting new JWTs.

Routes used by the native CLI must require both the `platform` target app and
the `cli:access` scope before passing the request to admin-backed workspace or
task handlers. Do not rely on the generic `internal-app:session` scope for
CLI-only APIs.

## External app flow

1. Register the external app ID, allowed origins, and allowed API scopes in the
   Infrastructure dashboard.
2. Issue an app secret and store it in the external app runtime environment.
3. Send users to the centralized web login with a `returnUrl` pointing back to
   the registered external app origin.
4. The external app receives a short-lived cross-app `token` on its return URL.
5. The external app server calls
   `POST /api/v1/auth/app-token/exchange` with `appId`, `appSecret`, `token`,
   optional `requestedScopes`, and `workspaceId` whenever the requested or
   issued scopes include `external-projects:*`, `external-projects:manage`,
   `external-projects:publish`, or `external-projects:read`.
   This server-to-server route must bypass browser challenges and WAF managed
   challenges. A Cloudflare response with `cf-mitigated: challenge` is an edge
   block, not an app-token validation failure, and the external app cannot
   complete it with `fetch`.
6. For external-project scopes, Tuturuuu validates that the workspace has an
   enabled external-project binding, that the binding's canonical adapter
   matches the registered external app ID, that the user is a direct `MEMBER`
   of the linked workspace, and that the user has the required EPM permission
   in that workspace. Root EPM admins can manage app registrations and
   bindings from the platform infrastructure UI, but they cannot enter or call a
   linked external app unless they are also members of that linked workspace.
7. If the user is not yet a workspace member but has a pending
   `workspace_invites` or `workspace_email_invites` row for the requested
   workspace, the exchange returns `403` with
   `code: "PENDING_WORKSPACE_INVITE"`, `workspaceId`, and `invitationUrl`.
   External apps must handle this code before showing generic no-access copy so
   the user can accept or reject the invitation in Tuturuuu first.
8. Tuturuuu validates the app secret and cross-app token, then returns a
   short-lived bearer token for Tuturuuu APIs plus the normalized authorized
   `workspaceId`.

External apps should store only their own app secret and local session material.
They should send Tuturuuu API calls with the returned bearer token and should
never require production Supabase keys. Third-party or custom Supabase JWT paths
are not used for registered internal apps; Tuturuuu JWTs stay at the gateway and
internal API layer. External-project admin apps must store the returned
authorized workspace ID in their encrypted local admin session and reject the
session if it no longer matches the app's configured linked workspace. They
should also revalidate stored local sessions against a protected
external-project API route before rendering admin UI or proxying admin API
calls; if Tuturuuu returns `401`, `403`, or `404`, the app must clear its local
session and send the user through the central login flow again.

### App-owned Drive attachments

Registered external apps can request `workspace:drive:read` and
`workspace:drive:write` without granting their members the broad `manage_drive`
workspace permission. The app must be enabled and linked to the requested
workspace, and every call still requires the token actor to be a direct
`MEMBER`. These scopes expose only the external-app Drive boundary:

* `POST /api/v1/workspaces/{wsId}/external-apps/drive/upload-url`
* `POST /api/v1/workspaces/{wsId}/external-apps/drive/finalize`
* `POST /api/v1/workspaces/{wsId}/external-apps/drive/read-url`
* `DELETE /api/v1/workspaces/{wsId}/external-apps/drive`

Chat attachments are isolated under
`external-apps/{targetApp}/chat/{conversationId}/{attachmentId}/{filename}`.
The upload route accepts metadata only and returns a short-lived direct-upload
payload for the workspace's configured Supabase Storage or R2 provider. The app
must call `finalize` after upload; Tuturuuu reads the actual object metadata,
deletes mismatched objects, and returns canonical metadata. Signed URLs are
transient response values and must never be logged or persisted. Use
`@tuturuuu/internal-api/external-app-drive` for the shared request and direct
upload helpers.

The centralized login page validates external and internal `returnUrl` targets
before it renders the normal sign-in form or account-confirmation handoff. If the
target origin is not registered or cannot be resolved, the page shows a warning
and asks the user to clear the broken return URL instead of silently falling back
to the generic login form.

## Operational notes

App-session and external app bearer tokens are signed with
`TUTURUUU_APP_COORDINATION_SECRET`.

Token lifetimes are configured from the root workspace Infrastructure app at
`/{wsId}/app-coordination` on `INFRA_APP_URL`. The older web and TanStack
infrastructure routes are removed rather than redirected. The policy is stored in
`workspace_secrets` on `ROOT_WORKSPACE_ID` as
`APP_COORDINATION_SESSION_POLICY` and cached in process for at most 60 seconds
on auth paths. Defaults and caps are:

* Internal app access TTL: 28,800 seconds default, min 300, max 86,400.
* Internal app refresh TTL: 2,592,000 seconds default, min 86,400, max
  7,776,000.
* Internal app refresh-early window: 900 seconds default, min 60, max 7,200.
* Browser refresh replay grace: 30 seconds default, min 0, max 300.
* External app bearer TTL: 28,800 seconds default, min 300, max 86,400.
* CLI access TTL: 28,800 seconds default, min 300, max 86,400.
* CLI refresh TTL: 7,776,000 seconds default, min 86,400, max 7,776,000.

The policy also supports per-internal-app overrides keyed by registered app id
for access TTL, refresh TTL, and refresh-early window. If the Infrastructure
secret is missing or invalid, runtime code falls back to compatibility
environment variables where available and then to defaults. Existing short-lived
tokens are not revoked when the policy changes; new cross-app handoffs and
refresh rotations pick up the latest cached policy after the cache window.
Refresh tokens remain HttpOnly browser cookies or CLI-local tokens. They are not
API credentials, are not exposed to browser JavaScript, and should never be sent
as bearer access tokens.

When registered internal apps are deployed separately, every deployment that
mints or verifies `tuturuuu_app_session` must share the same signing material.
Prefer setting `TUTURUUU_APP_COORDINATION_SECRET` on `apps/web` and every
registered satellite. For compatibility with existing Vercel satellite
deployments, the runtime also accepts the server-side Supabase secret as a
fallback verifier so satellites without the explicit coordination secret do not
fail immediately after cross-app token validation.

When rotating an app secret, deploy the new external app environment first, then
rotate from Infrastructure. Existing short-lived bearer tokens keep working
until they expire, but future exchanges require the new app secret.

Cross-app login tokens are user-bound handoff tokens. The database RPC only
mints a token for the authenticated caller's own `auth.uid()`; do not use it as a
server-side impersonation primitive or as a replacement for app credentials.
Registered apps should clear `tuturuuu_app_session` on local logout and expire
stale `sb-*-auth-token` cookies on the app host. Browser form logout should
redirect back to the app's landing/login page or to the central `/logout`
continuation after local cleanup instead of leaving the browser on
`/api/auth/logout`. Logout and browser-state recovery redirects must use the
app's configured public URL as the fallback when the request reaches the app
through a wildcard listener such as `0.0.0.0`, because that listener address is
not a browser destination.

Shared satellite UI must not assume every app publishes the full `apps/web`
`public/media` tree. Shared brand images such as `TuturuuLogo` should use the
canonical hosted Tuturuuu asset URL so apps without local `/media/logos/*`
files do not produce repeated 404s.

All Next apps configured with `next-intl` are checked by
`bun i18n:setup-check` (and therefore `bun check`). Locale-rooted apps must
resolve and validate the explicit `locale` override or awaited `requestLocale`
segment in `src/i18n/request.ts`, then resolve the document language from
`next/root-params` in the locale root layout and validate it with
`resolveRootLocale`. Avoid the legacy `setRequestLocale` path. Do not import
`next/root-params` from request configuration: Next supports it in Server
Components such as the root layout, while next-intl request configuration also
runs for Route Handlers. Do not call request-bound `getLocale()` from the root
layout because it opts otherwise static locale roots into runtime rendering.
Apps without a `[locale]` root segment use `requestLocale` directly; the checker
discovers this architecture from the route tree rather than maintaining an app
exception list.

## Satellite shell patterns

Workspace-scoped satellite apps (`drive`, `calendar`, `tasks`, `finance`, and
similar) should reuse the shared satellite provider shell from
`@tuturuuu/satellite/providers`. That shell mounts `next-themes` with
`system`, `light`, and `dark`, wraps `NextIntlClientProvider`, and wires the
shared TanStack Query client. Public or gateway-only apps such as `apps/qr` and
`apps/apps` should use the same provider re-export so theme toggles and shared
UI chrome behave consistently even when the app does not own workspace auth.

Every user-facing browser app that should appear in the Apps gateway or the
global Ctrl/Cmd+K launcher must be registered in
`packages/utils/src/launchable-apps.ts`. Keep the registry entry current with
the app title, slug, aliases, category, production URL, Portless/dev origin,
default path, package root, and workspace path resolver when the app has
workspace-scoped routes. `apps/apps/src/lib/apps-registry.ts` reads from that
shared registry so the gateway and launcher do not drift.

Workspace sidebar apps should keep an app-local `structure.tsx` file, but that
file should be a thin wrapper around
`@tuturuuu/satellite/sidebar-structure`. The shared structure owns the
collapsible sidebar behavior, `SidebarProvider` cookies, workspace switcher
placement, mobile header, footer actions, hover expansion, back navigation, and
user-nav slots. App wrappers should only provide app-specific navigation links,
workspace-select routing, billing URL shape, or small brand/content additions
such as Mind boards and Rewise branding. This applies to workspace product apps
such as Calendar, CMS, Drive, Finance, Inventory, Mind, Rewise, Tasks, Track,
Mail, Chat, and Meet. Learn and Teach intentionally keep their
education-specific shells.

Meet has a public `/:planId` route surface, so workspace-scoped Meet routes must
live under `/workspace/:wsId` instead of `/:wsId`. Use
`/workspace/:wsId/plans` for Tuturuuu Meet plans and
`/workspace/:wsId/meetings` for meeting-room operations, with
`/workspace/:wsId` redirecting to the plans route. Keep public plan-detail URLs
on the root plan-id surface.

For server-side workspace picker data, do not call
`@tuturuuu/ui/lib/workspace-actions` from satellite apps. That helper expects
Supabase Auth cookies on the app host and returns empty lists when only
`tuturuuu_app_session` is present. Instead, use
`fetchSatelliteWorkspaces()` from `@tuturuuu/satellite/workspace-actions`, which
forwards the incoming request auth to `GET /api/v1/workspaces` on `apps/web`.

When the workspace picker resolves a selected workspace, client code may call
the legacy detail route `GET /api/workspaces/:wsId`. That route must also opt
into app-session auth through `withSessionAuth(..., {
allowAppSessionAuth: CURRENT_USER_APP_SESSION_AUTH })` so satellite sessions do
not receive `401 Unauthorized` on `personal` or other workspace aliases.

When a workspace-scoped satellite page already has an app-session user, shared
permission checks must resolve `personal` from that explicit user context rather
than falling back to cookie-bound Supabase Auth on the app host. App-session
cookies are Tuturuuu-managed, so the app host may not have a local Supabase Auth
user even though the user is authenticated.


# Authentication Patterns
Source: https://docs.tuturuuu.com/platform/architecture/authentication

Authentication implementation patterns in the Tuturuuu platform

The Tuturuuu platform uses Supabase Auth for user authentication with support for email/password, OAuth providers, multi-factor authentication (MFA), and cross-app token authentication.

<Note>
  The server helpers in `@tuturuuu/supabase/next/server` resolve cookies (and an
  optional `request` argument) asynchronously, so `createClient()` and
  `createDynamicClient()` are **async** and must be awaited. `createAdminClient()`
  is synchronous, but its return type allows awaiting, so existing call sites that
  `await createAdminClient()` still work — never `await createClient()` results
  without the keyword.
</Note>

## Authentication Flow

```
┌──────────────┐      ┌──────────────┐      ┌──────────────┐
│   Client     │──1──>│  Supabase    │──2──>│  Database    │
│ (Browser/App)│      │  Auth        │      │  (RLS)       │
└──────────────┘      └──────────────┘      └──────────────┘
       │                      │                      │
       │<─────────3───────────│                      │
       │  Session Token       │                      │
       │                      │                      │
       │──────4──────────────────────────────────────>│
       │  Authenticated Request (w/ session)          │
       │<─────────────────────────────────────────────│
       │  Data (filtered by RLS)                      │
```

1. User signs in via Supabase Auth
2. Supabase validates credentials against database
3. Client receives session token
4. Subsequent requests include session token for RLS

## Cross-App Supabase Cookies

Production Tuturuuu browser sessions use one canonical Supabase auth cookie for
the configured Supabase project and share it across `*.tuturuuu.com` by setting
`Domain=.tuturuuu.com`. Portless local development does the same across
`*.tuturuuu.localhost` with `Domain=.tuturuuu.localhost`.

Keep the cookie host-only for plain `localhost`, preview deployments, and
unrelated domains. Registered satellite apps still keep Tuturuuu app-session
JWTs as a fallback and API isolation mechanism, so do not remove app-session
refresh or handoff paths when updating shared Supabase cookie behavior.

## Web Multi-Account Sessions

`apps/web` stores multi-account sessions in a server-owned vault instead of
browser `localStorage`. The browser keeps only an HttpOnly device cookie and
loads account summaries from `/api/v1/auth/accounts`; Supabase access and
refresh tokens remain encrypted in `private.web_account_sessions`.

Use `WEB_MULTI_ACCOUNT_SESSION_SECRET` for vault encryption when available. If
it is not configured, the server falls back to `SUPABASE_SECRET_KEY`,
`SUPABASE_SERVICE_ROLE_KEY`, then `SUPABASE_SERVICE_KEY`. Never expose those
values to client components or upload legacy browser-stored sessions into the
vault; users should re-add accounts after storage migrations.

### Keeping stored sessions usable

Supabase rotates the refresh token every time the browser refreshes a session,
so a stored copy is only good until the account it belongs to refreshes. A
switch therefore writes the *outgoing* account's live session into its row
before calling `setSession` for the incoming one — without that, switching back
fails, the row is deleted as unusable, and a retry reports the account as
missing entirely.

When a switch does fail, the response carries `requiresReauth: true` and the
account has already been dropped from the vault. Clients must re-read
`/api/v1/auth/accounts` on failure so the dead entry disappears, and should tell
the user to sign into that account again rather than surfacing the raw error.

A switch redirect is a navigation instruction, not a stored route: `/login` and
`/add-account` are rejected for `last_route` on purpose, so never resolve an
explicit `targetRoute` through the persistable-route filter or you will drop a
sign-in that is still in flight.

## Sign Up

### Basic Email/Password Sign Up

```typescript theme={null}
"use server";

import { createClient } from "@tuturuuu/supabase/next/server";
import { redirect } from "next/navigation";

export async function signUp(formData: FormData) {
  const supabase = await createClient();

  const email = formData.get("email") as string;
  const password = formData.get("password") as string;
  const displayName = formData.get("displayName") as string;

  const { data, error } = await supabase.auth.signUp({
    email,
    password,
    options: {
      data: {
        display_name: displayName,
      },
      emailRedirectTo: `${process.env.NEXT_PUBLIC_APP_URL}/auth/callback`,
    },
  });

  if (error) {
    return { error: error.message };
  }

  redirect("/verify-email");
}
```

### Client Component

```tsx theme={null}
"use client";

import { signUp } from "./actions";
import { useState } from "react";

export function SignUpForm() {
  const [error, setError] = useState<string | null>(null);

  async function handleSubmit(formData: FormData) {
    const result = await signUp(formData);
    if (result?.error) {
      setError(result.error);
    }
  }

  return (
    <form action={handleSubmit}>
      <input name="displayName" placeholder="Display Name" required />
      <input name="email" type="email" placeholder="Email" required />
      <input name="password" type="password" placeholder="Password" required />
      {error && <p className="text-dynamic-red">{error}</p>}
      <button type="submit">Sign Up</button>
    </form>
  );
}
```

## Sign In

### Email/Password Sign In

```typescript theme={null}
"use server";

import { createClient } from "@tuturuuu/supabase/next/server";
import { redirect } from "next/navigation";

export async function signIn(formData: FormData) {
  const supabase = await createClient();

  const email = formData.get("email") as string;
  const password = formData.get("password") as string;

  const { data, error } = await supabase.auth.signInWithPassword({
    email,
    password,
  });

  if (error) {
    return { error: error.message };
  }

  redirect("/dashboard");
}
```

### OAuth Sign In

The providers offered on the login page and in account linking come from
`AUTH_OAUTH_PROVIDERS` in `apps/web/src/lib/auth/oauth-providers.ts` — one list
drives the buttons, the `/api/v1/users/me/identities/link/[provider]` route, and
the settings linked-accounts card. Adding a provider anywhere means adding it
there.

<Warning>
  **The Supabase Azure provider must be pinned to a single tenant.** Microsoft
  (`azure`) is offered with the `email` scope, and Supabase links an OAuth
  identity into an existing account when the provider reports that address as
  verified. On the shared multi-tenant `common` issuer that claim is only an
  assertion by whichever directory the user signed in from, so anyone who
  controls any Azure directory could claim a Tuturuuu address and take over the
  matching account. Set the provider's URL override to your tenant, not
  `common`.
</Warning>

```typescript theme={null}
"use server";

import { createClient } from "@tuturuuu/supabase/next/server";

export async function signInWithOAuth(provider: "google" | "github") {
  const supabase = await createClient();

  const { data, error } = await supabase.auth.signInWithOAuth({
    provider,
    options: {
      redirectTo: `${process.env.NEXT_PUBLIC_APP_URL}/auth/callback`,
    },
  });

  if (error) {
    return { error: error.message };
  }

  return { url: data.url };
}
```

Client Component:

```tsx theme={null}
"use client";

import { signInWithOAuth } from "./actions";

export function OAuthButtons() {
  async function handleOAuthSignIn(provider: "google" | "github") {
    const result = await signInWithOAuth(provider);
    if (result.url) {
      window.location.href = result.url;
    }
  }

  return (
    <div>
      <button onClick={() => handleOAuthSignIn("google")}>
        Sign in with Google
      </button>
      <button onClick={() => handleOAuthSignIn("github")}>
        Sign in with GitHub
      </button>
    </div>
  );
}
```

### OAuth Callback State

For provider-specific OAuth callbacks that need to carry ephemeral verifier or
CSRF state across a browser redirect, prefer a short-lived HttpOnly cookie scoped
to the callback route. When the callback binds external credentials or mutates a
workspace, do not let the cookie value be the sole authority: use a signed,
expiry-bound state payload that also binds the workspace or account being
connected, then require the callback cookie and query `state` to match before
verifying that payload.

### Email-Based Auth Recovery

Infrastructure admins can use **Infrastructure > Auth Recovery** when a
manually reviewed user cannot complete normal OTP or password sign-in because of
email-scoped infrastructure blocks, stale Supabase bans, or OTP counters.

The support flow is:

1. Search the email on the Auth Recovery page and inspect diagnostics.
2. Create a recovery override with a support reason. Overrides default to 7 days.
3. Keep both **normal login** and **recovery email** enabled unless the case
   needs only one path.
4. Use **Send recovery email**. The platform sends the email; admins should not
   copy tokens or links manually.
5. The user can click the recovery link or enter the 6-digit code on
   `/auth/recovery`. Recovery credentials expire after 15 minutes and are
   single-use.
6. Revoke the override once the user has recovered access or the case no longer
   needs support access.

Normal-login overrides bypass only email-scoped infrastructure and OTP/password
rate-limit blocks. They still enforce malformed request validation, suspicious
user-agent checks, Turnstile, password correctness, MFA, and active IP blocks
unless an admin separately clears those IP blocks. When a valid override is used,
the service also attempts to clear the Supabase auth ban and confirm the email.

Recovery-email sign-in stores token and code hashes in private schema tables and
audits sends, consumes, rejects, creates, revokes, and Supabase unban/create
attempts. The recovery session is created with the existing admin
`generateLink` plus detached `verifyOtp` pattern, then normal auth cookies are
set. Redirects are limited to sanitized app paths.

Database objects live in:

* `private.auth_recovery_overrides`
* `private.auth_recovery_tokens`
* `private.auth_recovery_events`

Use `AUTH_RECOVERY_HASH_SECRET` in production when available. The code falls
back to existing Supabase server secrets for local development, but do not expose
those values to clients or support tooling. Do not run `bun sb:push` for this
change; apply migrations through the normal database release process.

### Passkeys

Passkeys use Supabase Auth's experimental WebAuthn APIs. Browser clients created
through `@tuturuuu/supabase/next/auth-browser` must pass
`auth.experimental.passkey: true`; otherwise Supabase rejects
`auth.signInWithPasskey()`, `auth.registerPasskey()`, and
`auth.passkey.*` calls.

`apps/web` owns passkey UX:

1. The public login form exposes an explicit "Continue with passkey" action so
   users can open the browser passkey picker without relying only on autofill.
2. Account Security in the apps/web settings dialog owns passkey registration,
   rename, and delete actions. Do not add separate passkey settings pages.
3. Satellite apps should continue to route user authentication through apps/web
   cross-app auth. Passkeys are bound to the relying party domain, so the central
   apps/web origin remains the authority for Tuturuuu account passkeys.

Production Supabase Auth must have passkeys enabled with these relying party
settings:

* Relying Party Display Name: `Tuturuuu`
* Relying Party ID: `tuturuuu.com`
* Relying Party Origins: `https://tuturuuu.com`

Local Supabase Auth must also enable passkeys in
`apps/database/supabase/config.toml`. The committed local config uses the
Portless apps/web origin:

* Relying Party Display Name: `Tuturuuu`
* Relying Party ID: `tuturuuu.localhost`
* Relying Party Origins: `https://tuturuuu.localhost`

Restart local Supabase after changing this config; the Auth service reads these
settings on startup. Real WebAuthn ceremonies require a secure origin, so test
registration and sign-in from `https://tuturuuu.localhost`. UI-only and
unsupported-browser paths can still be exercised without registering a
credential.

Remote Supabase development auth is different: if a cloud Supabase project has
captcha protection enabled, passkey sign-in must send a real Turnstile token.
The local E2E bypass is honored only when `NEXT_PUBLIC_SUPABASE_URL` points at
local Supabase. When testing remote Supabase from `https://tuturuuu.localhost`,
the Turnstile site key must authorize that local hostname; Cloudflare Turnstile
error `110200` means the widget cannot mint the token Supabase requires. The
login UI keeps passkey sign-in blocked while that token is missing; either add
the local hostname to the Cloudflare Turnstile widget used by the Supabase
project, or point `NEXT_PUBLIC_SUPABASE_URL` at local Supabase for dev passkey
testing.

### Web QR Session Handoff

QR-based session handoff must never be a public login bootstrap. An
unauthenticated browser cannot prove that it belongs to the account scanning the
QR code, so public challenge creation would allow QR phishing where an attacker
polls a victim-approved challenge and receives the victim's session.

The QR challenge endpoints are therefore constrained to authenticated,
same-account handoff:

1. `POST /api/v1/auth/qr-login/challenges` validates the request origin and the
   request-scoped Supabase session before inserting a `qr_login_challenges` row.
   The row stores a hashed secret, request metadata, `creatorUserId`, and a
   two-minute expiry.
2. The client renders a `tuturuuu://auth/qr-login` payload that contains the
   challenge id, one-time secret, and web origin.
3. The signed-in mobile app scans the code from Settings > Session. Mobile must
   have app lock enabled, then performs local authentication before approving.
4. `POST /api/v1/auth/qr-login/challenges/:id/approve` validates the mobile
   Bearer session, challenge secret, and `creatorUserId`. The approver must be
   the same user that created the challenge.
5. The creator polls `GET /api/v1/auth/qr-login/challenges/:id?secret=...`.
   Once approved, the server consumes the challenge and creates a fresh detached
   Supabase session via admin `generateLink` plus detached `verifyOtp`.

QR challenge rows never store access or refresh tokens. The table is RLS-enabled
without anon/authenticated grants; API routes use the service role for challenge
state and the request-scoped client to validate both the challenge creator and
the mobile approver.

## Sign Out

```typescript theme={null}
"use server";

import { createClient } from "@tuturuuu/supabase/next/server";
import { redirect } from "next/navigation";

export async function signOut() {
  const supabase = await createClient();
  await supabase.auth.signOut();
  redirect("/login");
}
```

## Server-side Auth Resolution (`getClaims` first)

For server-side route and helper authorization checks, prefer a claims-first flow:

1. Call `supabase.auth.getClaims()` first.
2. Use `claims.sub` as the authenticated user id when available.
3. Fall back to `supabase.auth.getUser()` when claims are unavailable or insufficient.

This reduces auth latency on hot API paths while preserving correctness for call sites
that still need canonical user resolution.

```typescript theme={null}
async function resolveCurrentUserId(supabase: TypedSupabaseClient) {
  const getClaims = (supabase.auth as { getClaims?: () => Promise<unknown> })
    .getClaims;

  if (typeof getClaims === "function") {
    const { data, error } = (await getClaims.call(supabase.auth)) as {
      data?: { claims?: { sub?: string } };
      error?: unknown;
    };

    if (!error && data?.claims?.sub) {
      return data.claims.sub;
    }
  }

  const {
    data: { user },
  } = await supabase.auth.getUser();

  return user?.id ?? null;
}
```

When implementing this pattern, feature-detect `getClaims` first. Some tests and
older stubs only mock `getUser`, and unconditional `getClaims` calls will break
those environments.

## Multi-Factor Authentication (MFA)

### Enable TOTP MFA

```typescript theme={null}
"use server";

import { createClient } from "@tuturuuu/supabase/next/server";

export async function enableMFA() {
  const supabase = await createClient();

  // Enroll in MFA
  const { data, error } = await supabase.auth.mfa.enroll({
    factorType: "totp",
  });

  if (error) throw error;

  return {
    qrCode: data.totp.qr_code, // Display to user
    secret: data.totp.secret, // For manual entry
    factorId: data.id,
  };
}
```

### Verify MFA Enrollment

```typescript theme={null}
"use server";

import { createClient } from "@tuturuuu/supabase/next/server";

export async function verifyMFAEnrollment(factorId: string, code: string) {
  const supabase = await createClient();

  const { data, error } = await supabase.auth.mfa.challengeAndVerify({
    factorId,
    code,
  });

  if (error) throw error;
  return { success: true };
}
```

### MFA Challenge During Sign In

```typescript theme={null}
"use server";

import { createClient } from "@tuturuuu/supabase/next/server";

export async function signInWithMFA(email: string, password: string) {
  const supabase = await createClient();

  // Initial sign in
  const { data: signInData, error: signInError } =
    await supabase.auth.signInWithPassword({
      email,
      password,
    });

  if (signInError) throw signInError;

  // Check if MFA is required
  const { data: factors } = await supabase.auth.mfa.listFactors();

  if (factors && factors.totp.length > 0) {
    const factorId = factors.totp[0].id;

    // Create MFA challenge
    const { data: challengeData, error: challengeError } =
      await supabase.auth.mfa.challenge({ factorId });

    if (challengeError) throw challengeError;

    return {
      requiresMFA: true,
      challengeId: challengeData.id,
      factorId,
    };
  }

  return { requiresMFA: false };
}
```

### Verify MFA Code

```typescript theme={null}
"use server";

import { createClient } from "@tuturuuu/supabase/next/server";

export async function verifyMFACode(
  factorId: string,
  challengeId: string,
  code: string,
) {
  const supabase = await createClient();

  const { data, error } = await supabase.auth.mfa.verify({
    factorId,
    challengeId,
    code,
  });

  if (error) throw error;
  return { success: true };
}
```

### Mobile MFA Approval Cookies

Mobile approval for web MFA is scoped to the Supabase login session that created
and consumed the approval challenge. When the web browser polls an approved
mobile MFA challenge, store the current JWT `session_id` in the challenge
approval metadata. The auth proxy must compare that stored session id with the
current request claims before using `ttr_mfa_mobile_approval` to bypass the MFA
redirect.

Do not treat the approval cookie as a user-scoped remember-me token. A valid
cookie only proves that one challenge secret was approved; it must also match
the current Supabase session. Central logout responses should expire the
approval cookie, and MFA redirects should clear stale approval cookies that do
not satisfy the current-session binding.

## Session Management

### Get Current Session

```typescript theme={null}
import { createClient } from "@tuturuuu/supabase/next/server";

export async function getSession() {
  const supabase = await createClient();

  const {
    data: { session },
    error,
  } = await supabase.auth.getSession();

  if (error) throw error;
  return session;
}
```

### Get Current User

```typescript theme={null}
import { createClient } from "@tuturuuu/supabase/next/server";

export async function getCurrentUser() {
  const supabase = await createClient();

  const {
    data: { user },
    error,
  } = await supabase.auth.getUser();

  if (error || !user) {
    return null;
  }

  return user;
}
```

### Refresh Session

```typescript theme={null}
"use server";

import { createClient } from "@tuturuuu/supabase/next/server";

export async function refreshSession() {
  const supabase = await createClient();

  const { data, error } = await supabase.auth.refreshSession();

  if (error) throw error;
  return data.session;
}
```

## Password Reset

### Request Password Reset

```typescript theme={null}
"use server";

import { createClient } from "@tuturuuu/supabase/next/server";

export async function requestPasswordReset(email: string) {
  const supabase = await createClient();

  const { error } = await supabase.auth.resetPasswordForEmail(email, {
    redirectTo: `${process.env.NEXT_PUBLIC_APP_URL}/auth/reset-password`,
  });

  if (error) throw error;
  return { success: true };
}
```

### Reset Password

```typescript theme={null}
"use server";

import { createClient } from "@tuturuuu/supabase/next/server";

export async function resetPassword(newPassword: string) {
  const supabase = await createClient();

  const { data, error } = await supabase.auth.updateUser({
    password: newPassword,
  });

  if (error) throw error;
  return { success: true };
}
```

## Email Verification

### Resend Verification Email

```typescript theme={null}
"use server";

import { createClient } from "@tuturuuu/supabase/next/server";

export async function resendVerificationEmail() {
  const supabase = await createClient();

  const {
    data: { user },
  } = await supabase.auth.getUser();

  if (!user?.email) {
    throw new Error("No user email found");
  }

  const { error } = await supabase.auth.resend({
    type: "signup",
    email: user.email,
  });

  if (error) throw error;
  return { success: true };
}
```

## Cross-App Authentication

The platform supports token-based authentication across different apps using `@tuturuuu/auth/cross-app`.

When a new satellite app participates in centralized login, wire both sides in the same patch:

* Register the app URL in `packages/utils/src/internal-domains.ts` so `mapUrlToApp(...)` can recognize its `returnUrl`.
* Add `apps/<app>/src/app/api/auth/verify-app-token/route.ts` so
  `/verify-token` can exchange the cross-app token for a host-only
  `tuturuuu_app_session` cookie. When the satellite requires rewritten
  `apps/web` API access, use `createPOST('<app>', { verificationBaseUrl:
  WEB_APP_URL })` so the handoff also stores the Web-issued app-session cookie.
* Keep `generate_cross_app_token(...)` bound to the authenticated caller
  (`p_user_id = auth.uid()`) so verify endpoints cannot mint sessions for
  arbitrary users.
* Do not call `supabase.auth.setSession()` in registered internal apps. The
  verifier route sets the HttpOnly app-session cookie, and satellite UI should
  fetch user/profile data by forwarding that cookie to central internal APIs.
* Registered internal app source must not call `supabase.auth.*` directly.
  Use `@tuturuuu/auth/app-session` server helpers and `@tuturuuu/internal-api`
  profile/default-workspace helpers instead; `bun check` runs the static guard
  across all registered app `src` directories.
* App-session auth is read/update oriented for satellite apps. Destructive
  workspace operations such as `DELETE /api/workspaces/[wsId]` require a full
  Supabase session (cookie or bearer) and `manage_workspace_settings`; they do
  not opt into `allowAppSessionAuth` because the app-session path uses an
  admin-backed client that would bypass workspace delete RLS.

If either piece is missing, centralized login can stall on the web login spinner or land on `/verify-token` with no token-verification endpoint to finish the handoff.

### Generate Cross-App Token

`generateCrossAppToken(supabase, targetApp, originApp, expirySeconds?)` is the
real signature. It reads the authenticated user from the passed Supabase client,
calls the `generate_cross_app_token` RPC, and returns the token string (or
`null` on failure). The origin app (`'web'`) mints the token; the target app
(`'shortener'`, `'nova'`, `'rewise'`, etc.) verifies it.

```typescript theme={null}
import { generateCrossAppToken } from "@tuturuuu/auth/cross-app";
import { createClient } from "@tuturuuu/supabase/next/server";

export async function createShortenerLink() {
  const supabase = await createClient();

  // Generate a token the shortener app can verify (default expiry: 300s).
  const token = await generateCrossAppToken(
    supabase,
    "shortener", // targetApp
    "web", // originApp
    3600, // expirySeconds (optional)
  );

  if (!token) {
    throw new Error("Failed to generate cross-app token");
  }

  return {
    url: `${process.env.SHORTENER_APP_URL}/create?token=${token}`,
  };
}
```

### Validate Cross-App Token

The target app validates the token with
`validateCrossAppToken(supabase, token, targetApp)`, which calls the
`validate_cross_app_token_with_session` RPC and returns `{ userId }` (or `null`).
The target app is responsible for establishing its own session/app-session from
that `userId`; the token never carries access or refresh tokens.

```typescript theme={null}
import { validateCrossAppToken } from "@tuturuuu/auth/cross-app";
import { createClient } from "@tuturuuu/supabase/next/server";

export async function handleCrossAppRequest(token: string) {
  const supabase = await createClient();

  const result = await validateCrossAppToken(supabase, token, "shortener");

  if (!result) {
    throw new Error("Invalid token");
  }

  // result contains: { userId }
  return result;
}
```

<Note>
  `@tuturuuu/auth/cross-app` does **not** export a `verifyCrossAppToken`
  function. For the browser-side handoff on `/verify-token`, use the exported
  `verifyRouteToken({ searchParams, token, router })` helper, which POSTs the
  token to `/api/auth/verify-app-token` and lets the verifier route set the
  HttpOnly app-session cookie. `revokeAllCrossAppTokens(supabase)` invalidates a
  user's outstanding tokens.
</Note>

## Proxy (Edge Middleware) Authentication

In `apps/web` the edge entry point that protects routes lives in
`apps/web/src/proxy.ts` (not a `middleware.ts` file). It exports an async
`proxy(req)` function plus a `config.matcher`, and Next.js is configured to use
this file as the request middleware. The real implementation delegates the
heavy lifting to `createCentralizedAuthProxy` from `@tuturuuu/auth/proxy`, then
layers on onboarding checks, workspace-slug normalization, guest-route guards,
and locale handling. See [Routing](/platform/architecture/routing) for how the
proxy coordinates those concerns.

The simplified example below shows the core shape: resolve the user from a
request-scoped Supabase client and redirect when unauthenticated. Note that
`createDynamicClient()` is async and must be awaited.

```typescript theme={null}
// apps/web/src/proxy.ts (simplified)
import { createClient } from "@tuturuuu/supabase/next/server";
import { type NextRequest, NextResponse } from "next/server";

export async function proxy(request: NextRequest) {
  const supabase = await createClient();

  const {
    data: { user },
  } = await supabase.auth.getUser();

  // Protect dashboard routes
  if (request.nextUrl.pathname.startsWith("/dashboard") && !user) {
    return NextResponse.redirect(new URL("/login", request.url));
  }

  // Redirect authenticated users from auth pages
  if (request.nextUrl.pathname.startsWith("/login") && user) {
    return NextResponse.redirect(new URL("/dashboard", request.url));
  }

  return NextResponse.next();
}

export const config = {
  matcher: ["/dashboard/:path*", "/login", "/signup"],
};
```

The production proxy resolves the user with
`resolveAuthenticatedSessionUser(supabase)` and propagates refreshed auth
cookies onto every redirect via `propagateAuthCookies(authRes, response)`.
Reuse those helpers instead of re-implementing session resolution and cookie
forwarding when you extend the proxy.

## Protected Server Component

```typescript theme={null}
import { createClient } from '@tuturuuu/supabase/next/server';
import { redirect } from 'next/navigation';

export default async function ProtectedPage() {
  const supabase = await createClient();

  const { data: { user } } = await supabase.auth.getUser();

  if (!user) {
    redirect('/login');
  }

  return (
    <div>
      <h1>Welcome, {user.email}</h1>
    </div>
  );
}
```

## Client-Side Authentication

<Warning>
  `@tuturuuu/supabase/next/client` is **deprecated** for CRUD/storage and may
  throw unless a compatibility flag is set. For browser data access, use
  `@tuturuuu/internal-api`. For the narrow case where the browser genuinely
  needs an auth client (reacting to live auth-state changes), use
  `createAuthClient()` from `@tuturuuu/supabase/next/auth-browser`. Do not fetch
  product data on the client through raw Supabase clients, and prefer TanStack
  Query over `useEffect` for any data fetching.
</Warning>

### useUser Hook (auth-state subscription)

Subscribing to Supabase auth-state changes is a legitimate exception to the
"no `useEffect` for data fetching" guidance: this hook does not fetch product
data, it mirrors the live session into React state. Use `createAuthClient` and
subscribe once.

```tsx theme={null}
"use client";

import type { User } from "@supabase/supabase-js";
import { createAuthClient } from "@tuturuuu/supabase/next/auth-browser";
import { useEffect, useMemo, useState } from "react";

export function useUser() {
  const [user, setUser] = useState<User | null>(null);
  const [loading, setLoading] = useState(true);
  const supabase = useMemo(() => createAuthClient(), []);

  useEffect(() => {
    // Resolve the current user once on mount.
    supabase.auth.getUser().then(({ data: { user } }) => {
      setUser(user ?? null);
      setLoading(false);
    });

    // Then keep it in sync with live auth-state changes.
    const {
      data: { subscription },
    } = supabase.auth.onAuthStateChange((_event, session) => {
      setUser(session?.user ?? null);
    });

    return () => subscription.unsubscribe();
  }, [supabase]);

  return { user, loading };
}
```

<Note>
  For authorization decisions, always re-verify the user server-side
  (`await supabase.auth.getUser()` or the `getClaims`-first pattern above). Client
  auth state is for UX only — never trust it as the sole gate for protected data.
</Note>

### Usage

```tsx theme={null}
"use client";

import { useUser } from "@/hooks/useUser";

export function UserProfile() {
  const { user, loading } = useUser();

  if (loading) return <div>Loading...</div>;
  if (!user) return <div>Not authenticated</div>;

  return <div>Logged in as {user.email}</div>;
}
```

## Identity Linking

Link multiple auth providers to same account:

```typescript theme={null}
"use server";

import { createClient } from "@tuturuuu/supabase/next/server";

export async function linkIdentity(provider: "google" | "github") {
  const supabase = await createClient();

  const { data, error } = await supabase.auth.linkIdentity({
    provider,
  });

  if (error) throw error;
  return { url: data.url };
}
```

## Best Practices

### ✅ DO

1. **Always check authentication server-side**

   ```typescript theme={null}
   const {
     data: { user },
   } = await supabase.auth.getUser();
   if (!user) throw new Error("Unauthorized");
   ```

2. **Redirect after authentication**

   ```typescript theme={null}
   redirect("/dashboard"); // Don't return sensitive data
   ```

3. **Handle errors gracefully**

   ```typescript theme={null}
   if (error) return { error: error.message };
   ```

4. **Implement MFA for sensitive operations**
   ```typescript theme={null}
   const mfaRequired = await checkMFAEnabled(userId);
   ```

### ❌ DON'T

1. **Don't trust client-side auth state alone**

   ```typescript theme={null}
   // ❌ Bad
   if (localStorage.getItem("user")) {
     /* ... */
   }
   ```

2. **Don't expose sensitive data in auth redirects**

   ```typescript theme={null}
   // ❌ Bad
   redirect(`/dashboard?apiKey=${apiKey}`);
   ```

3. **Don't store passwords**

   ```typescript theme={null}
   // ❌ Bad: Let Supabase handle password storage
   ```

4. **Don't use `createAdminClient()` for auth operations**
   ```typescript theme={null}
   // ❌ Bad: Use regular client
   const sbAdmin = await createAdminClient();
   await sbAdmin.auth.signUp({ ... });
   ```

## Related Documentation

* [Authorization](/platform/architecture/authorization) - Permission system
* [Supabase Client](/reference/packages/supabase) - Client creation patterns
* [RLS Policies](/reference/database/rls-policies) - Database security

## External Resources

* [Supabase Auth Documentation](https://supabase.com/docs/guides/auth)
* [Next.js Authentication](https://nextjs.org/docs/app/building-your-application/authentication)


# Authorization & Permissions
Source: https://docs.tuturuuu.com/platform/architecture/authorization

How apps/web evaluates workspace-scoped permissions and where those checks are enforced

`apps/web` uses workspace-scoped permissions, not a single coarse role string, to decide what a signed-in user can see or mutate.

The important implementation detail is that modern permission checks do **not** read `workspace_members.role`. The effective permission set is computed from:

* `workspace_role_members`
* `workspace_role_permissions`
* `workspace_default_permissions`
* workspace creator fallback logic in `getPermissions()`

`workspace_default_permissions` is typed by `member_type`:

* `MEMBER` rows are the normal workspace defaults for members and API keys.
* `GUEST` rows are signed-in guest defaults. Missing guest rows mean denied.

Guest defaults use the same `workspace_role_permission` catalog as member defaults, including management and `admin` bits, but guests are still denied on dashboard routes that have no mapped permission.

For the full workspace model, including URL resolution and API-key auth, see `platform/architecture/workspaces-permissions`.

## Core Helper

The main entry point is `getPermissions()` in `packages/utils/src/workspace-helper.ts`.

It evaluates permissions in this order:

1. Authenticate the current user with a request-scoped or cookie-scoped Supabase client.
2. Normalize the incoming workspace identifier so `personal` and `internal` become real workspace IDs.
3. Verify caller membership with `verifyWorkspaceMembershipType(..., requiredType: 'ANY')` so the helper can distinguish `MEMBER` from `GUEST`.
4. For `MEMBER`, load role-derived permissions from `workspace_role_members -> workspace_roles -> workspace_role_permissions`.
5. Load workspace-wide defaults from `workspace_default_permissions` using the resolved `member_type`.
6. Load the workspace creator and treat that member as an implicit superuser.

If the user is the workspace creator, `getPermissions()` returns the full permission catalog from `packages/utils/src/permissions.tsx`.

If the user is not the creator, `getPermissions()` returns the deduplicated union of:

* enabled permissions from every assigned workspace role
* enabled default workspace permissions for the resolved membership type

If the user has no effective permissions and is not the creator, the helper returns `null`.

For `GUEST`, role-derived permissions and creator fallback are skipped. The helper only reads `workspace_default_permissions.member_type = 'GUEST'`, so a guest with no enabled guest defaults receives no effective permissions.

## `admin` Is A Permission Bit

`admin` is part of the normal permission catalog. It is not a separate evaluator or a special membership table.

Once `containsPermission()` sees `admin` in the effective permission list, it treats every permission check as allowed:

```ts theme={null}
const isAdmin = permissions.includes('admin');

const containsPermission = (permission: PermissionId) => {
  return isCreator || isAdmin || permissions.includes(permission);
};
```

That means creator and `admin` behave similarly at call sites, even though they come from different sources:

* creator access is implicit and computed in code
* `admin` access is explicit and stored like any other permission

For guests, `admin` can satisfy a mapped permission route, but it does not open routes with no permission mapping. The dashboard shell stays default-deny for guest routes that cannot be tied to a permission ID.

## Permission Catalog

The permission catalog lives in `packages/utils/src/permissions.tsx`.

The non-root workspace groups currently include permissions for:

* workspace administration
* AI
* calendar
* projects
* documents
* time tracking
* drive
* users
* user groups
* leads
* inventory
* finance
* workforce
* transactions
* invoices

The root workspace adds an extra infrastructure-only group. Some catalog entries are also conditionally exposed for root or `@tuturuuu.com` users.

This matters because creator fallback uses the catalog directly. If a permission is added to the product but not added to the catalog, creator fallback and roles UI drift immediately.

## Where Web Pages Use It

Typical server-page flow in `apps/web`:

1. Resolve the workspace with `WorkspaceWrapper` or `getWorkspace()`.
2. Call `getPermissions({ wsId })`.
3. Redirect or `notFound()` when the required permission is missing.
4. Pass `containsPermission` / `withoutPermission` into the page composition.

Examples:

* `apps/web/src/app/[locale]/(dashboard)/[wsId]/(workspace-settings)/roles/page.tsx`
* `apps/web/src/app/[locale]/(dashboard)/[wsId]/(workspace-settings)/members/page.tsx`
* `apps/web/src/app/[locale]/(dashboard)/[wsId]/(workspace-settings)/settings/page.tsx`
* `apps/web/src/app/[locale]/(dashboard)/[wsId]/navigation.tsx`

`navigation.tsx` is especially important because a large part of the UX is permission-driven before the user even clicks into a page. Sidebar items are disabled or hidden from `withoutPermission(...)`, and some cross-workspace admin affordances also compare root-workspace permissions.

## Where API Routes Use It

There are three common patterns in `apps/web` routes.

### 1. Session auth only

Some routes only verify that the caller is signed in, usually through `createClient(request)` or `withSessionAuth(...)`.

Use this when the operation is about the current signed-in user or the route does not grant privileged workspace mutations by itself.

### 2. Membership + workspace normalization

Many workspace-scoped routes first convert the route param into a canonical workspace ID with `normalizeWorkspaceId(wsId, supabase)` and then verify membership.

This is the baseline for routes that accept `personal` or `internal` in the URL but must query by UUID in the database.

For non-permission routes that still require protected workspace access, use `verifyWorkspaceMembershipType(...)` from `packages/utils/src/workspace-helper.ts` and keep the default `requiredType` (`MEMBER`).

```ts theme={null}
const membership = await verifyWorkspaceMembershipType({
  wsId: normalizedWsId,
  userId: user.id,
  supabase,
});

if (membership.error === 'membership_lookup_failed') {
  return NextResponse.json({ message: 'Failed to verify workspace access' }, { status: 500 });
}

if (!membership.ok) {
  return NextResponse.json({ message: "You don't have access to this workspace" }, { status: 403 });
}
```

`workspace_members` now supports `MEMBER` and `GUEST`. If a route is not explicitly guest-capable, it should require `MEMBER` and avoid ad-hoc `.from('workspace_members')` checks that only validate row existence.

`normalizeWorkspaceId('personal', ...)` also enforces MEMBER membership on the personal-workspace join path by filtering `workspace_members.type = 'MEMBER'`.

Course consumption routes are the exception that combine both models: `MEMBER` workspace rows keep normal course access, while `GUEST` rows must pass `workspace_guest_permissions` resource checks such as `course:view`.

### 3. Membership + explicit permission gate

Privileged routes call `getPermissions()` after normalization and reject when `containsPermission(...)` fails.

This is the pattern to use for settings, finance, roles, infrastructure, and any other restricted mutation surface.

If a route writes workspace membership, invitations, roles, or other authorization
data with `createAdminClient()` / service-role privileges, enforce the relevant
permission before the admin write. A `workspace_members` row alone is never
enough for those flows: invite creation and membership-type changes require
`manage_workspace_members`, and `workspace_members.type` is protected at the
database layer so non-managers cannot self-promote from `GUEST` to `MEMBER`.

When a server page or API route uses `createAdminClient()` after a workspace
permission gate, the protected row lookup must still prove the row belongs to
the authorized route scope. For nested resources, include every trusted parent
identifier in the same query or RPC:

```ts theme={null}
await admin
  .schema('private')
  .from('user_group_posts')
  .select('id, group_id, workspace_user_groups!inner(ws_id)')
  .eq('id', postId)
  .eq('group_id', groupId)
  .eq('workspace_user_groups.ws_id', normalizedWsId)
  .maybeSingle();
```

Do not load a child row by ID with service-role privileges and then separately
validate only the supplied parent route data. A mismatched child ID can expose
cross-workspace data before later related lookups return empty results.

Education authoring and review APIs are also feature-gated. Routes that expose
quiz answer keys, learner attempt metadata, flashcards, quiz sets, or other
Education admin surfaces must use
`apps/web/src/lib/education/access.ts` so `ENABLE_EDUCATION` and `ai_lab` are
enforced server-side before any workspace-scoped read or mutation. Mobile and
other clients may hide Education affordances, but API routes remain the source
of truth for this gate.

## API Keys Reuse The Same Permission IDs

External SDK routes use `withApiAuth(...)` in `apps/web/src/lib/api-middleware.ts`.

The API key evaluator:

* authenticates a workspace API key from `workspace_api_keys`
* binds the request to exactly one workspace
* computes the effective permissions as `role permissions ∪ MEMBER default permissions`
* rejects requests whose `[wsId]` route param does not match the API key's workspace

That keeps permission IDs consistent across browser/session routes and external API routes, even though the authentication mechanism is different.

## Current Design Rules

* Use `getPermissions()` for feature-level authorization in server pages and session-auth routes.
* Use `normalizeWorkspaceId()` before querying workspace-scoped tables from route params.
* Do not assume `workspace_members.role` represents the effective permission model in `apps/web`.
* Treat `admin` as a permission that short-circuits checks, not as a separate role system.
* When adding new privileged features, update both the permission catalog and the UI/routes that consume it.


# Data Fetching Strategies
Source: https://docs.tuturuuu.com/platform/architecture/data-fetching

When and how to fetch data using RSC, Server Actions, TanStack Query, and Internal API helpers

The Tuturuuu platform uses a layered approach to data fetching, choosing the right strategy based on use case, caching requirements, and user experience needs.

<Note>
  The client-side fetch boundary is **TanStack Query (React Query v5) hooks backed
  by `@tuturuuu/internal-api` helpers**, which call the REST `/api/v1/...`
  endpoints. tRPC in `apps/web/src/trpc` is an **intentional stub** during the
  TanStack + Rust migration (it exposes only a `healthCheck` procedure), so this
  page does not use `trpc.*` routers for product data. See
  [tRPC Implementation](/platform/architecture/trpc) for the scaffold details.
</Note>

For the dedicated TanStack Start frontend plus Rust backend migration, use
`platform/architecture/tanstack-rust-migration`. TanStack loaders and server
functions are allowed as a BFF layer, while product data ownership moves behind
Rust endpoints and `packages/internal-api` facades.

## Heavy Dashboards

For queue-heavy dashboards that run expensive row + summary RPCs (for example posts review):

* Keep the route page server-only for auth, permissions, and canonical URL normalization.
* Move the actual table + summary fetch into a client shell with TanStack Query.
* Fetch through `@tuturuuu/internal-api` helpers, not ad-hoc client fetch calls.
* Avoid `router.refresh()` for routine list refreshes; prefer query refetch/invalidation.

## Server And Service Orchestration

When a server-side data flow coordinates multiple async resources, expected
failures, retry/scheduling policy, or replaceable dependencies, use
`@tuturuuu/utils/effect` inside the server/shared helper and keep the route or
client boundary plain. Effect complements this page's data-fetching strategy; it
does not replace React state, TanStack Query, `packages/internal-api`, Zod, or
generated database types.

Use Effect for server/service orchestration:

```ts theme={null}
import {
  Effect,
  fromDataError,
  runEffectAsResult,
} from '@tuturuuu/utils/effect';

const program = fromDataError(
  () =>
    supabase
      .from('workspace_tasks')
      .select('id, name')
      .eq('ws_id', wsId),
  {
    code: 'TASKS_READ_FAILED',
    message: 'Task list read failed.',
    context: { wsId },
  }
);

const result = await runEffectAsResult(Effect.map(program, (tasks) => ({ tasks })));
```

Client components should still call TanStack Query hooks and internal API
helpers. Server Components, Server Actions, API routes, cron jobs, and shared
packages may use Effect behind their public boundary when it improves typed
failure handling or orchestration clarity.

## Builder Migration Pattern (Education Module Groups)

For highly interactive editors (for example the course builder with module groups + drag/drop):

* Keep the route page as a thin server-side auth/permission gate.
* Move list data loading into a client shell backed by React Query.
* Use `@tuturuuu/internal-api` helpers as the client fetch boundary (`listWorkspaceCourseModuleGroups`, `listWorkspaceCourseModules`, and reorder helpers).
* Avoid `router.refresh()` for routine drag/drop updates; mutate via API and invalidate the corresponding query keys.
* When a drag/drop move changes both membership and order, await the membership mutation before firing any follow-up reorder mutations, and invalidate only the affected query keys instead of every list in the builder.
* Keep create/update payload contracts explicit (`module_group_id` is required for new course modules).

## Strategy Preference Order

Choose the earliest applicable strategy:

1. **Pure Server Component (RSC)** - Read-only, cacheable, SEO-critical data
2. **Server Action** - Mutations returning updated state to RSC
3. **RSC + Client Hydration** - When background refresh needed
4. **React Query (Client-Side)** - Interactive, rapidly changing state
5. **Realtime Subscriptions** - Live updates materially improve UX

## 1. Pure Server Component (RSC)

### When to Use

✅ **Best For:**

* Initial page load data
* SEO-critical content
* Rarely changing data
* Read-only operations
* Database queries that don't need real-time updates

❌ **Not For:**

* Interactive forms
* Frequent updates
* Client-side state
* Real-time data

### Implementation

```typescript theme={null}
// app/[locale]/(dashboard)/[wsId]/tasks/page.tsx
import { createClient } from '@tuturuuu/supabase/next/server';

export default async function TasksPage({
  params,
}: {
  params: Promise<{ wsId: string }>;
}) {
  const { wsId } = await params;
  // createClient() from @tuturuuu/supabase/next/server is async — always await it.
  const supabase = await createClient();

  // Direct database query in Server Component
  const { data: tasks } = await supabase
    .from('workspace_tasks')
    .select('*')
    .eq('ws_id', wsId)
    .order('created_at', { ascending: false })
    .limit(20);

  return (
    <div>
      <h1>Tasks</h1>
      <TaskList tasks={tasks || []} />
    </div>
  );
}
```

### Caching Strategy

```typescript theme={null}
// app/[locale]/(dashboard)/[wsId]/tasks/page.tsx

// Revalidate every hour
export const revalidate = 3600;

// OR generate static params
export async function generateStaticParams() {
  const supabase = await createClient();
  const { data: workspaces } = await supabase.from('workspaces').select('id');

  return workspaces?.map((ws) => ({ wsId: ws.id })) || [];
}
```

### Loading States

```typescript theme={null}
// app/[locale]/(dashboard)/[wsId]/tasks/loading.tsx
export default function Loading() {
  return <TasksSkeleton />;
}
```

### Error Handling

```typescript theme={null}
// app/[locale]/(dashboard)/[wsId]/tasks/error.tsx
'use client';

export default function Error({
  error,
  reset,
}: {
  error: Error;
  reset: () => void;
}) {
  return (
    <div>
      <h2>Something went wrong!</h2>
      <button onClick={reset}>Try again</button>
    </div>
  );
}
```

## 2. Server Actions

### When to Use

✅ **Best For:**

* Form submissions
* Mutations with server-side validation
* Operations requiring auth checks
* Redirects after mutations
* Progressive enhancement

❌ **Not For:**

* Read operations (use RSC instead)
* Complex client-side state management
* Real-time updates

### Implementation

```typescript theme={null}
// app/[locale]/(dashboard)/[wsId]/tasks/actions.ts
'use server';

import { createClient } from '@tuturuuu/supabase/next/server';
import { revalidatePath } from 'next/cache';
import { redirect } from 'next/navigation';
import { z } from 'zod';

const createTaskSchema = z.object({
  name: z.string().min(1).max(255),
  description: z.string().optional(),
  listId: z.string(),
});

export async function createTask(formData: FormData) {
  const supabase = await createClient();

  // Check authentication
  const {
    data: { user },
  } = await supabase.auth.getUser();
  if (!user) {
    throw new Error('Unauthorized');
  }

  // Validate input
  const parsed = createTaskSchema.safeParse({
    name: formData.get('name'),
    description: formData.get('description'),
    listId: formData.get('listId'),
  });

  if (!parsed.success) {
    return { error: 'Invalid input' };
  }

  // Perform mutation
  const { data, error } = await supabase
    .from('workspace_tasks')
    .insert({
      name: parsed.data.name,
      description: parsed.data.description,
      list_id: parsed.data.listId,
      created_by: user.id,
    })
    .select()
    .single();

  if (error) {
    return { error: error.message };
  }

  // Revalidate cache
  revalidatePath(`/[locale]/(dashboard)/[wsId]/tasks`);

  return { success: true, task: data };
}

export async function deleteTask(taskId: string, wsId: string) {
  const supabase = await createClient();

  const { error } = await supabase
    .from('workspace_tasks')
    .delete()
    .eq('id', taskId);

  if (error) {
    return { error: error.message };
  }

  revalidatePath(`/[locale]/(dashboard)/${wsId}/tasks`);
  redirect(`/${wsId}/tasks`);
}
```

### Client Usage

```tsx theme={null}
'use client';

import { createTask } from './actions';
import { useFormStatus } from 'react-dom';

function SubmitButton() {
  const { pending } = useFormStatus();

  return (
    <button type="submit" disabled={pending}>
      {pending ? 'Creating...' : 'Create Task'}
    </button>
  );
}

export function CreateTaskForm({ listId }: { listId: string }) {
  async function handleSubmit(formData: FormData) {
    const result = await createTask(formData);
    if (result.error) {
      console.error(result.error);
    }
  }

  return (
    <form action={handleSubmit}>
      <input type="hidden" name="listId" value={listId} />
      <input name="name" placeholder="Task name" required />
      <textarea name="description" placeholder="Description" />
      <SubmitButton />
    </form>
  );
}
```

## 3. RSC + Client Hydration

### When to Use

✅ **Best For:**

* Initial server render with client updates
* Data that changes frequently
* Combining SEO with interactivity
* Background refresh patterns

### Implementation

The server renders initial data and passes it as `initialData` to a TanStack
Query hook. Background refresh is handled by Query's `refetchInterval` — **not**
a `useEffect` + `setInterval` loop. AGENTS.md forbids `useEffect` for data
fetching.

```typescript theme={null}
// app/[locale]/(dashboard)/[wsId]/tasks/page.tsx
import { createClient } from '@tuturuuu/supabase/next/server';
import { TaskListClient } from './TaskListClient';

export default async function TasksPage({
  params,
}: {
  params: Promise<{ wsId: string }>;
}) {
  const { wsId } = await params;
  // Async server client — await it.
  const supabase = await createClient();

  const { data: initialTasks } = await supabase
    .from('workspace_tasks')
    .select('*')
    .eq('ws_id', wsId);

  return <TaskListClient initialTasks={initialTasks || []} wsId={wsId} />;
}
```

```tsx theme={null}
// app/[locale]/(dashboard)/[wsId]/tasks/TaskListClient.tsx
'use client';

import { useQuery } from '@tanstack/react-query';
import { listWorkspaceTasks } from '@tuturuuu/internal-api/tasks';
import type { Database } from '@tuturuuu/types';

type Task = Database['public']['Tables']['workspace_tasks']['Row'];

export function TaskListClient({
  initialTasks,
  wsId,
}: {
  initialTasks: Task[];
  wsId: string;
}) {
  // Server-rendered rows seed the cache via initialData; Query owns refreshes.
  const { data: tasks = initialTasks } = useQuery({
    queryKey: ['workspaces', wsId, 'tasks'],
    queryFn: () => listWorkspaceTasks(wsId),
    initialData: initialTasks,
    staleTime: 30 * 1000,
    // Background refresh without a manual setInterval.
    refetchInterval: 30_000,
  });

  return (
    <div>
      {tasks.map((task) => (
        <div key={task.id}>{task.name}</div>
      ))}
    </div>
  );
}
```

The client hook fetches through an `@tuturuuu/internal-api` helper (which calls
the REST `/api/v1` endpoint) rather than re-running Supabase queries from the
browser. This keeps authorization on the server and gives Query a single,
cacheable fetch boundary.

## 4. TanStack Query (Client-Side)

### When to Use

✅ **Best For:**

* Interactive dashboards
* Rapidly changing data
* Complex client-side state
* Optimistic updates
* Automatic background refetching

❌ **Not For:**

* SEO-critical content
* Initial page load (prefer RSC)

### Implementation with Internal API helpers

Client queries call `@tuturuuu/internal-api` helpers, which hit the REST
`/api/v1/...` endpoints where authorization lives. This is the actual fetch
boundary in `apps/web` — there are no `trpc.tasks.*` / `trpc.boards.*` routers
(tRPC is a [stub](/platform/architecture/trpc)).

```tsx theme={null}
'use client';

import { useQuery } from '@tanstack/react-query';
import { listWorkspaceTasks } from '@tuturuuu/internal-api/tasks';

export function TaskList({ wsId }: { wsId: string }) {
  const {
    data: tasks,
    isPending,
    error,
  } = useQuery({
    queryKey: ['workspaces', wsId, 'tasks'],
    queryFn: () => listWorkspaceTasks(wsId),
    staleTime: 5 * 60 * 1000, // Consider data fresh for 5 minutes
    refetchOnWindowFocus: true,
    refetchInterval: 30_000, // Refetch every 30 seconds
  });

  if (isPending) return <div>Loading...</div>;
  if (error) return <div>Error: {error.message}</div>;

  return (
    <div>
      {tasks?.map((task) => (
        <TaskCard key={task.id} task={task} />
      ))}
    </div>
  );
}
```

### Query Key Conventions

Use stable array query keys:

```typescript theme={null}
// ✅ Good: Specific, cacheable
['tasks', wsId, { listId, completed: false }]

// ❌ Bad: Too generic
['tasks']
```

### Thin Server Gate + Client Query Shell

For dense dashboard surfaces that need URL-driven filtering, pagination, and frequent background refreshes, prefer a **thin server gate** plus a **client query shell**:

1. Keep the route page server-side only for auth, permission checks, redirects, and metadata.
2. Move interactive data loading into client hooks backed by TanStack Query.
3. Back those hooks with workspace-scoped Internal API helpers instead of ad hoc `fetch('/api/...')` calls.
4. Store queryable UI state such as `page`, `pageSize`, `q`, `sortBy`, and `path` in `nuqs`.
5. Invalidate query keys after mutations instead of relying on `router.refresh()`.

This pattern is now the default for file-explorer style dashboard pages such as Drive, where the user expects immediate client-side updates while the server still owns authorization.

### Optimistic Updates

Use `useMutation` with the `queryClient` cache helpers. Drive the mutation
through an `@tuturuuu/internal-api` helper so the write goes through the same
authorized REST boundary as reads.

```tsx theme={null}
'use client';

import { useMutation, useQueryClient } from '@tanstack/react-query';
import { updateWorkspaceTask } from '@tuturuuu/internal-api/tasks';

export function TaskCheckbox({ task, wsId }: { task: Task; wsId: string }) {
  const queryClient = useQueryClient();
  const taskKey = ['workspaces', wsId, 'tasks', task.id];
  const listKey = ['workspaces', wsId, 'tasks'];

  const toggleComplete = useMutation({
    mutationFn: (input: { completed: boolean }) =>
      updateWorkspaceTask(wsId, task.id, input),

    // Optimistically update before the server responds
    onMutate: async (input) => {
      await queryClient.cancelQueries({ queryKey: taskKey });

      const previous = queryClient.getQueryData<Task>(taskKey);

      queryClient.setQueryData<Task>(taskKey, (old) =>
        old ? { ...old, completed: input.completed } : old
      );

      return { previous };
    },

    // Rollback on error
    onError: (_err, _input, context) => {
      if (context?.previous) {
        queryClient.setQueryData(taskKey, context.previous);
      }
    },

    // Refetch after success or error
    onSettled: () => {
      queryClient.invalidateQueries({ queryKey: taskKey });
      queryClient.invalidateQueries({ queryKey: listKey });
    },
  });

  return (
    <input
      type="checkbox"
      checked={task.completed}
      onChange={() => toggleComplete.mutate({ completed: !task.completed })}
    />
  );
}
```

### Cache Invalidation

```typescript theme={null}
const queryClient = useQueryClient();

// Invalidate a specific task
queryClient.invalidateQueries({ queryKey: ['workspaces', wsId, 'tasks', '123'] });

// Invalidate the workspace task list
queryClient.invalidateQueries({ queryKey: ['workspaces', wsId, 'tasks'] });

// Reset a query to its initial state
queryClient.resetQueries({ queryKey: ['workspaces', wsId, 'tasks'] });

// Refetch immediately
queryClient.refetchQueries({ queryKey: ['workspaces', wsId, 'tasks'] });
```

<Note>
  Query keys are prefix-matched by default, so invalidating
  `['workspaces', wsId, 'tasks']` also invalidates every more specific key under
  it (e.g. `['workspaces', wsId, 'tasks', taskId]`). Keep keys ordered
  broad → narrow so partial invalidation stays predictable.
</Note>

## 5. Realtime Subscriptions

### When to Use

✅ **Best For:**

* Collaborative features
* Chat applications
* Live dashboards
* Multiplayer features
* Notification systems

❌ **Not For:**

* Infrequent updates
* Static content
* SEO-critical data

### Implementation

The **initial fetch is a TanStack Query hook** (through an `@tuturuuu/internal-api`
helper), never a `useEffect` fetch. A `useEffect` is used only for the
subscription **lifecycle** (a genuine side effect), and the realtime payloads
mutate the **query cache** so the live data and the cached data stay in sync.

```tsx theme={null}
'use client';

import { useEffect } from 'react';
import { useQuery, useQueryClient } from '@tanstack/react-query';
import { createClient } from '@tuturuuu/supabase/next/client';
import { listWorkspaceTasks } from '@tuturuuu/internal-api/tasks';
import type { Database } from '@tuturuuu/types';

type Task = Database['public']['Tables']['workspace_tasks']['Row'];

export function RealtimeTaskList({ wsId }: { wsId: string }) {
  const queryClient = useQueryClient();
  const queryKey = ['workspaces', wsId, 'tasks'];

  // Initial + cached data comes from Query, not a useEffect fetch.
  const { data: tasks = [] } = useQuery({
    queryKey,
    queryFn: () => listWorkspaceTasks(wsId),
  });

  useEffect(() => {
    const supabase = createClient();

    // Subscription lifecycle is a side effect — payloads update the cache.
    const channel = supabase
      .channel(`workspace-tasks-${wsId}`)
      .on(
        'postgres_changes',
        {
          event: '*',
          schema: 'public',
          table: 'workspace_tasks',
          filter: `ws_id=eq.${wsId}`,
        },
        (payload) => {
          queryClient.setQueryData<Task[]>(queryKey, (prev = []) => {
            if (payload.eventType === 'INSERT') {
              return [...prev, payload.new as Task];
            }
            if (payload.eventType === 'UPDATE') {
              return prev.map((task) =>
                task.id === payload.new.id ? (payload.new as Task) : task
              );
            }
            if (payload.eventType === 'DELETE') {
              return prev.filter((task) => task.id !== payload.old.id);
            }
            return prev;
          });
        }
      )
      .subscribe();

    return () => {
      channel.unsubscribe();
    };
  }, [wsId, queryClient]);

  return (
    <div>
      {tasks.map((task) => (
        <div key={task.id}>{task.name}</div>
      ))}
    </div>
  );
}
```

## TanStack Query Guidelines

The shared `QueryClient` lives in `apps/web/src/trpc/query.ts` (`makeQueryClient`)
and ships a default `staleTime` of 30s plus rate-limit-aware retry handling.
Override per-query options only when a surface needs different freshness.

### Query Configuration

```typescript theme={null}
const { data } = useQuery({
  queryKey: ['workspaces', wsId, 'tasks'],
  queryFn: () => listWorkspaceTasks(wsId),

  // How long data is considered fresh
  staleTime: 5 * 60 * 1000, // 5 minutes

  // Garbage-collection time after the query has no observers.
  // (React Query v5 renamed `cacheTime` to `gcTime`.)
  gcTime: 10 * 60 * 1000, // 10 minutes

  // Refetch on window focus
  refetchOnWindowFocus: true,

  // Refetch on network reconnect
  refetchOnReconnect: true,

  // Background refetch interval
  refetchInterval: false, // or number in ms

  // Retry failed requests
  retry: 3,

  // Only run if condition is true
  enabled: !!wsId,
});
```

### Prefetching

```typescript theme={null}
// In a parent component or on hover
const queryClient = useQueryClient();

await queryClient.prefetchQuery({
  queryKey: ['workspaces', wsId, 'tasks', taskId],
  queryFn: () => getWorkspaceTask(wsId, taskId),
});
```

### Parallel Queries

```typescript theme={null}
'use client';

import { useQuery } from '@tanstack/react-query';
import { listWorkspaceTasks, listWorkspaceTaskBoards } from '@tuturuuu/internal-api/tasks';
import { getWorkspaceMembers } from '@tuturuuu/internal-api/workspaces';

export function Dashboard({ wsId }: { wsId: string }) {
  const tasks = useQuery({
    queryKey: ['workspaces', wsId, 'tasks'],
    queryFn: () => listWorkspaceTasks(wsId),
  });
  const boards = useQuery({
    queryKey: ['workspaces', wsId, 'task-boards'],
    queryFn: () => listWorkspaceTaskBoards(wsId),
  });
  const members = useQuery({
    queryKey: ['workspaces', wsId, 'members'],
    queryFn: () => getWorkspaceMembers(wsId),
  });

  // All three queries run in parallel
  const isPending = tasks.isPending || boards.isPending || members.isPending;

  if (isPending) return <div>Loading...</div>;

  return <div>{/* Render dashboard */}</div>;
}
```

For many dynamic queries, prefer `useQueries` over hand-listing hooks.

### Dependent Queries

```typescript theme={null}
'use client';

import { useQuery } from '@tanstack/react-query';
import { getWorkspaceTask, listWorkspaceTaskAssignees } from '@tuturuuu/internal-api/tasks';

export function TaskDetails({ wsId, taskId }: { wsId: string; taskId: string }) {
  const { data: task } = useQuery({
    queryKey: ['workspaces', wsId, 'tasks', taskId],
    queryFn: () => getWorkspaceTask(wsId, taskId),
  });

  const { data: assignees } = useQuery({
    queryKey: ['workspaces', wsId, 'tasks', taskId, 'assignees'],
    queryFn: () => listWorkspaceTaskAssignees(wsId, taskId),
    enabled: !!task, // Only run after the task is fetched
  });

  return <div>{/* Render task details */}</div>;
}
```

<Note>
  The exact helper names above (`getWorkspaceTask`, `listWorkspaceTaskAssignees`,
  `getWorkspaceMembers`) are illustrative — browse `packages/internal-api/src`
  for the real exports before wiring a hook. `listWorkspaceTasks` and
  `listWorkspaceTaskBoards` exist today.
</Note>

## Decision Matrix

| Use Case                 | Strategy                    | Why                           |
| ------------------------ | --------------------------- | ----------------------------- |
| Blog posts               | RSC                         | SEO, rarely changes           |
| Task list (initial load) | RSC                         | Fast initial render           |
| Create task form         | Server Action               | Mutation, redirect            |
| Dashboard metrics        | TanStack Query              | Frequent updates              |
| Real-time chat           | Realtime Subscription       | Collaboration                 |
| Task toggle              | TanStack Query (optimistic) | Interactive, instant feedback |
| User profile (view)      | RSC                         | Rarely changes                |
| User profile (edit)      | Server Action               | Mutation with validation      |
| Workspace members        | RSC + hydration             | SEO + background refresh      |
| Live notifications       | Realtime Subscription       | Real-time updates critical    |

## Best Practices

### ✅ DO

1. **Start with RSC**
   ```typescript theme={null}
   // Default to server components
   export default async function Page() { ... }
   ```

2. **Use specific query keys**
   ```typescript theme={null}
   ['tasks', wsId, { listId, status: 'active' }]
   ```

3. **Set appropriate staleTime**
   ```typescript theme={null}
   staleTime: 5 * 60 * 1000 // 5 minutes for user profiles
   ```

4. **Implement optimistic updates for better UX**
   ```typescript theme={null}
   onMutate: async (newData) => { /* optimistic update */ }
   ```

5. **Invalidate narrowly**
   ```typescript theme={null}
   // Target the specific task, not the whole workspace tasks tree
   queryClient.invalidateQueries({
     queryKey: ['workspaces', wsId, 'tasks', taskId],
   });
   ```

6. **Fetch through Internal API helpers**
   ```typescript theme={null}
   // Route client reads/writes through @tuturuuu/internal-api, not raw
   // fetch('/api/...') or trpc.* routers.
   queryFn: () => listWorkspaceTasks(wsId);
   ```

### ❌ DON'T

1. **Don't use client fetching for SEO content**
   ```typescript theme={null}
   // ❌ Bad: Client-side fetch for blog
   useEffect(() => fetchBlogPosts(), []);
   ```

2. **Don't skip staleTime**
   ```typescript theme={null}
   // ❌ Bad: Refetches too often
   useQuery({ ... }) // defaults to 0ms staleTime
   ```

3. **Don't invalidate globally**
   ```typescript theme={null}
   // ❌ Bad: Refetches everything
   queryClient.invalidateQueries();
   ```

4. **Don't use Realtime for infrequent updates**
   ```typescript theme={null}
   // ❌ Bad: Waste of resources
   supabase.channel('user-profiles-changes')
   ```

## Related Documentation

* [tRPC Implementation](/platform/architecture/trpc) — the minimal `healthCheck`
  stub kept alive during the migration (not a product fetch path)
* [TanStack + Rust Migration](/platform/architecture/tanstack-rust-migration)
* [Supabase Client](/reference/packages/supabase)
* [Server Components](https://nextjs.org/docs/app/building-your-application/rendering/server-components)
* [TanStack Query](https://tanstack.com/query/latest)


# Effect Orchestration
Source: https://docs.tuturuuu.com/platform/architecture/effect

How Tuturuuu uses Effect for server and service workflows

# Effect Orchestration

Tuturuuu uses [Effect](https://effect.website/docs/quickstart) as the default
tool for new or substantially edited TypeScript server/service orchestration
when it adds concrete value: typed expected errors, explicit dependencies,
retry/scheduling policy, resource boundaries, or controlled concurrency.

Import Effect through the platform entrypoint:

```ts theme={null}
import {
  Effect,
  Layer,
  runEffectAsResult,
  TuturuuuEffectError,
} from '@tuturuuu/utils/effect';
```

Do not import directly from `effect` in app or package code unless the curated
entrypoint is missing a module that the code genuinely needs. Add that module to
`@tuturuuu/utils/effect` first when it should become a platform pattern.

## Where Effect Fits

Use Effect for:

* Server-side workflows that coordinate several async operations.
* Expected failures that should stay typed until the route/action boundary.
* Service dependencies that need live, test, or mock implementations.
* Retry, timeout, scheduling, queue, stream, or concurrency policy.
* Shared packages that expose additive orchestration subpaths such as
  `@tuturuuu/ai/effect` or `@tuturuuu/trigger/effect`.

Avoid Effect for:

* React UI state and component-local event handlers.
* TanStack Query client fetching and mutation wrappers.
* Zod validation and generated database type contracts.
* Simple pure helpers, formatting utilities, and one-line transforms.
* Existing stable call sites where a rewrite adds churn without improving an
  error boundary or dependency boundary.

## Boundary Pattern

Keep route handlers and client helpers familiar. Build the richer orchestration
inside shared server modules, then convert to existing result shapes at the
boundary.

```ts theme={null}
import {
  Effect,
  fromDataError,
  runEffectAsResult,
} from '@tuturuuu/utils/effect';

const loadWorkspace = (query: () => Promise<{
  data: { id: string } | null;
  error: unknown;
}>) =>
  fromDataError(query, {
    code: 'WORKSPACE_READ_FAILED',
    message: 'Workspace read failed.',
  });

export async function loadWorkspaceResult(query: Parameters<typeof loadWorkspace>[0]) {
  return runEffectAsResult(
    Effect.map(loadWorkspace(query), (workspace) => ({ workspace }))
  );
}
```

API routes should still return sanitized public errors. Use
`serializeTuturuuuEffectError` or `runEffectAsResult` to cross the route/action
boundary, and log only sanitized server-side context through the existing
logging path.

## Reliability Policy

Use the Tuturuuu helpers for common server/service reliability controls before
dropping to raw Effect operators. They keep retry, timeout, and concurrency
defaults consistent across packages while still returning typed expected errors.

```ts theme={null}
import {
  Effect,
  forEachConcurrently,
  fromPromise,
  withTuturuuuRetry,
  withTuturuuuTimeout,
} from '@tuturuuu/utils/effect';

const request = fromPromise((signal) => fetch(url, { signal }), {
  code: 'UPSTREAM_REQUEST_FAILED',
  message: 'Upstream request failed.',
});

const resilientRequest = withTuturuuuRetry(
  withTuturuuuTimeout(request, {
    code: 'UPSTREAM_REQUEST_TIMEOUT',
    duration: '10 seconds',
    message: 'Upstream request timed out.',
  }),
  { times: 2, delay: '250 millis' }
);

const hydrateRows = (rows: readonly { id: string }[]) =>
  forEachConcurrently(
    rows,
    (row) => Effect.map(resilientRequest, (response) => ({ row, response })),
    { concurrency: 4 }
  );
```

Retries should be reserved for transient failures such as network errors,
timeouts, `408`, `425`, `429`, and `5xx` responses. Do not retry validation
errors, authorization failures, tenant-binding failures, or non-idempotent
mutations unless the owning service has explicit idempotency protection.

## Services And Layers

For dependencies that need replacement in tests, define a service tag and a live
layer near the owning package:

```ts theme={null}
import { Context, Effect, Layer } from '@tuturuuu/utils/effect';

interface BillingServiceShape {
  readonly charge: (amount: number) => Promise<{ ok: true }>;
}

class BillingService extends Context.Tag('BillingService')<
  BillingService,
  BillingServiceShape
>() {}

export const BillingLive = Layer.succeed(BillingService, {
  charge: async (amount) => ({ ok: true }),
});

export const chargeEffect = (amount: number) =>
  Effect.gen(function* () {
    const billing = yield* BillingService;
    return yield* Effect.promise(() => billing.charge(amount));
  });
```

Prefer package-specific entrypoints such as `@tuturuuu/ai/effect` when the
service belongs to a domain package. Keep the root `@tuturuuu/utils/effect`
entrypoint for shared primitives and small platform helpers.

## App Integration

* Server Components may call Effect programs from server-only helpers and then
  render plain data.
* Server Actions may return existing action result shapes after
  `runEffectAsResult`.
* API routes may use Effect for orchestration but must keep existing auth,
  tenant binding, Zod parsing, and sanitized response rules.
* Client components should consume normal props, TanStack Query hooks, or
  `packages/internal-api` helpers. Do not push Effect requirements into React
  component trees.

## Verification

When adding an Effect workflow:

1. Test the Effect program with a provided service/layer or a fake service.
2. Test the boundary conversion with `runEffectAsResult`.
3. Run the owning package test and type-check commands.
4. Finish with `bun check` when TypeScript, JavaScript, package metadata, docs,
   or repo guidance changed.


# Routing
Source: https://docs.tuturuuu.com/platform/architecture/routing

How apps/web resolves locale, workspace identity, and canonical dashboard URLs

`apps/web` routing has two jobs:

* map browser-friendly URLs onto the App Router file structure
* canonicalize workspace identity before pages and APIs touch the database

For the complete permission model that sits on top of this routing layer, see `platform/architecture/workspaces-permissions`.

The TanStack migration keeps a route ownership manifest for this route tree.
Use `platform/architecture/tanstack-rust-migration` before moving any
`apps/web/src/app` route to `apps/tanstack-web` or `apps/backend`.

## File Structure Versus Browser URLs

The dashboard uses the App Router structure:

```text theme={null}
apps/web/src/app/[locale]/(dashboard)/[wsId]/...
```

Users do not need to think about the internal route groups. What they see in the browser is effectively:

```text theme={null}
/{workspace-segment}/...
```

where `workspace-segment` is one of:

* a workspace UUID
* `personal`
* `internal`

## Proxy Responsibilities

`apps/web/src/proxy.ts` is the routing coordinator at the edge.

It is responsible for:

* locale negotiation
* auth-cookie propagation during redirects
* onboarding and root-path redirect behavior
* canonical workspace slug redirects
* workspace-aware request preprocessing before the App Router handles the page

## Workspace Slug Canonicalization

Two workspace IDs are intentionally rewritten into stable slugs:

* the current user's personal workspace UUID -> `personal`
* `ROOT_WORKSPACE_ID` -> `internal`

That means the proxy may receive a UUID but still redirect the browser onto a slugged URL for consistency.

### Why this matters

* links are shorter and more stable
* users do not need to memorize internal UUIDs for personal/internal workspaces
* page code can still resolve those slugs back to real UUIDs with shared helpers

## Default Workspace Redirect

When an authenticated user hits `/`, the proxy uses `getUserDefaultWorkspace()` to find the best landing workspace.

Resolution order:

1. `user_private_details.default_workspace_id`, if it still exists and the user is a member
2. the user's personal workspace

The redirect target becomes:

* `personal` for a personal workspace
* `internal` for the root workspace
* the UUID for a normal workspace

## Page-Level Workspace Resolution

Server pages should not parse workspace slugs manually.

Use `WorkspaceWrapper`, which calls `getWorkspace()` and gives the page:

* `workspace`
* canonical UUID `wsId`
* `isPersonal`
* `isRoot`

If the lookup fails, the wrapper calls `notFound()`.

This makes page code simpler because the page receives the normalized UUID even when the URL used `personal` or `internal`.

## API-Level Workspace Resolution

Route handlers should use `normalizeWorkspaceId()`.

That helper:

* accepts the raw route segment
* converts `personal` into the authenticated user's personal workspace UUID
* converts `internal` into `ROOT_WORKSPACE_ID`
* preserves request-scoped auth when passed a request-derived Supabase client

The common rule is:

* URLs may use slugs
* database reads and writes should use canonical UUID workspace IDs

## Routing And Authorization Are Separate Layers

Routing tells the app **which** workspace the request targets.

Authorization tells the app **whether** the current actor may view or mutate something inside that workspace.

That separation is deliberate:

* `WorkspaceWrapper` / `getWorkspace()` handle membership and identity resolution for pages
* `normalizeWorkspaceId()` handles route-param normalization for APIs
* `getPermissions()` handles feature-level access control

Do not collapse those responsibilities into one helper or assume a normalized workspace ID automatically means the caller has feature permissions.


# Satellite Apps
Source: https://docs.tuturuuu.com/platform/architecture/satellite-apps

How satellite apps (contacts, forms, pay, tasks, …) authenticate, proxy their APIs, render under Cache Components, and take ownership of a feature from apps/web.

## What a satellite is

`apps/web` is the central platform app. A **satellite** is a separate Next app on
its own subdomain that owns one slice of the product and shares the session with
web through cross-app auth.

`apps/contacts` (`contacts.tuturuuu.com`, port `7827`) is the largest example: it
owns the entire `workspace_users` CRM surface (`/[wsId]/users/*` plus
`workforce`). `apps/web` no longer has a users section at all.

Shared logic lives in packages so both apps run one implementation:

| Package                           | Contents                                                                                        |
| --------------------------------- | ----------------------------------------------------------------------------------------------- |
| `@tuturuuu/users-core`            | Server logic: route handlers, user-group server data, activity normalization, report/post types |
| `@tuturuuu/users-ui`              | Client logic: hooks and components (approvals view, attendance client, score display, …)        |
| `@tuturuuu/ui`, `@tuturuuu/utils` | Genuinely generic pieces (statistic cards, workspace-user link, calendar settings)              |

### Two shapes of ownership

Contacts kept shared logic in packages because `apps/web` still needed some of
it. `apps/forms` (`forms.tuturuuu.com`, port `7828`) is the other shape: a
**clean hard move**. The forms product had no consumers outside itself, so the
feature moved wholesale with no extracted package, and `apps/web` retained
nothing but redirects.

Forms also owns **every API route it needs** — `/api/v1/workspaces/[wsId]/forms/*`
and the public `/api/v1/shared/forms/*` — instead of proxying them to web. Two
things forced that and are worth copying:

* Forms tables live in the Postgres **`private` schema**
  (`getPrivateFormsClient(supabase) => supabase.schema('private')`), so every
  read needs the admin client. An anon/RLS client cannot reach them at all, which
  means proxying to web buys nothing.
* The public form-filling surface at `/f/<shareCode>` is served to **anonymous
  respondents**. See the public-API note under API proxying below.

Legacy public links (`tuturuuu.com/<locale>/shared/forms/<shareCode>`) get a
permanent **308** from web's proxy, issued before the auth proxy runs so
respondents and social crawlers are never bounced to `/login`.

`apps/infrastructure` follows the same hard-ownership rule for internal platform
operations. Infrastructure-only routes such as AI-credit administration,
translation tooling, and holiday administration live in that app. Shared route
shapes that its UI needs, including the root-admin workspace list and workspace
secret management, also have local Infrastructure handlers protected by the
Infrastructure app session and root-workspace membership. Do not add a new
Infrastructure UI call that depends on an `apps/web` fallback rewrite.

## Cache Components: `connection()`, not `dynamic`

<Warning>
  Every Next app runs with `cacheComponents` (PPR) enabled.
  `export const dynamic` and `export const revalidate` are **rejected at build
  time** — `await connection()` is the only way to opt into request-time rendering.
</Warning>

This matters more than it looks. Supabase-js issues `fetch()` under the hood, so
**every server-component query is a fetch**. A page with no dynamic signal gets
prerendered — and the prerender runs with **no cookies**:

```text theme={null}
Workspace not found: personal
[WorkspaceHelper] Failed to fetch workspace
Error: During prerendering, fetch() rejects when the prerender is complete
```

That is a real production failure mode (it broke `contacts/users/database`).

**Rules**

* Add `await connection()` as the first statement of any authed page or layout
  that touches Supabase, `getPermissions`, `getWorkspace`, or the app session.
  A dynamic *layout* does **not** make its child pages dynamic — each page needs
  its own call.
* `cacheComponents` also prerenders **GET route handlers**. A Supabase-backed GET
  route with no dynamic signal is statically generated and its response is baked
  in at build time. Add `await connection()` there too; every API route should
  report `ƒ (Dynamic)` in the build output.
* Where it fits, prefer the true PPR shape: a static shell with the dynamic part
  inside `<Suspense>` and `await connection()` **inside** the suspended
  component. `apps/meet/[planId]` is the reference.
* Unit tests call pages and handlers outside a request scope, where
  `connection()` throws. Stub it in the app's vitest setup while keeping every
  other export:

```ts theme={null}
vi.mock('next/server', async (importOriginal) => ({
  ...(await importOriginal<typeof import('next/server')>()),
  connection: vi.fn().mockResolvedValue(undefined),
}));
```

<Note>
  `bun check` does not compile Next apps, so it cannot see any of this. Always run
  the app's real `bun run build` when you change its routes, pages, or deps.
</Note>

## Auth: resolve the actor from the app session

A registered satellite must resolve the acting user from Tuturuuu app-session
auth — never from `@tuturuuu/utils/user-helper`, whose `getCurrentUser` /
`getCurrentWorkspaceUser` read Supabase auth directly. The `internal-app-auth`
guard in `bun check` enforces this.

When a shared helper needs the actor, give it an **injectable** `userId` instead
of letting it resolve one:

```ts theme={null}
// satellite page
const actor = await getSatelliteAppSessionUser('contacts');
const user = actor?.id
  ? await getWorkspaceUserLinkForUser(wsId, actor.id)
  : null;
```

`getCurrentWorkspaceUser` (web) now delegates to that same
`@tuturuuu/utils/workspace-user-link` helper, so there is one implementation and
web behavior is unchanged.

Workspace-user link repair must not require an optional platform display name.
New auth users initially have only a `public.users.id`; the repair RPC derives a
workspace profile name from display name, private full name, handle, email, and
finally a stable generic fallback. Membership remains mandatory, and the repair
does not create or broaden workspace access.

### Personal workspace aliases in APIs

API routes that accept `personal` must preserve the same authenticated actor
while resolving that alias. Use the actor-explicit helpers from
`@tuturuuu/satellite/workspace-access`: they verify the intended target app
before resolving `personal`, UUID, handle, or internal workspace identifiers,
and fall back to the request-scoped Supabase session only when no app-session
token is present. An invalid, expired, or mismatched app-session token must not
fall through to another identity. Passing only a cookie-backed client on a
satellite loses the app-session identity and incorrectly reports `User not
authenticated`.

Route handlers must keep both values returned by the auth context: use the
explicit `user` for `getPermissions({ user, wsId })`, and the returned admin
client for workspace-scoped data operations. A `request` property is not an
actor for a satellite app session.

An admin-backed app-session client has no `auth.uid()`. Therefore a satellite
must not call a public RPC wrapper whose authorization derives from
`auth.uid()`. Call the private actor-aware RPC and pass the verified user ID in
its actor argument while preserving the route response shape.

### The actorless-call trap

<Warning>
  `getWorkspace(id)` and `getPermissions({ wsId })` called **without** an actor fall
  back to a cookie-backed Supabase client. In a satellite that client is
  **anonymous** — the session is an app-session JWT, not a Supabase auth cookie.
</Warning>

The lookup then returns `null`, the page 404s, and — because the render aborts
with Supabase fetches still in flight — those fetches outlive it and surface as:

```text theme={null}
Workspace not found: personal
Error: During prerendering, fetch() rejects when the prerender is complete
digest: 'HANGING_PROMISE_REJECTION'
```

The second error is a *symptom*, not the cause. Chasing the "hanging fetch" leads
nowhere — there is no stray `setTimeout`/`after()` anywhere in the tree. The cause
is the missing actor.

This is also why **a satellite must not use the shared
`@tuturuuu/ui/custom/workspace-wrapper`**: it calls bare `getWorkspace(wsId)`
internally, so every page rendering it inherits the bug. That took down the whole
`apps/contacts` users surface (20 pages) in production.

Give each satellite a `src/lib/workspace.ts` that resolves the actor once and
threads it through, plus an app-local wrapper that uses it:

```ts theme={null}
export async function getContactsWorkspace(id: string) {
  const user = await getSatelliteAppSessionUser('contacts');
  if (!user?.id) return null;
  return getWorkspace(id, { useAdmin: true, user });
}

export async function getContactsWorkspacePermissions(wsId: string) {
  const user = await getSatelliteAppSessionUser('contacts');
  if (!user?.id) return null;
  return getPermissions({ user, wsId });
}
```

`scripts/check-internal-app-auth.js` enforces both halves (no shared wrapper, no
actorless workspace, permission, or alias-normalization call) across every
registered satellite. Compatibility fallback is centralized in audited auth
wrappers and the shared workspace-access helper; individual routes are not
allowlisted.

### One actor for the workspace shell

The workspace layout is the authentication boundary. Pass its verified user ID
into `NavbarActions` and render notifications from that same identity in
expanded, collapsed, and mobile navigation. Do not independently re-resolve
authentication for the notification bell: two resolvers can disagree and hide
the bell while the rest of the layout remains authenticated.

### Reserved route placeholders

Selection sentinels such as Contacts group ID `~` are navigation state, not
database identifiers. Parallel routes can begin rendering child pages before a
parent selection gateway replaces them, so app-local workspace wrappers must
stop those child loaders before any UUID filter runs. The parent gateway remains
responsible for group selection and selected-group navigation.

## API proxying — and the catch-all trap

A satellite's `next.config.ts` has a **fallback** rewrite sending any unmatched
`/api/:path*` to web. That is how contacts reaches endpoints it does not own.

<Warning>
  Never add a catch-all page (`[...slug]`) under `[locale]/[wsId]` in a satellite
  that proxies `/api/*`.
</Warning>

### The proxied web route must accept app sessions

<Warning>
  A web route that satellites proxy has to opt into app-session actors.
  `createClient(request)` deliberately returns an **unauthenticated** client as soon
  as the forwarded request carries the host-only `tuturuuu_app_session` cookie, so
  `resolveAuthenticatedSessionUser` / `getPermissions({ request })` find no user and
  the route answers `401 Unauthorized` — from every satellite, while the identical
  code keeps working on `tuturuuu.com`.
</Warning>

Opt in explicitly, then authorize on workspace permissions (the calling app grants
nothing by itself):

```ts theme={null}
// Workspace routes
const access = await resolveWorkspaceRouteAccess(req, wsId, [
  'manage_workspace_members',
]);
if (!access.ok) return access.response;

// Or, for withSessionAuth routes
export const GET = withSessionAuth(handler, {
  allowAppSessionAuth: CURRENT_USER_APP_SESSION_AUTH,
});
```

The tell-tale symptom is **one action failing inside an otherwise-working panel**.
Workspace member invites returned "Unauthorized" from Inventory and every other
satellite while the member list, roles, and invite links worked, because those
routes had been migrated and `members/invite` had not. A narrow allowlist behaves
the same way for the apps it omits: `{ targetApp: 'teach' }` on the user-group
storage route 401'd every Contacts request for group files. When you fix one route,
sweep the rest of its surface:

```bash theme={null}
grep -rL "resolveWorkspaceRouteAccess\|allowAppSessionAuth" \
  "apps/web/src/app/api/workspaces/[wsId]/members"
```

### Public (anonymous) API routes on a satellite

<Warning>
  The standard satellite `proxy.ts` `/api` branch calls
  `refreshAppSessionForRequest`, which returns `ok: false` when a request carries
  no session credentials at all — and the branch turns that into a **401**. Any
  genuinely public endpoint must be excluded, or it is unreachable for the
  anonymous users it exists to serve.
</Warning>

`apps/storefront` and `apps/forms` both do this: match the public paths, and skip
the app-session refresh unless the caller happens to be signed in.

```ts theme={null}
const isPublicSharedFormApi = isPublicSharedFormApiRequest(request);
const shouldRefreshAppSession =
  !isLocalAuthApi &&
  (!isPublicSharedFormApi || hasApiSessionCredentials(request));
```

Abuse protection for those routes is Turnstile plus rate limiting inside the
handler, not the app session. Note the same trap applies to *page* auth: forms
treats `/f/<shareCode>` as a public path so anonymous respondents are not
redirected to `/login`.

Related: a signed-in user on a satellite has an app-session JWT, **not** a
Supabase cookie. Code that asks `supabase.auth.getUser()` to decide "is this
person signed in" silently answers *no* for everyone. Forms' response-copy
email flow hit exactly this and had to read the actor from the app session.

Next checks `fallback` rewrites **only after dynamic routes**. So
`[locale]/[wsId]/[...catchAll]` happily matches
`/api/v1/workspaces/personal/settings` as `locale="api"`, `wsId="v1"` — shadowing
the proxy. The `[wsId]` layout then calls `getWorkspace('v1')` and every proxied
API call 404s:

```text theme={null}
[WorkspaceHelper] Failed to fetch workspace: { workspaceId: 'v1', … }
```

Put non-migrated-route redirects in the app's `proxy.ts` middleware instead. It
handles `/api` in an earlier branch, so it structurally cannot shadow the proxy.
Contacts lists what it owns in `CONTACTS_OWNED_ROUTE_PREFIXES`; anything else
under `/[wsId]` redirects to web with path and query preserved.

<Note>
  Add an entry to that list whenever you migrate a module, or the middleware will
  bounce the freshly-migrated route straight back to web. Mind prefix-vs-exact
  matching: a bare `users` entry that prefix-matches makes every `/users/*` path
  look owned, so non-migrated routes 404 instead of redirecting.
</Note>

## Translations

A satellite that renders broad shared UI must be in the **checked** `APPS` list
in `scripts/i18n-namespace-check.js`, not `UNCHECKED_APPS`.

Scanning only the app's own source cannot see namespaces used *inside*
`@tuturuuu/ui` or `@tuturuuu/satellite`. Miss one and it surfaces as a runtime
`MISSING_MESSAGE` in production rather than a CI failure — which is exactly how
contacts shipped without the `notifications` namespace.

<Warning>
  Having the namespace is not enough — the namespace can be **half-empty**.
</Warning>

The shell components (`user-nav-client`, `sidebar-structure-header`,
`workspace-select`, `settings-dialog-shell`) read their strings through a **bare**
`useTranslations()` and then call `t('common.dashboard')`. A bare translator
carries no namespace argument, so the key-level scan cannot attribute those keys
to a namespace: it only requires them from apps listed in
`BARE_ROOT_KEY_APP_SCOPES`. Since `common` was scoped to nobody, the keys were
required of **no app at all**.

Contacts therefore passed the namespace check (it *had* `common`) while missing
850+ keys inside it, and shipped `MISSING_MESSAGE: common.dashboard`,
`common.logout`, `nav-upgrade-dialog.*`, and `settings.back_to_app` to production.

An app that renders the full dashboard shell belongs in
`BARE_ROOT_KEY_FULL_SCOPE_APPS`, which requires every bare root-qualified key the
shared packages can request. Use `keyExceptions` to opt out of product surfaces
the app does not render.

For narrower shared surfaces, register the owning apps in the matching scoped
consumer set. The workspace members-and-roles panel uses
`SATELLITE_WORKSPACE_SETTINGS_APPS`, so `bun i18n:namespace-check` requires its
`ws-members.*` and `ws-roles.*` keys from every satellite that mounts that
panel. The source scanner also follows typed shared helpers such as
`t: (key: string) => string`; otherwise helper-owned labels can evade a normal
`useTranslations()` scan and render their key paths in production. Keep
conditional product-only branches covered with an explicit key exception
rather than weakening the whole consumer scope.

## Moving a feature from web to a satellite

Resolve every import to an **absolute path** before moving anything. A
`from '@/'` grep is not sufficient; each of these traps cost a broken build or a
failing test:

* **Relative-sibling** imports (`../../x`) — invisible to a `@/` grep.
* **Dynamic** imports — `await import('@/…')` has no `from` clause.
* **Side-effect** imports — `import '@/lib/dayjs-setup'` has no `from` clause.
* **npm deps of the extracted file** must be added to the *target package*.
* **`vi.mock` paths** silently break: a test mocking `@/lib/x` stops intercepting
  once the extracted module imports the package copy directly, so the real module
  runs unmocked.

Then classify each external dependency:

<Steps>
  <Step title="Already a re-export shim">
    Rewrite the import straight to the package it re-exports.
  </Step>

  <Step title="Used only by the moving module">
    Move it along. A satellite maps `@/` to its own `src`, so the specifier often
    needs no change at all.
  </Step>

  <Step title="Still used by the origin app">
    Extract it to `@tuturuuu/users-core` (server) or `@tuturuuu/users-ui`
    (client) and point both apps at it. Keep a re-export shim in the origin app
    when many files import it; repoint directly when only a few do.
  </Step>

  <Step title="Mutually coupled modules">
    Move them **together**. Preserving their relative layout keeps every
    cross-import valid with no rewrites at all.
  </Step>
</Steps>

Finish with: `connection()` on data pages, the owned-routes list, removing the
origin app's nav entry, an i18n backfill, the TanStack page-override + manifest +
doc counts, then `bun check` **and** a real `next build`.

<Note>
  Deleting pages from `apps/web` leaves `apps/web/.next/types/validator.ts` stale,
  so type-check fails on paths that no longer exist. `rm -rf apps/web/.next`.
</Note>

## Debugging a satellite in production

The Vercel CLI is the fastest path to a root cause:

```bash theme={null}
bun add -g vercel
vercel ls contacts --scope tuturuuu
vercel logs <deployment-url> --scope tuturuuu --json
```

Both contacts incidents above were diagnosed straight from those logs — the
`workspaceId: 'v1'` in a `WorkspaceHelper` error is what exposed the catch-all
shadowing the API proxy.


# SePay Integration
Source: https://docs.tuturuuu.com/platform/architecture/sepay-integration

Architecture and implementation notes for the SePay finance integration.

## Goal

The SePay integration connects a workspace to SePay through OAuth, provisions
webhooks without manual SePay UI setup, ingests transaction events, and writes
normalized finance records into the platform.

## Flow

1. A workspace admin starts the OAuth flow.
2. The platform stores an opaque state token in a short-lived HttpOnly cookie.
3. The OAuth callback exchanges the code, encrypts the SePay tokens, stores
   them in `sepay_connections`, and redirects the browser back to the workspace
   integrations surface with a compact success or error query flag.
4. The platform syncs SePay bank accounts into `sepay_wallet_links`.
5. The platform provisions a SePay webhook endpoint and stores the hashed token
   in `sepay_webhook_endpoints`.
6. SePay sends transaction webhooks to `/api/v1/webhooks/sepay/[token]`.
7. The webhook route validates auth, resolves the workspace and wallet,
   deduplicates/retries safely through `sepay_webhook_events`, classifies the
   transaction, and inserts `wallet_transactions`.

## Data Model

### `sepay_connections`

Stores the workspace-level OAuth connection, encrypted access and refresh
tokens, scopes, expiry, and connection status.

### `sepay_wallet_links`

Maps SePay bank-account metadata to workspace wallets so webhook deliveries can
resolve to the correct wallet without manual per-event routing.

### `sepay_webhook_endpoints`

Stores the hashed endpoint token, optional linked wallet, SePay webhook id, and
active/rotation state for workspace webhook routing. The endpoint `ws_id` is
treated as immutable after insert so existing event rows cannot drift across
workspaces through later admin-backed updates.

### `sepay_webhook_events`

Stores the raw webhook payload, dedupe keys, processing status, failure reason,
and the created `wallet_transactions.id` when processing succeeds.

## Processing Rules

* Incoming `transferAmount` values are normalized to a positive magnitude.
* Direction is derived from `transferType`, not from the sign of
  `transferAmount`.
* `transferType: "in"` is written as a positive wallet transaction amount.
* `transferType: "out"` is written as a negative wallet transaction amount.
* Webhook retries must atomically claim `failed` events by `id`, `ws_id`,
  `status`, and empty `created_transaction_id` before creating a wallet
  transaction. A competing retry that loses the claim is treated as a duplicate.
* `received` events become retriable once they are older than the stale-event
  TTL and still do not have a `created_transaction_id`; stale retries must use
  the same atomic claim with a stale `received_at` predicate.
* `processed` and `duplicate` rows are treated as non-replayable duplicates.
* Auto-classification failures must not block ingestion; the route falls back to
  an uncategorized category.
* SePay AI enrichers reserve fixed workspace-scoped AI credits before each
  classifier/tagger model call and release the reservation on failure, so
  webhook retries do not leak credits or block on long model latency.

## Operational Notes

* Required runtime env vars are documented in
  [Secrets & Configuration](/build/devops/secrets-and-configuration).
* The end-to-end validation flow lives in
  [SePay Testing Guide](/build/devops/sepay-testing-guide).
* OAuth callback state is a short-lived HMAC-signed payload bound to the
  workspace id and stored in a callback-scoped HttpOnly cookie. The callback
  must require the cookie value and query `state` to match before validating the
  signature, expiry, and workspace.
* SePay account sync follows cursor pagination and retries `429` responses using
  SePay's `x-sepay-userapi-retry-after` header, but request-path retry sleeps
  are capped at 2 seconds each so sync and webhook-provisioning handlers do not
  stay open for provider-supplied long delays.
* Webhook provisioning only accepts numeric SePay bank-account ids
  (`bank_account_id` or numeric `id`) and best-effort deletes the remote webhook
  if local persistence of the resulting webhook id fails.
* Fallback uncategorized transaction categories are created through a
  workspace/name/direction advisory-lock RPC so concurrent webhook workers reuse
  one canonical fallback category id.
* Eventless webhook dedupe uses a short `received_at` window for proactive
  duplicate detection, but the post-insert unique-key recovery path can still
  reopen the older canonical row when SePay retries the same event later.


# Core Architectural Decisions
Source: https://docs.tuturuuu.com/platform/architecture/system-design/architectural-decisions

Deep dive into the four fundamental architectural choices that define Tuturuuu's system design

This document explains four foundational architectural decisions that inform Tuturuuu's system design. Each section explores the **rationale**, **detailed justification**, and the **alternatives considered**.

<Warning>
  **Conceptual vs. implemented.** This page teaches the reasoning behind several
  classic patterns (microservices, event-driven, hexagonal, modular monolith).
  Tuturuuu adopts some of these in pragmatic, partial form and deliberately does
  **not** adopt others. Each "In Tuturuuu" callout below states what is actually
  true of the codebase today; clearly labelled examples are illustrative and may
  not map to a real file path. Trust the code over any architectural prose.
</Warning>

<Info>
  **Active migration.** The legacy `apps/web` Next.js runtime (port `7803`) is
  being replaced by `apps/tanstack-web` (TanStack Start) plus `apps/backend` (a
  Rust API runtime on port `7820`). The "React Modular Monolith" and
  "tRPC API Gateway" framing on this page describes the legacy `apps/web` stack
  that is being superseded. See
  [TanStack Start And Rust Migration](/platform/architecture/tanstack-rust-migration)
  for the migration contract.
</Info>

## 1. Decomposition Into Independently Deployable Apps

Tuturuuu is organized as a Turborepo monorepo containing many independently
deployable applications under `apps/*` plus shared `packages/*`. This is **not**
a textbook distributed-microservices system with per-service data stores and an
inter-service event bus; rather, each app is a conventional deployment unit, and
the apps share one Supabase project for auth and data. The microservices
*reasoning* below explains why we split along app boundaries, with each "In
Tuturuuu" callout grounded in what is actually true today.

### Core Rationale

To support long-term growth by enabling organizational scaling, independent deployment, and technological flexibility.

### Detailed Justification

#### Organizational Scaling and Team Autonomy

A monolithic architecture forces all developers to work on a single, large codebase, leading to high coordination overhead, merge conflicts, and slower development cycles as the team grows.

The microservices approach aligns with **Conway's Law**, allowing us to structure autonomous teams around specific business capabilities (e.g., an "Identity Team," a "Payments Team"). Each team can develop, test, and deploy their services independently, drastically increasing agility.

**In Tuturuuu:** the repo splits responsibility along app boundaries under
`apps/*`:

* `apps/web` (legacy main platform) and `apps/tanstack-web` (its replacement)
* AI surfaces such as `apps/rewise` (chatbot) and `apps/nova` (prompt engineering)
* Productivity surfaces such as `apps/calendar`, `apps/tasks`, and `apps/meet`
* `apps/finance` for finance workflows
* `apps/backend` (Rust API runtime) plus `apps/database` (Supabase migrations) and shared `packages/*`

These are deployment and ownership boundaries within a single monorepo, not
fully isolated services with private databases.

#### Independent Scalability

In a monolith, if one feature (e.g., a real-time data processing endpoint) experiences high load, the entire application must be scaled. This is inefficient and costly.

Separate deployment units allow for **granular scaling**. A high-load app can be
scaled independently of a low-traffic one, optimizing resource utilization
instead of scaling one monolith as a whole.

**Illustrative only (not a real config in the repo):**

```jsonc theme={null}
// Conceptual per-app scaling targets. Each Tuturuuu app deploys independently,
// so it can scale on its own rather than as part of one bundle.
{
  "web": { "min": 2, "max": 100 },   // Main app needs high availability
  "rewise": { "min": 1, "max": 20 }, // AI chat can scale separately
  "finance": { "min": 1, "max": 10 } // Finance moderate scaling
}
```

#### Fault Isolation and Resilience

A critical bug or memory leak in a non-essential module of a monolith can bring down the entire application.

In a microservices architecture, a failure is **contained within the boundary of that service**. A crash in the `ReportingService` will not affect critical user-facing services like `AuthenticationService` or `OrderService`, leading to a much more resilient and available system.

**In Tuturuuu:**

* Because apps deploy independently, a failure in one app's deployment does not take the others down with it
* Supabase Auth runs as a managed service, so authentication stays available even if an individual app deployment fails
* Background jobs (Trigger.dev) run out-of-band and fail independently from user-facing requests

Note that the apps share one Supabase project, so database-level failures are a
shared dependency, not fully isolated per app.

#### Technology Flexibility (Polyglot Architecture)

Microservices communicate over standard protocols (like events or APIs). This allows each service to be built with the technology best suited for its purpose.

While most apps use **TypeScript and Next.js/React**, the new `apps/backend`
runtime is written in **Rust** for the performance-critical API tier, and a
future machine-learning service could be written in **Python**. This flexibility
is hard to achieve in a single-language monolith and keeps the system adaptable.

**Current polyglot examples in Tuturuuu:**

* Most apps: TypeScript + Next.js + React (`apps/web`) and TanStack Start + React (`apps/tanstack-web`)
* `apps/backend`: Rust (dedicated API runtime, port `7820`; see [TanStack Start And Rust Migration](/platform/architecture/tanstack-rust-migration))
* `apps/discord`: Python (Discord bot utilities)
* Database: PostgreSQL (via Supabase)
* Background jobs: TypeScript on Trigger.dev v4 (`packages/trigger`)
* Possible future: Python ML services

### Why Not a Monolith?

While a monolith offers simplicity at the start of a project, it becomes a significant impediment to growth:

| Monolith Limitation            | Impact                                     | Microservices Solution                  |
| ------------------------------ | ------------------------------------------ | --------------------------------------- |
| **Tight Coupling**             | Changes ripple across the entire codebase  | Service boundaries isolate changes      |
| **Slow Deployment**            | All-or-nothing deploys, high-risk releases | Independent, low-risk deployments       |
| **All-or-Nothing Scaling**     | Wasteful resource allocation               | Granular, cost-effective scaling        |
| **Technological Rigidity**     | Locked into initial technology choices     | Freedom to choose best-fit technologies |
| **Team Coordination Overhead** | Merge conflicts, slow code reviews         | Autonomous team workflows               |

A monolith is unsuitable for a complex, long-lived enterprise system designed for agility.

***

## 2. Asynchronous Background Work (Event-Driven Patterns)

Long-running and side-effecting work is pushed off the request path and into
**Trigger.dev v4** background tasks (`packages/trigger`, `@trigger.dev/sdk`
`^4.4.5`). Tuturuuu does **not** run a general-purpose inter-service event bus
where every app publishes and subscribes to a shared broker; instead, it uses
Trigger.dev `task()` definitions that are invoked explicitly (or on a schedule)
to do durable, retryable async work. The event-driven *reasoning* below explains
why async, decoupled background work is valuable, and the examples use the real
v4 `task()` API.

### Core Rationale

To achieve **decoupling between request handling and durable background work**,
which is the foundation for a system that stays resilient, scalable, and
extensible under load.

### Detailed Justification

#### Ultimate Decoupling

If a request handler does its slow work inline, it must know about and wait on
every downstream side effect (email, indexing, analytics). That tightly couples
the user-facing path to all of them.

By offloading that work to a background task, the request handler only needs to
**enqueue the work and return**. The task owns the side effects and can be
changed, retried, or extended without touching the request handler.

**Real v4 task definition (`packages/trigger/src/schedule-tasks.ts`):**

```typescript theme={null}
import { task } from '@trigger.dev/sdk/v3';
import { schedulableTasksHelper } from './schedule-tasks-helper';

// A durable, retryable background task with its own queue/concurrency limit.
export const scheduleTask = task({
  id: 'schedule-task',
  queue: { concurrencyLimit: 10 },
  run: async (payload: { ws_id: string }) => {
    const result = await schedulableTasksHelper(payload.ws_id);
    if (!result.success) {
      throw new Error(result.error || 'Schedule tasks failed');
    }
    return { ws_id: payload.ws_id, ...result, success: true };
  },
});
```

The request handler enqueues this with `scheduleTask.trigger({ ws_id })` and
returns immediately; the task runs out-of-band.

#### Inherent Resilience and Asynchronicity

Synchronous API calls create "chains of failure." If a downstream service is slow or unavailable, the upstream caller is blocked, and the failure can cascade, bringing down the entire user request.

With background tasks, **Trigger.dev acts as a durable buffer**. If a downstream
dependency is slow or temporarily down, the task can retry without blocking the
original request, and the user-facing response is unaffected.

**In Tuturuuu:**

* A request can complete even if a downstream side effect (e.g. an email send) is temporarily failing
* Tasks are retried automatically (Trigger.dev manages retries and backoff)
* Failed runs are visible in the Trigger.dev dashboard for investigation
* A failing background task does not cascade into the user-facing request path

#### Natural Scalability and Load Leveling

A synchronous API can be overwhelmed by sudden traffic spikes.

Background tasks act as a **shock absorber**. Trigger.dev queues bursts of task
runs and processes them at a sustainable rate, governed by per-task
`queue.concurrencyLimit`. Scaling is a matter of letting more runs execute in
parallel rather than overwhelming a synchronous endpoint.

**Illustrative v4 task (patterned on `packages/trigger/src`):**

```typescript theme={null}
import { task } from '@trigger.dev/sdk/v3';

// During a burst, many onboarding runs are enqueued; the concurrency limit
// keeps execution at a sustainable rate.
export const onboardUserTask = task({
  id: 'onboard-user',
  queue: { concurrencyLimit: 25 },
  run: async (payload: { userId: string; email: string; wsId: string }) => {
    await sendWelcomeEmail(payload.email);
    await provisionDefaultResources(payload.userId, payload.wsId);
    return { userId: payload.userId, success: true };
  },
});

// Enqueue from a request handler without blocking the response:
// await onboardUserTask.trigger({ userId, email, wsId });
```

#### Extensibility and Future-Proofing

This is a **key strategic advantage**. EDA allows for new business capabilities to be added by simply deploying new services that listen to existing event streams.

For example, a new background task can be added to perform extra work after an
existing flow, often by triggering it from the same place that already enqueues
related work, without rewriting the core request handler.

**In Tuturuuu:**

* New async features: add a new Trigger.dev v4 `task()` in `packages/trigger` and enqueue it where needed
* Scheduled work: use Trigger.dev scheduling (see `unifiedScheduleTask` / `scheduleTask` in `packages/trigger/src`) without changing request handlers
* Heavier processing: move slow work into a task so the user-facing path stays fast

### Why Not a Purely Synchronous/REST Architecture?

While synchronous APIs are excellent for user-facing queries and commands that require an immediate response (a pattern supported by our API Gateway), using them for core inter-service communication creates a brittle, tightly coupled system.

| Synchronous Pattern Issue | Impact                                | Event-Driven Solution                                |
| ------------------------- | ------------------------------------- | ---------------------------------------------------- |
| **Tight Coupling**        | Services must know each other's APIs  | Services only know event schemas                     |
| **Cascading Failures**    | One slow service blocks entire chain  | Failures are isolated by broker                      |
| **Difficult Evolution**   | API changes break all consumers       | New consumers added without changes                  |
| **Poor Load Handling**    | Traffic spikes overwhelm services     | Background queue buffers and load-levels             |
| **Testing Complexity**    | Must mock all downstream side effects | Task `run` functions can be unit-tested in isolation |

**Our approach is hybrid:** synchronous APIs (Next.js API routes under
`/api/v1`, the `apps/backend` Rust API, and `packages/internal-api` helpers)
handle user-facing queries and commands, while durable Trigger.dev v4 tasks
handle slow or side-effecting background work. (Note: `apps/web/src/trpc` is a
minimal stub today, not the product API gateway — see Section 4.)

***

## 3. Ports-and-Adapters Thinking (Partial Hexagonal)

<Warning>
  Tuturuuu does **not** implement full hexagonal layering. There is no
  `packages/types/src/domain` directory and no
  `apps/web/src/infrastructure/repositories` layer. `apps/web` uses a conventional
  Next.js App Router structure (`app`, `components`, `lib`, `utils`, `hooks`,
  `features`). The code samples in this section are **illustrative pseudo-code** to
  teach the ports/adapters idea, not real file locations. Where Tuturuuu applies
  the *spirit* of this pattern, it does so through shared helper packages
  (`packages/internal-api`, `packages/supabase`) rather than formal domain/port
  interfaces.
</Warning>

### Core Rationale

To **keep business logic separable from technology dependencies** where it pays
off, improving maintainability and testability — applied pragmatically rather
than as a strict architectural mandate.

### Detailed Justification

#### Protection of the Domain Core

In traditional N-Tier architecture, business logic often becomes dependent on infrastructure concerns (e.g., database annotations within domain models). This couples the business rules to the technology.

The Hexagonal Architecture **inverts this dependency**. The core business logic is pure and has **zero knowledge of any external technology**. It defines "Ports" (interfaces) for the functionality it needs, such as `OrderRepository`.

**Illustrative pseudo-code (no such path exists in the repo):**

```typescript theme={null}
// Conceptual domain port (not a real file)
export interface WorkspaceRepository {
  findById(id: string): Promise<Workspace | null>;
  save(workspace: Workspace): Promise<void>;
}

// Business logic doesn't know about Supabase
export class WorkspaceService {
  constructor(private repo: WorkspaceRepository) {}

  async activateWorkspace(id: string) {
    const workspace = await this.repo.findById(id);
    workspace.activate(); // Pure domain logic
    await this.repo.save(workspace);
  }
}
```

#### Technology Agnosticism and Interchangeability

External technologies are implemented as "Adapters" that plug into the core's ports. We have a `PostgresOrderRepositoryAdapter` and a `KafkaEventPublisherAdapter`.

If we decide to migrate from PostgreSQL to MongoDB, we only need to write a new `MongoOrderRepositoryAdapter` and plug it in. The core business logic remains **completely unchanged**, making technology migrations low-risk and straightforward.

**Illustrative pseudo-code (no such path exists in the repo):**

```typescript theme={null}
// Conceptual infrastructure adapter (not a real file)
export class SupabaseWorkspaceRepository implements WorkspaceRepository {
  constructor(private client: SupabaseClient) {}

  async findById(id: string): Promise<Workspace | null> {
    const { data } = await this.client
      .from('workspaces')
      .select('*')
      .eq('id', id)
      .single();

    return data ? this.toDomain(data) : null;
  }

  async save(workspace: Workspace): Promise<void> {
    await this.client
      .from('workspaces')
      .upsert(this.toDatabase(workspace));
  }
}

// Easy to swap: Could create DrizzleWorkspaceRepository or PrismaWorkspaceRepository
```

#### Superior Testability

Because the domain core is isolated from the outside world, it can be tested **completely without** a running database, web server, or any other infrastructure.

We can use simple, in-memory mock adapters to test complex business rules. This results in tests that are **extremely fast**, **reliable**, and **easy to write**, leading to higher code quality.

**Illustrative pseudo-code (conceptual test, not a real file):**

```typescript theme={null}
class InMemoryWorkspaceRepository implements WorkspaceRepository {
  private workspaces = new Map<string, Workspace>();

  async findById(id: string) {
    return this.workspaces.get(id) || null;
  }

  async save(workspace: Workspace) {
    this.workspaces.set(workspace.id, workspace);
  }
}

describe('WorkspaceService', () => {
  it('activates workspace', async () => {
    const repo = new InMemoryWorkspaceRepository();
    const service = new WorkspaceService(repo);

    // No database, no network calls - tests run in milliseconds
    await service.activateWorkspace('ws-123');

    const workspace = await repo.findById('ws-123');
    expect(workspace.isActive).toBe(true);
  });
});
```

### Why Not a Traditional Layered/N-Tier Architecture?

The primary weakness of the traditional N-Tier architecture is its tendency to create **leaky abstractions** and **tight coupling** between layers.

| N-Tier Limitation        | Impact                                    | Hexagonal Solution                                    |
| ------------------------ | ----------------------------------------- | ----------------------------------------------------- |
| **Business Logic Leaks** | Domain models have ORM annotations        | Pure domain models, infrastructure separate           |
| **Tight Coupling**       | Layers depend on concrete implementations | Layers depend on abstractions (ports)                 |
| **Hard to Test**         | Tests require full infrastructure         | Mock adapters, fast unit tests                        |
| **Technology Lock-in**   | Changing DB means rewriting domain        | Swap adapters, domain unchanged                       |
| **Unclear Boundaries**   | "Service" and "Repository" blur together  | Clear separation: domain, application, infrastructure |

Business logic often becomes intertwined with persistence logic, making the system rigid, difficult to test in isolation, and hard to adapt to new technology requirements. The Hexagonal Architecture solves this by enforcing a **strict, clean boundary** around the application's core.

***

## 4. A React Modular Monolith & Headless UI

The `apps/web` frontend is architected as a "Modular Monolith" using React, with reusable logic factored into hooks following a "Headless UI" mindset.

<Info>
  This decision describes the **legacy `apps/web`** stack. It is being superseded
  by `apps/tanstack-web` (TanStack Start + TanStack Router/Query) for the frontend
  and `apps/backend` (Rust) for the API tier. The modular-monolith and headless-UI
  *principles* below still inform the new frontend, but treat `apps/web`-specific
  references as legacy. See
  [TanStack Start And Rust Migration](/platform/architecture/tanstack-rust-migration).
</Info>

### Core Rationale

To balance the **agility of a single codebase** with the **maintainability of a modular design**, while ensuring long-term flexibility in presentation.

### Detailed Justification

#### Maintainability at Scale (Modular Monolith)

A standard Single-Page Application (SPA) can quickly become a "big ball of mud" as it grows.

A **modular monolith** enforces logical boundaries between different features or domains (e.g., `Authentication`, `Dashboard`, `Settings`, `Finance`) within a single codebase. This improves code organization, reduces unintended coupling, and allows teams to work on different features with fewer conflicts.

**In Tuturuuu:**

```
apps/web/src/
├── app/
│   ├── [locale]/(dashboard)/[wsId]/
│   │   ├── finance/          # Finance module
│   │   ├── calendar/         # Calendar module
│   │   ├── tasks/            # Tasks module
│   │   └── settings/         # Settings module
├── components/
│   ├── finance/              # Finance-specific components
│   ├── calendar/             # Calendar-specific components
│   └── shared/               # Shared components
```

Each module is self-contained with clear boundaries, yet benefits from shared infrastructure.

#### Module Size Guardrail

Code that crosses 400 LOC per file or 200 LOC per component/widget should be split automatically before final verification. Prefer focused route modules, cards, panels, hooks, data loaders, and helper modules over monolithic files. When other modules already import an entrypoint, keep that entrypoint as a thin barrel re-export so the refactor improves maintainability without forcing unrelated import churn.

#### UI and Logic Separation (Headless UI)

In this pattern, React components are split into two parts:

1. A "headless" hook that manages all **logic, state, and accessibility** (e.g., `useUserDropdown`)
2. A presentation component that simply **renders the UI** based on the state provided by the hook

This clean separation allows us to **completely change the look and feel** (the "head") of a component by swapping out its presentation layer, without rewriting any of the complex business logic.

**Example from Tuturuuu:**

```typescript theme={null}
// Headless logic hook (packages/ui/src/hooks/useTaskList.ts)
export function useTaskList(boardId: string) {
  const [tasks, setTasks] = useState<Task[]>([]);
  const [isLoading, setIsLoading] = useState(false);

  const addTask = useCallback((task: Task) => {
    setTasks(prev => [...prev, task]);
  }, []);

  const removeTask = useCallback((id: string) => {
    setTasks(prev => prev.filter(t => t.id !== id));
  }, []);

  // All logic, accessibility, keyboard shortcuts
  return { tasks, isLoading, addTask, removeTask };
}

// Presentation component (apps/web/src/components/tasks/TaskList.tsx)
export function TaskList({ boardId }: Props) {
  const { tasks, isLoading, addTask, removeTask } = useTaskList(boardId);

  // Only UI rendering, no logic
  return (
    <div className="task-list">
      {tasks.map(task => (
        <TaskCard key={task.id} task={task} onRemove={removeTask} />
      ))}
    </div>
  );
}
```

#### Future-Proofing for Multiple Platforms

The headless hooks are **pure application logic**. This means they can be reused to power completely different UIs.

The same `useUserProfile` hook that powers a web application could later be used to power a **React Native mobile app** or even a command-line interface, providing maximum code reuse and flexibility.

**Future possibilities:**

```typescript theme={null}
// Same hook, different presentations
import { useTaskList } from '@tuturuuu/hooks';

// Web app (current)
<WebTaskList boardId={id} />

// Future: Mobile app
<MobileTaskList boardId={id} />

// Future: Desktop app (Electron/Tauri)
<DesktopTaskList boardId={id} />

// All use the same useTaskList() logic
```

### Why Not Other Frontend Architectures?

#### Micro-frontends

While powerful, this architecture introduces significant complexity in:

* Build tooling and module federation
* Deployment pipelines and version coordination
* Routing and state management across boundaries
* Performance overhead of loading multiple bundles

The modular monolith provides **many of the same organizational benefits** with a fraction of the operational overhead, making it a more pragmatic starting point.

#### Traditional Coupled (Server-Rendered) Frontends

These architectures tightly couple the frontend presentation to the backend logic, making it difficult to create modern, rich user experiences.

| Server-Rendered Limitation    | Impact                                   | React Modular Monolith Solution                                       |
| ----------------------------- | ---------------------------------------- | --------------------------------------------------------------------- |
| **Tight Backend Coupling**    | Frontend changes require backend deploys | Clean API separation via `/api/v1` routes and `packages/internal-api` |
| **Limited Interactivity**     | Complex UIs are difficult                | Full React capabilities                                               |
| **Poor Multi-Client Support** | Can't easily support mobile              | Reusable hooks and shared `packages/*`                                |
| **Slow Iteration**            | Full page reloads, slower development    | Fast HMR, component-level updates                                     |

They do not provide a clean API separation and are not flexible enough to support multiple client types (e.g., web and mobile) from a single backend.

<Note>
  **On the API gateway.** Earlier system-design pages referred to a tRPC API
  gateway. In the current codebase, `apps/web/src/trpc` is only a minimal stub:
  its router exports a single `healthCheck` procedure and its context is a
  hardcoded placeholder. There are **no** workspace/user/tasks/AI routers and no
  auth middleware there. Product data actually flows through `packages/internal-api`
  helpers and REST `/api/v1` routes (and, increasingly, the `apps/backend` Rust
  API). A repo guard also forbids `/trpc` calls from `apps/tanstack-web/src`.
</Note>

***

## Architectural Advantages and Drawbacks

The chosen architecture provides significant advantages but also introduces tradeoffs that must be managed. Understanding both sides enables informed decision-making.

<Info>
  For a comprehensive comparison of all architectural patterns (N-Tier, Hexagonal, Clean, Onion, Monolithic, Modular Monolith, Microservices, Event-Driven) with detailed pros and cons, see [Architectural Patterns Comparison](/platform/architecture/system-design/architectural-patterns-comparison).
</Info>

### Four Key Advantages

#### 1. Superior and Enduring Maintainability through Strong Architectural Boundaries

**Architectural Choice:** The architecture deliberately enforces separation of concerns at two critical levels: between business domains using Microservices, and between business logic and technology using Hexagonal Architecture.

**Impact and Justification:** This layered approach to separation is crucial for long-term project health. At the macro level, isolating business domains like "Web Platform" and "Finance" into separate microservices prevents the system from degrading into a "big ball of mud" where changes in one area have unintended consequences in another. At the micro level, the Hexagonal Architecture's strict isolation of the core domain logic ensures that the most valuable business rules are shielded from technological churn. This means we can upgrade a database, switch a messaging provider, or change a web framework with minimal, predictable impact, drastically reducing the cost and risk of maintenance over the system's lifespan.

**Clarifying Additions:** This structure makes responsibilities clearly defined and easier for teams to understand. Changes stay local to the affected boundary instead of leaking across the system. This reduces the likelihood of unintended side effects and simplifies long-term evolution.

#### 2. High Organizational Agility and Independent Deployability

**Architectural Choice:** The Microservices architecture decomposes the system into a suite of small, autonomous services, each aligned with a specific business capability.

**Impact and Justification:** This architectural choice is a direct enabler of organizational agility. It allows us to structure development teams to have full ownership of their respective services, from code to deployment (the "you build it, you run it" model). This autonomy eliminates the bottlenecks of a monolithic release process. A team can deploy updates to their service multiple times a day without coordinating with or waiting for other teams. This dramatically accelerates the feature delivery lifecycle and allows the organization to respond more quickly to changing business requirements.

**Clarifying Additions:** Teams can deliver updates without waiting on other domains. This separation increases overall development speed and lowers coordination overhead. The architecture naturally supports rapid and continuous improvement.

#### 3. Enhanced Fault Isolation and System-Wide Resilience

**Architectural Choice:** By decomposing the system into separate, independently running Microservices, we contain the "blast radius" of any potential failure.

**Impact and Justification:** In any complex system, failures are inevitable. A monolithic architecture is fragile because a single critical bug (like a memory leak or an unhandled exception) in a non-essential module can bring the entire application down. Our microservices design ensures that a failure in one service—for instance, the Finance app—is completely isolated. Core services like the main Web Platform and Calendar continue to run unaffected. This transforms a potentially catastrophic failure into a manageable, localized degradation of service, leading to a far more resilient and reliable platform for end-users.

**Clarifying Additions:** The system remains partially functional rather than failing entirely. Troubleshooting becomes simpler because issues are naturally localized. This architecture improves uptime and user experience during partial disruptions.

#### 4. UI/Logic Separation for Multi-Platform Potential and Design Flexibility

**Architectural Choice:** A Headless UI pattern is employed on the frontend, cleanly separating the presentation layer (the "head") from the application logic, state management, and accessibility hooks (the "body").

**Impact and Justification:** This choice provides two strategic advantages. Firstly, it offers immense design flexibility. The entire look and feel of the application can be radically redesigned by creating a new presentation layer that plugs into the existing, stable application logic, allowing for rapid rebranding or UX overhauls. Secondly, and more importantly, it makes the application logic platform-agnostic. The "headless" hooks and state management code can be reused to power completely different frontends in the future, such as a native mobile application or a voice-activated interface, maximizing code reuse and ensuring the system can adapt to new user touchpoints.

**Clarifying Additions:** Changes to visual design do not risk breaking functional behavior. Functional logic can be reused across new user interfaces with minimal changes. This future-proofs the frontend against new device types or presentation styles.

### Four Key Drawbacks

#### 1. Significant Inherent Operational Complexity

**Architectural Choice:** A distributed Microservices architecture is not a single application but a system of systems, requiring a sophisticated support infrastructure including Service Discovery, an API Gateway, and centralized observability.

**Impact and Justification:** This introduces a steep increase in operational complexity compared to a monolith. The team must now manage the deployment, networking, and health of multiple independent applications. This requires specialized DevOps expertise and a robust toolchain for logging, metrics, and tracing to understand the system's behavior. The infrastructure itself becomes a critical product that must be built and maintained, representing a significant investment of time and resources.

**Clarifying Additions:** More moving parts require greater architectural discipline. Each service adds overhead that must be monitored and understood. Organizations must prepare for the ongoing effort required to operate a distributed system.

#### 2. Challenges of Distributed Data Management and Consistency

**Architectural Choice:** The principle of decentralized data ownership in a Microservices architecture prohibits the use of traditional, simple ACID transactions across service boundaries.

**Impact and Justification:** This forces the system to embrace Eventual Consistency. Business processes that span multiple services must be carefully designed using complex patterns like Sagas to handle failures and ensure that the system eventually reaches a consistent state. This is a fundamentally harder paradigm for developers to reason about and requires a shift in mindset away from the guarantees provided by a single relational database.

**Clarifying Additions:** Teams must think differently about data reliability across boundaries. Data no longer updates everywhere at the same moment, which requires intentional design. This increases cognitive load when building cross-service workflows.

#### 3. Intrinsic Complexity of Distributed System Debugging and Performance Analysis

**Architectural Choice:** A single user request can trigger a complex, asynchronous chain of interactions that traverses the API Gateway and fans out to multiple backend services and background jobs.

**Impact and Justification:** When something goes wrong, diagnosing the root cause is no longer as simple as looking at a single log file or stack trace. It requires correlating logs, metrics, and traces from multiple services to piece together the full story. This necessitates a mature and well-integrated observability stack (e.g., distributed tracing with OpenTelemetry) to make debugging and performance tuning manageable.

**Clarifying Additions:** Architectural visibility becomes essential for diagnosing the flow of requests. Failures may appear in one service even if the root cause lies elsewhere. This makes system-wide insight a core architectural requirement.

#### 4. Governance Overhead of Maintaining Modularity

**Architectural Choice:** Both the backend Microservices and the frontend Modular Monolith rely on maintaining strict boundaries to be effective.

**Impact and Justification:** This requires active architectural governance. Without discipline, developers can easily create inappropriate dependencies, turning the microservices into a distributed monolith or eroding the boundaries of the frontend modules. The architecture requires ongoing vigilance, clear standards, and automated checks (e.g., dependency analysis tools) to prevent architectural decay over time.

**Clarifying Additions:** Teams must follow agreed-upon boundaries consistently. Regular architecture reviews help identify early signs of erosion. Maintaining clean boundaries becomes an ongoing responsibility rather than a one-time setup.

***

## Decision Summary

| Decision                          | Adoption in Tuturuuu                                                  | Problem Solved                    | Trade-off Accepted                 |
| --------------------------------- | --------------------------------------------------------------------- | --------------------------------- | ---------------------------------- |
| **Independently deployable apps** | Adopted (Turborepo `apps/*`, shared Supabase)                         | Monolith scaling/ownership limits | Increased operational complexity   |
| **Async background work**         | Adopted (Trigger.dev v4 `task()`)                                     | Tight synchronous coupling        | More moving parts to observe       |
| **Ports-and-adapters thinking**   | Partial (shared helper packages, not formal layers)                   | Technology lock-in                | N/A — applied pragmatically        |
| **React modular monolith**        | Adopted in legacy `apps/web`; principles carry to `apps/tanstack-web` | Frontend chaos at scale           | Discipline required for boundaries |

## Next Steps

* [Layering Patterns](/platform/architecture/system-design/layering-patterns) - N-tier vs Hexagonal/Clean architecture comparison
* [Event-Driven Architecture](/platform/architecture/system-design/event-driven-architecture) - Advantages and drawbacks in detail
* [Extensibility, Resilience & Scalability](/platform/architecture/system-design/extensibility-resilience-scalability) - Why these properties matter
* [Quality Attributes](/platform/architecture/system-design/quality-attributes) - Maintainability, testability, and deployability
* [Security Architecture](/platform/architecture/system-design/security-architecture) - Comprehensive security justification
* [Observability & Monitoring](/platform/architecture/system-design/observability-monitoring) - Observability patterns and practices
* [Hexagonal Architecture](/platform/architecture/system-design/hexagonal-architecture) - Implementation patterns
* [Microservices Patterns](/platform/architecture/system-design/microservices-patterns) - Service boundaries in practice


# Architectural Patterns Comparison
Source: https://docs.tuturuuu.com/platform/architecture/system-design/architectural-patterns-comparison

Comprehensive comparison of architectural patterns with design justifications, pros, cons, and usage guidance

This document provides a comprehensive comparison of all major architectural patterns, including their design justifications, advantages, disadvantages, and practical guidance on when to use each pattern.

<Note>
  **Key Insight**: Different architectural patterns solve different problems. Understanding the trade-offs is essential for making informed architectural decisions.
</Note>

<Warning>
  **How to read the "In Tuturuuu" notes**: This page is primarily a pattern-education reference. The Tuturuuu apps (`apps/web`, `apps/finance`, `apps/calendar`, etc.) are conventional Next.js App Router apps organized as `app/`, `components/`, `lib/`, and `utils/` — they do **not** implement formal hexagonal/clean/onion layering, and they share a single Supabase project rather than per-service databases. Where an "In Tuturuuu" note describes a pattern as adopted, treat it as **aspirational/illustrative** unless it is explicitly grounded in real code. The platform is also mid-migration from `apps/web` (Next.js) to `apps/tanstack-web` (TanStack Start) plus a Rust backend (`apps/backend`); see [TanStack Start And Rust Migration](/platform/architecture/tanstack-rust-migration).
</Warning>

## Pattern Categories

Architectural patterns can be categorized into two main types:

1. **Internal Patterns** - How code is organized within a service or application
   * N-Tier Architecture
   * Hexagonal Architecture (Ports & Adapters)
   * Clean Architecture
   * Onion Architecture

2. **External Patterns** - How services are distributed and communicate
   * Monolithic Architecture
   * Modular Monolith
   * Microservices Architecture
   * Event-Driven Architecture

***

## Internal Architectural Patterns

These patterns define how code is organized and structured within a single deployable unit (application or service).

### N-Tier Architecture

#### Design Justification

N-Tier architecture emerged from the need to separate concerns in applications by organizing code into horizontal layers based on technical responsibilities. Each tier handles a specific aspect of the application (presentation, business logic, data access), making it conceptually simple and straightforward to understand.

**Problem It Solves**: Provides basic separation of concerns in applications, making it easier to understand where different types of code should live.

#### Pros

**1. Simplicity and Familiarity**

* Extremely easy to understand and learn
* Most developers are already familiar with the pattern
* Minimal cognitive overhead for new team members
* Clear separation: UI code in presentation, business rules in BLL, database code in DAL

**2. Rapid Development for Simple Applications**

* Quick to set up and start building
* Minimal architectural overhead
* Straightforward data flow from top to bottom
* Works well for CRUD-heavy applications

**3. Tooling and Framework Support**

* Extensive tooling support (Visual Studio, IntelliJ, etc.)
* Many frameworks designed around this pattern (ASP.NET, Spring MVC)
* Large ecosystem of tutorials and examples
* Well-documented best practices

**4. Clear Technical Separation**

* Easy to assign work based on technical skills
* Frontend developers work in presentation tier
* Backend developers work in business logic tier
* Database specialists work in data access tier

#### Cons

**1. Tight Coupling to Infrastructure**

* Business logic directly depends on data access layer
* Changing databases requires modifying business logic
* Framework dependencies leak into business code
* Hard to test business rules in isolation

**Example:**

```typescript theme={null}
// Business logic tightly coupled to Supabase
export class WorkspaceService {
  async createWorkspace(name: string) {
    // PROBLEM: Business logic knows about database implementation
    const { data } = await supabase.from('workspaces').insert({ name });
    return data;
  }
}
```

**2. Poor Testability**

* Business logic can't be tested without database
* Tests are slow (require database setup/teardown)
* Tests are fragile (break when database changes)
* Mocking is complex and brittle

**3. Technology Lock-In**

* Business logic married to specific ORM or framework
* Difficult to swap technologies
* Framework upgrades can require business logic changes
* Vendor lock-in becomes a serious risk

**4. Leaky Abstractions**

* Database concerns leak into business logic (SQL, transactions)
* Business logic becomes aware of persistence details
* Domain models often have framework annotations
* Violates Single Responsibility Principle

**5. Inflexible for Complex Business Logic**

* Business rules scattered across multiple layers
* Complex domain logic doesn't fit well in BLL tier
* Validation logic duplicated across layers
* No clear place for domain concepts

#### When to Use

✅ **Simple CRUD applications** with minimal business logic
✅ **Rapid prototyping** where speed matters more than quality
✅ **Small teams** unfamiliar with DDD or hexagonal concepts
✅ **Short-lived projects** that won't need long-term maintenance
✅ **Applications that will remain small** (\<10k LOC)

#### When to Avoid

❌ **Complex business logic** that needs to be protected
❌ **Long-term projects** requiring maintainability
❌ **Applications requiring high test coverage**
❌ **Systems that may need technology swaps**
❌ **Domain-driven design** implementations

***

### Hexagonal Architecture (Ports & Adapters)

#### Design Justification

Hexagonal Architecture (invented by Alistair Cockburn) solves the fundamental problem of tight coupling between business logic and infrastructure. By inverting dependencies and isolating the domain core, it ensures that business rules remain pure, testable, and independent of technology choices.

**Problem It Solves**: Protects business logic from infrastructure changes and framework dependencies, enabling true technology agnosticism and superior testability.

```mermaid theme={null}
graph LR
    subgraph External
        UI[UI/API]
        DB[(Database)]
    end

    subgraph Hexagon
        subgraph Adapters
            PrimaryAdp[Primary<br/>Adapter]
            SecondaryAdp[Secondary<br/>Adapter]
        end

        subgraph Ports
            PrimaryPort[Primary<br/>Port]
            SecondaryPort[Secondary<br/>Port]
        end

        Core[Domain<br/>Core]
    end

    UI --> PrimaryAdp
    PrimaryAdp --> PrimaryPort
    PrimaryPort --> Core
    Core --> SecondaryPort
    SecondaryPort --> SecondaryAdp
    SecondaryAdp --> DB

    style Core fill:#ffd54f,stroke:#f57f17,stroke-width:3px
    style Ports fill:#81c784,stroke:#388e3c,stroke-width:2px
    style Adapters fill:#e3f2fd,stroke:#1976d2,stroke-width:2px
```

#### Pros

**1. Domain Logic is Pure and Technology-Agnostic**

* Business rules have zero infrastructure dependencies
* No database, no frameworks, no external services
* Core logic expresses business concepts directly
* Easy to understand business rules without technical noise

**Example:**

```typescript theme={null}
// Pure domain entity - no infrastructure dependencies
export class Workspace {
  static create(name: string, ownerId: string): Workspace {
    if (name.length < 3 || name.length > 50) {
      throw new DomainError('Workspace name must be 3-50 characters');
    }
    return new Workspace(generateId(), name, ownerId, true, new Date());
  }

  archive(): void {
    if (!this._isActive) {
      throw new DomainError('Workspace is already archived');
    }
    this._isActive = false;
  }
}
```

**2. Superior Testability**

* Domain logic tested in isolation without infrastructure
* Tests run in milliseconds (no database, no network)
* Tests are reliable (no external dependencies)
* Easy to write comprehensive test suites

**Example:**

```typescript theme={null}
// Test runs instantly, no infrastructure needed
describe('Workspace', () => {
  it('enforces name length business rule', () => {
    expect(() => Workspace.create('ab', 'owner-123'))
      .toThrow('Workspace name must be 3-50 characters');
  });
});
```

**3. Technology Can Be Swapped Easily**

* Infrastructure implemented as pluggable adapters
* Swap Supabase for Prisma without touching business logic
* Change from REST to GraphQL without domain changes
* Framework upgrades don't affect core business rules

**4. Clear Separation of Concerns**

* Domain core focuses purely on business rules
* Adapters handle technical concerns
* Ports define clear contracts
* Each layer has a single, well-defined responsibility

**5. Supports Test-Driven Development (TDD)**

* Easy to write tests before implementation
* Fast feedback loop encourages TDD practices
* Can develop business logic without infrastructure setup
* Reduces time to first working test

**6. Facilitates Domain-Driven Design (DDD)**

* Natural fit for DDD patterns (entities, value objects, aggregates)
* Business logic expressed in ubiquitous language
* Clear boundaries between domain and infrastructure
* Supports rich domain models

#### Cons

**1. Increased Complexity and Learning Curve**

* More moving parts than N-Tier
* Requires understanding of dependency inversion
* Team needs training on hexagonal concepts
* Harder for junior developers initially

**2. More Code and Boilerplate**

* Need to write ports (interfaces) and adapters
* Mapping between domain models and database models
* Dependency injection configuration
* More files and folders to manage

**Example:**

```typescript theme={null}
// Domain model
class Workspace { ... }

// Port (interface)
interface WorkspaceRepository { ... }

// Adapter implementation
class SupabaseWorkspaceRepository implements WorkspaceRepository { ... }

// Mapping logic
private toDomain(row: any): Workspace { ... }
private toDatabase(workspace: Workspace): any { ... }

// More code than just `await supabase.from('workspaces').insert(...)`
```

**3. Overkill for Simple CRUD Applications**

* Unnecessary complexity for basic data management
* Slows down development of trivial features
* Mapping overhead adds no value for simple cases
* May frustrate team working on straightforward tasks

**4. Requires Architectural Discipline**

* Easy to bypass abstractions and couple to infrastructure
* Needs code reviews to enforce boundaries
* Developers may take shortcuts under pressure
* Degradation is gradual and hard to detect

#### When to Use

✅ **Complex business logic** that requires protection
✅ **Long-term projects** (multi-year lifespan)
✅ **Domain-driven design** implementations
✅ **High test coverage requirements** (>80%)
✅ **Systems that may need technology migration**
✅ **Projects with domain experts** involved

#### When to Avoid

❌ **Simple CRUD applications** with minimal logic
❌ **Rapid prototypes** that won't be maintained
❌ **Teams lacking DDD/hexagonal experience**
❌ **Projects with extreme time constraints**
❌ **Very small codebases** (\<5k LOC)

**In Tuturuuu (aspirational)**: Full ports-and-adapters layering is a target pattern we reach for in genuinely complex domains, not a blanket rule. Today the apps are conventional Next.js App Router apps (`app/`, `components/`, `lib/`, `utils/`) without dedicated `domain/`, `application/`, and `infrastructure/` directories. Business logic that benefits from isolation is factored into shared `packages/*` helpers (for example `packages/internal-api`, `packages/utils`) rather than a strict hexagon.

***

### Clean Architecture

#### Design Justification

Clean Architecture (by Robert C. Martin) extends hexagonal principles by explicitly defining concentric layers with strict dependency rules. Dependencies must always point inward toward the domain core, ensuring the most important business rules are completely isolated from volatile technical details.

**Problem It Solves**: Provides a systematic approach to dependency management, ensuring business logic remains stable while infrastructure changes freely.

```mermaid theme={null}
graph TD
    subgraph L4["Frameworks & Drivers"]
        FW["Database, Web, UI"]
    end

    subgraph L3["Interface Adapters"]
        IA["Controllers, Gateways"]
    end

    subgraph L2["Application Business Rules"]
        UC["Use Cases"]
    end

    subgraph L1["Enterprise Business Rules"]
        E["Entities"]
    end

    FW -.->|Dependencies<br/>point INWARD| IA
    IA -.->|Dependencies<br/>point INWARD| UC
    UC -.->|Dependencies<br/>point INWARD| E

    style L1 fill:#ffd54f,stroke:#f57f17,stroke-width:4px
    style L2 fill:#fff3e0,stroke:#f57c00,stroke-width:3px
    style L3 fill:#e3f2fd,stroke:#1976d2,stroke-width:2px
    style L4 fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px
```

#### Pros

**1. Explicit Layer Definitions**

* Four clearly defined layers with specific purposes
* Enterprise Business Rules (entities) - core domain
* Application Business Rules (use cases) - application workflows
* Interface Adapters (controllers) - translation layer
* Frameworks & Drivers (infrastructure) - external tools

**2. Strong Dependency Rule**

* Dependencies can only point inward, never outward
* Inner layers know nothing about outer layers
* Violations are easy to detect
* Architectural integrity is maintainable

**3. Use Cases as First-Class Citizens**

* Application workflows explicitly modeled
* Clear boundary between domain and application logic
* Use cases are testable application-level operations
* Business processes well-documented in code

**Example:**

```typescript theme={null}
// Use case clearly expresses application workflow
export class CreateWorkspaceUseCase {
  constructor(
    private readonly repository: WorkspaceRepository,
    private readonly eventPublisher: EventPublisher
  ) {}

  async execute(command: CreateWorkspaceCommand): Promise<Workspace> {
    // 1. Create domain entity (domain logic)
    const workspace = Workspace.create(command.name, command.ownerId);

    // 2. Persist (infrastructure)
    await this.repository.save(workspace);

    // 3. Publish event (infrastructure)
    await this.eventPublisher.publish(new WorkspaceCreatedEvent(workspace));

    return workspace;
  }
}
```

**4. Framework Independence**

* Core business logic has zero framework dependencies
* Can upgrade frameworks without touching entities or use cases
* Frameworks become implementation details
* Reduces framework lock-in risks

#### Cons

**1. More Layers Than Hexagonal**

* Four layers vs hexagonal's simpler structure
* Can feel over-engineered for some applications
* More navigation between files and folders
* Steeper learning curve

**2. Distinction Between Entities and Use Cases Can Be Unclear**

* Developers may struggle with entity vs use case logic
* Business rules can end up in wrong layer
* Requires deep understanding of DDD concepts
* Guidelines needed to maintain clear boundaries

**3. Use Case Explosion**

* Each application workflow becomes a separate use case
* Can lead to many small, similar classes
* Folder structure can become overwhelming
* Feels like boilerplate for simple operations

#### When to Use

Same as Hexagonal Architecture, but especially when:

✅ **Clear separation of entities and use cases** is needed
✅ **Team values explicit architectural boundaries**
✅ **Application workflows are complex** and deserve first-class modeling
✅ **Robert C. Martin's principles** resonate with the team

#### When to Avoid

Same as Hexagonal Architecture, plus:

❌ **Team finds four layers unnecessarily complex**
❌ **Simple workflows don't justify use case classes**

**In Tuturuuu**: Not strictly followed; we prefer simpler hexagonal approach but adopt use case pattern where beneficial.

***

### Onion Architecture

#### Design Justification

Onion Architecture (by Jeffrey Palermo) visualizes layers as concentric circles, emphasizing that all dependencies point inward toward the core. It's similar to Clean Architecture but with slightly different layer names and emphasis on domain-centric design.

**Problem It Solves**: Same as Hexagonal and Clean, but with visual metaphor making dependency direction intuitive.

#### Pros & Cons

Onion Architecture shares the same pros and cons as Hexagonal and Clean Architecture. The main differences are:

**Unique Aspects:**

* Visual metaphor (onion layers) is intuitive
* Slightly simpler than Clean (fewer prescribed layers)
* Emphasizes domain services as a separate layer
* Popular in .NET community

**In Tuturuuu**: Not explicitly used, but principles align with our hexagonal approach.

***

## External Architectural Patterns

These patterns define how applications are deployed, distributed, and communicate with each other.

### Monolithic Architecture

#### Design Justification

A monolithic architecture packages the entire application as a single deployable unit. All features, modules, and layers exist within one codebase and deploy together. This is the traditional, default architecture for most applications.

**Problem It Solves**: Provides simplicity in deployment, development environment setup, and team coordination for small to medium applications.

```mermaid theme={null}
graph TB
    subgraph Monolith["Monolithic Application"]
        UI["UI Layer"]
        BLL["Business Logic"]
        DAL["Data Access"]
        ModA["Module A"]
        ModB["Module B"]
        ModC["Module C"]
    end

    DB[("Single Database")]

    UI --> BLL
    BLL --> DAL
    DAL --> DB

    BLL --> ModA
    BLL --> ModB
    BLL --> ModC

    style Monolith fill:#fff3e0,stroke:#f57c00,stroke-width:3px
    style DB fill:#e8f5e9,stroke:#388e3c,stroke-width:2px
```

#### Pros

**1. Simplicity**

* Single codebase, single repository
* Single deployment artifact
* Simple development environment setup
* Easy to reason about the entire system

**2. Easy Development Workflow**

* All code changes happen in one place
* No cross-service coordination needed
* Straightforward debugging (single process)
* IDE works well with single codebase

**3. Simple Deployment**

* Deploy one artifact to production
* Atomic deployments (all or nothing)
* No service orchestration needed
* Rollback is straightforward

**4. Performance**

* In-process function calls (fast)
* No network overhead between modules
* Single database connection pool
* No serialization/deserialization overhead

**5. Easier to Test End-to-End**

* Spin up entire application locally
* Integration tests are straightforward
* No need to mock external services
* Complete system available for testing

#### Cons

**1. Scaling Challenges**

* Must scale entire application as a unit
* Can't scale individual features independently
* Wasteful resource allocation
* Expensive at high scale

**Example:**

```typescript theme={null}
// Problem: Even if only the reporting module needs more resources,
// we must scale the entire monolith

// Monolith running on server:
// - User authentication (low load)
// - CRUD operations (low load)
// - Report generation (HIGH load) ← Only this needs scaling
// - Admin panel (low load)

// Must scale everything to handle report generation load
// This scales authentication, CRUD, and admin unnecessarily
```

**2. Tight Coupling and Dependency Management**

* Modules easily become interdependent
* Changes ripple across the codebase
* Hard to isolate features
* Difficult to enforce module boundaries

**3. Slow Development at Scale**

* Large codebase slows down IDE
* Long build times
* Merge conflicts increase with team size
* Difficult to parallelize work across teams

**4. Deployment Risk**

* Any change requires deploying entire application
* Small bug fix carries high risk
* Downtime affects all features
* Rollback affects entire system

**5. Technology Lock-In**

* Entire application must use same technology stack
* Can't adopt new technologies incrementally
* Framework upgrades affect entire application
* Limited flexibility in technology choices

**6. Team Scaling Issues**

* Difficult to divide work across multiple teams
* High coordination overhead
* Merge conflicts increase
* Conway's Law: Organization mirrors monolith structure

#### When to Use

✅ **Small to medium applications**
✅ **Single, co-located team**
✅ **Limited operational complexity budget**
✅ **Predictable scaling requirements**
✅ **Startup MVP** or proof of concept
✅ **Low traffic applications**

#### When to Avoid

❌ **Large teams** (>20 developers)
❌ **Need independent deployment** of features
❌ **Different scaling requirements** per feature
❌ **High availability requirements** (99.99%+)
❌ **Diverse technology needs** per domain

***

### Modular Monolith

#### Design Justification

A Modular Monolith combines monolithic deployment with modular organization. The application is still deployed as a single unit, but internally structured into well-defined, loosely-coupled modules with clear boundaries. This provides many benefits of microservices without operational complexity.

**Problem It Solves**: Enables team scalability and clear boundaries while avoiding distributed systems complexity.

```mermaid theme={null}
graph TB
    subgraph MM["Modular Monolith"]
        subgraph ModA["Finance Module"]
            FA["Finance API"]
            FL["Finance Logic"]
            FD["Finance Data"]
        end

        subgraph ModB["Calendar Module"]
            CA["Calendar API"]
            CL["Calendar Logic"]
            CD["Calendar Data"]
        end

        subgraph ModC["Tasks Module"]
            TA["Tasks API"]
            TL["Tasks Logic"]
            TD["Tasks Data"]
        end

        Shared["Shared Infrastructure"]
    end

    DB[("Single Database<br/>(with module schemas)")]

    FD --> DB
    CD --> DB
    TD --> DB

    ModA -.-|Module<br/>Boundaries| ModB
    ModB -.-|Module<br/>Boundaries| ModC

    style ModA fill:#e3f2fd,stroke:#1976d2,stroke-width:2px
    style ModB fill:#fff3e0,stroke:#f57c00,stroke-width:2px
    style ModC fill:#c8e6c9,stroke:#2e7d32,stroke-width:2px
    style MM fill:#fff,stroke:#000,stroke-width:3px
```

#### Pros

**1. Combines Monolith Simplicity with Modular Benefits**

* Single deployment unit (simple operations)
* Clear module boundaries (organizational clarity)
* Shared infrastructure (reduced duplication)
* Easier than microservices to operate

**2. Team Scalability**

* Teams can own modules independently
* Reduced coordination overhead
* Clear ownership boundaries
* Parallel development possible

**3. Enforced Boundaries Without Distribution**

* Modules communicate through well-defined interfaces
* Can enforce boundaries programmatically
* No network overhead
* Easier to refactor than microservices

**4. Migration Path to Microservices**

* Modules can be extracted as services later
* Boundaries already defined
* Incremental migration possible
* Low-risk evolution strategy

**Example in Tuturuuu:**

```typescript theme={null}
// apps/web/src/ - Modular organization
apps/web/src/
├── app/[locale]/(dashboard)/[wsId]/
│   ├── finance/           # Finance module
│   │   ├── transactions/
│   │   ├── reports/
│   │   └── _components/   # Finance-specific components
│   ├── calendar/          # Calendar module
│   │   ├── events/
│   │   └── _components/   # Calendar-specific components
│   └── tasks/             # Tasks module
│       ├── boards/
│       └── _components/   # Task-specific components
```

**5. Shared Infrastructure and Code**

* Reuse common utilities easily
* Shared authentication, logging, etc.
* No code duplication across modules
* Centralized configuration

#### Cons

**1. Requires Discipline to Maintain Boundaries**

* Easy to create cross-module dependencies
* Boundaries are convention-based, not enforced
* Gradual degradation without governance
* Need automated tools to detect violations

**2. Still Scales as a Unit**

* Can't scale individual modules
* All modules deployed together
* Resource allocation is coarse-grained
* Same scaling limitations as monolith

**3. Shared Database Can Become Bottleneck**

* All modules use same database
* Schema coupling between modules
* Difficult to optimize per-module data access
* Database becomes single point of contention

**4. Not True Isolation**

* Module failure can affect other modules
* Shared resources (memory, CPU) create contention
* Memory leak in one module affects all
* Less fault isolation than microservices

#### When to Use

✅ **Medium to large monoliths** needing better organization
✅ **Growing teams** (10-50 developers)
✅ **Clear domain boundaries** exist
✅ **Want microservices benefits** without operational complexity
✅ **Migration path** from monolith to microservices desired
✅ **Don't need independent deployment** yet

#### When to Avoid

❌ **Very small applications** (overhead not justified)
❌ **Need independent deployment** of modules
❌ **Different scaling requirements** per module
❌ **True fault isolation** is critical
❌ **Modules have very different technology needs**

**In Tuturuuu**: `apps/web` is organized as a modular monolith, with feature folders (Finance, Calendar, Tasks, and more) under `app/[locale]/(dashboard)/[wsId]/` and shared code in `packages/*`. The boundaries are convention-based rather than compiler-enforced. The successor frontend, `apps/tanstack-web`, follows the same modular approach with TanStack Router route trees.

***

### Microservices Architecture

#### Design Justification

Microservices architecture decomposes the system into small, independently deployable services, each focused on a specific business capability. Services communicate via lightweight protocols (HTTP, events) and can be developed, deployed, and scaled independently.

**Problem It Solves**: Enables organizational scalability, independent deployment, technology diversity, and granular scaling for complex, large-scale systems.

```mermaid theme={null}
graph TB
    subgraph MS["Microservices Architecture"]
        Web["Web Service"]
        Finance["Finance Service"]
        Calendar["Calendar Service"]
        Tasks["Tasks Service"]
        AI["AI Service"]
    end

    Gateway["API Gateway"]
    Broker["Event Broker"]

    WebDB[("Web DB")]
    FinDB[("Finance DB")]
    CalDB[("Calendar DB")]

    Gateway --> Web
    Gateway --> Finance
    Gateway --> Calendar

    Web --> Broker
    Finance --> Broker
    Calendar --> Broker
    Tasks --> Broker
    AI --> Broker

    Web --> WebDB
    Finance --> FinDB
    Calendar --> CalDB

    style Web fill:#e3f2fd,stroke:#1976d2,stroke-width:2px
    style Finance fill:#fff3e0,stroke:#f57c00,stroke-width:2px
    style Calendar fill:#c8e6c9,stroke:#2e7d32,stroke-width:2px
    style Tasks fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px
    style AI fill:#ffcdd2,stroke:#c62828,stroke-width:2px
```

#### Pros

**1. Independent Deployment and Scalability**

* Deploy services independently without coordination
* Scale services based on individual needs
* Deploy multiple times per day per service
* Reduced deployment risk (only one service affected)

**Example:**

```typescript theme={null}
// Different services scale independently
const scaling = {
  web: { min: 2, max: 100 },      // High traffic, needs scaling
  finance: { min: 1, max: 10 },   // Moderate traffic
  calendar: { min: 1, max: 5 },   // Low traffic
  admin: { min: 1, max: 2 }       // Very low traffic
};
```

**2. Organizational Scalability**

* Teams own services end-to-end ("you build it, you run it")
* Parallel development across teams
* Reduced coordination overhead
* Clear ownership and accountability

**3. Technology Diversity**

* Each service can use different technology stack
* Choose best tool for each job
* Experiment with new technologies in isolation
* Incremental technology adoption

**Example:**

```typescript theme={null}
// Different services, different technologies
const services = {
  web: { language: 'TypeScript', framework: 'Next.js' },
  ml: { language: 'Python', framework: 'FastAPI' },
  realtime: { language: 'Go', framework: 'Gin' },
  batch: { language: 'Rust', framework: 'Actix' }
};
```

**4. Fault Isolation**

* Service failure doesn't bring down entire system
* Blast radius is limited to single service
* Other services continue operating
* System degrades gracefully

**5. Easier to Understand Individual Services**

* Each service is small and focused
* New developers can understand one service quickly
* Cognitive load is reduced
* Domain complexity is bounded

#### Cons

**1. Significant Operational Complexity**

* Need service discovery, API gateway, load balancers
* Distributed logging, tracing, and monitoring essential
* Complex deployment pipelines
* Requires mature DevOps practices

**2. Distributed System Challenges**

* Network latency and unreliability
* Debugging is harder (distributed tracing needed)
* Performance tuning is complex
* Testing end-to-end is difficult

**3. Data Management Complexity**

* Each service has its own database
* No distributed transactions (must use sagas)
* Eventual consistency instead of strong consistency
* Complex queries across services are difficult

**Example:**

```typescript theme={null}
// Complex workflow spanning multiple services
async function createWorkspaceWithResources(data: WorkspaceData) {
  // 1. Create workspace (Web Service)
  const workspace = await webService.createWorkspace(data);

  // 2. Setup finance (Finance Service)
  // Problem: What if this fails? Need saga pattern
  await financeService.setupAccount(workspace.id);

  // 3. Create calendar (Calendar Service)
  // Problem: What if this fails? How to rollback?
  await calendarService.createCalendar(workspace.id);

  // Need complex saga orchestration for rollback
}
```

**4. Increased Infrastructure Costs**

* More servers/containers to run
* More databases to maintain
* More monitoring and logging infrastructure
* Higher cloud bills

**5. Requires Organizational Maturity**

* Teams must be autonomous and skilled
* Need strong DevOps culture
* Requires discipline to maintain service boundaries
* Not suitable for inexperienced teams

**6. Service Versioning and API Compatibility**

* Must maintain backward compatibility
* Breaking changes require careful coordination
* Versioning strategy is essential
* Contract testing is mandatory

#### When to Use

✅ **Large, complex systems** with multiple domains
✅ **Large teams** (>50 developers)
✅ **Different scaling requirements** per feature
✅ **Need independent deployment** per domain
✅ **High availability requirements** (99.99%+)
✅ **Organization has DevOps maturity**
✅ **Different technology needs** per domain

#### When to Avoid

❌ **Small applications** (\<50k LOC)
❌ **Small teams** (\<10 developers)
❌ **Limited operational expertise**
❌ **Tight budget** constraints
❌ **Strong consistency requirements** dominate
❌ **Startup MVP** or proof of concept

**In Tuturuuu**: The monorepo hosts many independently deployable apps (`web`, `finance`, `calendar`, `nova`, `rewise`, and more) that scale separately. This resembles microservices at the deployment layer, but with two important caveats: the apps share a **single Supabase project** rather than per-service databases, and most are built on the same Next.js stack rather than diverse technologies. The notable exception is `apps/backend`, the new Rust API service (port `7820`) introduced by the [TanStack Start And Rust Migration](/platform/architecture/tanstack-rust-migration).

***

### Event-Driven Architecture

#### Design Justification

Event-Driven Architecture (EDA) uses asynchronous events as the primary communication mechanism between services. Services publish events when state changes occur, and other services subscribe to relevant events, reacting accordingly. This creates ultimate decoupling between services.

**Problem It Solves**: Eliminates tight coupling between services, enables asynchronous processing, and provides natural extensibility for adding new functionality.

```mermaid theme={null}
graph LR
    subgraph Producers
        ServiceA["Service A"]
        ServiceB["Service B"]
    end

    Broker["Event Broker<br/>(Trigger.dev)"]

    subgraph Consumers
        ServiceC["Service C"]
        ServiceD["Service D"]
        ServiceE["Service E"]
    end

    ServiceA -->|Publish Events| Broker
    ServiceB -->|Publish Events| Broker

    Broker -->|Subscribe| ServiceC
    Broker -->|Subscribe| ServiceD
    Broker -->|Subscribe| ServiceE

    style Broker fill:#ffd54f,stroke:#f57f17,stroke-width:3px
    style Producers fill:#e3f2fd,stroke:#1976d2,stroke-width:2px
    style Consumers fill:#c8e6c9,stroke:#2e7d32,stroke-width:2px
```

#### Pros

**1. Ultimate Decoupling**

* Producers don't know about consumers
* Consumers don't know about producers
* Services can be added/removed without changes
* Natural extensibility

<Note>
  Tuturuuu uses **Trigger.dev v4** (`@trigger.dev/sdk` `^4.4.5`). The v4 API is built around `task()` with a typed `run` function, triggered with `myTask.trigger(payload)` or fanned out with `batchTrigger(...)`. The older v2 `client.defineJob` / `eventTrigger` / `trigger.event` API is **not** used in this repo. Real tasks live in `packages/trigger/src` (for example `scheduleTask`, `unifiedScheduleTask`, `googleCalendarFullSync`).
</Note>

**Example (Trigger.dev v4 `task()`):**

```typescript theme={null}
import { task } from '@trigger.dev/sdk/v3';

// Consumer 1: Send welcome email — a standalone task
export const sendWelcomeEmail = task({
  id: 'send-welcome-email',
  run: async (payload: { ownerId: string }) => {
    await sendEmail(payload.ownerId);
  },
});

// Consumer 2: Setup analytics — added later, no producer change
export const setupAnalytics = task({
  id: 'setup-analytics',
  run: async (payload: { workspaceId: string }) => {
    await trackWorkspace(payload.workspaceId);
  },
});

// Consumer 3: AI onboarding — added even later, still independent
export const aiOnboarding = task({
  id: 'ai-onboarding',
  run: async (payload: { workspaceId: string }) => {
    await setupAI(payload.workspaceId);
  },
});

// Producer: fan out to each task when a workspace is created.
// Each task runs independently; new tasks can be added without
// touching this call site beyond adding a new trigger.
async function onWorkspaceCreated(workspaceId: string, ownerId: string) {
  await Promise.all([
    sendWelcomeEmail.trigger({ ownerId }),
    setupAnalytics.trigger({ workspaceId }),
    aiOnboarding.trigger({ workspaceId }),
  ]);
}
```

<Note>
  Trigger.dev v4 dispatches by **task id**, so the producer references each task explicitly rather than publishing to a named topic. To get topic-style fan-out where a producer is fully unaware of consumers, pair Trigger.dev with a database table, Supabase Realtime channel, or a dedicated dispatcher task that decides which downstream tasks to trigger.
</Note>

**2. Natural Resilience**

* Broker acts as buffer for failures
* If consumer is down, events are persisted
* Automatic retry mechanisms
* Temporal decoupling (producer doesn't wait)

**3. Asynchronous Processing**

* Producers don't block on consumers
* Fast response times for users
* Long-running operations don't slow down requests
* Better resource utilization

**4. Audit Trail and Debugging**

* Complete history of events
* Can replay events for debugging
* Natural audit log
* Time-travel debugging possible

**5. Extensibility**

* Add new features by adding new consumers
* No changes to existing services
* Supports A/B testing (run old and new consumers in parallel)
* Safe experimentation

#### Cons

**1. Eventual Consistency**

* No immediate consistency guarantees
* System state converges over time
* Complex to reason about for developers
* Debugging race conditions is hard

**Example:**

```typescript theme={null}
// User creates workspace
await webService.createWorkspace(data);

// User immediately tries to access analytics
// Problem: Analytics consumer may not have processed event yet
const analytics = await analyticsService.getWorkspaceAnalytics(workspaceId);
// May return null because event hasn't been processed yet!
```

**2. Increased Complexity**

* Need to manage event broker infrastructure
* Event schema versioning is critical
* Debugging distributed event flows is difficult
* Monitoring and observability are essential

**3. Event Schema Management**

* Breaking changes to events affect all consumers
* Need careful versioning strategy
* Documentation of event schemas is critical
* Contract testing is mandatory

**4. No Immediate Responses**

* Can't return result from consumer to producer
* Must poll or use separate response events
* Complex request-response patterns
* Not suitable for all workflows

**5. Potential for Event Storms**

* Cascading events can amplify load
* Event loops are possible
* Need circuit breakers and rate limiting
* Monitoring for event accumulation essential

#### When to Use

✅ **Highly decoupled microservices** architecture
✅ **Asynchronous workflows** dominate
✅ **Need to add features** without modifying existing services
✅ **Audit trail** and event sourcing needed
✅ **Variable load** that benefits from buffering
✅ **Long-running operations** that can be async

#### When to Avoid

❌ **Strong consistency** is critical
❌ **Immediate responses** always needed
❌ **Simple request-response** patterns dominate
❌ **Team lacks event-driven experience**
❌ **Debugging complexity** is unacceptable
❌ **Real-time guarantees** are essential

**In Tuturuuu**: Trigger.dev v4 runs background and scheduled work — calendar sync, task scheduling, and similar jobs in `packages/trigger/src` — rather than serving as a full cross-service event bus. It is not the primary request path; most product data flows synchronously through `packages/internal-api` helpers and REST `/api/v1` routes (and, increasingly, the Rust `apps/backend`). Treat broad "event broker between every service" framing as illustrative.

***

## Comprehensive Comparison Matrix

| Pattern              | Scope         | Complexity  | Testability | Scalability | Team Size | Technology Flexibility | Best For               |
| -------------------- | ------------- | ----------- | ----------- | ----------- | --------- | ---------------------- | ---------------------- |
| **N-Tier**           | Internal      | Low         | Poor        | Limited     | Small     | Low                    | Simple CRUD apps       |
| **Hexagonal**        | Internal      | Medium      | Excellent   | N/A         | Any       | High                   | Complex business logic |
| **Clean**            | Internal      | Medium-High | Excellent   | N/A         | Any       | High                   | DDD applications       |
| **Onion**            | Internal      | Medium      | Excellent   | N/A         | Any       | High                   | Domain-centric apps    |
| **Monolith**         | External      | Low         | Easy        | Limited     | Small     | Low                    | Small applications     |
| **Modular Monolith** | External      | Medium      | Easy        | Limited     | Medium    | Low                    | Growing applications   |
| **Microservices**    | External      | High        | Moderate    | Excellent   | Large     | Very High              | Large, complex systems |
| **Event-Driven**     | Communication | High        | Moderate    | Excellent   | Large     | High                   | Decoupled services     |

***

## Decision Framework

### Choosing Internal Patterns

```mermaid theme={null}
graph TD
    Start["Internal<br/>Pattern Choice"]

    Start --> Q1{"Complex<br/>business logic?"}
    Q1 -->|No| NTier["N-Tier<br/>Architecture"]
    Q1 -->|Yes| Q2{"Long-term<br/>project?"}

    Q2 -->|No| NTier
    Q2 -->|Yes| Q3{"Team knows<br/>DDD?"}

    Q3 -->|No| Training["Provide<br/>training"]
    Q3 -->|Yes| Q4{"Prefer explicit<br/>layers?"}
    Training --> Q4

    Q4 -->|Yes| Clean["Clean<br/>Architecture"]
    Q4 -->|No| Hexagonal["Hexagonal<br/>Architecture"]

    style NTier fill:#ffcdd2,stroke:#c62828,stroke-width:2px
    style Clean fill:#c8e6c9,stroke:#2e7d32,stroke-width:2px
    style Hexagonal fill:#c8e6c9,stroke:#2e7d32,stroke-width:2px
```

### Choosing External Patterns

```mermaid theme={null}
graph TD
    Start["External<br/>Pattern Choice"]

    Start --> Q1{"Team size?"}
    Q1 -->|"&lt;10"| Monolith["Monolith"]
    Q1 -->|"10-50"| Q2{"Need clear<br/>boundaries?"}
    Q1 -->|"&gt;50"| Microservices["Microservices"]

    Q2 -->|No| Monolith
    Q2 -->|Yes| ModMono["Modular<br/>Monolith"]

    Microservices --> Q3{"Services need<br/>tight coupling?"}
    Q3 -->|No| EDA["Event-Driven<br/>Architecture"]
    Q3 -->|Yes| SyncMS["Microservices with<br/>Synchronous Calls"]

    style Monolith fill:#fff3e0,stroke:#f57c00,stroke-width:2px
    style ModMono fill:#fff3e0,stroke:#f57c00,stroke-width:2px
    style Microservices fill:#c8e6c9,stroke:#2e7d32,stroke-width:2px
    style EDA fill:#c8e6c9,stroke:#2e7d32,stroke-width:3px
```

***

## Tuturuuu's Architectural Decisions

Tuturuuu uses a **combination of patterns**, applying each where it provides the most value. The descriptions below reflect the real codebase as of mid-2026; the patterns are applied pragmatically, not dogmatically.

<Note>
  **Active migration**: The frontend and backend architecture is mid-transition. `apps/web` (Next.js, port `7803`) is being replaced by `apps/tanstack-web` (TanStack Start) plus a dedicated Rust backend, `apps/backend` (port `7820`). Decisions described here as current truth are subject to that migration — see [TanStack Start And Rust Migration](/platform/architecture/tanstack-rust-migration) for the authoritative contract.
</Note>

### Deployment: Many Independently Deployable Apps

**Decision**: Split the product surface into separate deployable apps (`web`, `finance`, `calendar`, `nova`, and more) that scale independently

**Reality and caveats**:

* Multiple domains (AI, Finance, Calendar, Tasks) live as distinct apps in the monorepo
* Apps deploy and scale independently, which gives microservice-like operational benefits
* They share a **single Supabase project** rather than per-service databases, so this is not a textbook "database-per-service" microservices topology
* Most apps share the same Next.js stack; the Rust `apps/backend` is the main technology-diversity example

### Background Work: Trigger.dev v4 Tasks

**Decision**: Run asynchronous and scheduled work as Trigger.dev v4 `task()` definitions in `packages/trigger/src`

**Justification**:

* Long-running and scheduled jobs (calendar sync, task scheduling) should not block request handling
* Built-in retries, concurrency controls, and queues add resilience
* This is background processing, not a general cross-service event bus; synchronous flows use `packages/internal-api` helpers and REST `/api/v1` routes

### Internal Code Organization: Conventional Next.js Layering

**Decision**: Organize each app as a conventional Next.js App Router project (`app/`, `components/`, `lib/`, `utils/`), extracting shared logic into `packages/*`

**Reality and caveats**:

* The apps do **not** implement formal hexagonal/clean/onion layering (no `domain/`, `application/`, `infrastructure/` directories)
* Reuse and isolation come from shared workspace packages (`packages/internal-api`, `packages/utils`, `packages/ui`, `packages/types`), not a strict ports-and-adapters hexagon
* Hexagonal/clean principles are an aspirational reference for unusually complex domains rather than an enforced rule

### Frontend: Modular Monolith

**Decision**: The web frontend is a modular monolith with convention-based module boundaries

**Justification**:

* Single deployment per frontend app simplifies operations
* Feature folders (Finance, Calendar, Tasks) provide organizational clarity
* The successor `apps/tanstack-web` keeps the same modular approach using TanStack Router route trees

***

## Related Documentation

* [Layering Patterns](/platform/architecture/system-design/layering-patterns) - Detailed comparison of N-Tier vs Hexagonal
* [Architectural Decisions](/platform/architecture/system-design/architectural-decisions) - Core architectural choices in Tuturuuu
* [Hexagonal Architecture](/platform/architecture/system-design/hexagonal-architecture) - Implementation details
* [Microservices Patterns](/platform/architecture/system-design/microservices-patterns) - Service boundaries and communication
* [Event-Driven Architecture](/platform/architecture/system-design/event-driven-architecture) - Event streaming patterns


# Encapsulation Patterns
Source: https://docs.tuturuuu.com/platform/architecture/system-design/encapsulation-patterns

Strategies for preventing unwanted communication within and between services in Tuturuuu's architecture

Encapsulation is a critical architectural quality that prevents unwanted coupling and maintains clear boundaries. This document covers patterns for preventing unwanted communication both **within an app** (cross-layer) and **between apps** (cross-service).

<Info>
  For a comprehensive comparison of how different architectural patterns handle encapsulation, see [Architectural Patterns Comparison](/platform/architecture/system-design/architectural-patterns-comparison).
</Info>

<Warning>
  **How to read this page.** The cross-layer hexagonal examples below
  (`domain/`, `application/`, `infrastructure/` directories, `WorkspaceRepository`
  ports, rich `Workspace` domain models) are **illustrative teaching patterns**,
  not a description of the current codebase. Tuturuuu apps are conventional
  **Next.js App Router** trees: `apps/web/src` contains `app/`, `components/`,
  `features/`, `hooks/`, `lib/`, and `utils/` — there is no
  `domain/`/`application/`/`infrastructure/` layering and no separate ports/adapters
  package. Likewise, apps communicate primarily through a **shared Supabase
  database** plus **Trigger.dev v4** background tasks, not through a broker with
  event ACLs. Each "in Tuturuuu" snippet below is marked as either *real* or
  *illustrative*. Treat the illustrative ones as design inspiration you could adopt,
  not as files that exist today.
</Warning>

<Note>
  **Migration in progress.** `apps/web` (Next.js, port 7803) is being replaced by
  `apps/tanstack-web` (TanStack Start) plus `apps/backend` (Rust, port 7820). The
  encapsulation principles here remain valid across both stacks, but treat any
  `apps/web`-specific path as legacy-or-current rather than permanent. See
  [TanStack Start and Rust Migration](/platform/architecture/tanstack-rust-migration).
</Note>

## Preventing Cross-Layer Communication (Inside an App)

Even without formal hexagonal layering, an app benefits from clear internal
boundaries that prevent tight coupling. The patterns below show how dependency
inversion, DTOs, and layered responsibility *could* be applied; where Tuturuuu
already does something equivalent (RLS, package boundaries, `internal-api`
helpers), that is called out as *real*.

### 1. The Dependency Inversion Principle (via Ports)

<Info>
  **Illustrative pattern.** The ports/adapters file paths below
  (`packages/types/src/domain/*`, `apps/web/src/domain/*`,
  `apps/web/src/infrastructure/*`) **do not exist** in the repo today and are shown
  purely to teach the dependency inversion principle. `packages/types/src` exposes
  flat modules (`db.ts`, `index.ts`, `supabase.ts`, `sdk.ts`, …) with no `domain/`
  directory.
</Info>

High-level business logic can define interfaces ("Ports") it requires, and
low-level infrastructure (like database code) implements them.

**Architectural Principle:** High-level modules should not depend on low-level modules. Both should depend on abstractions.

**Illustrative example:**

```typescript theme={null}
// Hypothetical domain layer defines interface (PORT)
// e.g. packages/types/src/domain/workspace.ts (does not exist today)
export interface WorkspaceRepository {
  findById(id: string): Promise<Workspace | null>;
  findByOwnerId(ownerId: string): Promise<Workspace[]>;
  save(workspace: Workspace): Promise<void>;
  delete(id: string): Promise<void>;
}

// Business logic depends on abstraction, NOT concrete implementation
// e.g. apps/web/src/domain/services/workspace-service.ts (illustrative path)
export class WorkspaceService {
  constructor(
    private readonly repository: WorkspaceRepository  // Depends on interface
  ) {}

  async createWorkspace(ownerId: string, name: string): Promise<Workspace> {
    const workspace = new Workspace(ownerId, name);

    // Domain logic doesn't know about Supabase, PostgreSQL, etc.
    await this.repository.save(workspace);

    return workspace;
  }
}

// Infrastructure layer implements interface (ADAPTER)
// e.g. apps/web/src/infrastructure/repositories/supabase-workspace-repository.ts (illustrative path)
export class SupabaseWorkspaceRepository implements WorkspaceRepository {
  constructor(private readonly supabase: SupabaseClient) {}

  async findById(id: string): Promise<Workspace | null> {
    const { data } = await this.supabase
      .from('workspaces')
      .select('*')
      .eq('id', id)
      .single();

    return data ? this.toDomainModel(data) : null;
  }

  async save(workspace: Workspace): Promise<void> {
    await this.supabase
      .from('workspaces')
      .upsert(this.toDatabaseModel(workspace));
  }

  // ... other methods
}
```

**Benefits:**

* Domain logic is **pure** and **testable** without infrastructure
* Can **swap implementations** (Supabase → Drizzle → Prisma) without changing business logic
* **Inversion of control** - domain doesn't depend on infrastructure
* **Technology agnostic** core business logic

**Clarifying Additions:** This enforces a clean separation that preserves the integrity of business rules. Infrastructure choices become replaceable rather than deeply embedded. The architecture stays flexible as technical needs evolve.

**"Anti-pattern" — but also how Tuturuuu actually writes code today:**

```typescript theme={null}
// In the hexagonal sense this "couples business logic to Supabase".
// In practice this IS the current Tuturuuu pattern: route handlers and
// server components call the Supabase client directly.
import { createClient } from '@tuturuuu/supabase/next/server';

export async function createWorkspace(ownerId: string, name: string) {
  // NOTE: createClient() from @tuturuuu/supabase/next/server is ASYNC — await it.
  // (createAdminClient() is synchronous; createDynamicClient() is async.)
  const supabase = await createClient();

  const { data } = await supabase
    .from('workspaces')
    .insert({ owner_id: ownerId, name })
    .select()
    .single();

  return data;
}
```

The hexagonal critique (harder to unit-test, technology lock-in) is real, but
Tuturuuu deliberately accepts direct Supabase access for app/API code and relies
on **Row-Level Security**, **shared `@tuturuuu/supabase` wrappers**, and
**`packages/internal-api` helpers** for boundaries instead of a ports/adapters
layer. Adopt the repository pattern only where a unit of logic genuinely needs to
be storage-agnostic or heavily unit-tested.

***

### 2. Strict Data Transfer Objects (DTOs)

The outer API layer of a service communicates with its inner Application layer using plain DTOs. This creates a strong boundary that prevents internal, behavior-rich Domain Models from being exposed to external layers, ensuring the core logic remains fully encapsulated.

**Architectural Principle:** External layers communicate via simple data structures, not rich domain objects.

<Info>
  **Illustrative pattern.** The rich `Workspace` domain class and
  `apps/web/src/domain/models/workspace.ts` path are illustrative. Real
  `apps/web` API routes work with plain objects and generated DB row types from
  `@tuturuuu/types/db`, not behavior-rich domain entities. The DTO discipline (keep
  HTTP request/response shapes separate from internal models, serialize dates as
  ISO strings) is still worth applying.
</Info>

**Illustrative example:**

```typescript theme={null}
// API layer DTO (external contract)
// e.g. apps/web/src/app/api/workspaces/create/route.ts
interface CreateWorkspaceRequest {
  name: string;
  description?: string;
}

interface CreateWorkspaceResponse {
  id: string;
  name: string;
  ownerId: string;
  createdAt: string;  // Serialized as ISO string
}

export async function POST(request: Request) {
  const body: CreateWorkspaceRequest = await request.json();

  // Convert DTO to domain command
  const command = new CreateWorkspaceCommand(
    userId,
    body.name,
    body.description
  );

  // Execute in domain
  const workspace = await workspaceService.execute(command);

  // Convert domain model back to DTO
  const response: CreateWorkspaceResponse = {
    id: workspace.id,
    name: workspace.name,
    ownerId: workspace.ownerId,
    createdAt: workspace.createdAt.toISOString()  // Domain Date → DTO string
  };

  return Response.json(response);
}

// Domain model (internal, rich behavior) — illustrative; no such file exists today
// e.g. apps/web/src/domain/models/workspace.ts
export class Workspace {
  constructor(
    public readonly id: string,
    public readonly ownerId: string,
    private _name: string,
    private _isActive: boolean,
    public readonly createdAt: Date
  ) {}

  // Rich domain behavior
  rename(newName: string) {
    if (newName.length < 3) {
      throw new DomainError('Workspace name must be at least 3 characters');
    }
    this._name = newName;
  }

  activate() {
    if (this._isActive) {
      throw new DomainError('Workspace is already active');
    }
    this._isActive = true;
  }

  deactivate() {
    this._isActive = false;
  }

  get name() {
    return this._name;
  }

  get isActive() {
    return this._isActive;
  }
}
// Domain model NEVER exposed to API layer
// API only sees DTOs
```

**Benefits:**

* **Encapsulation** of domain behavior
* **Clear boundaries** between layers
* **API stability** - internal changes don't break API contract
* **Serialization control** - DTOs are JSON-friendly
* **Versioning** - can support multiple DTO versions

**Clarifying Additions:** Interfaces clarify what the domain requires without exposing internal structures. This allows external systems to interact without knowing implementation details. Such boundaries minimize coupling between layers.

**Anti-pattern to avoid:**

```typescript theme={null}
// BAD: Exposing domain model directly
export async function POST(request: Request) {
  const workspace = await workspaceService.create(data);

  // WRONG: Returning domain model directly
  return Response.json(workspace);
}
// Problems:
// - Domain behavior exposed (rename, activate methods in JSON)
// - Date objects don't serialize correctly
// - Internal structure leaked to external API
// - Can't evolve domain without breaking API
```

***

### 3. Explicit Layered Responsibility

The architecture enforces a clear separation of concerns. The **Presentation layer** handles HTTP, the **Application layer** orchestrates workflows, and the **Domain layer** contains pure business logic. This clarity prevents logic from being misplaced and ensures layers only interact through their well-defined public interfaces.

**Architectural Principle:** Each layer has a single, well-defined responsibility and communicates only through defined interfaces.

**Actual `apps/web/src` structure (real):**

```
apps/web/src/
├── app/            # Next.js App Router: pages, layouts, and api/ route handlers
├── components/     # Shared React components for this app
├── features/       # Feature-scoped UI + logic
├── hooks/          # React hooks
├── lib/            # App-level helpers and clients
├── utils/          # Cross-cutting utilities
├── context/        # React context providers
├── data/           # Static/seed data
├── trpc/           # Local tRPC stub (healthCheck only — not a product data layer)
└── i18n/           # Localization config
```

There is **no** `application/`, `domain/`, or `infrastructure/` directory. Cross-app
product data flows through the **shared Supabase database** and
**`packages/internal-api`** helpers calling REST `/api/v1` routes — not through a
ports/adapters layer.

**Illustrative hexagonal structure** (what an explicitly layered service *could*
look like — not present today):

```
src/
├── app/                          # Presentation Layer (HTTP) — real today
│   └── api/workspaces/create/route.ts
├── application/                  # Application Layer (Orchestration) — illustrative
│   └── use-cases/create-workspace.ts
├── domain/                       # Domain Layer (Business Logic) — illustrative
│   ├── models/workspace.ts
│   └── services/workspace-service.ts
└── infrastructure/               # Infrastructure Layer (Technical) — illustrative
    └── repositories/supabase-workspace-repository.ts
```

**Illustrative example with clear layer responsibilities:**

```typescript theme={null}
// PRESENTATION LAYER: HTTP concerns only
// apps/web/src/app/api/workspaces/create/route.ts
export async function POST(request: Request) {
  // 1. HTTP handling (validation, auth)
  const session = await getSession();
  if (!session) {
    return Response.json({ error: 'Unauthorized' }, { status: 401 });
  }

  const body = await request.json();

  // Validate input schema
  const validation = CreateWorkspaceSchema.safeParse(body);
  if (!validation.success) {
    return Response.json({ error: validation.error }, { status: 400 });
  }

  // 2. Delegate to application layer
  const useCase = new CreateWorkspaceUseCase(
    workspaceRepository,
    eventPublisher
  );

  try {
    const workspace = await useCase.execute({
      ownerId: session.userId,
      name: validation.data.name,
      description: validation.data.description
    });

    // 3. HTTP response
    return Response.json({ workspace }, { status: 201 });
  } catch (error) {
    return Response.json({ error: error.message }, { status: 500 });
  }
}

// APPLICATION LAYER: Workflow orchestration
// apps/web/src/application/use-cases/create-workspace.ts
export class CreateWorkspaceUseCase {
  constructor(
    private readonly repository: WorkspaceRepository,
    private readonly eventPublisher: EventPublisher
  ) {}

  async execute(command: CreateWorkspaceCommand): Promise<Workspace> {
    // 1. Create domain entity
    const workspace = Workspace.create(
      command.ownerId,
      command.name,
      command.description
    );

    // 2. Persist
    await this.repository.save(workspace);

    // 3. Publish domain event
    await this.eventPublisher.publish(
      new WorkspaceCreatedEvent(workspace.id, workspace.ownerId)
    );

    return workspace;
  }
}

// DOMAIN LAYER: Pure business logic
// apps/web/src/domain/models/workspace.ts
export class Workspace {
  static create(
    ownerId: string,
    name: string,
    description?: string
  ): Workspace {
    // Business rules
    if (name.length < 3 || name.length > 50) {
      throw new DomainError('Workspace name must be 3-50 characters');
    }

    return new Workspace(
      generateId(),
      ownerId,
      name,
      description,
      true,  // isActive
      new Date()
    );
  }

  // No HTTP, no database, no events - pure domain logic
}
```

**Layer Communication Rules:**

| From Layer     | Can Call                | Cannot Call                               | Reason                 |
| -------------- | ----------------------- | ----------------------------------------- | ---------------------- |
| Presentation   | Application             | Domain directly                           | Bypass orchestration   |
| Application    | Domain, Infrastructure  | Presentation                              | Circular dependency    |
| Domain         | Nothing                 | Application, Infrastructure, Presentation | Pure logic             |
| Infrastructure | Domain (via interfaces) | Application, Presentation                 | Implementation details |

**Benefits:**

* **Clear responsibility** per layer
* **Easy to reason about** where code belongs
* **Testability** - each layer tested independently
* **Maintainability** - changes confined to appropriate layer

**Clarifying Additions:** This keeps the heart of the system stable despite environmental changes. The domain stays consistent across different execution contexts. This significantly boosts reliability and predictability.

**Anti-pattern to avoid:**

```typescript theme={null}
// BAD: Mixed responsibilities
export async function POST(request: Request) {
  const body = await request.json();

  // WRONG: Business logic in API layer
  if (body.name.length < 3) {
    return Response.json({ error: 'Name too short' }, { status: 400 });
  }

  // WRONG: Direct database access from API layer
  const { data } = await supabase
    .from('workspaces')
    .insert({ name: body.name });

  // WRONG (and outdated API): firing a background task inline with no structure.
  // In Trigger.dev v4 you trigger a defined task, e.g.:
  //   await myTask.trigger({ workspaceId: data.id });
  // (Trigger.dev v2 APIs like trigger.event/client.defineJob do not exist in this repo.)

  return Response.json(data);
}
// Problems:
// - Business rules scattered across codebase
// - No single source of truth for validation
// - Hard to test
// - Difficult to change
```

***

## Preventing Unwanted Cross-Service Communication (Between Apps)

<Warning>
  **Reality check.** Tuturuuu apps do **not** communicate exclusively through
  published events, and there is **no broker-level event ACL**. The current primary
  inter-app pattern is a **shared Supabase (PostgreSQL) database** with Row-Level
  Security, complemented by **Trigger.dev v4** tasks for asynchronous/background
  work. This matches the
  [Microservices Patterns](/platform/architecture/system-design/microservices-patterns)
  page, which lists "Shared Database (Current)" as the live pattern. The
  event-as-sole-interface material below is therefore an **aspirational pattern**
  showing the encapsulation benefits a fully event-driven design would provide —
  not the way the apps interact today.
</Warning>

### 1. Background Tasks as a Decoupling Boundary

When one app needs to kick off work in another context without a synchronous
dependency, Tuturuuu uses **Trigger.dev v4 `task()`** definitions in
`packages/trigger/src`. A trigger payload acts as a small, explicit contract: the
caller passes only what the task needs, and the task does not reach back into the
caller's internals.

**Architectural Principle:** Cross-context work is dispatched via explicit task payloads, not by calling another app's private functions.

**Real example (Trigger.dev v4):**

```typescript theme={null}
// packages/trigger/src/schedule-tasks.ts (real, abridged)
import { task } from '@trigger.dev/sdk/v3';
import { schedulableTasksHelper } from './schedule-tasks-helper';

export const scheduleTask = task({
  id: 'schedule-task',
  queue: { concurrencyLimit: 10 },
  // The payload is the entire contract this task depends on.
  run: async (payload: { ws_id: string }) => {
    const result = await schedulableTasksHelper(payload.ws_id);
    if (!result.success) {
      throw new Error(result.error || 'Schedule tasks failed');
    }
    return { ws_id: payload.ws_id, ...result, success: true };
  },
});
```

```typescript theme={null}
// Dispatching the task from app code (Trigger.dev v4):
import { scheduleTask } from '@tuturuuu/trigger';

// Fire-and-forget; returns a run handle, does not block on completion.
await scheduleTask.trigger({ ws_id: workspaceId });
```

<Note>
  The import path is `@trigger.dev/sdk/v3` even though the installed package is
  `@trigger.dev/sdk@^4.4.5` — the `/v3` subpath is the v4 SDK's stable entrypoint
  for `task()`. The Trigger.dev **v2** APIs referenced in older drafts
  (`client.defineJob`, `eventTrigger`, `io.runTask`, `trigger.event`) **do not
  exist** in this repo.
</Note>

***

### 2. (Aspirational) Published Event Contracts as the Sole Interface

In a fully event-driven design, the only way services interact is through the
events they publish; internal implementation, database schema, and private
functions stay **completely hidden**. Tuturuuu does **not** implement this today
(apps share a database), but the pattern is the strongest form of cross-service
encapsulation and is worth understanding.

**Architectural Principle:** Services communicate only via well-defined event contracts.

**Aspirational example (expressed in real Trigger.dev v4 syntax):**

```typescript theme={null}
// Producer side: instead of a v2 trigger.event(...) broadcast,
// dispatch a typed task with an explicit payload contract.
import { setupAiWorkspaceTask } from '@tuturuuu/trigger';

export async function createWorkspace(data: CreateWorkspaceData) {
  const supabase = await createClient(); // async client — await it
  const { data: workspace } = await supabase
    .from('workspaces')
    .insert(data)
    .select()
    .single();

  // Public contract = the task payload shape, nothing more.
  await setupAiWorkspaceTask.trigger({
    workspaceId: workspace.id,
    ownerId: workspace.owner_id,
  });
}

// Consumer side (Trigger.dev v4): a task() definition, not client.defineJob.
import { task } from '@trigger.dev/sdk/v3';

export const setupAiWorkspaceTask = task({
  id: 'setup-ai-workspace',
  run: async (payload: { workspaceId: string; ownerId: string }) => {
    // Only knows about the payload contract, not the producer's internals.
    return await createAIConfig(payload);
  },
});
```

**Event Schema Governance (aspirational):**

```typescript theme={null}
// Illustrative: e.g. packages/types/src/events/workspace.ts (no such file today)
import { z } from 'zod';

// Versioned schemas keep payload contracts backward compatible.
export const WorkspaceCreatedEventV1 = z.object({
  workspaceId: z.string().uuid(),
  ownerId: z.string().uuid(),
  name: z.string().min(1).max(100),
  createdAt: z.string().datetime()
});

export const WorkspaceCreatedEventV2 = z.object({
  workspaceId: z.string().uuid(),
  ownerId: z.string().uuid(),
  name: z.string().min(1).max(100),
  createdAt: z.string().datetime(),
  // New optional fields (backward compatible)
  description: z.string().optional(),
  plan: z.enum(['free', 'pro', 'enterprise']).optional()
});

export type WorkspaceCreatedEventV1 = z.infer<typeof WorkspaceCreatedEventV1>;
export type WorkspaceCreatedEventV2 = z.infer<typeof WorkspaceCreatedEventV2>;
```

**Benefits:**

* **Complete encapsulation** of service internals
* **Clear API contract** via event schemas
* **Versioning support** for evolution
* **Independent deployment** of services
* **No direct dependencies** between services

**Clarifying Additions:** Clients remain simple and unaffected by internal changes. Service boundaries stay intact because external access is tightly controlled. This enforces a clean separation between client-facing and internal concerns.

**Anti-pattern to avoid:**

```typescript theme={null}
// BAD: Direct service-to-service HTTP calls
export async function createWorkspace(data: CreateWorkspaceData) {
  const workspace = await db.workspaces.insert(data);

  // WRONG: Direct HTTP call to another service
  await fetch('http://rewise-service/api/setup', {
    method: 'POST',
    body: JSON.stringify({ workspaceId: workspace.id })
  });

  // Problems:
  // - Tight coupling to rewise-service
  // - Must know its URL and API
  // - Synchronous dependency (cascading failures)
  // - Hard to add new services
}
```

***

### 3. (Hypothetical) Broker-Level Access Control (ACLs)

<Warning>
  **Hypothetical pattern — not implemented.** There is **no message broker** and
  **no event ACL system** in Tuturuuu. The file `packages/trigger/src/events/acl.ts`
  and the `EVENT_PRODUCERS`/`EVENT_CONSUMERS` maps below **do not exist** —
  `packages/trigger/src` contains task definitions (`schedule-tasks.ts`,
  `google-calendar-sync.ts`, etc.), not an ACL layer. This section is kept only to
  illustrate what infrastructure-enforced boundaries would look like if Tuturuuu
  moved to a true event-driven broker.
</Warning>

In a broker-based design you would not rely on trust; the broker itself enforces
communication boundaries. Using ACLs you could declare that only one service may
produce `user.registered` events, and only specific downstream services may
consume them.

**Architectural Principle:** Enforce service boundaries at the infrastructure level, not just by convention.

**Hypothetical example (does not reflect repo code):**

```typescript theme={null}
// Hypothetical: packages/trigger/src/events/acl.ts (no such file exists)
export const EVENT_PRODUCERS = {
  'user.registered': ['apps/web'],
  'workspace.created': ['apps/web'],
  'payment.processed': ['apps/web', 'apps/finance'],
  'ai.chat.message': ['apps/rewise'],
  'task.created': ['apps/tasks']
} as const;

export const EVENT_CONSUMERS = {
  'user.registered': ['apps/rewise', 'apps/web', 'analytics-service'],
  'workspace.created': ['apps/rewise', 'apps/nova', 'apps/finance'],
  'payment.processed': ['apps/web', 'billing-service'],
  'ai.chat.message': ['apps/web'],
  'task.created': ['apps/web', 'apps/calendar']
} as const;

// Validation middleware
export function validateEventProducer(
  eventName: string,
  serviceId: string
): boolean {
  const allowedProducers = EVENT_PRODUCERS[eventName];
  if (!allowedProducers) {
    throw new Error(`Unknown event: ${eventName}`);
  }
  if (!allowedProducers.includes(serviceId)) {
    throw new Error(
      `Service ${serviceId} not allowed to produce ${eventName}`
    );
  }
  return true;
}
```

**Benefits:**

* **Enforced boundaries** at infrastructure level
* **Security** - services can't spoof events from other services
* **Audit trail** - know exactly which services produce/consume events
* **Documentation** - ACL config documents allowed communication

**Clarifying Additions:** This ensures services evolve internally without breaking others. External dependencies rely on stable contracts rather than hidden details. This strengthens overall modularity across the architecture.

***

### 4. Elimination of Synchronous Coupling

Dispatching background work asynchronously avoids direct, synchronous calls
between contexts for slow or non-critical flows. This prevents the tight coupling
that arises when one caller must know the network location, API signature, and
live availability of another. Tuturuuu applies this with **Trigger.dev v4** tasks:
the request returns immediately while follow-up work runs out of band.

**Architectural Principle:** Don't block a user request on slow, non-critical downstream work.

**Async flow (real Trigger.dev v4 syntax):**

```typescript theme={null}
import { createAdminClient } from '@tuturuuu/supabase/next/server';
import { setupUserAiTask, sendWelcomeEmailTask } from '@tuturuuu/trigger';

// apps/web: User registers
export async function registerUser(data: UserRegistrationData) {
  const supabase = createAdminClient(); // SYNC factory — do NOT await it
  const user = await createUser(supabase, data);

  // Dispatch background tasks (non-blocking); each returns a run handle.
  await setupUserAiTask.trigger({ userId: user.id });
  await sendWelcomeEmailTask.trigger({ email: user.email });

  return user;  // Returns immediately
}

// packages/trigger/src: each consumer is a task() definition.
import { task } from '@trigger.dev/sdk/v3';

export const setupUserAiTask = task({
  id: 'setup-user-ai',
  run: async (payload: { userId: string }) => {
    return await createAIProfile(payload.userId);
  },
});

export const sendWelcomeEmailTask = task({
  id: 'send-welcome-email',
  run: async (payload: { email: string }) => {
    return await sendEmail(payload.email, 'welcome');
  },
});

// Each task runs independently; registration never blocks on them.
```

**Benefits:**

* **No cascading failures**
* **Independent availability** of services
* **Faster user responses**
* **Easier to add new services**

**Clarifying Additions:** Controlled communication prevents accidental or unauthorized interactions. Service boundaries stay clear as the system grows. This improves safety and consistency in distributed communication.

**Anti-pattern to avoid:**

```typescript theme={null}
// BAD: Synchronous service-to-service calls
export async function registerUser(data: UserRegistrationData) {
  const user = await createUser(data);

  // WRONG: Blocking calls to other services
  await rewiseService.setupAI(user.id);        // 2 seconds
  await emailService.sendWelcome(user.email);  // 1 second
  await analyticsService.track(user.id);       // 1 second

  return user;  // User waits 4+ seconds
}
// Problems:
// - User waits for all services
// - If rewise service is down, registration fails
// - Tight coupling to multiple services
```

***

## Encapsulation in Practice

### Workspace Isolation via RLS (real)

This is Tuturuuu's actual primary encapsulation mechanism: because apps share one
Supabase database, **Row-Level Security** — defined by migrations under
`apps/database/supabase/migrations/` — keeps every app inside its permitted data
scope at the database level, regardless of which app issues the query.

```sql theme={null}
-- apps/database/supabase/migrations/
-- Row-Level Security ensures data encapsulation at database level
CREATE POLICY "Users can only see their workspaces"
ON workspaces
FOR SELECT
USING (
  id IN (
    SELECT workspace_id
    FROM workspace_members
    WHERE user_id = auth.uid()
  )
);

-- Services cannot access data outside their scope
-- Enforced at database level, not application level
```

### Package Boundaries (real)

Apps depend on shared `workspace:*` packages and never import another app's
internals. (Add or update these with scoped installs, e.g.
`cd apps/web && bun add <pkg>` — never `bun add --workspace`.)

```jsonc theme={null}
// apps/web/package.json (illustrative subset)
{
  "dependencies": {
    "@tuturuuu/ui": "workspace:*",        // ✅ Allowed
    "@tuturuuu/types": "workspace:*",     // ✅ Allowed
    "@tuturuuu/supabase": "workspace:*"   // ✅ Allowed
    // ❌ Do not import from apps/rewise or apps/finance directly
  }
}
```

## Summary

Status legend: **real** = implemented today; **illustrative/aspirational** =
teaching pattern not implemented in the repo.

| Encapsulation Type           | Pattern                           | Status       | Enforced By                             | Benefit                |
| ---------------------------- | --------------------------------- | ------------ | --------------------------------------- | ---------------------- |
| **Cross-Layer (Internal)**   | Dependency Inversion / ports      | Illustrative | Hexagonal layering (not adopted)        | Testable, flexible     |
| **Cross-Layer (Internal)**   | DTOs                              | Illustrative | Layer boundaries                        | Stable APIs            |
| **Cross-Layer (Internal)**   | Layered Responsibility            | Illustrative | Directory structure (apps/web is flat)  | Clear organization     |
| **Cross-Layer (Internal)**   | Row-Level Security                | Real         | Supabase RLS policies                   | Data scoping at the DB |
| **Cross-Layer (Internal)**   | Package boundaries                | Real         | `workspace:*` deps + Biome/import rules | No cross-app imports   |
| **Cross-Service (External)** | Background task payloads          | Real         | Trigger.dev v4 `task()`                 | Async decoupling       |
| **Cross-Service (External)** | Event Contracts as sole interface | Aspirational | Event schemas                           | Service autonomy       |
| **Cross-Service (External)** | Broker ACLs                       | Hypothetical | Broker config (no broker today)         | Security, governance   |
| **Cross-Service (External)** | Async background work             | Real         | Trigger.dev v4 tasks                    | No cascading failures  |

## Related Documentation

* [Layering Patterns](/platform/architecture/system-design/layering-patterns) - N-tier vs Hexagonal/Clean architecture comparison
* [Hexagonal Architecture](/platform/architecture/system-design/hexagonal-architecture) - Detailed ports and adapters pattern
* [Event-Driven Architecture](/platform/architecture/system-design/event-driven-architecture) - Event-based communication
* [Microservices Patterns](/platform/architecture/system-design/microservices-patterns) - Service boundaries
* [Authorization](/platform/architecture/authorization) - RLS policies and permissions


# Event-Driven Architecture
Source: https://docs.tuturuuu.com/platform/architecture/system-design/event-driven-architecture

Asynchronous, event-driven patterns in Tuturuuu: advantages, drawbacks, and how background work actually runs on Trigger.dev v4

Event-Driven Architecture (EDA) is a useful lens for the asynchronous,
fire-and-forget work in Tuturuuu — calendar syncs, auto-scheduling, and other
background jobs that should not block a user request. This document explains the
general advantages and drawbacks of EDA, then grounds each idea in how Tuturuuu
**actually** runs background work today: [Trigger.dev](https://trigger.dev) v4
tasks.

<Note>
  **Read this as patterns, not literal architecture.** Tuturuuu is not built on a
  Kafka-style event bus with an immutable event log, replayable streams, or
  dead-letter queues. It runs conventional Next.js apps that enqueue
  background **tasks** on Trigger.dev (a managed jobs platform) and persist state
  in a shared Supabase Postgres database. Sections below are labelled
  **Concept** (general EDA theory) or **In Tuturuuu** (verified against real
  code). Treat any capability not shown in real code as illustrative.
</Note>

<Info>
  **Active migration.** `apps/web` (Next.js, port `7803`) is being replaced by
  `apps/tanstack-web` (TanStack Start) plus `apps/backend` (Rust, port `7820`).
  Background-job ownership may shift during this transition — some asynchronous
  work that runs as a Trigger.dev task today may move into the Rust backend. See
  [TanStack + Rust Migration](/platform/architecture/tanstack-rust-migration).
  Nothing in this page is a permanent architectural commitment.
</Info>

## Overview

**Concept.** In a fully event-driven system, services communicate asynchronously
through events published to a central broker. Services are **producers**
(publishing events) and **consumers** (subscribing to and processing events),
with the broker handling delivery, persistence, and reliability.

```mermaid theme={null}
graph LR
    A[Producer<br/>API route] -->|enqueue task| B[Trigger.dev<br/>managed jobs]
    B -->|run| C[Task: calendar sync]
    B -->|run| D[Task: auto-schedule]
    B -->|fan out via task.trigger| E[Per-workspace tasks]

    style B fill:#4f46e5,stroke:#3730a3,color:#fff
```

**In Tuturuuu.** There is no central event bus. Instead:

* A request handler (an `apps/web` API route or a cron entrypoint) does its
  synchronous work and then **enqueues a Trigger.dev task** for follow-up work.
* Trigger.dev runs that task on its managed infrastructure, with retries,
  concurrency control, and queues.
* An "orchestrator" task can **fan out** by triggering one child task per
  workspace via `task.trigger(...)`.

The Trigger.dev tasks live in `packages/trigger/src` — for example
`google-calendar-sync.ts`, `google-calendar-full-sync.ts`,
`unified-schedule.ts`, and `schedule-tasks.ts`. They are defined with the
Trigger.dev v4 `task()` API (`@trigger.dev/sdk` `^4.4.5`), imported from the
`@trigger.dev/sdk/v3` entrypoint.

## Advantages of Event-Driven Design

### 1. Decoupling work from the request path

**Concept.** A producer publishes an event and is done; it does not know which
consumers react. This is the loosest possible coupling and lets you add or
remove downstream behavior without touching the producer.

**In Tuturuuu.** We get a pragmatic version of this: an API route finishes its
synchronous work, then **enqueues a task** instead of doing the slow work
inline. The route does not care how the task is implemented, and the task can
evolve independently.

```typescript theme={null}
// Conceptual: an API route enqueues background work instead of blocking.
// Real task definitions live in packages/trigger/src.
import { googleCalendarFullSync } from '@tuturuuu/trigger/google-calendar-full-sync';

export async function POST(request: Request) {
  const workspace = await createWorkspace(data);

  // Hand off slow work to Trigger.dev; the response returns immediately.
  await googleCalendarFullSync.trigger({
    ws_id: workspace.id,
    access_token,
    refresh_token,
  });

  return Response.json({ workspace });
}
```

**Benefits:**

* Keep user-facing requests fast by moving slow work off the request path.
* Change a task's internals without changing its callers.
* Add new background behavior by adding a new task, not by editing the producer.

<Note>
  Tuturuuu does **not** broadcast a single event to many anonymous subscribers.
  Callers explicitly enqueue named tasks. There is no event-name pub/sub fan-in
  layer between producer and consumer.
</Note>

***

### 2. Resilience through retries

**Concept.** A durable broker keeps events until a consumer processes them, so a
consumer outage does not lose work — it just delays it.

**In Tuturuuu.** Trigger.dev persists each enqueued task run and retries failed
runs on its managed infrastructure, so a transient failure (an expired Google
token, a flaky network call) does not silently drop the work. Tasks are written
to return a structured `{ success, error }` result and to log failures rather
than crash the caller.

```typescript theme={null}
// packages/trigger/src/schedule-tasks.ts (real task)
import { task } from '@trigger.dev/sdk/v3';
import { schedulableTasksHelper } from './schedule-tasks-helper';

export const scheduleTask = task({
  id: 'schedule-task',
  queue: {
    concurrencyLimit: 10,
  },
  run: async (payload: { ws_id: string }) => {
    try {
      const result = await schedulableTasksHelper(payload.ws_id);

      if (!result.success) {
        throw new Error(result.error || 'Schedule tasks failed');
      }

      return { ws_id: payload.ws_id, ...result, success: true };
    } catch (error) {
      console.error(`[${payload.ws_id}] Error in schedule task:`, error);
      return {
        ws_id: payload.ws_id,
        success: false,
        error: error instanceof Error ? error.message : 'Unknown error',
      };
    }
  },
});
```

**Benefits:**

* **No cascading failures**: the API route that enqueued the task is unaffected
  if the task fails.
* **Automatic retries**: Trigger.dev re-runs failed task runs.
* **Durability**: enqueued runs survive a worker restart.

<Note>
  **Concept, not implemented in Tuturuuu:** an immutable event log you can
  re-read from the beginning, plus dead-letter queues for permanently failed
  events. Trigger.dev retries and surfaces failed runs in its dashboard; our
  tasks additionally swallow errors into a structured result so an orchestrator
  can continue with the next workspace. There is no `*.dlq` wildcard trigger or
  DLQ topic in this repo.
</Note>

***

### 3. Scalability through concurrency control

**Concept.** Multiple consumer instances can process the same stream in
parallel, and the broker levels load by buffering spikes.

**In Tuturuuu.** Trigger.dev runs many task runs concurrently, and we cap that
concurrency per task with a `queue` so a burst of work cannot overwhelm shared
resources (Postgres, the Google Calendar API). An orchestrator fans out one
child run per workspace and gives each its own `concurrencyKey`.

```typescript theme={null}
// packages/trigger/src/google-calendar-full-sync.ts (real orchestrator, abridged)
export const googleCalendarFullSyncOrchestrator = task({
  id: 'google-calendar-full-sync-orchestrator',
  run: async () => {
    const workspaces = await getWorkspacesForSync();
    const results: SyncOrchestratorResult[] = [];

    for (const workspace of workspaces) {
      try {
        // Fan out: one child run per workspace, isolated by concurrencyKey.
        const handle = await googleCalendarFullSync.trigger(workspace, {
          concurrencyKey: `google-calendar-full-sync-${workspace.ws_id}`,
        });
        results.push({ ws_id: workspace.ws_id, handle, status: 'triggered' });
      } catch (error) {
        results.push({
          ws_id: workspace.ws_id,
          error: error instanceof Error ? error.message : 'Unknown error',
          status: 'failed',
        });
      }
    }

    return results;
  },
});
```

**Benefits:**

* **Bounded throughput**: `queue.concurrencyLimit` (e.g. `10` for
  `scheduleTask`, `5` for `unifiedScheduleTask`) protects shared dependencies.
* **Per-key isolation**: `concurrencyKey` keeps each workspace's runs from
  stepping on each other.
* **Spike absorption**: Trigger.dev queues work it cannot run immediately.

***

### 4. Temporal decoupling

**Concept.** With a persistent, replayable event log, a brand-new consumer can
read the entire history of events to bootstrap itself — useful for rebuilding
read models, training models, or running new analyses on past data.

<Warning>
  **This is the part Tuturuuu does not have.** There is no event-sourcing store
  and no "replay all events from launch" capability. Trigger.dev tasks are
  fire-and-run jobs, not an append-only event log. State of record lives in the
  shared Supabase Postgres database; to re-derive something, you query Postgres,
  you do not replay an event stream. Treat this section as EDA theory only.
</Warning>

If you genuinely need history-as-a-stream in the future, you would build it
explicitly (e.g. an append-only Postgres table plus a job that reads it) — it is
not a free property of the current stack.

***

## Drawbacks of Event-Driven Design

### 1. Harder to reason about and debug

**Concept.** Asynchronous, choreographed work has no single linear call stack, so
tracing "why did this fail?" spans multiple independent runs.

**In Tuturuuu.** The same trade-off applies the moment work moves off the request
path. A failing calendar sync does not show up in the API route's stack trace;
you find it in the Trigger.dev run logs. We lean on:

* The Trigger.dev dashboard for per-run logs, retries, and status.
* Structured `console.log`/`console.error` inside tasks, keyed by `ws_id`, so
  runs are correlatable.
* Returning a structured `{ ws_id, success, error }` result from each task so an
  orchestrator can report per-workspace outcomes.

<Note>
  There is no `@tuturuuu/logging` or `@tuturuuu/observability` package and no
  cross-service distributed-tracing system wired into these tasks today.
  Inside runtime code, use the native console method matching severity; the
  Trigger.dev tasks in `packages/trigger` log the same way to Trigger.dev run
  logs.
</Note>

***

### 2. Eventual consistency

**Concept.** Because processing is asynchronous, there is a delay between when
work is enqueued and when its effects are visible. The system is "eventually
consistent," and the UX must accommodate that.

**In Tuturuuu.** A calendar sync or auto-schedule run completes some time after
it is enqueued, so freshly triggered changes are not instantly reflected. Handle
this the way the rest of the platform does:

* **Optimistic UI** and **loading states** via TanStack Query while background
  work settles.
* Design flows so the user is not blocked waiting on a background task.

```typescript theme={null}
// Conceptual: enqueue, then let the UI reconcile when the task lands.
await unifiedScheduleManualTrigger.trigger({ ws_id, forceReschedule: true });
// The schedule updates in Postgres once the task finishes; the client
// re-fetches (TanStack Query) rather than blocking on the task result.
```

**Mitigation strategies:**

* Optimistic UI updates with background reconciliation.
* Clear loading/processing states.
* Read-your-own-writes via a direct query path when a value must be immediate.

***

### 3. Payload/schema governance

**Concept.** Event payloads become a contract between producer and consumer, so
schema evolution must be backward compatible or versioned.

**In Tuturuuu.** Each task's `payload` type is its contract. Because callers and
tasks live in the same monorepo and TypeScript checks both sides, breaking a
payload shape surfaces at type-check time rather than silently at runtime. Keep
payload changes additive (new optional fields) and validate untrusted input with
`zod` where a payload crosses a trust boundary.

```typescript theme={null}
// Real task payloads are plain typed objects, e.g.:
//   { ws_id: string }                                  // scheduleTask
//   { ws_id: string; windowDays?: number; forceReschedule?: boolean } // unifiedScheduleTask
//   { ws_id: string; access_token: string; refresh_token: string }    // full sync
//
// Prefer additive changes (new optional fields) so existing callers keep working.
```

**Mitigation strategies:**

* Additive payload changes only; avoid removing or retyping existing fields.
* Let the monorepo's shared types and `bun check` catch mismatches.
* Validate external/untrusted payloads with `zod`.

***

### 4. Operational dependency on the jobs platform

**Concept.** A central broker is critical infrastructure that must be operated,
tuned, and monitored.

**In Tuturuuu.** Using **managed Trigger.dev** removes most of that operational
burden — there is no broker to run. What remains is application-level care:

* Make task work **idempotent** where possible, since runs can retry.
* Set sane `queue.concurrencyLimit` values to protect Postgres and external APIs.
* Watch the Trigger.dev dashboard for failure rates and run latency.
* Keep secrets (e.g. `INTERNAL_TRIGGER_SECRET_KEY`,
  `GOOGLE_CLIENT_ID`/`GOOGLE_CLIENT_SECRET`) in environment variables, never in
  code.

**Mitigation strategies:**

* Managed platform (Trigger.dev) instead of self-hosting a broker.
* Idempotent, retry-safe task bodies.
* Concurrency limits and per-workspace `concurrencyKey`s.

***

## How Background Work Actually Runs in Tuturuuu

### Defining a task (Trigger.dev v4)

Tasks are defined with `task()` and exported from `packages/trigger/src`. The SDK
is `@trigger.dev/sdk` `^4.4.5`; tasks import `task` from `@trigger.dev/sdk/v3`.

```typescript theme={null}
// packages/trigger/src/unified-schedule.ts (real task, abridged)
import { task } from '@trigger.dev/sdk/v3';
import { unifiedScheduleHelper } from './unified-schedule-helper';

export const unifiedScheduleTask = task({
  id: 'unified-schedule-task',
  queue: {
    concurrencyLimit: 5, // Limit concurrent workspace scheduling
  },
  run: async (payload: {
    ws_id: string;
    windowDays?: number;
    forceReschedule?: boolean;
  }) => {
    const result = await unifiedScheduleHelper(payload.ws_id, {
      windowDays: payload.windowDays,
      forceReschedule: payload.forceReschedule,
    });

    if (!result.success) {
      throw new Error(result.error || 'Unified schedule failed');
    }

    return { ws_id: payload.ws_id, success: true, ...result.data };
  },
});
```

### Enqueuing and fanning out

Other code triggers a task by calling `.trigger(payload, options?)` on the
exported task. An orchestrator triggers one child run per workspace, isolating
each with a `concurrencyKey` (see `googleCalendarFullSyncOrchestrator` above).

```typescript theme={null}
const handle = await unifiedScheduleTask.trigger({ ws_id, forceReschedule: true });
```

### Scheduling

<Warning>
  Recurring **Calendar** scheduling does **not** live in `packages/trigger` as a
  `schedules.task` cron job. As documented in
  [the Trigger.dev package reference](/reference/packages/trigger), production
  Calendar scheduling runs through `apps/web` cron, which calls the internal
  `/api/<wsId>/calendar/auto-schedule` route (authenticated with
  `INTERNAL_TRIGGER_SECRET_KEY`). The `scheduleTask` /
  `unifiedScheduleTask` definitions here are wrappers kept for manual
  Trigger.dev runs and tests.
</Warning>

## When to Reach for Asynchronous (Event-Driven) Work

**Enqueue a background task when:**

* The work is slow and should not block the HTTP response (calendar sync, bulk
  processing, external-API fan-out).
* Eventual consistency is acceptable for the use case.
* Retries and bounded concurrency add real value.
* The work fans out across many workspaces or items.

**Do it synchronously instead when:**

* The caller needs the result immediately to return a response.
* The user is waiting in real time and cannot tolerate a delay.
* It is a simple CRUD operation with no slow side effects.
* The added indirection would only make debugging harder.

## Related Documentation

* [Architectural Decisions](/platform/architecture/system-design/architectural-decisions) — system-design trade-offs
* [Extensibility, Resilience & Scalability](/platform/architecture/system-design/extensibility-resilience-scalability) — these benefits in detail
* [Trigger.dev Package](/reference/packages/trigger) — the real task implementations and conventions
* [TanStack + Rust Migration](/platform/architecture/tanstack-rust-migration) — where background work is heading
* [Development Tools](/build/development-tools/overview) — local development and verification workflow


# Extensibility, Resilience & Scalability
Source: https://docs.tuturuuu.com/platform/architecture/system-design/extensibility-resilience-scalability

15 reasons why event-driven architecture prioritizes extensibility, resilience, and scalability

Event-driven architecture is fundamentally designed for evolution, stability, and growth. This document explores **15 key reasons** (5 for each property) why these qualities matter, and shows how Tuturuuu applies the practical subset of these patterns today.

<Info>
  To understand how different architectural patterns compare in terms of these quality attributes, see [Architectural Patterns Comparison](/platform/architecture/system-design/architectural-patterns-comparison).
</Info>

<Warning>
  **How to read this page.** The patterns below are general event-driven concepts. Tuturuuu is not a Kafka-style microservice mesh: the apps under `apps/` are conventional applications that share a single Supabase Postgres project, and asynchronous/background work runs on **[Trigger.dev v4](/reference/packages/trigger)** (`@trigger.dev/sdk` v4) using the `task()` API, not a self-managed broker with consumer groups or topic partitions. Code samples that use Trigger.dev show the real v4 `task()` shape; samples that describe broker primitives (partitions, DLQ topics, replay windows) are **conceptual pseudo-code** that illustrate the pattern rather than implemented Tuturuuu behavior. Each section calls out which is which.
</Warning>

<Note>
  **Active migration.** The legacy Next.js app (`apps/web`, port `7803`) is being replaced by `apps/tanstack-web` (TanStack Start) plus `apps/backend` (Rust, port `7820`). See [TanStack Start And Rust Migration](/platform/architecture/tanstack-rust-migration). The quality attributes below survive the migration; only the runtimes hosting them change.
</Note>

## Extensibility (5 Reasons)

The event-driven architecture is fundamentally designed for evolution and the seamless addition of new functionality.

### 1. The "Add a Consumer" Pattern (Open/Closed Principle)

To introduce new business functionality, you add a new handler that reacts to existing work rather than editing the existing code path. In Tuturuuu that handler is a new Trigger.dev task (and, conceptually in a broker-based system, a new consumer subscribed to an event stream).

**Example:** To add a fraud-detection capability, we can introduce a new Trigger.dev task that runs whenever a payment is attempted or fails, without modifying the code that initiates payments. In Trigger.dev v4, a task is a plain `task()` export; an upstream handler triggers it by name (`yourTask.trigger(payload)` / `tasks.trigger(...)`).

```typescript theme={null}
// NEW task - zero changes to the code that initiates payments
import { task, tasks } from '@trigger.dev/sdk/v3';

export const fraudDetection = task({
  id: 'fraud-detection',
  queue: { concurrencyLimit: 10 },
  run: async (payload: { paymentId: string; amount: number }) => {
    const riskScore = await analyzeFraudRisk(payload);

    if (riskScore > 0.8) {
      // Fan out to a follow-up task instead of a broker "sendEvent"
      await tasks.trigger('alert-fraud-team', { ...payload, riskScore });
    }

    return { paymentId: payload.paymentId, riskScore };
  },
});
```

The payment flow only adds a single `fraudDetection.trigger(...)` call (or none, if a shared dispatcher already fans out payment events). The existing charge logic is untouched.

**Benefits:**

* **Zero modification** to the payment logic
* **Independent deployment** of the fraud-detection task
* **No regression risk** to existing functionality
* **Team autonomy** - the fraud team works independently

**Clarifying Additions:** This ensures growth does not disrupt existing areas. New capabilities arrive as new components rather than modifications to old ones. This avoids large, risky refactors as the system expands.

***

### 2. Introduction of New, Non-Breaking Events

When a new data source is introduced, like a new type of IoT sensor, we can introduce new event types (e.g., `SensorReadingRecorded`). Existing services will simply ignore these new events, ensuring they are not impacted. New, specialized services can then be built to handle this new stream, allowing the system to grow organically.

**Example:** in a Trigger.dev v4 model, a "new event type" becomes a new task plus the call site that triggers it. Existing tasks never see the new payload, so they are unaffected.

```typescript theme={null}
// New IoT feature - add a NEW task; nothing existing changes
import { task } from '@trigger.dev/sdk/v3';

export const iotDataProcessor = task({
  id: 'iot-data-processor',
  run: async (payload: {
    sensorId: string;
    reading: number;
    timestamp: string;
    location: string;
  }) => {
    return await storeIoTReading(payload);
  },
});

// The producer adds one line to fan the new work out:
//   await iotDataProcessor.trigger({ sensorId, reading, timestamp, location });
// Existing tasks are never invoked with this payload - no impact.
```

**Benefits:**

* **Non-breaking changes** to system
* **Gradual adoption** of new features
* **Backward compatibility** maintained
* **Experimentation** with low risk

**Clarifying Additions:** Teams are not forced into a single technology path. Different services evolve using the most suitable tools for their domain. This architectural freedom supports innovation over time.

***

### 3. Compatible Schema Evolution

The architecture utilizes schema validation (Zod) to govern event structures. This allows us to evolve event payloads in a compatible manner, such as adding a new, optional `correlationId` field to an existing event without breaking any older consumer services that are not yet aware of the new field.

**Example:**

```typescript theme={null}
// Version 1: Original schema
const WorkspaceCreatedV1 = z.object({
  workspaceId: z.string(),
  ownerId: z.string(),
  createdAt: z.date()
});

// Version 2: Add optional fields (backward compatible)
const WorkspaceCreatedV2 = z.object({
  workspaceId: z.string(),
  ownerId: z.string(),
  createdAt: z.date(),
  correlationId: z.string().optional(),  // NEW: optional
  source: z.string().optional()           // NEW: optional
});

// Old consumers still work (ignore new fields)
// New consumers can use new fields
```

**Benefits:**

* **Gradual migration** of consumers
* **No breaking changes** for existing services
* **Type safety** with Zod validation
* **Clear documentation** of event structure

**Clarifying Additions:** Infrastructure changes stay isolated from business logic. Adapters act as interchangeable layers without affecting the core. This keeps the system adaptable to new technical requirements.

***

### 4. Modular Data Ownership

> **Conceptual pattern.** In a full microservice mesh each service owns a private database. **Tuturuuu does not do this today** - all apps share a single Supabase Postgres project, and per-feature isolation is enforced through schema boundaries, table ownership conventions, and RLS rather than separate physical databases. The pattern below shows how decoupled ownership *would* look and is useful when reasoning about future extraction; it is not the current deployment.

To support a new feature requiring geospatial queries, you can isolate the new data shape behind a dedicated module (its own tables, or its own database extension such as PostGIS) so it evolves independently of unrelated tables.

```typescript theme={null}
// Conceptual: a feature-owned task that writes to its own geospatial tables.
import { task } from '@trigger.dev/sdk/v3';

export const updateUserLocation = task({
  id: 'update-user-location',
  run: async (payload: { userId: string; lat: number; lng: number }) => {
    // Writes to geolocation-owned tables (e.g. a PostGIS extension),
    // without touching unrelated schemas.
    return await storeUserLocation(payload);
  },
});

// In Tuturuuu today this lives in the shared Supabase project; isolation is
// schema/RLS-based rather than a physically separate database.
```

**Benefits (of the pattern):**

* **Right tool for the job** - choose the optimal storage for each feature
* **Independent evolution** of data models
* **Bounded blast radius** for schema changes
* **Module isolation** - feature data evolves without cross-feature migrations

**Clarifying Additions:** Each module grows independently while remaining part of a cohesive whole. UI changes become safer because the blast radius stays limited. This supports consistent long-term UI development.

***

### 5. Frontend Composability

The modular frontend can be extended with new components that drive new interactions. A new dashboard widget can call a REST route (`/api/v1/...` in `apps/web`, or a Rust `apps/backend` endpoint in the migrated stack), and that route either responds directly or kicks off background work by triggering a Trigger.dev task. The widget never talks to a broker; it talks to an HTTP endpoint that owns the side effects.

**Example:**

```typescript theme={null}
// apps/web/src/components/dashboard/NewWidget.tsx
'use client';

import { useMutation } from '@tanstack/react-query';

export function NewDashboardWidget() {
  // Use TanStack Query for client mutations - never fetch in useEffect.
  const refresh = useMutation({
    mutationFn: () =>
      fetch('/api/v1/widgets/refresh', {
        method: 'POST',
        body: JSON.stringify({ widgetId: 'new-widget' }),
      }),
  });

  return (
    <div className="widget">
      <button onClick={() => refresh.mutate()}>Refresh Data</button>
      {/* Widget UI */}
    </div>
  );
}

// Backend route: apps/web/src/app/api/v1/widgets/refresh/route.ts
import { tasks } from '@trigger.dev/sdk/v3';

export async function POST(request: Request) {
  const { widgetId } = await request.json();

  // Kick off background work by triggering a task (no broker publish).
  await tasks.trigger('refresh-widget', { widgetId });

  return Response.json({ success: true });
}
```

**Benefits:**

* **Frontend-driven innovation** - the UI team can add features
* **Clean integration** via stable HTTP routes that own the side effects
* **Backend extensibility** without tight coupling to the client
* **Feature experimentation** with low risk

**Clarifying Additions:** Frontends stay insulated from backend restructuring. The HTTP route is the stable interface even as the work behind it moves between an inline handler and a background task. This continuity simplifies client-side development and survives the `apps/web` to `apps/tanstack-web` + `apps/backend` migration.

***

## Resilience (5 Reasons)

Resilience is an intrinsic property of this loosely coupled, asynchronous architecture.

### 1. The Queue as a Stability Buffer (Temporal Decoupling)

If downstream processing is slow or temporarily unavailable, the code that triggers it is unaffected: triggering a Trigger.dev task enqueues a run and returns immediately. Trigger.dev persists and retries runs, so work is not lost while a task's worker capacity catches up. The same buffering property holds in a full broker too; in Tuturuuu it is provided by Trigger.dev's managed run queue rather than a self-hosted broker.

**Example:**

```typescript theme={null}
import { task, tasks } from '@trigger.dev/sdk/v3';

// The caller continues working even if processing is backed up.
await tasks.trigger('process-report', { reportId, data });
// Returns immediately - it does not wait for the run to complete.

// The task drains its backlog at its own sustainable pace.
export const processReport = task({
  id: 'process-report',
  queue: { concurrencyLimit: 5 },
  run: async (payload: { reportId: string; data: unknown }) => {
    return await generateReport(payload);
  },
});
```

**Benefits:**

* **Zero data loss** during outages
* **Automatic recovery** when service restarts
* **Producer isolation** from consumer failures
* **System resilience** to partial failures

**Clarifying Additions:** Failures stay local rather than affecting the entire system. The architecture encourages designing for graceful degradation. This improves overall system continuity.

***

### 2. Asynchronous, Non-Blocking Communication

Producers "fire and forget" events without waiting for a response. This prevents cascading failures, where a slow consumer would otherwise block an upstream service and cause a system-wide slowdown.

**Example:**

```typescript theme={null}
// SYNCHRONOUS (problematic):
async function createWorkspace(data) {
  const workspace = await db.createWorkspace(data);

  // Blocks if email service is slow (5 seconds)
  await sendWelcomeEmail(workspace.ownerId);  // BLOCKS HERE

  // Blocks if provisioning is slow (10 seconds)
  await provisionResources(workspace.id);      // BLOCKS HERE

  return workspace;  // User waits 15+ seconds
}

// EVENT-DRIVEN (resilient):
import { tasks } from '@trigger.dev/sdk/v3';

async function createWorkspace(data) {
  const workspace = await db.createWorkspace(data);

  // Non-blocking - enqueues background work and returns immediately
  await tasks.trigger('workspace-created-followups', { workspaceId: workspace.id });

  return workspace;  // User gets a response in <1 second
}

// Tasks run asynchronously.
// If the email step is slow, it does not affect the user-facing response.
```

**Benefits:**

* **Fast user responses** - no blocking on background work
* **Isolation from slow consumers**
* **Better resource utilization**
* **Improved user experience**

**Clarifying Additions:** Resilience logic becomes consistent for all services. The system handles temporary failures automatically without client-side complexity. This stabilizes user experience during partial outages.

***

### 3. Idempotent Consumer Design

A core resilience pattern is to make task handlers idempotent so they can safely run on the same payload more than once without duplicate side effects. Trigger.dev retries failed runs (and supports an `idempotencyKey` on trigger), so a task that crashes after sending an email but before recording it may run again; idempotency ensures that retry does not corrupt state.

**Example:**

```typescript theme={null}
import { task } from '@trigger.dev/sdk/v3';

export const sendWelcomeEmail = task({
  id: 'send-welcome-email',
  run: async (payload: { userId: string; email: string }) => {
    const { userId, email } = payload;

    // Idempotent: check if already sent before sending.
    const existingEmail = await db.sentEmails.findOne({
      userId,
      type: 'welcome',
    });

    if (existingEmail) {
      // Already sent - skip (idempotent behavior).
      return { skipped: true };
    }

    await sendEmail({ to: email, template: 'welcome' });

    await db.sentEmails.insert({ userId, type: 'welcome', sentAt: new Date() });

    return { sent: true };
  },
});

// If this run is retried, the user does not get a duplicate email.
// Triggering with an idempotencyKey also deduplicates the run itself:
//   sendWelcomeEmail.trigger(payload, { idempotencyKey: `welcome-${userId}` });
```

**Benefits:**

* **Safe retries** without side effects
* **Data consistency** even with failures
* **Simple error recovery** - just retry
* **Reliable processing** guarantees

**Clarifying Additions:** Availability remains high because traffic avoids unhealthy components. Failover happens without requiring operator involvement. This supports seamless recovery.

***

### 4. Retries and a Dead-Letter Path for Error Handling

> **Conceptual + partial.** A true dead-letter *queue* (a separate topic the broker auto-routes poison messages to) is a broker primitive Tuturuuu does not run. Trigger.dev v4 *does* provide the durable building blocks: per-task `retry` policies and the ability to hand a permanently failing payload off to a dedicated "dead-letter" follow-up task for offline analysis. The example below uses real v4 `retry` config and models the dead-letter step as an explicit follow-up trigger.

For payloads that consistently fail (e.g., malformed data), configure bounded retries and route the still-failing payload to a dedicated task instead of letting it block the rest of the workload.

```typescript theme={null}
import { task, tasks } from '@trigger.dev/sdk/v3';

export const processPayment = task({
  id: 'process-payment',
  // Real v4 retry policy: bounded, exponential backoff.
  retry: { maxAttempts: 3, factor: 2, minTimeoutInMs: 1000 },
  run: async (payload: { id: string }) => {
    return await chargePaymentMethod(payload);
  },
  // Runs after all retries are exhausted - the "dead-letter" hand-off.
  handleError: async (payload, error) => {
    await tasks.trigger('payment-dead-letter', {
      originalPayload: payload,
      error: error instanceof Error ? error.message : 'Unknown error',
    });
  },
});

// Dedicated task that records failures and alerts for manual review.
export const paymentDeadLetter = task({
  id: 'payment-dead-letter',
  run: async (payload: { originalPayload: { id: string }; error: string }) => {
    await recordFailedPayment(payload);
    await alertOnCallTeam(payload.originalPayload.id);
  },
});
```

<Note>
  Confirm the exact `retry` / `handleError` field names against the installed `@trigger.dev/sdk` v4 types before copying this verbatim; the shape above illustrates the pattern, and Tuturuuu's own tasks in `packages/trigger/src` favor catching errors inside `run` and returning a `{ success: false }` result.
</Note>

**Benefits:**

* **Poison pill isolation** - one bad message doesn't stop queue
* **Automatic retry** for transient errors
* **Manual review** for persistent errors
* **Pattern detection** for systemic issues

**Clarifying Additions:** Workloads continue flowing even when some services are unavailable. Components operate at different speeds without blocking each other. This improves stability in distributed workflows.

***

### 5. Replayability for Disaster Recovery

> **Conceptual - not implemented in Tuturuuu.** This is a classic *event-sourcing* property: when an immutable, ordered log of domain events is the source of truth, you can rebuild any derived state by replaying that log from a known-good point. **Tuturuuu is not event-sourced** - state lives in Supabase Postgres tables, recovery relies on Postgres backups/PITR, and Trigger.dev v4 has no "replay this date range of events" trigger like the one previous versions of this page implied. Keep this section as a mental model for derived/cached state, not as an operational runbook.

**How it would work (event-sourcing concept):**

```text theme={null}
DISASTER: a derived read model (e.g. a cache or projection) is corrupted by a bug.
1. Stop the consumer that builds the read model.
2. Deploy the fixed projection logic.
3. Discard the corrupted derived state.
4. Re-process the durable source events in order to rebuild the read model.
```

```typescript theme={null}
// Conceptual rebuild loop - a plain task that re-applies events you have
// stored durably. There is no built-in Trigger.dev "replay by date" trigger;
// you supply the events yourself (e.g. from an append-only table).
import { task } from '@trigger.dev/sdk/v3';

export const rebuildUserProjection = task({
  id: 'rebuild-user-projection',
  run: async (payload: { event: UserEvent }) => {
    const { event } = payload;
    if (event.type === 'user.registered') await db.users.insert(event);
    else if (event.type === 'user.updated') await db.users.update(event.userId, event);
    else if (event.type === 'user.deleted') await db.users.delete(event.userId);
  },
});
```

**Why Tuturuuu relies on backups instead:** without an append-only event log as the system of record, the durable truth is the Postgres tables themselves. Disaster recovery uses Supabase backups and point-in-time recovery rather than log replay.

**Benefits (of the event-sourcing pattern, where adopted):**

* **State reconstruction** from a durable event log
* **Bug-fix validation** by re-deriving projections
* **Audit trail** for compliance

**Clarifying Additions:** Treat derived/cached data as rebuildable from a durable source. For Tuturuuu that durable source is Postgres plus its backups; for a true event-sourced subsystem it would be the event log.

***

## Scalability (5 Reasons)

The event-driven model is inherently designed for high-throughput and elastic scaling.

### 1. Parallel Processing via Concurrency

To increase throughput, you raise the task's allowed concurrency and let more runs execute in parallel. In a Kafka-style system this is done with consumer groups; in Tuturuuu it is Trigger.dev's managed concurrency - you define the task once and set a `queue.concurrencyLimit` (and queue-level controls) rather than running and balancing your own consumer instances.

**Example:**

```typescript theme={null}
import { task } from '@trigger.dev/sdk/v3';

export const processAnalytics = task({
  id: 'process-analytics',
  // Higher concurrency = more parallel runs = more throughput.
  queue: { concurrencyLimit: 50 },
  run: async (payload: { userId: string; activity: unknown }) => {
    return await aggregateMetrics(payload);
  },
});

// Trigger.dev schedules many runs of this task in parallel up to the limit,
// so raising the concurrency limit raises throughput without code changes.
```

**Benefits:**

* **Throughput scales with concurrency** - raise the limit, process more in parallel
* **Managed scheduling** - no consumer instances to run or balance yourself
* **No code changes** required to scale
* **Cost-effective** - tune concurrency up or down as needed

**Clarifying Additions:** Each service grows according to its actual demand rather than the needs of the system as a whole. This leads to better resource distribution. It prevents unnecessary scaling of unrelated components.

***

### 2. Per-Entity Ordering with Parallelism Across Entities

A common scaling goal is: process work for a single entity (e.g. one workspace) in order, while processing different entities fully in parallel. Kafka achieves this with topic partitions keyed by a business key; Tuturuuu does not run Kafka topics. The closest Trigger.dev mechanism is a **concurrency key** plus per-queue concurrency limits, which serialize runs that share a key while letting different keys run in parallel.

**Example:**

```typescript theme={null}
import { task } from '@trigger.dev/sdk/v3';

export const updateWorkspace = task({
  id: 'update-workspace',
  // Serialize runs per workspace (one in flight per concurrencyKey),
  // while different workspaces run in parallel.
  queue: { concurrencyLimit: 25 },
  run: async (payload: { workspaceId: string; data: unknown }) => {
    return await applyWorkspaceUpdate(payload);
  },
});

// Trigger per workspace so same-workspace runs are ordered:
//   updateWorkspace.trigger(payload, { concurrencyKey: payload.workspaceId });
//
// Workspace A runs: serialized (ordered)
// Workspace B runs: serialized (ordered), in parallel with A
// Workspace C runs: serialized (ordered), in parallel with A & B
```

<Note>
  This maps the partitioning *concept* onto Trigger.dev v4. Verify the `concurrencyKey` option name against the installed SDK before relying on it; there are no Kafka topics, partitions, or broker ACLs in Tuturuuu.
</Note>

**Benefits:**

* **Ordering guarantees** per entity (per concurrency key)
* **Maximum parallelism** across distinct entities
* **Optimal throughput** with consistency
* **Scalable architecture**

**Clarifying Additions:** Stateless components are easy to duplicate and coordinate. Scaling becomes predictable and controllable. Traffic fluctuations can be handled efficiently.

***

### 3. Independent Scaling per Workload

Different workloads scale on their own axis. In Tuturuuu this shows up two ways: the deployable apps (`apps/web`, the migration target `apps/tanstack-web`, and the Rust `apps/backend`) scale at the deployment layer, and each Trigger.dev task carries its own concurrency budget so a heavy task can run wide while a light one stays narrow - without coupling either to a single shared scale knob.

**Example:**

```typescript theme={null}
import { task } from '@trigger.dev/sdk/v3';

// Heavy, high-volume work: allow many parallel runs.
export const processAnalytics = task({
  id: 'process-analytics',
  queue: { concurrencyLimit: 100 },
  run: async (payload) => aggregateMetrics(payload),
});

// Low-volume, rate-sensitive work: keep it narrow.
export const sendReport = task({
  id: 'send-report',
  queue: { concurrencyLimit: 2 },
  run: async (payload) => deliverReport(payload),
});

// Each task scales independently via its own concurrency limit -
// no need to scale the whole app to speed up one workload.
```

**Benefits:**

* **Granular scaling** per service
* **Cost optimization** - only scale what's needed
* **Resource efficiency**
* **Performance optimization** per workload

**Clarifying Additions:** Uniform request handling promotes system stability. Load is shared automatically without service-specific logic. This ensures consistent performance at scale.

***

### 4. The Run Queue as a Load Absorber

A managed run queue can absorb sudden bursts of triggered work. It smooths out load so tasks process at their own sustainable pace (bounded by concurrency) without being overwhelmed. In Tuturuuu this absorber is the Trigger.dev run queue; the same role would be played by a broker in a Kafka-style system.

**Example:**

```mermaid theme={null}
graph LR
    A[Traffic Spike<br/>10,000 triggers/sec] -->|Enqueues all| B[Trigger.dev Run Queue<br/>Buffers runs]
    B -->|Drains at<br/>concurrency limit| C[Task Workers<br/>Process sustainably]

    style B fill:#4f46e5,stroke:#3730a3,color:#fff
```

**Benefits:**

* **Spike protection** - absorbs bursts
* **Sustainable processing** rates
* **No service overload**
* **Improved reliability**

**Clarifying Additions:** Separating reads from writes avoids resource contention. High-traffic paths get dedicated scaling strategies. This improves responsiveness and throughput.

***

### 5. CQRS for Optimized Read Performance

An asynchronous, task-based flow is a natural fit for Command Query Responsibility Segregation (CQRS). A "command" writes the authoritative record and then triggers a background task; that task maintains a read-optimized model (for example a denormalized cache), letting read-heavy paths scale independently and deliver low latency.

> **Conceptual.** Tuturuuu does not run a formal CQRS split today; this shows how the pattern maps onto the real `task()` API if you adopt it for a read-heavy surface.

**Example:**

```typescript theme={null}
import { task, tasks } from '@trigger.dev/sdk/v3';

// COMMAND: write the authoritative record, then trigger the projection.
async function updateWorkspace(id: string, data: unknown) {
  await db.workspaces.update(id, data);
  await tasks.trigger('update-workspace-cache', { workspaceId: id, data });
}

// QUERY: maintain a read-optimized cache.
export const updateWorkspaceCache = task({
  id: 'update-workspace-cache',
  run: async (payload: { workspaceId: string; data: Record<string, unknown> }) => {
    await redis.set(
      `workspace:${payload.workspaceId}`,
      JSON.stringify({
        ...payload.data,
        memberCount: await getMemberCount(payload.workspaceId),
        lastActivity: new Date(),
      })
    );
  },
});

// Reads hit the cache (fast); writes go to Postgres (consistent).
```

**Benefits:**

* **Read/write optimization** separately
* **Low-latency reads** from cache
* **Consistent writes** to database
* **Independent scaling** of read vs write paths

**Clarifying Additions:** The system adapts naturally to changes in workload. Instances come and go without manual reconfiguration. This makes scaling continuous and flexible.

***

## Summary Matrix

| Property          | Key Benefit                  | Primary Pattern      | Example Use Case                         |
| ----------------- | ---------------------------- | -------------------- | ---------------------------------------- |
| **Extensibility** | Add features without changes | Add Consumer         | Fraud detection on existing payments     |
| **Resilience**    | Graceful failure handling    | Temporal Decoupling  | Email service down, users still register |
| **Scalability**   | Linear throughput growth     | Parallel Consumption | Black Friday traffic spike handling      |

## Related Documentation

* [Event-Driven Architecture](/platform/architecture/system-design/event-driven-architecture) - Detailed advantages and drawbacks
* [Architectural Decisions](/platform/architecture/system-design/architectural-decisions) - Why we chose this architecture
* [Trigger.dev Package](/reference/packages/trigger) - Implementation reference


# Hexagonal Architecture
Source: https://docs.tuturuuu.com/platform/architecture/system-design/hexagonal-architecture

An educational guide to the ports and adapters pattern, with notes on where Tuturuuu applies its ideas

# Hexagonal Architecture (Ports and Adapters)

Hexagonal Architecture, also known as Ports and Adapters, is a design pattern
for achieving **technology independence**, **testability**, and
**maintainability** by isolating core business logic from the technologies that
surround it.

<Note>
  This page is an **educational pattern guide**, not a description of Tuturuuu's
  current directory layout. The Tuturuuu apps (`apps/web`, `apps/finance`) are
  conventional Next.js App Router apps organized by `app/`, `components/`, `lib/`,
  and `utils/` — they do **not** use formal `domain/`, `application/`, and
  `infrastructure/` layers. The code samples below are illustrative; their file
  paths are aspirational and do not exist in the repo. Where Tuturuuu genuinely
  borrows an idea from this pattern, the text says so explicitly.
</Note>

<Note>
  **Architecture is moving.** Tuturuuu is migrating the legacy Next.js
  `apps/web` runtime (port `7803`) to TanStack Start (`apps/tanstack-web`) plus a
  dedicated Rust backend (`apps/backend`, port `7820`). The emerging backend is
  the Rust service, not a TypeScript "microservice." See
  [TanStack Start And Rust Migration](/platform/architecture/tanstack-rust-migration)
  for the canonical target. Treat the patterns below as portable design ideas, not
  a permanent structural mandate.
</Note>

## Core Concept

The hexagon represents your application's core business logic. **Ports** are interfaces that define how the outside world can interact with your application, and **Adapters** are implementations that connect external technologies to these ports.

```mermaid theme={null}
graph TB
    subgraph "External World"
        A[HTTP/API]
        B[Database]
        C[Event Broker]
        D[External Services]
    end

    subgraph "Adapters (Infrastructure)"
        E[API Adapter]
        F[Database Adapter]
        G[Event Adapter]
        H[Service Adapter]
    end

    subgraph "Hexagon (Core)"
        I[Business Logic]
        J[Domain Models]
        K[Use Cases]
    end

    A --> E
    B --> F
    C --> G
    D --> H
    E --> I
    F --> I
    G --> I
    H --> I
    I --> J
    I --> K

    style I fill:#4f46e5,stroke:#3730a3,color:#fff
    style J fill:#4f46e5,stroke:#3730a3,color:#fff
    style K fill:#4f46e5,stroke:#3730a3,color:#fff
```

## How Tuturuuu Actually Structures Apps

Before the conceptual layers below, here is the real layout you will find in the
codebase today. The Next.js apps are organized by concern, not by hexagonal
layer:

```
apps/web/src/
├── app/          # Next.js App Router routes + /api/v1 REST handlers (presentation)
├── components/   # React components (presentation)
├── features/     # Feature-scoped UI and logic
├── hooks/        # Client hooks (TanStack Query, etc.)
├── lib/          # Cross-cutting helpers and clients
├── utils/        # Pure utilities
├── constants/    # Static config
└── trpc/         # Minimal tRPC stub (health-check only — not the product data path)
```

Product data flows through shared helpers in `packages/internal-api` and the
REST `/api/v1` routes — **not** through tRPC, which in `apps/web/src/trpc` is
only a `healthCheck` stub today. Cross-app concerns live in `packages/*`
(`packages/supabase`, `packages/payment`, `packages/trigger`,
`packages/internal-api`, `packages/ui`, ...), which is where most "swap the
adapter" flexibility actually lives in practice.

The sections that follow describe the **idealized hexagonal layers** as a
learning model. Read them for the concepts; do not expect to find these exact
directories in the repo.

## The Idealized Layers (Conceptual)

### 1. Domain Layer (Core Business Logic)

**Conceptual location:** `domain/` (illustrative — not a real directory in Tuturuuu)

**Responsibilities:**

* Pure business logic and rules
* Domain models (entities, value objects)
* Domain services (complex business operations)
* Domain events

**Characteristics:**

* No dependencies on external libraries
* No knowledge of databases, APIs, or frameworks
* Fully unit-testable without infrastructure

**Example (illustrative — this file does not exist in the repo):**

```typescript theme={null}
// Illustrative: domain/models/workspace.ts
export class Workspace {
  private constructor(
    public readonly id: string,
    public readonly ownerId: string,
    private _name: string,
    private _isActive: boolean,
    private _plan: WorkspacePlan,
    public readonly createdAt: Date,
    private _updatedAt: Date
  ) {}

  static create(ownerId: string, name: string, plan: WorkspacePlan): Workspace {
    // Business rules
    this.validateName(name);

    return new Workspace(
      generateId(),
      ownerId,
      name,
      true,
      plan,
      new Date(),
      new Date()
    );
  }

  rename(newName: string): void {
    Workspace.validateName(newName);
    this._name = newName;
    this._updatedAt = new Date();
  }

  upgrade(newPlan: WorkspacePlan): void {
    if (newPlan.tier <= this._plan.tier) {
      throw new DomainError('Can only upgrade to higher tier');
    }
    this._plan = newPlan;
    this._updatedAt = new Date();
  }

  deactivate(): void {
    if (!this._isActive) {
      throw new DomainError('Workspace already inactive');
    }
    this._isActive = false;
    this._updatedAt = new Date();
  }

  private static validateName(name: string): void {
    if (name.length < 3 || name.length > 50) {
      throw new DomainError('Workspace name must be 3-50 characters');
    }
    if (!/^[a-zA-Z0-9\s-]+$/.test(name)) {
      throw new DomainError('Workspace name contains invalid characters');
    }
  }

  // Getters only - no setters (encapsulation)
  get name() { return this._name; }
  get isActive() { return this._isActive; }
  get plan() { return this._plan; }
  get updatedAt() { return this._updatedAt; }
}
```

### 2. Application Layer (Use Cases / Orchestration)

**Conceptual location:** `application/` (illustrative — not a real directory in Tuturuuu)

**Responsibilities:**

* Orchestrate domain objects
* Implement use cases (business workflows)
* Transaction management
* Call infrastructure services via ports

**Example (illustrative):**

```typescript theme={null}
// Illustrative: application/use-cases/create-workspace.ts
export interface WorkspaceRepository {
  save(workspace: Workspace): Promise<void>;
  findById(id: string): Promise<Workspace | null>;
  findByOwnerId(ownerId: string): Promise<Workspace[]>;
}

export interface EventPublisher {
  publish(event: DomainEvent): Promise<void>;
}

export class CreateWorkspaceUseCase {
  constructor(
    private readonly repository: WorkspaceRepository,  // PORT
    private readonly eventPublisher: EventPublisher     // PORT
  ) {}

  async execute(command: CreateWorkspaceCommand): Promise<Workspace> {
    // 1. Business logic (domain)
    const workspace = Workspace.create(
      command.ownerId,
      command.name,
      command.plan
    );

    // 2. Persist (via port)
    await this.repository.save(workspace);

    // 3. Publish event (via port)
    await this.eventPublisher.publish(
      new WorkspaceCreatedEvent(workspace.id, workspace.ownerId)
    );

    return workspace;
  }
}
```

### 3. Infrastructure Layer (Adapters)

**Conceptual location:** `infrastructure/` (illustrative — not a real directory in Tuturuuu)

**Responsibilities:**

* Implement ports defined by application/domain
* Handle technology-specific details
* Database access, API calls, event publishing

**Example (illustrative):**

```typescript theme={null}
// Illustrative: infrastructure/repositories/supabase-workspace-repository.ts
import { WorkspaceRepository } from '@/application/use-cases/create-workspace';

export class SupabaseWorkspaceRepository implements WorkspaceRepository {
  constructor(private readonly supabase: SupabaseClient) {}

  async save(workspace: Workspace): Promise<void> {
    const data = this.toDatabaseModel(workspace);

    await this.supabase
      .from('workspaces')
      .upsert(data);
  }

  async findById(id: string): Promise<Workspace | null> {
    const { data } = await this.supabase
      .from('workspaces')
      .select('*')
      .eq('id', id)
      .single();

    return data ? this.toDomainModel(data) : null;
  }

  async findByOwnerId(ownerId: string): Promise<Workspace[]> {
    const { data } = await this.supabase
      .from('workspaces')
      .select('*')
      .eq('owner_id', ownerId);

    return (data || []).map(row => this.toDomainModel(row));
  }

  private toDomainModel(data: any): Workspace {
    // Map database row to domain model
    return new Workspace(
      data.id,
      data.owner_id,
      data.name,
      data.is_active,
      new WorkspacePlan(data.plan_tier, data.plan_features),
      new Date(data.created_at),
      new Date(data.updated_at)
    );
  }

  private toDatabaseModel(workspace: Workspace): any {
    // Map domain model to database row
    return {
      id: workspace.id,
      owner_id: workspace.ownerId,
      name: workspace.name,
      is_active: workspace.isActive,
      plan_tier: workspace.plan.tier,
      plan_features: workspace.plan.features,
      created_at: workspace.createdAt.toISOString(),
      updated_at: workspace.updatedAt.toISOString()
    };
  }
}
```

### 4. Presentation Layer (API / UI)

**Real location:** `apps/web/src/app/api/v1/` (REST handlers) or `apps/web/src/app/`
(routes/pages). This is the one layer that maps cleanly onto Tuturuuu's actual
structure.

**Responsibilities:**

* HTTP request/response handling
* Input validation (DTOs)
* Authentication/authorization
* Call application use cases

In real Tuturuuu code, a route handler does its own validation, gets an
**awaited** Supabase client (`createClient()` from `@tuturuuu/supabase/next/server`
is async), checks auth via `supabase.auth.getUser()`, and then calls a helper.
The example below keeps the use-case indirection for teaching purposes:

**Example (illustrative use-case wiring; Supabase client usage is real):**

```typescript theme={null}
// Illustrative: apps/web/src/app/api/v1/workspaces/create/route.ts
import { createClient } from '@tuturuuu/supabase/next/server';
import { CreateWorkspaceUseCase } from '@/application/use-cases/create-workspace';

const CreateWorkspaceRequestSchema = z.object({
  name: z.string().min(3).max(50),
  plan: z.enum(['free', 'pro', 'enterprise'])
});

export async function POST(request: Request) {
  // 1. Authentication — createClient() is async; await it
  const supabase = await createClient();
  const {
    data: { user },
  } = await supabase.auth.getUser();
  if (!user) {
    return Response.json({ error: 'Unauthorized' }, { status: 401 });
  }

  // 2. Validation
  const body = await request.json();
  const validation = CreateWorkspaceRequestSchema.safeParse(body);

  if (!validation.success) {
    return Response.json(
      { error: validation.error.issues },
      { status: 400 }
    );
  }

  // 3. Execute use case
  const useCase = new CreateWorkspaceUseCase(
    new SupabaseWorkspaceRepository(supabase),
    new TriggerWorkspaceEventPublisher()
  );

  try {
    const workspace = await useCase.execute({
      ownerId: user.id,
      name: validation.data.name,
      plan: new WorkspacePlan(validation.data.plan)
    });

    // 4. Response (DTO)
    return Response.json({
      id: workspace.id,
      name: workspace.name,
      ownerId: workspace.ownerId,
      plan: workspace.plan.tier,
      createdAt: workspace.createdAt.toISOString()
    }, { status: 201 });
  } catch (error) {
    if (error instanceof DomainError) {
      return Response.json({ error: error.message }, { status: 400 });
    }
    return Response.json({ error: 'Internal error' }, { status: 500 });
  }
}
```

## Key Benefits

### 1. Technology Independence

The core business logic has **zero knowledge** of the technologies used. We can swap Supabase for Prisma, Drizzle, or even MongoDB without touching business logic.

**Example migration:**

```typescript theme={null}
// OLD: Supabase adapter
class SupabaseWorkspaceRepository implements WorkspaceRepository { /* ... */ }

// NEW: Drizzle adapter (same interface)
class DrizzleWorkspaceRepository implements WorkspaceRepository {
  constructor(private readonly db: DrizzleDB) {}

  async save(workspace: Workspace): Promise<void> {
    await this.db
      .insert(workspaces)
      .values(this.toDatabaseModel(workspace));
  }

  // Same interface, different implementation
}

// Business logic unchanged!
```

### 2. Testability

Domain logic can be tested **without any infrastructure**:

```typescript theme={null}
// tests/domain/workspace.test.ts
describe('Workspace', () => {
  it('enforces name length rules', () => {
    expect(() => {
      Workspace.create('user-1', 'ab', FreePlan);
    }).toThrow('Workspace name must be 3-50 characters');
  });

  it('prevents downgrade', () => {
    const workspace = Workspace.create('user-1', 'Test', ProPlan);

    expect(() => {
      workspace.upgrade(FreePlan);
    }).toThrow('Can only upgrade to higher tier');
  });
});
// No database, no HTTP, no network - millisecond tests
```

Application layer with mocks:

```typescript theme={null}
// tests/application/create-workspace.test.ts
class InMemoryWorkspaceRepository implements WorkspaceRepository {
  private workspaces = new Map<string, Workspace>();

  async save(workspace: Workspace): Promise<void> {
    this.workspaces.set(workspace.id, workspace);
  }

  async findById(id: string): Promise<Workspace | null> {
    return this.workspaces.get(id) || null;
  }
}

describe('CreateWorkspaceUseCase', () => {
  it('creates workspace and publishes event', async () => {
    const repository = new InMemoryWorkspaceRepository();
    const eventPublisher = new InMemoryEventPublisher();
    const useCase = new CreateWorkspaceUseCase(repository, eventPublisher);

    const workspace = await useCase.execute({
      ownerId: 'user-1',
      name: 'Test Workspace',
      plan: FreePlan
    });

    expect(workspace.name).toBe('Test Workspace');
    expect(eventPublisher.events).toHaveLength(1);
    expect(eventPublisher.events[0]).toBeInstanceOf(WorkspaceCreatedEvent);
  });
});
```

### 3. Maintainability

**Clear boundaries** make it obvious where code belongs:

* Business rules → Domain layer
* Workflows → Application layer
* Technology details → Infrastructure layer
* HTTP handling → Presentation layer

## Ports (Interfaces)

Ports are **contracts** defined by the application/domain:

```typescript theme={null}
// Inbound ports (driving - from outside to core)
export interface CreateWorkspaceCommand {
  ownerId: string;
  name: string;
  plan: WorkspacePlan;
}

// Outbound ports (driven - from core to outside)
export interface WorkspaceRepository {
  save(workspace: Workspace): Promise<void>;
  findById(id: string): Promise<Workspace | null>;
  findByOwnerId(ownerId: string): Promise<Workspace[]>;
  delete(id: string): Promise<void>;
}

export interface EventPublisher {
  publish(event: DomainEvent): Promise<void>;
}

export interface EmailService {
  sendWorkspaceInvitation(email: string, workspaceId: string): Promise<void>;
}
```

## Adapters (Implementations)

Adapters **implement** the ports:

```typescript theme={null}
// Repository adapter
export class SupabaseWorkspaceRepository implements WorkspaceRepository { /* ... */ }

// Event publisher adapter.
// Tuturuuu uses Trigger.dev v4 (@trigger.dev/sdk ^4.x). There is no
// `trigger.event(...)` / `eventTrigger` API — background work is modeled as
// tasks defined with `task({ id, run })` (see packages/trigger/src) and
// invoked with `.trigger(payload)`.
import { type DomainEvent } from '@/domain/events';
import { task } from '@trigger.dev/sdk/v3';

// A real Trigger.dev v4 task lives in packages/trigger/src, e.g.:
export const workspaceCreatedTask = task({
  id: 'workspace-created',
  run: async (payload: { workspaceId: string; ownerId: string }) => {
    // ...side effects: notifications, projections, etc.
    return { ok: true };
  },
});

// The adapter just enqueues the task — keeping the core ignorant of Trigger.dev.
export class TriggerWorkspaceEventPublisher implements EventPublisher {
  async publish(event: DomainEvent): Promise<void> {
    await workspaceCreatedTask.trigger({
      workspaceId: event.payload.workspaceId,
      ownerId: event.payload.ownerId,
    });
  }
}

// Email service adapter.
// Tuturuuu sends transactional email through packages/transactional and
// packages/email-service rather than a raw provider SDK in app code; the body
// here is illustrative of how any provider would sit behind the port.
export class TransactionalEmailService implements EmailService {
  async sendWorkspaceInvitation(email: string, workspaceId: string): Promise<void> {
    await sendInvitationEmail({ to: email, workspaceId });
  }
}
```

## Dependency Injection

Wire adapters to use cases. Note that `createClient()` is async, so the factory
must be async too:

```typescript theme={null}
// Illustrative: lib/container.ts (no such DI container exists in Tuturuuu today)
import { createClient } from '@tuturuuu/supabase/next/server';

export async function createWorkspaceUseCase(): Promise<CreateWorkspaceUseCase> {
  const supabase = await createClient();
  return new CreateWorkspaceUseCase(
    new SupabaseWorkspaceRepository(supabase),
    new TriggerWorkspaceEventPublisher()
  );
}

// Usage in API route
const useCase = await createWorkspaceUseCase();
const result = await useCase.execute(command);
```

<Note>
  Tuturuuu does **not** ship a formal DI container. Route handlers and
  `packages/internal-api` helpers wire their dependencies directly. The factory
  above shows the pattern conceptually.
</Note>

## Directory Structure Example (Illustrative)

The tree below shows what a **fully layered** hexagonal app could look like. It
is a teaching illustration — **Tuturuuu does not use this layout.** For the
actual structure, see [How Tuturuuu Actually Structures Apps](#how-tuturuuu-actually-structures-apps)
above.

```
src/                                 # Illustrative hexagonal layout (NOT the real apps/web layout)
├── domain/                          # Core (no dependencies)
│   ├── models/
│   │   ├── workspace.ts             # Domain entities
│   │   └── workspace-plan.ts
│   ├── services/
│   │   └── workspace-service.ts     # Domain logic
│   └── events/
│       └── workspace-created.ts     # Domain events
├── application/                     # Use cases (depends on domain)
│   └── use-cases/
│       ├── create-workspace.ts      # Defines ports
│       ├── update-workspace.ts
│       └── delete-workspace.ts
├── infrastructure/                  # Adapters (implements ports)
│   ├── repositories/
│   │   └── supabase-workspace-repository.ts
│   ├── events/
│   │   └── trigger-workspace-publisher.ts
│   └── email/
│       └── transactional-email-service.ts
└── app/                             # Presentation
    └── api/v1/workspaces/
        ├── create/route.ts          # HTTP adapter
        └── [id]/route.ts
```

## C4 Component Diagram Explanations

The C4 model provides a structured way to visualize software architecture at different levels of abstraction. At the Component level, we focus on the major structural building blocks and their interactions within a system.

### Backend – Applying Ports and Adapters to Payments

<Note>
  The original version of this section described a Java/Kafka/Redis/Stripe payment
  microservice. **None of that exists in Tuturuuu.** Payments are handled by
  `packages/payment`, which currently has a single provider integration: **Polar**
  (`packages/payment/src/polar`, with `checkout/`, `client.ts`, `server.ts`, and
  Next.js helpers under `next/`). There is no Kafka, no Redis, no Stripe SDK, and
  no Java. The dedicated backend is the **Rust** service in `apps/backend`
  (route modules such as `inventory.rs`, `aurora.rs`, `nova.rs`,
  `onboarding_progress.rs`), not a JVM microservice.
</Note>

The ports-and-adapters *idea* still maps cleanly onto how `packages/payment` is
organized, even though the package does not enforce formal layers:

**Inbound (Outside → Core):**

Requests enter through HTTP route handlers (in `apps/web` `/api/v1` today, and
increasingly in `apps/backend` Rust routes) and provider webhooks. These
translate transport payloads into typed inputs and call payment helpers — the
"inbound adapter" role.

**Core (Business Rules):**

Subscription tier logic, entitlement checks, and checkout orchestration are the
domain concern. Keeping these decisions independent of the provider is the goal:
the rest of the platform asks "what tier is this workspace?" without caring that
Polar answers it.

**Outbound (Core → Outside):**

The **Polar provider** in `packages/payment/src/polar` is the outbound adapter
to the payment processor. Persistence flows through the shared Supabase project
(`packages/supabase`), not a dedicated payment database. If Tuturuuu added a
second processor, it would implement the same client/checkout contract behind
the existing interface — which is exactly the substitutability hexagonal
architecture is designed to give you.

**Why the pattern still helps here:**

Even without formal `domain/`/`application/`/`infrastructure/` directories,
isolating the provider behind `packages/payment` keeps the swap surface small.
That is the practical, real-world takeaway from this pattern in Tuturuuu — a
clean seam around an external dependency, not a strict layered file tree.

### Frontend – Headless UI React Architecture (C4 Component Diagram)

The frontend separates rendering from state and behavioural logic to maintain
scalability and reusability. This part of the description **does** broadly match
Tuturuuu's real conventions (Server Components by default, client hooks for
interactivity, shared UI in `packages/ui`).

**Presentation Layer:**

Each **route/page** acts as a top-level container that orchestrates data loading
and renders UI components. Visual components stay purely presentational, while
stateful or behavioural logic is delegated to **hooks** (`apps/web/src/hooks`,
typically TanStack Query for fetching and mutations). Per the platform rules,
data fetching is **not** done in `useEffect`.

**Communication Layer:**

Client-side data access flows through **TanStack Query** hooks, and app API
access is routed through the shared **`packages/internal-api`** helpers rather
than raw client-side `fetch` against app endpoints. Backend calls target the
REST `/api/v1` routes today and, increasingly, the Rust `apps/backend` service.

**Shared Component Library:**

Reusable UI building blocks live in **`packages/ui`** (imported via
`@tuturuuu/ui/*`), with shared icons in **`packages/icons`** (`@tuturuuu/icons`),
supporting composability and reducing duplication across apps.

**Layer Separation:**

This architecture clearly separates **Presentation → Logic → Communication** layers, enabling maintainable state management, easier testability, and clean integration with backend APIs (Tuturuuu's `/api/v1` routes and the emerging Rust `apps/backend`). Since the diagram operates at C4 Component Level, it intentionally excludes internal React implementation details (such as local state, props, or context) and instead focuses on component roles, interactions, and the flow of data through the system.

**Key Principles:**

1. **Separation of Concerns**: UI components are purely presentational; hooks handle state and behavior
2. **Reusability**: Shared components and utilities reduce code duplication
3. **Testability**: Clear boundaries enable isolated testing of presentation, logic, and communication layers
4. **Type Safety**: Typed HTTP clients ensure contract adherence between frontend and backend

## Related Documentation

* [Architectural Decisions](/platform/architecture/system-design/architectural-decisions) - Why we chose hexagonal architecture
* [Encapsulation Patterns](/platform/architecture/system-design/encapsulation-patterns) - Layer boundaries
* [Data Fetching](/platform/architecture/data-fetching) - Integration with React


# Layering Patterns in Architecture
Source: https://docs.tuturuuu.com/platform/architecture/system-design/layering-patterns

Comprehensive comparison of N-tier, layer-based, and microservices architectural patterns in Tuturuuu

Understanding how to structure code within services is critical for maintainability and testability. This document compares traditional N-Tier architecture with modern layer-based patterns, and explains how layering works within microservices.

<Note>
  **Key Insight**: Layering is an **internal** concern (how code is organized within a service), while microservices is an **external** concern (how services are distributed). These patterns are complementary, not mutually exclusive.
</Note>

<Warning>
  **How to read this page.** The N-Tier, Hexagonal, Clean, and Onion sections
  below are **conceptual / educational** material that explains layering theory
  with illustrative TypeScript. Tuturuuu's apps do **not** ship a formal hexagonal
  directory layout (no `domain/`, `application/`, or `infrastructure/` folders).
  Each app is a conventional **Next.js App Router** app (`app/`, `components/`,
  `lib/`, `utils/`, `features/`) that talks to a shared Supabase project, with the
  newer backend logic moving into the Rust service in `apps/backend`. Treat the
  layered code samples as patterns to learn from, not as a map of the current
  codebase. The "Tuturuuu's Implementation" section near the end describes the
  **actual** layout.
</Warning>

<Info>
  **Active migration.** `apps/web` (Next.js, port `7803`) is being replaced by
  `apps/tanstack-web` (TanStack Start) plus `apps/backend` (Rust, port `7820`).
  Backend layering increasingly lives in the Rust service. See
  [TanStack Start And Rust Migration](/platform/architecture/tanstack-rust-migration)
  for the migration contract.
</Info>

<Info>
  For a comprehensive comparison of all architectural patterns with detailed pros and cons, see [Architectural Patterns Comparison](/platform/architecture/system-design/architectural-patterns-comparison).
</Info>

## Architectural Layering Patterns Compared

### 1. Traditional N-Tier Architecture

#### What Is N-Tier Architecture?

N-Tier (also called "N-Layer") is a traditional architectural pattern that organizes code into horizontal layers, each responsible for a specific technical concern. The most common form is 3-tier architecture:

```mermaid theme={null}
graph TD
    A["Presentation Tier (UI)<br/>User interaction, rendering"]
    B["Business Logic Tier (BLL)<br/>Business rules, validation"]
    C["Data Access Tier (DAL)<br/>Database operations, persistence"]
    D[("Database")]

    A -->|Calls| B
    B -->|Calls| C
    C -->|Queries| D

    style A fill:#e3f2fd,stroke:#1976d2,stroke-width:2px
    style B fill:#fff3e0,stroke:#f57c00,stroke-width:2px
    style C fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px
    style D fill:#e8f5e9,stroke:#388e3c,stroke-width:2px
```

#### Characteristics of N-Tier

**Dependencies Flow Downward:**

* Presentation → Business Logic → Data Access → Database
* Each layer can only call the layer directly below it
* Upper layers depend on concrete implementations in lower layers

**Example (Traditional N-Tier):**

```typescript theme={null}
// Presentation Layer
export async function GET(request: Request) {
  const workspaceService = new WorkspaceService();
  const workspaces = await workspaceService.getWorkspaces();

  return Response.json(workspaces);
}

// Business Logic Layer
export class WorkspaceService {
  async getWorkspaces() {
    // Business logic mixed with data access
    const dal = new WorkspaceDAL();
    const workspaces = await dal.findAll();

    // Validation happens here
    return workspaces.filter(w => w.isActive);
  }
}

// Data Access Layer
export class WorkspaceDAL {
  async findAll() {
    // Direct database coupling
    const { data } = await supabase
      .from('workspaces')
      .select('*');

    return data;
  }
}
```

#### Problems with Traditional N-Tier

1. **Tight Coupling to Infrastructure**
   * Business logic depends directly on data access layer
   * Changing databases requires modifying business logic
   * Hard to test business rules without a database

2. **Leaky Abstractions**
   * Database concerns leak into business logic (SQL, ORM entities)
   * Business logic becomes aware of persistence details
   * Domain models often have database annotations

3. **Circular Dependencies**
   * Business layer creates data access objects
   * Data access returns domain models
   * Creates tight coupling between layers

4. **Technology Lock-In**
   * Business logic married to specific ORM or database
   * Difficult to swap technologies
   * Framework dependencies throughout codebase

**Example of the Problem:**

```typescript theme={null}
// Business logic layer - TIGHTLY COUPLED to database
export class WorkspaceService {
  async createWorkspace(name: string, ownerId: string) {
    // PROBLEM: Business logic knows about Supabase
    const { data, error } = await supabase
      .from('workspaces')
      .insert({ name, owner_id: ownerId })
      .select()
      .single();

    if (error) throw error;

    // PROBLEM: Business validation after database insert
    if (data.name.length < 3) {
      // Too late - already in database!
      await supabase.from('workspaces').delete().eq('id', data.id);
      throw new Error('Name too short');
    }

    return data;
  }
}
```

***

### 2. Modern Layer-Based Architectures

Layer-based architectures (Hexagonal, Clean, Onion) solve N-Tier's problems by inverting dependencies and organizing around business domains rather than technical layers.

#### Hexagonal Architecture (Ports & Adapters)

```mermaid theme={null}
graph TB
    subgraph External["External Systems"]
        HTTP["HTTP REST"]
        GQL["GraphQL"]
        CLI["CLI"]
        Events["Event Consumers"]
        DB[("Database")]
        MsgBus[("Message Bus")]
        Email["Email Service"]
        API["External API"]
    end

    subgraph Hexagon["Hexagonal Architecture"]
        subgraph Primary["Primary Adapters<br/>(Inbound/Driving)"]
            RestCtrl["REST Controllers"]
            GqlResolv["GraphQL Resolvers"]
            CliCmd["CLI Commands"]
            EventCons["Event Consumers"]
        end

        subgraph PrimaryPorts["Primary Ports<br/>(Interfaces)"]
        end

        subgraph DomainCore["DOMAIN CORE<br/>(Business Logic)"]
            Entities["Entities"]
            VOs["Value Objects"]
            DomainSvc["Domain Services"]
            BizRules["Business Rules"]
        end

        subgraph SecondaryPorts["Secondary Ports<br/>(Interfaces)"]
        end

        subgraph Secondary["Secondary Adapters<br/>(Outbound/Driven)"]
            RepoImpl["Repository Impl"]
            EventPub["Event Publisher"]
            EmailSend["Email Sender"]
            HttpClient["HTTP Client"]
        end
    end

    HTTP --> RestCtrl
    GQL --> GqlResolv
    CLI --> CliCmd
    Events --> EventCons

    RestCtrl --> PrimaryPorts
    GqlResolv --> PrimaryPorts
    CliCmd --> PrimaryPorts
    EventCons --> PrimaryPorts

    PrimaryPorts --> DomainCore
    DomainCore --> SecondaryPorts

    SecondaryPorts --> RepoImpl
    SecondaryPorts --> EventPub
    SecondaryPorts --> EmailSend
    SecondaryPorts --> HttpClient

    RepoImpl --> DB
    EventPub --> MsgBus
    EmailSend --> Email
    HttpClient --> API

    style DomainCore fill:#ffd54f,stroke:#f57f17,stroke-width:3px
    style PrimaryPorts fill:#81c784,stroke:#388e3c,stroke-width:2px
    style SecondaryPorts fill:#81c784,stroke:#388e3c,stroke-width:2px
    style Primary fill:#e3f2fd,stroke:#1976d2,stroke-width:2px
    style Secondary fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px
```

**Key Principles:**

1. **Dependency Inversion**: Domain defines interfaces (ports), infrastructure implements them (adapters)
2. **Domain Core is Pure**: No infrastructure dependencies, no framework code
3. **Testability**: Domain can be tested in isolation with test doubles
4. **Technology Agnostic**: Infrastructure can be swapped without changing business logic

**Example (Hexagonal Architecture):**

```typescript theme={null}
// ===== DOMAIN CORE (Pure Business Logic) =====

// Domain Entity - No infrastructure dependencies
export class Workspace {
  private constructor(
    public readonly id: string,
    private _name: string,
    private _ownerId: string,
    private _isActive: boolean,
    public readonly createdAt: Date
  ) {}

  static create(name: string, ownerId: string): Workspace {
    // Business rule: Name must be 3-50 characters
    if (name.length < 3 || name.length > 50) {
      throw new DomainError('Workspace name must be 3-50 characters');
    }

    return new Workspace(
      generateId(),
      name,
      ownerId,
      true,
      new Date()
    );
  }

  rename(newName: string): void {
    if (newName.length < 3 || newName.length > 50) {
      throw new DomainError('Workspace name must be 3-50 characters');
    }
    this._name = newName;
  }

  archive(): void {
    if (!this._isActive) {
      throw new DomainError('Workspace is already archived');
    }
    this._isActive = false;
  }

  get name(): string { return this._name; }
  get ownerId(): string { return this._ownerId; }
  get isActive(): boolean { return this._isActive; }
}

// Secondary Port - Interface defined by domain
export interface WorkspaceRepository {
  findById(id: string): Promise<Workspace | null>;
  findByOwnerId(ownerId: string): Promise<Workspace[]>;
  save(workspace: Workspace): Promise<void>;
  delete(id: string): Promise<void>;
}

// Domain Service - Pure business logic
export class WorkspaceService {
  constructor(
    private readonly repository: WorkspaceRepository  // Depends on interface
  ) {}

  async createWorkspace(name: string, ownerId: string): Promise<Workspace> {
    // Business validation happens BEFORE persistence
    const workspace = Workspace.create(name, ownerId);

    await this.repository.save(workspace);

    return workspace;
  }

  async archiveWorkspace(id: string): Promise<void> {
    const workspace = await this.repository.findById(id);
    if (!workspace) {
      throw new DomainError('Workspace not found');
    }

    // Domain method encapsulates business rule
    workspace.archive();

    await this.repository.save(workspace);
  }
}

// ===== INFRASTRUCTURE (Adapters) =====

// Secondary Adapter - Implements domain interface
export class SupabaseWorkspaceRepository implements WorkspaceRepository {
  constructor(private readonly supabase: SupabaseClient) {}

  async findById(id: string): Promise<Workspace | null> {
    const { data } = await this.supabase
      .from('workspaces')
      .select('*')
      .eq('id', id)
      .single();

    return data ? this.toDomain(data) : null;
  }

  async save(workspace: Workspace): Promise<void> {
    await this.supabase
      .from('workspaces')
      .upsert(this.toDatabase(workspace));
  }

  // Mapping between database schema and domain model
  private toDomain(row: any): Workspace {
    return new Workspace(
      row.id,
      row.name,
      row.owner_id,
      row.is_active,
      new Date(row.created_at)
    );
  }

  private toDatabase(workspace: Workspace): any {
    return {
      id: workspace.id,
      name: workspace.name,
      owner_id: workspace.ownerId,
      is_active: workspace.isActive,
      created_at: workspace.createdAt.toISOString()
    };
  }
}

// Primary Adapter - API endpoint
export async function POST(request: Request) {
  const body = await request.json();

  // Dependency injection - provide implementation.
  // Note: Tuturuuu's createClient() (@tuturuuu/supabase/next/server) is async.
  const repository = new SupabaseWorkspaceRepository(await createClient());
  const service = new WorkspaceService(repository);

  const workspace = await service.createWorkspace(
    body.name,
    body.ownerId
  );

  return Response.json({ workspace });
}
```

#### Benefits of Hexagonal Architecture

✅ **Domain Logic is Pure and Testable**

```typescript theme={null}
// Test without any infrastructure
describe('Workspace', () => {
  it('enforces name length business rule', () => {
    expect(() => {
      Workspace.create('ab', 'owner-123');  // Too short
    }).toThrow('Workspace name must be 3-50 characters');
  });

  it('prevents archiving already archived workspace', () => {
    const workspace = Workspace.create('Test', 'owner-123');
    workspace.archive();

    expect(() => workspace.archive()).toThrow('Workspace is already archived');
  });
});
```

✅ **Technology Can Be Swapped Easily**

```typescript theme={null}
// Switch from Supabase to Drizzle - domain unchanged
const repository = new DrizzleWorkspaceRepository(db);
const service = new WorkspaceService(repository);
// All business logic works identically
```

✅ **Fast, Reliable Tests**

```typescript theme={null}
// In-memory test double - runs in milliseconds
class InMemoryWorkspaceRepository implements WorkspaceRepository {
  private workspaces = new Map<string, Workspace>();

  async findById(id: string) {
    return this.workspaces.get(id) || null;
  }

  async save(workspace: Workspace) {
    this.workspaces.set(workspace.id, workspace);
  }
}

// Test runs instantly, no database needed
const repo = new InMemoryWorkspaceRepository();
const service = new WorkspaceService(repo);
await service.createWorkspace('Test', 'owner-123');
```

***

### 3. Clean Architecture

Clean Architecture (by Robert C. Martin) is similar to Hexagonal but emphasizes concentric circles of dependencies.

```mermaid theme={null}
graph TD
    subgraph Layer4["Frameworks & Drivers<br/>(Outermost)"]
        FW["Database, Web,<br/>External APIs, UI"]
    end

    subgraph Layer3["Interface Adapters"]
        IA["Controllers,<br/>Presenters,<br/>Gateways"]
    end

    subgraph Layer2["Application Business Rules"]
        ABR["Use Cases,<br/>Application Services"]
    end

    subgraph Layer1["Enterprise Business Rules<br/>(Innermost)"]
        EBR["Entities,<br/>Domain Services"]
    end

    FW -.->|"Dependencies<br/>point INWARD"| IA
    IA -.->|"Dependencies<br/>point INWARD"| ABR
    ABR -.->|"Dependencies<br/>point INWARD"| EBR

    style Layer1 fill:#ffd54f,stroke:#f57f17,stroke-width:4px
    style Layer2 fill:#fff3e0,stroke:#f57c00,stroke-width:3px
    style Layer3 fill:#e3f2fd,stroke:#1976d2,stroke-width:2px
    style Layer4 fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px
```

**Key Rule**: Dependencies can only point inward. Inner circles know nothing about outer circles.

**Example Structure** (illustrative — these paths are not present in the repo):

```typescript theme={null}
// ===== INNERMOST: Enterprise Business Rules =====
// Illustrative: packages/types/src/domain/workspace.ts
export class Workspace {
  // Pure domain entity - no dependencies
}

// ===== APPLICATION LAYER: Use Cases =====
// Illustrative: src/application/use-cases/create-workspace.ts
export class CreateWorkspaceUseCase {
  constructor(
    private readonly repository: WorkspaceRepository,
    private readonly eventPublisher: EventPublisher
  ) {}

  async execute(command: CreateWorkspaceCommand): Promise<Workspace> {
    // Orchestrates domain entities and infrastructure
    const workspace = Workspace.create(command.name, command.ownerId);
    await this.repository.save(workspace);
    await this.eventPublisher.publish(new WorkspaceCreatedEvent(workspace));
    return workspace;
  }
}

// ===== INTERFACE ADAPTERS: Controllers =====
// Illustrative: src/app/api/workspaces/create/route.ts
export async function POST(request: Request) {
  const useCase = new CreateWorkspaceUseCase(repository, eventPublisher);
  const workspace = await useCase.execute(command);
  return Response.json(toDTO(workspace));
}

// ===== OUTERMOST: Frameworks & Drivers =====
// Infrastructure implementations (Supabase, Trigger.dev, etc.)
```

***

### 4. Onion Architecture

Onion Architecture is similar to Clean but visualizes layers as concentric circles with explicit layer names.

```mermaid theme={null}
graph TD
    subgraph Outer["Infrastructure Layer<br/>(Outer)"]
        Infra["Database,<br/>HTTP, etc"]
    end

    subgraph AppSvc["Application Services Layer"]
        App["Use Cases,<br/>Commands"]
    end

    subgraph DomSvc["Domain Services Layer"]
        DS["Business<br/>Operations"]
    end

    subgraph Core["Domain Model<br/>(Inner Core)"]
        DM["Entities,<br/>Value Objects,<br/>Rules"]
    end

    Infra --> AppSvc
    AppSvc --> DomSvc
    DomSvc --> Core

    style Core fill:#ffd54f,stroke:#f57f17,stroke-width:4px
    style DomSvc fill:#fff3e0,stroke:#f57c00,stroke-width:3px
    style AppSvc fill:#e3f2fd,stroke:#1976d2,stroke-width:2px
    style Outer fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px
```

All three patterns (Hexagonal, Clean, Onion) share the same core principle: **Dependency Inversion** to keep business logic pure and independent.

***

## Layering Within Microservices

### Microservices ≠ No Layering

**Common Misconception**: "Microservices replace layering."

**Reality**: Microservices is an **external** architectural pattern (how services are distributed across the network). Layering is an **internal** pattern (how code is organized within each service).

```mermaid theme={null}
graph TB
    subgraph MS["MICROSERVICES<br/>(External Architecture)"]
        subgraph ServiceA["Service A"]
            DomainA["Domain Core"]
            AdaptersA["Adapters"]
            DomainA ---|Internal<br/>Layers| AdaptersA
        end

        subgraph ServiceB["Service B"]
            DomainB["Domain Core"]
            AdaptersB["Adapters"]
            DomainB ---|Internal<br/>Layers| AdaptersB
        end

        subgraph ServiceC["Service C"]
            DomainC["Domain Core"]
            AdaptersC["Adapters"]
            DomainC ---|Internal<br/>Layers| AdaptersC
        end
    end

    Note["Each service has internal layers<br/>(Hexagonal, Clean, or Onion)"]

    ServiceA -.->|Events| ServiceB
    ServiceB -.->|Events| ServiceC
    ServiceC -.->|Events| ServiceA

    style DomainA fill:#ffd54f,stroke:#f57f17,stroke-width:2px
    style DomainB fill:#ffd54f,stroke:#f57f17,stroke-width:2px
    style DomainC fill:#ffd54f,stroke:#f57f17,stroke-width:2px
    style AdaptersA fill:#e3f2fd,stroke:#1976d2,stroke-width:2px
    style AdaptersB fill:#e3f2fd,stroke:#1976d2,stroke-width:2px
    style AdaptersC fill:#e3f2fd,stroke:#1976d2,stroke-width:2px
    style ServiceA fill:#f5f5f5,stroke:#616161,stroke-width:2px
    style ServiceB fill:#f5f5f5,stroke:#616161,stroke-width:2px
    style ServiceC fill:#f5f5f5,stroke:#616161,stroke-width:2px
    style MS fill:#fff,stroke:#000,stroke-width:3px
    style Note fill:#ffeb3b,stroke:#f57f17,stroke-width:2px
```

### Illustrative: Hexagonal Architecture Within a Service

<Warning>
  The directory tree below is an **illustrative target** showing how a service
  *could* be organized with strict hexagonal layers. It is **not** the current
  Tuturuuu layout — `apps/web/src` and `apps/finance/src` do not contain
  `domain/`, `application/`, or `infrastructure/` folders. See
  [Tuturuuu's Implementation](#tuturuuus-implementation) for the real structure.
</Warning>

```text theme={null}
# Aspirational hexagonal layout for a single service (not the current repo)
src/
├── domain/                    # Domain Core (Pure business logic)
│   ├── models/
│   │   └── workspace.ts       # Entities, Value Objects
│   └── services/
│       └── workspace-service.ts
├── application/               # Application Layer (Use Cases)
│   └── use-cases/
│       └── create-workspace.ts
├── infrastructure/            # Infrastructure (Adapters)
│   ├── repositories/
│   │   └── supabase-workspace-repository.ts
│   └── events/
│       └── trigger-publisher.ts
└── app/                       # Presentation (API Endpoints)
    └── api/workspaces/create/route.ts
```

**Why a team might adopt this approach:**

1. **Service Isolation**: Each deployable unit stays independently shippable
2. **Internal Quality**: Each service maintains clean internal architecture
3. **Technology Freedom**: Each service can use different infrastructure
4. **Testability**: Domain logic in each service is pure and testable
5. **Maintainability**: Clear structure within each service

In practice, Tuturuuu keeps most code in conventional Next.js folders and pushes
heavier backend logic into the Rust service (`apps/backend`) rather than
introducing a formal hexagonal folder hierarchy inside each frontend app.

***

## Layer-Based Architecture Inside Microservices (Deep Dive)

While microservices define how services communicate externally, the internal structure of each service is equally important. This section provides a comprehensive guide to implementing layer-based architecture within microservices.

### Why Layering Matters in Microservices

Many teams make the mistake of thinking: "We have microservices, so we don't need internal structure." This leads to:

* Business logic mixed with HTTP handling
* Database queries scattered throughout the codebase
* Difficult-to-test services
* Technology coupling within services

**The reality**: Each microservice should have clean internal architecture to maintain quality as services grow.

### Complete Layer-by-Layer Breakdown

#### Layer 1: Domain Core (Innermost)

**Purpose**: Contains pure business logic with zero external dependencies.

**Contents**:

* Entities (business objects with identity)
* Value Objects (immutable business concepts)
* Domain Services (complex business operations)
* Business Rules (validation, constraints)
* Domain Events (things that happened)

**Example - Complete Domain Layer** (illustrative path; the repo does not
contain a `src/domain/` folder):

```typescript theme={null}
// Illustrative: src/domain/models/workspace.ts
// Pure business entity - no infrastructure dependencies

export class Workspace {
  private constructor(
    public readonly id: string,
    private _name: string,
    private _ownerId: string,
    private _isActive: boolean,
    private _memberLimit: number,
    public readonly createdAt: Date
  ) {}

  // Factory method - enforces business rules
  static create(name: string, ownerId: string, memberLimit: number = 10): Workspace {
    // Business Rule: Name length
    if (name.length < 3 || name.length > 50) {
      throw new DomainError('Workspace name must be 3-50 characters');
    }

    // Business Rule: Member limit
    if (memberLimit < 1 || memberLimit > 1000) {
      throw new DomainError('Member limit must be 1-1000');
    }

    return new Workspace(
      generateId(),
      name,
      ownerId,
      true,
      memberLimit,
      new Date()
    );
  }

  // Domain behavior - business operations
  rename(newName: string): void {
    if (newName.length < 3 || newName.length > 50) {
      throw new DomainError('Workspace name must be 3-50 characters');
    }

    if (newName === this._name) {
      throw new DomainError('New name must be different');
    }

    this._name = newName;
  }

  archive(): void {
    if (!this._isActive) {
      throw new DomainError('Workspace is already archived');
    }
    this._isActive = false;
  }

  reactivate(): void {
    if (this._isActive) {
      throw new DomainError('Workspace is already active');
    }
    this._isActive = true;
  }

  // Business rule encapsulated in method
  canAddMember(currentMemberCount: number): boolean {
    return currentMemberCount < this._memberLimit;
  }

  // Getters
  get name(): string { return this._name; }
  get ownerId(): string { return this._ownerId; }
  get isActive(): boolean { return this._isActive; }
  get memberLimit(): number { return this._memberLimit; }
}

// Illustrative: src/domain/value-objects/email.ts
// Value Object - immutable, validated business concept
export class Email {
  private constructor(private readonly value: string) {}

  static create(email: string): Email {
    // Business rule: Valid email format
    if (!this.isValidEmail(email)) {
      throw new DomainError('Invalid email format');
    }
    return new Email(email.toLowerCase());
  }

  private static isValidEmail(email: string): boolean {
    return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email);
  }

  toString(): string {
    return this.value;
  }

  equals(other: Email): boolean {
    return this.value === other.value;
  }
}
```

**Testing Domain Layer:**

```typescript theme={null}
// Domain tests - no infrastructure needed
describe('Workspace Domain', () => {
  describe('create', () => {
    it('creates valid workspace', () => {
      const workspace = Workspace.create('My Workspace', 'owner-123', 50);

      expect(workspace.name).toBe('My Workspace');
      expect(workspace.ownerId).toBe('owner-123');
      expect(workspace.memberLimit).toBe(50);
      expect(workspace.isActive).toBe(true);
    });

    it('rejects short names', () => {
      expect(() => Workspace.create('ab', 'owner-123'))
        .toThrow('Workspace name must be 3-50 characters');
    });

    it('rejects invalid member limits', () => {
      expect(() => Workspace.create('Test', 'owner-123', 0))
        .toThrow('Member limit must be 1-1000');
    });
  });

  describe('rename', () => {
    it('allows renaming', () => {
      const workspace = Workspace.create('Test', 'owner-123');
      workspace.rename('New Name');
      expect(workspace.name).toBe('New Name');
    });

    it('rejects renaming to same name', () => {
      const workspace = Workspace.create('Test', 'owner-123');
      expect(() => workspace.rename('Test'))
        .toThrow('New name must be different');
    });
  });

  describe('canAddMember', () => {
    it('allows adding when under limit', () => {
      const workspace = Workspace.create('Test', 'owner-123', 10);
      expect(workspace.canAddMember(5)).toBe(true);
    });

    it('prevents adding when at limit', () => {
      const workspace = Workspace.create('Test', 'owner-123', 10);
      expect(workspace.canAddMember(10)).toBe(false);
    });
  });
});

// Tests run in milliseconds - no database, no network
```

#### Layer 2: Application Layer (Use Cases)

**Purpose**: Orchestrates domain entities and infrastructure to fulfill application workflows.

**Contents**:

* Use Cases (application workflows)
* Commands (input data structures)
* Application Services (workflow orchestration)
* DTOs (data transfer objects)

**Example - Complete Application Layer:**

```typescript theme={null}
// Illustrative: src/application/commands/create-workspace.command.ts
export interface CreateWorkspaceCommand {
  name: string;
  ownerId: string;
  memberLimit?: number;
}

// Illustrative: src/application/use-cases/create-workspace.usecase.ts
import { Workspace } from '@/domain/models/workspace';
import { WorkspaceRepository } from '@/domain/interfaces/workspace-repository';
import { EventPublisher } from '@/domain/interfaces/event-publisher';
import { WorkspaceCreatedEvent } from '@/domain/events/workspace-created.event';

export class CreateWorkspaceUseCase {
  constructor(
    private readonly repository: WorkspaceRepository,
    private readonly eventPublisher: EventPublisher,
    private readonly logger: Logger
  ) {}

  async execute(command: CreateWorkspaceCommand): Promise<Workspace> {
    this.logger.info('Creating workspace', { command });

    // 1. Create domain entity (business logic)
    const workspace = Workspace.create(
      command.name,
      command.ownerId,
      command.memberLimit || 10
    );

    // 2. Persist (infrastructure)
    await this.repository.save(workspace);
    this.logger.info('Workspace persisted', { workspaceId: workspace.id });

    // 3. Publish domain event (infrastructure)
    await this.eventPublisher.publish(
      new WorkspaceCreatedEvent(
        workspace.id,
        workspace.ownerId,
        workspace.name,
        new Date()
      )
    );
    this.logger.info('Workspace created event published', { workspaceId: workspace.id });

    return workspace;
  }
}

// Illustrative: src/application/use-cases/archive-workspace.usecase.ts
export class ArchiveWorkspaceUseCase {
  constructor(
    private readonly repository: WorkspaceRepository,
    private readonly eventPublisher: EventPublisher
  ) {}

  async execute(workspaceId: string, userId: string): Promise<void> {
    // 1. Load entity
    const workspace = await this.repository.findById(workspaceId);
    if (!workspace) {
      throw new ApplicationError('Workspace not found');
    }

    // 2. Check authorization (application-level concern)
    if (workspace.ownerId !== userId) {
      throw new UnauthorizedError('Only owner can archive workspace');
    }

    // 3. Execute domain operation
    workspace.archive();

    // 4. Persist changes
    await this.repository.save(workspace);

    // 5. Publish event
    await this.eventPublisher.publish(
      new WorkspaceArchivedEvent(workspace.id, userId, new Date())
    );
  }
}
```

**Testing Application Layer:**

```typescript theme={null}
// Use case tests - with test doubles
describe('CreateWorkspaceUseCase', () => {
  let useCase: CreateWorkspaceUseCase;
  let mockRepository: MockWorkspaceRepository;
  let mockEventPublisher: MockEventPublisher;
  let mockLogger: MockLogger;

  beforeEach(() => {
    mockRepository = new MockWorkspaceRepository();
    mockEventPublisher = new MockEventPublisher();
    mockLogger = new MockLogger();
    useCase = new CreateWorkspaceUseCase(
      mockRepository,
      mockEventPublisher,
      mockLogger
    );
  });

  it('creates and persists workspace', async () => {
    const command = {
      name: 'Test Workspace',
      ownerId: 'owner-123',
      memberLimit: 50
    };

    const workspace = await useCase.execute(command);

    // Verify workspace created correctly
    expect(workspace.name).toBe('Test Workspace');
    expect(workspace.ownerId).toBe('owner-123');

    // Verify repository called
    expect(mockRepository.saved).toHaveLength(1);
    expect(mockRepository.saved[0]).toBe(workspace);

    // Verify event published
    expect(mockEventPublisher.published).toHaveLength(1);
    expect(mockEventPublisher.published[0]).toBeInstanceOf(WorkspaceCreatedEvent);
  });

  it('propagates domain errors', async () => {
    const command = {
      name: 'ab', // Too short
      ownerId: 'owner-123'
    };

    await expect(useCase.execute(command))
      .rejects
      .toThrow('Workspace name must be 3-50 characters');
  });
});
```

#### Layer 3: Infrastructure Layer (Adapters)

**Purpose**: Implements infrastructure concerns and connects to external systems.

**Contents**:

* Repository Implementations (database access)
* Event Publishers (message brokers)
* External Service Clients (HTTP, gRPC)
* Caching Implementations
* File Storage Implementations

**Example - Complete Infrastructure Layer:**

```typescript theme={null}
// Illustrative: src/infrastructure/repositories/supabase-workspace.repository.ts
import { Workspace } from '@/domain/models/workspace';
import { WorkspaceRepository } from '@/domain/interfaces/workspace-repository';
import { SupabaseClient } from '@supabase/supabase-js';

export class SupabaseWorkspaceRepository implements WorkspaceRepository {
  constructor(private readonly supabase: SupabaseClient) {}

  async findById(id: string): Promise<Workspace | null> {
    const { data, error } = await this.supabase
      .from('workspaces')
      .select('*')
      .eq('id', id)
      .single();

    if (error || !data) return null;

    return this.toDomain(data);
  }

  async findByOwnerId(ownerId: string): Promise<Workspace[]> {
    const { data, error } = await this.supabase
      .from('workspaces')
      .select('*')
      .eq('owner_id', ownerId)
      .order('created_at', { ascending: false });

    if (error || !data) return [];

    return data.map(row => this.toDomain(row));
  }

  async save(workspace: Workspace): Promise<void> {
    const dbModel = this.toDatabase(workspace);

    const { error } = await this.supabase
      .from('workspaces')
      .upsert(dbModel);

    if (error) {
      throw new InfrastructureError(`Failed to save workspace: ${error.message}`);
    }
  }

  async delete(id: string): Promise<void> {
    const { error } = await this.supabase
      .from('workspaces')
      .delete()
      .eq('id', id);

    if (error) {
      throw new InfrastructureError(`Failed to delete workspace: ${error.message}`);
    }
  }

  // Mapping: Database schema → Domain model
  private toDomain(row: any): Workspace {
    // Use a reflection or factory method to create Workspace
    // bypassing constructor if needed for reconstruction
    return Object.assign(
      Object.create(Workspace.prototype),
      {
        id: row.id,
        _name: row.name,
        _ownerId: row.owner_id,
        _isActive: row.is_active,
        _memberLimit: row.member_limit,
        createdAt: new Date(row.created_at)
      }
    );
  }

  // Mapping: Domain model → Database schema
  private toDatabase(workspace: Workspace): any {
    return {
      id: workspace.id,
      name: workspace.name,
      owner_id: workspace.ownerId,
      is_active: workspace.isActive,
      member_limit: workspace.memberLimit,
      created_at: workspace.createdAt.toISOString()
    };
  }
}

// Illustrative: src/infrastructure/events/trigger-publisher.ts
//
// Tuturuuu uses Trigger.dev v4. Background work is modelled as `task()`
// definitions (in packages/trigger/src) that you enqueue with
// `myTask.trigger(payload)` — there is no v2-style `trigger.event(...)`,
// `client.defineJob`, or `eventTrigger`. The real tasks live in
// packages/trigger/src (e.g. scheduleTask, unifiedScheduleTask).
import { EventPublisher } from '@/domain/interfaces/event-publisher';
import { DomainEvent } from '@/domain/events/domain-event';
import { workspaceCreatedTask } from '@tuturuuu/trigger';

export class TriggerEventPublisher implements EventPublisher {
  async publish(event: DomainEvent): Promise<void> {
    // Enqueue a Trigger.dev v4 task run for the event.
    await workspaceCreatedTask.trigger({
      eventName: event.eventName,
      eventId: event.eventId,
      occurredAt: event.occurredAt.toISOString(),
      ...event.payload,
    });
  }

  async publishMany(events: DomainEvent[]): Promise<void> {
    await Promise.all(events.map((event) => this.publish(event)));
  }
}
```

For reference, the matching Trigger.dev v4 task definition looks like the real
tasks in `packages/trigger/src`:

```typescript theme={null}
// packages/trigger/src/<your-task>.ts (Trigger.dev v4 task() API)
import { task } from '@trigger.dev/sdk/v3';

export const workspaceCreatedTask = task({
  id: 'workspace-created',
  queue: { concurrencyLimit: 10 },
  run: async (payload: {
    eventName: string;
    eventId: string;
    occurredAt: string;
    [key: string]: unknown;
  }) => {
    // ...react to the event (notifications, projections, etc.)
    return { ok: true };
  },
});
```

#### Layer 4: Presentation Layer (API/UI)

**Purpose**: Handles HTTP requests, validates input, and returns responses.

**Contents**:

* API Route Handlers
* Request/Response DTOs
* Input Validation
* Authentication/Authorization
* HTTP Status Codes

**Example - Complete Presentation Layer:**

```typescript theme={null}
// Illustrative: src/app/api/workspaces/create/route.ts
import { NextRequest, NextResponse } from 'next/server';
import { z } from 'zod';
import { CreateWorkspaceUseCase } from '@/application/use-cases/create-workspace.usecase';
import { SupabaseWorkspaceRepository } from '@/infrastructure/repositories/supabase-workspace.repository';
import { TriggerEventPublisher } from '@/infrastructure/events/trigger-publisher';
// In Tuturuuu, createClient() from @tuturuuu/supabase/next/server is ASYNC.
import { createClient } from '@tuturuuu/supabase/next/server';

// Request validation schema
const CreateWorkspaceSchema = z.object({
  name: z.string().min(3).max(50),
  memberLimit: z.number().min(1).max(1000).optional()
});

export async function POST(request: NextRequest) {
  try {
    // 1. Authentication (await the async client factory)
    const supabase = await createClient();
    const { data: { session } } = await supabase.auth.getSession();

    if (!session) {
      return NextResponse.json(
        { error: 'Unauthorized' },
        { status: 401 }
      );
    }

    // 2. Parse and validate request body
    const body = await request.json();
    const validation = CreateWorkspaceSchema.safeParse(body);

    if (!validation.success) {
      return NextResponse.json(
        { error: 'Invalid request', details: validation.error.issues },
        { status: 400 }
      );
    }

    // 3. Dependency injection - wire up layers
    const repository = new SupabaseWorkspaceRepository(supabase);
    const eventPublisher = new TriggerEventPublisher();
    const logger = console; // Or proper logger

    const useCase = new CreateWorkspaceUseCase(
      repository,
      eventPublisher,
      logger
    );

    // 4. Execute use case
    const workspace = await useCase.execute({
      name: validation.data.name,
      ownerId: session.user.id,
      memberLimit: validation.data.memberLimit
    });

    // 5. Return response
    return NextResponse.json(
      {
        workspace: {
          id: workspace.id,
          name: workspace.name,
          ownerId: workspace.ownerId,
          isActive: workspace.isActive,
          memberLimit: workspace.memberLimit,
          createdAt: workspace.createdAt.toISOString()
        }
      },
      { status: 201 }
    );

  } catch (error) {
    // Error handling
    if (error instanceof DomainError) {
      return NextResponse.json(
        { error: error.message },
        { status: 400 }
      );
    }

    if (error instanceof UnauthorizedError) {
      return NextResponse.json(
        { error: error.message },
        { status: 403 }
      );
    }

    console.error('Unexpected error:', error);
    return NextResponse.json(
      { error: 'Internal server error' },
      { status: 500 }
    );
  }
}
```

### Layer Communication Patterns

```mermaid theme={null}
graph TD
    User["User/Client"]

    subgraph Service["Microservice"]
        Presentation["Presentation Layer<br/>(API Route)"]
        Application["Application Layer<br/>(Use Case)"]
        Domain["Domain Layer<br/>(Entity)"]
        Infrastructure["Infrastructure Layer<br/>(Repository)"]
    end

    DB[("Database")]

    User -->|HTTP Request| Presentation
    Presentation -->|Execute| Application
    Application -->|Create/Load| Domain
    Domain -->|Business Rules| Domain
    Application -->|Save| Infrastructure
    Infrastructure -->|SQL| DB

    Presentation -.->|Response| User

    style Domain fill:#ffd54f,stroke:#f57f17,stroke-width:3px
    style Application fill:#fff3e0,stroke:#f57c00,stroke-width:2px
    style Presentation fill:#e3f2fd,stroke:#1976d2,stroke-width:2px
    style Infrastructure fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px
```

### Testing Strategy Per Layer

| Layer              | Test Type             | Speed        | Infrastructure Needed | Coverage Target |
| ------------------ | --------------------- | ------------ | --------------------- | --------------- |
| **Domain**         | Unit Tests            | Milliseconds | None                  | 100%            |
| **Application**    | Unit Tests with Mocks | Milliseconds | None                  | 90%+            |
| **Infrastructure** | Integration Tests     | Seconds      | Database, Services    | 70%+            |
| **Presentation**   | Integration Tests     | Seconds      | Full stack            | 60%+            |

### Comparison: N-Tier vs Hexagonal in Microservices

```mermaid theme={null}
graph TB
    subgraph NTier["Microservice with N-Tier"]
        NT_API["API Layer"]
        NT_BLL["Business Logic Layer"]
        NT_DAL["Data Access Layer"]

        NT_API --> NT_BLL
        NT_BLL --> NT_DAL
        NT_DAL -.->|Tight Coupling| NT_BLL
    end

    subgraph Hex["Microservice with Hexagonal"]
        H_API["API Adapter"]
        H_UseCase["Use Case"]
        H_Domain["Domain Core"]
        H_Repo["Repository Adapter"]

        H_API --> H_UseCase
        H_UseCase --> H_Domain
        H_Domain --> H_Repo
    end

    style NT_BLL fill:#ffcdd2,stroke:#c62828,stroke-width:2px
    style H_Domain fill:#c8e6c9,stroke:#2e7d32,stroke-width:2px
```

**N-Tier within Microservice:**

* ❌ Business logic coupled to database
* ❌ Hard to test without infrastructure
* ❌ Technology lock-in within service
* ✅ Simpler for trivial services

**Hexagonal within Microservice:**

* ✅ Business logic is pure and testable
* ✅ Technology can be swapped per service
* ✅ High test coverage achievable
* ❌ More code and structure needed

### Deployment Considerations

Each app deploys independently. Tuturuuu does **not** expose `bun deploy:web` /
`bun deploy:finance` / `bun deploy:calendar` scripts — deployment is driven by
CI/CD (GitHub Actions) and Docker images, and each app's `package.json` ships
conventional `dev`, `build`, `start`, and `test` scripts (for example
`apps/web` builds with `next build --turbopack`). Verify the current scripts in
each app's `package.json` before quoting commands.

```bash theme={null}
# Build / run a single app locally (real scripts in apps/web/package.json)
$ cd apps/web && bun run build   # next build --turbopack
$ cd apps/web && bun start       # next start on port 7803

# Each app is a conventional Next.js App Router app sharing one Supabase
# project; heavier backend logic increasingly lives in apps/backend (Rust).
```

### Key Takeaways

1. **Microservices ≠ No Internal Structure**: Each service needs clean internal architecture
2. **Hexagonal Within Services**: Provides testability and maintainability per service
3. **Layer Discipline**: Strict layer boundaries prevent architectural decay
4. **Independent Evolution**: Each service can evolve its internals independently
5. **Consistent Patterns**: Same layering approach across services aids understanding

***

## Comparison Matrix

| Aspect                     | N-Tier                                            | Hexagonal/Clean/Onion          | Microservices                    |
| -------------------------- | ------------------------------------------------- | ------------------------------ | -------------------------------- |
| **Scope**                  | Internal organization                             | Internal organization          | External distribution            |
| **Dependencies**           | Downward (UI→BLL→DAL)                             | Inward (Infrastructure→Domain) | Service-to-service via events    |
| **Coupling**               | Tight (layers depend on concrete implementations) | Loose (depends on interfaces)  | Very loose (event-driven)        |
| **Testability**            | Hard (requires database)                          | Easy (pure domain logic)       | Moderate (contract testing)      |
| **Technology Flexibility** | Low (framework lock-in)                           | High (swappable adapters)      | Very high (per-service choice)   |
| **Deployment Unit**        | Entire application                                | Entire application             | Individual service               |
| **Scalability**            | All-or-nothing                                    | All-or-nothing                 | Granular per service             |
| **Complexity**             | Low                                               | Moderate                       | High                             |
| **Best For**               | Simple CRUD apps                                  | Complex business logic         | Distributed systems, large teams |

***

## When to Use Each Pattern

### Use N-Tier When:

* ✅ Building simple CRUD applications
* ✅ Team is unfamiliar with DDD/Hexagonal concepts
* ✅ Rapid prototyping with acceptable technical debt
* ✅ Application will remain small (\<10k LOC)

### Use Hexagonal/Clean/Onion When:

* ✅ Complex business logic requires protection
* ✅ Long-term maintainability is critical
* ✅ Need to swap infrastructure components
* ✅ High test coverage is required
* ✅ Domain experts are involved in development

### Use Microservices When:

* ✅ Multiple teams working on different domains
* ✅ Need independent deployment and scaling
* ✅ Different parts of system have different technology needs
* ✅ Can handle distributed system complexity
* ✅ Have DevOps maturity for service orchestration

### Tuturuuu's Pragmatic Choice

Tuturuuu favors pragmatism over textbook purity:

* **Multiple deployable apps** (`apps/web`, `apps/finance`, `apps/calendar`,
  the Rust `apps/backend`, ...) for organizational agility and independent
  deployment.
* **Conventional Next.js App Router structure** inside each frontend app
  (`app/`, `components/`, `lib/`, `utils/`, `features/`) rather than a formal
  hexagonal `domain/application/infrastructure` hierarchy. Shared logic lives in
  `packages/*`; cross-app data access goes through `packages/internal-api`
  helpers and REST `/api/v1` routes.
* **Heavier backend logic moving into the Rust service** (`apps/backend`),
  where layering and typed domain modules increasingly live as part of the
  [TanStack + Rust migration](/platform/architecture/tanstack-rust-migration).

The hexagonal samples above remain useful for *reasoning about* boundaries and
testability, even though the repository does not enforce that exact folder
shape.

***

## Evolution Path

Many systems evolve through these patterns:

```mermaid theme={null}
graph TD
    Step1["Simple App<br/>(N-Tier)"]
    Step2["Modular Monolith<br/>(Hexagonal)"]
    Step3["Microservices with<br/>Hexagonal Architecture"]

    Step1 -->|"Business logic<br/>becomes complex"| Step2
    Step2 -->|"Team grows,<br/>need independent<br/>deployment"| Step3

    style Step1 fill:#ffcdd2,stroke:#c62828,stroke-width:2px
    style Step2 fill:#fff3e0,stroke:#f57c00,stroke-width:2px
    style Step3 fill:#c8e6c9,stroke:#2e7d32,stroke-width:3px
```

**Where Tuturuuu sits today.** Rather than formally adopting "Step 3"
(microservices with strict hexagonal layering), Tuturuuu runs several
conventional Next.js App Router apps backed by a shared Supabase project, with
shared logic in `packages/*` and an emerging Rust backend (`apps/backend`). The
practical trajectory is toward the TanStack Start frontend
(`apps/tanstack-web`) plus the Rust backend rather than toward per-app
hexagonal folder hierarchies — see the
[TanStack + Rust migration](/platform/architecture/tanstack-rust-migration).
Treat the steps above as a conceptual maturity model, not a literal description
of the repository.

***

## Anti-Patterns to Avoid

### ❌ Hexagonal Architecture Without Discipline

```typescript theme={null}
// BAD: "Hexagonal" in name only
export class WorkspaceService {
  constructor(private readonly repository: WorkspaceRepository) {}

  async createWorkspace(name: string, ownerId: string) {
    // WRONG: Direct Supabase usage bypasses repository
    const { data } = await supabase.from('workspaces').insert({ name, owner_id: ownerId });
    return data;
  }
}
// This defeats the purpose of Hexagonal Architecture
```

### ❌ Distributed Monolith

```typescript theme={null}
// BAD: Microservices with tight coupling
// Service A
export async function createWorkspace(data: CreateWorkspaceData) {
  const workspace = await db.insert(data);

  // WRONG: Synchronous HTTP call to Service B
  await fetch('http://service-b/setup', {
    method: 'POST',
    body: JSON.stringify({ workspaceId: workspace.id })
  });

  return workspace;
}
// This is a distributed monolith, not microservices
```

### ❌ No Layering in Microservices

```typescript theme={null}
// BAD: API route with all logic mixed together
export async function POST(request: Request) {
  const body = await request.json();

  // Validation
  if (body.name.length < 3) return Response.json({ error: 'Too short' }, { status: 400 });

  // Database
  const { data } = await supabase.from('workspaces').insert(body);

  // Events (Trigger.dev v4: enqueue a task run, not v2 trigger.event(...))
  await workspaceCreatedTask.trigger({ ...data });

  return Response.json(data);
}
// No separation of concerns, hard to test, hard to maintain
```

***

## Tuturuuu's Implementation

### Actual Project Structure

This is the **real** repository layout (verified against the codebase). Apps are
conventional Next.js App Router apps — there are no `domain/`, `application/`, or
`infrastructure/` folders.

```text theme={null}
tuturuuu/
├── apps/                          # Independently deployable apps
│   ├── web/                       # Main platform (Next.js, port 7803)
│   │   └── src/
│   │       ├── app/               # App Router routes + /api endpoints
│   │       ├── components/
│   │       ├── features/          # Feature modules (forms, reports, ...)
│   │       ├── hooks/
│   │       ├── lib/
│   │       └── utils/
│   ├── finance/                   # Finance app (Next.js)
│   │   └── src/                   # app/, components/, lib/, utils/, ...
│   ├── calendar/                  # Calendar app (Next.js)
│   │   └── src/                   # app/, components/, lib/, constants/, ...
│   ├── tanstack-web/              # TanStack Start replacement for apps/web
│   └── backend/                   # Rust backend (port 7820)
│       └── src/                   # aurora.rs, inventory.rs, lib.rs, ...
└── packages/                      # Shared libraries (workspace:*)
    ├── types/                     # Shared types (DB types in @tuturuuu/types/db)
    ├── ui/                        # Shared UI components
    ├── supabase/                  # Shared Supabase client factories
    ├── internal-api/              # Cross-app data access helpers
    └── trigger/                   # Trigger.dev v4 task() definitions
```

<Note>
  **Where backend layering lives.** Newer/heavier backend logic is implemented in
  the Rust service (`apps/backend/src`, e.g. `aurora.rs`, `inventory.rs`,
  `onboarding_progress.rs`) rather than as a layered TypeScript hierarchy inside
  each frontend app. Frontends reach shared app data through
  `packages/internal-api` and REST `/api/v1` routes. (A repo guard,
  `check-tanstack-api-access`, forbids `apps/tanstack-web/src` from calling
  `/trpc` — the tRPC surface in `apps/web/src/trpc` is a stub, not the product
  data path.)
</Note>

### How the Real Flow Maps to These Layers

You can still reason about a real Tuturuuu request in layered terms, even though
the folders are flat:

* **Presentation** — an App Router route handler in `apps/web/src/app/api/...`
  (or a TanStack Start route in `apps/tanstack-web`).
* **Application / orchestration** — helpers in `lib/`, `features/`,
  `packages/internal-api`, or background `task()` runs in `packages/trigger`.
* **Domain rules** — validation and business logic colocated with the feature
  (or enforced in the Rust backend).
* **Infrastructure** — the shared Supabase client from
  `@tuturuuu/supabase/next/server` and the Rust backend's data access.

```typescript theme={null}
// Real shape: an App Router API route in apps/web/src/app/api/...
import { NextRequest, NextResponse } from 'next/server';
import { createClient } from '@tuturuuu/supabase/next/server';
import { workspaceCreatedTask } from '@tuturuuu/trigger';

export async function POST(request: NextRequest) {
  // createClient() is ASYNC in Tuturuuu — await it.
  const supabase = await createClient();
  const body = await request.json();

  // Presentation-level validation
  if (typeof body.name !== 'string' || body.name.length < 3) {
    return NextResponse.json({ error: 'Name too short' }, { status: 400 });
  }

  // Infrastructure: shared Supabase project
  const { data, error } = await supabase
    .from('workspaces')
    .insert({ name: body.name, owner_id: body.ownerId })
    .select()
    .single();

  if (error) {
    return NextResponse.json({ error: error.message }, { status: 500 });
  }

  // Background work via Trigger.dev v4 task()
  await workspaceCreatedTask.trigger({ workspaceId: data.id });

  return NextResponse.json({ workspace: data }, { status: 201 });
}
```

The layered patterns earlier in this page are a lens for keeping responsibilities
clear; the snippet above shows what that looks like in the conventional
structure Tuturuuu actually ships.

***

## Related Documentation

* [Hexagonal Architecture](/platform/architecture/system-design/hexagonal-architecture) - Detailed ports and adapters implementation
* [Microservices Patterns](/platform/architecture/system-design/microservices-patterns) - Service boundaries and communication
* [Architectural Decisions](/platform/architecture/system-design/architectural-decisions) - Why we chose this architecture
* [Quality Attributes](/platform/architecture/system-design/quality-attributes) - Maintainability and testability benefits
* [Encapsulation Patterns](/platform/architecture/system-design/encapsulation-patterns) - Preventing unwanted coupling


# Microservices Patterns
Source: https://docs.tuturuuu.com/platform/architecture/system-design/microservices-patterns

Service boundaries, communication patterns, and deployment strategies in Tuturuuu's monorepo architecture

Tuturuuu uses a **monorepo of conventional Next.js App Router apps** that share one
Supabase project plus a growing set of workspace packages. We describe this as a
"microservices-within-a-monorepo" style: each app deploys independently and owns a
product surface, but they are not isolated services with private databases or an
inter-service token mesh. This page documents the patterns we actually use today,
and flags where the platform is mid-migration.

<Note>
  **Active migration.** The legacy `apps/web` Next.js runtime (port `7803`) is being
  replaced by `apps/tanstack-web` (TanStack Start) for the frontend and
  `apps/backend` (Rust) for the API layer. See
  [TanStack Start And Rust Migration](/platform/architecture/tanstack-rust-migration)
  for the migration contract and
  `apps/tanstack-web/migration/route-manifest.json` for live route-by-route
  progress. Treat the tRPC and Next.js REST sections below as the *legacy*
  `apps/web` path; new read/write endpoints increasingly land in the Rust backend.
</Note>

## Service Boundaries

### Current Services

| Service          | Location            | Purpose                                  | Database              | Tech Stack                                      |
| ---------------- | ------------------- | ---------------------------------------- | --------------------- | ----------------------------------------------- |
| **web** (legacy) | `apps/web`          | Main platform application (port `7803`)  | Supabase (PostgreSQL) | Next.js (App Router), React 19                  |
| **tanstack-web** | `apps/tanstack-web` | Replacement frontend for `apps/web`      | Supabase (shared)     | TanStack Start + Router + Query, Vite, React 19 |
| **backend**      | `apps/backend`      | Dedicated Rust API runtime (port `7820`) | Supabase (shared)     | Rust (Axum), Cloudflare Workers-ready           |
| **rewise**       | `apps/rewise`       | AI-powered chatbot                       | Supabase (shared)     | Next.js, AI SDK                                 |
| **nova**         | `apps/nova`         | Prompt engineering platform              | Supabase (shared)     | Next.js, AI SDK                                 |
| **calendar**     | `apps/calendar`     | Calendar & scheduling                    | Supabase (shared)     | Next.js, React                                  |
| **finance**      | `apps/finance`      | Finance management                       | Supabase (shared)     | Next.js, React                                  |
| **tasks**        | `apps/tasks`        | Task management (hierarchical)           | Supabase (shared)     | Next.js, React                                  |
| **meet**         | `apps/meet`         | Meeting management                       | Supabase (shared)     | Next.js, React                                  |
| **shortener**    | `apps/shortener`    | URL shortener service                    | Supabase (shared)     | Next.js                                         |
| **database**     | `apps/database`     | Database migrations & schema             | Supabase              | SQL, TypeScript                                 |
| **discord**      | `apps/discord`      | Discord bot utilities                    | None (stateless)      | Python                                          |

Additional product apps (`apps/chat`, `apps/drive`, `apps/mail`, `apps/cms`,
`apps/mind`, `apps/teach`, `apps/track`, `apps/storefront`, and others) follow the
same conventional Next.js App Router shape and share the same Supabase project.

<Warning>
  All these apps share **one** Supabase project. There are no per-app distinct
  Supabase keys, no per-service databases, and no inter-service token system in
  the codebase today. "Service-specific databases" and an inter-service token
  mesh are aspirational patterns discussed later, not implemented reality.
</Warning>

### Shared Packages

All services share common infrastructure via workspace packages:

```
packages/
├── ui/           # Shared UI components (Shadcn)
├── ai/           # AI integration utilities
├── supabase/     # Supabase client wrappers
├── types/        # Shared TypeScript types (including generated DB types)
├── utils/        # Cross-cutting utilities
├── trigger/      # Background job definitions (Trigger.dev v4)
├── payment/      # Payment processing (Polar provider)
├── internal-api/ # Typed helpers for app REST endpoints
└── ... (many shared packages)
```

## Monorepo Architecture

### Benefits

1. **Shared Code**: Common utilities, UI components, types shared across services
2. **Atomic Changes**: Change types in one commit, update all services
3. **Simplified Tooling**: Single build system (Turborepo + Bun)
4. **Easy Refactoring**: Move code between services, extract packages
5. **Consistent Standards**: Shared linting, testing, deployment configs

### Structure

```
platform/
├── apps/                  # Independent microservices
│   ├── web/              # Main app (port 7803)
│   ├── rewise/           # AI chat
│   ├── nova/             # Prompt engineering
│   └── ... (other apps)
├── packages/              # Shared libraries
│   ├── ui/               # Component library
│   ├── types/            # Shared types
│   └── ... (other packages)
├── turbo.json            # Turborepo configuration
└── package.json          # Workspace root
```

### Workspace Dependencies

Services declare dependencies on shared packages:

```json theme={null}
// apps/web/package.json
{
  "name": "@tuturuuu/web",
  "dependencies": {
    "@tuturuuu/ui": "workspace:*",
    "@tuturuuu/types": "workspace:*",
    "@tuturuuu/supabase": "workspace:*",
    "@tuturuuu/ai": "workspace:*",
    "@tuturuuu/utils": "workspace:*"
  }
}

// apps/rewise/package.json
{
  "name": "@tuturuuu/rewise",
  "dependencies": {
    "@tuturuuu/ui": "workspace:*",
    "@tuturuuu/types": "workspace:*",
    "@tuturuuu/ai": "workspace:*"
    // Note: Different subset of packages
  }
}
```

## Communication Patterns

### 1. Background Jobs (Trigger.dev v4)

**When to use:** Asynchronous workflows, background processing, scheduled work

**Implementation:** Trigger.dev v4 (`@trigger.dev/sdk` `^4.4.5`), using the
`task()` API. Task definitions live in `packages/trigger/src`.

The v2/v3 `client.defineJob` / `eventTrigger` / `io.runTask` APIs do **not** exist
in this repo. Define a task with `task()` and run it from app code with
`tasks.trigger(...)` (or `<task>.trigger(...)`):

```typescript theme={null}
// packages/trigger/src/schedule-tasks.ts
import { task } from '@trigger.dev/sdk/v3';
import { schedulableTasksHelper } from './schedule-tasks-helper';

export const scheduleTask = task({
  id: 'schedule-task',
  queue: { concurrencyLimit: 10 },
  run: async (payload: { ws_id: string }) => {
    const result = await schedulableTasksHelper(payload.ws_id);
    if (!result.success) {
      throw new Error(result.error || 'Schedule tasks failed');
    }
    return { ws_id: payload.ws_id, ...result, success: true };
  },
});
```

```typescript theme={null}
// Producer: trigger the task from app code (e.g. an apps/web API route)
import { tasks } from '@trigger.dev/sdk/v3';
import type { scheduleTask } from '@tuturuuu/trigger';

await tasks.trigger<typeof scheduleTask>('schedule-task', {
  ws_id: workspaceId,
});
```

> The import path is `@trigger.dev/sdk/v3` even though the installed SDK is the
> v4 line — that path is the current entrypoint for the `task()` API.

**Characteristics:**

* Loose coupling: producers fire-and-forget, tasks run out of band
* Resilient to failures, with built-in retries and queue concurrency limits
* Asynchronous processing
* Run history and replay in the Trigger.dev dashboard

### 2. Shared Database (Current)

**When to use:** Strong consistency requirements, complex queries across entities

**Implementation:** Supabase PostgreSQL with RLS

```typescript theme={null}
import { createClient } from '@tuturuuu/supabase/next/server';

// Both apps/web and apps/finance access the same Supabase project.
// createClient() is async — await it.
const supabase = await createClient();

// Row-Level Security ensures data isolation
const { data } = await supabase
  .from('workspaces')
  .select('*')
  .eq('id', workspaceId);
// RLS automatically filters by user permissions
```

**Characteristics:**

* Strong consistency
* ACID transactions
* Complex joins possible
* Shared schema (requires coordination)

**Trade-offs:**

* ✅ Simple implementation
* ✅ Strong consistency
* ❌ Tight coupling at data layer
* ❌ Schema changes affect multiple services

### 3. tRPC (legacy `apps/web`, currently a stub)

**Status:** The tRPC layer in `apps/web/src/trpc` is intentionally a **stub**. The
router (`apps/web/src/trpc/routers/_app.ts`) exports a single `healthCheck`
`baseProcedure` to keep the type system wired up:

```typescript theme={null}
// apps/web/src/trpc/routers/_app.ts (actual contents)
import { baseProcedure, createTRPCRouter } from '../init';

export const appRouter = createTRPCRouter({
  healthCheck: baseProcedure.query(() => {
    return { status: 'ok', timestamp: Date.now() };
  }),
});

export type AppRouter = typeof appRouter;
```

The real exports are `createTRPCRouter`, `createTRPCContext`, `baseProcedure`, and
`createCallerFactory`. There is **no** `protectedProcedure`, no auth middleware,
and no workspace/user/tasks/ai routers — the context is not a product data layer.
Product data flows through `@tuturuuu/internal-api` helpers and REST
`/api/v1/*` routes (below), not through tRPC. In `apps/tanstack-web` a guard
(`check-tanstack-api-access`) forbids `/trpc` calls entirely.

Do not document tRPC as the canonical internal API surface — it is a thin
compatibility shim that may be removed during the migration.

### 4. REST API (`/api/v1`, legacy `apps/web`) and the Rust backend

**When to use:** Public APIs, webhook endpoints, third-party integrations, and
product read/write endpoints.

**Legacy implementation:** Next.js App Router route handlers under
`apps/web/src/app/api/v1/*` (e.g. `workspaces`, `inventory`, `nova`, `storage`):

```typescript theme={null}
// apps/web/src/app/api/v1/workspaces/route.ts
import { createClient } from '@tuturuuu/supabase/next/server';

export async function POST(request: Request) {
  const supabase = await createClient(); // async — await it
  const body = await request.json();

  // Validate, authenticate, execute
  const workspace = await createWorkspace(supabase, body);

  return Response.json({ workspace }, { status: 201 });
}
```

**Migration target:** The Rust backend (`apps/backend`, port `7820`) is
progressively taking ownership of these endpoints. Route groups live in
`apps/backend/src/*.rs` (for example `inventory.rs`, `nova.rs`,
`onboarding_progress.rs`, `aurora.rs`), and the contract is documented in
`apps/backend/api/openapi.yaml`. Migration progress per endpoint is tracked in
`apps/tanstack-web/migration/route-manifest.json`.

**Characteristics:**

* Standard HTTP / JSON
* Versioned endpoints (`/api/v1/...`)
* Rate limiting and authentication
* OpenAPI documentation for the Rust backend (`apps/backend/api/openapi.yaml`)

## Service Communication Matrix

| From         | To           | Pattern        | Protocol         | Use Case                                 |
| ------------ | ------------ | -------------- | ---------------- | ---------------------------------------- |
| any app      | Supabase     | Shared DB      | PostgreSQL + RLS | Read/write product data (primary path)   |
| any app      | Trigger.dev  | Background job | `task()` trigger | Async/scheduled work                     |
| External     | app          | REST API       | HTTP/JSON        | Public API access (`/api/v1/...`)        |
| tanstack-web | backend      | REST           | HTTP/JSON        | Migrated read/write endpoints (Rust)     |
| app (client) | app (server) | TanStack Query | HTTP/JSON        | Client fetching via internal-api helpers |
| discord      | web          | Webhook        | HTTP/JSON        | Discord bot commands                     |

Most cross-surface coordination is **not** direct service-to-service RPC: apps
share the Supabase database (guarded by RLS) and hand off long-running work to
Trigger.dev. This keeps coupling at the data and job layers rather than in a
service mesh.

## Deployment Strategies

### Next.js apps: Vercel

Each Next.js app deploys independently to Vercel. CI builds the selected app,
packages prebuilt artifacts, and deploys the production artifact through the
matching GitHub Actions workflow.

There is one Vercel workflow per app, named by product surface. For example,
`vercel-production-platform.yaml` builds `apps/web` on pushes to the `production`
branch and deploys the prebuilt production artifact:

```yaml theme={null}
# .github/workflows/vercel-production-platform.yaml (abridged)
name: Vercel Platform Production Deployment
on:
  push:
    branches: [production]
  workflow_dispatch:

jobs:
  Deploy-Production:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - uses: actions/setup-node@v6
        with:
          node-version: 24
      - uses: ./.github/actions/setup-bun-with-retry
        with:
          bun-version: 1.3.14
      - run: bash scripts/ci/run-with-backoff.sh bun install
      # Pull env, build the Vercel artifact, and deploy the prebuilt output.
      - run: vercel pull --yes --environment=production --token=${{ secrets.VERCEL_TOKEN }}
      - run: vercel build --prod --token=${{ secrets.VERCEL_TOKEN }}
      - run: vercel deploy --archive=tgz --prebuilt --prod --token=${{ secrets.VERCEL_TOKEN }}
```

Matching `vercel-preview-*.yaml` workflows run for pull requests. Node engines are
`>=22` (CI uses Node 24) and Bun is pinned to `1.3.14`.

### Rust backend

`apps/backend` is built and validated by `.github/workflows/rust-backend.yml`.
It runs as a native container and keeps a Cloudflare Workers Rust entrypoint
(`apps/backend/wrangler.jsonc`) ready for edge preview deployment, per the
[migration contract](/platform/architecture/tanstack-rust-migration).

### Independent Scaling

Each app scales independently on its hosting platform (Vercel autoscaling for the
Next.js apps; container/edge scaling for the Rust backend). The per-app
`minInstances`/`maxInstances` objects shown in earlier versions of this page were
illustrative, not a real config file in the repo — scaling is configured in the
Vercel project settings and the backend's container/edge runtime, not in
versioned source.

## Service Boundary Decisions

### When to Create a New Service

✅ **Extract to new service when:**

* Feature is logically independent (e.g., URL shortener)
* Different scaling requirements (high-traffic vs low-traffic)
* Different technology needs (Python for ML vs TypeScript for web)
* Team ownership boundary (separate team owns feature)
* Independent deployment cycle needed

❌ **Keep in existing service when:**

* Shares most code with existing service
* Tight coupling to core domain
* Low complexity (\< 1000 LOC)
* No special scaling or technology needs

### Example: Why `finance` is a separate app

```
Reasons:
✅ Logically independent domain (finance vs tasks)
✅ Can be worked on by dedicated team
✅ Independent deployment for finance updates
✅ Future: Could use different database for financial data

Alternatives considered:
❌ Module in web app - harder to maintain boundaries
❌ Separate package - loses deployment independence
```

## Data Ownership

### Current: Shared Database Pattern

**Pros:**

* Simple joins across entities
* Strong consistency
* ACID transactions
* Single source of truth

**Cons:**

* Tight coupling at data layer
* Schema changes affect multiple services
* Harder to scale independently

### Aspirational: Service-Specific Databases

<Note>
  This is **not implemented today.** Every app shares one Supabase project. The
  following is a future option, not current architecture.
</Note>

**When to consider:**

* A surface needs a specialized database (e.g., PostGIS for geolocation)
* Independent scaling requirements for specific data
* Strong service boundaries needed

**Illustrative pattern (not in the codebase):**

```typescript theme={null}
import { createClient } from '@tuturuuu/supabase/next/server';

// Today: every app uses the shared Supabase project.
const db = await createClient(); // createClient() is async — await it

// Hypothetical future: a dedicated DB plus a background task to keep
// derived data in sync, triggered via Trigger.dev's task() API.
// await tasks.trigger('record-transaction', { /* ... */ });
```

## Package Extraction Strategy

### When to Extract to Package

The repo's root `AGENTS.md` carries the package-extraction decision matrix. As a
rough heuristic, **extract when ≥3 HIGH signals:**

| Signal           | Extract Now (HIGH)             |
| ---------------- | ------------------------------ |
| Reuse Breadth    | Actively duplicated in ≥2 apps |
| Complexity       | >150 LOC multi-module          |
| Domain Ownership | Pure cross-domain utility      |
| Testing Needs    | Comprehensive tests stable     |

**Example extractions in Tuturuuu:**

```
@tuturuuu/ui → Shared across all apps
@tuturuuu/types → Used by all services
@tuturuuu/supabase → Client wrapper used everywhere
@tuturuuu/ai → Shared AI utilities (rewise, nova, web)
```

## Testing Strategies

### Unit Tests

Test individual services in isolation:

```typescript theme={null}
// apps/web/src/__tests__/workspace.test.ts
import { createWorkspace } from '../lib/workspace';

describe('Workspace Service', () => {
  it('creates workspace with valid data', async () => {
    const workspace = await createWorkspace({
      ownerId: 'user-1',
      name: 'Test Workspace'
    });

    expect(workspace.name).toBe('Test Workspace');
  });
});
```

### Integration Tests

Test service interactions:

```typescript theme={null}
// apps/web/src/__tests__/integration/workspace-creation.test.ts
// Tests run under Vitest. There is no event-store to assert against;
// instead, mock the Trigger.dev task trigger and assert it was invoked.
import { vi } from 'vitest';
import { tasks } from '@trigger.dev/sdk/v3';

vi.spyOn(tasks, 'trigger');

describe('Workspace Creation Flow', () => {
  it('creates a workspace and schedules follow-up work', async () => {
    const workspace = await POST('/api/v1/workspaces', {
      name: 'Test Workspace',
    });

    expect(tasks.trigger).toHaveBeenCalledWith(
      'schedule-task',
      expect.objectContaining({ ws_id: workspace.id })
    );
  });
});
```

### End-to-End Tests

Test full user workflows across services (future):

```typescript theme={null}
// e2e/workspace-onboarding.spec.ts
test('user creates workspace and receives AI setup', async ({ page }) => {
  await page.goto('/workspaces/create');
  await page.fill('[name="name"]', 'Test Workspace');
  await page.click('button[type="submit"]');

  // Wait for AI setup completion
  await page.waitForSelector('[data-testid="ai-ready"]');
});
```

## Monitoring & Observability

### Service Health

```typescript theme={null}
// apps/web/src/app/api/health/route.ts
export async function GET() {
  const health = {
    service: 'web',
    status: 'healthy',
    uptime: process.uptime(),
    dependencies: {
      database: await checkDatabaseConnection(),
      eventBroker: await checkTriggerConnection()
    }
  };

  return Response.json(health);
}
```

### Correlation IDs

There is no dedicated `@tuturuuu/logging` or `@tuturuuu/observability` package and
no event-store; the example below is an illustrative pattern. Runtime server
code should log diagnostics with the native console method matching severity.

```typescript theme={null}
import { tasks } from '@trigger.dev/sdk/v3';

export async function POST(request: Request) {
  const correlationId =
    request.headers.get('x-correlation-id') ?? crypto.randomUUID();

  // Hand off async work to a Trigger.dev task, threading the correlation id.
  await tasks.trigger('schedule-task', { ws_id: workspaceId, correlationId });

  console.log('Queued schedule task', { correlationId, workspaceId });
}
```

## Migration Paths

### Current State → Future State

**Current:** A monorepo of Next.js apps over one shared Supabase project, with
background work on Trigger.dev v4.

**In progress:** The frontend is migrating from `apps/web` (Next.js) to
`apps/tanstack-web` (TanStack Start), and the API layer to `apps/backend` (Rust).
This is the concrete, active migration — see
[TanStack Start And Rust Migration](/platform/architecture/tanstack-rust-migration).

**Longer-term options (not committed):**

1. **Service-Specific Databases** (when needed)
   * Extract finance data to dedicated DB
   * Communicate via events
   * Maintain consistency with sagas

2. **API Gateway Layer** (if REST APIs grow)
   * Single entry point for external clients
   * Route to appropriate services
   * Handle auth, rate limiting centrally

3. **GraphQL Federation** (if complex queries needed)
   * Each service exposes GraphQL schema
   * Gateway federates schemas
   * Clients query unified graph

**Migration principle:** Evolve gradually based on real needs, not speculation.

## Related Documentation

* [Architectural Decisions](/platform/architecture/system-design/architectural-decisions) - Why microservices
* [Event-Driven Architecture](/platform/architecture/system-design/event-driven-architecture) - Inter-service communication
* [Monorepo Architecture](/build/development-tools/monorepo-architecture) - Turborepo setup
* [Database Schema](/reference/database/schema-overview) - Shared schema details


# Observability & Monitoring
Source: https://docs.tuturuuu.com/platform/architecture/system-design/observability-monitoring

How Tuturuuu observes the platform today, and the patterns that guide where it is heading

Observability gives you the ability to understand system behavior by examining
its outputs—logs, request records, and metrics. This page explains the core
observability patterns and, for each one, describes **what Tuturuuu actually
implements today** versus what is conceptual or aspirational.

<Note>
  **Observability vs Monitoring**: Monitoring tells you when something is wrong.
  Observability tells you why it's wrong and how to fix it. Tuturuuu leans on a
  self-hosted, Postgres-backed log drain rather than a third-party observability
  vendor.
</Note>

<Warning>
  **Ground-truth scope.** Tuturuuu's apps are conventional Next.js App Router and
  TanStack Start apps plus a Rust backend—not a hexagonal microservice mesh.
  There is no OpenTelemetry pipeline, no `@vercel/otel`, no
  `@tuturuuu/logging`/`@tuturuuu/observability` package, and no event-sourcing
  store. Where this page describes a pattern Tuturuuu has not adopted, it says so
  plainly and keeps the pattern only for its teaching value.
</Warning>

## Architecture in Transition

The legacy `apps/web` Next.js runtime (port `7803`) is being replaced by
`apps/tanstack-web` (TanStack Start) plus `apps/backend` (Rust, port `7820`).
The observability surface described below lives mostly in `apps/web` today and
is migrating alongside the rest of the platform. See
[TanStack Start And Rust Migration](/platform/architecture/tanstack-rust-migration)
for the contract, runtime shape, and ports.

***

## 1. Request-Scoped Correlation (Not Distributed Tracing)

### The pattern

Distributed tracing assigns each request a **trace ID** that flows through every
service, with each service recording **spans** (units of work) linked by that
trace ID. This is invaluable in a deep microservice mesh where one user action
fans out across dozens of services.

### What Tuturuuu actually does

Tuturuuu does **not** run OpenTelemetry or `@vercel/otel`, and there is no
`instrumentation.ts` that registers an OTel exporter. The real
`apps/web/src/instrumentation.ts` does not install a console drain:

```typescript theme={null}
// apps/web/src/instrumentation.ts (real)
export async function register() {
  return;
}
```

Instead of cross-service spans, Tuturuuu correlates work **within a single
request** using an `AsyncLocalStorage` context that carries a generated
`requestId`. API and cron handlers run inside `withRequestLogDrain` /
`withCronLogDrain`, and every log emitted during that request is stamped with
the same `requestId`, route, deployment color/stamp, and (once known)
`userId`/`userEmail`:

```typescript theme={null}
// apps/web/src/lib/infrastructure/log-drain.ts (real shape, abridged)
export async function withRequestLogDrain<T extends Response>(
  options: RequestDrainOptions,
  handler: () => Promise<T>
) {
  // Runs handler inside an AsyncLocalStorage context.
  // Retained request/cron events are persisted with a shared requestId.
}
```

When the handler finishes, the request and its captured `log_events` are written
to Postgres in one transaction, so you can later query every log line for a
single `requestId`. This gives per-request correlation and timing without an OTel
backend—but it does **not** propagate a trace across the `apps/web` → Rust
backend boundary. True cross-service tracing remains aspirational.

<Note>
  **Takeaway:** Correlate by `requestId`, not by OTel spans. There is no
  `getActiveTrace()`, `trace.span()`, or `io.getSpan()` API in this codebase.
</Note>

***

## 2. Centralized Logging via the Log Drain

### The pattern

In a distributed system, scattered per-instance log files are impractical.
Centralized logging streams structured logs to a unified store where they can be
searched, filtered, and correlated across boundaries.

### What Tuturuuu actually does

This pattern **is partially implemented**. `apps/web/src/lib/infrastructure/log-drain.ts`
is a self-hosted Postgres store for retained request, cron, deployment, and
usage events. Server runtime logs use the native console method that matches
severity; do not add `serverLogger` runtime imports or automatic console
log-drain installation.
Captured retained events are persisted to dedicated tables:

| Table          | Holds                                                        |
| -------------- | ------------------------------------------------------------ |
| `requests`     | One row per request/cron run: method, path, status, duration |
| `log_events`   | Individual log lines, linked to a `request_id`               |
| `cron_runs`    | Cron execution outcomes (success/failed, http status)        |
| `usage_events` | Numeric usage/metric samples (`metric`, `value`, `unit`)     |
| `deployments`  | Blue/green deployment metadata used to stamp logs            |

Each event carries `level`, `message`, `route`, `requestId`, deployment
color/stamp, optional `userId`/`userEmail`, and a JSON `metadata` bag. The drain
redacts bearer tokens and `token`/`key`/`secret`/`password` query params before
persisting, and is designed to **never throw into the caller**—logging failures
are swallowed.

```typescript theme={null}
console.info('Payment processing started', { workspaceId });
console.error('Payment failed', error);
```

Configuration is environment-driven (referenced by name, not value):

* `PLATFORM_LOG_DRAIN_ENABLED` — set to `0`/`false`/`off` to disable.
* `PLATFORM_LOG_DRAIN_DATABASE_URL` — Postgres connection for the drain.
* `PLATFORM_LOG_DRAIN_RAW_RETENTION_DAYS` — raw `log_events` retention
  (default 30 days).
* `PLATFORM_LOG_DRAIN_SUMMARY_RETENTION_DAYS` — summary table retention
  (default 90 days).
* `PLATFORM_BLUE_GREEN_COLOR`, `PLATFORM_DEPLOYMENT_STAMP`,
  `PLATFORM_PROJECT_ID` — deployment stamping.

The drain also prunes old rows on write, so retention is enforced without an
external job.

### Querying logs

Logs are read back through the internal observability API under
`apps/infrastructure/src/app/api/v1/infrastructure/observability/*` (for example `logs`,
`requests`, `cron-runs`, `deployments`, `overview`, `resources`, `analytics`),
which power the in-app infrastructure/observability dashboard. There is no
third-party log platform (no Datadog/ELK) in the loop.

***

## 3. Metrics and Usage Telemetry

### The pattern

Per-service metrics—request rates, error rates, latency percentiles, resource
utilization—let you detect and localize failures quickly and scale individual
services on their own load.

### What Tuturuuu actually does

Tuturuuu does **not** run Prometheus, a `metrics.counter()/histogram()/gauge()`
client, or a `@tuturuuu/observability` package. Instead, metrics are derived
from the same Postgres-backed drain:

* The `requests` table already encodes per-request **status** and
  **duration\_ms**, so request rate, error rate, and latency are computed by
  aggregating that table over a time window.
* The `usage_events` table stores arbitrary numeric samples
  (`metric`, `value`, `unit`)—the place to record product/business telemetry
  such as tokens consumed or workspaces created.
* `apps/web/src/lib/infrastructure/observability.ts` aggregates these (and
  container resource metrics like CPU percent / memory bytes) for the
  observability `overview`, `analytics`, and `resources` endpoints.

So per-service Prometheus metrics are **conceptual/aspirational** here; the
implemented reality is SQL aggregation over request, cron, and usage rows. If you
need a new metric, write `usage_events` rows through the infrastructure layer
rather than reaching for a Prometheus client that does not exist.

***

## 4. Health Checks

### The pattern

Services expose standardized health endpoints. Orchestrators probe them and stop
routing to—or replace—instances that fail, enabling self-healing deployments.
A common refinement splits **liveness** ("is the process running?") from
**readiness** ("is it ready to serve traffic?").

### What Tuturuuu actually does

The `apps/web` health endpoint is intentionally trivial—it does **not** probe
the database, Supabase, or Trigger.dev, and there are no `liveness`/`readiness`
sub-routes:

```typescript theme={null}
// apps/web/src/app/api/health/route.ts (real, complete)
import { connection, NextResponse } from 'next/server';

export async function GET() {
  await connection();

  return NextResponse.json(
    { status: 'ok' },
    {
      headers: {
        'Cache-Control': 'no-store',
      },
    }
  );
}
```

The Rust backend (`apps/backend`) goes further and **does** separate liveness
from readiness:

* `GET /api/health` → `{ "status": "ok" }` (parity with the web app, `no-store`).
* `GET /healthz` → liveness, returning service name, runtime (`"rust"`), and
  environment.
* `GET /readyz` → readiness; returns `200` only when the backend is fully
  configured (for example, `BACKEND_INTERNAL_TOKEN` is present), otherwise `503`.

These are simple HTTP probes suitable for container orchestration and the
blue/green deployment watcher. The Kubernetes `livenessProbe`/`readinessProbe`
YAML shown in earlier revisions of this page is illustrative only—Tuturuuu's
deployment model is the blue/green container watcher, not raw Kubernetes pods.

***

## 5. Scheduled Background Work (Not Event Sourcing)

### The pattern

Event sourcing persists an immutable, ordered history of domain events and
rebuilds state by replaying them—enabling audit trails, time-travel debugging,
and projection rebuilds.

### What Tuturuuu actually does

Tuturuuu does **not** implement event sourcing. There is no event store,
no `eventStore.append/query`, and no `rebuildProjection`. Background work runs on
**Trigger.dev v4** (`@trigger.dev/sdk` `^4.4.5`) using the `task()` API—not the
removed v2 `client.defineJob` / `eventTrigger` / `io.runTask` APIs.

```typescript theme={null}
// packages/trigger/src/schedule-tasks.ts (real)
import { task } from '@trigger.dev/sdk/v3';
import { schedulableTasksHelper } from './schedule-tasks-helper';

export const scheduleTask = task({
  id: 'schedule-task',
  queue: {
    concurrencyLimit: 10,
  },
  run: async (payload: { ws_id: string }) => {
    try {
      const result = await schedulableTasksHelper(payload.ws_id);

      if (!result.success) {
        throw new Error(result.error || 'Schedule tasks failed');
      }

      return { ws_id: payload.ws_id, ...result, success: true };
    } catch (error) {
      console.error(`[${payload.ws_id}] Error in schedule task:`, error);
      return {
        ws_id: payload.ws_id,
        success: false,
        error: error instanceof Error ? error.message : 'Unknown error',
      };
    }
  },
});
```

The historical-insight need that event sourcing addresses is partially met by
the log drain's `requests`, `cron_runs`, and `log_events` tables: cron and
request history is queryable for a retention window, and cron outcomes are
recorded as success/failure with duration and HTTP status. That is operational
history, **not** a replayable domain-event log.

***

## What Is Implemented vs. Conceptual

| Capability                 | Status in Tuturuuu | Reality                                                                |
| -------------------------- | ------------------ | ---------------------------------------------------------------------- |
| Request-scoped correlation | Implemented        | `AsyncLocalStorage` `requestId` in the log drain                       |
| Distributed tracing (OTel) | Aspirational       | No OTel / `@vercel/otel`; no cross-service spans                       |
| Centralized logging        | Partial            | Native `console.*` plus retained Postgres request/cron/deployment data |
| Per-service metrics        | Partial            | SQL aggregation over `requests`/`usage_events`; no Prometheus          |
| Health checks              | Implemented        | Web `/api/health`; backend `/healthz` + `/readyz`                      |
| Self-healing orchestration | Partial            | Blue/green watcher, not Kubernetes pods                                |
| Event sourcing / replay    | Not implemented    | Trigger.dev v4 `task()` scheduled jobs + cron history                  |

## Observability Best Practices Here

1. **Use native server logs.** In API, cron, and infrastructure runtime code,
   log diagnostics with the native console method that matches severity. Include
   structured metadata in the same call so retained platform views and deployment
   logs stay readable.
2. **Correlate by `requestId`.** When debugging, find the request row, then pull
   its `log_events`—that is the unit of correlation, not a trace ID.
3. **Record metrics as `usage_events`.** New product/business metrics belong in
   the usage table via the infrastructure layer, surfaced through the
   observability API.
4. **Never let logging break the caller.** The drain swallows its own errors by
   design; preserve that property in any extension.
5. **Reference config by name.** Tune retention and enablement through the
   `PLATFORM_LOG_DRAIN_*` environment variables; never commit connection values.

## Related Documentation

* [TanStack Start And Rust Migration](/platform/architecture/tanstack-rust-migration) - Frontend/backend runtime split and ports
* [Microservices Patterns](/platform/architecture/system-design/microservices-patterns) - Service design and deployment
* [Event-Driven Architecture](/platform/architecture/system-design/event-driven-architecture) - Event/queue patterns
* [Extensibility, Resilience & Scalability](/platform/architecture/system-design/extensibility-resilience-scalability) - System quality attributes
* [Security Architecture](/platform/architecture/system-design/security-architecture) - Security observability and audit trails


# System Design Overview
Source: https://docs.tuturuuu.com/platform/architecture/system-design/overview

Comprehensive overview of Tuturuuu's architectural patterns, principles, and design philosophy

Tuturuuu's architecture is built on a foundation of proven design patterns and principles that prioritize **extensibility**, **resilience**, **scalability**, and **maintainability**. This section provides a comprehensive guide to the system's architectural decisions and implementation patterns.

<Note>
  Several pages in this bucket describe patterns as general design guidance, not
  as fully-adopted Tuturuuu implementations. The platform apps are conventional
  Next.js App Router apps (`apps/web`) plus a TanStack Start frontend
  (`apps/tanstack-web`) and a Rust backend (`apps/backend`) that share one
  Supabase project. There is no hexagonal layering, event-store, or inter-service
  event bus in the codebase today. Where a pattern below is conceptual rather
  than implemented, treat it as a "when you would reach for this" guide and trust
  the cited source files over the prose.
</Note>

<Warning>
  **Active migration.** `apps/web` (Next.js, port `7803`) is being superseded by
  `apps/tanstack-web` (TanStack Start) plus `apps/backend` (Rust API, port
  `7820`). Patterns described here as "Next.js + tRPC" reflect the legacy
  `apps/web` runtime. See
  [TanStack Start And Rust Migration](/platform/architecture/tanstack-rust-migration)
  for the route-ownership contract and target architecture.
</Warning>

## Architectural Philosophy

Our architectural approach is guided by several core principles:

1. **Loose Coupling, High Cohesion**: Services and components are independently deployable with well-defined boundaries
2. **Evolutionary Design**: The system can adapt to changing requirements without extensive rewrites
3. **Resilience by Default**: Failures are isolated and don't cascade across the system
4. **Developer Experience First**: Architecture choices prioritize maintainability and developer productivity
5. **Pragmatic Trade-offs**: We make conscious decisions about complexity vs. simplicity based on actual needs

## Architectural Layers

```mermaid theme={null}
graph TB
    subgraph "Presentation Layer"
        A["React UI (apps/web, legacy)"]
        A2["TanStack Start (apps/tanstack-web, target)"]
        B[Shared @tuturuuu/ui Components]
    end

    subgraph "API Layer"
        C["Next.js API Routes /api/v1 (legacy)"]
        D["tRPC stub (healthCheck only)"]
        R["Rust backend (apps/backend, target)"]
        IA["packages/internal-api facades"]
    end

    subgraph "Application Surfaces"
        E[Web App]
        F[Rewise - AI Chat]
        G[Nova - Prompt Engineering]
        H[Calendar]
        I[Finance]
        J[Tuturuuu Tasks]
        K[Other Apps]
    end

    subgraph "Background Tasks"
        L["Trigger.dev v4 task() — calendar sync, scheduling"]
    end

    subgraph "Data Layer"
        N[Supabase PostgreSQL]
        O[RLS Policies]
        P[Realtime Subscriptions]
    end

    A --> C
    A2 --> IA
    B --> A
    B --> A2
    IA --> R
    IA --> C
    C --> E
    R --> N
    E --> L
    F --> N
    G --> N
    H --> L
    H --> N
    I --> N
    J --> N
    C --> N
    L --> N
```

<Info>
  The `tRPC` node is intentionally small: `apps/web/src/trpc` is a stub that
  exports only a `healthCheck` `baseProcedure` with a hardcoded context. Real
  product data flows through `packages/internal-api` helpers calling REST
  `/api/v1` routes (legacy `apps/web`) or the Rust backend (`apps/backend`). A
  guard (`check-tanstack-api-access`) forbids direct `/trpc`, `/api`, and
  `/internal` calls from `apps/tanstack-web/src`.
</Info>

## Core Architectural Patterns

### 1. Background And Scheduled Tasks (Trigger.dev)

Asynchronous, long-running work runs as Trigger.dev v4 `task()` definitions in
`packages/trigger`. Today this is scoped to a handful of concrete jobs —
Google Calendar full/incremental sync and the unified habit/task scheduler —
not a general cross-service event bus.

```ts theme={null}
// packages/trigger/src/unified-schedule.ts (Trigger.dev v4 task API)
import { task } from '@trigger.dev/sdk/v3';

export const unifiedScheduleTask = task({
  id: 'unified-schedule-task',
  queue: { concurrencyLimit: 5 },
  run: async (payload: { ws_id: string; windowDays?: number }) => {
    // ...scheduling work for one workspace
  },
});
```

<Note>
  The `@trigger.dev/sdk` is on v4 (`^4.4.5`). The v4 `task()` API is imported
  from `@trigger.dev/sdk/v3` (the path is unchanged across the v3→v4 SDK). The
  older v2 patterns (`client.defineJob`, `eventTrigger`, `io.runTask`,
  `io.sendEvent`) are not used in this repo.
</Note>

**When to use:**

* Background processing that shouldn't block user requests
* Long-running operations (calendar full sync, batch scheduling)
* Scheduled/recurring work coordinated through Trigger.dev queues and concurrency limits

**Read more:** [Event-Driven Architecture](/platform/architecture/system-design/event-driven-architecture)

### 2. Hexagonal Architecture (Ports & Adapters)

Clean separation between business logic and infrastructure concerns within a
service.

<Note>
  Tuturuuu apps do not implement full hexagonal layering: there are no
  `domain/`, `application/`, or `infrastructure/` directories in `apps/web`.
  The closest real boundary is `packages/internal-api` (a typed facade in front
  of REST/backend endpoints) and the Rust backend's per-domain route modules in
  `apps/backend/src` (for example `inventory`, `changelog`, `aurora`). Treat
  this section as guidance for where a port/adapter seam is worth introducing,
  not a description of an existing layered structure.
</Note>

**When to use:**

* Complex business logic that needs protection from technology changes
* Services requiring high testability
* When multiple adapters might be needed (REST + tRPC + GraphQL)

**Read more:** [Hexagonal Architecture](/platform/architecture/system-design/hexagonal-architecture)

### 3. Microservices in a Monorepo

Logical service boundaries with shared tooling and dependencies via Turborepo.

**When to use:**

* Independent teams working on different features
* Services with different scaling needs
* Features that benefit from technological flexibility

**Read more:** [Microservices Patterns](/platform/architecture/system-design/microservices-patterns)

### 4. Shared UI With Per-App Frontends

Organized frontend with a shared `@tuturuuu/ui` component library consumed by
each app. The legacy `apps/web` is a Next.js App Router app (Server Components
by default); the target `apps/tanstack-web` is a TanStack Start app. Both pull
from the same shared packages.

<Note>
  This was previously framed as a single "React Modular Monolith." In practice
  the frontend is split across distinct apps (`apps/web`, `apps/tanstack-web`,
  the Flutter `apps/mobile`) sharing packages, and the web frontend is mid-
  migration from Next.js to TanStack Start.
</Note>

**When to use:**

* Complex UIs with shared component libraries
* Multiple client types (web, mobile) sharing logic
* Teams that value fast iteration over distributed deployments

**Related:** [Data Fetching](/platform/architecture/data-fetching)

## Decision Matrix

| Requirement                           | Recommended Pattern                                       | Alternative            | Trade-off                      |
| ------------------------------------- | --------------------------------------------------------- | ---------------------- | ------------------------------ |
| Background / scheduled job processing | Trigger.dev v4 `task()`                                   | Synchronous API        | Complexity vs. Resilience      |
| User-facing API (target)              | Rust backend (`apps/backend`) via `packages/internal-api` | Direct REST            | Centralization vs. Effort      |
| User-facing API (legacy)              | Next.js API Routes (`/api/v1`) in `apps/web`              | tRPC                   | Existing surface vs. migration |
| Shared/typed API access               | `packages/internal-api` facades                           | Scattered raw `fetch`  | Encapsulation vs. Directness   |
| Service boundaries                    | Monorepo apps + shared packages                           | Polyrepo               | DX vs. Independence            |
| Frontend state                        | TanStack Query + Jotai                                    | Redux                  | Simplicity vs. Predictability  |
| Data access                           | Supabase RLS                                              | Application-level auth | Security vs. Performance       |

<Note>
  tRPC is **not** the user-facing API layer in Tuturuuu. The `apps/web/src/trpc`
  module is a stub (`healthCheck` only). Use `packages/internal-api` helpers in
  front of the Rust backend (`apps/backend`, target) or legacy `apps/web`
  `/api/v1` routes.
</Note>

## Key Design Documents

### Foundational Decisions

* [Architectural Decisions](/platform/architecture/system-design/architectural-decisions) - Why we chose microservices, EDA, hexagonal architecture, and React patterns

### Pattern Deep Dives

* [Event-Driven Architecture](/platform/architecture/system-design/event-driven-architecture) - Advantages, drawbacks, and implementation
* [Extensibility, Resilience & Scalability](/platform/architecture/system-design/extensibility-resilience-scalability) - 15 reasons these properties are prioritized
* [Encapsulation Patterns](/platform/architecture/system-design/encapsulation-patterns) - Preventing unwanted coupling

### Implementation Guides

* [Hexagonal Architecture](/platform/architecture/system-design/hexagonal-architecture) - Ports, adapters, and layering
* [Microservices Patterns](/platform/architecture/system-design/microservices-patterns) - Service boundaries and communication

## Integration with Existing Docs

This system design documentation complements our existing architecture guides:

* **[Routing](/platform/architecture/routing)**: Workspace-scoped routing implementation
* **[Data Fetching](/platform/architecture/data-fetching)**: RSC, Server Actions, TanStack Query patterns
* **[Authentication](/platform/architecture/authentication)**: Supabase Auth integration
* **[Authorization](/platform/architecture/authorization)**: RLS and permission system
* **[tRPC](/platform/architecture/trpc)**: Type-safe API layer (currently a stub; not the product API path)
* **[API Routes](/platform/architecture/api-routes)**: REST endpoint patterns (legacy `apps/web` `/api/v1`)
* **[TanStack Start And Rust Migration](/platform/architecture/tanstack-rust-migration)**: Target frontend/backend split and route-ownership contract

<Note>
  The Routing, Data Fetching, tRPC, and API Routes guides above describe the
  legacy `apps/web` runtime. For the target architecture, the equivalent path is
  TanStack Start loaders/server functions plus Rust backend endpoints fronted by
  `packages/internal-api`.
</Note>

## Quality Attributes

Our architecture explicitly optimizes for:

1. **Extensibility**: New features can be added with minimal changes to existing code
2. **Resilience**: Failures are isolated and the system degrades gracefully
3. **Scalability**: Services can scale independently based on demand
4. **Maintainability**: Code is organized, testable, and understandable
5. **Developer Experience**: Fast feedback loops and productive workflows

Each of these attributes is explored in depth in the linked documents above.

## Getting Started

For developers new to the codebase:

1. Start with [Architectural Decisions](/platform/architecture/system-design/architectural-decisions) to understand the "why"
2. Review [Microservices Patterns](/platform/architecture/system-design/microservices-patterns) to understand service boundaries
3. Explore [Hexagonal Architecture](/platform/architecture/system-design/hexagonal-architecture) for code organization within services
4. Read [Event-Driven Architecture](/platform/architecture/system-design/event-driven-architecture) for async communication patterns

For implementing new features:

1. Determine which app the work belongs to (`apps/web`, `apps/tanstack-web`, `apps/backend`, `apps/mobile`)
2. Route shared/typed API access through `packages/internal-api` rather than scattered raw `fetch`
3. Use Trigger.dev v4 `task()` definitions in `packages/trigger` for background/scheduled work
4. Follow data fetching patterns (TanStack Query; no `useEffect` fetching) for frontend integration
5. Keep boundaries clean and add tests; for new TanStack frontend ports, check the migration contract and the `check-tanstack-api-access` guard

## Architecture Evolution

This architecture is not static. The most significant in-flight change is the
migration of the web frontend from Next.js (`apps/web`) to TanStack Start
(`apps/tanstack-web`) plus a dedicated Rust backend (`apps/backend`), tracked
route-by-route in
[TanStack Start And Rust Migration](/platform/architecture/tanstack-rust-migration).
As the platform grows, we continuously evaluate:

* When to extract shared logic into new packages
* When to move product API surface from legacy `apps/web` routes to the Rust backend
* When to introduce new communication patterns
* When to adopt new technologies

All architectural changes are documented and follow the principles outlined in [AGENTS.md](https://github.com/tutur3u/platform/blob/main/AGENTS.md).


# Quality Attributes
Source: https://docs.tuturuuu.com/platform/architecture/system-design/quality-attributes

Maintainability, testability, and deployability in Tuturuuu's architecture

This document covers three critical quality attributes that are foundational to long-term system success: **Maintainability** (the ease of evolving and fixing the system), **Testability** (the ability to verify system correctness), and **Deployability** (the ease and safety of releasing changes).

<Note>
  These quality attributes are not added after the fact but are designed into the architecture from the beginning, ensuring the system remains healthy and productive as it grows.
</Note>

<Warning>
  **How to read this page.** Several patterns below (Hexagonal Architecture, ports/adapters, event sourcing, replay testing) are presented as **teaching models**, not as a description of the current codebase. Tuturuuu's apps are conventional **Next.js App Router** apps (plus a Rust backend) that share a single Supabase project — there are no `domain/`/`infrastructure/` hexagonal layers, no event store, and no per-app inter-service contracts package. Code samples that show those layers are **illustrative**; sections labeled **"In Tuturuuu today"** describe the real, verifiable structure. Treat the rest as design guidance for how we want isolated modules to behave.
</Warning>

<Info>
  **Active migration.** `apps/web` (Next.js, port `7803`) is being incrementally replaced by `apps/tanstack-web` (TanStack Start) plus `apps/backend` (Rust, port `7820`). The maintainability and deployability properties described here are being carried forward into that target architecture. See [TanStack + Rust Migration](/platform/architecture/tanstack-rust-migration) for the current state.
</Info>

<Info>
  To understand how different architectural patterns affect these quality attributes, see [Architectural Patterns Comparison](/platform/architecture/system-design/architectural-patterns-comparison).
</Info>

## Maintainability

Maintainability determines how easily the system can be modified to fix bugs, add features, or adapt to changing requirements. Poor maintainability leads to increasing development costs and slower delivery over time.

### 1. Clear Domain Boundaries Reduce Cognitive Load

#### Architectural Choice

The microservices architecture and modular frontend design establish clear boundaries between different business domains, each with well-defined responsibilities and interfaces.

#### Impact and Justification

In a monolithic, tightly-coupled system, understanding how to make a change requires comprehending vast swaths of interconnected code. A developer wanting to modify the billing logic might need to understand authentication, user management, and inventory systems simply because they're all tangled together.

**Clear domain boundaries** solve this by ensuring each service or module has a focused responsibility. A developer working on the `FinanceService` only needs to understand finance-related concepts and the clearly-defined interfaces for interacting with other services. This dramatically reduces cognitive load and enables faster, more confident changes.

**In Tuturuuu today:**

```text theme={null}
apps/
├── web/          // Main Next.js platform (port 7803) - workspace management
├── tanstack-web/ // TanStack Start successor to apps/web (migration in progress)
├── backend/      // Rust backend (port 7820)
├── finance/      // Finance surface
├── calendar/     // Calendar surface
├── tasks/        // Tasks surface
├── nova/         // AI challenges
├── rewise/       // AI chat
└── mobile/       // Flutter mobile app

// Each app owns a focused surface. The web-facing apps are conventional
// Next.js App Router apps; they share one Supabase project rather than
// each owning a private datastore. Cross-cutting product logic lives in
// shared packages (packages/internal-api, packages/types, packages/ui).
```

The boundary that reduces cognitive load here is the **app + feature folder**, not a separate per-service runtime with its own database. A developer working on finance can stay inside `apps/finance` (and the finance helpers in `packages/apis`/`packages/internal-api`) without learning the calendar surface.

**Module boundaries in frontend:**

```typescript theme={null}
// apps/web/src/app/[locale]/(dashboard)/[wsId]/
finance/
├── layout.tsx              // Finance-specific layout
├── transactions/           // Transaction management
├── reports/                // Financial reports
└── settings/               // Finance settings

// Finance module is self-contained
// Changes here don't affect calendar or tasks modules
```

#### Clarifying Additions

**Engineers focus on one area at a time without understanding the entire system.** New team members can become productive quickly by mastering a single domain rather than the entire codebase.

**This reduces onboarding complexity.** Clear boundaries make it obvious where to find code related to specific features, accelerating the learning curve for new developers.

**Maintenance tasks become easier to isolate and execute.** Bug fixes and feature additions are scoped to specific services or modules, reducing the risk of unintended side effects.

***

### 2. Technology Independence Prevents Legacy Lock-In

#### Architectural Choice

Isolating technology choices (databases, frameworks, external services) behind well-defined interfaces keeps core business logic decoupled from the tools that implement it.

#### Impact and Justification

Technology evolves rapidly. Frameworks fall out of favor, databases become outdated, and new tools emerge. Systems that tightly couple business logic to specific technologies become **legacy systems**—expensive and risky to modernize.

**Technology independence** protects the valuable business logic (which changes rarely) from technological churn (which happens frequently). When infrastructure details sit behind an interface, you can upgrade or replace technologies without rewriting business rules.

<Note>
  **Illustrative pattern.** The `WorkspaceRepository` / `SupabaseWorkspaceRepository` example below is a teaching model. Tuturuuu does **not** ship `packages/types/src/domain/workspace.ts` or `apps/web/src/infrastructure/repositories/*`; there is no repository-interface layer. In the real code, route handlers and shared helpers in `packages/internal-api` and `packages/apis` call the Supabase client directly (see "In Tuturuuu today" below). Read this as how to keep a swappable seam if you introduce one.
</Note>

```typescript theme={null}
// Illustrative: business logic expressed against an interface, not an implementation
export interface WorkspaceRepository {
  findById(id: string): Promise<Workspace | null>;
  save(workspace: Workspace): Promise<void>;
  delete(id: string): Promise<void>;
}

// Core business logic depends on the interface
export class WorkspaceService {
  constructor(private repo: WorkspaceRepository) {}

  async archiveWorkspace(id: string) {
    const workspace = await this.repo.findById(id);
    if (!workspace) throw new Error('Workspace not found');

    workspace.archive(); // Pure business logic
    await this.repo.save(workspace);
  }
}

// Illustrative infrastructure implementation (the swappable seam)
export class SupabaseWorkspaceRepository implements WorkspaceRepository {
  constructor(private client: SupabaseClient) {}

  async findById(id: string) {
    const { data } = await this.client
      .from('workspaces')
      .select('*')
      .eq('id', id)
      .single();

    return data ? this.toDomain(data) : null;
  }

  async save(workspace: Workspace) {
    await this.client
      .from('workspaces')
      .upsert(this.toDatabase(workspace));
  }

  async delete(id: string) {
    await this.client
      .from('workspaces')
      .delete()
      .eq('id', id);
  }
}

// Future: Can swap Supabase for Prisma, Drizzle, or any other ORM
// WITHOUT changing business logic
```

**Example technology evolution:**

```typescript theme={null}
// Today: Supabase
const repo = new SupabaseWorkspaceRepository(supabaseClient);

// Tomorrow: Drizzle ORM (business logic unchanged)
const repo = new DrizzleWorkspaceRepository(drizzleClient);

// Next year: Different database (business logic still unchanged)
const repo = new MongoWorkspaceRepository(mongoClient);

// Business logic stays the same:
const service = new WorkspaceService(repo);
await service.archiveWorkspace('ws-123');
```

**In Tuturuuu today:** technology independence comes from a few concrete seams rather than a full ports/adapters layer:

* Supabase access is centralized behind the `@tuturuuu/supabase/next/server` factories (`createClient()` and `createDynamicClient()` are async, `createAdminClient()` is sync). Swapping how a client is built happens in one place.
* Generated DB types are imported from `@tuturuuu/types/db`, so schema changes propagate through types instead of hand-written mappers.
* Shared product logic lives in `packages/internal-api` and `packages/apis`, so the web app and its TanStack successor can reuse the same helpers as the migration proceeds.

The biggest real-world example of this independence is the in-progress move of `apps/web` to `apps/tanstack-web` + a Rust `apps/backend`: shared packages let the data layer be re-pointed without rewriting every call site.

#### Clarifying Additions

**No single technical choice restricts future evolution.** The architecture accommodates technological progress without requiring expensive rewrites of core business logic.

**Components modernize incrementally as needed.** Instead of "big bang" technology migrations that put the entire system at risk, individual components can be upgraded independently.

**This protects the system from long-term stagnation.** The architecture remains flexible enough to adopt new technologies as they mature, preventing technical debt accumulation.

***

### 3. Hexagonal Architecture Minimizes Ripple Effects

#### Architectural Choice

The Hexagonal Architecture's strict separation between core domain logic and external concerns ensures that changes to infrastructure do not ripple into business rules.

#### Impact and Justification

In traditional layered architectures, changes to infrastructure (like upgrading a database library or switching message brokers) often require modifications to business logic because the layers are tightly coupled.

Hexagonal Architecture **inverts the dependency direction**. The core domain is completely isolated and defines interfaces (ports) for what it needs. Infrastructure adapters implement these interfaces but the core remains ignorant of implementation details.

This means infrastructure changes stay contained in the adapter layer. Upgrading from PostgreSQL 14 to PostgreSQL 16, changing from REST to GraphQL, or switching message brokers requires modifying only the relevant adapters—the domain core remains untouched.

<Note>
  **Illustrative pattern, not current code.** Tuturuuu does **not** implement a `TaskService` with injected `TaskRepository` / `EventBus` / `Logger` ports, and there is no `@tuturuuu/logging` or `@tuturuuu/observability` package. Task logic lives in conventional Next.js route handlers and shared helpers. The example below shows the *shape* of a hexagonal seam so you can recognize where one would help if a piece of logic becomes worth isolating. For background work, Tuturuuu uses **Trigger.dev v4 `task()`** definitions in `packages/trigger/src` — not a custom `EventBus`.
</Note>

```typescript theme={null}
// Illustrative domain core (unchanged when infrastructure changes)
export class TaskService {
  constructor(
    private taskRepo: TaskRepository,
    private eventBus: EventBus,
    private logger: Logger
  ) {}

  async createTask(data: CreateTaskData) {
    const task = Task.create(data);

    await this.taskRepo.save(task);
    await this.eventBus.publish(new TaskCreated(task));
    this.logger.info('Task created', { taskId: task.id });

    return task;
  }
}

// Infrastructure layer (changeable without affecting domain)
// Version 1: Supabase + Trigger.dev + Console logging
const service = new TaskService(
  new SupabaseTaskRepository(supabase),
  new TriggerEventBus(trigger),
  new ConsoleLogger()
);

// Version 2: Drizzle + NATS + Structured logging
// Domain core completely unchanged!
const service = new TaskService(
  new DrizzleTaskRepository(drizzle),
  new NatsEventBus(nats),
  new StructuredLogger(winston)
);
```

**Real-world example - Upgrading Next.js:**

```typescript theme={null}
// Business logic and components remain the same
// Only infrastructure adapters need updates

// Before Next.js 16
export function getWorkspaceData(id: string) {
  // Implementation using Next.js 15 patterns
}

// After Next.js 16
export function getWorkspaceData(id: string) {
  // Implementation using Next.js 16 patterns
  // Component code using this function unchanged
}
```

#### Clarifying Additions

**Core logic remains stable even during broad technical changes.** The most valuable part of the codebase (business rules) is shielded from the volatility of technology trends.

**Adaptation happens at edges rather than at the center.** When technology changes, only the outer layers (adapters) need modification, keeping changes localized and predictable.

**This protects business rules against unnecessary modification.** Domain experts can rely on business logic remaining stable, reducing the risk of introducing bugs when upgrading infrastructure.

***

### 4. Modular Frontend Prevents UI-Level Entanglement

#### Architectural Choice

The React Modular Monolith pattern organizes the frontend into self-contained modules with clear boundaries, preventing the "big ball of mud" problem common in large SPAs.

#### Impact and Justification

As frontend applications grow, they often become tangled webs of interdependent components, shared state, and implicit dependencies. Making a change in one area unexpectedly breaks seemingly unrelated features.

The **modular monolith** approach enforces architectural discipline by organizing code into feature-based modules with explicit boundaries. Each module (Finance, Calendar, Tasks, etc.) owns its components, state management, and business logic. Inter-module dependencies are explicit and minimized.

This structure makes maintenance dramatically easier because changes stay localized within module boundaries.

**In Tuturuuu today:** `apps/web` follows exactly this shape — feature folders under `app/[locale]/(dashboard)/[wsId]/` (finance, calendar, tasks, ...) each own their routes and colocated `_components/`. Client state uses **Jotai** (and TanStack Query for server data); the per-module `state.ts` paths below are a representative shape rather than fixed filenames.

```text theme={null}
apps/web/src/
├── app/[locale]/(dashboard)/[wsId]/
│   ├── finance/                    // Finance module
│   │   ├── layout.tsx
│   │   ├── transactions/
│   │   ├── reports/
│   │   └── _components/           // Finance-specific components
│   ├── calendar/                   // Calendar module
│   │   ├── layout.tsx
│   │   ├── events/
│   │   └── _components/           // Calendar-specific components
│   └── tasks/                      // Tasks module
│       ├── layout.tsx
│       ├── boards/
│       └── _components/           // Task-specific components
├── components/
│   ├── finance/                   // Shared finance components
│   ├── calendar/                  // Shared calendar components
│   ├── tasks/                     // Shared task components
│   └── common/                    // Truly shared components
```

**Module independence:**

```typescript theme={null}
// Finance module - self-contained state management
// apps/web/src/app/[locale]/(dashboard)/[wsId]/finance/state.ts
import { atom } from 'jotai';

export const financeTransactionsAtom = atom<Transaction[]>([]);
export const financeFiltersAtom = atom<Filters>({});

// Calendar module - separate state management
// apps/web/src/app/[locale]/(dashboard)/[wsId]/calendar/state.ts
import { atom } from 'jotai';

export const calendarEventsAtom = atom<Event[]>([]);
export const calendarViewAtom = atom<'month' | 'week' | 'day'>('month');

// Modules don't share state - clear boundaries
```

#### Clarifying Additions

**UI concerns grow independently instead of interfering with each other.** Finance features can evolve without touching calendar code, and vice versa.

**Teams can refactor modules safely.** Because module boundaries are clear, teams can confidently restructure their module knowing they won't break other features.

**Visual and functional changes stay well-scoped.** UI redesigns or feature enhancements affect only the relevant module, reducing regression testing burden.

***

### 5. Operational Independence per Service

#### Architectural Choice

Each microservice can be deployed, scaled, monitored, and maintained independently without coordinating with other services.

#### Impact and Justification

In a monolithic architecture, operational tasks affect the entire system. Deploying a minor bug fix to the reporting module requires rebuilding and redeploying the entire application. Scaling requires scaling everything, even if only one feature is under load.

**Operational independence** means each service is a separate deployable unit with its own lifecycle. Teams can:

* Deploy updates to their service multiple times per day
* Scale their service based on its specific load patterns
* Monitor their service's health independently
* Apply operational changes (like upgrading Node.js) on their own schedule

This independence accelerates development velocity and reduces the coordination overhead that plagues monolithic systems.

**In Tuturuuu today:** there are no `deploy:web` / `deploy:finance` / `deploy:calendar` package scripts. Independence is achieved through **per-app Vercel projects** wired up by dedicated GitHub Actions workflows. Each app has its own preview workflow under `.github/workflows/` (for example `vercel-preview-finance.yaml`, `vercel-preview-calendar.yaml`, `vercel-preview-drive.yaml`), and Turborepo only rebuilds the apps affected by a change:

```bash theme={null}
# Build a single workspace and its dependency graph (Turborepo filters by app)
bun turbo run build --filter=@tuturuuu/web

# Run an app locally (each app owns its own dev script)
cd apps/finance && bun dev
```

```yaml theme={null}
# Real per-app preview workflow — .github/workflows/vercel-preview-finance.yaml
name: Vercel Finance Preview Deployment
# Builds only the shared deps the finance app needs, then deploys it to Vercel:
#   bun turbo:local run build --filter=@tuturuuu/types --filter=@tuturuuu/supabase --filter=@tuturuuu/internal-api
```

Because each app is its own Vercel project, finance can deploy without rebuilding or redeploying the web or calendar apps.

**Monitoring:** Tuturuuu does not ship a custom per-service metrics SDK. Runtime/server logs in API, cron, and infrastructure code use the native console method matching severity, while retained request, cron, deployment, and usage data still flows through the internal log-drain storage where those wrappers are wired. Vercel provides per-project deployment and runtime insight. Treat the `monitorErrorRate(...)` snippet style as conceptual.

#### Clarifying Additions

**Services update without impacting other services.** A finance service deployment doesn't require coordination with the calendar team or risk affecting calendar functionality.

**Maintenance tasks stay focused and manageable.** Security patches, dependency updates, and refactoring efforts are scoped to individual services.

**This encourages timely updates and better long-term health.** Teams aren't hesitant to deploy updates because the blast radius is limited to their service.

***

## Testability

Testability determines how easily we can write and maintain automated tests that verify system correctness. High testability leads to better quality, faster development, and greater confidence in changes.

### 1. Pure Logic Enables Fast Unit Testing

#### Architectural Choice

Keeping pure logic free of infrastructure dependencies enables fast unit tests that don't require databases, network calls, or other external systems. (A full Hexagonal layer is one way to enforce this; Tuturuuu does not implement that layering, but the *principle* — isolate decision logic from I/O — still applies inside conventional modules.)

#### Impact and Justification

In traditional architectures, business logic is often tightly coupled to infrastructure (database access, API calls, file I/O). This makes testing painful because every test requires:

* Setting up test databases
* Mocking network requests
* Managing test data cleanup
* Dealing with test environment flakiness

These tests are slow (seconds per test instead of milliseconds), fragile (break when infrastructure changes), and difficult to write (require complex setup).

Isolating pure logic solves this by making the decision code free of infrastructure dependencies. Tests instantiate the object and verify rules with simple in-memory inputs. These tests run in milliseconds and never fail due to infrastructure issues.

<Note>
  **Illustrative pattern.** The `Workspace` class below does not exist at `packages/types/src/domain/workspace.ts` (there is no `domain/` directory). It models how a pure, framework-free unit would look. Real tests in the repo run on **Vitest** (`vitest run`) and live next to the code they cover as `*.test.ts` — for example the route handler tests under `packages/apis/src/finance/**`.
</Note>

```typescript theme={null}
// Illustrative pure logic — no I/O, fully testable
export class Workspace {
  private constructor(
    public readonly id: string,
    public name: string,
    public status: 'active' | 'archived',
    public memberLimit: number
  ) {}

  static create(data: CreateWorkspaceData): Workspace {
    if (data.name.length < 3) {
      throw new Error('Workspace name must be at least 3 characters');
    }

    return new Workspace(
      uuid(),
      data.name,
      'active',
      data.memberLimit || 10
    );
  }

  archive() {
    if (this.status === 'archived') {
      throw new Error('Workspace already archived');
    }
    this.status = 'archived';
  }

  addMember() {
    // Business rule: enforce member limit
    if (this.getMemberCount() >= this.memberLimit) {
      throw new Error('Member limit reached');
    }
    // ... add member logic
  }
}

// Test - no infrastructure required (Vitest, colocated *.test.ts)
describe('Workspace', () => {
  describe('create', () => {
    it('creates workspace with valid name', () => {
      const workspace = Workspace.create({
        name: 'My Workspace',
        memberLimit: 10
      });

      expect(workspace.name).toBe('My Workspace');
      expect(workspace.status).toBe('active');
      expect(workspace.memberLimit).toBe(10);
    });

    it('rejects workspace with short name', () => {
      expect(() => {
        Workspace.create({ name: 'ab', memberLimit: 10 });
      }).toThrow('Workspace name must be at least 3 characters');
    });
  });

  describe('archive', () => {
    it('archives active workspace', () => {
      const workspace = Workspace.create({ name: 'Test', memberLimit: 10 });

      workspace.archive();

      expect(workspace.status).toBe('archived');
    });

    it('rejects archiving already archived workspace', () => {
      const workspace = Workspace.create({ name: 'Test', memberLimit: 10 });
      workspace.archive();

      expect(() => workspace.archive()).toThrow('Workspace already archived');
    });
  });
});

// Tests run in <1ms each, no database required
```

#### Clarifying Additions

**Domain logic is easy to verify because it avoids external dependencies.** Tests focus purely on business rules without the complexity of infrastructure setup.

**Tests remain fast and reliable.** Unit tests execute in milliseconds, enabling tight feedback loops and encouraging developers to run tests frequently.

**This leads to strong coverage of critical business rules.** Because tests are easy to write, developers write more of them, leading to better quality and fewer bugs.

***

### 2. Adapter Design Enables Test Doubles

#### Architectural Choice

All external dependencies are accessed through interfaces (ports), allowing test implementations (test doubles) to be easily substituted during testing.

#### Impact and Justification

Real external systems (databases, APIs, message brokers) are problematic for testing:

* **Slow**: Network calls and database queries add latency
* **Flaky**: External systems can be temporarily unavailable
* **Stateful**: Tests can interfere with each other through shared state
* **Complex**: Require extensive setup and teardown

**Test doubles** (in-memory implementations of interfaces) solve all these problems. They're fast, reliable, isolated, and simple. The pattern works wherever a dependency is reachable behind an interface or an injected client.

<Note>
  **Illustrative pattern.** `TaskRepository` / `InMemoryTaskRepository` is a model, not repo code. In practice, Tuturuuu tests usually mock the Supabase client (or use Vitest mocks) at the boundary of a route handler rather than swapping a hand-written repository port. The shape below shows the underlying idea: keep the seam mockable.
</Note>

```typescript theme={null}
// Illustrative interface seam
export interface TaskRepository {
  findById(id: string): Promise<Task | null>;
  save(task: Task): Promise<void>;
  findByWorkspace(workspaceId: string): Promise<Task[]>;
}

// Production implementation (Supabase)
export class SupabaseTaskRepository implements TaskRepository {
  // ... real database implementation
}

// Test implementation (in-memory)
export class InMemoryTaskRepository implements TaskRepository {
  private tasks = new Map<string, Task>();

  async findById(id: string): Promise<Task | null> {
    return this.tasks.get(id) || null;
  }

  async save(task: Task): Promise<void> {
    this.tasks.set(task.id, task);
  }

  async findByWorkspace(workspaceId: string): Promise<Task[]> {
    return Array.from(this.tasks.values())
      .filter(task => task.workspaceId === workspaceId);
  }

  // Test helpers
  clear() {
    this.tasks.clear();
  }

  count() {
    return this.tasks.size;
  }
}

// Test using in-memory repository
describe('TaskService', () => {
  let taskRepo: InMemoryTaskRepository;
  let service: TaskService;

  beforeEach(() => {
    taskRepo = new InMemoryTaskRepository();
    service = new TaskService(taskRepo);
  });

  it('creates task', async () => {
    const task = await service.createTask({
      title: 'Test task',
      workspaceId: 'ws-123'
    });

    expect(task.title).toBe('Test task');
    expect(taskRepo.count()).toBe(1);

    // Verify task was saved
    const saved = await taskRepo.findById(task.id);
    expect(saved).toBeDefined();
  });

  it('finds tasks by workspace', async () => {
    await service.createTask({ title: 'Task 1', workspaceId: 'ws-1' });
    await service.createTask({ title: 'Task 2', workspaceId: 'ws-1' });
    await service.createTask({ title: 'Task 3', workspaceId: 'ws-2' });

    const tasks = await taskRepo.findByWorkspace('ws-1');

    expect(tasks).toHaveLength(2);
  });
});
```

#### Clarifying Additions

**External interactions can be simulated cleanly.** Test doubles provide predictable, controllable implementations of external systems.

**Testing becomes predictable and thorough.** Tests aren't affected by external system availability or performance, leading to consistent, reliable test suites.

**Complex conditions are easier to replicate.** Error scenarios (network failures, database constraints) can be easily simulated with test doubles that would be difficult to reproduce with real systems.

***

### 3. Contract Testing for Microservices

#### Architectural Choice

Service boundaries are verified through contract tests that ensure APIs and event schemas remain compatible as services evolve independently.

#### Impact and Justification

In a microservices architecture, services evolve independently. A breaking change to a service's API can silently break consumers without the producer knowing until runtime. Traditional integration tests that spin up all services are slow, complex, and brittle.

**Contract testing** solves this by verifying that:

1. **Producer** honors the contract (API/event schema) that consumers expect
2. **Consumer** can handle the responses/events that producers emit

This catches breaking changes early (at build time) without requiring full integration test environments.

<Note>
  **Illustrative pattern.** There is no `packages/apis/src/contracts/workspace.contract.ts`, and Tuturuuu does not run formal producer/consumer contract tests today. `packages/apis` (`@tuturuuu/apis`) holds **REST route handlers** (e.g. `src/finance/debts/route.ts`) with colocated `*.test.ts` files — not contract schemas. The closest real practice is validating request/response payloads with **Zod** inside route handlers and asserting on them in tests. The schema/contract code below is a conceptual model for how an explicit contract would look if introduced.
</Note>

```typescript theme={null}
// Illustrative API contract definition
import { z } from 'zod';

export const WorkspaceContract = {
  getWorkspace: {
    input: z.object({
      id: z.guid()
    }),
    output: z.object({
      id: z.guid(),
      name: z.string(),
      status: z.enum(['active', 'archived']),
      memberCount: z.number(),
      createdAt: z.string().datetime()
    })
  },

  createWorkspace: {
    input: z.object({
      name: z.string().min(3),
      memberLimit: z.number().optional()
    }),
    output: z.object({
      id: z.guid(),
      name: z.string(),
      status: z.literal('active'),
      memberLimit: z.number()
    })
  }
};

// Producer test - verify service honors contract
describe('WorkspaceAPI - Producer Contract', () => {
  it('getWorkspace returns valid response', async () => {
    const workspace = await createTestWorkspace();

    const response = await api.getWorkspace({ id: workspace.id });

    // Verify response matches contract
    expect(() => {
      WorkspaceContract.getWorkspace.output.parse(response);
    }).not.toThrow();
  });

  it('createWorkspace accepts valid input and returns valid output', async () => {
    const input = { name: 'Test Workspace', memberLimit: 20 };

    // Verify input is valid
    expect(() => {
      WorkspaceContract.createWorkspace.input.parse(input);
    }).not.toThrow();

    const response = await api.createWorkspace(input);

    // Verify output matches contract
    expect(() => {
      WorkspaceContract.createWorkspace.output.parse(response);
    }).not.toThrow();
  });
});

// Consumer test - verify consumer can handle producer responses
describe('WorkspaceAPI - Consumer Contract', () => {
  it('handles workspace response', () => {
    // Mock response that matches contract
    const mockResponse = {
      id: '123e4567-e89b-12d3-a456-426614174000',
      name: 'My Workspace',
      status: 'active' as const,
      memberCount: 5,
      createdAt: '2024-11-17T00:00:00Z'
    };

    // Consumer code should handle this
    expect(() => {
      const workspace = parseWorkspaceResponse(mockResponse);
      expect(workspace.name).toBe('My Workspace');
    }).not.toThrow();
  });
});
```

**Event contract testing:**

```typescript theme={null}
// Event schema contract
export const WorkspaceEvents = {
  'workspace.created': z.object({
    workspaceId: z.guid(),
    name: z.string(),
    ownerId: z.guid(),
    createdAt: z.string().datetime()
  }),

  'workspace.member.added': z.object({
    workspaceId: z.guid(),
    userId: z.guid(),
    role: z.enum(['owner', 'admin', 'member']),
    addedAt: z.string().datetime()
  })
};

// Producer test
it('emits valid workspace.created event', async () => {
  const event = await captureEvent('workspace.created', () => {
    return createWorkspace({ name: 'Test' });
  });

  // Verify event matches schema
  expect(() => {
    WorkspaceEvents['workspace.created'].parse(event);
  }).not.toThrow();
});

// Consumer test
it('handles workspace.created event', async () => {
  const mockEvent = {
    workspaceId: '123e4567-e89b-12d3-a456-426614174000',
    name: 'Test Workspace',
    ownerId: '234e5678-e89b-12d3-a456-426614174000',
    createdAt: '2024-11-17T00:00:00Z'
  };

  // Consumer should handle valid events
  expect(async () => {
    await handleWorkspaceCreated(mockEvent);
  }).not.toThrow();
});
```

#### Clarifying Additions

**Service boundaries remain stable through contract checks.** Breaking changes are caught by failing contract tests before code reaches production.

**Teams catch breaking changes early.** Instead of discovering API incompatibilities in staging or production, contract tests fail during CI/CD.

**Collaboration between services stays reliable.** Contract tests act as executable documentation of service interfaces, ensuring compatibility as teams work independently.

***

### 4. Event-Driven Systems Support Replay Testing

#### Architectural Choice

The event-driven architecture preserves event history, enabling powerful testing techniques like event replay and scenario recreation.

#### Impact and Justification

Traditional request-response systems are ephemeral. Once a request completes, reproducing the exact conditions that led to a bug is difficult or impossible. Debugging production issues often involves guesswork.

**Event replay** provides a time machine for testing. Because all events are preserved, we can:

1. **Capture** event sequences from production
2. **Replay** them in test environments to reproduce bugs
3. **Verify** that fixes resolve the issue
4. **Test** edge cases by constructing specific event sequences

This makes debugging significantly more reliable and enables regression testing for complex, multi-step workflows.

<Warning>
  **Aspirational pattern — not implemented.** Tuturuuu has **no event store and no event-sourcing layer**, so there is no `eventStore.query(...)` or production event replay. Background work runs as **Trigger.dev v4 `task()`** definitions (`packages/trigger/src`), which are individually testable but are not a replayable event log. The code below illustrates the *concept* of replay testing; do not treat it as an available API.
</Warning>

```typescript theme={null}
// Aspirational: capture events from an event store (not present in Tuturuuu)
export async function captureEventSequence(
  workspaceId: string,
  startTime: Date,
  endTime: Date
): Promise<DomainEvent[]> {
  return await eventStore.query({
    workspaceId,
    from: startTime,
    to: endTime,
    orderBy: 'timestamp'
  });
}

// Replay events in test environment
export async function replayEvents(events: DomainEvent[]) {
  // Reset test environment
  await resetTestDatabase();

  // Replay each event in order
  for (const event of events) {
    await eventBus.publish(event);
    await waitForEventProcessing();
  }
}

// Test by replaying production scenario
describe('Bug: Workspace members not receiving invitations', () => {
  it('reproduces production bug', async () => {
    // Capture events from production incident
    const events = await captureEventSequence(
      'ws-problematic',
      new Date('2024-11-15T14:00:00Z'),
      new Date('2024-11-15T14:05:00Z')
    );

    // Replay in test environment
    await replayEvents(events);

    // Verify bug is reproduced
    const invitations = await getInvitations('ws-problematic');
    expect(invitations).toHaveLength(0); // Bug: no invitations sent
  });

  it('verifies fix resolves the issue', async () => {
    // Apply the fix (code changes)

    // Replay same event sequence
    const events = await captureEventSequence(
      'ws-problematic',
      new Date('2024-11-15T14:00:00Z'),
      new Date('2024-11-15T14:05:00Z')
    );

    await replayEvents(events);

    // Verify fix worked
    const invitations = await getInvitations('ws-problematic');
    expect(invitations).toHaveLength(3); // Fix: invitations sent correctly
  });
});

// Test edge cases by constructing event sequences
describe('Workspace state transitions', () => {
  it('handles rapid member additions and removals', async () => {
    const events = [
      createEvent('workspace.created', { id: 'ws-1' }),
      createEvent('member.added', { userId: 'user-1' }),
      createEvent('member.added', { userId: 'user-2' }),
      createEvent('member.removed', { userId: 'user-1' }),
      createEvent('member.added', { userId: 'user-3' }),
      createEvent('member.removed', { userId: 'user-2' }),
    ];

    await replayEvents(events);

    const workspace = await getWorkspace('ws-1');
    expect(workspace.members).toHaveLength(1);
    expect(workspace.members[0].userId).toBe('user-3');
  });
});
```

#### Clarifying Additions

**Capturing event sequences makes reproducing issues easier.** Production bugs can be reliably recreated in test environments by replaying the exact sequence of events that led to the failure.

**Historical flows can be studied and validated.** Teams can analyze how the system responded to past events and verify that fixes prevent recurrence.

**This strengthens debugging across distributed processes.** Complex, multi-service workflows can be tested end-to-end by replaying events, making it easier to verify system behavior.

***

### 5. Independent CI Pipelines

#### Architectural Choice

Each microservice has its own independent CI/CD pipeline that runs tests, builds, and deploys the service without coordinating with other services.

#### Impact and Justification

In a monolithic architecture, all tests run in a single, long CI pipeline. A failure in any part of the system blocks the entire deployment, and slow tests create bottlenecks.

**Independent CI pipelines** for each service provide:

* **Parallelism**: All services test simultaneously, dramatically reducing feedback time
* **Isolation**: Failures in one service don't block others from deploying
* **Focus**: Teams see only their service's test results, reducing noise
* **Speed**: Smaller test suites run faster than monolithic suites

**In Tuturuuu today:** there are no `web-ci.yml` / `finance-ci.yml` per-app pipeline files. Instead, shared workflows test the whole graph with Turborepo's affected-package filtering, and **per-app Vercel preview workflows** handle build/deploy. Real workflows under `.github/workflows/` include:

* `turbo-unit-tests.yaml` — runs unit tests across affected workspaces
* `type-check.yaml` — type checking
* `biome-check.yaml` — lint/format (Tuturuuu uses **Biome**, not ESLint/Prettier)
* `ci-check.yml` — validates CI configuration
* `vercel-preview-finance.yaml`, `vercel-preview-calendar.yaml`, `vercel-preview-drive.yaml`, ... — one preview-deploy workflow per app
* `rust-backend.yml` — builds/tests `apps/backend`

The independence comes from Turborepo only running tasks for changed packages plus separate Vercel projects per app, rather than from one CI file per service.

```bash theme={null}
# How affected work is scoped locally and in CI
bun turbo run test --filter=@tuturuuu/web
bun turbo run build --filter=@tuturuuu/finance
```

**Turborepo task configuration.** The repo runs **Turborepo 2.x**, which uses the `tasks` key (the older `pipeline` key was removed in v2):

```json theme={null}
// turbo.json (real key is "tasks", not "pipeline")
{
  "$schema": "https://turbo.build/schema.json",
  "tasks": {
    "test": {
      "cache": true
    },
    "build": {
      "dependsOn": ["^build"],
      "outputs": [".next/**", "!.next/cache/**", "dist/**"],
      "cache": true
    }
  }
}
```

#### Clarifying Additions

**Tests run in parallel without interfering with each other.** Multiple teams can have their tests running simultaneously, reducing wait times.

**Failures stay localized to the affected service.** A failing test in the finance service doesn't prevent the web app from deploying.

**Delivery becomes smoother and less risky.** Smaller, focused deployments are easier to verify and roll back if needed.

***

## Deployability

Deployability determines how easily and safely we can release changes to production. Good deployability enables frequent, low-risk deployments.

### 1. Independent Deployment Pipelines

#### Architectural Choice

Each microservice is independently deployable with its own release cycle, allowing teams to ship updates without coordinating across the organization.

#### Impact and Justification

Monolithic architectures force **all-or-nothing deployments**. Every change, no matter how small or isolated, requires rebuilding and redeploying the entire application. This creates:

* **Deployment bottlenecks**: Teams must coordinate release windows
* **High-risk releases**: Large deployments contain many changes, increasing failure probability
* **Slow feedback**: Small fixes take days to reach production
* **Deployment fear**: Teams avoid deploying due to coordination overhead

**Independent deployment** eliminates these problems. Each service ships on its own schedule:

* **Fast iteration**: Deploy bug fixes minutes after they're written
* **Low risk**: Small, focused deployments are easier to verify and roll back
* **Team autonomy**: No cross-team coordination required for deployments
* **Continuous delivery**: Deploy multiple times per day without fear

**In Tuturuuu today:** there is no `bun deploy:web` / `bun deploy:finance` / `bun deploy:calendar` command. Each app is a **separate Vercel project**, driven by its own GitHub Actions workflow, so deploys are already decoupled per app:

```text theme={null}
.github/workflows/
├── vercel-preview-finance.yaml    // Finance app preview/deploy
├── vercel-preview-calendar.yaml   // Calendar app preview/deploy
├── vercel-preview-drive.yaml      // Drive app preview/deploy
├── vercel-preview-apps.yaml       // Shared preview orchestration
└── rust-backend.yml               // apps/backend (Rust) build + deploy
```

Each workflow builds only the shared dependencies that app needs (via Turborepo `--filter`) and ships that one Vercel project. Deploying finance does not rebuild or redeploy web or calendar.

<Note>
  The Rust `apps/backend` (port `7820`) deploys on its own track (`rust-backend.yml`), independent of the Vercel front-ends — another axis of deployment independence introduced by the migration.
</Note>

#### Clarifying Additions

**Teams ship updates without affecting others.** Finance deployments don't trigger web redeployments or risk breaking calendar functionality.

**Releases become smaller and less risky.** Instead of deploying 50 changes from 10 teams, each team deploys 5 changes independently.

**This improves overall delivery speed.** Removing coordination overhead and deployment fear leads to more frequent, confident releases.

***

### 2. Controlled Rollout Strategies Through Architectural Boundaries

#### Architectural Choice

Service boundaries enable granular deployment strategies like canary releases, blue-green deployments, and feature flags, allowing changes to be introduced gradually.

#### Impact and Justification

Even with small deployments, risk remains. A bug can slip through testing and impact production users. **Controlled rollout strategies** mitigate this risk by:

* **Gradual exposure**: New versions serve only a small percentage of traffic initially
* **Monitoring**: Observe error rates and performance before full rollout
* **Quick rollback**: Instantly revert to previous version if issues detected
* **Confidence**: Deploy with confidence knowing failures impact minimal users

Service boundaries make these strategies practical because each service can have independent routing and versioning.

<Note>
  **Mixed: real platform capability + illustrative code.** Per-app Vercel projects give Tuturuuu **atomic, instantly-revertible deployments** and preview URLs per change — that part is real. However, Tuturuuu does **not** ship the `featureFlags.get/enable(...)` service or the `switchTraffic('blue' -> 'green')` / `supabase.rpc('run_migration')` orchestration shown below; those are conceptual illustrations of canary, feature-flag, and blue-green strategies, not repo APIs. (Tuturuuu's Supabase migrations are plain SQL applied via the migration workflow, not an RPC call.)
</Note>

```typescript theme={null}
// Conceptual: canary deployment (Vercel handles atomic deploy + instant rollback)
// New version serves 10% of traffic initially

// vercel.json
{
  "name": "tuturuuu-finance",

  // Vercel automatically does canary deployments
  // 1. Deploy new version
  // 2. Route 10% traffic to new version
  // 3. Monitor error rates
  // 4. Gradually increase to 100% if healthy
  // 5. Automatic rollback if error rates spike
}

// Feature flags for gradual feature rollout
export async function getFinanceFeatures(workspaceId: string) {
  const flags = await featureFlags.get(workspaceId);

  return {
    advancedReports: flags.has('finance.advanced-reports'),
    aiForecasting: flags.has('finance.ai-forecasting'),
    multiCurrency: flags.has('finance.multi-currency'),
  };
}

// Enable feature for specific workspaces first
await featureFlags.enable('finance.ai-forecasting', {
  workspaces: ['ws-beta-1', 'ws-beta-2'] // Beta test
});

// Monitor performance and errors
const metrics = await monitorFeature('finance.ai-forecasting', '24h');

if (metrics.errorRate < 0.01 && metrics.userSatisfaction > 0.8) {
  // Gradually roll out to more users
  await featureFlags.enable('finance.ai-forecasting', {
    percentage: 50 // 50% of all workspaces
  });
}

// Full rollout after validation
await featureFlags.enable('finance.ai-forecasting', {
  percentage: 100 // Everyone
});
```

**Blue-green deployment (conceptual snippet).** Tuturuuu's self-hosted Docker deploy does use a real blue/green release watcher (snapshot + cutover) for the web app, but it is driven by deployment scripts, not the `switchTraffic(...)` / `supabase.rpc(...)` calls shown here. Read this as the idea, not the API:

```typescript theme={null}
// Run migrations on "green" environment
// Switch traffic after validation

// 1. Green environment: Apply migration
await supabase.rpc('run_migration', {
  migration: '20241117_add_ai_forecasting'
});

// 2. Verify green environment health
const healthy = await verifyGreenEnvironment();

if (healthy) {
  // 3. Switch traffic from blue to green
  await switchTraffic('blue' -> 'green');

  // 4. Monitor for issues
  setTimeout(() => {
    if (metricsLookGood()) {
      // 5. Destroy blue environment
      destroyBlueEnvironment();
    } else {
      // Rollback: Switch back to blue
      switchTraffic('green' -> 'blue');
    }
  }, 3600000); // Monitor for 1 hour
}
```

#### Clarifying Additions

**New versions introduce changes gradually instead of all at once.** Risk is minimized by limiting exposure to a small percentage of users or specific cohorts.

**Issues surface early in controlled conditions.** Problems are detected when only 10% of users are affected, allowing quick rollback before widespread impact.

**This improves deployment safety.** Teams deploy confidently knowing that issues will be caught early and can be mitigated quickly.

***

### 3. Architecture-Supported Environment Consistency

#### Architectural Choice

Infrastructure as Code (IaC) and containerization ensure that development, staging, and production environments are consistent and reproducible.

#### Impact and Justification

The classic "works on my machine" problem stems from environment inconsistencies. Code behaves differently in production than in development due to different:

* Dependencies and versions
* Environment variables and configuration
* Infrastructure and scaling behavior
* Operating systems and system libraries

**Architecture-supported environment consistency** eliminates this by:

* **Defining environments as code** that can be version-controlled
* **Using containers** to ensure identical runtime across environments
* **Automating setup** to prevent manual configuration drift
* **Validating consistency** through automated checks

**In Tuturuuu - Environment consistency:**

```typescript theme={null}
// .env.example - template for all environments
// Developers, staging, and production use same variables

NEXT_PUBLIC_SUPABASE_URL=
SUPABASE_SECRET_KEY=
TRIGGER_API_KEY=
DATABASE_URL=

// Environment-specific .env files
// .env.local (development)
// .env.staging (staging)
// .env.production (production)

// All have same structure, different values
```

**Vercel environment configuration:**

```json theme={null}
// vercel.json ensures consistency
{
  "env": {
    // Required in all environments
    "NEXT_PUBLIC_SUPABASE_URL": "@supabase-url",
    "SUPABASE_SECRET_KEY": "@supabase-service-key"
  },

  "build": {
    "env": {
      // Build-time variables. The platform version is owned by Release Please
      // and read from TUTURUUU_PLATFORM_VERSION in
      // packages/utils/src/platform-release.ts — do not hard-code a literal here.
      "NEXT_PUBLIC_APP_VERSION": "$TUTURUUU_PLATFORM_VERSION"
    }
  }
}
```

**Pinned toolchain ensures runtime consistency.** The repo pins its toolchain so every environment resolves identical versions: `packageManager` is `bun@1.3.14`, and Node `engines` require `>=22`. A container image would mirror those pins:

```dockerfile theme={null}
# Illustrative Dockerfile — keep versions aligned with package.json pins
FROM oven/bun:1.3.14 as base

WORKDIR /app

# Install dependencies (frozen lockfile => same versions everywhere)
COPY package.json bun.lock ./
RUN bun install --frozen-lockfile

COPY . .
RUN bun run build

# Production image (identical across environments)
FROM oven/bun:1.3.14-slim
WORKDIR /app
COPY --from=base /app/.next ./.next
COPY --from=base /app/node_modules ./node_modules
COPY --from=base /app/package.json ./

CMD ["bun", "run", "start"]
```

**Supabase local development matches production.** Migrations are written once and applied identically; type generation keeps types in sync:

```bash theme={null}
# Start local Supabase (mirrors the production schema)
bun sb:start

# Author and apply migrations locally
bun sb:new      # scaffold a new migration
bun sb:up       # apply migrations to the local database

# Regenerate DB types after schema changes
bun sb:typegen
```

<Warning>
  Production migrations are applied by a maintainer, not from agent/CI prose. Do **not** run `bun sb:push` / `bun sb:linkpush` from this workflow — prepare the migration and let the owner apply it.
</Warning>

#### Clarifying Additions

**Environments remain aligned through structured definitions.** Configuration as code prevents drift between development, staging, and production.

**Deployment steps become predictable across stages.** The same deployment process works identically in all environments, reducing deployment-specific issues.

**This reduces surprises when promoting changes.** Code that works in staging will work in production because environments are consistent.

***

## Quality Attributes Summary

The table separates what is **implemented today** from patterns presented as **teaching models / aspirational** so the mechanisms aren't read as all-adopted.

| Attribute           | Implemented today                                                                                                                                                            | Illustrative / aspirational                                                      | Primary Benefit                 |
| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- | ------------------------------- |
| **Maintainability** | App + feature-folder boundaries, shared Supabase + `@tuturuuu/types/db`, shared `packages/internal-api` / `packages/apis`, modular Next.js frontend, per-app Vercel projects | Hexagonal ports/adapters, repository interfaces, technology-swap seams           | Sustainable long-term evolution |
| **Testability**     | Vitest unit + colocated `*.test.ts`, Zod payload validation, Turborepo affected-package CI                                                                                   | Pure domain objects, in-memory test doubles, formal contract tests, event replay | High confidence in changes      |
| **Deployability**   | Per-app Vercel preview/deploy workflows, separate Rust `apps/backend` track, pinned toolchain (`bun@1.3.14`, Node `>=22`), Supabase migrations + typegen                     | Canary/blue-green orchestration scripts, custom feature-flag service             | Frequent, low-risk releases     |

<Note>
  These properties are being preserved through the `apps/web` → `apps/tanstack-web` + Rust `apps/backend` migration. See [TanStack + Rust Migration](/platform/architecture/tanstack-rust-migration).
</Note>

## Related Documentation

* [Core Architectural Decisions](/platform/architecture/system-design/architectural-decisions) - Why we chose this architecture
* [Layering Patterns](/platform/architecture/system-design/layering-patterns) - N-tier vs Hexagonal/Clean architecture
* [Hexagonal Architecture](/platform/architecture/system-design/hexagonal-architecture) - Ports and adapters in detail
* [Microservices Patterns](/platform/architecture/system-design/microservices-patterns) - Service boundaries and deployment
* [Event-Driven Architecture](/platform/architecture/system-design/event-driven-architecture) - Event streaming patterns
* [Observability & Monitoring](/platform/architecture/system-design/observability-monitoring) - Testing in production


# Security Architecture
Source: https://docs.tuturuuu.com/platform/architecture/system-design/security-architecture

Comprehensive security justification and architectural security patterns in Tuturuuu

Security is a foundational architectural concern in Tuturuuu, embedded at every level of the system design. This document explains the core architectural patterns that provide comprehensive security coverage.

<Note>
  This document focuses on **architecture-level security patterns**. For implementation details, see:

  * [Authentication](/platform/architecture/authentication) - User authentication flows
  * [Authorization](/platform/architecture/authorization) - Permission system
  * [RLS Policies](/reference/database/rls-policies) - Row-level security implementation
</Note>

<Warning>
  **What is real vs. illustrative.** Tuturuuu's web tier (`apps/web`) is a conventional Next.js App Router app, not a network of independently keyed microservices. Several patterns below (a single API gateway, service-to-service token exchange, an immutable event-sourced audit log) are presented as **conceptual / target patterns** to explain the reasoning — they are explicitly labeled where they are not implemented as written. The concrete code examples (the `withApiAuth` wrapper, Supabase Row-Level Security, the Rust backend's Supabase auth) reflect the real codebase.

  The platform is also mid-migration: `apps/web` (Next.js, port `7803`) is being replaced by `apps/tanstack-web` (TanStack Start) plus `apps/backend` (Rust, port `7820`). See [TanStack Start And Rust Migration](/platform/architecture/tanstack-rust-migration) for how security responsibilities move into the Rust backend.
</Warning>

## 1. Consistent Security Enforcement at the API Boundary

### Architectural Choice

Rather than a literal standalone API gateway, Tuturuuu enforces security **consistently at the API route boundary** through a shared higher-order wrapper. Every public SDK route under `apps/web/src/app/api/v1/*` is wrapped with `withApiAuth`, which centralizes the security logic (API-key authentication, rate limiting, permission checks) in one tested implementation instead of re-deriving it per route.

<Note>
  **Conceptual vs. real.** "API gateway" describes the *pattern* — a single, uniform enforcement point — not a literal gateway process in front of microservices. In `apps/web` there is no separate gateway tier; security is enforced per route. The uniformity comes from sharing the `withApiAuth` wrapper (`apps/web/src/lib/api-middleware.ts`), Next.js `middleware.ts`, and Vercel's edge. In the [TanStack + Rust migration](/platform/architecture/tanstack-rust-migration), the Rust backend (`apps/backend`) becomes the primary boundary that validates Supabase sessions.
</Note>

### Impact and Justification

By funneling authentication and authorization through one shared wrapper, we create a **single security control plane in code**: policies are defined once and applied consistently before any business logic runs. Routes do not re-implement token parsing, key validation, or rate-limiting individually, which removes the drift and duplication that cause inconsistent security postures.

**Conceptual enforcement flow (illustrative, not a literal gateway process):**

```typescript theme={null}
// The shared concerns withApiAuth applies before your handler runs:
// 1. IP-based pre-auth rate limiting (cheap flood rejection)
// 2. API-key authentication against the database
// 3. Adaptive, key- and workspace-scoped rate limiting
// 4. Declarative permission checks
// 5. Workspace-scoped data access via an admin Supabase client
```

**Real example from Tuturuuu's SDK API** (`apps/web/src/app/api/v1/storage/list/route.ts`):

```typescript theme={null}
export const GET = withApiAuth(
  async (request, { context }) => {
    // Security is already enforced by the withApiAuth wrapper:
    // - API key authenticated
    // - Rate limiting applied (IP pre-auth + key/workspace-scoped)
    // - 'manage_drive' permission verified for this workspace
    const { wsId } = context;

    // Use the admin client for SDK routes (no user session cookies).
    // createDynamicAdminClient is async — await it.
    const supabase = await createDynamicAdminClient();

    return supabase.storage.from('workspaces').list(wsId /* ... */);
  },
  {
    permissions: ['manage_drive'], // Declarative authorization
    // Custom limits are also supported, e.g.:
    // rateLimit: { windowMs: 60000, maxRequests: 20 }
  }
);
```

Note that `rateLimit` is optional: by default `withApiAuth` leaves `GET`/`HEAD` reads open and applies a per-key mutation limit (about 100 requests/minute), with workspace-specific overrides read from `workspace_secrets`. Pass a `rateLimit` object only to tighten or relax those defaults.

### Clarifying Additions

**Shared enforcement ensures uniform security behavior across routes.** Instead of each route implementing authentication differently, `withApiAuth` provides a single, tested implementation every endpoint benefits from.

**Policies update consistently without touching each route.** When a new requirement emerges (e.g., a stricter default rate limit), it is implemented once in the wrapper and immediately applies everywhere it is used.

**This strengthens protection by eliminating inconsistent security implementations.** Human error is reduced because developers do not re-implement the same security logic across many routes.

***

## 2. Zero Trust Principles Applied at the Architectural Level

### Architectural Choice

The architecture implements Zero Trust security principles, where no service or request is inherently trusted based on its network location or source. Every interaction, whether from external clients or between internal services, must be explicitly authenticated and authorized.

### Impact and Justification

Traditional "castle-and-moat" security assumes that anything inside the network perimeter is trusted. This is a dangerous assumption because once an attacker breaches the perimeter, they have unrestricted access to internal systems.

Zero Trust architecture **eliminates implicit trust**. Every request is re-validated for identity and permissions at the boundary it crosses, and the database independently enforces access rules regardless of which app issued the query.

<Warning>
  **No inter-service token system exists.** Tuturuuu does **not** implement service-to-service token exchange (`generateServiceToken`, `X-Service-Id` headers, per-service token verification). The apps share a single Supabase Postgres database, and Zero Trust is realized through **(a) request authentication at each API boundary** and **(b) Row-Level Security in the database** — not a mesh of mutually authenticating services. The example below shows how the apps actually establish identity, not a fictional token broker.
</Warning>

**How identity is established in practice.** Every request that reaches data must carry a verifiable identity, and that identity is re-checked at the boundary:

* **User requests** carry a Supabase session (cookie or `Authorization: Bearer` access token). The Rust backend validates these in `apps/backend/src/supabase_auth.rs`, which extracts the access token from the `sb-*-auth-token` cookie (including base64-prefixed, chunked cookies) or a non-app Bearer token, then calls the Supabase Auth `/user` endpoint with the service-role key to resolve the user.
* **SDK / machine requests** carry a workspace-scoped API key, authenticated and rate-limited by `withApiAuth` in `apps/web` before any handler runs.

```rust theme={null}
// apps/backend/src/supabase_auth.rs — real backend auth (simplified)
// 1. Pull the access token from a Bearer header or the Supabase auth cookie.
// 2. Verify it against Supabase Auth's /user endpoint using the service-role key.
// 3. Only a verified user proceeds; nothing is trusted by network location.
let access_token = request_access_token(request)?;            // bearer or cookie
let user = fetch_supabase_auth_user(contact_data, &access_token, outbound).await?;
```

There is no per-service shared secret to leak: trust derives from a Supabase-issued token (validated against Supabase) or a workspace API key (validated against the database), and the database enforces the final word via RLS.

**Database-level Zero Trust (Row-Level Security):**

```sql theme={null}
-- RLS policy ensures data access is validated at database level
-- Even if application code is compromised, database enforces security

CREATE POLICY "workspace_members_select_policy"
ON workspace_members FOR SELECT
TO authenticated
USING (
  -- User can only see members of workspaces they belong to
  EXISTS (
    SELECT 1 FROM workspace_members wm
    WHERE wm.ws_id = workspace_members.ws_id
    AND wm.user_id = auth.uid()
  )
);
```

### Clarifying Additions

**Identity is established from verifiable tokens, not network location.** A request is trusted because it carries a valid Supabase session or workspace API key that is re-validated at the boundary — not because it originated inside the deployment.

**The database has the final say.** Even if an API layer were bypassed or compromised, RLS policies independently enforce that a user can only read or write rows for workspaces they belong to. Application bugs cannot silently defeat data-access rules.

**This reduces risks associated with implicit trust.** Because authorization is enforced both at the boundary and in the database, a single compromised layer does not grant unrestricted data access.

***

## 3. Security Boundaries Through RLS and Permission Scoping

### Architectural Choice

Isolation between domains (finance, AI chat, drive, tasks) is enforced primarily by **per-table Row-Level Security policies and scoped permissions**, not by giving each app its own Supabase project or key. The apps share one Supabase database; the boundary lives in the policies and in the permission set each API key or user role is granted.

<Warning>
  **Per-app anon keys are not how this works.** Earlier revisions of this page implied distinct `WEB_ANON_KEY`, `FINANCE_ANON_KEY`, and `REWISE_ANON_KEY` values backing separate "services". That is **not accurate** — Tuturuuu's apps share a single Supabase project and the same anon/service-role keys. Domain isolation comes from RLS policies and permission scoping on shared tables, described below.
</Warning>

### Impact and Justification

In a single shared database, a vulnerability that bypasses one route must still defeat the per-table RLS policy to reach data. By scoping each domain's tables with **dedicated policies and permission requirements**, we contain the blast radius: a bug in a drive route cannot read finance rows, because the finance policy requires finance-specific roles and the request's identity does not satisfy them.

Concretely, SDK routes declare the permissions they need (`permissions: ['manage_drive']`), and the database enforces an orthogonal check at query time. An attacker who somehow reaches a query path is still bounded by both the granted permission scope and the row-level policy.

**Data isolation through RLS policy design:**

```sql theme={null}
-- Finance-specific tables with dedicated RLS policies
CREATE TABLE finance_transactions (
  id UUID PRIMARY KEY,
  workspace_id UUID NOT NULL,
  amount DECIMAL NOT NULL,
  -- ... other fields
);

-- RLS policy specific to finance module
CREATE POLICY "finance_transactions_policy"
ON finance_transactions
TO authenticated
USING (
  -- Only users with finance permissions in workspace
  EXISTS (
    SELECT 1 FROM workspace_members wm
    WHERE wm.ws_id = finance_transactions.workspace_id
    AND wm.user_id = auth.uid()
    AND wm.role IN ('owner', 'admin', 'finance_manager')
  )
);

-- AI chat tables completely separate
CREATE TABLE ai_chat_messages (
  id UUID PRIMARY KEY,
  workspace_id UUID NOT NULL,
  message TEXT NOT NULL,
  -- ... other fields
);

-- Different RLS policy for AI data
CREATE POLICY "ai_chat_messages_policy"
ON ai_chat_messages
TO authenticated
USING (
  EXISTS (
    SELECT 1 FROM workspace_members wm
    WHERE wm.ws_id = ai_chat_messages.workspace_id
    AND wm.user_id = auth.uid()
  )
);
```

### Clarifying Additions

**A bug in one domain's routes does not expose another domain's data.** RLS policies and permission scoping bound each domain independently, so reaching a finance table requires finance-grade identity even from an unrelated route.

**Policies act as an independent barrier alongside application checks.** Defense in depth is achieved because the database re-validates access regardless of what the application layer believed.

**This scoping limits the damage in security incidents.** Incident response is more manageable because the data an attacker could reach is bounded by the policies and permissions that gate each table.

***

## 4. Defense-in-Depth via Layered Architecture

### Architectural Choice

The architecture implements multiple layers of security controls, from the network edge through the API Gateway, into the application services, down to the database layer. Each layer provides independent security validation.

### Impact and Justification

Relying on a single security layer is fragile. If that layer is bypassed or fails, the entire system is exposed. The **defense-in-depth** approach ensures that even if an attacker successfully bypasses one security control, they encounter additional independent security barriers at deeper layers.

For example, even if an attacker bypassed the API boundary's authentication (highly unlikely but theoretically possible), they would still encounter:

1. **Route-level authorization** checks (declared permissions) in the application code
2. **Database Row-Level Security** policies that enforce data access rules
3. **Workspace scoping** that bounds every query to the caller's workspace

**In Tuturuuu - Multiple Security Layers:**

**Layer 1: Edge / Boundary Security**

```typescript theme={null}
// First line of defense — applied by withApiAuth + Next.js middleware + Vercel edge:
// - API-key / session authentication
// - IP-based and key/workspace-scoped rate limiting
// - Request validation (e.g. zod query schemas)
// Note: there is no separate gateway process; these run at the route boundary.
```

**Browser framing boundary.** Every Next.js app that uses
`createTuturuuuNextConfig` receives `Content-Security-Policy: frame-ancestors
'none'` and `X-Frame-Options: DENY` on its responses. This prevents an
attacker-controlled page from rendering Tuturuuu interfaces inside an iframe
for UI redressing. App-specific `headers()` entries are composed after the
shared security rule, so route-specific cache and indexing headers remain
intact.

The only shared exception is the CMS WebGL asset route
`/api/v1/workspaces/:wsId/external-projects/assets/:assetId/webgl/*`. The CMS
player intentionally renders that document in a sandboxed iframe without
`allow-same-origin`; the asset route keeps its own restrictive CSP sandbox
policy. New framing exceptions must be path-specific, justified by a documented
product requirement, and preserve an equivalent sandbox boundary.

**Layer 2: Application-Level Security**

```typescript theme={null}
// Second line of defense - Application logic
export async function handleFinanceRequest(request: Request) {
  const user = await getCurrentUser(); // Verify user session

  // Application-level authorization
  const hasPermission = await userHasFinanceAccess(user.id, workspaceId);
  if (!hasPermission) {
    throw new ForbiddenError('No finance access');
  }

  // Business logic with additional checks
  return processFinanceOperation();
}
```

**Layer 3: Database-Level Security**

```sql theme={null}
-- Third line of defense - Database RLS
CREATE POLICY "finance_access_policy"
ON finance_transactions
TO authenticated
USING (
  -- Even if application is compromised,
  -- database enforces access control
  workspace_id IN (
    SELECT ws_id FROM workspace_members
    WHERE user_id = auth.uid()
    AND role IN ('owner', 'admin', 'finance_manager')
  )
);
```

**Layer 4: Data Encryption**

```typescript theme={null}
// Fourth line of defense - Encryption at rest
// Supabase automatically encrypts data at rest
// Sensitive fields additionally encrypted in application

async function storeSensitiveData(data: SensitiveData) {
  const encrypted = await encrypt(data, ENCRYPTION_KEY);
  await database.insert({
    data: encrypted,
    // Even with database access, data is encrypted
  });
}
```

### Clarifying Additions

**Multiple layers ensure no single point of failure exposes sensitive logic.** An attacker must defeat multiple independent security controls to compromise the system, making successful attacks exponentially harder.

**Higher layers validate and protect the domain before requests reach it.** The most critical business logic (the domain core) is protected by multiple security barriers, ensuring it only processes validated, authorized requests.

**The system becomes safer by distributing security responsibility across layers.** Security is not the responsibility of a single component but is woven throughout the architecture, creating a more resilient security posture.

***

## 5. Auditability and Background Security Workflows

### Architectural Choice

Security-relevant actions should be traceable, and heavier security workflows (anomaly scans, notifications, periodic reviews) should run as durable background jobs. Tuturuuu uses **Trigger.dev v4 `task()`** for background work and native server console logs plus retained platform observability data for server-side diagnostics.

<Warning>
  **Aspirational, not implemented as written.** A comprehensive, cryptographically signed, immutable, event-sourced audit log is a **target pattern**, not a shipped subsystem. Tuturuuu does not have an event store or event-sourcing layer, and there is no global `audit_events` table that captures every state change. Treat the audit-log code below as an illustration of the goal. What exists today: Supabase keeps row history where tables are designed for it, retained platform observability data records selected server-side events, Trigger.dev runs durable background tasks, and runtime diagnostics use the native console method matching severity.
</Warning>

### Impact and Justification

Security is not just about prevention; it's also about **detection and accountability**. A durable, append-only audit trail would provide:

1. **Forensic Analysis**: After an incident, history lets investigators reconstruct what happened, when, and by whom
2. **Compliance**: Regulations (GDPR, SOX, HIPAA) require audit trails of data access and modifications
3. **Anomaly Detection**: Patterns can be analyzed to detect suspicious behavior (e.g., unusual access patterns, privilege escalation)
4. **Non-Repudiation**: Append-only, tamper-evident records provide strong proof of actions

**Target audit-write pattern (aspirational — illustrates intent):**

```typescript theme={null}
// Illustrative: how a critical operation could record an audit entry.
// There is no global event store today; persist via your table's history
// mechanism and emit server-side logs through native console methods.
export async function updateWorkspaceSettings(
  workspaceId: string,
  settings: WorkspaceSettings,
  userId: string
) {
  const previousSettings = await getSettings(workspaceId);

  // Apply the change.
  await updateSettings(workspaceId, settings);

  // Record an audit entry (target: append-only audit table or log-drain).
  await recordAuditEntry({
    event: 'workspace.settings.updated',
    workspaceId,
    userId,
    previousSettings,
    newSettings: settings,
    occurredAt: new Date().toISOString(),
  });
}

// Security-sensitive event names worth auditing (illustrative set)
export const AUDIT_EVENTS = {
  'user.login': 'User authentication',
  'user.logout': 'User session end',
  'user.password.changed': 'Password modification',
  'user.mfa.enabled': 'MFA enabled',
  'user.mfa.disabled': 'MFA disabled',
  'workspace.member.added': 'Member added to workspace',
  'workspace.member.removed': 'Member removed from workspace',
  'workspace.role.changed': 'Member role modified',
  'finance.transaction.created': 'Financial transaction',
  'data.export.requested': 'Data export initiated',
  'api.key.created': 'API key generated',
  'api.key.revoked': 'API key revoked',
} as const;
```

**Audit Log Query Interface (target shape):**

```typescript theme={null}
// Illustrative: querying an append-only audit table once one exists.
export async function getAuditLog(filters: AuditFilters) {
  const supabase = await createDynamicAdminClient(); // async — await it
  return supabase
    .from('audit_events')
    .select('event_type, user_id, workspace_id, created_at, payload')
    .eq('workspace_id', filters.workspaceId)
    .gte('created_at', filters.startDate)
    .lte('created_at', filters.endDate)
    .in('event_type', filters.events)
    .order('created_at', { ascending: false });
}
```

**Background security workflow (real Trigger.dev v4 `task()` API):**

Trigger.dev v4 uses the `task()` builder (`@trigger.dev/sdk` `^4.4.5`). The v2 API (`client.defineJob`, `eventTrigger`, `io.*`) does **not** exist in this repo. A security-scan task looks like the calendar/schedule tasks under `packages/trigger/src`:

```typescript theme={null}
import { task } from '@trigger.dev/sdk/v3';

// A task you trigger (e.g. from an API route) when repeated auth failures
// are observed, to evaluate and respond to a possible brute-force attempt.
export const securityScanTask = task({
  id: 'security-scan',
  queue: { concurrencyLimit: 5 },
  run: async (payload: { userId: string; windowSeconds?: number }) => {
    const recentFailures = await countRecentLoginFailures(
      payload.userId,
      payload.windowSeconds ?? 300 // 5 minutes
    );

    if (recentFailures > 5) {
      // Respond (e.g. temporary lock + notify) and return a structured result.
      await applyTemporaryLock(payload.userId);
      return { userId: payload.userId, action: 'account.lock.temporary' };
    }

    return { userId: payload.userId, action: 'none' };
  },
});
```

Trigger it from server code with `securityScanTask.trigger({ userId })` (or `batchTrigger` for many). See the [Event-Driven Architecture](/platform/architecture/system-design/event-driven-architecture) page for how Tuturuuu actually uses Trigger.dev v4 and native server console logs.

### Clarifying Additions

**Durable background tasks keep heavy security work off the request path.** Anomaly scans and notifications run as Trigger.dev v4 tasks rather than blocking the user's request.

**An append-only audit trail would support accountability and forensics.** This is the target; today, rely on retained platform observability data, native server console logs, and table-level history for traceability.

**Compliance benefits from consistent logging.** Use the native console method matching severity and retain structured metadata where platform observability wrappers are wired.

***

## Security Architecture Summary

| Security Layer        | Mechanism                  | Protection Provided                                   | Implementation in Tuturuuu                                                                                                            |
| --------------------- | -------------------------- | ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| **Boundary Security** | Shared auth wrapper        | Consistent authentication, rate limiting, validation  | `withApiAuth` + Next.js `middleware.ts` + Vercel edge; Rust backend validates Supabase sessions (`apps/backend/src/supabase_auth.rs`) |
| **Zero Trust**        | Token re-validation        | Identity from verifiable tokens, not network location | Supabase session / workspace API-key validation at each boundary                                                                      |
| **Domain Isolation**  | RLS + permission scoping   | Blast-radius containment on a shared database         | Per-table RLS policies + declared route permissions (shared Supabase project)                                                         |
| **Defense-in-Depth**  | Layered controls           | Multiple independent security checks                  | Boundary + App + Database RLS + Supabase encryption at rest                                                                           |
| **Auditability**      | Logging + background tasks | Traceability, anomaly response                        | Log-drain logger + Trigger.dev v4 tasks (append-only audit table is *aspirational*)                                                   |

## Security Best Practices in Tuturuuu

### 1. Never Trust, Always Verify

* Every request validated at multiple layers
* No assumptions about request origin or authenticity
* All user input sanitized and validated

### 2. Principle of Least Privilege

* Services granted minimum permissions needed
* Users granted minimum roles required
* API keys scoped to specific operations

### 3. Fail Securely

* Default deny for authorization decisions
* Explicit permission grants required
* Errors don't leak sensitive information

### 4. Defense in Depth

* Multiple layers of security controls
* Redundant security checks
* No single point of failure

### 5. Audit Everything

* All security-relevant events logged
* Immutable audit trail
* Regular security audits and reviews

## Security Under the TanStack + Rust Migration

`apps/web` (Next.js, port `7803`) is being replaced by `apps/tanstack-web` (TanStack Start) plus `apps/backend` (Rust, port `7820`). Several security responsibilities move accordingly:

* **Boundary authentication** shifts into the Rust backend (`apps/backend/src/supabase_auth.rs`), which validates Supabase access tokens from cookies or Bearer headers against Supabase Auth using the service-role key.
* **TanStack web** must not call `/trpc` or raw app APIs directly (a guard, `check-tanstack-api-access`, enforces this); product data flows through `packages/internal-api` helpers and REST `/api/v1` routes.
* **RLS remains the durable backstop** across both stacks because both share the same Supabase project.

See [TanStack Start And Rust Migration](/platform/architecture/tanstack-rust-migration) for the full migration contract.

## Related Documentation

* [Authentication](/platform/architecture/authentication) - User authentication implementation
* [Authorization](/platform/architecture/authorization) - Permission system and role-based access
* [RLS Policies](/reference/database/rls-policies) - Database-level security
* [TanStack Start And Rust Migration](/platform/architecture/tanstack-rust-migration) - How the boundary moves into the Rust backend
* [Encapsulation Patterns](/platform/architecture/system-design/encapsulation-patterns) - Service boundary enforcement
* [Event-Driven Architecture](/platform/architecture/system-design/event-driven-architecture) - Trigger.dev v4 tasks and background workflows


# TanStack Start And Rust Migration
Source: https://docs.tuturuuu.com/platform/architecture/tanstack-rust-migration

Migration contract for replacing apps/web with apps/tanstack-web plus the Rust backend

`apps/tanstack-web` is the replacement frontend for the legacy Next.js
`apps/web` runtime. It uses TanStack Start, TanStack Router, TanStack Query,
Vite, React 19, Tailwind 4, and the existing Tuturuuu shared packages.

`apps/backend` is the planned Rust API runtime. Do not create another backend
service for this migration; extend `apps/backend` route groups and keep API
contracts documented in `apps/backend/api/openapi.yaml`.

<Warning>
  `apps/backend` is not currently deployed and receives no production traffic.
  `apps/web` remains the live API runtime. A route marked `migrated` in this
  document means its future Rust source contract is implemented and tested; it
  does not mean that request routing has cut over.
</Warning>

The crate can run as a native container and keeps a Cloudflare Workers Rust
entrypoint in `apps/backend/wrangler.jsonc` for future, explicitly approved
preview deployment.

For exact local run commands and deployment steps across native local, Docker,
Cloudflare Workers, Vercel, and VPS/Cloudflare Tunnel paths, use
[TanStack/Rust Local And Deployment](/build/devops/tanstack-rust-local-deploy).

## Runtime Shape

| Runtime      | Local URL                             | Fallback port | Owner               |
| ------------ | ------------------------------------- | ------------: | ------------------- |
| Legacy web   | `https://tuturuuu.localhost`          |        `7803` | `apps/web`          |
| TanStack web | `https://tanstack.tuturuuu.localhost` |        `7824` | `apps/tanstack-web` |
| Rust backend | `http://localhost:7820`               |        `7820` | `apps/backend`      |

Use `bun dev:tanstack-web` for local TanStack work. Docker dev also exposes the
`tanstack-web` service on port `7824` and injects `BACKEND_PUBLIC_ORIGIN`,
`BACKEND_INTERNAL_URL`, and `BACKEND_INTERNAL_TOKEN` for Rust backend calls.
Cloudflare preview uses the `BACKEND` service binding first and keeps
`BACKEND_INTERNAL_URL` as an HTTP fallback for local, Docker, and emergency
non-binding runs.

## Rendering And Cache Policy

Every migrated TanStack route must declare its rendering/cache class before it
is marked terminal in `route-overrides.json`:

| Class                         | Use for                                                                                | Required implementation                                                                                                                                            |
| ----------------------------- | -------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Static prerender              | Public routes whose HTML is fully local/static at build time.                          | Add the localized path to the `pages` and `prerender` options in `apps/tanstack-web/vite.config.ts`; keep `crawlLinks: true` plus the static-route filter enabled. |
| ISR-style CDN revalidation    | Public routes backed by slow-changing Rust/backend data, such as models and changelog. | Add route-level `headers()` with `Cache-Control` `s-maxage` plus `stale-while-revalidate`; add `CDN-Cache-Control` for Cloudflare.                                 |
| Dynamic no-store              | Authenticated, workspace-scoped, session-specific, or secret-backed routes.            | Do not prerender; use server functions/internal API calls with forwarded auth and no shared-cache headers.                                                         |
| Redirect/static compatibility | Redirect-only compatibility routes such as QR and docs handoffs.                       | Keep redirect behavior exact; only cache when the target contract is public and invariant.                                                                         |

This follows TanStack Start's current guidance: prerender public paths through
the Start Vite plugin, use standard HTTP cache headers for ISR-style pages, and
prefer CDN headers such as `CDN-Cache-Control` for Cloudflare-specific shared
cache control. Official references:
[Static Prerendering](https://tanstack.com/start/latest/docs/framework/react/guide/static-prerendering)
and
[Incremental Static Regeneration](https://tanstack.com/start/latest/docs/framework/react/guide/isr).

The initial prerender set intentionally includes only public, unauthenticated,
non-backend-backed pages. Backend-backed public pages are not prerendered at
build time because Docker, CI, and Cloudflare builds must not require a live
Rust backend just to emit static HTML. Instead, those pages use conservative
ISR-style CDN headers from `apps/tanstack-web/src/lib/platform/cache.ts`.

## Cloudflare Preview Deployment

Cloudflare preview deployments are supported before cutover so the team can
validate the Worker runtime, smoke endpoints, and benchmark numbers without
moving production traffic. The preview path uses:

* `apps/backend/wrangler.jsonc` for the Rust Worker bundle.
* `apps/tanstack-web/wrangler.jsonc` for the TanStack Start Worker.
* `@cloudflare/vite-plugin` in `apps/tanstack-web/vite.config.ts`, registered
  before `tanstackStart()`.
* root `wrangler` tooling plus `bun check:cloudflare` to validate both Worker
  configs without contacting Cloudflare.

Validate the checked Cloudflare contract locally:

```bash theme={null}
bun check:cloudflare
```

Current compatibility contract:

| Runtime                 | Cloudflare entrypoint              | Deploy command                                             | Compatibility status                                                                                                                |
| ----------------------- | ---------------------------------- | ---------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| Rust backend            | `apps/backend/wrangler.jsonc`      | `bun wrangler deploy --config apps/backend/wrangler.jsonc` | Source- and preview-ready, but not currently deployed. The command is reserved for an explicitly approved future preview.           |
| TanStack Start frontend | `apps/tanstack-web/wrangler.jsonc` | `bun --cwd apps/tanstack-web run deploy:cloudflare`        | Preview-ready for migrated public routes, redirects, the root migration shell, and Start server-function calls to the Rust backend. |

`apps/tanstack-web` deployment runs `bun run build` internally through the
app-local `deploy:cloudflare` script. Do not run it during docs-only or
inspection work unless the task explicitly allows build commands. For a
configuration-only preflight, use `bun check:cloudflare`.

Both Wrangler configs declare required secret names with the schema-supported
`secrets.required` property. The validator requires these names and rejects
secret-looking values under `vars`:

| Worker                             | Required preview secrets                                                                                                                                                                              |
| ---------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `apps/backend/wrangler.jsonc`      | `BACKEND_INTERNAL_TOKEN`, `TUTURUUU_APP_COORDINATION_SECRET`, `SUPABASE_URL`, `SUPABASE_SERVICE_ROLE_KEY`, `CRON_SECRET`, `DISCORD_APP_DEPLOYMENT_URL`, `AURORA_EXTERNAL_URL`, `AURORA_EXTERNAL_WSID` |
| `apps/tanstack-web/wrangler.jsonc` | `BACKEND_PUBLIC_ORIGIN`, `BACKEND_INTERNAL_TOKEN`; `BACKEND` service binding to `tuturuuu-backend`                                                                                                    |

For local Worker previews, put secret values next to the owning Wrangler config
in ignored files:

* `apps/backend/.dev.vars`
* `apps/tanstack-web/.dev.vars`

Do not commit `.dev.vars*` or `.env.preview*` files. `bun check:cloudflare`
validates the ignore rules so preview tokens and account-specific Worker
origins do not enter Git.

The backend Worker uses `BACKEND_ENV=preview` in `wrangler.jsonc`. Do not set
Cloudflare preview traffic to `development`; development-only migration routes
remain limited to local development and the explicit local E2E bypass.

Use `wrangler secret put` for initial preview bootstrapping only: Cloudflare
creates and deploys a new active Worker version when that command changes a
secret. For rotations, canaries, or any deployed Worker that already receives
traffic, use `wrangler versions secret put`, then promote the resulting version
with `wrangler versions deploy`.

Deploy the Rust backend Worker first:

```bash theme={null}
rustup target add wasm32-unknown-unknown
cargo install worker-build --locked
bun wrangler secret put BACKEND_INTERNAL_TOKEN --config apps/backend/wrangler.jsonc
bun wrangler secret put TUTURUUU_APP_COORDINATION_SECRET --config apps/backend/wrangler.jsonc
bun wrangler secret put SUPABASE_URL --config apps/backend/wrangler.jsonc
bun wrangler secret put SUPABASE_SERVICE_ROLE_KEY --config apps/backend/wrangler.jsonc
bun wrangler secret put CRON_SECRET --config apps/backend/wrangler.jsonc
bun wrangler secret put DISCORD_APP_DEPLOYMENT_URL --config apps/backend/wrangler.jsonc
bun wrangler secret put AURORA_EXTERNAL_URL --config apps/backend/wrangler.jsonc
bun wrangler secret put AURORA_EXTERNAL_WSID --config apps/backend/wrangler.jsonc
bun wrangler deploy --config apps/backend/wrangler.jsonc
```

`BACKEND_INTERNAL_TOKEN` is required before backend preview deploys are useful:
`/readyz` reports not-ready when the token is missing.
`TUTURUUU_APP_COORDINATION_SECRET` is required before contact/profile preview
routes can verify Tuturuuu `ttr_app_` app-session tokens in production-like
Cloudflare environments. `CRON_SECRET` and `DISCORD_APP_DEPLOYMENT_URL` are
required before the Rust-owned Discord cron proxy routes can call the Discord
app. `AURORA_EXTERNAL_URL` is required before the Rust-owned Aurora health and
ingest routes can call the Aurora service, and `AURORA_EXTERNAL_WSID` is
required before Aurora ingest routes can write rows. Wrangler prompts for
values; do not place those values in `wrangler.jsonc`, `vars`, docs, or shell
history.

`SUPABASE_URL` and `SUPABASE_SERVICE_ROLE_KEY` are required backend Worker
secrets for the Rust-owned contact/profile APIs. They stay server-only: the
backend reads `users` and `user_private_details`, updates profile fields, and
inserts `support_inquiries` through Supabase REST with the service-role key.
`GET /api/migration/status` exposes only redacted readiness state and the
Supabase origin, never the credential.

Smoke-test the returned `workers.dev` URL before pointing the frontend at it:

```bash theme={null}
curl -fsS https://<backend-worker-origin>/healthz
curl -fsS https://<backend-worker-origin>/readyz
curl -fsS \
  -H "Authorization: Bearer ${BACKEND_INTERNAL_TOKEN:?set BACKEND_INTERNAL_TOKEN}" \
  https://<backend-worker-origin>/api/migration/status
```

Then configure the TanStack Worker. `apps/tanstack-web/wrangler.jsonc`
declares a `BACKEND` service binding to `tuturuuu-backend`, so the backend
Worker must be deployed first. Store only the browser-safe public backend
origin and the shared internal token as Cloudflare secrets for preview runs:

```bash theme={null}
bun wrangler secret put BACKEND_PUBLIC_ORIGIN --config apps/tanstack-web/wrangler.jsonc
bun wrangler secret put BACKEND_INTERNAL_TOKEN --config apps/tanstack-web/wrangler.jsonc
```

For gradual/canary secret rotation after the first preview deploy, use the
versions command family instead:

```bash theme={null}
bun wrangler versions secret put BACKEND_INTERNAL_TOKEN --config apps/backend/wrangler.jsonc
bun wrangler versions secret put TUTURUUU_APP_COORDINATION_SECRET --config apps/backend/wrangler.jsonc
bun wrangler versions secret put SUPABASE_URL --config apps/backend/wrangler.jsonc
bun wrangler versions secret put SUPABASE_SERVICE_ROLE_KEY --config apps/backend/wrangler.jsonc
bun wrangler versions secret put CRON_SECRET --config apps/backend/wrangler.jsonc
bun wrangler versions secret put DISCORD_APP_DEPLOYMENT_URL --config apps/backend/wrangler.jsonc
bun wrangler versions secret put AURORA_EXTERNAL_URL --config apps/backend/wrangler.jsonc
bun wrangler versions secret put AURORA_EXTERNAL_WSID --config apps/backend/wrangler.jsonc
bun wrangler versions deploy --config apps/backend/wrangler.jsonc

bun wrangler versions secret put BACKEND_PUBLIC_ORIGIN --config apps/tanstack-web/wrangler.jsonc
bun wrangler versions secret put BACKEND_INTERNAL_TOKEN --config apps/tanstack-web/wrangler.jsonc
bun wrangler versions deploy --config apps/tanstack-web/wrangler.jsonc
```

`BACKEND_PUBLIC_ORIGIN` should initially be the backend Worker origin, for
example the `https://<backend-worker>.<subdomain>.workers.dev` URL returned by
the backend deploy. It remains the browser-safe origin used for public probes
and non-protected traffic. Start server functions prefer the `BACKEND` service
binding for Worker-to-Worker backend calls and fall back to
`BACKEND_INTERNAL_URL` only outside Cloudflare or when the binding is absent.
Use `BACKEND_INTERNAL_URL` in local Docker, local Node preview, or emergency
HTTP fallback runs; do not make it a required TanStack Worker secret while the
service binding is declared. The TanStack Worker still needs the same
`BACKEND_INTERNAL_TOKEN` value so Start server functions can call protected Rust
migration inventory endpoints. Local `wrangler dev` can omit origin bindings
because `packages/internal-api` falls back to `http://localhost:7820`; local
migration dashboard calls will fall back to the checked manifest when the
backend token is not configured.

Deploy the TanStack Start Worker after the backend origin secrets are present:

```bash theme={null}
bun --cwd apps/tanstack-web run cf-typegen
bun --cwd apps/tanstack-web run deploy:cloudflare
```

For a local Worker-shape smoke before deployment, use Wrangler preview servers
in separate terminals and then point the smoke command at those origins:

```bash theme={null}
bun wrangler dev --config apps/backend/wrangler.jsonc
bun --cwd apps/tanstack-web run preview:cloudflare
```

The checked Wrangler configs reserve distinct local preview ports so both
Workers can run at the same time: `http://localhost:8780` for the Rust backend
and `http://localhost:8784` for TanStack Start. Keep those ports stable because
`bun check:cloudflare` validates them and the smoke examples below assume them.

Set the same env variable names that the deployed Workers use. Keep values in
the shell, local ignored env files, or Wrangler secret storage only:
`BACKEND_INTERNAL_TOKEN` and `BACKEND_PUBLIC_ORIGIN`. When the TanStack local
Worker cannot use the `BACKEND` service binding, set `BACKEND_INTERNAL_URL` to
the local backend Wrangler origin as an HTTP fallback.

Then run the preview smoke command against the returned Worker origins:

```bash theme={null}
BACKEND_INTERNAL_TOKEN="${BACKEND_INTERNAL_TOKEN:?set BACKEND_INTERNAL_TOKEN}" \
BACKEND_WORKER_ORIGIN=http://localhost:8780 \
TANSTACK_WEB_WORKER_ORIGIN=http://localhost:8784 \
bun smoke:cloudflare \
  --output tmp/benchmarks/web-migration/<timestamp>/cloudflare-smoke.json
```

For deployed previews, replace those local origins with the `workers.dev` or
custom preview origins returned by Wrangler. Set `BACKEND_INTERNAL_TOKEN` in the
shell before running the smoke command. The smoke command probes `/healthz`,
`/readyz`, authenticated `/api/migration/status`, missing/invalid-token
rejection for the protected migration status endpoint, and the TanStack root
shell. It fails on unexpected `4xx` and `5xx` responses, requires the TanStack
root shell to show `Backend reachable`, and redacts the bearer token from
output. That final check proves the deployed Start server function can reach
the Rust Worker through the service binding or configured HTTP fallback and
token, not just that the static shell rendered. Use `--output` to persist the
smoke report under
ignored `tmp/benchmarks/web-migration/<timestamp>/cloudflare-smoke.json` when
the run is part of a cutover rehearsal.
For deployed E2E smoke runs, set `TANSTACK_EXPECT_BACKEND_REACHABLE=1` and
`TANSTACK_EXPECT_BACKEND_TARGET=cloudflare-workers` so the migration shell must
prove the frontend can reach the Rust Worker.

For a non-terminal Cloudflare preview gate, attach that smoke report while
explicitly allowing the still-legacy route inventory:

```bash theme={null}
bun migration:tanstack:gates -- \
  --allow-legacy \
  --skip-benchmark \
  --skip-e2e \
  --cloudflare-smoke-report tmp/benchmarks/web-migration/<timestamp>/cloudflare-smoke.json
```

This command is only preview evidence. It proves the current Workers can talk
to each other, but it does not satisfy the final route parity, Docker E2E, or
benchmark cutover gates.

This is still a preview/canary path. Keep `apps/web` as the production source of
truth until the manifest, Docker E2E, benchmark, and cutover gates below pass.
Do not map production hostnames to the preview Worker while `workers_dev`
canary traffic and route parity are still in progress.

Rollback is currently DNS/routing only: remove or roll back any Cloudflare route
or custom-domain mapping that sends traffic to the preview Worker, and leave the
Docker blue/green `apps/web` production stack serving the canonical host. Do
not delete Wrangler secrets during rollback unless the secret itself is
compromised; keeping them bound makes redeploying the previous Worker version or
re-running smoke checks deterministic. Inspect and roll back preview Worker
deployments with Wrangler:

```bash theme={null}
bun wrangler deployments list --config apps/backend/wrangler.jsonc
bun wrangler deployments status --config apps/backend/wrangler.jsonc
bun wrangler rollback <VERSION_ID> --config apps/backend/wrangler.jsonc

bun wrangler deployments list --config apps/tanstack-web/wrangler.jsonc
bun wrangler deployments status --config apps/tanstack-web/wrangler.jsonc
bun wrangler rollback <VERSION_ID> --config apps/tanstack-web/wrangler.jsonc
```

Worker rollback does not revert external resources, bindings, routes, custom
domains, or secret values. If a preview deploy regresses, roll back the Worker
version or remove the preview route, then run `bun smoke:cloudflare` against the
remaining preview origins before resuming canary traffic.

Protected TanStack-to-backend traffic now has a Cloudflare service binding from
the TanStack Worker to the backend Worker: binding name `BACKEND`, service
`tuturuuu-backend`. The shared backend client prefers that binding in
server-only TanStack code and keeps `BACKEND_INTERNAL_URL` as a non-Cloudflare
HTTP fallback. Protected workspace and admin APIs still must not move to
production Worker traffic until each route has backend tests, OpenAPI coverage,
an internal-api facade, and migration gate evidence. Browser code must never
receive service tokens, and server-owned protected data must stay behind
server-owned calls.

Current Cloudflare limitations:

* Runtime service binding smoke is pending. The config and internal client use
  the `BACKEND` binding, but deployed smoke still needs to prove the binding
  path in Cloudflare preview before production host routing.
* Production host routing is pending full route manifest completion, Docker
  compare-mode E2E evidence, benchmark evidence, and
  `bun migration:tanstack:gates`.
* Preview Workers should not become the owner for private workspace/admin APIs
  until each route has backend tests, OpenAPI coverage, an internal-api facade,
  and migration gate evidence.

## Route Ownership Manifest

The current migration manifest is checked in at
`apps/tanstack-web/migration/route-manifest.json`. It records the current
`apps/web/src/app` route inventory, intended target owner for each route, and a
progress summary grouped by target owner and route kind. API and route-handler
entries also include a `methods` array derived from exported Next route methods;
`summary.methodCounts` tracks total exported `GET`, `POST`, `PUT`, `PATCH`,
`DELETE`, `HEAD`, and `OPTIONS` handlers. When only some methods on a legacy
`route.ts` are migrated, `route-overrides.json` can split that file into
method-level artifacts with `parentId` and `method`; the unmigrated paired
methods stay visible as `legacy-next`.

### Rust GET-handler migration wave

The backend port proceeds GET-first: a route's read path moves to a Rust handler
in `apps/backend/src/<module>.rs` while its mutation methods stay on the live
Next.js route. The Rust handler matches the legacy mount path exactly and returns
`None` (never `405`) for every method it does not own, so the worker falls through
to Next.js for `POST`/`PUT`/`PATCH`/`DELETE`. Because the route is still the source
of truth for writes, it correctly stays `legacy-next` in the manifest until the
remaining methods are ported and a cutover decision is recorded — GET-only ports
do not flip ownership status, so they add no manifest debt.

As of this wave the curated non-special fresh-GET surface is migrated: \~235 GET
routes now have Rust handlers. The only deliberately-skipped GET routes are
`/api/v1/workspaces/:wsId/mind/boards/:boardId` and
`/api/v1/workspaces/:wsId/whiteboards/:boardId`, whose CRDT/Yjs binary state lives
in a store the worker cannot reach; they stay on Next.js. Still pending as
separate phases: mutation methods for the GET-migrated routes, and special-auth
GET routes (`/api/cron/*` `CRON_SECRET`, `/api/trpc`, `/:locale` pages, OAuth
callbacks, and Hive routes backed by `HIVE_DATABASE_URL`).

Each batch is verified with `bun check:backend` (mirrors the CI Rust gate: `cargo
fmt --check`, `cargo clippy --locked --all-targets --features native -- -D
warnings`, `cargo test --locked`, and the `wasm32-unknown-unknown` worker check)
plus a runtime dual coverage probe that asserts every migrated `GET` is served by
the dispatcher (COVER) and every un-ported method still falls through (FRESH).

### Worker-incompatible routes (native-backend or Next.js only)

Some legacy routes cannot run on the **Cloudflare Worker** build of
`apps/backend` because the wasm sandbox has no arbitrary sockets, no filesystem,
and no Redis/Postgres drivers. They split into three buckets:

* **Native-backend portable (deferred, needs secrets wired):** the scheduler
  `/api/cron/*` jobs that just "call an external API + write Supabase" —
  `finance/exchange-rates`, `inventory/polar-product-sync`, `payment/{orders,products,subscriptions}`,
  `ai/sync-models`, `tasks/generate-embeddings`, `calendar/{provider-sync,smart-schedule}`,
  `process-{post-email-queue,topic-announcement-queue,notification-batches}`, and
  `hive/simulate`. These ARE portable to the **native Rust container** target
  (`--features native`, which can do outbound HTTP and reach external DBs) once
  each job's provider secret/connection is added to `BackendConfig` +
  `wrangler.jsonc` secrets. They are not portable to the wasm Worker build. Until
  the secrets are wired they stay on Next.js (`Bearer CRON_SECRET`).
* **Host/infra-coupled (stay where the runner lives):** the cron-runner
  *monitoring* surface — `monitoring/cron/{control,run,runner-recovery,executions}`,
  plus `cron/infrastructure/{docker-recovery-alerts,sample-resources}` — reads a
  filesystem archive / controls the deployment host (Docker control), and
  `cron/infrastructure/sync-trust-cache` needs Redis. These belong with whatever
  orchestrates the runner, not a stateless handler.
* **Transport that can't be a single handler:** `/api/trpc/[trpc]` is a catch-all
  that dispatches the entire tRPC procedure router (`appRouter`). The transport
  stays on Next.js; its data access migrates incrementally as individual
  procedures move behind `packages/internal-api` / the Rust backend.

Record the chosen disposition for each in
`apps/tanstack-web/migration/route-overrides.json` with an evidence note rather
than leaving them as untriaged `legacy-next` backlog.

Current inventory:

* `151` pages
* `58` layouts
* `592` route handler artifacts
* `8` cron handlers
* `805` total tracked route artifacts
* `215` migrated artifacts, `228` terminal artifacts, and `577` remaining
  legacy-owned artifacts in the checked manifest

Regenerate it after adding or removing legacy routes:

```bash theme={null}
bun migration:tanstack:manifest
```

Regenerate the TanStack Router route tree after adding or removing
`apps/tanstack-web/src/routes/**` files:

```bash theme={null}
bun migration:tanstack:routes
```

This command preserves the TanStack Start `Register` augmentation footer that
`bun check:cloudflare` validates for the Cloudflare-compatible Start runtime,
then formats the generated `routeTree.gen.ts` with the generator's isolated
Biome config so repeated route-tree generation does not leave persistent dirty
output. The Rust/TanStack Cloudflare workflow runs
`scripts/generate-tanstack-route-tree.test.js` whenever the generator changes.

Route ownership status is preserved through
`apps/tanstack-web/migration/route-overrides.json`. Add an override with a
non-empty evidence note when a route becomes `migrated` or receives an accepted
removal decision; do not edit the generated manifest by hand.

Check that the manifest still matches the legacy route tree while migration is
in progress:

```bash theme={null}
bun migration:tanstack:check
```

Cutover mode is intentionally stricter. It fails while any route remains marked
as `legacy-next`:

```bash theme={null}
bun migration:tanstack:cutover-check
```

The full cutover gate also requires explicit Docker E2E, benchmark, and
Cloudflare smoke evidence:

```bash theme={null}
bun migration:tanstack:gates -- \
  --e2e-report tmp/e2e/web-migration/compare-report.json \
  --benchmark-report tmp/benchmarks/web-migration/<timestamp>/report.json \
  --cloudflare-smoke-report tmp/benchmarks/web-migration/<timestamp>/cloudflare-smoke.json \
  --output tmp/benchmarks/web-migration/<timestamp>/cutover-gates.json
```

This command validates route parity, terminal migration statuses, backend-owned
route mapping, compare-mode Docker E2E evidence, and a full compare benchmark
report without committing generated artifacts. The output JSON is the
review/handoff artifact for cutover sign-off and stays under ignored `tmp/`
paths with the source reports. The benchmark report must be created with
`--setup compare --profile full` and include every required metric comparison;
smoke reports alone are useful for previews but are not sufficient cutover
evidence. The Cloudflare smoke report must come from
`bun smoke:cloudflare` against distinct live Rust backend and TanStack Worker
origins, and the cutover gate verifies that each required probe URL matches
that provenance.

The manifest also includes `progress.byOwner`, `progress.byKind`, and
`progress.topLegacyRoutes`. Use those fields when splitting the remaining port
work across frontend and backend owners. Use each route's `methods` list when
checking API parity so a `GET` port does not accidentally hide an unmigrated
`POST`, `OPTIONS`, or mutation handler on the same route artifact. The Rust
backend exposes the same derived progress at:

```text theme={null}
GET /api/migration/progress
```

`apps/tanstack-web` reads that endpoint through `packages/internal-api` and
falls back to the checked manifest when the backend is offline.

Method-level migration ownership is only valid when the deployment path can
route traffic by HTTP method or otherwise avoid sending still-legacy methods to
Rust. For example, the Rust backend can own `OPTIONS` preflight responses for an
auth route while the corresponding `POST` or `GET` artifact remains
`legacy-next`; a path-only proxy must keep that whole path on Next until the
auth method is migrated too.

First migrated ownership:

| Legacy route                                                                                                                                                                                                               | New owner                            | Evidence                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `GET /.well-known/*` / `HEAD /.well-known/*`                                                                                                                                                                               | `apps/backend` Rust route dispatcher | `route-overrides.json` marks the route handler `migrated`; Rust returns a cacheable empty `404` with `Cache-Control: public, max-age=300, must-revalidate`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `GET /~recover-browser-state` / `POST /~recover-browser-state`                                                                                                                                                             | `apps/backend` Rust route dispatcher | `route-overrides.json` marks the route handler `migrated`; Rust returns the no-store reset HTML, enforces same-origin POST confirmation, emits `Clear-Site-Data`, clears Supabase auth cookies, and redirects to `/login?browserStateReset=1`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `GET /serwist/:path`                                                                                                                                                                                                       | `apps/backend` Rust route dispatcher | `route-overrides.json` marks the route handler `migrated`; Rust serves a no-store decommissioning worker at `/serwist/sw.js` that unregisters stale Next/Serwist service workers during Cloudflare cutover and returns deterministic source-map metadata at `/serwist/sw.js.map`. This is cutover ownership, not offline-cache feature parity.                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `GET /api/health`                                                                                                                                                                                                          | `apps/backend` Rust route dispatcher | `route-overrides.json` marks the route `migrated`; `GET /api/health` returns the legacy ok status JSON with `Cache-Control: no-store` and JSON security headers.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `GET /api/time-tracking/export`                                                                                                                                                                                            | `apps/backend` Rust route dispatcher | `route-overrides.json` marks the route `migrated`; Rust revalidates the browser Supabase session or non-app-session Bearer token, requires a `@tuturuuu.com` root user and the root workspace, verifies workspace membership, preserves legacy query parsing and the 1000-row limit cap, forwards `get_grouped_sessions_paginated` through the caller Supabase token, and returns the legacy data/pagination envelope with an empty-result fallback when RPC and JS-style recovery cannot produce rows.                                                                                                                                                                                                                                                          |
| `GET /api/auth/me`                                                                                                                                                                                                         | `apps/backend` Rust route dispatcher | `route-overrides.json` marks the route `migrated`; Rust revalidates the Supabase browser session cookie or non-app-session Bearer token with Supabase Auth, returns the raw legacy user payload, keeps no-store headers, and preserves the legacy Unauthorized message response for missing or invalid sessions.                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `GET /api/auth/mfa/totp/assurance-level`                                                                                                                                                                                   | `apps/backend` Rust route dispatcher | `route-overrides.json` marks the route `migrated`; Rust revalidates the Supabase browser session cookie or non-app-session Bearer token with Supabase Auth, derives `currentLevel` from the JWT `aal` claim, derives `nextLevel` from verified Supabase Auth factors on the revalidated user JSON, returns `currentAuthenticationMethods` from the JWT `amr` claim, and keeps the legacy no-store/error response shape.                                                                                                                                                                                                                                                                                                                                          |
| `GET` / `POST` `/api/auth/mfa/totp/factors`                                                                                                                                                                                | `apps/backend` Rust route dispatcher | `route-overrides.json` marks the route `migrated`; Rust revalidates the Supabase browser session cookie or non-app-session Bearer token with Supabase Auth, mirrors Auth JS `listFactors()` from the revalidated user JSON, enrolls TOTP factors through Supabase Auth REST, normalizes TOTP QR codes, and preserves the legacy no-store/error response shape.                                                                                                                                                                                                                                                                                                                                                                                                   |
| `GET` / `DELETE` `/api/auth/mfa/totp/factors/:factorId`                                                                                                                                                                    | `apps/backend` Rust route dispatcher | `route-overrides.json` marks the route `migrated`; Rust revalidates the Supabase browser session cookie or non-app-session Bearer token with Supabase Auth, resolves factor detail from the verified TOTP subset returned by Auth JS-compatible `listFactors()`, unenrolls factors through Supabase Auth REST, and preserves the legacy `Factor not found` and success-wrapper responses.                                                                                                                                                                                                                                                                                                                                                                        |
| `GET /api/:wsId/crawlers/domains`                                                                                                                                                                                          | `apps/backend` Rust route dispatcher | `route-overrides.json` marks the route `migrated`; Rust preserves the legacy no-auth, workspace-agnostic behavior, reads `crawled_urls` and non-skipped `crawled_url_next_urls` through the server-owned Supabase REST adapter, extracts valid URL hostnames, deduplicates them, and returns the sorted domain list with `cached: false`.                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `GET /api/:wsId/crawlers/list`                                                                                                                                                                                             | `apps/backend` Rust route dispatcher | `route-overrides.json` marks the route `migrated`; Rust revalidates the browser Supabase session, requires a `@tuturuuu.com` user email before server-owned admin reads, preserves the legacy raw `crawled_urls` row payload, domain/search filters, `created_at.desc` ordering, exact-count pagination, and data/count response shape. Unauthorized callers now receive an explicit `401` instead of the legacy catch-all `500`.                                                                                                                                                                                                                                                                                                                                |
| `GET /api/:wsId/crawlers/uncrawled`                                                                                                                                                                                        | `apps/backend` Rust route dispatcher | `route-overrides.json` marks the route `migrated`; Rust preserves the legacy no-auth, workspace-agnostic behavior, reads non-skipped `crawled_url_next_urls`, applies legacy URL filters and pagination, removes URLs already present in `crawled_urls`, groups the remaining rows by `origin_id`, and returns the legacy `uncrawledUrls`, `groupedUrls`, and `pagination` payload.                                                                                                                                                                                                                                                                                                                                                                              |
| `GET /api/v1/workspaces/:wsId/crawlers/status`                                                                                                                                                                             | `apps/backend` Rust route dispatcher | `route-overrides.json` marks the route `migrated`; Rust preserves the legacy workspace-agnostic URL status lookup, validates the required `url` query parameter, reads the exact `crawled_urls.url` row through the server-owned Supabase REST adapter, and returns raw `crawledUrl` plus raw `crawled_url_next_urls` rows ordered by `created_at.desc`; missing crawled URLs still return `crawledUrl: null` and `relatedUrls: []`.                                                                                                                                                                                                                                                                                                                             |
| `GET /api/v1/calendar/mock`                                                                                                                                                                                                | `apps/backend` Rust route dispatcher | `route-overrides.json` marks the route `migrated`; Rust returns the deterministic legacy mock calendar event payload with JSON security headers.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `GET /api/v1/devboxes/cache` and `POST /api/v1/devboxes/cache/prune`                                                                                                                                                       | `apps/backend` Rust route dispatcher | `route-overrides.json` marks both devbox cache routes `migrated`; Rust accepts CLI app-session Bearer tokens for the platform target with `cli:access` or browser/non-app-session Supabase credentials, requires root workspace `MEMBER` access, preserves the legacy empty caches list body, and returns the legacy prune acknowledgement without private devbox table mutations. Other devbox mutation routes remain legacy-owned.                                                                                                                                                                                                                                                                                                                             |
| `GET /api/admin/tasks/embeddings/stats`                                                                                                                                                                                    | `apps/backend` Rust route dispatcher | `route-overrides.json` marks the admin statistics route `migrated`; Rust validates the browser Supabase auth cookie with Supabase Auth, requires a `tuturuuu.com` or `xwf.tuturuuu.com` user email, reads exact system-wide task counts through the server-owned Supabase REST adapter, and returns only the derived legacy embedding coverage payload. The SSE embedding generation route remains legacy-owned.                                                                                                                                                                                                                                                                                                                                                 |
| `GET /api/v1/ai/whitelist/me`                                                                                                                                                                                              | `apps/backend` Rust route dispatcher | `route-overrides.json` marks the route `migrated`; Rust preserves the legacy app-session-first auth behavior for satellite app-session targets, falls back to browser Supabase auth cookies only when no app-session token is present, reads only the `enabled` flag for the authenticated email from `private.ai_whitelisted_emails`, and returns the derived legacy email/enabled payload.                                                                                                                                                                                                                                                                                                                                                                     |
| `GET` / `POST` `/api/v1/infrastructure/ai/whitelist/domains` and `/emails`; `PUT` / `DELETE` `/api/v1/infrastructure/ai/whitelist/:email` / `/domain/:domain`                                                              | `apps/backend` Rust route dispatcher | `route-overrides.json` marks the list/create collection methods plus detail `PUT` and `DELETE` method artifacts `migrated`; Rust revalidates the normal Supabase browser session or non-app-session Bearer token, requires a `@tuturuuu.com` operator email, reads, inserts, patches, and deletes private whitelist rows through the service-role private-schema REST adapter, preserves list pagination and create validation/defaults, applies legacy `Boolean(enabled)` truthiness for detail updates, and keeps the legacy success, validation, 403, JSON failure, and plain-text failure bodies.                                                                                                                                                            |
| `GET /api/v1/users/me/hive-access`                                                                                                                                                                                         | `apps/backend` Rust route dispatcher | `route-overrides.json` marks the route `migrated`; Rust preserves the legacy app-session-first auth behavior for current-user app-session targets, falls back to browser Supabase auth cookies only when no app-session token is present, reads only `hive_members.enabled` and `platform_user_roles.enabled`/`allow_role_management` for the authenticated user through the server-owned Supabase REST adapter, returns the derived legacy access/admin/member payload, and keeps the legacy private cache directive on successful responses.                                                                                                                                                                                                                   |
| `GET /api/v1/cms/workspaces`                                                                                                                                                                                               | `apps/backend` Rust route dispatcher | `route-overrides.json` marks the route `migrated`; Rust preserves app-session and browser Supabase auth, loads the caller's admin-visible workspaces through service-role Supabase REST, applies root-admin and per-workspace external-project permission checks, resolves active external-project bindings, and returns the raw legacy workspace array with subscription tier metadata.                                                                                                                                                                                                                                                                                                                                                                         |
| `GET /api/v1/notifications/unread-count`                                                                                                                                                                                   | `apps/backend` Rust route dispatcher | `route-overrides.json` marks the route `migrated`; Rust preserves app-session and browser Supabase auth, validates the optional `wsId` query filter, verifies workspace membership before scoped counts, builds the legacy notification access filter, reads the exact unread count through the service-role Supabase REST adapter, and returns no-store JSON responses.                                                                                                                                                                                                                                                                                                                                                                                         |
| `GET /api/v1/mira/achievements`                                                                                                                                                                                            | `apps/backend` Rust route dispatcher | `route-overrides.json` marks the route `migrated`; Rust revalidates the browser Supabase session or non-app-session Bearer token, reads the private Mira achievement catalog through the service-role private-schema Supabase REST adapter, reads the caller's unlocked achievements through the caller-token Supabase REST adapter, and preserves the legacy unlocked-status merge, grouping, XP/stat calculation, and empty-unlocked fallback when the user-achievement read fails.                                                                                                                                                                                                                                                                            |
| `GET /api/v1/storage/list`                                                                                                                                                                                                 | `apps/backend` Rust route dispatcher | `route-overrides.json` marks the route `migrated`; Rust validates legacy `ttr_` workspace API keys, resolves role/default workspace permissions, requires `manage_drive` or `admin`, preserves query coercion and storage path sanitization, blocks mobile-deployment vault paths, lists Supabase Storage through the server-owned storage REST adapter, filters placeholder/reserved entries, recursively counts matching files, and returns the legacy data/pagination and error envelopes.                                                                                                                                                                                                                                                                    |
| `GET /api/v1/hive/ai/models`                                                                                                                                                                                               | `apps/backend` Rust route dispatcher | `route-overrides.json` marks the route `migrated`; Rust preserves Hive-only app-session auth and browser Supabase cookie fallback, requires Hive member or admin access before private reads, reads only UI-safe model columns from `private.ai_gateway_models` through the server-owned private-schema REST adapter, preserves the legacy `enabled`/`type` filters and provider/name ordering, and returns the derived models UI payload.                                                                                                                                                                                                                                                                                                                       |
| `GET /api/v1/nova/me/team`                                                                                                                                                                                                 | `apps/backend` Rust route dispatcher | `route-overrides.json` marks the route `migrated`; Rust preserves Nova-only app-session auth and browser Supabase cookie fallback, reads only `team_id` for the authenticated user from `private.nova_team_members` through the server-owned private-schema REST adapter, and returns the derived legacy team ID payload.                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `GET /api/v1/task-board-status-templates`                                                                                                                                                                                  | `apps/backend` Rust route dispatcher | `route-overrides.json` marks the route `migrated`; Rust preserves authenticated Supabase browser-cookie and non-app-session Bearer access, rejects Tuturuuu app-session tokens without falling back to stale cookies, reads the global `task_board_status_templates` catalog through the server-owned Supabase REST adapter, preserves legacy `is_default.desc,name.asc` ordering, and returns the raw legacy templates payload.                                                                                                                                                                                                                                                                                                                                 |
| `GET` / `PUT` `/api/v1/infrastructure/mobile-versions`                                                                                                                                                                     | `apps/backend` Rust route dispatcher | `route-overrides.json` marks both method artifacts `migrated`; Rust revalidates the normal Supabase browser session or non-app-session Bearer token, requires root workspace `manage_workspace_roles` through the server-owned `has_workspace_permission` RPC, reads the fixed root workspace mobile policy config IDs for snapshots, validates and normalizes write payloads, upserts all nine root workspace policy config rows through the server-owned Supabase REST adapter, and preserves the legacy admin policy snapshot plus success/error write bodies.                                                                                                                                                                                                |
| `GET` / `POST` `/api/v1/infrastructure/timezones` and `PUT` / `DELETE` `/api/v1/infrastructure/timezones/:timezoneId`                                                                                                      | `apps/backend` Rust route dispatcher | `route-overrides.json` marks the collection `GET`/`POST` and detail `PUT`/`DELETE` artifacts `migrated`; Rust revalidates the normal Supabase browser session or non-app-session Bearer token, requires root workspace `manage_workspace_roles`, reads and writes `private.timezones` through the server-owned private-schema Supabase REST adapter, preserves `value.asc` ordering for reads, normalizes legacy create/update payloads, omits missing/null create IDs so the database UUID default is used, and preserves the legacy success and method-specific failure bodies.                                                                                                                                                                                |
| `GET /api/v1/infrastructure/user-status-changes`                                                                                                                                                                           | `apps/backend` Rust route dispatcher | `route-overrides.json` marks the route `migrated`; Rust requires a normal Supabase browser session or non-app-session Bearer token, forwards that caller token to Supabase REST so `workspace_user_status_changes` RLS remains active, preserves the legacy `ws_id` requirement, parseInt-style `limit`/`offset` range behavior, exact-count pagination, raw row list response, and legacy Supabase error body.                                                                                                                                                                                                                                                                                                                                                  |
| `GET /api/v1/infrastructure/users`                                                                                                                                                                                         | `apps/backend` Rust route dispatcher | `route-overrides.json` marks the route `migrated`; Rust uses the shared caller-token paginated export helper for `workspace_users`, preserving Supabase RLS, the legacy `ws_id` requirement, parseInt-style `limit`/`offset` range behavior, exact-count pagination, raw row list response, and legacy Supabase error body.                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `GET /api/v1/infrastructure/classes`, `/product-categories`, and `/score-names`                                                                                                                                            | `apps/backend` Rust route dispatcher | `route-overrides.json` marks these routes `migrated`; Rust uses the shared caller-token paginated export helper for `workspace_user_groups`, `product_categories`, and `user_group_metrics`, preserving Supabase RLS, the legacy `ws_id` requirement, parseInt-style `limit`/`offset` range behavior, exact-count pagination, raw row list responses, and legacy Supabase error bodies.                                                                                                                                                                                                                                                                                                                                                                          |
| `GET /api/v1/infrastructure/lessons` and `/packages`                                                                                                                                                                       | `apps/backend` Rust route dispatcher | `route-overrides.json` marks these routes `migrated`; Rust preserves the legacy no-auth service-role private-schema export for `lessons`, while `packages` revalidates a normal Supabase browser session or non-app-session Bearer token, normalizes the workspace, requires `view_inventory`, reads `workspace_products` through the service-role Supabase REST adapter, and preserves the legacy `ws_id`, parseInt-style `limit`/`offset`, exact-count pagination, data/count body, and error responses.                                                                                                                                                                                                                                                       |
| `GET /api/v1/infrastructure/bills`, `/roles`, and `/transaction-categories`                                                                                                                                                | `apps/backend` Rust route dispatcher | `route-overrides.json` marks these routes `migrated`; Rust uses the shared caller-token paginated export helper for `finance_invoices`, `workspace_user_groups`, and `transaction_categories`, preserving Supabase RLS, the legacy `ws_id` requirement, parseInt-style `limit`/`offset` range behavior, exact-count pagination, raw row list responses, and legacy Supabase error bodies.                                                                                                                                                                                                                                                                                                                                                                        |
| `GET /api/v1/infrastructure/abuse-intelligence`                                                                                                                                                                            | `apps/backend` Rust route dispatcher | `route-overrides.json` marks only the `GET` method artifact `migrated`; Rust revalidates the normal Supabase browser session or non-app-session Bearer token, requires root workspace `view_infrastructure` through the shared workspace permission helper, reads reputation subjects, activity signals, and step-up challenges with caller-token Supabase REST, reads active trust overrides with the service-role Supabase adapter, and preserves the legacy `limit`/`signalLimit` parsing, summary, `topRiskySubjects` sorting, and auth/error bodies. POST remains legacy-owned.                                                                                                                                                                             |
| `GET /api/v1/infrastructure/abuse-events`                                                                                                                                                                                  | `apps/backend` Rust route dispatcher | `route-overrides.json` marks the route `migrated`; Rust revalidates the normal Supabase browser session or non-app-session Bearer token, preserves the root workspace membership gate through caller-token Supabase REST reads, queries `abuse_events` with the caller token, and preserves the legacy `ip`/`type`/`success` filters, `page`/`pageSize` parseInt-style range behavior, exact-count pagination, data/count/page/pageSize/totalPages body, and legacy auth/error responses.                                                                                                                                                                                                                                                                        |
| `GET /api/v1/infrastructure/blocked-ips`                                                                                                                                                                                   | `apps/backend` Rust route dispatcher | `route-overrides.json` marks only the `GET` method artifact `migrated`; Rust revalidates the normal Supabase browser session or non-app-session Bearer token, preserves the root workspace membership gate through caller-token Supabase REST reads, queries `blocked_ips` with the legacy `unblocked_by_user` embed, and preserves the legacy `status`/`ip` filters, `page`/`pageSize` parseInt-style range behavior, exact-count pagination, data/count/page/pageSize/totalPages body, and legacy auth/error responses. POST/DELETE remain legacy-owned.                                                                                                                                                                                                       |
| `GET /api/v1/infrastructure/suspensions`                                                                                                                                                                                   | `apps/backend` Rust route dispatcher | `route-overrides.json` marks only the `GET` method artifact `migrated`; Rust revalidates the normal Supabase browser session or non-app-session Bearer token, requires root workspace `manage_workspace_roles` through `has_workspace_permission` with the caller token, reads active `user_suspensions` rows through the service-role Supabase REST adapter ordered by `suspended_at.desc`, returns the legacy raw row array, and preserves the legacy `Unauthorized`, `Forbidden`, and `Failed to fetch suspensions` error bodies. POST and detail DELETE remain legacy-owned.                                                                                                                                                                                 |
| `GET` / `POST` `/api/v1/infrastructure/email-blacklist` and `GET` / `PUT` / `DELETE` `/api/v1/infrastructure/email-blacklist/:entryId`                                                                                     | `apps/backend` Rust route dispatcher | `route-overrides.json` marks all email blacklist collection and detail method artifacts `migrated`; Rust revalidates the normal Supabase browser session or non-app-session Bearer token, preserves root workspace membership gates and the detail GET non-root `401` quirk, reads, inserts, updates, and deletes through caller-token Supabase REST so RLS remains active, preserves Zod-style write validation bodies, maps duplicate creates to `409`, maps detail misses to the legacy `404` bodies, and preserves update/delete prefetch behavior.                                                                                                                                                                                                          |
| `GET /api/v1/infrastructure/bill-coupons`, `/bill-packages`, `/class-attendance`, `/class-members`, `/class-packages`, `/class-scores`, `/package-stock-changes`, and `/student-feedbacks`                                 | `apps/backend` Rust route dispatcher | `route-overrides.json` marks these routes `migrated`; Rust extends the shared caller-token paginated export helper with route-specific embedded select strings and related-table workspace filters, preserving Supabase RLS, the legacy `ws_id` requirement, parseInt-style `limit`/`offset` range behavior, exact-count pagination, raw row list responses, and legacy Supabase error bodies.                                                                                                                                                                                                                                                                                                                                                                   |
| `GET /api/v1/infrastructure/coupons`, `/user-coupons`, `/user-monthly-reports`, and `/user-monthly-report-logs`                                                                                                            | `apps/backend` Rust route dispatcher | `route-overrides.json` marks these routes `migrated`; Rust revalidates the normal Supabase browser session or non-app-session Bearer token, normalizes the requested workspace, requires `manage_external_migrations` through the shared workspace permission resolver, reads `private.workspace_promotions`, `private.user_linked_promotions`, and the private monthly report views through the server-owned Supabase REST adapter with private-schema headers, preserves the user-coupons empty-promotion short-circuit and `workspace_promotions` relation object reconstruction, and preserves the legacy `ws_id` requirement, parseInt-style `limit`/`offset` range behavior, exact-count pagination, raw row list responses, and legacy auth/error bodies. |
| `GET /api/v1/infrastructure/payment-methods`, `/wallets`, and `/wallet-transactions`                                                                                                                                       | `apps/backend` Rust route dispatcher | `route-overrides.json` marks these routes `migrated`; Rust revalidates the normal Supabase browser session or non-app-session Bearer token, normalizes the requested workspace and requires `view_transactions` for wallet/payment method reads, reads `private.workspace_wallets` through the server-owned Supabase REST adapter with private-schema headers, forwards wallet transaction reads to `get_wallet_transactions_with_permissions` with the caller token, and preserves the legacy `ws_id` requirement, parseInt-style `limit`/`offset` behavior, pagination/count envelopes, raw row list responses, and legacy auth/error bodies.                                                                                                                  |
| `GET /api/v1/workspaces/limits`                                                                                                                                                                                            | `apps/backend` Rust route dispatcher | `route-overrides.json` marks the route `migrated`; Rust validates the browser Supabase auth cookie with Supabase Auth, treats `tuturuuu.com` and `xwf.tuturuuu.com` user emails as unlimited, otherwise reads only the exact count of non-deleted workspaces created by the authenticated user through the server-owned Supabase REST adapter, and returns the legacy `canCreate`, `currentCount`, `limit`, and `remaining` payload.                                                                                                                                                                                                                                                                                                                             |
| `GET /api/v1/workspaces/:wsId/posts/permissions`                                                                                                                                                                           | `apps/backend` Rust route dispatcher | `route-overrides.json` marks the route `migrated`; Rust revalidates a normal Supabase session when present, calls the server-owned `has_workspace_permission` RPC for workspace `approve_posts` and root workspace `manage_workspace_roles`, and preserves the legacy quiet-failure behavior where missing auth, inaccessible workspaces, RPC failures, and missing permissions all return `200` with both permission flags `false`.                                                                                                                                                                                                                                                                                                                             |
| `GET /api/v1/workspaces/:wsId/Mention`                                                                                                                                                                                     | `apps/backend` Rust route dispatcher | `route-overrides.json` marks the route `migrated`; Rust preserves the legacy path casing, revalidates a normal Supabase browser session or non-app-session Bearer token, rejects app-session tokens, requires exact `MEMBER` workspace membership, reads `workspace_users.email` with the caller token, and preserves the legacy email response, Unauthorized, Forbidden, membership lookup failure, and Supabase error bodies.                                                                                                                                                                                                                                                                                                                                  |
| `GET /api/v1/workspaces/:wsId/habits/access`                                                                                                                                                                               | `apps/backend` Rust route dispatcher | `route-overrides.json` marks the route `migrated`; Rust revalidates a normal Supabase browser session or non-app-session Bearer token, rejects app-session tokens, resolves `internal`, `personal`, UUID, and handle workspace identifiers, requires exact `MEMBER` membership through the service-role `workspace_members` read, reads `ENABLE_HABITS` from `workspace_secrets` with exact `value === "true"` matching, and returns the legacy enabled access payload.                                                                                                                                                                                                                                                                                          |
| `GET /api/v1/workspaces/:wsId/mobile/module-flags`                                                                                                                                                                         | `apps/backend` Rust route dispatcher | `route-overrides.json` marks the route `migrated`; Rust revalidates a normal Supabase browser session or non-app-session Bearer token, rejects app-session tokens, resolves the legacy `internal` workspace slug, requires workspace membership through a caller-token `workspace_members` read, reads `MOBILE_HIDE_EXPERIMENTAL_MODULES` and `MOBILE_HIDDEN_MODULES` from `workspace_secrets` through the server-owned Supabase REST adapter, preserves JSON-array and comma-separated hidden-module parsing, and returns sorted `hiddenModuleIds` with the legacy private cache directive.                                                                                                                                                                     |
| `GET /api/v1/workspaces/:wsId/education/access`                                                                                                                                                                            | `apps/backend` Rust route dispatcher | `route-overrides.json` marks the route `migrated`; Rust revalidates a normal Supabase browser session or non-app-session Bearer token, mirrors getPermissions-style workspace permission resolution for `ai_lab`, reads `ENABLE_EDUCATION` from `workspace_secrets` through the server-owned Supabase REST adapter, and preserves the legacy access-probe behavior where workspace, feature-flag, permission, and lookup failures return `200` with `enabled: false`.                                                                                                                                                                                                                                                                                            |
| `GET /api/v1/workspaces/:wsId/finance/budgets/status`                                                                                                                                                                      | `apps/backend` Rust route dispatcher | `route-overrides.json` marks the route `migrated`; Rust accepts finance/platform app-session tokens and CLI app-session tokens before falling back to a normal Supabase browser session or non-app-session Bearer token, normalizes internal, personal, handle, and UUID workspace identifiers, requires `manage_finance` through `has_workspace_permission`, calls `get_budget_status` with the service-role credential, returns the raw legacy RPC payload, and preserves the legacy Unauthorized, Insufficient permissions, and Error fetching budget status bodies.                                                                                                                                                                                          |
| `GET /api/workspaces/:wsId/finance/charts/balance`                                                                                                                                                                         | `apps/backend` Rust route dispatcher | `route-overrides.json` marks the route `migrated`; Rust accepts finance/platform app-session tokens and CLI app-session tokens before normal Supabase fallback, normalizes workspace identifiers, requires `view_finance_stats`, preserves the legacy required `date` query plus `includeConfidential` parsing, calls `get_wallet_balance_at_date`, and returns the legacy balance/date payload, Unauthorized, Forbidden, invalid-query, and balance lookup error bodies.                                                                                                                                                                                                                                                                                        |
| `GET /api/v1/workspaces/:wsId/finance/debts/summary`                                                                                                                                                                       | `apps/backend` Rust route dispatcher | `route-overrides.json` marks the route `migrated`; Rust accepts finance/platform app-session tokens and CLI app-session tokens before normal Supabase fallback, normalizes internal, personal, handle, and UUID workspace identifiers, requires `manage_finance`, calls private-schema `get_debt_loan_summary` with `_actor_id` and `_ws_id` using service-role auth, returns the first legacy RPC row or the zero summary, and preserves the legacy Unauthorized, Insufficient permissions, and Error fetching debt/loan summary bodies.                                                                                                                                                                                                                        |
| `GET /api/v1/workspaces/:wsId/finance/filter-users`                                                                                                                                                                        | `apps/backend` Rust route dispatcher | `route-overrides.json` marks the route `migrated`; Rust accepts finance/platform app-session tokens and CLI app-session tokens before normal Supabase fallback, normalizes workspace identifiers, requires `view_transactions`, preserves the legacy `type` branches, reads transaction and invoice creator filters through service-role Supabase REST with explicit `ws_id` filters, reads workspace users with the caller token for normal Supabase sessions and service-role auth for app sessions, and preserves the legacy users payload, Unauthorized, and branch-specific failure bodies.                                                                                                                                                                 |
| `GET /api/v1/workspaces/:wsId/finance/invoices/subscription/context`                                                                                                                                                       | `apps/backend` Rust route dispatcher | `route-overrides.json` marks the route `migrated`; Rust accepts finance/platform app-session tokens and CLI app-session tokens before normal Supabase fallback, normalizes workspace identifiers, requires `create_invoices`, preserves the legacy missing-query short-circuit, validates requested student groups inside the workspace, reads month-scoped attendance and completed invoice history through service-role Supabase REST, returns the legacy attendance and latest paid invoice context shape, and preserves the legacy Unauthorized and subscription-context error bodies.                                                                                                                                                                       |
| `GET /api/v1/workspaces/:wsId/finance/recurring-transactions/upcoming`                                                                                                                                                     | `apps/backend` Rust route dispatcher | `route-overrides.json` marks only the upcoming transactions route `migrated`; Rust accepts finance/platform app-session tokens and CLI app-session tokens before normal Supabase fallback, normalizes workspace identifiers, requires `view_transactions`, preserves JavaScript parseInt-style `daysAhead` parsing with a 30-day fallback, calls `get_upcoming_recurring_transactions` with caller-token auth for normal Supabase sessions and service-role auth for app sessions, and preserves the legacy upcomingTransactions payload, `403` Unauthorized, and fetch-failure bodies. Recurring transaction collection and detail routes remain legacy-owned.                                                                                                  |
| `GET /api/v1/workspaces/:wsId/settings/permissions`                                                                                                                                                                        | `apps/backend` Rust route dispatcher | `route-overrides.json` marks the route `migrated`; Rust revalidates a normal Supabase browser session or non-app-session Bearer token, rejects app-session tokens, resolves personal/workspace identifiers, mirrors `getPermissions` role/default/creator/admin behavior, and returns the legacy `manage_subscription`, `manage_workspace_settings`, and `manage_workspace_members` flags with the private 30-second success cache directive.                                                                                                                                                                                                                                                                                                                    |
| `GET /api/v1/workspaces/:wsId/settings/permissions/check`                                                                                                                                                                  | `apps/backend` Rust route dispatcher | `route-overrides.json` marks the route `migrated`; Rust revalidates a normal Supabase browser session or non-app-session Bearer token, ignores app-session tokens and the legacy `userId` query, resolves personal/workspace identifiers, requires workspace access, and mirrors `getPermissions` role/default/creator/admin behavior before returning the hasPermission payload.                                                                                                                                                                                                                                                                                                                                                                                |
| `GET /api/v1/workspaces/:wsId/course-modules` and `GET /api/v1/workspaces/:wsId/quiz-sets/:setId/linked-modules`                                                                                                           | `apps/backend` Rust route dispatcher | `route-overrides.json` marks both education read endpoints `migrated`; Rust revalidates a normal Supabase browser session or non-app-session Bearer token, resolves `ai_lab` workspace permission, requires the `ENABLE_EDUCATION` secret, reads course modules through service-role Supabase REST with exact-count page/pageSize/q behavior, and verifies linked quiz sets belong to the resolved workspace before listing linked modules.                                                                                                                                                                                                                                                                                                                      |
| `GET` / `PATCH` `/api/v1/user/onboarding-progress`                                                                                                                                                                         | `apps/backend` Rust route dispatcher | `route-overrides.json` marks the route `migrated`; Rust validates the browser Supabase session with Supabase Auth, reads or upserts only the authenticated user's `onboarding_progress` row through the server-owned Supabase REST adapter, preserves the legacy allowed-field filter, null missing-row response, invalid/empty update errors, and method handling.                                                                                                                                                                                                                                                                                                                                                                                              |
| `PATCH /api/v1/user/profile`                                                                                                                                                                                               | `apps/backend` Rust route dispatcher | `route-overrides.json` marks the route `migrated`; Rust validates the browser Supabase session with Supabase Auth, validates `display_name`, `bio`, and `avatar_url` with the legacy limits, ignores unknown fields, updates only the authenticated user's `users` row through the server-owned Supabase REST adapter, and preserves the legacy success/error response messages.                                                                                                                                                                                                                                                                                                                                                                                 |
| `GET` / `PATCH` `/api/v1/users/me/default-workspace`                                                                                                                                                                       | `apps/backend` Rust route dispatcher | `route-overrides.json` marks the route `migrated`; Rust accepts current-user app-session tokens or revalidated browser Supabase sessions for reads, preserves the legacy `null` fallback when workspace data cannot be resolved, falls back from an inaccessible saved default to the caller's personal workspace, and updates `user_private_details.default_workspace_id` only after validating the `workspaceId` field as a UUID or `null` and verifying workspace membership with the caller token.                                                                                                                                                                                                                                                           |
| `GET` / `PATCH` `/api/v1/users/calendar-settings`                                                                                                                                                                          | `apps/backend` Rust route dispatcher | `route-overrides.json` marks the route `migrated`; Rust accepts calendar app-session tokens or revalidated browser Supabase sessions, reads and updates the authenticated user's `timezone`, `first_day_of_week`, and `time_format` from `user_private_details`, defaults missing values to `auto`, strips unknown patch fields, validates the legacy enum/string limits, and preserves private read cache plus no-store mutation responses.                                                                                                                                                                                                                                                                                                                     |
| `GET /api/v1/users/me/identities`                                                                                                                                                                                          | `apps/backend` Rust route dispatcher | `route-overrides.json` marks the route `migrated`; Rust revalidates a normal Supabase browser session or non-app-session Bearer token with Supabase Auth, rejects Tuturuuu app-session tokens, extracts the Auth JS-compatible `identities` array from the revalidated Supabase user JSON, returns the legacy identities/canUnlink payload, and keeps the legacy private cache directive plus auth, Supabase rejection, and internal error bodies.                                                                                                                                                                                                                                                                                                               |
| `PATCH /api/v1/users/me/full-name`                                                                                                                                                                                         | `apps/backend` Rust route dispatcher | `route-overrides.json` marks the route `migrated`; Rust revalidates the browser Supabase session cookie or non-app-session Bearer token with Supabase Auth, validates `full_name` as a required JSON string with trimmed length `1..100`, and upserts `user_private_details` with `user_id` fixed to the authenticated user through Supabase REST using the caller token and `on_conflict=user_id`.                                                                                                                                                                                                                                                                                                                                                              |
| `POST /api/v1/aurora/health`                                                                                                                                                                                               | `apps/backend` Rust route dispatcher | `route-overrides.json` marks the route `migrated`; Rust validates the browser Supabase session with Supabase Auth, preserves the exact `@tuturuuu.com` email-domain gate, calls `AURORA_EXTERNAL_URL/health`, and returns the legacy success, auth, forbidden, and upstream-failure JSON bodies.                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `GET` / `POST` `/api/v1/aurora/forecast`, `GET` / `POST` `/api/v1/aurora/ml-metrics`, `GET` / `POST` `/api/v1/aurora/statistical-metrics`                                                                                  | `apps/backend` Rust route dispatcher | `route-overrides.json` marks the Aurora forecast and metrics method artifacts `migrated`; Rust reads public Aurora forecast and metric tables through the server-owned Supabase REST adapter for GET. POST ingest routes preserve the legacy `AURORA_EXTERNAL_URL` and `AURORA_EXTERNAL_WSID` checks, Supabase session revalidation, exact `@tuturuuu.com` email-domain gate, external Aurora fetches, normalized Supabase inserts with the caller token, and legacy success/error JSON bodies.                                                                                                                                                                                                                                                                  |
| `GET` / `POST` `/api/v1/infrastructure/changelog`, `GET` / `PUT` / `DELETE` `/api/v1/infrastructure/changelog/:id`, `POST /api/v1/infrastructure/changelog/:id/publish`, `GET /api/v1/infrastructure/changelog/slug/:slug` | `apps/backend` Rust route dispatcher | `route-overrides.json` marks the collection, detail, publish, and slug route artifacts `migrated`; Rust reads `changelog_entries` through the server-owned Supabase REST adapter, validates browser Supabase auth cookies with Supabase Auth before checking root workspace `manage_changelog`, falls back to published-only public reads for anonymous or unauthorized sessions, preserves exact-count list pagination, singular PostgREST detail/slug lookups, write authorization and validation, publish/unpublish timestamp behavior, and maps `PGRST116` to the legacy `404` body. Media upload remains legacy-owned.                                                                                                                                      |
| `GET /api/v1/inventory/storefronts/:slug`, `GET /api/v1/inventory/orders/:publicToken`                                                                                                                                     | `apps/backend` Rust route dispatcher | `route-overrides.json` marks both public inventory read endpoints `migrated`; Rust keeps storefront/order data behind private inventory RPCs and service-role private-schema metadata reads, preserves public storefront CDN cache headers, private storefront/order app-session and browser-session membership checks, simulated HMAC order tokens, private no-store cache headers, and legacy `401`/`403`/`404`/`500` JSON bodies. Storefront checkout creation, analytics events, Polar webhooks, and workspace inventory management remain legacy-owned.                                                                                                                                                                                                     |
| `GET /api/v1/topic-announcement-verifications/:token`                                                                                                                                                                      | `apps/backend` Rust route dispatcher | `route-overrides.json` marks the route `migrated`; Rust decodes the token path segment, hashes it with SHA-256, reads and updates `private.topic_announcement_contact_verifications` through the server-owned Supabase REST adapter, and returns the legacy public HTML pages for verified, unavailable/already-used, expired, and failed links. Workspace Topic Announcements management APIs remain legacy-owned.                                                                                                                                                                                                                                                                                                                                              |
| `POST` / `DELETE` `/api/v1/infrastructure/languages`                                                                                                                                                                       | `apps/backend` Rust route dispatcher | `route-overrides.json` marks the route `migrated`; Rust preserves the legacy locale validation bodies and `NEXT_LOCALE` set/delete cookie behavior.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `POST` / `DELETE` `/api/v1/infrastructure/sidebar`                                                                                                                                                                         | `apps/backend` Rust route dispatcher | `route-overrides.json` marks the route `migrated`; Rust preserves the legacy collapsed-sidebar validation body and `sidebar-collapsed` set/delete cookie behavior.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `POST` / `DELETE` `/api/v1/infrastructure/sidebar/sizes`                                                                                                                                                                   | `apps/backend` Rust route dispatcher | `route-overrides.json` marks the route `migrated`; Rust preserves the legacy size validation body, two-cookie write behavior, and DELETE behavior that clears only `sidebar-size`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `GET /api/v1/infrastructure/users/fields/types`                                                                                                                                                                            | `apps/backend` Rust route dispatcher | `route-overrides.json` marks the route `migrated`; Rust returns the deterministic ordered legacy field type payload without opening a Supabase admin client for static metadata.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `GET /api/v1/infrastructure/ai/models`                                                                                                                                                                                     | `apps/backend` Rust route dispatcher | `route-overrides.json` marks the route `migrated`; Rust reads `private.ai_gateway_models` through the server-owned Supabase REST adapter with private-schema headers, preserves the fixed public column list, default `type=language` filtering, provider/tag/enabled/search/ids filters, exact-count pagination, and caps ID filters at 100 so private model metadata stays behind the backend.                                                                                                                                                                                                                                                                                                                                                                 |
| `OPTIONS /api/v1/auth/password-login`, `/otp/send`, and `/otp/verify`; `GET` / `OPTIONS` `/api/v1/auth/otp/settings`                                                                                                       | `apps/backend` Rust route dispatcher | `route-overrides.json` marks the shared auth preflight method artifacts plus OTP settings `GET` migrated; Rust preserves wildcard CORS, public client/platform validation, `WEB_OTP_ENABLED` reads for web/tulearn, mobile OTP policy reads, non-mobile fail-open diagnostics, and mobile fail-closed errors while the paired OTP send/verify and password auth methods remain `legacy-next`.                                                                                                                                                                                                                                                                                                                                                                    |
| `OPTIONS /api/v1/auth/mobile/password-login`, `/send-otp`, and `/verify-otp`                                                                                                                                               | `apps/backend` Rust route dispatcher | `route-overrides.json` marks only the `OPTIONS` method artifacts `migrated`; Rust preserves the shared legacy wildcard CORS `204` response while the `POST` auth methods remain `legacy-next`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `GET` / `OPTIONS` `/api/v1/mobile/version-check`                                                                                                                                                                           | `apps/backend` Rust route dispatcher | `route-overrides.json` marks both method artifacts `migrated`; Rust preserves public strict query validation, root workspace mobile policy config reads through the server-owned Supabase REST adapter, legacy update-status evaluation, and the shared wildcard CORS response headers.                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `OPTIONS /api/v1/auth/qr-login/challenges`, `/:challengeId`, `/:challengeId/approve`                                                                                                                                       | `apps/backend` Rust route dispatcher | `route-overrides.json` marks only the `OPTIONS` method artifacts `migrated`; Rust preserves the legacy bare empty `204` response while QR challenge creation, polling, and approval remain `legacy-next`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `OPTIONS /api/v1/auth/mfa/mobile/challenges` and `/approvals`                                                                                                                                                              | `apps/backend` Rust route dispatcher | `route-overrides.json` marks only the `OPTIONS` method artifacts `migrated`, including dynamic challenge polling and approval paths; Rust preserves the legacy bare empty `204` response while challenge creation, polling, approval, and approval listing remain `legacy-next`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `OPTIONS /api/v1/workspaces/:wsId/external-projects/webgl-packages/upload`                                                                                                                                                 | `apps/backend` Rust route dispatcher | `route-overrides.json` marks only the `OPTIONS` method artifact `migrated`; Rust preserves the legacy origin-dependent CMS upload CORS `204` response while the protected `PUT` upload remains `legacy-next`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `POST /api/v1/workspaces/:wsId/user-groups/:groupId/group-checks/:postId/email`                                                                                                                                            | `apps/backend` Rust route dispatcher | `route-overrides.json` marks the route `migrated`; Rust preserves the legacy `410 Gone` response for removed direct post email sending.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `GET` / `POST` `/api/v1/workspaces/:wsId/slides`                                                                                                                                                                           | `apps/backend` Rust route dispatcher | `route-overrides.json` marks the route `migrated`; Rust preserves the current `501 Not implemented` placeholder contract without adding protected workspace slide data access.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `PUT` / `DELETE` `/api/v1/workspaces/:wsId/slides/:slideId`                                                                                                                                                                | `apps/backend` Rust route dispatcher | `route-overrides.json` marks the route `migrated`; Rust preserves the current `501 Not implemented` placeholder contract without adding protected workspace slide data access.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `PUT /api/v1/infrastructure/migrate/grouped-score-names`                                                                                                                                                                   | `apps/backend` Rust route dispatcher | `route-overrides.json` marks the route `migrated`; Rust preserves the legacy development-only guard and the disabled `410 MIGRATION_DISABLED` response for the removed `user_group_indicators` table.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `GET` / `PUT` / `PATCH` / `POST` `/api/v1/infrastructure/migrate/:migration`                                                                                                                                               | `apps/backend` Rust route dispatcher | `route-overrides.json` marks the legacy one-off batch migration helpers `accepted-removal`; Rust preserves the development/local-E2E guard and legacy method allow lists, but returns terminal `410 MIGRATION_DISABLED` instead of exposing broad admin batch reads or writes through the Cloudflare-compatible backend.                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `PUT /api/workspaces/:wsId/products/categories/migrate`, `/products/units/migrate`, `/transactions/categories/migrate`, `/users/indicators/migrate`, and `/wallets/transactions/migrate`                                   | `apps/backend` Rust route dispatcher | `route-overrides.json` marks these obsolete workspace migration writes `accepted-removal`; Rust preserves the development-only guard and returns the terminal `410 MIGRATION_DISABLED` decommission body instead of preserving legacy Supabase data writes.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `GET` / `POST` `/api/v1/workspaces/:wsId/encryption/migrate`, `POST /api/v1/workspaces/:wsId/storage/migrate`, `GET /api/v2/workspaces/:wsId/migrate/:module`                                                              | `apps/backend` Rust route dispatcher | `route-overrides.json` marks these production auth/API-key migration helpers `accepted-removal`; Rust preserves each legacy method allow list but returns terminal `410 MIGRATION_DISABLED` in every environment instead of preserving broad admin calendar encryption, storage migration, or migration export data paths.                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `GET /api/share/course/:courseId`, `GET /api/sync-logs`, `GET /api/users/search`, `GET /api/v1/proxy/tuturuuu`                                                                                                             | `apps/backend` Rust route dispatcher | `route-overrides.json` marks these retired legacy API aliases, broad maintenance/search routes, and the development-only Tuturuuu API proxy `accepted-removal`; Rust returns terminal `410 ENDPOINT_REMOVED` with legacy `Allow` headers while maintained replacements, workspace-scoped readers, phase-specific routes, or direct backend/internal API clients remain separate migration work. Payment paths are not claimed by this compatibility responder and therefore return the normal platform `404`.                                                                                                                                                                                                                                                    |

First TanStack Start migrated ownership:

| Legacy route                                                                                                                                                                                                                                                                    | New owner                                         | Evidence                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `/:locale`                                                                                                                                                                                                                                                                      | `apps/tanstack-web` TanStack Start static route   | `route-overrides.json` marks the landing page, landing metadata layout, and shared marketing layout `migrated`; the Start route preserves the public English and Vietnamese landing content with local primitives and no framer-motion, Next.js APIs, auth, Supabase, or protected workspace data access.                                                                                                                                                                                                                                                         |
| `/:locale/docs`                                                                                                                                                                                                                                                                 | `apps/tanstack-web` TanStack Start route loader   | `route-overrides.json` marks the page `migrated`; `/:locale/docs` throws a TanStack Router `307` redirect to `https://docs.tuturuuu.com`.                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `/:locale/calendar/meet-together/[[...slug]]`                                                                                                                                                                                                                                   | `apps/tanstack-web` TanStack Start route loader   | `route-overrides.json` marks the page `migrated`; `/:locale/calendar/meet-together` and nested slug paths redirect to `/meet-together` while preserving trailing slug segments.                                                                                                                                                                                                                                                                                                                                                                                   |
| `/:locale/pricing`                                                                                                                                                                                                                                                              | `apps/tanstack-web` TanStack Start route loader   | `route-overrides.json` marks the page `migrated`; `/pricing` and `/:locale/pricing` throw a TanStack Router `307` redirect to `/?hash-nav=1#pricing`.                                                                                                                                                                                                                                                                                                                                                                                                             |
| `/:locale/about`                                                                                                                                                                                                                                                                | `apps/tanstack-web` TanStack Start static route   | `route-overrides.json` marks the about page and metadata-only layout `migrated`; the Start route preserves the legacy English and Vietnamese `about.*` message namespace through TanStack-local message files and renders without framer-motion, Next.js APIs, auth, Supabase, or protected workspace data access.                                                                                                                                                                                                                                                |
| `/:locale/contact`                                                                                                                                                                                                                                                              | `apps/tanstack-web` TanStack Start route          | `route-overrides.json` marks the page and metadata layout `migrated`; the Start route preserves the visible contact shell, hydrates the current-user contact profile through TanStack Query and Start server functions, and submits inquiries through `@tuturuuu/internal-api` Rust backend facades for `/api/v1/users/me/profile` and `/api/v1/inquiries`.                                                                                                                                                                                                       |
| `/:locale/users/:handle`                                                                                                                                                                                                                                                        | `apps/tanstack-web` TanStack Start dynamic route  | `route-overrides.json` marks the auth-gated marketing profile page `migrated`; the Start route preserves fail-closed current-user auth, locale-aware login redirects with `nextUrl`, private no-store headers, caller-scoped reads of the legacy public `users` profile fields through the internal-api `users-server` facade, the profile background/avatar shell, and explicit no-auth Playwright coverage. A Rust-owned public profile reader remains the follow-up before removing the temporary request-scoped Supabase helper.                              |
| `/:locale/contributors`                                                                                                                                                                                                                                                         | `apps/tanstack-web` TanStack Start route          | `route-overrides.json` marks the page `migrated`; the Start route preserves the public contributors shell, GitHub repository/contributor data loading, loading and error states, stats, contributor list, CTA links, and analytics sections through TanStack Query. Dependency-free CSS/SVG equivalents are accepted for the legacy `framer-motion`, Recharts, and `react-confetti` visuals.                                                                                                                                                                      |
| `/:locale/women-in-tech`                                                                                                                                                                                                                                                        | `apps/tanstack-web` TanStack Start route          | `route-overrides.json` marks the page and metadata layout `migrated`; the Start route preserves the localized legacy title, Open Graph/Twitter/head metadata, public Vietnamese Women's Day content, copied media, local language switcher, and section structure. Dependency-free native image and CSS animation replacements are accepted for the legacy Next/framer-motion runtime.                                                                                                                                                                            |
| `/:locale/acceptable-use`, `/community-guidelines`, `/privacy`, and `/terms`                                                                                                                                                                                                    | `apps/tanstack-web` TanStack Start static routes  | `route-overrides.json` marks each legal page and metadata-only layout `migrated`; the Start routes preserve the legacy static legal content, local legal primitives, and metadata without auth, Supabase, or protected workspace data access.                                                                                                                                                                                                                                                                                                                     |
| `/:locale/partners`                                                                                                                                                                                                                                                             | `apps/tanstack-web` TanStack Start static route   | `route-overrides.json` marks the partners page and metadata-only layout `migrated`; the Start route preserves the legacy partner content, CTAs, outbound links, local partner primitives, and copied public logo assets without auth, Supabase, or protected workspace data access.                                                                                                                                                                                                                                                                               |
| `/:locale/products/ai`, `/calendar`, `/crm`, `/documents`, `/drive`, `/finance`, `/inventory`, `/lms`, `/mail`, `/tasks`, and `/workflows`                                                                                                                                      | `apps/tanstack-web` TanStack Start static routes  | `route-overrides.json` marks each static product page and layout `migrated`; the Start routes preserve the legacy product copy, metadata, and shared page primitives without adding auth, Supabase, or protected workspace data access.                                                                                                                                                                                                                                                                                                                           |
| `/:locale/ai/chats/:chatId`                                                                                                                                                                                                                                                     | `apps/tanstack-web` TanStack Start route          | `route-overrides.json` marks the public AI chat page and metadata layout `migrated`; the Start route fetches only `ai_chats.is_public=true` rows and their ordered public messages through a server function backed by Supabase REST, hydrates with TanStack Query, preserves not-found behavior for missing/private chats, and renders a read-only transcript instead of the dashboard streaming chat client.                                                                                                                                                    |
| `/:locale/documents/:documentId`                                                                                                                                                                                                                                                | `apps/tanstack-web` TanStack Start route          | `route-overrides.json` marks the public document page and layout `migrated`; the Start route fetches only public `workspace_documents` rows through a server function, hydrates with TanStack Query, preserves fail-closed not-found behavior, and keeps the current empty document body shell. The migrated layout uses stable localized generic head metadata instead of the legacy document-name Open Graph lookup to avoid a second metadata-time Supabase dependency.                                                                                        |
| `/:locale/products/meet-together`                                                                                                                                                                                                                                               | `apps/tanstack-web` TanStack Start route loader   | `route-overrides.json` marks the page `migrated`; `/products/meet-together` and `/:locale/products/meet-together` throw a TanStack Router `307` redirect to `/meet-together`.                                                                                                                                                                                                                                                                                                                                                                                     |
| `/:locale/qr-generator`                                                                                                                                                                                                                                                         | `apps/tanstack-web` TanStack Start route loader   | `route-overrides.json` marks the page `migrated`; `/qr-generator` and `/:locale/qr-generator` redirect to the QR app origin and forward the raw query string so duplicate query keys are preserved.                                                                                                                                                                                                                                                                                                                                                               |
| `/:locale/changelog`                                                                                                                                                                                                                                                            | `apps/tanstack-web` TanStack Start route          | `route-overrides.json` marks the changelog index page `migrated`; the Start route reads the Rust-owned public changelog `GET` API through a server function, hydrates the list with TanStack Query, applies ISR-style CDN headers, and falls back to an empty public state when the backend cannot return published entries.                                                                                                                                                                                                                                      |
| `/:locale/changelog/:slug`                                                                                                                                                                                                                                                      | `apps/tanstack-web` TanStack Start route          | `route-overrides.json` marks the changelog detail page `migrated`; the Start route reads the Rust-owned public changelog slug `GET` API through a server function, hydrates the entry with TanStack Query, reuses the public changelog list for adjacent navigation, applies ISR-style CDN headers, and throws the TanStack not-found response when the slug is missing. No-auth coverage uses a deterministic missing-slug 404 example so empty databases remain valid.                                                                                          |
| `/:locale/:wsId/changelog`                                                                                                                                                                                                                                                      | `apps/tanstack-web` TanStack Start dynamic route  | `route-overrides.json` marks the dashboard changelog page artifact `migrated`; the Start route preserves fail-closed current-user auth, forwarded workspace resolution, dashboard card/list parity, public changelog links, and TanStack Query loading through the Rust-owned changelog list API instead of direct Supabase reads.                                                                                                                                                                                                                                |
| `/:locale/:wsId/infrastructure/changelog`                                                                                                                                                                                                                                       | `apps/tanstack-web` TanStack Start dynamic route  | `route-overrides.json` marks the infrastructure changelog admin list page artifact `migrated`; the Start route preserves fail-closed current-user auth, workspace resolution, `manage_changelog` settings redirect parity, URL search filters, TanStack Query hydration, legacy table columns/actions, and Rust-backed changelog list loading instead of direct service-role Supabase reads. New/edit pages and media upload remain separately tracked.                                                                                                           |
| `/tools/random`, `/:locale/tools/random`                                                                                                                                                                                                                                        | `apps/tanstack-web` TanStack Start route loaders  | The Start routes preserve the current web proxy contract by redirecting to `apps/tools /random` and forwarding the raw query string. The generator UI is owned by the tools satellite, not the platform shell.                                                                                                                                                                                                                                                                                                                                                    |
| `/:locale/branding`, `/blog`, and `/careers`                                                                                                                                                                                                                                    | `apps/tanstack-web` TanStack Start static routes  | `route-overrides.json` marks the visible marketing pages and metadata-only layouts `migrated`; the Start routes preserve the static brand, blog placeholder, and careers content without auth, Supabase, or protected workspace data access. Branding Open Graph/Twitter image artifacts remain legacy-owned.                                                                                                                                                                                                                                                     |
| `/:locale/facebook-mockup`                                                                                                                                                                                                                                                      | `apps/tanstack-web` TanStack Start client route   | `route-overrides.json` marks the page `migrated`; the Start route preserves the public Facebook mockup demo with local browser-safe components and no auth, Supabase, or protected workspace data access.                                                                                                                                                                                                                                                                                                                                                         |
| `/:locale/security`                                                                                                                                                                                                                                                             | `apps/tanstack-web` TanStack Start static route   | `route-overrides.json` marks the security landing page and metadata-only layout `migrated`; the Start route preserves the legacy static security copy, vulnerability-reporting CTAs, trust sections, and local primitives without framer-motion, Next.js APIs, auth, Supabase, or protected workspace data access.                                                                                                                                                                                                                                                |
| `/:locale/security/policy` and `/bug-bounty`                                                                                                                                                                                                                                    | `apps/tanstack-web` TanStack Start static routes  | `route-overrides.json` marks the security policy page, Security Hall of Fame page, and bug-bounty metadata-only layout `migrated`; the Start routes preserve the legacy responsible-disclosure and researcher-credit copy with local security primitives and no auth, Supabase, or protected workspace data access.                                                                                                                                                                                                                                               |
| `/:locale/solutions/construction`, `/education`, `/healthcare`, `/hospitality`, `/manufacturing`, `/pharmacies`, `/realestate`, `/restaurants`, and `/retail`                                                                                                                   | `apps/tanstack-web` TanStack Start static routes  | `route-overrides.json` marks every static solution page and layout `migrated`; the Start routes preserve legacy copy, metadata, FAQ content, CTAs, success metrics, and local solution primitives without framer-motion, Next.js APIs, auth, Supabase, or protected workspace data access.                                                                                                                                                                                                                                                                        |
| `/:locale/ui`, `/:locale/ui/setup`, `/:locale/ui/contributing`, `/:locale/ui/components`, `/:locale/ui/components/:componentId`                                                                                                                                                 | `apps/tanstack-web` TanStack Start static routes  | `route-overrides.json` marks the public UI showcase layout and pages `migrated`; the Start routes preserve the UI docs shell, setup/contribution pages, component index, and component detail views through local registry/docs data without auth, Supabase, or protected workspace data access.                                                                                                                                                                                                                                                                  |
| `/:locale/visualizations/horse-racing`                                                                                                                                                                                                                                          | `apps/tanstack-web` TanStack Start client route   | `route-overrides.json` marks the page `migrated`; the Start route preserves the public horse-racing algorithm visualization with local TanStack-safe visualization components and no auth, Supabase, or protected workspace data access.                                                                                                                                                                                                                                                                                                                          |
| `/:locale/verify-token`                                                                                                                                                                                                                                                         | `apps/tanstack-web` TanStack Start route loader   | `route-overrides.json` marks the page `migrated`; the Start route preserves the legacy `nextUrl` redirect sanitizer and `/onboarding` fallback without importing Next auth/session runtime into the Cloudflare-compatible frontend.                                                                                                                                                                                                                                                                                                                               |
| `/:locale/shared/user-profile/:code`                                                                                                                                                                                                                                            | `apps/tanstack-web` TanStack Start route          | `route-overrides.json` marks the page artifact `migrated`; the Start route preserves the legacy noindex head, profile-link loader, fail-closed auth redirect for protected links, unavailable shell for expired/revoked links, localized fill form, and allowlist-scoped prefill behavior. Submit/avatar APIs still route through `packages/internal-api` and remain separate backend migration work.                                                                                                                                                             |
| `/:locale/shared/task/:shareCode`                                                                                                                                                                                                                                               | `apps/tanstack-web` TanStack Start route          | `route-overrides.json` marks the page artifact `migrated`; the Start route preserves fail-closed current-user resolution before task data fetch, the legacy login redirect with `nextUrl`, noindex metadata, unavailable shell for revoked links, and shared task dialog rendering. `/api/v1/shared/tasks/:shareCode` remains legacy-owned backend work.                                                                                                                                                                                                          |
| `/:locale/shared/task-boards/:code`                                                                                                                                                                                                                                             | `apps/tanstack-web` TanStack Start dynamic route  | `route-overrides.json` marks the page artifact `migrated`; the Start route preserves noindex metadata, unavailable-shell behavior for missing or revoked public board links, no-store loading through the `packages/internal-api` public board facade, and read-only public `BoardViews` rendering through TanStack-local payload adapters. `/api/v1/shared/task-boards/:code` remains legacy-owned backend work.                                                                                                                                                 |
| `/:locale/:wsId/finance` route layout plus `/:locale/:wsId/finance` and `/:locale/:wsId/finance/{analytics,budgets,categories,debts,debts/:debtId,invoices,invoices/:invoiceId,invoices/new,recurring,tags,transactions,transactions/:transactionId,wallets,wallets/:walletId}` | `apps/tanstack-web` TanStack Start route loaders  | `route-overrides.json` marks the Finance route-specific layout and page artifacts `migrated`; the Start routes preserve the accepted 307 redirects to the platform Finance paths and forward raw query strings so creation/search/pagination handoff parameters survive. Dynamic finance IDs are encoded before handoff. The legacy Finance layout's command/provider UI is not rendered in TanStack because these migrated leaves redirect; parent dashboard/session and Finance data ownership remain legacy-owned until workspace provider parity is complete. |
| `/:locale/:wsId/mail` route layout plus `/:locale/:wsId/mail` and `/:locale/:wsId/mail/sent` pages                                                                                                                                                                              | `apps/tanstack-web` TanStack Start route loaders  | `route-overrides.json` marks the Mail leaf pages `migrated` and the legacy route-specific Mail layout `accepted-removal`; the Start leaves preserve 307 handoff to the standalone Mail app through `buildMailRedirectHref`, while the Mail app centralized auth proxy and workspace-normalization boundary replace the legacy dashboard layout gate. Parent dashboard/session ownership remains legacy-owned until workspace provider parity is complete.                                                                                                         |
| `/:locale/:wsId/workforce`, `/ai-chat/new`, `/meet`, `/qr-generator`, `/drive`, education library/builder pages, `/epm`, and `/external-projects`                                                                                                                               | `apps/tanstack-web` TanStack Start route loaders  | `route-overrides.json` marks these page artifacts `migrated`; the Start routes preserve the legacy 307/308 redirects to workspace user database, chat, meet plans, QR app with query forwarding, Drive app handoff with workspace slug normalization, education library/builder, and CMS app destinations. Parent dashboard layout/session ownership remains legacy-owned until workspace provider parity is complete.                                                                                                                                            |
| `/:locale/:wsId/education/quiz-sets/:setId`                                                                                                                                                                                                                                     | `apps/tanstack-web` TanStack Start route loader   | `route-overrides.json` marks the page artifact `migrated`; the Start route preserves fail-closed current-user auth, workspace resolution, quiz table search/pagination with the legacy 10-row default, forwarded-auth internal-api quiz reads, and TanStack Query-backed create/update/delete plus AI explanation actions. The quiz-set detail layout and quiz APIs remain separately tracked.                                                                                                                                                                    |
| `/:locale/:wsId/education/quiz-sets/:setId/linked-modules`                                                                                                                                                                                                                      | `apps/tanstack-web` TanStack Start route loader   | `route-overrides.json` marks the page artifact `migrated`; the Start route preserves fail-closed current-user auth, workspace resolution, linked course module table parity, and link/unlink workflow through forwarded-auth internal-api facades backed by Rust-owned education read endpoints. Parent dashboard/session ownership remains legacy-owned.                                                                                                                                                                                                         |
| `/:locale/:wsId/education/courses/:courseId/modules/:moduleId/content`                                                                                                                                                                                                          | `apps/tanstack-web` TanStack Start route loader   | `route-overrides.json` marks the page artifact `migrated`; the Start route preserves fail-closed current-user auth, workspace resolution, forwarded internal-api module reads, localized module content summary, and TanStack Query/internal-api-backed debounced content saves. The parent module layout and module API ownership remain separately tracked.                                                                                                                                                                                                     |
| `/:locale/:wsId/education/courses/:courseId/modules/:moduleId/quizzes`                                                                                                                                                                                                          | `apps/tanstack-web` TanStack Start route loader   | `route-overrides.json` marks the page artifact `migrated`; the Start route preserves fail-closed current-user auth, workspace resolution, the legacy `update_user_groups` not-found gate before data loading, URL-backed quiz search/pagination, and forwarded-auth internal-api quiz reads plus shared quiz table edit/delete actions. Quiz API and AI quiz-generation backend ownership remain separately tracked.                                                                                                                                              |
| `/:locale/:wsId/education/courses/:courseId/modules/:moduleId/quizzes/new`                                                                                                                                                                                                      | `apps/tanstack-web` TanStack Start route loader   | `route-overrides.json` marks the page artifact `migrated`; the Start route preserves fail-closed current-user auth, workspace resolution, localized manual quiz creation shell, and TanStack Query-backed submission through the internal-api quiz facade. Quiz create/update API ownership and the module quiz list page remain separately tracked.                                                                                                                                                                                                              |
| `/:locale/:wsId/hive` route layout                                                                                                                                                                                                                                              | `apps/tanstack-web` TanStack Start route loaders  | `route-overrides.json` marks the route-specific layout artifact `migrated`; the migrated Hive leaves redirect to the standalone Hive app, while the legacy layout only imported `@xyflow/react` styles and returned children. Hive APIs and parent dashboard/session ownership remain legacy-owned.                                                                                                                                                                                                                                                               |
| `/:locale/:wsId/mind/boards/:boardId` route layout                                                                                                                                                                                                                              | `apps/tanstack-web` TanStack Start route loader   | `route-overrides.json` marks the route-specific layout artifact `migrated`; the migrated Mind board page redirects to the standalone Mind board route with query forwarding, while the legacy layout only imported `@xyflow/react` styles and returned children. Mind APIs and parent dashboard/session ownership remain legacy-owned.                                                                                                                                                                                                                            |
| `/:locale/:wsId/documents/:documentId` route layout                                                                                                                                                                                                                             | `apps/tanstack-web` TanStack Start metadata       | `route-overrides.json` marks the static Document Details metadata layout artifact `migrated`; the legacy layout only exported title/description metadata and returned children. The document detail page, workspace dashboard/session ownership, and document data/API routes remain legacy-owned.                                                                                                                                                                                                                                                                |
| `/:locale/:wsId/infrastructure` and `/:locale/:wsId/platform` parent layouts                                                                                                                                                                                                    | `apps/tanstack-web` TanStack Start parent loaders | `route-overrides.json` marks both layout artifacts `migrated`; the Start parent routes preserve fail-closed current-user auth, workspace resolution, root `view_infrastructure` permission gating, and `Outlet` rendering for migrated children. The exact infrastructure analytics page, platform billing, platform roles, and remaining settings children stay separately tracked as legacy-next artifacts.                                                                                                                                                     |
| `/:locale/:wsId/epm/collections/:collectionId`, `/epm/entries/:entryId`, `/platform/external-projects`, and `/users/topic-announcements`                                                                                                                                        | `apps/tanstack-web` TanStack Start route loaders  | `route-overrides.json` marks these page artifacts `migrated`; the Start routes preserve the legacy 307 redirects to CMS collection/entry/admin destinations and legacy dashboard aliases. Infrastructure settings/app-coordination routes now live in `apps/infrastructure` and the old TanStack/web route is recorded as an accepted removal. Parent dashboard layout/session ownership remains legacy-owned until workspace provider parity is complete.                                                                                                        |
| `/:locale/:wsId/ai-chat/chatbots`                                                                                                                                                                                                                                               | `apps/tanstack-web` TanStack Start route loader   | `route-overrides.json` marks the page artifact `migrated`; the Start route preserves fail-closed current-user auth, workspace resolution, `ai_chat` permission gating, route metadata, and localized `FeatureSummary` content. The create action intentionally targets the canonical `/:locale/:wsId/ai-chat/my-chatbots/new` Start route instead of the legacy `/:wsId/chat` alias. Parent dashboard and AI chat session/provider ownership remains legacy-owned.                                                                                                |
| `/:locale/:wsId/ai-chat/my-chatbots`                                                                                                                                                                                                                                            | `apps/tanstack-web` TanStack Start route loader   | `route-overrides.json` marks the page artifact `migrated`; the Start route preserves fail-closed current-user auth, workspace resolution, the legacy `ai_chat` layout permission gate, URL-backed table search/pagination, forwarded-auth group-tag reads, internal-api-backed row deletion, and localized `FeatureSummary`/`CustomDataTable` UI. Parent dashboard and AI chat session/provider ownership remains legacy-owned.                                                                                                                                   |
| `/:locale/:wsId/ai-chat/my-chatbots/new`                                                                                                                                                                                                                                        | `apps/tanstack-web` TanStack Start client route   | `route-overrides.json` marks the static metadata layout and client-only form page `migrated`; the Start route preserves the local validation, localized summary strings, and submit toast behavior without adding protected API, Supabase, or server-action access. Parent dashboard and AI chat session/provider ownership remains legacy-owned.                                                                                                                                                                                                                 |
| `/:locale/:wsId/users/group-tags`                                                                                                                                                                                                                                               | `apps/tanstack-web` TanStack Start route loader   | `route-overrides.json` marks the page artifact `migrated`; the Start route preserves fail-closed current-user auth, workspace resolution, URL-backed table search/pagination, forwarded-auth group-tag reads, internal-api-backed group-tag mutations/row actions, localized `FeatureSummary`/`CustomDataTable` UI, and locale-prefixed detail hrefs. Group-tag API ownership remains separately tracked for the backend Rust wave.                                                                                                                               |
| `/:locale/:wsId/users/group-tags/:tagId`                                                                                                                                                                                                                                        | `apps/tanstack-web` TanStack Start route loader   | `route-overrides.json` marks the page artifact `migrated`; the dynamic no-store Start route preserves fail-closed current-user auth, workspace resolution, URL-backed linked-group search/pagination, forwarded-auth tag detail and linked-group reads, TanStack Query-backed add/remove linked-group actions, localized `FeatureSummary`/`CustomDataTable` UI, and locale-prefixed group detail hrefs. Group-tag API ownership remains separately tracked for the backend Rust wave.                                                                             |
| `/:locale/:wsId/settings/reports`                                                                                                                                                                                                                                               | `apps/tanstack-web` TanStack Start route loader   | `route-overrides.json` marks the page artifact `migrated`; the Start route preserves fail-closed current-user auth, workspace resolution, `manage_user_report_templates` gating, URL-backed `q` search state, report and lead-generation template tables, preview panels, and edit/reset actions through TanStack Query server functions plus `packages/internal-api` workspace-config facades.                                                                                                                                                                   |
| `/:locale/:wsId/settings/notifications`                                                                                                                                                                                                                                         | `apps/tanstack-web` TanStack Start route loader   | `route-overrides.json` marks the page artifact `migrated`; the Start route preserves fail-closed current-user auth, workspace resolution, account notification status, workspace-wide enable/disable, browser permission controls, and editable event/channel preferences through TanStack Query server functions plus `packages/internal-api` notification preference facades. Notification preference API artifacts remain separately tracked Rust backend work.                                                                                                |
| `/:locale/:wsId/billing/success`                                                                                                                                                                                                                                                | `apps/pay` satellite app via TanStack redirect    | `route-overrides.json` marks the legacy success page as a `satellite-app` accepted replacement; the Start route issues a `307` to Pay and preserves the complete query string, including `checkoutId`. Checkout result rendering and payment reads remain Pay-owned.                                                                                                                                                                                                                                                                                              |
| `/:locale/:wsId/inventory`                                                                                                                                                                                                                                                      | `apps/tanstack-web` TanStack Start route loader   | `route-overrides.json` marks the root inventory dashboard page artifact `migrated`; the Start route preserves fail-closed current-user auth, forwarded-auth workspace resolution, `view_inventory` permission handling, localized access-denied state, statistic-card loading/error states, and inventory statistics loaded through the internal-api facade. `/api/v1/workspaces/:wsId/inventory/statistics` and deeper inventory pages remain separately tracked.                                                                                                |
| `/:locale/:wsId/inventory/batches`                                                                                                                                                                                                                                              | `apps/tanstack-web` TanStack Start dynamic route  | `route-overrides.json` marks the inventory batches page artifact `migrated`; the Start route preserves fail-closed current-user auth, forwarded-auth workspace resolution, `view_inventory` permission handling, localized access-denied state, URL-backed `q`/`page`/`pageSize` search state, and TanStack Query table loading through the internal-api inventory facade. `/api/v1/workspaces/:wsId/inventory/batches` remains separately tracked backend work.                                                                                                  |
| `/:locale/:wsId/inventory/categories`, `/manufacturers`, `/suppliers`, `/units`, and `/warehouses`                                                                                                                                                                              | `apps/tanstack-web` TanStack Start dynamic routes | `route-overrides.json` marks these inventory resource page artifacts `migrated`; the Start routes preserve fail-closed current-user auth, forwarded-auth workspace resolution, inventory view/create/update/delete or catalog/setup permission booleans, localized access-denied states, URL-backed `q`/`page`/`pageSize` table state, and TanStack Query table loading plus create/update/delete actions through the internal-api inventory facades. The matching workspace inventory and product compatibility APIs remain separately tracked backend work.     |
| `/:locale/:wsId/inventory/products` and `/:productId`                                                                                                                                                                                                                           | `apps/tanstack-web` TanStack Start dynamic routes | `route-overrides.json` marks the inventory product list and product detail/new form page artifacts `migrated`; the Start routes preserve fail-closed auth, workspace resolution, inventory and stock permission parity, route metadata, localized access-denied state, and TanStack Query product list/form loading plus mutations through internal-api inventory facades. Workspace inventory product APIs remain separately tracked backend work.                                                                                                               |
| `/:locale/:wsId/inventory/promotions`                                                                                                                                                                                                                                           | `apps/tanstack-web` TanStack Start dynamic route  | `route-overrides.json` marks the inventory promotions page artifact `migrated`; the Start route preserves fail-closed auth, workspace resolution, inventory view/create/update/delete permission context, route metadata, and TanStack Query CRUD through internal-api promotion facades. Workspace promotion API routes remain separately tracked backend work.                                                                                                                                                                                                  |
| `/:locale/:wsId/inventory/storefronts`                                                                                                                                                                                                                                          | `apps/tanstack-web` TanStack Start dynamic route  | `route-overrides.json` marks the inventory storefronts page artifact `migrated`; the Start route preserves fail-closed auth, workspace resolution, inventory catalog permission parity, route metadata, localized access-denied state, and TanStack Query reads/mutations through internal-api inventory storefront facades. Workspace storefront, listing, option-template, product, and public storefront APIs remain separately tracked backend work.                                                                                                          |
| `/:locale/:wsId/members`                                                                                                                                                                                                                                                        | `apps/tanstack-web` TanStack Start route loader   | `route-overrides.json` marks the workspace members page artifact `migrated`; the Start route preserves fail-closed auth, workspace resolution, personal-workspace/settings redirect, `manage_workspace_members` and `manage_workspace_roles` context, tab search validation, metadata, and the shared workspace-access client. `disableInvite` currently defaults to false until a Rust/internal-api workspace secret reader lands for `DISABLE_INVITE`; invite-link creation remains protected by the existing server API check.                                 |
| `/:locale/:wsId/tasks` plus task cycles, estimates, initiatives, labels, logs, notes, projects, templates, and template marketplace pages                                                                                                                                       | `apps/tanstack-web` TanStack Start route loaders  | `route-overrides.json` marks these page artifacts `migrated`; the Start routes preserve authenticated workspace resolution, route metadata, and shared task UI clients. Project/cycle/initiative/log/template/estimate/label routes keep the legacy `manage_projects` permission gate through the forwarded-auth internal permission check, while the project/template detail routes load their initial data through forwarded-auth internal-api facades. Parent dashboard/session and remaining task data APIs remain separately owned.                          |
| `/:locale/:wsId/tasks/boards` and `/:locale/:wsId/tasks/boards/:boardId`                                                                                                                                                                                                        | `apps/tanstack-web` TanStack Start route loaders  | `route-overrides.json` marks both page artifacts `migrated`; the Start routes preserve authenticated board index/detail shells through shared task-board UI, the `next/navigation` runtime shim, forwarded-auth board authorization, legacy not-found mapping, and member/guest board access handling. The detail page omits the legacy Mira idle chat island until its local Next.js API/UI dependencies move behind shared TanStack/Rust facades.                                                                                                               |
| `/:locale/:wsId/calendar`, `/chat`, `/cron`, and `/memories`                                                                                                                                                                                                                    | `apps/tanstack-web` TanStack Start route loaders  | `route-overrides.json` marks these page artifacts `migrated`; the Start routes preserve authenticated workspace shells, route metadata, and legacy permission gates (`manage_calendar`, `view_chat`, or `ai_lab`) through forwarded-auth internal permission checks. Calendar/chat clients self-load through existing facades, while cron and memories keep data-free shared headers until app-local data clients move behind shared internal-api/Rust facades.                                                                                                   |
| `/:locale/:wsId/users/tutoring`                                                                                                                                                                                                                                                 | `apps/tanstack-web` TanStack Start route loader   | `route-overrides.json` marks the page artifact `migrated`; the Start route preserves fail-closed current-user auth, forwarded-auth full workspace resolution, personal-workspace and `view_user_groups` not-found handling, `update_user_groups_scores` management context, route metadata, and the shared tutoring client. Tutoring backing APIs remain separately tracked Rust migration work.                                                                                                                                                                  |
| `/:locale/:wsId/polls`                                                                                                                                                                                                                                                          | `apps/tanstack-web` TanStack Start static route   | `route-overrides.json` marks the page artifact `migrated`; the Start route preserves the legacy mock polls dashboard with local English/Vietnamese message bundles and shared UI primitives, without adding auth, Supabase, protected API, or server-action access. Parent dashboard layout/session ownership remains legacy-owned.                                                                                                                                                                                                                               |
| `/:locale/:wsId/users/structure`                                                                                                                                                                                                                                                | `apps/tanstack-web` TanStack Start static route   | `route-overrides.json` marks the page artifact `migrated`; the Start route ports the legacy local-state organizational-structure mock page, metadata, message bundle keys, canvas interactions, profile/details panel, and management dialogs without adding Supabase, protected API, or server-action access. Parent dashboard layout/session ownership remains legacy-owned.                                                                                                                                                                                    |
| `/:locale/:wsId/users/feedbacks`                                                                                                                                                                                                                                                | `apps/tanstack-web` TanStack Start route loader   | `route-overrides.json` marks the page artifact `migrated`; the Start route preserves fail-closed current-user auth, full workspace resolution, personal-workspace and `view_user_groups` not-found handling, `update_user_groups_scores` management context, route metadata, and the shared feedbacks client through internal-api user facades. Feedback data APIs remain separately tracked backend/internal-api work.                                                                                                                                           |
| `/:locale` error and not-found shells                                                                                                                                                                                                                                           | `apps/tanstack-web` root route                    | `route-overrides.json` marks both artifacts `migrated`; the Start root route owns the legacy reset button, localized `404` copy, and onboarding link through route error/not-found components.                                                                                                                                                                                                                                                                                                                                                                    |
| `/~offline` page                                                                                                                                                                                                                                                                | `apps/tanstack-web` TanStack Start route          | `route-overrides.json` marks the page `migrated`; the Start route renders the shared `OfflinePage` with the legacy title, message, and foreground/background classes.                                                                                                                                                                                                                                                                                                                                                                                             |
| `/~offline` layout                                                                                                                                                                                                                                                              | `apps/tanstack-web` root document                 | `route-overrides.json` marks the layout `migrated`; the Start root document imports shared UI globals and applies the legacy scroll/background body classes without relying on Next.js font helpers.                                                                                                                                                                                                                                                                                                                                                              |

Accepted removals:

| Legacy artifact                                                         | Decision           | Evidence                                                                                                                                                                                                                                                 |
| ----------------------------------------------------------------------- | ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `apps/web/src/app/api/auth/me/session/route.ts`                         | `accepted-removal` | The debug-style route returns raw `sb-*` auth cookie values plus the full Supabase session payload. No in-repo caller references `/api/auth/me/session`, and the TanStack/Rust cutover must not preserve raw session export behavior.                    |
| `apps/web/src/app/api/workspaces/[wsId]/categories/route.ts`            | `accepted-removal` | The file is zero bytes and exports no HTTP methods, so there is no runtime behavior to port. The override keeps the artifact visible and terminal instead of silently dropping it from the inventory.                                                    |
| `apps/web/src/app/api/v1/workspaces/[wsId]/encryption/migrate/route.ts` | `accepted-removal` | The legacy route performs admin calendar-event encryption status reads and E2EE data writes. Rust owns a terminal `410 MIGRATION_DISABLED` response with the original `GET, POST` allow list so cutover does not preserve broad migration writes.        |
| `apps/web/src/app/api/v1/workspaces/[wsId]/storage/migrate/route.ts`    | `accepted-removal` | The legacy route mutates workspace storage providers after privileged permission checks. Rust owns a terminal `410 MIGRATION_DISABLED` response with the original `POST` allow list; storage moves must use maintained runbooks or local backfills.      |
| `apps/web/src/app/api/v2/workspaces/[wsId]/migrate/[module]/route.ts`   | `accepted-removal` | The legacy route exposes broad API-key migration exports backed by admin Supabase reads, private schemas, and RPCs. Rust owns a terminal `410 MIGRATION_DISABLED` response with the original `GET` allow list instead of preserving this export surface. |

Recently migrated backend runtime candidates:

| Legacy route                                                                                                                                                                               | Decision   | Evidence                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `GET /api/auth/me`                                                                                                                                                                         | `migrated` | Rust `handle_backend_request` revalidates the Supabase browser cookie or non-app-session Bearer token with Supabase Auth, preserves the raw legacy user payload, no-store headers, and unauthorized response.                                                                                                                                                                                                                                                           |
| `GET /api/auth/mfa/totp/assurance-level`                                                                                                                                                   | `migrated` | Rust `handle_backend_request` revalidates the Supabase browser cookie or non-app-session Bearer token with Supabase Auth, then derives the no-argument Supabase MFA AAL payload from JWT claims and verified factors.                                                                                                                                                                                                                                                   |
| `GET` / `POST` `/api/auth/mfa/totp/factors`                                                                                                                                                | `migrated` | Rust `handle_backend_request` mirrors Auth JS factor listing from the revalidated Supabase user JSON and enrolls TOTP factors through Supabase Auth REST with QR-code normalization.                                                                                                                                                                                                                                                                                    |
| `GET` / `DELETE` `/api/auth/mfa/totp/factors/:factorId`                                                                                                                                    | `migrated` | Rust `handle_backend_request` resolves verified TOTP factor detail from the Auth JS-compatible list and unenrolls factors through Supabase Auth REST with the legacy success wrapper.                                                                                                                                                                                                                                                                                   |
| `GET /api/v1/workspaces/:wsId/posts/permissions`                                                                                                                                           | `migrated` | Rust `handle_backend_request` returns the legacy post approval/force-send flags through `has_workspace_permission` RPC checks, with missing auth or permission failures collapsed to false flags.                                                                                                                                                                                                                                                                       |
| `GET /api/v1/workspaces/:wsId/Mention`                                                                                                                                                     | `migrated` | Rust `handle_backend_request` returns the legacy singular email array after Supabase auth revalidation and exact `MEMBER` workspace membership, with caller-token `workspace_users.email` reads and legacy error bodies.                                                                                                                                                                                                                                                |
| `GET /api/v1/workspaces/:wsId/habits/access`                                                                                                                                               | `migrated` | Rust `handle_backend_request` returns the legacy enabled habits access probe after Supabase auth revalidation, workspace normalization, service-role `MEMBER` validation, and exact `ENABLE_HABITS=true` secret matching.                                                                                                                                                                                                                                               |
| `GET /api/v1/workspaces/:wsId/mobile/module-flags`                                                                                                                                         | `migrated` | Rust `handle_backend_request` returns the legacy sorted hiddenModuleIds payload after Supabase auth revalidation, caller-token workspace membership, and server-owned `workspace_secrets` mobile module flag reads.                                                                                                                                                                                                                                                     |
| `GET /api/v1/workspaces/:wsId/education/access`                                                                                                                                            | `migrated` | Rust `handle_backend_request` returns the legacy enabled education access probe after Supabase auth, getPermissions-compatible `ai_lab` checks, and server-owned `workspace_secrets` feature-flag reads, with workspace/secret/permission lookup failures collapsed to `enabled: false`.                                                                                                                                                                                |
| `GET /api/v1/workspaces/:wsId/finance/budgets/status`                                                                                                                                      | `migrated` | Rust `handle_backend_request` accepts finance/platform app-session and CLI credentials before Supabase fallback, normalizes the workspace, checks `manage_finance`, calls `get_budget_status` with service-role auth, and returns the raw legacy payload/error bodies.                                                                                                                                                                                                  |
| `GET /api/workspaces/:wsId/finance/charts/balance`                                                                                                                                         | `migrated` | Rust `handle_backend_request` accepts finance app-session, CLI, or Supabase credentials, normalizes the workspace, checks `view_finance_stats`, calls `get_wallet_balance_at_date`, and returns the legacy balance/date payload.                                                                                                                                                                                                                                        |
| `GET /api/v1/workspaces/:wsId/finance/debts/summary`                                                                                                                                       | `migrated` | Rust `handle_backend_request` accepts finance app-session, CLI, or Supabase credentials, normalizes the workspace, checks `manage_finance`, calls private `get_debt_loan_summary` with `_actor_id`, and returns the first row or legacy zero summary.                                                                                                                                                                                                                   |
| `GET /api/v1/workspaces/:wsId/finance/filter-users`                                                                                                                                        | `migrated` | Rust `handle_backend_request` accepts finance app-session, CLI, or Supabase credentials, normalizes the workspace, checks `view_transactions`, returns legacy users filter rows, and preserves caller-token workspace user reads for normal sessions.                                                                                                                                                                                                                   |
| `GET /api/v1/workspaces/:wsId/finance/invoices/subscription/context`                                                                                                                       | `migrated` | Rust `handle_backend_request` accepts finance app-session, CLI, or Supabase credentials, normalizes the workspace, checks `create_invoices`, validates requested student groups, and returns the legacy attendance plus latest paid invoice context.                                                                                                                                                                                                                    |
| `GET /api/v1/workspaces/:wsId/finance/recurring-transactions/upcoming`                                                                                                                     | `migrated` | Rust `handle_backend_request` accepts finance app-session, CLI, or Supabase credentials, normalizes the workspace, checks `view_transactions`, preserves `daysAhead` parseInt behavior, and returns the legacy upcomingTransactions envelope.                                                                                                                                                                                                                           |
| `GET /api/v1/workspaces/:wsId/settings/permissions`                                                                                                                                        | `migrated` | Rust `handle_backend_request` mirrors the legacy `getPermissions` result for settings permission flags after Supabase auth revalidation and workspace membership/default/role permission resolution.                                                                                                                                                                                                                                                                    |
| `GET /api/v1/workspaces/:wsId/settings/permissions/check`                                                                                                                                  | `migrated` | Rust `handle_backend_request` mirrors the legacy `getPermissions(...).containsPermission(...)` result after Supabase auth revalidation and workspace membership/default/role permission resolution.                                                                                                                                                                                                                                                                     |
| `GET` / `PUT` `/api/v1/infrastructure/mobile-versions`                                                                                                                                     | `migrated` | Rust `handle_backend_request` revalidates the browser cookie or non-app-session Bearer token, requires root `manage_workspace_roles`, returns the legacy mobile policy snapshot, and upserts normalized mobile policy writes through the server-owned Supabase REST adapter.                                                                                                                                                                                            |
| `GET` / `POST` `/api/v1/infrastructure/timezones` and `PUT` / `DELETE` `/api/v1/infrastructure/timezones/:timezoneId`                                                                      | `migrated` | Rust `handle_backend_request` revalidates the browser cookie or non-app-session Bearer token, requires root `manage_workspace_roles`, reads and writes `private.timezones` with private-schema headers, normalizes legacy create/update payloads, omits missing/null create IDs for database UUID defaults, and preserves legacy success/error bodies.                                                                                                                  |
| `GET /api/v1/infrastructure/user-status-changes`                                                                                                                                           | `migrated` | Rust `handle_backend_request` forwards the caller's Supabase token to PostgREST for `workspace_user_status_changes`, preserving RLS, required `ws_id`, parseInt-style range headers, exact count, and the legacy data/count body.                                                                                                                                                                                                                                       |
| `GET /api/v1/infrastructure/users`                                                                                                                                                         | `migrated` | Rust `handle_backend_request` forwards the caller's Supabase token to PostgREST for `workspace_users`, preserving RLS, required `ws_id`, parseInt-style range headers, exact count, and the legacy data/count body.                                                                                                                                                                                                                                                     |
| `GET /api/v1/infrastructure/classes`, `/product-categories`, and `/score-names`                                                                                                            | `migrated` | Rust `handle_backend_request` uses the shared caller-token paginated export helper for `workspace_user_groups`, `product_categories`, and `user_group_metrics`, preserving RLS, exact count, and the legacy data/count bodies.                                                                                                                                                                                                                                          |
| `GET /api/v1/infrastructure/lessons` and `/packages`                                                                                                                                       | `migrated` | Rust `handle_backend_request` preserves the no-auth private-schema lesson export and revalidates package callers before requiring `view_inventory`, while keeping exact-count pagination and the legacy data/count bodies.                                                                                                                                                                                                                                              |
| `GET /api/v1/infrastructure/product-prices`, `/product-units`, and `/warehouses`                                                                                                           | `migrated` | Rust `handle_backend_request` accepts inventory app-session credentials or normal Supabase browser/Bearer credentials, requires inventory catalog/setup read permissions, and reads private inventory setup rows through the service-role Supabase REST adapter with exact-count pagination. Product prices scope through the `workspace_products` inner workspace filter.                                                                                              |
| `GET` / `POST` `/api/v1/infrastructure/ai/whitelist/domains` and `/emails`                                                                                                                 | `migrated` | Rust `handle_backend_request` revalidates the Supabase browser session or non-app-session Bearer token, requires a `@tuturuuu.com` operator email, reads and inserts private whitelist rows through the service-role private-schema REST adapter, and preserves `page`/`pageSize`/`q`, `created_at.desc` ordering, exact-count pagination, Zod-style create validation messages, `enabled` defaults, 201 create wrappers, 403 denial bodies, and plain-text 500 bodies. |
| `PUT` / `DELETE` `/api/v1/infrastructure/ai/whitelist/:email` and `/domain/:domain`                                                                                                        | `migrated` | Rust `handle_backend_request` revalidates the same operator boundary as the list routes, decodes the path segment, patches/deletes matching private whitelist rows through the service-role private-schema REST adapter, applies legacy `Boolean(enabled)` update truthiness, and preserves the legacy success/error bodies.                                                                                                                                            |
| `GET /api/v1/infrastructure/post-email-queue`                                                                                                                                              | `migrated` | Rust `handle_backend_request` revalidates the Supabase browser session or non-app-session Bearer token, requires root workspace membership, reads `post_email_queue` through the service-role Supabase REST adapter, preserves the legacy summary/workspace/recent-batch aggregation payload, and keeps workspace/batch breakdown failures non-fatal.                                                                                                                   |
| `GET /api/v1/infrastructure/bills`, `/roles`, and `/transaction-categories`                                                                                                                | `migrated` | Rust `handle_backend_request` uses the shared caller-token paginated export helper for `finance_invoices`, `workspace_user_groups`, and `transaction_categories`, preserving RLS, exact count, and the legacy data/count bodies.                                                                                                                                                                                                                                        |
| `GET /api/v1/infrastructure/wallet-transactions`                                                                                                                                           | `migrated` | Rust `handle_backend_request` forwards the caller's Supabase token to `get_wallet_transactions_with_permissions`, preserving the legacy RPC payload, raw rows, and first-row `total_count` envelope.                                                                                                                                                                                                                                                                    |
| `GET /api/v1/infrastructure/abuse-intelligence`                                                                                                                                            | `migrated` | Rust `handle_backend_request` validates the Supabase browser session or Bearer token, requires root `view_infrastructure`, reads caller-scoped abuse reputation subjects, activity signals, and challenges, reads active overrides with service-role auth, and returns the legacy summary plus `topRiskySubjects` payload while leaving POST legacy-owned.                                                                                                              |
| `GET /api/v1/infrastructure/abuse-events`                                                                                                                                                  | `migrated` | Rust `handle_backend_request` validates the Supabase browser session or Bearer token, checks root workspace membership with the caller token, reads `abuse_events` with legacy filters and page/pageSize pagination, and returns the legacy pagination envelope.                                                                                                                                                                                                        |
| `GET /api/v1/infrastructure/blocked-ips`                                                                                                                                                   | `migrated` | Rust `handle_backend_request` validates the Supabase browser session or Bearer token, checks root workspace membership with the caller token, reads `blocked_ips` with legacy filters and page/pageSize pagination, and leaves POST/DELETE legacy-owned.                                                                                                                                                                                                                |
| `GET /api/v1/infrastructure/suspensions`                                                                                                                                                   | `migrated` | Rust `handle_backend_request` validates the Supabase browser session or Bearer token, requires root `manage_workspace_roles`, reads active `user_suspensions` rows through the service-role Supabase REST adapter, and leaves POST/detail DELETE legacy-owned.                                                                                                                                                                                                          |
| `GET` / `POST` `/api/v1/infrastructure/email-blacklist` and `GET` / `PUT` / `DELETE` `/api/v1/infrastructure/email-blacklist/:entryId`                                                     | `migrated` | Rust `handle_backend_request` validates the Supabase browser session or Bearer token, checks root workspace membership with the caller token, returns the legacy ordered collection/detail rows, writes with caller-token Supabase REST, preserves POST/PUT Zod-style validation bodies, maps duplicate creates to `409`, and preserves detail update/delete prefetch/not-found behavior.                                                                               |
| `GET /api/v1/infrastructure/bill-coupons`, `/bill-packages`, `/class-attendance`, `/class-members`, `/class-packages`, `/class-scores`, `/package-stock-changes`, and `/student-feedbacks` | `migrated` | Rust `handle_backend_request` uses the shared caller-token paginated export helper with route-specific embedded select strings and related-table workspace filters while preserving exact count and the legacy data/count bodies.                                                                                                                                                                                                                                       |
| `GET /api/v1/infrastructure/user-monthly-reports` and `/user-monthly-report-logs`                                                                                                          | `migrated` | Rust `handle_backend_request` requires `manage_external_migrations`, resolves workspace aliases through the shared permission helper, and reads the private monthly report views through private-schema Supabase REST with exact-count pagination.                                                                                                                                                                                                                      |
| `GET /api/v1/workspaces/:wsId/crawlers/status`                                                                                                                                             | `migrated` | Rust `handle_backend_request` preserves the legacy exact-URL crawler status lookup, raw Supabase row payloads, missing-URL validation, and `crawledUrl: null` fallback when no row exists.                                                                                                                                                                                                                                                                              |
| `GET /api/v1/workspaces/:wsId/course-modules` and `GET /api/v1/workspaces/:wsId/quiz-sets/:setId/linked-modules`                                                                           | `migrated` | Rust `handle_backend_request` resolves education workspace access, requires `ENABLE_EDUCATION`, reads service-role course-module rows with exact-count pagination, and verifies linked quiz sets belong to the resolved workspace before listing linked modules.                                                                                                                                                                                                        |
| `PATCH /api/v1/user/profile`                                                                                                                                                               | `migrated` | Rust `handle_backend_request` validates browser Supabase auth, validates legacy profile fields, and updates only the authenticated user's `users` row through the server-owned Supabase REST adapter.                                                                                                                                                                                                                                                                   |
| `GET` / `PATCH` `/api/v1/users/me/default-workspace`                                                                                                                                       | `migrated` | Rust `handle_backend_request` resolves the authenticated user's default workspace with the legacy personal-workspace/null fallback and updates `default_workspace_id` after caller-token membership validation.                                                                                                                                                                                                                                                         |
| `GET` / `PATCH` `/api/v1/users/calendar-settings`                                                                                                                                          | `migrated` | Rust `handle_backend_request` accepts calendar app-session tokens or revalidated browser Supabase sessions, reads and updates the authenticated user's calendar settings in `user_private_details`, defaults missing values to `auto`, and preserves legacy patch validation/cache behavior.                                                                                                                                                                            |
| `GET /api/v1/users/me/identities`                                                                                                                                                          | `migrated` | Rust `handle_backend_request` revalidates browser Supabase auth, reads the raw Supabase Auth user JSON, returns the legacy linked identities list plus `canUnlink`, and preserves the private cache directive.                                                                                                                                                                                                                                                          |
| `PATCH /api/v1/users/me/full-name`                                                                                                                                                         | `migrated` | Rust `handle_backend_request` validates browser Supabase auth, validates the required trimmed `full_name`, and upserts `user_private_details` for the authenticated user with the caller token.                                                                                                                                                                                                                                                                         |
| `GET /api/cron/discord/daily-report`                                                                                                                                                       | `migrated` | Rust `handle_backend_request` proxies to `DISCORD_APP_DEPLOYMENT_URL/daily-report` with cron bearer auth, upstream status/body passthrough, invalid-JSON fallback, OpenAPI coverage, and native/Worker outbound support.                                                                                                                                                                                                                                                |
| `GET /api/cron/discord/wol/daily/remind`                                                                                                                                                   | `migrated` | Rust `handle_backend_request` reuses the same proxy contract for `DISCORD_APP_DEPLOYMENT_URL/wol-reminder` with route tests and Cloudflare Worker config requirements for the cron secret and Discord app deployment URL.                                                                                                                                                                                                                                               |

Frontend pages now terminal:

| Legacy route                                                                                                   | Status     | Evidence                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| -------------------------------------------------------------------------------------------------------------- | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `/:locale/add-account`                                                                                         | `migrated` | Dynamic no-store TanStack Start route `/$locale/add-account` is registered in `routeTree.gen.ts`, preserves the legacy account-switcher add-account handoff, carries `returnUrl` through TanStack Router search validation, renders localized loading/success/error states, and persists the current session through a TanStack Query mutation backed by `@tuturuuu/internal-api` auth helpers instead of Next navigation or raw protected API calls.                                                                                                                                                                                                                                                                                                                                    |
| `/:locale/:wsId/habits`                                                                                        | `migrated` | TanStack Start route `/$locale/$wsId/habits` is registered in `routeTree.gen.ts`, gates anonymous users through `requireCurrentUser`, resolves the workspace, checks the Rust-owned `/api/v1/workspaces/:wsId/habits/access` feature probe, and renders the shared `HabitsClientPage`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `/:locale/:wsId/posts`                                                                                         | `migrated` | TanStack Start route `/$locale/$wsId/posts` is registered in `routeTree.gen.ts`, gates anonymous users through `requireCurrentUser`, resolves the workspace, preserves pass-through URL search state for the shared posts client, and uses internal-api facades including the Rust-owned posts permission probe.                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `/:locale/:wsId/crawlers`                                                                                      | `migrated` | TanStack Start route `/$locale/$wsId/crawlers` is registered in `routeTree.gen.ts`, gates anonymous users through `requireCurrentUser`, resolves the workspace, preserves legacy `ai_lab` gating, carries URL page/pageSize/domain/search state through TanStack Router, and renders a read-only crawled URL table plus uncrawled/domain stats through Rust-owned crawler backend facades.                                                                                                                                                                                                                                                                                                                                                                                               |
| `/:locale/:wsId/crawlers/uncrawled`                                                                            | `migrated` | TanStack Start route `/$locale/$wsId/crawlers/uncrawled` is registered in `routeTree.gen.ts`, uses the same authenticated workspace and `ai_lab` gate, carries URL filters through TanStack Router, and renders grouped read-only uncrawled URLs through the Rust-owned crawler backend facades while leaving crawl-trigger mutations out of scope.                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `/:locale/:wsId/pipelines`                                                                                     | `migrated` | Dynamic no-store TanStack Start route `/$locale/$wsId/pipelines` is registered in `routeTree.gen.ts`, gates anonymous users through `requireCurrentUser`, resolves the workspace, preserves legacy `ai_lab` gating, carries URL page/pageSize/domain/search state through TanStack Router, and renders the crawler-backed read-only list through Rust-owned crawler backend facades. Legacy crawler create/update actions remain separately tracked.                                                                                                                                                                                                                                                                                                                                     |
| `/:locale/:wsId/queues`                                                                                        | `migrated` | Dynamic no-store TanStack Start route `/$locale/$wsId/queues` is registered in `routeTree.gen.ts`, gates anonymous users through `requireCurrentUser`, resolves the workspace, preserves legacy `ai_lab` gating, carries URL page/pageSize/domain/search state through TanStack Router, and renders the crawler-backed read-only list through Rust-owned crawler backend facades. Legacy crawler create/update actions remain separately tracked.                                                                                                                                                                                                                                                                                                                                        |
| `/:locale/:wsId/cron` layout                                                                                   | `migrated` | Dynamic no-store TanStack Start route `/$locale/$wsId/cron` preserves the legacy cron route-specific layout gate by requiring current-user auth, resolving the workspace, enforcing `ai_lab`, and rendering exact-match Overview, Cron jobs, and Executions tabs. Child cron pages stay separately tracked until their tables and mutations move behind internal-api or Rust facades.                                                                                                                                                                                                                                                                                                                                                                                                    |
| `/:locale/:wsId/cron/jobs`                                                                                     | `migrated` | Dynamic no-store TanStack Start route `/$locale/$wsId/cron/jobs` is registered in `routeTree.gen.ts`, duplicates fail-closed current-user/workspace/`ai_lab` gates before loading protected data, carries `q`, `page`, and `pageSize` through TanStack Router search state, and renders the cron job list through a typed internal-api facade instead of direct Supabase reads or raw browser `/api` fetches. Create, edit, delete, next-run calculation, and job detail navigation remain separately tracked until dataset readers, mutation flows, and `/:locale/:wsId/cron/jobs/:jobId` move behind internal-api or Rust facades.                                                                                                                                                     |
| `/:locale/:wsId/documents`                                                                                     | `migrated` | Dynamic no-store TanStack Start route `/$locale/$wsId/documents` is registered in `routeTree.gen.ts`, gates anonymous users through `requireCurrentUser`, resolves the workspace, preserves the legacy `manage_documents` permission gate, and renders the workspace document list/create/delete flow through TanStack Query plus the typed documents internal-api facade. Document editor mutations and workspace document APIs remain separately tracked.                                                                                                                                                                                                                                                                                                                              |
| `/:locale/:wsId/documents/:documentId`                                                                         | `migrated` | Dynamic no-store TanStack Start route `/$locale/$wsId/documents/$documentId` is registered in `routeTree.gen.ts`, gates anonymous users through `requireCurrentUser`, resolves the workspace, preserves the legacy `manage_documents` permission gate, loads the protected document row through the typed documents internal-api facade with forwarded request auth, and renders document metadata plus a read-only rich-text preview. Document edit/share/delete/autosave behavior and workspace document APIs remain separately tracked.                                                                                                                                                                                                                                               |
| `/:locale/:wsId/infrastructure/abuse-events`                                                                   | `migrated` | TanStack Start route `/$locale/$wsId/infrastructure/abuse-events` is registered in `routeTree.gen.ts`, gates anonymous users through `requireCurrentUser`, resolves the workspace, preserves `view_infrastructure` not-found gating, carries URL search filters through TanStack Router, and loads rows through the Rust-owned abuse-events backend facade.                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `/:locale/:wsId/infrastructure/abuse-intelligence`                                                             | `migrated` | Dynamic no-store TanStack Start route `/$locale/$wsId/infrastructure/abuse-intelligence` is registered in `routeTree.gen.ts`, gates anonymous users through `requireCurrentUser`, resolves the workspace, preserves the legacy root-workspace redirect boundary, requires root `view_infrastructure`, and renders shared TanStack Query/internal-api-backed reputation subject, signal, and trust override controls. Abuse Intelligence mutation APIs remain separately tracked.                                                                                                                                                                                                                                                                                                         |
| `/:locale/:wsId/infrastructure/app-coordination`                                                               | `migrated` | Dynamic no-store TanStack Start route `/$locale/$wsId/infrastructure/app-coordination` is registered in `routeTree.gen.ts`, gates anonymous users through `requireCurrentUser`, resolves the workspace, preserves the legacy root-workspace redirect boundary, accepts root `manage_workspace_secrets` or `manage_workspace_roles`, and renders shared TanStack Query/internal-api-backed app-session policy controls. App Coordination APIs remain separately tracked.                                                                                                                                                                                                                                                                                                                  |
| `/:locale/:wsId/infrastructure/blocked-ips`                                                                    | `migrated` | Dynamic no-store TanStack Start route `/$locale/$wsId/infrastructure/blocked-ips` is registered in `routeTree.gen.ts`, gates anonymous users through `requireCurrentUser`, resolves the workspace, preserves root and workspace `view_infrastructure` not-found gating, carries URL search/status/pagination filters through TanStack Router, and renders localized block/unblock controls through typed internal-api facades instead of direct Supabase reads or raw client `/api` fetches. Blocked IP APIs remain separately tracked.                                                                                                                                                                                                                                                  |
| `/:locale/:wsId/infrastructure/realtime`                                                                       | `migrated` | Dynamic no-store TanStack Start route `/$locale/$wsId/infrastructure/realtime` is registered in `routeTree.gen.ts`, gates anonymous users through `requireCurrentUser`, resolves the workspace alias, preserves root and workspace `view_infrastructure` not-found gating, and renders the realtime analytics TanStack Query surface through createServerFn wrappers plus typed internal-api facades instead of raw protected `/api` fetches. Realtime analytics API artifacts remain separately tracked backend migration work.                                                                                                                                                                                                                                                         |
| `/:locale/:wsId/infrastructure/external-apps`                                                                  | `migrated` | Dynamic no-store TanStack Start route `/$locale/$wsId/infrastructure/external-apps` is registered in `routeTree.gen.ts`, gates anonymous users through `requireCurrentUser`, resolves the workspace, preserves the legacy root-workspace redirect boundary, accepts root `manage_workspace_secrets` or `manage_workspace_roles`, and renders shared TanStack Query/internal-api-backed external app registration and secret rotation controls. External Apps APIs remain separately tracked.                                                                                                                                                                                                                                                                                             |
| `/:locale/:wsId/infrastructure/github-bot`                                                                     | `migrated` | Dynamic no-store TanStack Start route `/$locale/$wsId/infrastructure/github-bot` is registered in `routeTree.gen.ts`, gates anonymous users through `requireCurrentUser`, resolves the workspace, preserves the legacy root-workspace redirect boundary, requires root `manage_workspace_secrets`, loads the initial GitHub Bot state through forwarded internal-api auth, and renders localized TanStack Query/internal-api-backed configuration, validation, watcher client, and audit controls. GitHub Bot APIs remain separately tracked.                                                                                                                                                                                                                                            |
| `/:locale/:wsId/infrastructure/ai/whitelist/{domains,emails}`                                                  | `migrated` | TanStack Start routes `/$locale/$wsId/infrastructure/ai/whitelist/domains` and `/emails` are registered in `routeTree.gen.ts`, gate anonymous users through `requireCurrentUser`, preserve the `@tuturuuu.com` operator not-found boundary plus root `view_infrastructure` gating, carry URL pagination/search through TanStack Router, and load/mutate rows through the Rust-owned AI whitelist internal-api facade.                                                                                                                                                                                                                                                                                                                                                                    |
| `/:locale/:wsId/infrastructure/mobile-versions`                                                                | `migrated` | TanStack Start route `/$locale/$wsId/infrastructure/mobile-versions` is registered in `routeTree.gen.ts`, gates anonymous users through `requireCurrentUser`, preserves the legacy root-workspace redirect boundary, requires root `manage_workspace_roles`, loads policies through the Rust-owned mobile-versions internal-api facade, and saves updates through TanStack Query mutations.                                                                                                                                                                                                                                                                                                                                                                                              |
| `/:locale/:wsId/infrastructure/mobile-deployment`                                                              | `migrated` | Dynamic no-store TanStack Start route `/$locale/$wsId/infrastructure/mobile-deployment` is registered in `routeTree.gen.ts`, gates anonymous users through `requireCurrentUser`, resolves the workspace, preserves the legacy root-workspace redirect boundary, requires root `manage_mobile_deployment_vault`, loads the initial vault state through forwarded internal-api auth, and renders localized secret, file, activation, rollback, and CI token controls through TanStack Query/internal-api facades. Mobile Deployment APIs remain separately tracked.                                                                                                                                                                                                                        |
| `/:locale/:wsId/infrastructure/monitoring/stress-tests`                                                        | `migrated` | Dynamic no-store TanStack Start route `/$locale/$wsId/infrastructure/monitoring/stress-tests` is registered under the TanStack monitoring layout in `routeTree.gen.ts`, gates anonymous users through `requireCurrentUser`, resolves the workspace, preserves the legacy root-workspace redirect boundary and root `view_infrastructure` not-found gate, renders the localized monitoring hero/section navigation, and uses TanStack Query/internal-api facades for stress-test snapshots, queue, abort, run detail polling, metrics, and history. Stress-test APIs remain separately tracked.                                                                                                                                                                                           |
| `/:locale/:wsId/infrastructure/monitoring/cron`                                                                | `migrated` | Dynamic no-store TanStack Start route `/$locale/$wsId/infrastructure/monitoring/cron` is registered under the TanStack monitoring layout in `routeTree.gen.ts`, relies on the parent current-user, root-workspace redirect, and root `view_infrastructure` gates, and uses TanStack Query/internal-api facades for cron snapshots, execution archives, manual run queueing, control toggles, and console-log detail. Cron APIs remain separately tracked.                                                                                                                                                                                                                                                                                                                                |
| `/:locale/:wsId/infrastructure/monitoring/requests`                                                            | `migrated` | Dynamic no-store TanStack Start route `/$locale/$wsId/infrastructure/monitoring/requests` is registered under the TanStack monitoring layout in `routeTree.gen.ts`, relies on the parent current-user, root-workspace redirect, and root `view_infrastructure` gates, and uses TanStack Query/internal-api facades for retained request archives, status/route/render/traffic filters, pagination, deployment context, and request inspection. Request archive APIs remain separately tracked.                                                                                                                                                                                                                                                                                           |
| `/:locale/:wsId/infrastructure/monitoring/watcher-logs`                                                        | `migrated` | Dynamic no-store TanStack Start route `/$locale/$wsId/infrastructure/monitoring/watcher-logs` is registered under the TanStack monitoring layout in `routeTree.gen.ts`, relies on the parent current-user, root-workspace redirect, and root `view_infrastructure` gates, and uses TanStack Query/internal-api facades for watcher snapshots, deployment scope/level/rollout status filters, pagination, commit context, and log detail inspection. Watcher-log APIs remain separately tracked.                                                                                                                                                                                                                                                                                          |
| `/:locale/:wsId/infrastructure/monitoring/rollouts`                                                            | `migrated` | Dynamic no-store TanStack Start route `/$locale/$wsId/infrastructure/monitoring/rollouts` is registered under the TanStack monitoring layout in `routeTree.gen.ts`, relies on the parent current-user, root-workspace redirect, and root `view_infrastructure` gates, and uses TanStack Query/internal-api facades for rollout summaries, deployment stage panels, standby sync controls, deployment pin controls, watcher event streams, and deployment history. Rollout mutation APIs remain separately tracked.                                                                                                                                                                                                                                                                       |
| `/:locale/:wsId/infrastructure/monitoring{,/analytics,/deployments,/logs,/observability,/projects,/resources}` | `migrated` | Dynamic no-store TanStack Start routes are registered under the TanStack monitoring layout in `routeTree.gen.ts`, rely on the parent current-user, root-workspace redirect, and root `view_infrastructure` gates, and render the observability overview, analytics, deployment history, grouped logs, health signals, project controls, and resource inventory through TanStack Query/internal-api facades. Project deletion and deeper observability API ownership remain separately tracked follow-ups.                                                                                                                                                                                                                                                                                |
| `/:locale/:wsId/infrastructure/timezones`                                                                      | `migrated` | TanStack Start route `/$locale/$wsId/infrastructure/timezones` is registered in `routeTree.gen.ts`, gates anonymous users through `requireCurrentUser`, preserves the legacy root-workspace redirect boundary, requires root `manage_workspace_roles`, overlays Rust-owned persisted timezone rows onto the bundled timezone catalog, and performs create/update/delete sync mutations through the backend timezones facade.                                                                                                                                                                                                                                                                                                                                                             |
| `/:locale/:wsId/infrastructure/holidays`                                                                       | `migrated` | TanStack Start route `/$locale/$wsId/infrastructure/holidays` is registered in `routeTree.gen.ts`, gates anonymous users through `requireCurrentUser`, preserves the legacy root-workspace redirect boundary, requires root `manage_workspace_roles`, carries the year filter through TanStack Router search state, and performs list/create/update/delete/bulk-import work through the Rust-owned holidays backend facade.                                                                                                                                                                                                                                                                                                                                                              |
| `/:locale/:wsId/infrastructure/email-blacklist`                                                                | `migrated` | TanStack Start route `/$locale/$wsId/infrastructure/email-blacklist` is registered in `routeTree.gen.ts`, gates anonymous users through `requireCurrentUser`, resolves the workspace, preserves `view_infrastructure` not-found gating, carries URL search/type/pagination filters through TanStack Router, and loads/mutates rows through the Rust-owned email blacklist backend facade.                                                                                                                                                                                                                                                                                                                                                                                                |
| `/:locale/:wsId/infrastructure/email-templates`                                                                | `migrated` | Dynamic no-store TanStack Start route `/$locale/$wsId/infrastructure/email-templates` is registered in `routeTree.gen.ts`, gates anonymous users through `requireCurrentUser`, resolves the workspace, preserves root and workspace `view_infrastructure` not-found gating, and renders the localized React Email template selector, property editor, server-function preview renderer, dark-mode simulation, and iframe HTML preview without raw `/api` fetches or Supabase reads.                                                                                                                                                                                                                                                                                                      |
| `/:locale/:wsId/infrastructure/rate-limits`                                                                    | `migrated` | Dynamic no-store TanStack Start route `/$locale/$wsId/infrastructure/rate-limits` is registered in `routeTree.gen.ts`, gates anonymous users through `requireCurrentUser`, resolves the workspace, preserves the legacy root-workspace redirect boundary, requires root `view_infrastructure`, forwards `manage_workspace_roles` as can-manage state, and renders the shared TanStack Query/internal-api-backed protection toggles, rate-limit rule, live-usage, and workspace-secret controls. Rate-limit APIs remain separately tracked.                                                                                                                                                                                                                                               |
| `/:locale/:wsId/infrastructure/post-email-queue`                                                               | `migrated` | TanStack Start route `/$locale/$wsId/infrastructure/post-email-queue` is registered in `routeTree.gen.ts`, gates anonymous users through `requireCurrentUser`, resolves the workspace, preserves `view_infrastructure` not-found gating, and renders the read-only queue summary, workspace breakdown, and recent batches through the Rust-owned post-email-queue backend facade while leaving the legacy cron trigger out of scope.                                                                                                                                                                                                                                                                                                                                                     |
| `/:locale/:wsId/education`                                                                                     | `migrated` | Dynamic no-store TanStack Start route `/$locale/$wsId/education` is registered in `routeTree.gen.ts`, gates anonymous users through `requireCurrentUser`, resolves the workspace, and renders the legacy education overview shell with forwarded-auth internal-api counts for courses, flashcards, and quizzes. Education list APIs remain separately tracked.                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `/:locale/:wsId/education/library/flashcards`                                                                  | `migrated` | Dynamic no-store TanStack Start route `/$locale/$wsId/education/library/flashcards` is registered in `routeTree.gen.ts`, gates anonymous users through `requireCurrentUser`, resolves the workspace, carries `q`/`page`/`pageSize` search state through TanStack Router, and renders the legacy flashcard library table through forwarded internal-api auth plus shared TanStack Query-backed create/update/delete components. Flashcard API ownership remains separately tracked.                                                                                                                                                                                                                                                                                                       |
| `/:locale/:wsId/education/library/quizzes`                                                                     | `migrated` | Dynamic no-store TanStack Start route `/$locale/$wsId/education/library/quizzes` is registered in `routeTree.gen.ts`, gates anonymous users through `requireCurrentUser`, resolves the workspace, carries `q`/`page`/`pageSize` search state through TanStack Router with the legacy 10-row default, and renders the legacy quiz library table through forwarded internal-api auth plus shared TanStack Query-backed create/update/delete components and AI explanation generation. Quiz API ownership remains separately tracked.                                                                                                                                                                                                                                                       |
| `/:locale/:wsId/education/library/quiz-sets`                                                                   | `migrated` | Dynamic no-store TanStack Start route `/$locale/$wsId/education/library/quiz-sets` is registered in `routeTree.gen.ts`, gates anonymous users through `requireCurrentUser`, resolves the workspace, carries `q`/`page`/`pageSize` search state through TanStack Router with the legacy 10-row default, and renders the legacy quiz-set library table through forwarded internal-api auth plus linked course/module label hydration and shared TanStack Query-backed create/update/delete components. Quiz-set and linked-module API ownership remains separately tracked.                                                                                                                                                                                                                |
| `/:locale/:wsId/education/attempts`                                                                            | `migrated` | Dynamic no-store TanStack Start route `/$locale/$wsId/education/attempts` is registered in `routeTree.gen.ts`, gates anonymous users through `requireCurrentUser`, resolves the workspace, preserves the legacy `view_user_groups_reports` not-found gate, carries filter/sort/page/pageSize search state through TanStack Router, and renders the legacy attempts review table through forwarded internal-api auth with learner and quiz-set metadata. Attempts APIs remain separately tracked.                                                                                                                                                                                                                                                                                         |
| `/:locale/:wsId/education/attempts/:attemptId`                                                                 | `migrated` | Dynamic no-store TanStack Start route `/$locale/$wsId/education/attempts/$attemptId` is registered in `routeTree.gen.ts`, gates anonymous users through `requireCurrentUser`, resolves the workspace, preserves the `view_user_groups_reports` not-found gate used by the list/API, and renders the legacy attempt detail header, learner card, KPI strip, and per-question answer correctness cards through forwarded internal-api auth. Attempts APIs remain separately tracked.                                                                                                                                                                                                                                                                                                       |
| `/:locale/:wsId/education/courses`                                                                             | `migrated` | Dynamic no-store TanStack Start route `/$locale/$wsId/education/courses` is registered in `routeTree.gen.ts`, gates anonymous users through `requireCurrentUser`, resolves the workspace, carries `q`/`page`/`pageSize`/`view` search state through TanStack Router, and renders the legacy course card/table page through forwarded internal-api auth plus shared CourseCardView, CoursePagination, CustomDataTable, and internal-api-backed create/edit/delete actions. Course API ownership and course builder remain separately tracked.                                                                                                                                                                                                                                             |
| `/:locale/:wsId/education/quiz-sets/:setId`                                                                    | `migrated` | Dynamic no-store TanStack Start route `/$locale/$wsId/education/quiz-sets/$setId` is registered in `routeTree.gen.ts`, gates anonymous users through `requireCurrentUser`, resolves the workspace, carries `q`/`page`/`pageSize` search state through TanStack Router with the legacy 10-row default, and renders the legacy quiz-set quiz table through forwarded internal-api auth plus shared TanStack Query-backed create/update/delete components and AI explanation generation. The exact `/education/quiz-sets` redirect is an index route so detail children are reachable; the quiz-set detail layout and quiz APIs remain separately tracked.                                                                                                                                  |
| `/:locale/:wsId/ai-chat` layout                                                                                | `migrated` | Dynamic no-store TanStack Start parent route `/$locale/$wsId/ai-chat` wraps migrated AI chat child routes with fail-closed current-user auth, workspace resolution, the legacy `ai_chat` permission redirect, and localized New Chat, Chatbots, and My Chatbots tabs. The exact `/ai-chat` leaf deliberately remains not-found in TanStack until the legacy chat page is migrated; parent dashboard/session ownership also remains separately tracked.                                                                                                                                                                                                                                                                                                                                   |
| `/:locale/:wsId/ai-chat/my-chatbots`                                                                           | `migrated` | Dynamic no-store TanStack Start route `/$locale/$wsId/ai-chat/my-chatbots` is registered in `routeTree.gen.ts`, gates anonymous users through `requireCurrentUser`, resolves the workspace, preserves the legacy `ai_chat` permission gate, carries `q`/`page`/`pageSize` search state through TanStack Router, and renders the legacy My Chatbots table through forwarded internal-api auth plus internal-api-backed row deletion. Group-tag API ownership remains separately tracked.                                                                                                                                                                                                                                                                                                  |
| `/:locale/:wsId/users/approvals`                                                                               | `migrated` | Dynamic no-store TanStack Start route `/$locale/$wsId/users/approvals` is registered in `routeTree.gen.ts`, gates anonymous users through `requireCurrentUser`, resolves the workspace, preserves the personal-workspace notice and approve reports/posts not-found gating, carries `status`/`page`/`limit`/`groupId`/`userId`/`creatorId` filter state through TanStack Router, and renders the shared approvals tabs through TanStack Query-backed reads and internal-api-backed approve/reject/unapprove mutations. Approval APIs remain separately tracked.                                                                                                                                                                                                                          |
| `/:locale/:wsId/users/group-tags`                                                                              | `migrated` | Dynamic no-store TanStack Start route `/$locale/$wsId/users/group-tags` is registered in `routeTree.gen.ts`, gates anonymous users through `requireCurrentUser`, resolves the workspace, carries `q`/`page`/`pageSize` search state through TanStack Router, and renders the legacy group-tag table through forwarded internal-api auth plus shared create/update/delete components and locale-prefixed detail hrefs. Group-tag API ownership remains separately tracked.                                                                                                                                                                                                                                                                                                                |
| `/:locale/:wsId/users/group-tags/:tagId`                                                                       | `migrated` | Dynamic no-store TanStack Start route `/$locale/$wsId/users/group-tags/$tagId` is registered in `routeTree.gen.ts`, gates anonymous users through `requireCurrentUser`, resolves the workspace, carries `q`/`page`/`pageSize` search state through TanStack Router, and renders the legacy linked user-group table through forwarded internal-api auth plus TanStack Query-backed linked-group add/remove components. Group-tag API ownership remains separately tracked.                                                                                                                                                                                                                                                                                                                |
| `/:locale/:wsId/users/topic-announcements/announcements`                                                       | `migrated` | Dynamic no-store TanStack Start route `/$locale/$wsId/users/topic-announcements/announcements` is registered in `routeTree.gen.ts`, gates anonymous users through `requireCurrentUser`, resolves the workspace, preserves personal-workspace not-found parity, enforces `ENABLE_TOPIC_ANNOUNCEMENTS` and `manage_users`, carries `status`/`q`/`page` search state through TanStack Router, and renders the legacy announcements composer/table with send-permission-aware create/send/schedule flows, attachment upload, live email preview, save-as-template, and typed topic-announcement internal-api contracts.                                                                                                                                                                      |
| `/:locale/:wsId/users/topic-announcements/templates`                                                           | `migrated` | Dynamic no-store TanStack Start route `/$locale/$wsId/users/topic-announcements/templates` is registered in `routeTree.gen.ts`, gates anonymous users through `requireCurrentUser`, resolves the workspace, preserves personal-workspace not-found parity, enforces `ENABLE_TOPIC_ANNOUNCEMENTS` and `manage_users`, and renders the legacy templates CRUD page through TanStack Query plus typed topic-announcement and user-group internal-api facades. The exact parent redirect now only fires on `/topic-announcements`, so migrated child tabs can render.                                                                                                                                                                                                                         |
| `/:locale/:wsId/users/topic-announcements/contacts`                                                            | `migrated` | Dynamic no-store TanStack Start route `/$locale/$wsId/users/topic-announcements/contacts` is registered in `routeTree.gen.ts`, gates anonymous users through `requireCurrentUser`, resolves the workspace, preserves personal-workspace not-found parity, enforces `ENABLE_TOPIC_ANNOUNCEMENTS` and `manage_users`, and renders the legacy contacts table, create dialog, linked workspace-user selector, delete confirmation, and verification request action through TanStack Query plus typed topic-announcement and workspace-user internal-api facades. Verification controls stay hidden unless the caller has `send_user_group_post_emails`.                                                                                                                                      |
| `/:locale/:wsId/users/topic-announcements/delivery`                                                            | `migrated` | Dynamic no-store TanStack Start route `/$locale/$wsId/users/topic-announcements/delivery` is registered in `routeTree.gen.ts`, gates anonymous users through `requireCurrentUser`, resolves the workspace, preserves personal-workspace not-found parity, enforces `ENABLE_TOPIC_ANNOUNCEMENTS` and `manage_users`, and renders the legacy read-only delivery history with forwarded-auth `listTopicAnnouncements({ status: "sent" })` loader hydration, calendar timezone normalization, TanStack Query refreshes, sent-only defensive filtering, recipient summary chips, sent-at formatting, and empty-state compose handoff. Delivery does not require `send_user_group_post_emails`.                                                                                                |
| `/:locale/:wsId/users/topic-announcements/import`                                                              | `migrated` | Dynamic no-store TanStack Start route `/$locale/$wsId/users/topic-announcements/import` is registered in `routeTree.gen.ts`, gates anonymous users through `requireCurrentUser`, resolves the workspace, preserves personal-workspace not-found parity, enforces `ENABLE_TOPIC_ANNOUNCEMENTS` and `manage_users`, derives `send_user_group_post_emails` for create-and-send availability, and renders the legacy bulk import flow with client-only XLSX template download/first-sheet parsing, custom CSV/header alias parsing, editable spreadsheet grid, row validation/result summaries, and TanStack Query mutations through `importTopicAnnouncements` plus `sendTopicAnnouncementsBulk`. Rust backend ownership of the import and send-bulk API routes remains separately tracked. |
| `/:locale/:wsId/settings/reports`                                                                              | `migrated` | Dynamic no-store TanStack Start route `/$locale/$wsId/settings/reports` is registered in `routeTree.gen.ts`, gates anonymous users through `requireCurrentUser`, resolves the workspace, preserves `manage_user_report_templates` permission gating, carries `q` search state through TanStack Router, and renders the legacy reports and lead-generation template tables plus previews through TanStack Query server functions and the shared workspace-config internal-api facade.                                                                                                                                                                                                                                                                                                     |
| `/:locale/:wsId/users/groups/calendar`                                                                         | `migrated` | Dynamic no-store TanStack Start route `/$locale/$wsId/users/groups/calendar` is registered in `routeTree.gen.ts`, gates anonymous users through `requireCurrentUser`, resolves the workspace, preserves manage-users/view-user-groups not-found gating, forwards update-user-groups schedule permission state, and renders the shared user-group session calendar through internal-api-backed session reads and mutations. User-group session APIs remain separately tracked.                                                                                                                                                                                                                                                                                                            |
| `/:locale/:wsId/users/groups/:groupId/attendance`                                                              | `migrated` | Dynamic no-store TanStack Start route `/$locale/$wsId/users/groups/$groupId/attendance` is registered in `routeTree.gen.ts`, gates anonymous users through `requireCurrentUser`, resolves the workspace, preserves `check_user_attendance` not-found gating and `update_user_attendance` save gating, hydrates group/session/member/config/attendance data through forwarded internal-api auth, and renders the attendance calendar/session/member cards with TanStack Query-backed reads and saves. User-group attendance/member/config/session APIs remain separately tracked for the backend Rust wave.                                                                                                                                                                               |
| `/:locale/:wsId/users/groups/:groupId/requests`                                                                | `migrated` | Dynamic no-store TanStack Start route `/$locale/$wsId/users/groups/$groupId/requests` is registered in `routeTree.gen.ts`, gates anonymous users through `requireCurrentUser`, resolves the workspace, preserves approve reports/posts not-found gating, and renders the shared group requests tabs through TanStack Query and internal-api-backed approval mutations. Parent group detail page and approval APIs remain separately tracked.                                                                                                                                                                                                                                                                                                                                             |
| `/:locale/:wsId/users/groups/:groupId/schedule`                                                                | `migrated` | Dynamic no-store TanStack Start route `/$locale/$wsId/users/groups/$groupId/schedule` is registered in `routeTree.gen.ts`, gates anonymous users through `requireCurrentUser`, resolves the workspace, loads the target group through forwarded internal-api auth, preserves update-user-groups schedule permission state, and renders the shared end-date dialog and user-group session calendar. Parent group detail page and schedule APIs remain separately tracked.                                                                                                                                                                                                                                                                                                                 |
| `/:locale/:wsId/education/courses/:courseId/modules/:moduleId/content`                                         | `migrated` | Dynamic no-store TanStack Start route `/$locale/$wsId/education/courses/$courseId/modules/$moduleId/content` is registered in `routeTree.gen.ts`, gates anonymous users through `requireCurrentUser`, resolves the workspace, loads the requested module through forwarded internal-api auth, and renders the legacy rich-text module content editor with TanStack Query/internal-api-backed debounced saves. Parent module layout and module API ownership remain separately tracked.                                                                                                                                                                                                                                                                                                   |
| `/:locale/:wsId/education/courses/:courseId/modules/:moduleId/youtube-links`                                   | `migrated` | Dynamic no-store TanStack Start route `/$locale/$wsId/education/courses/$courseId/modules/$moduleId/youtube-links` is registered in `routeTree.gen.ts`, gates anonymous users through `requireCurrentUser`, resolves the workspace, loads the requested module through forwarded internal-api auth, and renders the legacy Youtube Links management page with shared form/delete/embed UI backed by strict internal-api mutations. Parent module layout and module API ownership remain separately tracked.                                                                                                                                                                                                                                                                              |
| `/:locale/:wsId/education/courses/:courseId/modules/:moduleId/quiz-sets`                                       | `migrated` | Dynamic no-store TanStack Start route `/$locale/$wsId/education/courses/$courseId/modules/$moduleId/quiz-sets` is registered in `routeTree.gen.ts`, gates anonymous users through `requireCurrentUser`, resolves the workspace, carries list search state through TanStack Router, and renders the legacy module quiz-set table through forwarded internal-api auth plus shared TanStack Query-backed create/update/delete components. Course-module quiz-set API ownership remains separately tracked.                                                                                                                                                                                                                                                                                  |
| `/:locale/:wsId/education/courses/:courseId/modules/:moduleId/quizzes`                                         | `migrated` | Dynamic no-store TanStack Start route `/$locale/$wsId/education/courses/$courseId/modules/$moduleId/quizzes` is registered in `routeTree.gen.ts`, gates anonymous users through `requireCurrentUser`, resolves the workspace, preserves the legacy `update_user_groups` not-found gate before quiz reads, carries search state through TanStack Router, and renders the shared quiz table through forwarded internal-api auth. Quiz API and AI quiz-generation backend ownership remain separately tracked.                                                                                                                                                                                                                                                                              |
| `/:locale/:wsId/education/courses/:courseId/modules/:moduleId/quizzes/new`                                     | `migrated` | Dynamic no-store TanStack Start route `/$locale/$wsId/education/courses/$courseId/modules/$moduleId/quizzes/new` is registered in `routeTree.gen.ts`, gates anonymous users through `requireCurrentUser`, resolves the workspace, renders the legacy manual quiz creation shell, and submits through the shared TanStack Query/internal-api quiz form before returning to the locale-prefixed module quizzes route. Quiz API ownership and the module quiz list page remain separately tracked.                                                                                                                                                                                                                                                                                          |
| `/:locale/logout`                                                                                              | `migrated` | Dynamic TanStack Start route `/$locale/logout` is registered in `routeTree.gen.ts`, gates anonymous users through `requireCurrentUser`, renders the legacy localized confirmation card with `from` copy, and logs out through the typed internal-api browser-session facade without raw protected app API or Supabase access in TanStack source. The underlying `POST /api/auth/logout` route remains legacy-owned until the auth backend wave.                                                                                                                                                                                                                                                                                                                                          |
| `/:locale/:wsId/infrastructure/ai-agents`                                                                      | `migrated` | Dynamic no-store TanStack Start route `/$locale/$wsId/infrastructure/ai-agents` is registered in `routeTree.gen.ts`, gates anonymous users through `requireCurrentUser`, resolves the workspace, preserves the root-workspace and `manage_workspace_secrets` redirect gates, and renders the legacy AI Agents controls through forwarded internal-api auth plus shared TanStack Query-backed agent, channel, identity, secret, and external-thread actions. AI Agents APIs remain separately tracked for Rust backend ownership.                                                                                                                                                                                                                                                         |
| `/:locale/:wsId/notifications`                                                                                 | `migrated` | Dynamic no-store TanStack Start route `/$locale/$wsId/notifications` is registered in `routeTree.gen.ts`, gates anonymous users through `requireCurrentUser`, resolves the workspace, carries tab/type/scope/priority/page/pageSize search state through TanStack Router, and renders the legacy read-only notifications inbox through forwarded internal-api auth. Mark read/unread, mark all read, delete, invite actions, metadata updates, realtime subscription behavior, and entity action links remain separately tracked follow-ups.                                                                                                                                                                                                                                             |

Frontend migration candidates blocked on auth/data ownership:

| Legacy route                                                                                        | Blocker                                                                                                                                                                                                                                                                                                                                                      | Required design                                                                                                                                                                                                                                                                      |
| --------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `/:locale/meet` and `/:locale/meet-together`                                                        | Public TanStack preview shells are available, but the legacy routes also load authenticated meeting plans and create plans through Next-only Supabase/server-action paths.                                                                                                                                                                                   | Add Rust-owned or TanStack server-function-backed plan list/create APIs, route them through `packages/internal-api`, preserve unauthenticated empty/login-required behavior, and add E2E evidence before adding the `page:/:locale/meet` or `page:/:locale/meet-together` overrides. |
| `/:locale/:wsId/usage`                                                                              | The wrapper is small, but the content fans out into many server-side workspace stats backed by Supabase RPCs, admin reads, storage provider helpers, and per-feature permission checks.                                                                                                                                                                      | Create a Rust-owned workspace usage summary endpoint or a small set of typed server functions that return the same permission-masked stats, then render the dashboard through TanStack Query without direct Supabase reads.                                                          |
| `/:locale/:wsId/ai/spark`, `/:locale/:wsId/mira`, and the canonical `/:locale/:wsId` Mira dashboard | These look compact at the page file level, but their clients call AI object generation, Mira focus/task/calendar/pet APIs, live voice/audio helpers, or assistant multimodal providers that are still Next/API coupled. The standalone `/:locale/:wsId/assistant` route was removed when text and rich live voice were consolidated into the workspace root. | Move each AI surface as a dedicated product lane with typed AI/Mira/assistant facades and focused browser evidence; avoid shell-only migrations that would expose incomplete AI behavior.                                                                                            |
| `/:locale/games/farm`                                                                               | The visible game page is client-only, but the legacy layout gates access through Supabase auth and `isValidTuturuuuEmail(user?.email)` before rendering.                                                                                                                                                                                                     | Add a TanStack server gate that validates the session and email domain through server-owned auth helpers, then port the game UI without exposing it publicly.                                                                                                                        |
| `/:locale` app-shell providers                                                                      | The root route now centralizes locale validation, legacy root head metadata, `html lang`, theme bootstrapping, Query, and tooltip providers, but full legacy layout parity still includes `next-intl`, `NuqsAdapter`, theme-aware toasts, auth-backed version/DB badges, and service-worker runtime behavior.                                                | Finish the provider/runtime contract in TanStack Start, decide which legacy badges and service-worker behaviors are accepted removals versus ports, then add route-level E2E or screenshot evidence before marking remaining localized layout artifacts terminal.                    |
| `/:locale/login`                                                                                    | Login owns OAuth callback forwarding, Supabase session redirects, app-token confirmation, OTP/password/passkey/MFA flows, account switching, Turnstile state, and session hydration.                                                                                                                                                                         | Complete the auth/session contract for TanStack Start and Rust, then port login as a dedicated auth milestone with focused E2E coverage.                                                                                                                                             |

## Frontend Runtime Adapters

TanStack route ports should use the adapter modules under
`apps/tanstack-web/src/lib/platform/` instead of rebuilding Next.js behavior in
each route:

| Adapter         | Owns                                                                                                                           |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `locale.ts`     | `en` / `vi` locale detection, `NEXT_LOCALE`, as-needed prefixes, and `Accept-Language` fallback.                               |
| `head.ts`       | TanStack-compatible metadata, canonical links, alternates, and stylesheet descriptors.                                         |
| `theme.ts`      | The class-based `system` / `light` / `dark` theme boot script used by the root shell.                                          |
| `navigation.ts` | Typed redirect and not-found errors that can be converted to `Response` objects in loaders or server functions.                |
| `session.ts`    | Sanitized auth/session hydration snapshots from request cookies without exposing token values to the browser.                  |
| `query.ts`      | Shared TanStack Query defaults and dehydration behavior for loader-prefetched data.                                            |
| `app-shell.ts`  | Root locale validation, localized document language derivation, and legacy-compatible head descriptors.                        |
| `redirects.ts`  | Legacy-compatible redirect destinations for public, auth, dashboard alias, QR, Mail, CMS, CMS deep-link, and education routes. |

The root TanStack shell already uses the head, locale, theme, and Query
adapters. New route ports should add route-specific metadata through
`createPageHead`, prefetch loader data through the shared QueryClient, and pass
only sanitized session state to client components.

## Data And API Rules

* TanStack loaders and server functions may act as a BFF layer for SSR,
  cookies, headers, and query hydration.
* Product data reads/writes move to Rust-owned endpoints in `apps/backend`.
* Browser/shared UI code calls `packages/internal-api` helpers, not scattered
  raw API paths.
* Protected data stays behind server-owned private/admin access. Do not expose
  private Supabase or protected workspace reads directly to browser code.
* Use TanStack Query for client fetching and mutation. Do not fetch data in
  `useEffect`.
* `bun check` runs `node scripts/check-tanstack-api-access.js` to enforce that
  `apps/tanstack-web/src` does not call relative protected `/api`, `/internal`,
  or `/trpc` paths directly and does not import or create Supabase clients. Run
  the focused command when reviewing a frontend port before the full repo check.

## Backend Crate Structure And The 700-LOC Ceiling

Every source file in the repo — Rust included — must stay well-maintained and
under a hard **700-LOC ceiling** whenever possible (start splitting around
\~400 LOC). The `apps/backend` crate root was decomposed to honor this:

* `src/lib.rs` (\~680 LOC) is now just the module registry (`mod <handler>;`),
  the public types, and `pub(crate) use` re-exports.
* `src/dispatch/` holds `handle_backend_request` plus one
  `dispatch_chunk_NN.rs` per route-table chunk. **New route arms append to a
  `dispatch_chunk_NN.rs`**; when a chunk approaches 700 LOC, add a fresh
  `chunk_NN.rs` and wire it into `dispatch/mod.rs`. Each chunk does
  `use crate::*;` to reach crate-root helpers/types.
* Cohesive helper families live in named submodules, each under 700 LOC:
  `types.rs`, `response.rs`, `runtime.rs`, `migration.rs`, `legacy_routes.rs`,
  `static_routes.rs`, `route_predicates.rs`, `config_env.rs`, `constants.rs`,
  `native.rs`, `worker_runtime.rs`. Each is re-exported from `lib.rs` with
  `pub(crate) use <mod>::*;` so existing call sites resolve unchanged.
* The unit-test suite lives in `src/tests.rs` (`mod tests;`), split by area so
  no test file crosses the ceiling.

To extract a new family: move the items into `src/<mod>.rs`, header it with
`use crate::*;` (plus any external `use serde…`), give moved items `pub(crate)`
visibility, then add `mod <mod>; pub(crate) use <mod>::*;` to `lib.rs`. Keep a
struct and the functions that read its private fields in the same module so
fields only need `pub(crate)` where a cross-module reader (e.g. `tests.rs`)
requires it. Do not bulk-restructure `lib.rs`/`dispatch/` while batches are
appending without a `tmp/agent-coordination/` claim. See `apps/backend/AGENTS.md`
for the full rules.

## No New Debt While The Switch Is Pending

Treat `apps/web`, `apps/backend`, and `apps/tanstack-web` as **one system**. The
migration runs in parallel with normal feature work, so any change that touches
only `apps/web` silently grows the backlog the cutover must clear. All future
work must keep the three surfaces consistent where applicable:

* **New or changed `apps/web` API route (any method).** If `apps/backend` already
  owns that path, port the same behavior change into the Rust handler in the same
  PR (match status codes, body shape, cache headers; migrate GET first and return
  `None` for un-ported methods so they fall through). If it is not owned yet,
  register/refresh the route in
  `apps/tanstack-web/migration/route-overrides.json` and regenerate with
  `bun migration:tanstack:manifest`, so the new surface is tracked as backlog
  instead of invisible debt. Verify ownership with the runtime coverage probe in
  `apps/backend/AGENTS.md` (migrated method = COVER, un-ported = FRESH).
* **New or changed dashboard page/route.** Mirror the manifest registration so
  `apps/tanstack-web` tracking stays accurate, and route shared data access
  through `packages/internal-api` (consumed by both frontends) rather than
  app-local fetchers, so the eventual TanStack port is a move, not a rewrite.
* **Shared data access.** Prefer adding a `packages/internal-api` facade over a
  one-off `apps/web` fetcher; the facade is the seam both the Next.js and
  TanStack frontends call, and it forwards to the Rust backend server-side.
* **Tracking, not blocking.** You do not have to finish the Rust/TanStack port in
  every PR, but you must leave the manifest accurate. A route that is added to
  `apps/web` and not reflected in the manifest is the debt this migration exists
  to avoid. `bun migration:tanstack:check` and the backend coverage probe are the
  guards.

## Security And Test Requirements

Every migrated Rust endpoint needs the same ownership evidence before its
manifest entry can move out of `legacy-next`:

* a `route-overrides.json` entry with a non-empty evidence note that marks the
  legacy artifact as `migrated` or `accepted-removal`
* an OpenAPI path or schema update in `apps/backend/api/openapi.yaml`
* a Rust route dispatcher test covering the success case; full-route ownership
  also needs unsupported method behavior, while method-level ownership needs an
  assertion that still-legacy sibling methods are not claimed by Rust
* a `packages/internal-api` facade when the TanStack app or shared UI needs to
  call the endpoint

Contact/profile backend routes now meet that terminal bar for the app-session
contract used by TanStack contact: `GET /api/v1/users/me/profile`,
`PATCH /api/v1/users/me/profile`, and `POST /api/v1/inquiries` verify
`ttr_app_` app-session JWTs, enforce same-origin mutation checks for cookie
auth, validate request bodies, call Supabase REST through the server-owned Rust
outbound adapter, and have mocked native/Worker persistence tests.
`PATCH /api/v1/users/me/full-name` separately revalidates the browser Supabase
session, validates the required trimmed `full_name`, and upserts the
authenticated user's `user_private_details` row with the caller token.
`GET` / `PATCH` `/api/v1/users/me/default-workspace` separately preserves the
legacy default-workspace read fallback to `null`, supports current-user
app-session reads, and updates the authenticated user's saved default workspace
only after caller-token workspace membership validation.
`PATCH /api/v1/inquiries/:id` separately revalidates the browser Supabase
session, requires a Tuturuuu/XWF email domain, and updates the inquiry admin
flags through the same Rust Supabase REST adapter. Broader Supabase session
revalidation remains part of the dedicated auth migration milestone, so route
notes must stay explicit about the app-session versus browser-session boundary.

`scripts/backend-openapi-migration-contract.test.js` compares the migrated
Rust-owned route artifacts in `apps/tanstack-web/migration/route-manifest.json`
with `apps/backend/api/openapi.yaml`. Add or update the OpenAPI operation in the
same commit that marks a Rust route artifact `migrated`; otherwise `bun check`
fails.

For method-level overrides, the same evidence applies to each migrated method,
and the route override must leave every unmigrated sibling method as a generated
`legacy-next` artifact. Do not mark a full route migrated only because a safe
preflight or placeholder method is implemented in Rust.

The manifest check compares both aggregate method counts and each route's method
list against the current `apps/web/src/app` tree, including generated export
patterns such as `createOfflineRoute(...)` exports. Regenerate
the manifest after adding, removing, or changing exported methods in a legacy
`route.ts`. Non-terminal routes with `methods: []` are still artifacts in the
ownership inventory; port, restore an exported method, or mark them
`accepted-removal` with an explicit reason before cutover.

Rust JSON responses must keep the shared response security defaults:
`Content-Type: application/json`, `Content-Security-Policy: default-src 'none';
frame-ancestors 'none'; base-uri 'none'`, `Referrer-Policy: no-referrer`,
`X-Content-Type-Options: nosniff`, and `X-Frame-Options: DENY`. Route ports that
replace legacy public probes or API handlers must preserve explicit cache
behavior, including `Cache-Control: no-store` for `/api/health` and
`Cache-Control: public, max-age=300, must-revalidate` for `/.well-known/*`.
Non-JSON routes should use the empty-response path instead of serializing JSON
`null` when the legacy handler returned no body.

Protected workspace, cron, job, and admin endpoints stay server-owned. Browser
code cannot call protected Rust routes directly, cannot receive service tokens,
and cannot bypass `packages/internal-api` / TanStack server functions for
session-aware data access. Worker-bound secrets belong in Cloudflare secret
bindings; keep local, Docker, and Wrangler configuration to environment
variable names only.

For Cloudflare specifically:

* Bind `BACKEND_INTERNAL_TOKEN`, `BACKEND_PUBLIC_ORIGIN`, `SUPABASE_URL`,
  `SUPABASE_SERVICE_ROLE_KEY`, `CRON_SECRET`, and
  `DISCORD_APP_DEPLOYMENT_URL`, plus `AURORA_EXTERNAL_URL` and
  `AURORA_EXTERNAL_WSID`, with `wrangler secret put`,
  `wrangler versions secret put`, or Cloudflare dashboard secret bindings.
  The TanStack Worker reaches the backend Worker through the `BACKEND` service
  binding; configure `BACKEND_INTERNAL_URL` only for non-binding HTTP fallback
  runs. Use `secret put` for first preview bootstrap only because it deploys a
  new active version immediately; use the versions command family for
  rotations and canaries.
* Bind `TUTURUUU_APP_COORDINATION_SECRET` on the backend Worker before testing
  contact/profile routes. The Rust verifier also accepts existing
  app-coordination fallback secret names for compatibility, but the dedicated
  secret name is the preferred Cloudflare binding.
* Keep local Worker secret values in ignored `apps/backend/.dev.vars` and
  `apps/tanstack-web/.dev.vars` files. Do not commit literal origins that are
  account-specific private targets, tokens, API keys, cookies, or session
  material.
* `CMS_APP_URL` and `NEXT_PUBLIC_CMS_APP_URL` are public origin allowlist inputs
  for the WebGL upload preflight. They may be supplied through Wrangler vars or
  local `.dev.vars`, but they are not backend tokens and must not be listed as
  required secrets.
* Keep private/admin data ownership server-side. If a migrated endpoint needs a
  Supabase service role or private schema access, the Rust backend owns that
  call path; the browser receives only the authorized response shape.
* Review CORS, cookie domain, `SameSite`, secure-cookie, and session-origin
  behavior before mapping a custom hostname. Preview `workers.dev` origins are
  different sites from `tuturuuu.localhost` and production `tuturuuu.com`, so
  cookie/session behavior must be proven with smoke or E2E evidence rather than
  assumed from Docker.
* Keep `BACKEND_ENV=preview` for Cloudflare preview. Development-only
  migration routes and local E2E bypasses must not be enabled by Worker deploys.
* Do not bypass the migration gate because a Worker smoke passed. Worker smoke
  proves deploy compatibility; cutover still requires manifest, Docker E2E, and
  benchmark evidence.

Migration inventory endpoints are also protected because they expose checked
legacy route source paths and route ownership state. `GET /api/migration/status`,
`GET /api/migration/manifest`, `GET /api/migration/progress`, and
`GET /api/migration/cutover-gates` require
`Authorization: Bearer <BACKEND_INTERNAL_TOKEN>`. The TanStack migration
dashboard calls them from a Start server function through
`packages/internal-api`, which adds the bearer token only on the server.

The first Rust-owned migration contracts are exposed from `apps/backend` and
consumed by the TanStack shell through a Start server function:

| Endpoint                                                                                                                                                                                   | Purpose                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `GET /.well-known/*` / `HEAD /.well-known/*`                                                                                                                                               | Legacy-compatible cacheable empty `404` for unsupported well-known probes.                                                                                                                                                                                                                                                                                                                                                                            |
| `GET /~recover-browser-state` / `POST /~recover-browser-state`                                                                                                                             | Legacy-compatible browser recovery route with no-store HTML, same-origin POST protection, Clear-Site-Data, auth cookie clearing, and login redirect.                                                                                                                                                                                                                                                                                                  |
| `GET /api/health`                                                                                                                                                                          | Legacy-compatible health route migrated from `apps/web` to Rust.                                                                                                                                                                                                                                                                                                                                                                                      |
| `GET /api/auth/me`                                                                                                                                                                         | Legacy-compatible current Supabase user route backed by browser Supabase cookie or non-app-session Bearer revalidation through Supabase Auth, returning the raw user payload with no-store headers.                                                                                                                                                                                                                                                   |
| `GET /api/auth/mfa/totp/assurance-level`                                                                                                                                                   | Legacy-compatible Supabase MFA assurance-level route backed by browser Supabase cookie or non-app-session Bearer revalidation, JWT `aal`/`amr` claims, and verified factors from the revalidated user JSON.                                                                                                                                                                                                                                           |
| `GET` / `POST` `/api/auth/mfa/totp/factors`                                                                                                                                                | Legacy-compatible Supabase TOTP factor list/enrollment routes backed by browser Supabase cookie or non-app-session Bearer revalidation and Supabase Auth REST for enrollment.                                                                                                                                                                                                                                                                         |
| `GET` / `DELETE` `/api/auth/mfa/totp/factors/:factorId`                                                                                                                                    | Legacy-compatible Supabase TOTP factor detail/unenrollment routes backed by Auth JS-compatible factor listing and Supabase Auth REST unenrollment.                                                                                                                                                                                                                                                                                                    |
| `GET /api/v1/calendar/mock`                                                                                                                                                                | Legacy-compatible deterministic mock calendar events migrated from `apps/web` to Rust.                                                                                                                                                                                                                                                                                                                                                                |
| `GET /api/v1/devboxes/cache` and `POST /api/v1/devboxes/cache/prune`                                                                                                                       | Legacy-compatible devbox cache routes accepting platform CLI app-session access tokens or browser Supabase sessions, requiring root workspace `MEMBER` access, returning the current empty cache list body, and acknowledging prune requests without private devbox table mutations.                                                                                                                                                                  |
| `GET` / `POST` `/api/v1/aurora/forecast`, `/ml-metrics`, and `/statistical-metrics`                                                                                                        | Legacy-compatible Aurora forecast and metric readers plus protected ingest routes backed by Supabase Auth, the legacy Tuturuuu email-domain gate, external Aurora fetches, and caller-token Supabase inserts.                                                                                                                                                                                                                                         |
| `POST` / `DELETE` `/api/v1/infrastructure/languages`                                                                                                                                       | Legacy-compatible locale preference cookie route for `NEXT_LOCALE`.                                                                                                                                                                                                                                                                                                                                                                                   |
| `POST` / `DELETE` `/api/v1/infrastructure/sidebar`                                                                                                                                         | Legacy-compatible sidebar collapsed preference cookie route for `sidebar-collapsed`.                                                                                                                                                                                                                                                                                                                                                                  |
| `POST` / `DELETE` `/api/v1/infrastructure/sidebar/sizes`                                                                                                                                   | Legacy-compatible sidebar sizing preference cookie route for `sidebar-size` and `main-content-size`.                                                                                                                                                                                                                                                                                                                                                  |
| `GET /api/v1/infrastructure/users/fields/types`                                                                                                                                            | Legacy-compatible static user field type metadata route returning `TEXT`, `NUMBER`, `BOOLEAN`, `DATE`, and `DATETIME` in the original order.                                                                                                                                                                                                                                                                                                          |
| `GET /api/v1/infrastructure/ai/models`                                                                                                                                                     | Legacy-compatible public AI model catalog backed by private-schema Supabase REST reads with a fixed public column list, filters, sanitized search, capped ID filters, and exact-count pagination.                                                                                                                                                                                                                                                     |
| `GET /api/admin/tasks/embeddings/stats`                                                                                                                                                    | Legacy-compatible Tuturuuu-admin task embedding coverage stats backed by Supabase Auth cookie validation and server-owned exact task counts. The SSE embedding generator remains legacy-owned.                                                                                                                                                                                                                                                        |
| `GET /api/:wsId/crawlers/list`                                                                                                                                                             | Legacy-compatible authenticated crawled URL listing backed by Supabase Auth cookie validation, server-owned raw `crawled_urls` reads, exact-count pagination, and an explicit 401 for non-Tuturuuu callers.                                                                                                                                                                                                                                           |
| `GET /api/v1/workspaces/:wsId/crawlers/status`                                                                                                                                             | Legacy-compatible workspace-agnostic crawler status lookup backed by server-owned exact `crawled_urls.url` reads and raw related `crawled_url_next_urls` rows ordered by `created_at.desc`.                                                                                                                                                                                                                                                           |
| `GET /api/v1/ai/whitelist/me`                                                                                                                                                              | Legacy-compatible authenticated current-user AI whitelist status backed by satellite app-session auth or browser Supabase cookie auth and a server-owned private-schema enabled-flag lookup.                                                                                                                                                                                                                                                          |
| `GET /api/v1/cms/workspaces`                                                                                                                                                               | Legacy-compatible CMS workspace list backed by app-session or browser Supabase auth, service-role workspace reads, root-admin/per-workspace external-project permission checks, active binding resolution, and subscription tier metadata.                                                                                                                                                                                                            |
| `GET /api/v1/mira/achievements`                                                                                                                                                            | Legacy-compatible Mira achievement catalog backed by browser Supabase auth, private-schema service-role catalog reads, caller-token unlocked-achievement reads, and derived unlock/grouping/stat payloads.                                                                                                                                                                                                                                            |
| `GET /api/v1/storage/list`                                                                                                                                                                 | Legacy-compatible workspace Drive object list backed by `ttr_` workspace API-key validation, `manage_drive` permission checks, path sanitization, reserved mobile-deployment vault blocking, server-owned Supabase Storage list calls, placeholder/reserved-entry filtering, and recursive file-count pagination.                                                                                                                                     |
| `GET /api/time-tracking/export`                                                                                                                                                            | Legacy-compatible root-only grouped time-tracking export backed by browser Supabase auth, Tuturuuu email-domain gating, root workspace membership checks, caller-token `get_grouped_sessions_paginated` RPC calls, parseInt-style query defaults, a 1000-row limit cap, and the legacy empty-result fallback.                                                                                                                                         |
| `GET /api/v1/hive/ai/models`                                                                                                                                                               | Legacy-compatible Hive AI model catalog backed by Hive app-session or browser Supabase auth, Hive member/admin access, and server-owned private-schema model reads mapped to the shared UI model shape.                                                                                                                                                                                                                                               |
| `GET /api/v1/users/me/hive-access`                                                                                                                                                         | Legacy-compatible authenticated current-user Hive access status backed by current-user app-session auth or browser Supabase cookie auth and server-owned membership/admin flag lookups.                                                                                                                                                                                                                                                               |
| `GET /api/v1/nova/me/team`                                                                                                                                                                 | Legacy-compatible authenticated current-user Nova team lookup backed by Nova app-session auth or browser Supabase cookie auth and a server-owned private-schema team membership lookup.                                                                                                                                                                                                                                                               |
| `GET /api/v1/task-board-status-templates`                                                                                                                                                  | Legacy-compatible authenticated global task-board status template catalog backed by Supabase cookie or Bearer auth and server-owned ordered catalog reads.                                                                                                                                                                                                                                                                                            |
| `GET /api/v1/workspaces/limits`                                                                                                                                                            | Legacy-compatible authenticated workspace creation limit check backed by Supabase Auth cookie validation and server-owned exact counts of non-deleted workspaces created by the caller.                                                                                                                                                                                                                                                               |
| `GET /api/v1/workspaces/:wsId/posts/permissions`                                                                                                                                           | Legacy-compatible post permission flag reader backed by Supabase Auth revalidation and server-owned `has_workspace_permission` RPC checks, preserving quiet false flags for missing auth or unresolved permissions.                                                                                                                                                                                                                                   |
| `GET /api/v1/workspaces/:wsId/Mention`                                                                                                                                                     | Legacy-compatible mention email endpoint backed by Supabase Auth revalidation, exact `MEMBER` workspace membership, and caller-token `workspace_users.email` reads.                                                                                                                                                                                                                                                                                   |
| `GET /api/v1/workspaces/:wsId/habits/access`                                                                                                                                               | Legacy-compatible habits feature access probe backed by Supabase Auth revalidation, workspace normalization, service-role membership validation, and exact `ENABLE_HABITS=true` workspace secret matching.                                                                                                                                                                                                                                            |
| `GET /api/v1/workspaces/:wsId/mobile/module-flags`                                                                                                                                         | Legacy-compatible mobile module flag endpoint backed by Supabase Auth revalidation, caller-token workspace membership, and server-owned `workspace_secrets` reads for hidden module policy.                                                                                                                                                                                                                                                           |
| `GET /api/v1/workspaces/:wsId/education/access`                                                                                                                                            | Legacy-compatible education feature access probe backed by Supabase Auth revalidation, getPermissions-compatible `ai_lab` checks, and server-owned `workspace_secrets` `ENABLE_EDUCATION` reads.                                                                                                                                                                                                                                                      |
| `GET /api/v1/workspaces/:wsId/finance/budgets/status`                                                                                                                                      | Legacy-compatible budget status probe backed by finance/platform app-session or Supabase Auth revalidation, workspace normalization, `manage_finance` permission checks, and server-owned `get_budget_status` RPC reads.                                                                                                                                                                                                                              |
| `GET /api/workspaces/:wsId/finance/charts/balance`                                                                                                                                         | Legacy-compatible balance chart point backed by finance/platform app-session or Supabase Auth revalidation, workspace normalization, `view_finance_stats` checks, and `get_wallet_balance_at_date` RPC reads.                                                                                                                                                                                                                                         |
| `GET /api/v1/workspaces/:wsId/finance/debts/summary`                                                                                                                                       | Legacy-compatible debt and loan summary probe backed by finance/platform app-session or Supabase Auth revalidation, workspace normalization, `manage_finance` checks, and private `get_debt_loan_summary` RPC reads.                                                                                                                                                                                                                                  |
| `GET /api/v1/workspaces/:wsId/finance/filter-users`                                                                                                                                        | Legacy-compatible finance filter user endpoint backed by finance/platform app-session or Supabase Auth revalidation, workspace normalization, `view_transactions` checks, service-role creator reads, and caller-token workspace user reads.                                                                                                                                                                                                          |
| `GET /api/v1/workspaces/:wsId/finance/invoices/subscription/context`                                                                                                                       | Legacy-compatible subscription invoice context endpoint backed by finance/platform app-session or Supabase Auth revalidation, workspace normalization, `create_invoices` checks, student group validation, and service-role attendance/invoice reads.                                                                                                                                                                                                 |
| `GET /api/v1/workspaces/:wsId/finance/recurring-transactions/upcoming`                                                                                                                     | Legacy-compatible upcoming recurring transaction probe backed by finance/platform app-session or Supabase Auth revalidation, workspace normalization, `view_transactions` checks, and `get_upcoming_recurring_transactions` RPC reads.                                                                                                                                                                                                                |
| `GET /api/v1/workspaces/:wsId/settings/permissions`                                                                                                                                        | Legacy-compatible workspace settings permission flags backed by Supabase Auth revalidation, personal/workspace identifier resolution, membership validation, server-owned role/default permission reads, and the private 30-second success cache directive.                                                                                                                                                                                           |
| `GET /api/v1/workspaces/:wsId/settings/permissions/check`                                                                                                                                  | Legacy-compatible workspace permission checker backed by Supabase Auth revalidation, personal/workspace identifier resolution, membership validation, and server-owned role/default permission reads.                                                                                                                                                                                                                                                 |
| `GET /api/v1/workspaces/:wsId/course-modules` and `GET /api/v1/workspaces/:wsId/quiz-sets/:setId/linked-modules`                                                                           | Legacy-compatible education module readers backing the TanStack linked-modules page, with browser Supabase auth, `ai_lab` permission resolution, `ENABLE_EDUCATION` gating, exact-count pagination, and quiz-set workspace binding.                                                                                                                                                                                                                   |
| `GET` / `PATCH` `/api/v1/user/onboarding-progress`                                                                                                                                         | Legacy-compatible authenticated onboarding progress reader/updater backed by Supabase Auth cookie validation, server-owned `onboarding_progress` reads/upserts, and the legacy allowed-field update contract.                                                                                                                                                                                                                                         |
| `PATCH /api/v1/user/profile`                                                                                                                                                               | Legacy-compatible browser-session profile update backed by Supabase Auth cookie validation, legacy profile field validation, and server-owned `users` row updates scoped to the authenticated user.                                                                                                                                                                                                                                                   |
| `GET` / `PATCH` `/api/v1/users/me/default-workspace`                                                                                                                                       | Legacy-compatible default-workspace reader/updater backed by current-user app-session or browser Supabase auth for reads, caller-token membership validation for writes, and the legacy personal-workspace/null fallback.                                                                                                                                                                                                                             |
| `GET` / `PATCH` `/api/v1/users/calendar-settings`                                                                                                                                          | Legacy-compatible current-user calendar settings reader/updater backed by calendar app-session or browser Supabase auth, `user_private_details` reads/writes, `auto` defaults, and legacy enum/string patch validation.                                                                                                                                                                                                                               |
| `GET /api/v1/users/me/identities`                                                                                                                                                          | Legacy-compatible browser-session linked identity reader backed by Supabase Auth revalidation, raw user JSON identity extraction, derived `canUnlink`, and the private success cache directive.                                                                                                                                                                                                                                                       |
| `PATCH /api/v1/users/me/full-name`                                                                                                                                                         | Legacy-compatible browser-session full-name update backed by Supabase Auth cookie validation, required trimmed `full_name` validation, and caller-token `user_private_details` upsert scoped to the authenticated user.                                                                                                                                                                                                                               |
| `POST /api/v1/aurora/health`                                                                                                                                                               | Legacy-compatible protected Aurora health probe backed by Supabase Auth cookie validation, the legacy Tuturuuu email-domain gate, and an outbound `AURORA_EXTERNAL_URL/health` check.                                                                                                                                                                                                                                                                 |
| `GET` / `POST` `/api/v1/internal/holidays`, `POST` `/api/v1/internal/holidays/bulk`, and `PUT` / `DELETE` `/api/v1/internal/holidays/:holidayId`                                           | Rust counterparts for the Infrastructure-owned Vietnamese holiday list/create/bulk-import/update/delete routes. GET uses the Rust server-owned Supabase REST adapter with optional parseInt-style year filtering. Mutations revalidate Supabase auth, require root workspace `MEMBER` access, and write with the caller token so holiday RLS stays active. Bulk import preserves the replace-existing year delete plus date-conflict upsert behavior. |
| `GET /api/v1/topic-announcement-verifications/:token`                                                                                                                                      | Legacy-compatible public Topic Announcements email verification route backed by server-owned private-schema Supabase REST reads and updates. Workspace Topic Announcements management APIs remain legacy-owned.                                                                                                                                                                                                                                       |
| `GET /api/v1/users/me/profile`                                                                                                                                                             | App-session current-user profile route. It verifies `ttr_app_` JWTs, reads `users` and `user_private_details` through the server-owned Supabase REST adapter, and returns the legacy profile shape with no-store headers.                                                                                                                                                                                                                             |
| `PATCH /api/v1/users/me/profile`                                                                                                                                                           | App-session profile mutation route. It enforces same-origin confirmation for cookie auth, validates `display_name`, `bio`, and `avatar_url`, and persists the allowed fields to the `users` row through Supabase REST.                                                                                                                                                                                                                                |
| `POST /api/v1/inquiries`                                                                                                                                                                   | App-session support-inquiry route. It enforces same-origin confirmation for cookie auth, validates the legacy payload and field limits, and inserts `support_inquiries` with `creator_id` from the resolved app-session user.                                                                                                                                                                                                                         |
| `PATCH /api/v1/inquiries/:id`                                                                                                                                                              | Browser-session inquiry admin update route. It validates the legacy `is_read` and `is_resolved` flags, requires a Tuturuuu/XWF email domain, and patches `support_inquiries` through the server-owned Supabase REST adapter.                                                                                                                                                                                                                          |
| `OPTIONS /api/v1/auth/password-login`, `/otp/send`, and `/otp/verify`; `GET` / `OPTIONS` `/api/v1/auth/otp/settings`                                                                       | Legacy-compatible shared wildcard CORS preflights plus public OTP availability lookup backed by the root workspace OTP config reads. Paired OTP send/verify and password auth methods remain legacy-owned.                                                                                                                                                                                                                                            |
| `OPTIONS /api/v1/auth/mobile/password-login`, `/send-otp`, and `/verify-otp`                                                                                                               | Method-level legacy-compatible shared wildcard CORS `204` preflights; paired mobile auth methods remain legacy-owned.                                                                                                                                                                                                                                                                                                                                 |
| `GET` / `PUT` `/api/v1/infrastructure/mobile-versions`                                                                                                                                     | Legacy-compatible protected mobile policy snapshot and write route requiring a revalidated Supabase browser session or Bearer token plus root `manage_workspace_roles`; writes normalize the policy payload and upsert all nine root config rows.                                                                                                                                                                                                     |
| `GET` / `POST` `/api/v1/infrastructure/timezones` and `PUT` / `DELETE` `/api/v1/infrastructure/timezones/:timezoneId`                                                                      | Legacy-compatible protected timezone collection plus detail update/delete routes requiring a revalidated Supabase browser session or Bearer token plus root `manage_workspace_roles`, backed by server-owned private-schema `timezones` reads/writes.                                                                                                                                                                                                 |
| `GET /api/v1/infrastructure/user-status-changes`                                                                                                                                           | Legacy-compatible workspace user status change list backed by caller-token Supabase REST reads so `workspace_user_status_changes` RLS, exact count, required `ws_id`, and legacy `limit`/`offset` range behavior stay intact.                                                                                                                                                                                                                         |
| `GET /api/v1/infrastructure/users`                                                                                                                                                         | Legacy-compatible workspace user export list backed by caller-token Supabase REST reads so `workspace_users` RLS, exact count, required `ws_id`, and legacy `limit`/`offset` range behavior stay intact.                                                                                                                                                                                                                                              |
| `GET /api/v1/infrastructure/classes`, `/product-categories`, and `/score-names`                                                                                                            | Legacy-compatible catalog export lists backed by caller-token Supabase REST reads so `workspace_user_groups`, `product_categories`, and `user_group_metrics` RLS and exact-count pagination stay intact.                                                                                                                                                                                                                                              |
| `GET /api/v1/infrastructure/lessons` and `/packages`                                                                                                                                       | Legacy-compatible content export lists for private `user_group_posts` and `workspace_products`, preserving exact-count pagination, legacy auth shape for packages, and the no-auth lesson export behavior.                                                                                                                                                                                                                                            |
| `GET /api/v1/infrastructure/product-prices`, `/product-units`, and `/warehouses`                                                                                                           | Legacy-compatible inventory setup exports for private `inventory_products`, `inventory_units`, and `inventory_warehouses`, preserving inventory app-session auth, catalog/setup permission checks, exact-count pagination, and error bodies.                                                                                                                                                                                                          |
| `GET` / `POST` `/api/v1/infrastructure/ai/whitelist/domains` and `/emails`                                                                                                                 | Legacy-compatible protected AI whitelist collection routes backed by service-role private-schema reads/inserts after Supabase auth and `@tuturuuu.com` operator email validation.                                                                                                                                                                                                                                                                     |
| `PUT` / `DELETE` `/api/v1/infrastructure/ai/whitelist/:email` and `/domain/:domain`                                                                                                        | Legacy-compatible protected AI whitelist detail update/delete backed by service-role private-schema writes after Supabase auth and `@tuturuuu.com` operator email validation.                                                                                                                                                                                                                                                                         |
| `GET /api/v1/infrastructure/post-email-queue`                                                                                                                                              | Legacy-compatible protected post email queue infrastructure summary backed by service-role `post_email_queue` reads after root workspace membership validation, preserving summary, workspace, and batch aggregation behavior.                                                                                                                                                                                                                        |
| `GET /api/v1/infrastructure/bills`, `/roles`, and `/transaction-categories`                                                                                                                | Legacy-compatible workspace export lists backed by caller-token Supabase REST reads so `finance_invoices`, `workspace_user_groups`, and `transaction_categories` RLS and exact-count pagination stay intact.                                                                                                                                                                                                                                          |
| `GET /api/v1/infrastructure/wallet-transactions`                                                                                                                                           | Legacy-compatible protected wallet transaction export backed by the caller-token `get_wallet_transactions_with_permissions` RPC with legacy ordering, limit/offset, raw rows, and first-row `total_count` extraction.                                                                                                                                                                                                                                 |
| `GET /api/v1/infrastructure/abuse-intelligence`                                                                                                                                            | Legacy-compatible protected abuse intelligence snapshot backed by caller-token reputation subject, signal, and challenge reads plus service-role active trust override reads after root `view_infrastructure` permission validation.                                                                                                                                                                                                                  |
| `GET /api/v1/infrastructure/abuse-events`                                                                                                                                                  | Legacy-compatible root-workspace abuse event list backed by caller-token Supabase REST reads with legacy `ip`/`type`/`success` filters, page/pageSize pagination, exact counts, and auth/error bodies.                                                                                                                                                                                                                                                |
| `GET /api/v1/infrastructure/blocked-ips`                                                                                                                                                   | Legacy-compatible root-workspace blocked IP list backed by caller-token Supabase REST reads with the legacy `unblocked_by_user` embed, status/ip filters, page/pageSize pagination, exact counts, and auth/error bodies.                                                                                                                                                                                                                              |
| `GET /api/v1/infrastructure/suspensions`                                                                                                                                                   | Legacy-compatible active user suspension list backed by service-role `user_suspensions` reads after root `manage_workspace_roles`; POST and detail DELETE remain legacy-owned mutation methods.                                                                                                                                                                                                                                                       |
| `GET` / `POST` `/api/v1/infrastructure/email-blacklist` and `GET` / `PUT` / `DELETE` `/api/v1/infrastructure/email-blacklist/:entryId`                                                     | Legacy-compatible root-workspace email blacklist reads, creation, detail update, and detail deletion backed by caller-token Supabase REST with Zod-style write validation parity.                                                                                                                                                                                                                                                                     |
| `GET /api/v1/infrastructure/bill-coupons`, `/bill-packages`, `/class-attendance`, `/class-members`, `/class-packages`, `/class-scores`, `/package-stock-changes`, and `/student-feedbacks` | Legacy-compatible related-filter export lists backed by caller-token Supabase REST reads with embedded workspace relationships and exact-count pagination.                                                                                                                                                                                                                                                                                            |
| `GET /api/v1/infrastructure/user-monthly-reports` and `/user-monthly-report-logs`                                                                                                          | Legacy-compatible protected monthly report export lists backed by shared workspace permission resolution and private-schema Supabase REST exact-count pagination.                                                                                                                                                                                                                                                                                     |
| `GET` / `OPTIONS` `/api/v1/mobile/version-check`                                                                                                                                           | Legacy-compatible public mobile version policy evaluation and shared wildcard CORS preflight backed by fixed root workspace policy config IDs read through the Rust backend Supabase REST adapter.                                                                                                                                                                                                                                                    |
| `OPTIONS /api/v1/auth/qr-login/challenges[...]`                                                                                                                                            | Method-level legacy-compatible bare empty `204` preflights for QR login challenge create, poll, and approve routes.                                                                                                                                                                                                                                                                                                                                   |
| `OPTIONS /api/v1/auth/mfa/mobile/challenges[...]` and `/approvals[...]`                                                                                                                    | Method-level legacy-compatible bare empty `204` preflights for MFA mobile challenge create, poll, approve, and approval listing routes.                                                                                                                                                                                                                                                                                                               |
| `OPTIONS /api/v1/workspaces/:wsId/external-projects/webgl-packages/upload`                                                                                                                 | Method-level legacy-compatible WebGL upload preflight with credentialed CMS CORS headers only for allowed CMS origins.                                                                                                                                                                                                                                                                                                                                |
| `POST /api/v1/workspaces/:wsId/user-groups/:groupId/group-checks/:postId/email`                                                                                                            | Legacy-compatible removed direct post email route returning `410 Gone`; queue-based sending owns approved emails.                                                                                                                                                                                                                                                                                                                                     |
| `GET` / `POST` `/api/v1/workspaces/:wsId/slides`                                                                                                                                           | Legacy-compatible workspace slides collection placeholder returning `501 Not implemented`.                                                                                                                                                                                                                                                                                                                                                            |
| `PUT` / `DELETE` `/api/v1/workspaces/:wsId/slides/:slideId`                                                                                                                                | Legacy-compatible workspace slide item placeholder returning `501 Not implemented`.                                                                                                                                                                                                                                                                                                                                                                   |
| `PUT /api/v1/infrastructure/migrate/grouped-score-names`                                                                                                                                   | Disabled infrastructure migration route migrated from `apps/web` to Rust with the same development-only guard and `410 MIGRATION_DISABLED` body.                                                                                                                                                                                                                                                                                                      |
| `GET` / `PUT` / `PATCH` / `POST` `/api/v1/infrastructure/migrate/:migration`                                                                                                               | Accepted-removal terminal decommission for legacy batch migration helpers; Rust preserves the development/local-E2E guard and per-slug legacy method allow lists while returning `410 MIGRATION_DISABLED`.                                                                                                                                                                                                                                            |
| `PUT /api/workspaces/:wsId/products/categories/migrate`, `/products/units/migrate`, `/transactions/categories/migrate`, `/users/indicators/migrate`, and `/wallets/transactions/migrate`   | Obsolete workspace migration writes accepted for removal; Rust keeps the development-only guard and returns a terminal `410 MIGRATION_DISABLED` response.                                                                                                                                                                                                                                                                                             |
| `GET` / `POST` `/api/v1/workspaces/:wsId/encryption/migrate`, `POST /api/v1/workspaces/:wsId/storage/migrate`, `GET /api/v2/workspaces/:wsId/migrate/:module`                              | Production auth/API-key migration helpers accepted for removal; Rust keeps the legacy method allow lists and returns terminal `410 MIGRATION_DISABLED` in all environments.                                                                                                                                                                                                                                                                           |
| `GET /api/migration/status`                                                                                                                                                                | Runtime, environment, deployment target, and manifest pointer.                                                                                                                                                                                                                                                                                                                                                                                        |
| `GET /api/migration/manifest`                                                                                                                                                              | The checked route manifest JSON.                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `GET /api/migration/progress`                                                                                                                                                              | Owner/kind progress buckets and representative remaining legacy route artifacts.                                                                                                                                                                                                                                                                                                                                                                      |
| `GET /api/migration/cutover-gates`                                                                                                                                                         | Backend-derived manifest gates plus required E2E and benchmark evidence placeholders.                                                                                                                                                                                                                                                                                                                                                                 |

`/api/migration/cutover-gates` is the dashboard authority for cutover state. It
must stay blocked while any manifest route remains `legacy-next`, any backend
route artifact is not mapped to `rust-backend`, or required Docker E2E and
benchmark evidence is missing.

## Docker And E2E

The production compose stack defines `tanstack-web`, `tanstack-web-blue`, and
`tanstack-web-green` services. The Docker Bake file includes matching
`blue-green-tanstack-web*` targets so benchmark and cutover work can build
candidate TanStack images beside the legacy web images.

`apps/backend/Dockerfile` copies
`apps/tanstack-web/migration/route-manifest.json` into the Rust build context
because the backend includes the manifest at compile time for the migration
contract endpoints. Run `bun check:docker` after manifest path or Dockerfile
changes.

Legacy E2E remains the default:

```bash theme={null}
bun test:e2e:web:docker -- --frontend next
```

TanStack E2E uses the same Playwright suite and points at the TanStack route:

```bash theme={null}
bun test:e2e:web:docker -- --frontend tanstack
```

Run both modes sequentially before cutover:

```bash theme={null}
bun test:e2e:web:docker -- --frontend compare
```

Compare mode writes `tmp/e2e/web-migration/compare-report.json` after running
both frontends. Each frontend result includes normalized origin evidence,
`passRate`, `wallMs`, and Playwright JSON reporter test counts so
`bun migration:tanstack:gates` can evaluate same-origin mistakes, E2E
regressions, and zero-test false positives from the same evidence file. The gate
rejects missing, credentialed, invalid, or identical Next/TanStack origins, and
it rejects compare reports that do not prove nonzero Playwright execution for
both frontends. Set `E2E_COMPARE_REPORT_PATH` when a run needs to write the file
elsewhere under `tmp/`.

`apps/web/e2e/public-marketing-routes.noauth.spec.ts` is the first shared
public-route parity suite for this migration. It runs under the existing
`apps/web` Playwright project so `--frontend tanstack` and `--frontend compare`
reuse the same assertions for migrated landing, product, legal, redirect,
offline, branding, blog, careers, demo, security, partners, UI docs,
visualization, and static solution routes.

`scripts/public-marketing-e2e-coverage.test.js` compares the migrated public
page entries in `apps/tanstack-web/migration/route-manifest.json` with that
no-auth Playwright spec. When a public marketing, UI docs, redirect, or offline
page is marked `migrated`, the route needs a concrete default-locale E2E
example in the shared spec before `bun check` can pass.

## Benchmarks

Use the benchmark harness to compare reachable Next and TanStack frontend
routes, plus independent Rust backend smoke routes. It does not yet compare
legacy Next.js API route timing against equivalent Rust endpoints. Reports are
written under ignored
`tmp/benchmarks/web-migration/<timestamp>/report.json`.

```bash theme={null}
bun benchmark:web-setups -- --setup compare --profile smoke
```

Backend benchmark samples include protected migration endpoints. Set
`BACKEND_INTERNAL_TOKEN` when running the benchmark against local Docker,
preview Workers, or any backend that requires internal authorization; otherwise
the protected samples correctly fail as unreachable `4xx` responses.

To compare the legacy production/staging origin against Cloudflare preview
Workers, pass all origins explicitly:

```bash theme={null}
BACKEND_INTERNAL_TOKEN="${BACKEND_INTERNAL_TOKEN:?set BACKEND_INTERNAL_TOKEN}" \
bun benchmark:web-setups -- \
  --setup compare \
  --profile smoke \
  --next-origin https://<legacy-next-origin> \
  --tanstack-origin https://<tanstack-worker-origin> \
  --backend-origin https://<backend-worker-origin>
```

Compare reports must prove that the legacy Next.js and TanStack Start samples
came from distinct normalized frontend origins. `bun benchmark:web-setups`
rejects same-origin compare runs before writing a report, and
`bun migration:tanstack:gates` rejects benchmark evidence with missing origins,
credentialed origins, identical Next/TanStack origins, route/sample URLs that do
not match the recorded setup origin, or matched frontend routes without their
own `frontend-route-p95` comparison. Docker E2E compare evidence uses the same
distinct-origin rule for the browser-facing Next and TanStack frontend runs.

Use full mode when both frontends are running with representative seeded data:

```bash theme={null}
bun benchmark:web-setups -- --setup compare --profile full --require-all
```

In compare mode, `--require-all` fails the benchmark command when any required
metric evidence is missing. That keeps local benchmark rehearsals aligned with
`bun migration:tanstack:gates` instead of deferring missing dev-ready, build,
image-size, RSS/CPU, JS-output, E2E, or API latency evidence until cutover.

Pass reviewer-approved non-HTTP metrics and accepted regression notes through
`--evidence` when the harness cannot measure them directly:

```json theme={null}
{
  "metrics": {
    "backend": {
      "apiLatencyP50Ms": 80,
      "apiLatencyP95Ms": 120,
      "apiLatencyP99Ms": 180
    },
    "next": {
      "apiLatencyP50Ms": 75,
      "apiLatencyP95Ms": 110,
      "apiLatencyP99Ms": 170,
      "devReadyMs": 2200,
      "dockerBuildMs": 240000,
      "e2ePassRate": 1,
      "e2eWallMs": 90000,
      "firstRouteColdMs": 650,
      "imageSizeBytes": 1200000000,
      "jsOutputBytes": 850000,
      "productionCpuPercent": 4,
      "productionRssBytes": 640000000,
      "warmNavigationMs": 180
    },
    "tanstack": {
      "devReadyMs": 1800,
      "dockerBuildMs": 180000,
      "e2ePassRate": 1,
      "e2eWallMs": 84000,
      "firstRouteColdMs": 520,
      "imageSizeBytes": 760000000,
      "jsOutputBytes": 620000,
      "productionCpuPercent": 3,
      "productionRssBytes": 420000000,
      "warmNavigationMs": 140
    }
  },
  "acceptedRegressions": [
    {
      "metric": "first-route-cold-time",
      "note": "Approved while Cloudflare preview cache is cold."
    }
  ]
}
```

```bash theme={null}
bun benchmark:web-setups -- \
  --setup compare \
  --profile full \
  --require-all \
  --evidence tmp/benchmarks/web-migration/evidence.json
```

After the full benchmark writes a report, pass that report to
`bun migration:tanstack:gates` with the Docker E2E compare report and
Cloudflare smoke report. Generated benchmark, smoke, and E2E reports stay under
ignored `tmp/` paths. Cutover gates reject evidence older than 24 hours by
default; use `--evidence-max-age-ms <milliseconds>` only when a rehearsal
explicitly accepts a longer freshness window.

Default gates:

* frontend route p95 must not regress more than `25%`
* Cloudflare smoke evidence must include passing `backend-health`,
  `backend-ready`, `backend-migration-status`,
  `backend-migration-status-missing-token`,
  `backend-migration-status-invalid-token`, and `tanstack-root` probes
* cutover reports must include the full metric comparison contract:
  API p50/p95/p99, dev ready time, first-route cold time, warm navigation time,
  Docker build time, image size, JS output size, production RSS/CPU baseline,
  E2E wall time, and E2E pass rate, with numeric baseline, candidate, ratio,
  and threshold values for each required comparison
* full compare evidence must include complete matching frontend route coverage;
  unmatched Next-only or TanStack-only routes fail `--require-all` and cutover
  gate validation
* representative backend smoke routes must stay below the smoke ceiling
* strict runs fail when any required route is unreachable

Route samples include aggregate `p50Ms`, `p95Ms`, and `p99Ms`, plus `coldMs`
for the first successful request and `warmP50Ms` / `warmP95Ms` / `warmP99Ms`
for later samples. Use those fields for first-route cold time, warm navigation
time, and representative API latency notes. Add Docker build time, image size,
process RSS/CPU, JS output size, and E2E wall-time evidence to the same
benchmark directory when running full cutover rehearsals.

Record approved exceptions in the migration PR. Do not silently widen thresholds
to make a run pass.

## Cutover Checklist

1. Every manifest route is `migrated` or `accepted-removal`.
2. `bun migration:tanstack:cutover-check` passes.
3. `bun test:e2e:web:docker -- --frontend compare` passes and has a compare
   evidence report.
4. `bun benchmark:web-setups -- --setup compare --profile full --require-all` passes or has approved exceptions. HTTPS origins must present a certificate trusted by the host; use the local development CA or `NODE_EXTRA_CA_CERTS` instead of disabling certificate verification.
5. `bun smoke:cloudflare --output <path>` passes against the preview Workers.
6. `bun migration:tanstack:gates -- --e2e-report <path> --benchmark-report <path> --cloudflare-smoke-report <path>` passes.
7. `bun check:docker` and `bun check` pass.
8. Legacy `apps/web` remains available as the rollback fixture until production
   monitoring shows the TanStack/Rust path is stable.


# TanStack/Rust Migration Plan
Source: https://docs.tuturuuu.com/platform/architecture/tanstack-rust-migration-plan

Phased plan for replacing apps/web with apps/tanstack-web and apps/backend.

This page is the discoverable docs copy of the root migration plan for replacing
the legacy Next.js platform app with a dedicated TanStack Start frontend and a
Rust backend.

Use the architecture contract at
`platform/architecture/tanstack-rust-migration` for route ownership rules and
implementation patterns. Use the operational runbook at
`build/devops/tanstack-rust-cutover-runbook` for dual-stack bring-up and final
cutover evidence. Use this page for sequencing, verification gates, and
agent-lane planning.

## Current Snapshot

The route manifest at `apps/tanstack-web/migration/route-manifest.json` is the
source of truth. The latest local snapshot on 2026-08-03 is:

| Status                  | Count |
| ----------------------- | ----: |
| `legacy-next`           |   577 |
| `migrated`              |   215 |
| `accepted-removal`      |    13 |
| Total tracked artifacts |   805 |

Remaining legacy artifacts are concentrated in API/backend ownership:

| Kind             | Remaining legacy artifacts |
| ---------------- | -------------------------: |
| API              |                        506 |
| Cron             |                          6 |
| Error boundary   |                          1 |
| Loading boundary |                          1 |
| tRPC             |                          1 |
| Route handler    |                          1 |
| Page             |                         50 |
| Layout           |                         11 |

The production target is:

* `apps/tanstack-web` as the user-facing frontend.
* `apps/backend` as the Rust-owned API/backend runtime.
* `apps/web` kept only as a rollback fallback until terminal cutover gates are
  green.

## First Verification Gap Closure

Before accelerating route waves, keep the verification layer green and visible:

* Expose the dual-stack Docker E2E runner through the root package scripts.
* Keep `scripts/run-tanstack-e2e-docker.test.js` inside `test:scripts`.
* Run actual CI coverage for the minimal TanStack/Rust dual-stack compose stack.
* Run CI compare-mode coverage against a focused public no-auth Playwright
  smoke before broader cutover rehearsals.
* Keep the migration plan and cutover runbook discoverable from `apps/docs`.

The root commands are:

```bash theme={null}
bun test:e2e:tanstack:docker -- -- --project=chromium
bun test:e2e:web:docker:compare -- public-marketing-routes.noauth.spec.ts --project=chromium-no-auth
```

The double separator in the first command is intentional when invoking through
Bun: the first `--` separates Bun args, and the second is forwarded to the
TanStack runner so Playwright receives the project flag.

## Backend Waves

Backend migration is the primary bottleneck. Batch Rust routes by domain and
keep each batch independently revertible:

1. Auth, session, account identity, and current-user profile.
2. Workspace core, membership, limits, and permissions/navigation prerequisites.
3. High-density `/api/v1/workspaces/*` domains that unblock authenticated pages.
4. Cron, tRPC, and remaining low-frequency API compatibility routes.

Each backend wave must update focused Rust tests, route helper abstractions when
patterns harden, `apps/backend/README.md` when runtime behavior changes, and the
OpenAPI contract through the coordinator-owned `apps/backend/api/openapi.yaml`.

## Frontend Waves

Frontend work should follow backend readiness rather than reintroduce protected
raw API calls:

1. Dashboard shell, providers, navigation, auth gate, and workspace permission
   parity.
2. Authenticated dashboard pages whose data APIs are Rust-owned.
3. Module and settings pages in domain batches.
4. Public/static pages that still have legacy route artifacts.
5. Decommission-only accepted removals.

Use TanStack Router loaders, `createServerFn`, TanStack Query, and the existing
`auth-gate`, `workspace`, and `workspace-permission` helpers. Shared UI and the
TanStack app must call typed internal-api/backend facades, not protected raw
Supabase reads or raw `/api/*` endpoints.

Every terminal route must be classified as one of:

* static prerender
* ISR/CDN cache
* dynamic no-store
* redirect
* accepted removal

### 2026-06-25 Frontend Scout Handoff

The first frontend-only scout wave deliberately rejected several compact-looking
routes because they would otherwise become shell-only migrations. Keep these
handoffs visible so parallel workers do not repeat the same audit:

| Candidate lane                                                                                      | Current finding                                                                                                                                                                                                                                                                            | Next unblock                                                                                                                                                  |
| --------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `/:locale/meet` and `/:locale/meet-together`                                                        | TanStack public preview shells exist, but legacy also shows authenticated meeting plans and creates plans through Supabase/server-action paths.                                                                                                                                            | Add typed plan list/create APIs through Rust or TanStack server functions, then prove unauthenticated and authenticated parity with focused E2E.              |
| `/:locale/:wsId/users/topic-announcements/import`                                                   | Migrated in the TanStack frontend as a dynamic no-store page with fail-closed auth, workspace and feature gates, `manage_users`, send-permission-aware create-and-send controls, client-only XLSX/CSV parsing, editable row validation, and typed internal-api import/send-bulk mutations. | Backend agents still need Rust ownership for `/api/v1/workspaces/:wsId/topic-announcements/import` and `/send-bulk` before full backend cutover.              |
| `/:locale/:wsId/users/groups/:groupId/attendance`                                                   | Migrated in the TanStack frontend as a dynamic no-store page with fail-closed auth, workspace and group checks, `check_user_attendance`, `update_user_attendance` save gating, session/date URL state, and typed internal-api attendance/member/config/session facades.                    | Backend agents still need Rust ownership for the user-group attendance, members, workspace config, and session APIs before full backend cutover.              |
| `/:locale/:wsId/billing`                                                                            | `apps/pay` owns detailed billing, checkout, invoices, credits, subscriptions, webhooks, and payment mutations. `apps/web` retains only a read-only summary loaded from Pay through `packages/internal-api`; all actions link to Pay.                                                       | Treat the remaining web summary as an intentional satellite-app handoff. Do not restore payment mutations or detailed billing UI to either platform frontend. |
| `/:locale/:wsId/usage`                                                                              | The page wrapper is small, but the content is a broad Supabase/RPC workspace usage dashboard.                                                                                                                                                                                              | Create a usage-summary backend contract or server-function bundle that returns permission-masked stats without direct Supabase reads in TanStack.             |
| `/:locale/:wsId/ai/spark`, `/:locale/:wsId/mira`, and the canonical `/:locale/:wsId` Mira dashboard | Page files are compact, but the behavior is coupled to AI object APIs, Mira API routes, voice/live API helpers, or assistant providers. The standalone `/:locale/:wsId/assistant` route has been removed in favor of the unified workspace-root chat and rich voice experience.            | Treat these as dedicated product lanes with typed AI/Mira/assistant facades and focused browser evidence.                                                     |

## Coordinator-Owned Artifacts

Only the migration coordinator should edit generated or contract artifacts:

* `apps/tanstack-web/src/routeTree.gen.ts`
* `apps/tanstack-web/migration/route-manifest.json`
* `apps/tanstack-web/migration/route-overrides.json`
* `apps/backend/api/openapi.yaml`
* `apps/docs/platform/architecture/tanstack-rust-migration.mdx`

Workers should own disjoint route/API/domain lanes and leave coordinator-owned
files for integration.

## Required Gates

Per backend wave:

* `cargo fmt --check`
* focused `cargo test --locked <module>`
* `cargo clippy --locked --all-targets --features native -- -D warnings`
* OpenAPI contract tests
* `bun migration:tanstack:check`

Per frontend wave:

* `bun --filter @tuturuuu/tanstack-web type-check`
* `bun --filter @tuturuuu/tanstack-web test`
* route-tree generator tests when route files change
* `bun migration:tanstack:check`
* TanStack API access checks
* focused Playwright when route behavior changes

Final cutover requires:

* `bun migration:tanstack:cutover-check`
* `bun migration:tanstack:gates`
* dual-stack Docker E2E evidence
* compare-mode Docker E2E evidence
* benchmark evidence
* Cloudflare smoke evidence
* final `bun check`

## Commit Cadence

Commit after each independently revertible lane or small batch. In a shared
checkout, claim the commit window immediately before exact-path staging, inspect
the staged files, commit with a Conventional Commit subject, then release the
window. Do not run `bun git-sync` or push unless explicitly requested.


# tRPC Implementation Guide
Source: https://docs.tuturuuu.com/platform/architecture/trpc

How to create and use tRPC routers in the Tuturuuu platform

The Tuturuuu platform uses [tRPC](https://trpc.io/) for end-to-end type-safe API communication between the Next.js frontend and backend.

## Architecture Overview

```
┌─────────────────────────────────────────────────────────┐
│                    Client (Browser)                      │
│  ┌──────────────────────────────────────────────────┐   │
│  │  React Components (RSC or 'use client')          │   │
│  │  ↓                                                │   │
│  │  trpc.workspace.get.useQuery()                    │   │
│  └────────────────┬─────────────────────────────────┘   │
└────────────────────┼─────────────────────────────────────┘
                     │ HTTP Request
                     ↓
┌─────────────────────────────────────────────────────────┐
│                Server (Next.js API)                      │
│  ┌──────────────────────────────────────────────────┐   │
│  │  tRPC Router (/api/trpc/[trpc]/route.ts)         │   │
│  │  ↓                                                │   │
│  │  Procedure Handler (input validation with Zod)   │   │
│  │  ↓                                                │   │
│  │  Supabase Query / Business Logic                 │   │
│  │  ↓                                                │   │
│  │  Type-safe Response                              │   │
│  └──────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────┘
```

## Directory Structure

```
apps/web/src/trpc/
├── init.ts              # tRPC initialization
├── routers/
│   ├── _app.ts          # Root router aggregating all routes
│   ├── workspace.ts     # Workspace-related procedures
│   ├── user.ts          # User-related procedures
│   ├── ai.ts            # AI-related procedures
│   └── ...              # Other domain routers
├── client.tsx           # Client-side hooks (useQuery, useMutation)
├── server.ts            # Server-side caller
└── query.ts             # React Query integration
```

## Creating a New Router

### Step 1: Define the Router

Create a new file in `apps/web/src/trpc/routers/`:

```typescript theme={null}
// apps/web/src/trpc/routers/tasks.ts
import { z } from 'zod';
import { router, protectedProcedure } from '../init';
import { createClient } from '@tuturuuu/supabase/next/server';

export const tasksRouter = router({
  // GET single task
  get: protectedProcedure
    .input(
      z.object({
        taskId: z.guid(),
      })
    )
    .query(async ({ input, ctx }) => {
      const supabase = createClient();

      const { data, error } = await supabase
        .from('workspace_tasks')
        .select('*')
        .eq('id', input.taskId)
        .single();

      if (error) throw new Error(error.message);
      return data;
    }),

  // LIST tasks in workspace
  list: protectedProcedure
    .input(
      z.object({
        wsId: z.string(),
        listId: z.string().optional(),
        completed: z.boolean().optional(),
      })
    )
    .query(async ({ input, ctx }) => {
      const supabase = createClient();

      let query = supabase
        .from('workspace_tasks')
        .select('*')
        .eq('ws_id', input.wsId);

      if (input.listId) {
        query = query.eq('list_id', input.listId);
      }

      if (input.completed !== undefined) {
        query = query.eq('completed', input.completed);
      }

      const { data, error } = await query;
      if (error) throw new Error(error.message);
      return data;
    }),

  // CREATE task
  create: protectedProcedure
    .input(
      z.object({
        wsId: z.string(),
        listId: z.string(),
        name: z.string().min(1).max(255),
        description: z.string().optional(),
        priority: z.number().int().min(0).max(5).optional(),
        dueDate: z.date().optional(),
      })
    )
    .mutation(async ({ input, ctx }) => {
      const supabase = createClient();

      const { data, error } = await supabase
        .from('workspace_tasks')
        .insert({
          ws_id: input.wsId,
          list_id: input.listId,
          name: input.name,
          description: input.description,
          priority: input.priority,
          due_date: input.dueDate?.toISOString(),
          created_by: ctx.user.id, // From protected context
        })
        .select()
        .single();

      if (error) throw new Error(error.message);
      return data;
    }),

  // UPDATE task
  update: protectedProcedure
    .input(
      z.object({
        taskId: z.guid(),
        name: z.string().min(1).max(255).optional(),
        description: z.string().optional(),
        completed: z.boolean().optional(),
        priority: z.number().int().min(0).max(5).optional(),
      })
    )
    .mutation(async ({ input, ctx }) => {
      const supabase = createClient();

      const { taskId, ...updates } = input;

      const { data, error } = await supabase
        .from('workspace_tasks')
        .update(updates)
        .eq('id', taskId)
        .select()
        .single();

      if (error) throw new Error(error.message);
      return data;
    }),

  // DELETE task
  delete: protectedProcedure
    .input(
      z.object({
        taskId: z.guid(),
      })
    )
    .mutation(async ({ input }) => {
      const supabase = createClient();

      const { error } = await supabase
        .from('workspace_tasks')
        .delete()
        .eq('id', input.taskId);

      if (error) throw new Error(error.message);
      return { success: true };
    }),
});
```

### Step 2: Add to Root Router

Add your router to `apps/web/src/trpc/routers/_app.ts`:

```typescript theme={null}
import { router } from '../init';
import { workspaceRouter } from './workspace';
import { userRouter } from './user';
import { tasksRouter } from './tasks'; // Import new router

export const appRouter = router({
  workspace: workspaceRouter,
  user: userRouter,
  tasks: tasksRouter, // Add to root
});

export type AppRouter = typeof appRouter;
```

### Step 3: Use in Components

#### Client Component with useQuery

```tsx theme={null}
'use client';

import { trpc } from '@/trpc/client';

export function TaskList({ wsId }: { wsId: string }) {
  const { data: tasks, isLoading, error } = trpc.tasks.list.useQuery({
    wsId,
    completed: false,
  });

  if (isLoading) return <div>Loading...</div>;
  if (error) return <div>Error: {error.message}</div>;

  return (
    <ul>
      {tasks?.map((task) => (
        <li key={task.id}>{task.name}</li>
      ))}
    </ul>
  );
}
```

#### Client Component with useMutation

```tsx theme={null}
'use client';

import { trpc } from '@/trpc/client';
import { useState } from 'react';

export function CreateTaskForm({ wsId, listId }: { wsId: string; listId: string }) {
  const [name, setName] = useState('');
  const utils = trpc.useContext();

  const createTask = trpc.tasks.create.useMutation({
    onSuccess: () => {
      // Invalidate tasks list to refetch
      utils.tasks.list.invalidate({ wsId });
      setName('');
    },
  });

  const handleSubmit = (e: React.FormEvent) => {
    e.preventDefault();
    createTask.mutate({ wsId, listId, name });
  };

  return (
    <form onSubmit={handleSubmit}>
      <input
        value={name}
        onChange={(e) => setName(e.target.value)}
        placeholder="Task name"
      />
      <button type="submit" disabled={createTask.isPending}>
        {createTask.isPending ? 'Creating...' : 'Create Task'}
      </button>
      {createTask.error && <p>Error: {createTask.error.message}</p>}
    </form>
  );
}
```

#### Server Component (Server-Side Caller)

```tsx theme={null}
import { createCaller } from '@/trpc/server';

export default async function TaskPage({ params }: { params: { taskId: string } }) {
  const trpc = await createCaller();
  const task = await trpc.tasks.get({ taskId: params.taskId });

  return (
    <div>
      <h1>{task.name}</h1>
      <p>{task.description}</p>
    </div>
  );
}
```

## Procedure Types

### `publicProcedure`

No authentication required. Use for public endpoints.

```typescript theme={null}
export const publicRouter = router({
  status: publicProcedure.query(() => {
    return { status: 'ok' };
  }),
});
```

### `protectedProcedure`

Requires authentication. Provides `ctx.user` in handler.

```typescript theme={null}
export const protectedRouter = router({
  profile: protectedProcedure.query(({ ctx }) => {
    return { userId: ctx.user.id }; // ctx.user is guaranteed
  }),
});
```

Implementation in `apps/web/src/trpc/init.ts`:

```typescript theme={null}
const isAuthed = t.middleware(async ({ ctx, next }) => {
  const supabase = createClient();
  const { data: { user } } = await supabase.auth.getUser();

  if (!user) {
    throw new Error('Unauthorized');
  }

  return next({
    ctx: {
      user, // Add user to context
    },
  });
});

export const protectedProcedure = t.procedure.use(isAuthed);
```

## Input Validation with Zod

Always validate inputs using Zod schemas:

```typescript theme={null}
import { z } from 'zod';

const createTaskSchema = z.object({
  wsId: z.string().min(1, 'Workspace ID required'),
  name: z.string().min(1, 'Name required').max(255, 'Name too long'),
  priority: z.number().int().min(0).max(5).default(0),
  dueDate: z.date().optional(),
  tags: z.array(z.string()).optional(),
});

export const tasksRouter = router({
  create: protectedProcedure
    .input(createTaskSchema)
    .mutation(async ({ input }) => {
      // input is fully typed and validated
      // ...
    }),
});
```

### Common Zod Patterns

```typescript theme={null}
// UUID validation
z.guid()

// Email validation
z.email()

// URL validation
z.url()

// Enum
z.enum(['pending', 'in_progress', 'completed'])

// Date
z.date() // or z.string().datetime() for ISO strings

// Optional with default
z.string().default('default-value')

// Nested objects
z.object({
  user: z.object({
    id: z.guid(),
    name: z.string(),
  }),
})

// Arrays
z.array(z.string())

// Union types
z.union([z.string(), z.number()])

// Transform
z.string().transform((val) => val.toLowerCase())

// Refine (custom validation)
z.string().refine((val) => val.includes('@'), {
  message: 'Must be an email',
})
```

## Error Handling

### Throwing Errors

```typescript theme={null}
import { TRPCError } from '@trpc/server';

export const tasksRouter = router({
  get: protectedProcedure
    .input(z.object({ taskId: z.guid() }))
    .query(async ({ input }) => {
      const supabase = createClient();
      const { data, error } = await supabase
        .from('workspace_tasks')
        .select('*')
        .eq('id', input.taskId)
        .single();

      if (error) {
        throw new TRPCError({
          code: 'NOT_FOUND',
          message: `Task ${input.taskId} not found`,
          cause: error,
        });
      }

      return data;
    }),
});
```

### Error Codes

* `BAD_REQUEST` - Invalid input
* `UNAUTHORIZED` - Not authenticated
* `FORBIDDEN` - Authenticated but not authorized
* `NOT_FOUND` - Resource not found
* `INTERNAL_SERVER_ERROR` - Server error
* `TIMEOUT` - Request timeout
* `CONFLICT` - Resource conflict

### Handling Errors Client-Side

```tsx theme={null}
'use client';

import { trpc } from '@/trpc/client';

export function TaskDetails({ taskId }: { taskId: string }) {
  const { data, error } = trpc.tasks.get.useQuery({ taskId });

  if (error) {
    if (error.data?.code === 'NOT_FOUND') {
      return <div>Task not found</div>;
    }
    if (error.data?.code === 'UNAUTHORIZED') {
      return <div>Please log in</div>;
    }
    return <div>Error: {error.message}</div>;
  }

  return <div>{data?.name}</div>;
}
```

## React Query Integration

tRPC uses React Query under the hood. You have access to all React Query features:

### Query Options

```tsx theme={null}
const { data } = trpc.tasks.list.useQuery(
  { wsId },
  {
    staleTime: 5 * 60 * 1000, // 5 minutes
    refetchOnWindowFocus: false,
    retry: 3,
    enabled: !!wsId, // Only run if wsId exists
  }
);
```

### Optimistic Updates

```tsx theme={null}
const utils = trpc.useContext();

const updateTask = trpc.tasks.update.useMutation({
  onMutate: async (newData) => {
    // Cancel outgoing refetches
    await utils.tasks.get.cancel({ taskId: newData.taskId });

    // Snapshot previous value
    const previous = utils.tasks.get.getData({ taskId: newData.taskId });

    // Optimistically update
    utils.tasks.get.setData({ taskId: newData.taskId }, (old) => ({
      ...old!,
      ...newData,
    }));

    return { previous };
  },
  onError: (err, newData, context) => {
    // Rollback on error
    if (context?.previous) {
      utils.tasks.get.setData({ taskId: newData.taskId }, context.previous);
    }
  },
  onSettled: (data, error, variables) => {
    // Always refetch after error or success
    utils.tasks.get.invalidate({ taskId: variables.taskId });
  },
});
```

### Cache Invalidation

```tsx theme={null}
const utils = trpc.useContext();

// Invalidate specific query
utils.tasks.get.invalidate({ taskId: '123' });

// Invalidate all tasks.list queries
utils.tasks.list.invalidate();

// Invalidate all tasks queries
utils.tasks.invalidate();

// Reset to initial state
utils.tasks.list.reset({ wsId });
```

## Performance Best Practices

### 1. Use Query Keys Wisely

```typescript theme={null}
// ✅ Good: Specific query keys
trpc.tasks.list.useQuery({ wsId, listId, completed: false });

// ❌ Bad: Over-fetching
trpc.tasks.getAll.useQuery(); // Gets ALL tasks
```

### 2. Enable Request Batching

tRPC automatically batches requests made within 10ms:

```tsx theme={null}
// These three queries are sent in a single HTTP request
const tasks = trpc.tasks.list.useQuery({ wsId });
const boards = trpc.boards.list.useQuery({ wsId });
const members = trpc.workspace.members.useQuery({ wsId });
```

### 3. Use `staleTime` for Cacheable Data

```tsx theme={null}
// User profile rarely changes - cache for 10 minutes
const { data: profile } = trpc.user.profile.useQuery(undefined, {
  staleTime: 10 * 60 * 1000,
});
```

### 4. Prefetch on Server

```tsx theme={null}
// app/workspace/[wsId]/tasks/page.tsx
import { createCaller } from '@/trpc/server';
import { HydrateClient } from '@/trpc/query';

export default async function TasksPage({ params }: { params: { wsId: string } }) {
  const trpc = await createCaller();
  const tasks = await trpc.tasks.list({ wsId: params.wsId });

  return (
    <HydrateClient>
      <TaskList wsId={params.wsId} /> {/* Uses prefetched data */}
    </HydrateClient>
  );
}
```

## Testing tRPC Procedures

```typescript theme={null}
// __tests__/tasks.test.ts
import { createCaller } from '@/trpc/server';
import { describe, it, expect } from 'vitest';

describe('tasks router', () => {
  it('should create a task', async () => {
    const trpc = await createCaller();

    const task = await trpc.tasks.create({
      wsId: 'test-workspace',
      listId: 'test-list',
      name: 'Test Task',
    });

    expect(task.name).toBe('Test Task');
    expect(task.ws_id).toBe('test-workspace');
  });

  it('should throw on invalid input', async () => {
    const trpc = await createCaller();

    await expect(
      trpc.tasks.create({
        wsId: '',
        listId: 'test-list',
        name: '', // Invalid: empty name
      })
    ).rejects.toThrow();
  });
});
```

## Related Documentation

* [API Routes](/platform/architecture/api-routes) - REST API patterns
* [Data Fetching](/platform/architecture/data-fetching) - When to use tRPC vs other patterns
* [Authentication](/platform/architecture/authentication) - Auth middleware
* [Authorization](/platform/architecture/authorization) - Permission checking

## External Resources

* [tRPC Official Docs](https://trpc.io/)
* [Zod Documentation](https://zod.dev/)
* [React Query Docs](https://tanstack.com/query/latest)


# Workspaces & Permissions
Source: https://docs.tuturuuu.com/platform/architecture/workspaces-permissions

Complete reference for workspace identity, membership, routing, and effective permissions in apps/web

This page documents the actual workspace and permission model used by `apps/web` today.

It focuses on the implementation that page components, route handlers, and the internal API helpers actually consume:

* `packages/utils/src/workspace-helper.ts`
* `packages/ui/src/components/ui/custom/workspace-wrapper.tsx`
* `apps/web/src/proxy.ts`
* `packages/utils/src/permissions.tsx`
* `apps/web/src/lib/api-middleware.ts`

## Mental Model

There are four layers, and most bugs come from mixing them together:

1. **Workspace identity**
   `personal`, `internal`, and UUIDs all describe the same underlying `workspaces.id` shape, but only UUIDs are stored in the database.
2. **Membership**
   `workspace_members` answers "is this signed-in user allowed inside this workspace at all?"
3. **Effective permissions**
   `workspace_role_members`, `workspace_role_permissions`, `workspace_default_permissions`, and creator fallback answer "what may this member do?"
4. **Surface enforcement**
   Pages, navigation, and API routes decide whether to hide, redirect, 403, or allow the action.

```mermaid theme={null}
flowchart LR
  URL["Incoming URL or API param"] --> Proxy["apps/web/src/proxy.ts"]
  Proxy --> Slug["Canonical slug handling<br/>personal / internal / UUID"]
  Slug --> Page["WorkspaceWrapper / getWorkspace()"]
  Slug --> Route["normalizeWorkspaceId()"]
  Page --> Member["workspace_members membership check"]
  Route --> Auth["createClient(request)"]
  Auth --> Perms["getPermissions()"]
  Perms --> UI["navigation.tsx / server pages"]
  Perms --> API["privileged route handlers"]
```

## Workspace Vocabulary

| Concept                    | Source of truth                 | What it means in `apps/web`                                                                                                 |
| -------------------------- | ------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| Workspace                  | `workspaces`                    | A top-level collaboration boundary and the scope for most product data.                                                     |
| Personal workspace         | `workspaces.personal = true`    | A one-user workspace that is canonicalized to the `personal` URL slug.                                                      |
| Root workspace             | `ROOT_WORKSPACE_ID`             | The internal/system workspace, canonicalized to the `internal` URL slug.                                                    |
| Membership                 | `workspace_members`             | Grants baseline access to a workspace as either `MEMBER` or `GUEST`.                                                        |
| Workspace role             | `workspace_roles`               | A named collection of enabled permission bits for one workspace.                                                            |
| Role assignment            | `workspace_role_members`        | Links a user to one or more workspace roles.                                                                                |
| Default permissions        | `workspace_default_permissions` | Workspace-wide defaults scoped by `member_type`. `MEMBER` rows apply to members and API keys; `GUEST` rows apply to guests. |
| Guest resource permissions | `workspace_guest_permissions`   | Per-guest or resource-scoped guest grants such as course access.                                                            |
| API key                    | `workspace_api_keys`            | Workspace-bound SDK credential that reuses the same permission IDs.                                                         |

## Membership Is Not The Same Thing As A Workspace User Record

`apps/web` uses two different "user-ish" concepts:

* `workspace_members`
  This is the access-control boundary. Most auth checks read this table.
* `workspace_users`
  This is domain data used by product features such as user management, attendance, reports, and directory-style views.

Do not treat `workspace_users` as evidence that a signed-in platform user has workspace access. In the web app, access checks consistently use `workspace_members`.

## Canonical Workspace Identifiers

The web app accepts three route forms:

* a raw workspace UUID
* `personal`
* `internal`

The database only stores UUID workspace IDs. The slugs are convenience identifiers used at the edge and in page params.

### Resolution Rules

* `personal` resolves to the signed-in user's personal workspace UUID.
* `internal` resolves to `ROOT_WORKSPACE_ID`.
* a personal workspace UUID in the URL is redirected back to `/personal/...`.
* the root workspace UUID in the URL is redirected back to `/internal/...`.

This canonicalization happens before most page rendering so the browser settles on stable, human-friendly URLs.

## How Proxy Routing Works

`apps/web/src/proxy.ts` is the entry point for workspace-aware URL normalization.

The proxy is responsible for:

* locale-aware path parsing
* redirecting root visits to the user's default workspace
* rewriting raw root UUIDs to `internal`
* rewriting personal workspace UUIDs to `personal`
* preserving auth cookies while issuing those redirects

It also uses `getUserDefaultWorkspace()` from `packages/utils/src/user-helper.ts` to decide where an authenticated user lands when they hit `/`.

### Default Workspace Behavior

The default workspace is stored in `user_private_details.default_workspace_id`.

When the stored default workspace is missing or no longer accessible, the helper falls back to the user's personal workspace.

That fallback is used both for root-path redirect behavior and for other flows that need a stable "start workspace" concept.

## Server-Page Workspace Resolution

For server-rendered pages under `apps/web/src/app/[locale]/(dashboard)/[wsId]/...`, the normal entry point is `WorkspaceWrapper`.

`WorkspaceWrapper` delegates to `getWorkspace(wsId)`, which:

1. validates that the incoming identifier is a supported direct lookup form
2. authenticates the current user
3. resolves `personal` / `internal` into a concrete workspace ID
4. queries `workspaces` joined through `workspace_members!inner(user_id)`
5. returns the workspace plus:
   * `joined`
   * `tier`
   * normalized `workspace.id`

If that lookup fails, the wrapper calls `notFound()`.

### Important Consequence

Page components that use `WorkspaceWrapper` already know:

* the user is authenticated
* the user has a `workspace_members` row for the workspace
* the child callback receives the canonical UUID as `wsId`

That does **not** mean the user has feature-level permissions. Fine-grained authorization still needs `getPermissions()`.

It also does not mean the user is a full member. Guests can have `workspace_members.type = 'GUEST'`, so non-guest-capable pages and APIs must explicitly require `MEMBER`.

## Route-Handler Workspace Resolution

API routes cannot depend on `WorkspaceWrapper`, so they use `normalizeWorkspaceId()`.

`normalizeWorkspaceId()`:

* accepts the route param
* optionally accepts a request-scoped Supabase client
* preserves mobile/Bearer-token auth by using `createClient(request)` when needed
* returns the canonical workspace UUID
* throws when `personal` is requested but no authenticated personal workspace exists

App-session and CLI routes that call `normalizeWorkspaceId()` with an admin
Supabase client should first attach the verified actor with
`attachSupabaseAuthUser()` from `@tuturuuu/auth/app-session`. Do not duplicate
manual `personal` workspace fallback lookups inside each route.

Use it whenever a route param may contain `personal` or `internal` but the query must operate on concrete workspace IDs.

## Effective Permission Evaluation

The main evaluator is `getPermissions({ wsId, request? })` in `packages/utils/src/workspace-helper.ts`.

Its behavior is the key thing to understand.

### Inputs

* authenticated current user
* workspace identifier from the page or route

### Data sources

* `workspace_role_members`
* `workspace_roles`
* `workspace_role_permissions`
* `workspace_default_permissions.member_type`
* `workspaces.creator_id`

### Evaluation algorithm

1. Authenticate the current user.
2. Normalize the workspace ID.
3. Verify whether the caller is a `MEMBER` or `GUEST`.
4. For `MEMBER`, load role-derived permissions for the current user in that workspace.
5. Load workspace-wide default permissions where `member_type` matches the caller.
6. Load the workspace creator ID.
7. If the user is the creator and a `MEMBER`, return the full permission catalog from `packages/utils/src/permissions.tsx`.
8. Otherwise return the deduplicated union of role-derived and default permissions.
9. If the user is not the creator and the union is empty, return `null`.

`MEMBER` defaults are the backward-compatible default. Existing rows became `member_type = 'MEMBER'`, and `/api/v1/workspaces/[wsId]/roles/default` still defaults to `memberType=MEMBER` when the query parameter is omitted.

`GUEST` defaults use the same full permission catalog as members, but the default is deny: a missing guest row means no permission. The dashboard proxy applies this as a route guard for guests: members keep existing behavior, while guests may open only routes that map to an enabled guest default permission. Routes without a permission mapping are denied for guests even when the guest has `admin`.

### Why creator fallback matters

A newly created workspace may exist before any roles or defaults are configured.

The creator fallback prevents the creator from locking themselves out. The dashboard permission-setup banner exists because everyone else would otherwise have no effective permissions until defaults or roles are configured.

## `workspace_members.role` Is Not The Current Permission Source

This is the most important corrective note for anyone reading older docs or legacy schema assumptions.

`apps/web` permission checks do **not** currently derive access from `workspace_members.role`.

Modern member permission evaluation reads:

* role memberships from `workspace_role_members`
* permission definitions from `workspace_role_permissions`
* workspace-wide defaults from `workspace_default_permissions.member_type = 'MEMBER'`

Guest permission evaluation reads `workspace_default_permissions.member_type = 'GUEST'` for dashboard route defaults and keeps `workspace_guest_permissions` for resource-specific grants such as `course:view`.

If you document or implement new authorization behavior against `workspace_members.role`, you will diverge from the real app behavior.

## Permission Catalog

The permission catalog is defined in `packages/utils/src/permissions.tsx`.

The catalog is grouped for UI presentation and creator fallback. The main groups currently cover:

* workspace administration
* AI
* calendar
* projects
* documents
* time tracking
* drive
* users
* user groups
* leads
* inventory
* finance
* workforce
* transactions
* invoices

When the current workspace is the root workspace, an additional infrastructure group is available.

### `admin` semantics

`admin` is just another permission ID in the catalog, but `containsPermission()` treats it as a full bypass:

* creator => all permissions
* `admin` => all permissions
* explicit permission match => specific permission granted

That means `admin` is a permission bit, not a separate role engine.

## Where Permissions Affect The UI

### Navigation

`apps/web/src/app/[locale]/(dashboard)/[wsId]/navigation.tsx` is the broadest consumer of `getPermissions()`.

It uses `withoutPermission(...)` to:

* disable whole sidebar sections
* disable specific children under a section
* expose root-only capabilities only when the current user also has root-workspace permissions
* combine permissions with workspace secrets and product-tier checks

This is why a missing permission often appears first as a disabled nav item, not as a late 403 from the clicked page.

### Mobile module flags

The mobile app can hide experimental app modules per workspace through
workspace secrets exposed by
`/api/v1/workspaces/[wsId]/mobile/module-flags`. The route authenticates the
mobile session, verifies workspace membership with the request-scoped client,
then reads only the mobile module flag secrets with an admin client.

Supported secrets:

* `MOBILE_HIDE_EXPERIMENTAL_MODULES`: truthy values (`1`, `true`, `yes`, `on`)
  hide the default experimental modules.
* `MOBILE_HIDDEN_MODULES`: JSON array or comma-separated module IDs for explicit
  hidden modules.

Keep these flags as display controls. API routes that expose protected module
data must still perform their own workspace membership and permission checks.

### Settings pages

Workspace settings pages usually follow this pattern:

1. resolve the workspace with `WorkspaceWrapper`
2. call `getPermissions({ wsId })`
3. redirect away or `notFound()` if the required permission is missing

Examples:

* members page requires `manage_workspace_members`
* roles page requires `manage_workspace_roles`
* settings page checks `manage_workspace_settings` and `manage_workspace_security`

### Members UI

The members settings surfaces use `workspace_members_and_invites` so joined members and pending invites can be shown together.

The enhanced members route also merges:

* role memberships
* enabled role permissions
* default permissions
* creator flag
* privacy-related workspace secrets like `HIDE_MEMBER_EMAIL` and `HIDE_MEMBER_NAME`

That is why the members page can show a permission breakdown per person without recomputing everything in the browser.

## Where Permissions Affect API Routes

There are two broad families in `apps/web`.

### Session-authenticated browser/mobile routes

These routes use:

* `createClient(request)` or `withSessionAuth(...)` for authentication
* `normalizeWorkspaceId()` for canonical workspace lookup
* `getPermissions()` when a privileged capability is involved

Examples:

* `apps/web/src/app/api/workspaces/[wsId]/route.ts`
* `apps/web/src/app/api/workspaces/[wsId]/members/route.ts`
* many `apps/web/src/app/api/.../workspaces/[wsId]/...` handlers

### Workspace API key routes

SDK-facing routes use `withApiAuth(...)` from `apps/web/src/lib/api-middleware.ts`.

The middleware:

1. extracts the API key from `Authorization`
2. validates it against `workspace_api_keys`
3. loads role-derived and default permissions for that key
4. enforces rate limits and IP bans
5. rejects requests whose `[wsId]` does not match the API key's bound workspace

That keeps the permission vocabulary identical between browser/session access and API-key access.

## Split Between Session Client And Admin Client

A recurring pattern in the helpers is:

* authenticate with the request-scoped or cookie-scoped Supabase client
* then read supporting tables with an admin client when richer joins or privileged reads are needed

Examples:

* `getPermissions()` authenticates with a normal client but reads role/default data through an admin client.
* `getWorkspace()` authenticates first, then may use an admin client for the workspace fetch when requested.

This is intentional. It preserves the caller identity while still allowing the app to assemble permission state that would be awkward to fetch purely through RLS-limited joins.

Name every `createAdminClient()` local `sbAdmin`, not `supabase`, so reviewers can immediately distinguish service-role access from request-scoped clients.

## Special Workspace Rules

### Personal workspaces

Personal workspaces are special in several places:

* canonical URL slug is always `personal`
* roles management is effectively bypassed in the UI
* invitations are blocked
* manual deletion is blocked
* many workspace settings pages simplify or redirect for personal mode

### Root/internal workspace

The root workspace is the internal control plane.

Common patterns:

* canonical URL slug is `internal`
* extra infrastructure permissions exist only here
* some features compare target-workspace permissions with root-workspace permissions
* root membership is often treated as the gate for platform-wide admin tooling

### Account security administration

Infrastructure exposes **Platform Admin → Account Security** only when the
operator has the root-only `manage_internal_accounts` permission. The server
rechecks that permission against the root workspace on every request and
requires the actor to use an exact `@tuturuuu.com` email address.

Use **Platform account recovery** to force-set a temporary password for any
Tuturuuu platform account by its exact email address. The internal directory
continues to limit profile, Drive, disable-access, and restore-access controls
to exact `@tuturuuu.com` accounts. Self-service access and password mutations
are rejected to reduce accidental lockouts. Passwords must never be copied into
logs, tickets, or coordination notes; share a temporary password only through
an approved secure channel.

Disabling access applies an Auth ban and does not implicitly revoke every
already-issued session. If an incident also requires session revocation, handle
that as a separate authenticated operation and verify the target carefully.

## Current Enforcement Patterns In The Codebase

Today the codebase uses a mix of patterns:

* newer surfaces centralize on `WorkspaceWrapper`, `normalizeWorkspaceId()`, and `getPermissions()`
* internal API client helpers call web routes instead of letting client components query arbitrary tables directly
* some older routes still hand-query role/default permission tables instead of calling `getPermissions()`
* some routes still rely mostly on membership + RLS and do not add a second explicit permission layer

That means the architecture is clear, but the implementation is still partly transitional. When adding new routes, prefer the shared helpers instead of reimplementing the joins manually.

## Recommended Developer Pattern

For a new workspace-scoped server page:

1. Use `WorkspaceWrapper`.
2. Use the normalized `wsId` from the wrapper callback for all DB reads.
3. Call `getPermissions({ wsId })` before rendering privileged content.
4. Gate or redirect from `containsPermission(...)` / `withoutPermission(...)`.

For a new workspace-scoped API route:

1. Authenticate with `createClient(request)` or `withSessionAuth(...)`.
2. Normalize the route param with `normalizeWorkspaceId(...)`.
3. Verify membership when needed.
4. Call `getPermissions({ wsId, request })` for privileged behavior.
5. Use `packages/internal-api` on the client instead of ad hoc browser `fetch()` contracts when the route is meant to be reused.

For a new SDK/API-key route:

1. Wrap the handler with `withApiAuth(...)`.
2. Require specific permission IDs in the middleware options when possible.
3. Reject workspace mismatches instead of trying to remap the requested workspace.

## Quick Reference

| Problem                                                   | Helper to reach for                                     |
| --------------------------------------------------------- | ------------------------------------------------------- |
| Resolve `personal` or `internal` in a route param         | `normalizeWorkspaceId()`                                |
| Validate page access and get canonical `wsId`             | `WorkspaceWrapper`                                      |
| Load a workspace only if the signed-in user belongs to it | `getWorkspace()`                                        |
| Compute fine-grained effective permissions                | `getPermissions()`                                      |
| Redirect the root URL to the user's preferred workspace   | `getUserDefaultWorkspace()` via `apps/web/src/proxy.ts` |
| Protect session-auth API routes                           | `withSessionAuth(...)`                                  |
| Protect workspace API-key routes                          | `withApiAuth(...)`                                      |

## Practical Rules To Keep In Mind

* A member can exist without any effective permissions.
* The creator always has the full catalog, even if no roles/defaults exist yet.
* `admin` is a permission bit that grants universal access through the helper.
* `workspace_users` is not the access-control table.
* Browser URLs prefer `personal` and `internal`, but DB queries should use canonical UUIDs.
* New privileged routes should reuse the shared helpers instead of reimplementing role/default joins.


# Components
Source: https://docs.tuturuuu.com/platform/components/overview

Reusable UI components and utilities for the Tuturuuu platform

This section contains documentation for reusable components and utilities used across the Tuturuuu platform.

## Available Components

### WorkspaceWrapper

A standardized component for handling workspace ID resolution and validation across the application.

The canonical implementation is shared from `packages/ui` at
`packages/ui/src/components/ui/custom/workspace-wrapper.tsx` and is imported as
`@tuturuuu/ui/custom/workspace-wrapper`. `apps/web/src/components/workspace-wrapper.tsx`
is a thin re-export kept for backward compatibility with existing imports.

* [WorkspaceWrapper Guide](./workspace-wrapper) - Complete documentation with examples
* [Quick Reference](./workspace-wrapper-quick-reference) - Quick reference guide

## Component Guidelines

### When to Create a Component

Create a new component when:

1. **Reusability**: The code is used in 2+ places
2. **Complexity**: The logic is complex enough to warrant separation
3. **Testing**: The component needs isolated testing
4. **Maintenance**: The component has specific maintenance requirements

### Where Components Live

Components belong in the narrowest home that fits their reuse:

* **Shared / reusable components** (used across apps) live in `packages/ui` under
  `packages/ui/src/components/ui/custom/`. For example, `WorkspaceWrapper` lives at
  `packages/ui/src/components/ui/custom/workspace-wrapper.tsx` and is imported via
  `@tuturuuu/ui/custom/workspace-wrapper`.
* **App-specific components** live in that app's `components/` directory
  (for example `apps/web/src/components/`).
* When a shared component is promoted to `packages/ui`, keep the old app path stable
  with a thin re-export so existing imports keep working — as
  `apps/web/src/components/workspace-wrapper.tsx` does for `WorkspaceWrapper`.

There is no enforced per-component folder scaffold. Most components are a single file
(co-located types and small hooks are fine inline); split into multiple files only when
size or complexity warrants it. Per the repo guidelines, split files over \~400 LOC and
components/widgets over \~200 LOC, and keep import paths stable with thin re-exports when
callers depend on them. Colocated tests live in `__tests__/` directories next to the code.

### Documentation Requirements

Each component must include:

1. **Purpose**: What the component does
2. **Props**: Complete API reference
3. **Examples**: Real-world usage examples
4. **Migration Guide**: If replacing existing patterns
5. **Best Practices**: Usage guidelines

### Naming Conventions

* **Components**: PascalCase (`WorkspaceWrapper`)
* **Files**: kebab-case (`workspace-wrapper.mdx`)
* **Props**: camelCase (`params`)
* **Types**: PascalCase with descriptive suffixes (`WorkspaceWrapperProps`)

## Contributing

When adding new components:

1. Create the component in the narrowest home that fits its reuse — `packages/ui` for
   shared/reusable components, or the app's `components/` directory for app-specific ones
2. Add comprehensive documentation
3. Include TypeScript types
4. Add tests
5. Update this overview page
6. Follow the established patterns

## Examples

See the [Examples Library](/learn/examples/overview) for practical implementation examples of all components.


# Accordion
Source: https://docs.tuturuuu.com/platform/components/ui/accordion

Preview Accordion, copy setup snippets, review examples, and inspect API exports for @tuturuuu/ui/accordion.

<Info>
  Explore the live, interactive preview at [tuturuuu.com/ui/components/accordion](https://tuturuuu.com/ui/components/accordion).
</Info>

**Category:** Layout · **Import:** `@tuturuuu/ui/accordion` · **Status:** Live preview

## Installation

Install the shared UI package, import global styles once, then import the component from its public subpath.

```bash theme={null}
bun add @tuturuuu/ui
```

```tsx theme={null}
import '@tuturuuu/ui/globals.css';
import { Accordion, AccordionItem, AccordionTrigger, AccordionContent } from '@tuturuuu/ui/accordion';
```

## Usage

Copy the default usage snippet and adapt labels, state, and event handlers to the product surface.

```tsx theme={null}
import { Accordion, AccordionContent, AccordionItem, AccordionTrigger } from '@tuturuuu/ui/accordion';

<Accordion type="single" collapsible>
  <AccordionItem value="overview">
    <AccordionTrigger>Overview</AccordionTrigger>
    <AccordionContent>Composable disclosure content.</AccordionContent>
  </AccordionItem>
</Accordion>
```

## Examples

Examples reuse the registry snippets so the docs stay aligned with the component catalog.

### Default

A minimal implementation using the current registry snippet.

```tsx theme={null}
import { Accordion, AccordionContent, AccordionItem, AccordionTrigger } from '@tuturuuu/ui/accordion';

<Accordion type="single" collapsible>
  <AccordionItem value="overview">
    <AccordionTrigger>Overview</AccordionTrigger>
    <AccordionContent>Composable disclosure content.</AccordionContent>
  </AccordionItem>
</Accordion>
```

### Composition

Use the grouped exports when the primitive has slots, triggers, content regions, or providers.

```tsx theme={null}
import {
  Accordion,
  AccordionItem,
  AccordionTrigger,
  AccordionContent,
} from '@tuturuuu/ui/accordion';
```

### Package import

Import through the public package path so workspace and external apps share the same contract.

```tsx theme={null}
// Public package import
import { Accordion } from '@tuturuuu/ui/accordion';

// Workspace apps should keep importing through the package boundary.
```

## API reference

The public exports currently available from this component entry.

| Export             | Kind      |
| ------------------ | --------- |
| `Accordion`        | component |
| `AccordionItem`    | component |
| `AccordionTrigger` | component |
| `AccordionContent` | component |

## Customization

Common props, states, and composition points to review before using this component.

* Type
* Collapsible
* Content density

## Related components

* [Aspect Ratio](./aspect-ratio)
* [Card](./card)
* [Carousel](./carousel)


# Alert
Source: https://docs.tuturuuu.com/platform/components/ui/alert

Preview Alert, copy setup snippets, review examples, and inspect API exports for @tuturuuu/ui/alert.

<Info>
  Explore the live, interactive preview at [tuturuuu.com/ui/components/alert](https://tuturuuu.com/ui/components/alert).
</Info>

**Category:** Feedback · **Import:** `@tuturuuu/ui/alert` · **Status:** Live preview

## Installation

Install the shared UI package, import global styles once, then import the component from its public subpath.

```bash theme={null}
bun add @tuturuuu/ui
```

```tsx theme={null}
import '@tuturuuu/ui/globals.css';
import { Alert, AlertTitle, AlertDescription } from '@tuturuuu/ui/alert';
```

## Usage

Copy the default usage snippet and adapt labels, state, and event handlers to the product surface.

```tsx theme={null}
import { Alert, AlertDescription, AlertTitle } from '@tuturuuu/ui/alert';

<Alert>
  <AlertTitle>Deployment ready</AlertTitle>
  <AlertDescription>All required checks have passed.</AlertDescription>
</Alert>
```

## Examples

Examples reuse the registry snippets so the docs stay aligned with the component catalog.

### Default

A minimal implementation using the current registry snippet.

```tsx theme={null}
import { Alert, AlertDescription, AlertTitle } from '@tuturuuu/ui/alert';

<Alert>
  <AlertTitle>Deployment ready</AlertTitle>
  <AlertDescription>All required checks have passed.</AlertDescription>
</Alert>
```

### Composition

Use the grouped exports when the primitive has slots, triggers, content regions, or providers.

```tsx theme={null}
import {
  Alert,
  AlertTitle,
  AlertDescription,
} from '@tuturuuu/ui/alert';
```

### Package import

Import through the public package path so workspace and external apps share the same contract.

```tsx theme={null}
// Public package import
import { Alert } from '@tuturuuu/ui/alert';

// Workspace apps should keep importing through the package boundary.
```

## API reference

The public exports currently available from this component entry.

| Export             | Kind      |
| ------------------ | --------- |
| `Alert`            | component |
| `AlertTitle`       | component |
| `AlertDescription` | component |

## Customization

Common props, states, and composition points to review before using this component.

* Variant
* Icon
* Tone

## Related components

* [Avatar](./avatar)
* [Badge](./badge)
* [Progress](./progress)


# Alert Dialog
Source: https://docs.tuturuuu.com/platform/components/ui/alert-dialog

Preview Alert Dialog, copy setup snippets, review examples, and inspect API exports for @tuturuuu/ui/alert-dialog.

<Info>
  Explore the live, interactive preview at [tuturuuu.com/ui/components/alert-dialog](https://tuturuuu.com/ui/components/alert-dialog).
</Info>

**Category:** Overlays · **Import:** `@tuturuuu/ui/alert-dialog` · **Status:** Live preview

## Installation

Install the shared UI package, import global styles once, then import the component from its public subpath.

```bash theme={null}
bun add @tuturuuu/ui
```

```tsx theme={null}
import '@tuturuuu/ui/globals.css';
import { AlertDialog, AlertDialogTrigger, AlertDialogContent } from '@tuturuuu/ui/alert-dialog';
```

## Usage

Copy the default usage snippet and adapt labels, state, and event handlers to the product surface.

```tsx theme={null}
import { AlertDialog, AlertDialogContent, AlertDialogTrigger } from '@tuturuuu/ui/alert-dialog';

<AlertDialog>
  <AlertDialogTrigger>Open confirmation</AlertDialogTrigger>
  <AlertDialogContent>Confirm the irreversible action.</AlertDialogContent>
</AlertDialog>
```

## Examples

Examples reuse the registry snippets so the docs stay aligned with the component catalog.

### Default

A minimal implementation using the current registry snippet.

```tsx theme={null}
import { AlertDialog, AlertDialogContent, AlertDialogTrigger } from '@tuturuuu/ui/alert-dialog';

<AlertDialog>
  <AlertDialogTrigger>Open confirmation</AlertDialogTrigger>
  <AlertDialogContent>Confirm the irreversible action.</AlertDialogContent>
</AlertDialog>
```

### Composition

Use the grouped exports when the primitive has slots, triggers, content regions, or providers.

```tsx theme={null}
import {
  AlertDialog,
  AlertDialogTrigger,
  AlertDialogContent,
} from '@tuturuuu/ui/alert-dialog';
```

### Package import

Import through the public package path so workspace and external apps share the same contract.

```tsx theme={null}
// Public package import
import { AlertDialog } from '@tuturuuu/ui/alert-dialog';

// Workspace apps should keep importing through the package boundary.
```

## API reference

The public exports currently available from this component entry.

| Export               | Kind      |
| -------------------- | --------- |
| `AlertDialog`        | component |
| `AlertDialogTrigger` | component |
| `AlertDialogContent` | component |

## Customization

Common props, states, and composition points to review before using this component.

* Trigger
* Destructive action
* Copy

## Related components

* [Context Menu](./context-menu)
* [Dialog](./dialog)
* [Drawer](./drawer)


# Aspect Ratio
Source: https://docs.tuturuuu.com/platform/components/ui/aspect-ratio

Preview Aspect Ratio, copy setup snippets, review examples, and inspect API exports for @tuturuuu/ui/aspect-ratio.

<Info>
  Explore the live, interactive preview at [tuturuuu.com/ui/components/aspect-ratio](https://tuturuuu.com/ui/components/aspect-ratio).
</Info>

**Category:** Layout · **Import:** `@tuturuuu/ui/aspect-ratio` · **Status:** Live preview

## Installation

Install the shared UI package, import global styles once, then import the component from its public subpath.

```bash theme={null}
bun add @tuturuuu/ui
```

```tsx theme={null}
import '@tuturuuu/ui/globals.css';
import { AspectRatio } from '@tuturuuu/ui/aspect-ratio';
```

## Usage

Copy the default usage snippet and adapt labels, state, and event handlers to the product surface.

```tsx theme={null}
import { AspectRatio } from '@tuturuuu/ui/aspect-ratio';

<AspectRatio ratio={16 / 9}>
  <img src="/preview.png" alt="" className="h-full w-full object-cover" />
</AspectRatio>
```

## Examples

Examples reuse the registry snippets so the docs stay aligned with the component catalog.

### Default

A minimal implementation using the current registry snippet.

```tsx theme={null}
import { AspectRatio } from '@tuturuuu/ui/aspect-ratio';

<AspectRatio ratio={16 / 9}>
  <img src="/preview.png" alt="" className="h-full w-full object-cover" />
</AspectRatio>
```

### Package import

Import through the public package path so workspace and external apps share the same contract.

```tsx theme={null}
// Public package import
import { AspectRatio } from '@tuturuuu/ui/aspect-ratio';

// Workspace apps should keep importing through the package boundary.
```

## API reference

The public exports currently available from this component entry.

| Export        | Kind      |
| ------------- | --------- |
| `AspectRatio` | component |

## Customization

Common props, states, and composition points to review before using this component.

* Ratio
* Media
* Radius

## Related components

* [Accordion](./accordion)
* [Card](./card)
* [Carousel](./carousel)


# Avatar
Source: https://docs.tuturuuu.com/platform/components/ui/avatar

Preview Avatar, copy setup snippets, review examples, and inspect API exports for @tuturuuu/ui/avatar.

<Info>
  Explore the live, interactive preview at [tuturuuu.com/ui/components/avatar](https://tuturuuu.com/ui/components/avatar).
</Info>

**Category:** Feedback · **Import:** `@tuturuuu/ui/avatar` · **Status:** Live preview

## Installation

Install the shared UI package, import global styles once, then import the component from its public subpath.

```bash theme={null}
bun add @tuturuuu/ui
```

```tsx theme={null}
import '@tuturuuu/ui/globals.css';
import { Avatar, AvatarImage, AvatarFallback } from '@tuturuuu/ui/avatar';
```

## Usage

Copy the default usage snippet and adapt labels, state, and event handlers to the product surface.

```tsx theme={null}
import { Avatar, AvatarFallback, AvatarImage } from '@tuturuuu/ui/avatar';

<Avatar>
  <AvatarImage src="/avatar.png" alt="User" />
  <AvatarFallback>TT</AvatarFallback>
</Avatar>
```

## Examples

Examples reuse the registry snippets so the docs stay aligned with the component catalog.

### Default

A minimal implementation using the current registry snippet.

```tsx theme={null}
import { Avatar, AvatarFallback, AvatarImage } from '@tuturuuu/ui/avatar';

<Avatar>
  <AvatarImage src="/avatar.png" alt="User" />
  <AvatarFallback>TT</AvatarFallback>
</Avatar>
```

### Composition

Use the grouped exports when the primitive has slots, triggers, content regions, or providers.

```tsx theme={null}
import {
  Avatar,
  AvatarImage,
  AvatarFallback,
} from '@tuturuuu/ui/avatar';
```

### Package import

Import through the public package path so workspace and external apps share the same contract.

```tsx theme={null}
// Public package import
import { Avatar } from '@tuturuuu/ui/avatar';

// Workspace apps should keep importing through the package boundary.
```

## API reference

The public exports currently available from this component entry.

| Export           | Kind      |
| ---------------- | --------- |
| `Avatar`         | component |
| `AvatarImage`    | component |
| `AvatarFallback` | component |

## Customization

Common props, states, and composition points to review before using this component.

* Size
* Fallback
* Stacking

## Related components

* [Alert](./alert)
* [Badge](./badge)
* [Progress](./progress)


# Badge
Source: https://docs.tuturuuu.com/platform/components/ui/badge

Preview Badge, copy setup snippets, review examples, and inspect API exports for @tuturuuu/ui/badge.

<Info>
  Explore the live, interactive preview at [tuturuuu.com/ui/components/badge](https://tuturuuu.com/ui/components/badge).
</Info>

**Category:** Feedback · **Import:** `@tuturuuu/ui/badge` · **Status:** Live preview

## Installation

Install the shared UI package, import global styles once, then import the component from its public subpath.

```bash theme={null}
bun add @tuturuuu/ui
```

```tsx theme={null}
import '@tuturuuu/ui/globals.css';
import { Badge } from '@tuturuuu/ui/badge';
```

## Usage

Copy the default usage snippet and adapt labels, state, and event handlers to the product surface.

```tsx theme={null}
import { Badge } from '@tuturuuu/ui/badge';

<Badge variant="secondary">Beta</Badge>
```

## Examples

Examples reuse the registry snippets so the docs stay aligned with the component catalog.

### Default

A minimal implementation using the current registry snippet.

```tsx theme={null}
import { Badge } from '@tuturuuu/ui/badge';

<Badge variant="secondary">Beta</Badge>
```

### Package import

Import through the public package path so workspace and external apps share the same contract.

```tsx theme={null}
// Public package import
import { Badge } from '@tuturuuu/ui/badge';

// Workspace apps should keep importing through the package boundary.
```

## API reference

The public exports currently available from this component entry.

| Export  | Kind      |
| ------- | --------- |
| `Badge` | component |

## Customization

Common props, states, and composition points to review before using this component.

* Variant
* Tone
* Icon

## Related components

* [Alert](./alert)
* [Avatar](./avatar)
* [Progress](./progress)


# Breadcrumb
Source: https://docs.tuturuuu.com/platform/components/ui/breadcrumb

Preview Breadcrumb, copy setup snippets, review examples, and inspect API exports for @tuturuuu/ui/breadcrumb.

<Info>
  Explore the live, interactive preview at [tuturuuu.com/ui/components/breadcrumb](https://tuturuuu.com/ui/components/breadcrumb).
</Info>

**Category:** Navigation · **Import:** `@tuturuuu/ui/breadcrumb` · **Status:** Live preview

## Installation

Install the shared UI package, import global styles once, then import the component from its public subpath.

```bash theme={null}
bun add @tuturuuu/ui
```

```tsx theme={null}
import '@tuturuuu/ui/globals.css';
import { Breadcrumb, BreadcrumbList, BreadcrumbItem, BreadcrumbLink } from '@tuturuuu/ui/breadcrumb';
```

## Usage

Copy the default usage snippet and adapt labels, state, and event handlers to the product surface.

```tsx theme={null}
import { Breadcrumb, BreadcrumbItem, BreadcrumbLink, BreadcrumbList } from '@tuturuuu/ui/breadcrumb';

<Breadcrumb>
  <BreadcrumbList>
    <BreadcrumbItem><BreadcrumbLink href="/">Home</BreadcrumbLink></BreadcrumbItem>
  </BreadcrumbList>
</Breadcrumb>
```

## Examples

Examples reuse the registry snippets so the docs stay aligned with the component catalog.

### Default

A minimal implementation using the current registry snippet.

```tsx theme={null}
import { Breadcrumb, BreadcrumbItem, BreadcrumbLink, BreadcrumbList } from '@tuturuuu/ui/breadcrumb';

<Breadcrumb>
  <BreadcrumbList>
    <BreadcrumbItem><BreadcrumbLink href="/">Home</BreadcrumbLink></BreadcrumbItem>
  </BreadcrumbList>
</Breadcrumb>
```

### Composition

Use the grouped exports when the primitive has slots, triggers, content regions, or providers.

```tsx theme={null}
import {
  Breadcrumb,
  BreadcrumbList,
  BreadcrumbItem,
  BreadcrumbLink,
} from '@tuturuuu/ui/breadcrumb';
```

### Package import

Import through the public package path so workspace and external apps share the same contract.

```tsx theme={null}
// Public package import
import { Breadcrumb } from '@tuturuuu/ui/breadcrumb';

// Workspace apps should keep importing through the package boundary.
```

## API reference

The public exports currently available from this component entry.

| Export           | Kind      |
| ---------------- | --------- |
| `Breadcrumb`     | component |
| `BreadcrumbList` | component |
| `BreadcrumbItem` | component |
| `BreadcrumbLink` | component |

## Customization

Common props, states, and composition points to review before using this component.

* Separator
* Current item
* Overflow

## Related components

* [Command](./command)
* [Quick Command Center](./quick-command-center)
* [Menubar](./menubar)


# Button
Source: https://docs.tuturuuu.com/platform/components/ui/button

Preview Button, copy setup snippets, review examples, and inspect API exports for @tuturuuu/ui/button.

<Info>
  Explore the live, interactive preview at [tuturuuu.com/ui/components/button](https://tuturuuu.com/ui/components/button).
</Info>

**Category:** Actions · **Import:** `@tuturuuu/ui/button` · **Status:** Live preview

## Installation

Install the shared UI package, import global styles once, then import the component from its public subpath.

```bash theme={null}
bun add @tuturuuu/ui
```

```tsx theme={null}
import '@tuturuuu/ui/globals.css';
import { Button, buttonVariants } from '@tuturuuu/ui/button';
```

## Usage

Copy the default usage snippet and adapt labels, state, and event handlers to the product surface.

```tsx theme={null}
import { Button } from '@tuturuuu/ui/button';

<Button variant="default" size="sm">Create workspace</Button>
```

## Examples

Examples reuse the registry snippets so the docs stay aligned with the component catalog.

### Default

A minimal implementation using the current registry snippet.

```tsx theme={null}
import { Button } from '@tuturuuu/ui/button';

<Button variant="default" size="sm">Create workspace</Button>
```

### Composition

Use the grouped exports when the primitive has slots, triggers, content regions, or providers.

```tsx theme={null}
import {
  Button,
  buttonVariants,
} from '@tuturuuu/ui/button';
```

### Package import

Import through the public package path so workspace and external apps share the same contract.

```tsx theme={null}
// Public package import
import { Button } from '@tuturuuu/ui/button';

// Workspace apps should keep importing through the package boundary.
```

## API reference

The public exports currently available from this component entry.

| Export           | Kind      |
| ---------------- | --------- |
| `Button`         | component |
| `buttonVariants` | helper    |

## Customization

Common props, states, and composition points to review before using this component.

* Variant
* Size
* Icon

## Related components

* [Toggle](./toggle)
* [Toggle Group](./toggle-group)
* [Accordion](./accordion)


# Calendar
Source: https://docs.tuturuuu.com/platform/components/ui/calendar

Preview Calendar, copy setup snippets, review examples, and inspect API exports for @tuturuuu/ui/calendar.

<Info>
  Explore the live, interactive preview at [tuturuuu.com/ui/components/calendar](https://tuturuuu.com/ui/components/calendar).
</Info>

**Category:** Inputs · **Import:** `@tuturuuu/ui/calendar` · **Status:** Live preview

## Installation

Install the shared UI package, import global styles once, then import the component from its public subpath.

```bash theme={null}
bun add @tuturuuu/ui
```

```tsx theme={null}
import '@tuturuuu/ui/globals.css';
import { Calendar } from '@tuturuuu/ui/calendar';
```

## Usage

Copy the default usage snippet and adapt labels, state, and event handlers to the product surface.

```tsx theme={null}
import { Calendar } from '@tuturuuu/ui/calendar';

<Calendar mode="single" selected={date} onSelect={setDate} />
```

## Examples

Examples reuse the registry snippets so the docs stay aligned with the component catalog.

### Default

A minimal implementation using the current registry snippet.

```tsx theme={null}
import { Calendar } from '@tuturuuu/ui/calendar';

<Calendar mode="single" selected={date} onSelect={setDate} />
```

### Package import

Import through the public package path so workspace and external apps share the same contract.

```tsx theme={null}
// Public package import
import { Calendar } from '@tuturuuu/ui/calendar';

// Workspace apps should keep importing through the package boundary.
```

## API reference

The public exports currently available from this component entry.

| Export     | Kind      |
| ---------- | --------- |
| `Calendar` | component |

## Customization

Common props, states, and composition points to review before using this component.

* Mode
* Timezone
* Week start

## Related components

* [Checkbox](./checkbox)
* [Color Picker](./color-picker)
* [Currency Input](./currency-input)


# Card
Source: https://docs.tuturuuu.com/platform/components/ui/card

Preview Card, copy setup snippets, review examples, and inspect API exports for @tuturuuu/ui/card.

<Info>
  Explore the live, interactive preview at [tuturuuu.com/ui/components/card](https://tuturuuu.com/ui/components/card).
</Info>

**Category:** Layout · **Import:** `@tuturuuu/ui/card` · **Status:** Live preview

## Installation

Install the shared UI package, import global styles once, then import the component from its public subpath.

```bash theme={null}
bun add @tuturuuu/ui
```

```tsx theme={null}
import '@tuturuuu/ui/globals.css';
import { Card, CardHeader, CardTitle, CardDescription, CardContent, CardFooter } from '@tuturuuu/ui/card';
```

## Usage

Copy the default usage snippet and adapt labels, state, and event handlers to the product surface.

```tsx theme={null}
import { Card, CardContent, CardHeader, CardTitle } from '@tuturuuu/ui/card';

<Card>
  <CardHeader><CardTitle>Workspace</CardTitle></CardHeader>
  <CardContent>Summary content</CardContent>
</Card>
```

## Examples

Examples reuse the registry snippets so the docs stay aligned with the component catalog.

### Default

A minimal implementation using the current registry snippet.

```tsx theme={null}
import { Card, CardContent, CardHeader, CardTitle } from '@tuturuuu/ui/card';

<Card>
  <CardHeader><CardTitle>Workspace</CardTitle></CardHeader>
  <CardContent>Summary content</CardContent>
</Card>
```

### Composition

Use the grouped exports when the primitive has slots, triggers, content regions, or providers.

```tsx theme={null}
import {
  Card,
  CardHeader,
  CardTitle,
  CardDescription,
  CardContent,
  CardFooter,
} from '@tuturuuu/ui/card';
```

### Package import

Import through the public package path so workspace and external apps share the same contract.

```tsx theme={null}
// Public package import
import { Card } from '@tuturuuu/ui/card';

// Workspace apps should keep importing through the package boundary.
```

## API reference

The public exports currently available from this component entry.

| Export            | Kind      |
| ----------------- | --------- |
| `Card`            | component |
| `CardHeader`      | component |
| `CardTitle`       | component |
| `CardDescription` | component |
| `CardContent`     | component |
| `CardFooter`      | component |

## Customization

Common props, states, and composition points to review before using this component.

* Header
* Content
* Footer

## Related components

* [Accordion](./accordion)
* [Aspect Ratio](./aspect-ratio)
* [Carousel](./carousel)


# Carousel
Source: https://docs.tuturuuu.com/platform/components/ui/carousel

Preview Carousel, copy setup snippets, review examples, and inspect API exports for @tuturuuu/ui/carousel.

<Info>
  Explore the live, interactive preview at [tuturuuu.com/ui/components/carousel](https://tuturuuu.com/ui/components/carousel).
</Info>

**Category:** Layout · **Import:** `@tuturuuu/ui/carousel` · **Status:** Live preview

## Installation

Install the shared UI package, import global styles once, then import the component from its public subpath.

```bash theme={null}
bun add @tuturuuu/ui
```

```tsx theme={null}
import '@tuturuuu/ui/globals.css';
import { Carousel, CarouselContent, CarouselItem, CarouselNext, CarouselPrevious } from '@tuturuuu/ui/carousel';
```

## Usage

Copy the default usage snippet and adapt labels, state, and event handlers to the product surface.

```tsx theme={null}
import { Carousel, CarouselContent, CarouselItem } from '@tuturuuu/ui/carousel';

<Carousel opts={{ align: 'start' }}>
  <CarouselContent>
    <CarouselItem>Slide content</CarouselItem>
  </CarouselContent>
</Carousel>
```

## Examples

Examples reuse the registry snippets so the docs stay aligned with the component catalog.

### Default

A minimal implementation using the current registry snippet.

```tsx theme={null}
import { Carousel, CarouselContent, CarouselItem } from '@tuturuuu/ui/carousel';

<Carousel opts={{ align: 'start' }}>
  <CarouselContent>
    <CarouselItem>Slide content</CarouselItem>
  </CarouselContent>
</Carousel>
```

### Composition

Use the grouped exports when the primitive has slots, triggers, content regions, or providers.

```tsx theme={null}
import {
  Carousel,
  CarouselContent,
  CarouselItem,
  CarouselNext,
  CarouselPrevious,
} from '@tuturuuu/ui/carousel';
```

### Package import

Import through the public package path so workspace and external apps share the same contract.

```tsx theme={null}
// Public package import
import { Carousel } from '@tuturuuu/ui/carousel';

// Workspace apps should keep importing through the package boundary.
```

## API reference

The public exports currently available from this component entry.

| Export             | Kind      |
| ------------------ | --------- |
| `Carousel`         | component |
| `CarouselContent`  | component |
| `CarouselItem`     | component |
| `CarouselNext`     | component |
| `CarouselPrevious` | component |

## Customization

Common props, states, and composition points to review before using this component.

* Orientation
* Slides
* Controls

## Related components

* [Accordion](./accordion)
* [Aspect Ratio](./aspect-ratio)
* [Card](./card)


# Chart
Source: https://docs.tuturuuu.com/platform/components/ui/chart

Preview Chart, copy setup snippets, review examples, and inspect API exports for @tuturuuu/ui/chart.

<Info>
  Explore the live, interactive preview at [tuturuuu.com/ui/components/chart](https://tuturuuu.com/ui/components/chart).
</Info>

**Category:** Data · **Import:** `@tuturuuu/ui/chart` · **Status:** Live preview

## Installation

Install the shared UI package, import global styles once, then import the component from its public subpath.

```bash theme={null}
bun add @tuturuuu/ui
```

```tsx theme={null}
import '@tuturuuu/ui/globals.css';
import { ChartContainer, ChartTooltip, ChartTooltipContent } from '@tuturuuu/ui/chart';
```

## Usage

Copy the default usage snippet and adapt labels, state, and event handlers to the product surface.

```tsx theme={null}
import { ChartContainer, ChartTooltip, ChartTooltipContent } from '@tuturuuu/ui/chart';

<ChartContainer config={{ work: { label: 'Work', color: 'hsl(var(--primary))' } }}>
  <BarChart data={data}>
    <ChartTooltip content={<ChartTooltipContent />} />
  </BarChart>
</ChartContainer>
```

## Examples

Examples reuse the registry snippets so the docs stay aligned with the component catalog.

### Default

A minimal implementation using the current registry snippet.

```tsx theme={null}
import { ChartContainer, ChartTooltip, ChartTooltipContent } from '@tuturuuu/ui/chart';

<ChartContainer config={{ work: { label: 'Work', color: 'hsl(var(--primary))' } }}>
  <BarChart data={data}>
    <ChartTooltip content={<ChartTooltipContent />} />
  </BarChart>
</ChartContainer>
```

### Composition

Use the grouped exports when the primitive has slots, triggers, content regions, or providers.

```tsx theme={null}
import {
  ChartContainer,
  ChartTooltip,
  ChartTooltipContent,
} from '@tuturuuu/ui/chart';
```

### Package import

Import through the public package path so workspace and external apps share the same contract.

```tsx theme={null}
// Public package import
import { ChartContainer } from '@tuturuuu/ui/chart';

// Workspace apps should keep importing through the package boundary.
```

## API reference

The public exports currently available from this component entry.

| Export                | Kind      |
| --------------------- | --------- |
| `ChartContainer`      | component |
| `ChartTooltip`        | component |
| `ChartTooltipContent` | component |

## Customization

Common props, states, and composition points to review before using this component.

* Series
* Theme
* Tooltip

## Related components

* [Diff Viewer](./diff-viewer)
* [Table](./table)
* [Accordion](./accordion)


# Checkbox
Source: https://docs.tuturuuu.com/platform/components/ui/checkbox

Preview Checkbox, copy setup snippets, review examples, and inspect API exports for @tuturuuu/ui/checkbox.

<Info>
  Explore the live, interactive preview at [tuturuuu.com/ui/components/checkbox](https://tuturuuu.com/ui/components/checkbox).
</Info>

**Category:** Inputs · **Import:** `@tuturuuu/ui/checkbox` · **Status:** Live preview

## Installation

Install the shared UI package, import global styles once, then import the component from its public subpath.

```bash theme={null}
bun add @tuturuuu/ui
```

```tsx theme={null}
import '@tuturuuu/ui/globals.css';
import { Checkbox } from '@tuturuuu/ui/checkbox';
```

## Usage

Copy the default usage snippet and adapt labels, state, and event handlers to the product surface.

```tsx theme={null}
import { Checkbox } from '@tuturuuu/ui/checkbox';

<Checkbox id="terms" defaultChecked />
```

## Examples

Examples reuse the registry snippets so the docs stay aligned with the component catalog.

### Default

A minimal implementation using the current registry snippet.

```tsx theme={null}
import { Checkbox } from '@tuturuuu/ui/checkbox';

<Checkbox id="terms" defaultChecked />
```

### Package import

Import through the public package path so workspace and external apps share the same contract.

```tsx theme={null}
// Public package import
import { Checkbox } from '@tuturuuu/ui/checkbox';

// Workspace apps should keep importing through the package boundary.
```

## API reference

The public exports currently available from this component entry.

| Export     | Kind      |
| ---------- | --------- |
| `Checkbox` | component |

## Customization

Common props, states, and composition points to review before using this component.

* Checked state
* Disabled state
* Label

## Related components

* [Calendar](./calendar)
* [Color Picker](./color-picker)
* [Currency Input](./currency-input)


# Code Block
Source: https://docs.tuturuuu.com/platform/components/ui/codeblock

Preview Code Block, copy setup snippets, review examples, and inspect API exports for @tuturuuu/ui/codeblock.

<Info>
  Explore the live, interactive preview at [tuturuuu.com/ui/components/codeblock](https://tuturuuu.com/ui/components/codeblock).
</Info>

**Category:** Typography · **Import:** `@tuturuuu/ui/codeblock` · **Status:** Pattern preview

## Installation

Install the shared UI package, import global styles once, then import the component from its public subpath.

```bash theme={null}
bun add @tuturuuu/ui
```

```tsx theme={null}
import '@tuturuuu/ui/globals.css';
import { CodeBlock } from '@tuturuuu/ui/codeblock';
```

## Usage

Copy the default usage snippet and adapt labels, state, and event handlers to the product surface.

```tsx theme={null}
import { CodeBlock } from '@tuturuuu/ui/codeblock';

<CodeBlock language="tsx" value={"<Button>Save</Button>"} />
```

## Examples

Examples reuse the registry snippets so the docs stay aligned with the component catalog.

### Default

A minimal implementation using the current registry snippet.

```tsx theme={null}
import { CodeBlock } from '@tuturuuu/ui/codeblock';

<CodeBlock language="tsx" value={"<Button>Save</Button>"} />
```

### Package import

Import through the public package path so workspace and external apps share the same contract.

```tsx theme={null}
// Public package import
import { CodeBlock } from '@tuturuuu/ui/codeblock';

// Workspace apps should keep importing through the package boundary.
```

## API reference

The public exports currently available from this component entry.

| Export      | Kind      |
| ----------- | --------- |
| `CodeBlock` | component |

## Customization

Common props, states, and composition points to review before using this component.

* Language
* Theme
* Line numbers

## Related components

* [Kbd](./kbd)
* [Markdown](./markdown)
* [Accordion](./accordion)


# Collapsible
Source: https://docs.tuturuuu.com/platform/components/ui/collapsible

Preview Collapsible, copy setup snippets, review examples, and inspect API exports for @tuturuuu/ui/collapsible.

<Info>
  Explore the live, interactive preview at [tuturuuu.com/ui/components/collapsible](https://tuturuuu.com/ui/components/collapsible).
</Info>

**Category:** Layout · **Import:** `@tuturuuu/ui/collapsible` · **Status:** Live preview

## Installation

Install the shared UI package, import global styles once, then import the component from its public subpath.

```bash theme={null}
bun add @tuturuuu/ui
```

```tsx theme={null}
import '@tuturuuu/ui/globals.css';
import { Collapsible, CollapsibleTrigger, CollapsibleContent } from '@tuturuuu/ui/collapsible';
```

## Usage

Copy the default usage snippet and adapt labels, state, and event handlers to the product surface.

```tsx theme={null}
import { Collapsible, CollapsibleContent, CollapsibleTrigger } from '@tuturuuu/ui/collapsible';

<Collapsible>
  <CollapsibleTrigger>Toggle details</CollapsibleTrigger>
  <CollapsibleContent>Hidden content</CollapsibleContent>
</Collapsible>
```

## Examples

Examples reuse the registry snippets so the docs stay aligned with the component catalog.

### Default

A minimal implementation using the current registry snippet.

```tsx theme={null}
import { Collapsible, CollapsibleContent, CollapsibleTrigger } from '@tuturuuu/ui/collapsible';

<Collapsible>
  <CollapsibleTrigger>Toggle details</CollapsibleTrigger>
  <CollapsibleContent>Hidden content</CollapsibleContent>
</Collapsible>
```

### Composition

Use the grouped exports when the primitive has slots, triggers, content regions, or providers.

```tsx theme={null}
import {
  Collapsible,
  CollapsibleTrigger,
  CollapsibleContent,
} from '@tuturuuu/ui/collapsible';
```

### Package import

Import through the public package path so workspace and external apps share the same contract.

```tsx theme={null}
// Public package import
import { Collapsible } from '@tuturuuu/ui/collapsible';

// Workspace apps should keep importing through the package boundary.
```

## API reference

The public exports currently available from this component entry.

| Export               | Kind      |
| -------------------- | --------- |
| `Collapsible`        | component |
| `CollapsibleTrigger` | component |
| `CollapsibleContent` | component |

## Customization

Common props, states, and composition points to review before using this component.

* Open state
* Trigger
* Content density

## Related components

* [Accordion](./accordion)
* [Aspect Ratio](./aspect-ratio)
* [Card](./card)


# Color Picker
Source: https://docs.tuturuuu.com/platform/components/ui/color-picker

Preview Color Picker, copy setup snippets, review examples, and inspect API exports for @tuturuuu/ui/color-picker.

<Info>
  Explore the live, interactive preview at [tuturuuu.com/ui/components/color-picker](https://tuturuuu.com/ui/components/color-picker).
</Info>

**Category:** Inputs · **Import:** `@tuturuuu/ui/color-picker` · **Status:** Live preview

## Installation

Install the shared UI package, import global styles once, then import the component from its public subpath.

```bash theme={null}
bun add @tuturuuu/ui
```

```tsx theme={null}
import '@tuturuuu/ui/globals.css';
import { ColorPicker, ensureVisibleColor } from '@tuturuuu/ui/color-picker';
```

## Usage

Copy the default usage snippet and adapt labels, state, and event handlers to the product surface.

```tsx theme={null}
import { ColorPicker } from '@tuturuuu/ui/color-picker';

<ColorPicker value={color} onChange={setColor} />
```

## Examples

Examples reuse the registry snippets so the docs stay aligned with the component catalog.

### Default

A minimal implementation using the current registry snippet.

```tsx theme={null}
import { ColorPicker } from '@tuturuuu/ui/color-picker';

<ColorPicker value={color} onChange={setColor} />
```

### Composition

Use the grouped exports when the primitive has slots, triggers, content regions, or providers.

```tsx theme={null}
import {
  ColorPicker,
  ensureVisibleColor,
} from '@tuturuuu/ui/color-picker';
```

### Package import

Import through the public package path so workspace and external apps share the same contract.

```tsx theme={null}
// Public package import
import { ColorPicker } from '@tuturuuu/ui/color-picker';

// Workspace apps should keep importing through the package boundary.
```

## API reference

The public exports currently available from this component entry.

| Export               | Kind      |
| -------------------- | --------- |
| `ColorPicker`        | component |
| `ensureVisibleColor` | helper    |

## Customization

Common props, states, and composition points to review before using this component.

* Value
* Contrast
* Disabled state

## Related components

* [Calendar](./calendar)
* [Checkbox](./checkbox)
* [Currency Input](./currency-input)


# Command
Source: https://docs.tuturuuu.com/platform/components/ui/command

Preview Command, copy setup snippets, review examples, and inspect API exports for @tuturuuu/ui/command.

<Info>
  Explore the live, interactive preview at [tuturuuu.com/ui/components/command](https://tuturuuu.com/ui/components/command).
</Info>

**Category:** Navigation · **Import:** `@tuturuuu/ui/command` · **Status:** Live preview

## Installation

Install the shared UI package, import global styles once, then import the component from its public subpath.

```bash theme={null}
bun add @tuturuuu/ui
```

```tsx theme={null}
import '@tuturuuu/ui/globals.css';
import { Command, CommandInput, CommandItem, CommandList } from '@tuturuuu/ui/command';
```

## Usage

Copy the default usage snippet and adapt labels, state, and event handlers to the product surface.

```tsx theme={null}
import { Command, CommandInput, CommandItem, CommandList } from '@tuturuuu/ui/command';

<Command>
  <CommandInput placeholder="Search..." />
  <CommandList><CommandItem>Open dashboard</CommandItem></CommandList>
</Command>
```

## Examples

Examples reuse the registry snippets so the docs stay aligned with the component catalog.

### Default

A minimal implementation using the current registry snippet.

```tsx theme={null}
import { Command, CommandInput, CommandItem, CommandList } from '@tuturuuu/ui/command';

<Command>
  <CommandInput placeholder="Search..." />
  <CommandList><CommandItem>Open dashboard</CommandItem></CommandList>
</Command>
```

### Composition

Use the grouped exports when the primitive has slots, triggers, content regions, or providers.

```tsx theme={null}
import {
  Command,
  CommandInput,
  CommandItem,
  CommandList,
} from '@tuturuuu/ui/command';
```

### Package import

Import through the public package path so workspace and external apps share the same contract.

```tsx theme={null}
// Public package import
import { Command } from '@tuturuuu/ui/command';

// Workspace apps should keep importing through the package boundary.
```

## API reference

The public exports currently available from this component entry.

| Export         | Kind      |
| -------------- | --------- |
| `Command`      | component |
| `CommandInput` | component |
| `CommandItem`  | component |
| `CommandList`  | component |

## Customization

Common props, states, and composition points to review before using this component.

* Groups
* Empty state
* Shortcuts

## Related components

* [Breadcrumb](./breadcrumb)
* [Quick Command Center](./quick-command-center)
* [Menubar](./menubar)


# Context Menu
Source: https://docs.tuturuuu.com/platform/components/ui/context-menu

Preview Context Menu, copy setup snippets, review examples, and inspect API exports for @tuturuuu/ui/context-menu.

<Info>
  Explore the live, interactive preview at [tuturuuu.com/ui/components/context-menu](https://tuturuuu.com/ui/components/context-menu).
</Info>

**Category:** Overlays · **Import:** `@tuturuuu/ui/context-menu` · **Status:** Live preview

## Installation

Install the shared UI package, import global styles once, then import the component from its public subpath.

```bash theme={null}
bun add @tuturuuu/ui
```

```tsx theme={null}
import '@tuturuuu/ui/globals.css';
import { ContextMenu, ContextMenuTrigger, ContextMenuContent } from '@tuturuuu/ui/context-menu';
```

## Usage

Copy the default usage snippet and adapt labels, state, and event handlers to the product surface.

```tsx theme={null}
import { ContextMenu, ContextMenuContent, ContextMenuItem, ContextMenuTrigger } from '@tuturuuu/ui/context-menu';

<ContextMenu>
  <ContextMenuTrigger>Right click area</ContextMenuTrigger>
  <ContextMenuContent><ContextMenuItem>Duplicate</ContextMenuItem></ContextMenuContent>
</ContextMenu>
```

## Examples

Examples reuse the registry snippets so the docs stay aligned with the component catalog.

### Default

A minimal implementation using the current registry snippet.

```tsx theme={null}
import { ContextMenu, ContextMenuContent, ContextMenuItem, ContextMenuTrigger } from '@tuturuuu/ui/context-menu';

<ContextMenu>
  <ContextMenuTrigger>Right click area</ContextMenuTrigger>
  <ContextMenuContent><ContextMenuItem>Duplicate</ContextMenuItem></ContextMenuContent>
</ContextMenu>
```

### Composition

Use the grouped exports when the primitive has slots, triggers, content regions, or providers.

```tsx theme={null}
import {
  ContextMenu,
  ContextMenuTrigger,
  ContextMenuContent,
} from '@tuturuuu/ui/context-menu';
```

### Package import

Import through the public package path so workspace and external apps share the same contract.

```tsx theme={null}
// Public package import
import { ContextMenu } from '@tuturuuu/ui/context-menu';

// Workspace apps should keep importing through the package boundary.
```

## API reference

The public exports currently available from this component entry.

| Export               | Kind      |
| -------------------- | --------- |
| `ContextMenu`        | component |
| `ContextMenuTrigger` | component |
| `ContextMenuContent` | component |

## Customization

Common props, states, and composition points to review before using this component.

* Items
* Shortcuts
* Danger zone

## Related components

* [Alert Dialog](./alert-dialog)
* [Dialog](./dialog)
* [Drawer](./drawer)


# Currency Input
Source: https://docs.tuturuuu.com/platform/components/ui/currency-input

Preview Currency Input, copy setup snippets, review examples, and inspect API exports for @tuturuuu/ui/currency-input.

<Info>
  Explore the live, interactive preview at [tuturuuu.com/ui/components/currency-input](https://tuturuuu.com/ui/components/currency-input).
</Info>

**Category:** Inputs · **Import:** `@tuturuuu/ui/currency-input` · **Status:** Live preview

## Installation

Install the shared UI package, import global styles once, then import the component from its public subpath.

```bash theme={null}
bun add @tuturuuu/ui
```

```tsx theme={null}
import '@tuturuuu/ui/globals.css';
import { CurrencyInput } from '@tuturuuu/ui/currency-input';
```

## Usage

Copy the default usage snippet and adapt labels, state, and event handlers to the product surface.

```tsx theme={null}
import { CurrencyInput } from '@tuturuuu/ui/currency-input';

<CurrencyInput value={amount} onChange={setAmount} currencySymbol="$" />
```

## Examples

Examples reuse the registry snippets so the docs stay aligned with the component catalog.

### Default

A minimal implementation using the current registry snippet.

```tsx theme={null}
import { CurrencyInput } from '@tuturuuu/ui/currency-input';

<CurrencyInput value={amount} onChange={setAmount} currencySymbol="$" />
```

### Package import

Import through the public package path so workspace and external apps share the same contract.

```tsx theme={null}
// Public package import
import { CurrencyInput } from '@tuturuuu/ui/currency-input';

// Workspace apps should keep importing through the package boundary.
```

## API reference

The public exports currently available from this component entry.

| Export          | Kind      |
| --------------- | --------- |
| `CurrencyInput` | component |

## Customization

Common props, states, and composition points to review before using this component.

* Locale
* Symbol
* Helpers

## Related components

* [Calendar](./calendar)
* [Checkbox](./checkbox)
* [Color Picker](./color-picker)


# Date Time Picker
Source: https://docs.tuturuuu.com/platform/components/ui/date-time-picker

Preview Date Time Picker, copy setup snippets, review examples, and inspect API exports for @tuturuuu/ui/date-time-picker.

<Info>
  Explore the live, interactive preview at [tuturuuu.com/ui/components/date-time-picker](https://tuturuuu.com/ui/components/date-time-picker).
</Info>

**Category:** Inputs · **Import:** `@tuturuuu/ui/date-time-picker` · **Status:** Live preview

## Installation

Install the shared UI package, import global styles once, then import the component from its public subpath.

```bash theme={null}
bun add @tuturuuu/ui
```

```tsx theme={null}
import '@tuturuuu/ui/globals.css';
import { DateTimePicker } from '@tuturuuu/ui/date-time-picker';
```

## Usage

Copy the default usage snippet and adapt labels, state, and event handlers to the product surface.

```tsx theme={null}
import { DateTimePicker } from '@tuturuuu/ui/date-time-picker';

<DateTimePicker date={date} setDate={setDate} showTimeSelect />
```

## Examples

Examples reuse the registry snippets so the docs stay aligned with the component catalog.

### Default

A minimal implementation using the current registry snippet.

```tsx theme={null}
import { DateTimePicker } from '@tuturuuu/ui/date-time-picker';

<DateTimePicker date={date} setDate={setDate} showTimeSelect />
```

### Package import

Import through the public package path so workspace and external apps share the same contract.

```tsx theme={null}
// Public package import
import { DateTimePicker } from '@tuturuuu/ui/date-time-picker';

// Workspace apps should keep importing through the package boundary.
```

## API reference

The public exports currently available from this component entry.

| Export           | Kind      |
| ---------------- | --------- |
| `DateTimePicker` | component |

## Customization

Common props, states, and composition points to review before using this component.

* Timezone
* Time format
* Inline mode

## Related components

* [Calendar](./calendar)
* [Checkbox](./checkbox)
* [Color Picker](./color-picker)


# Dialog
Source: https://docs.tuturuuu.com/platform/components/ui/dialog

Preview Dialog, copy setup snippets, review examples, and inspect API exports for @tuturuuu/ui/dialog.

<Info>
  Explore the live, interactive preview at [tuturuuu.com/ui/components/dialog](https://tuturuuu.com/ui/components/dialog).
</Info>

**Category:** Overlays · **Import:** `@tuturuuu/ui/dialog` · **Status:** Live preview

## Installation

Install the shared UI package, import global styles once, then import the component from its public subpath.

```bash theme={null}
bun add @tuturuuu/ui
```

```tsx theme={null}
import '@tuturuuu/ui/globals.css';
import { Dialog, DialogTrigger, DialogContent, DialogHeader } from '@tuturuuu/ui/dialog';
```

## Usage

Copy the default usage snippet and adapt labels, state, and event handlers to the product surface.

```tsx theme={null}
import { Dialog, DialogContent, DialogTrigger } from '@tuturuuu/ui/dialog';

<Dialog>
  <DialogTrigger>Open</DialogTrigger>
  <DialogContent>Dialog content</DialogContent>
</Dialog>
```

## Examples

Examples reuse the registry snippets so the docs stay aligned with the component catalog.

### Default

A minimal implementation using the current registry snippet.

```tsx theme={null}
import { Dialog, DialogContent, DialogTrigger } from '@tuturuuu/ui/dialog';

<Dialog>
  <DialogTrigger>Open</DialogTrigger>
  <DialogContent>Dialog content</DialogContent>
</Dialog>
```

### Composition

Use the grouped exports when the primitive has slots, triggers, content regions, or providers.

```tsx theme={null}
import {
  Dialog,
  DialogTrigger,
  DialogContent,
  DialogHeader,
} from '@tuturuuu/ui/dialog';
```

### Package import

Import through the public package path so workspace and external apps share the same contract.

```tsx theme={null}
// Public package import
import { Dialog } from '@tuturuuu/ui/dialog';

// Workspace apps should keep importing through the package boundary.
```

## API reference

The public exports currently available from this component entry.

| Export          | Kind      |
| --------------- | --------- |
| `Dialog`        | component |
| `DialogTrigger` | component |
| `DialogContent` | component |
| `DialogHeader`  | component |

## Customization

Common props, states, and composition points to review before using this component.

* Size
* Trigger
* Footer

## Related components

* [Alert Dialog](./alert-dialog)
* [Context Menu](./context-menu)
* [Drawer](./drawer)


# Diff Viewer
Source: https://docs.tuturuuu.com/platform/components/ui/diff-viewer

Preview Diff Viewer, copy setup snippets, review examples, and inspect API exports for @tuturuuu/ui/diff-viewer.

<Info>
  Explore the live, interactive preview at [tuturuuu.com/ui/components/diff-viewer](https://tuturuuu.com/ui/components/diff-viewer).
</Info>

**Category:** Data · **Import:** `@tuturuuu/ui/diff-viewer` · **Status:** Live preview

## Installation

Install the shared UI package, import global styles once, then import the component from its public subpath.

```bash theme={null}
bun add @tuturuuu/ui
```

```tsx theme={null}
import '@tuturuuu/ui/globals.css';
import { DiffViewer } from '@tuturuuu/ui/diff-viewer';
```

## Usage

Copy the default usage snippet and adapt labels, state, and event handlers to the product surface.

```tsx theme={null}
import { DiffViewer } from '@tuturuuu/ui/diff-viewer';

<DiffViewer oldValue={oldText} newValue={newText} wrapper="inline" />
```

## Examples

Examples reuse the registry snippets so the docs stay aligned with the component catalog.

### Default

A minimal implementation using the current registry snippet.

```tsx theme={null}
import { DiffViewer } from '@tuturuuu/ui/diff-viewer';

<DiffViewer oldValue={oldText} newValue={newText} wrapper="inline" />
```

### Package import

Import through the public package path so workspace and external apps share the same contract.

```tsx theme={null}
// Public package import
import { DiffViewer } from '@tuturuuu/ui/diff-viewer';

// Workspace apps should keep importing through the package boundary.
```

## API reference

The public exports currently available from this component entry.

| Export       | Kind      |
| ------------ | --------- |
| `DiffViewer` | component |

## Customization

Common props, states, and composition points to review before using this component.

* View mode
* Granularity
* Line numbers

## Related components

* [Chart](./chart)
* [Table](./table)
* [Accordion](./accordion)


# Drawer
Source: https://docs.tuturuuu.com/platform/components/ui/drawer

Preview Drawer, copy setup snippets, review examples, and inspect API exports for @tuturuuu/ui/drawer.

<Info>
  Explore the live, interactive preview at [tuturuuu.com/ui/components/drawer](https://tuturuuu.com/ui/components/drawer).
</Info>

**Category:** Overlays · **Import:** `@tuturuuu/ui/drawer` · **Status:** Live preview

## Installation

Install the shared UI package, import global styles once, then import the component from its public subpath.

```bash theme={null}
bun add @tuturuuu/ui
```

```tsx theme={null}
import '@tuturuuu/ui/globals.css';
import { Drawer, DrawerTrigger, DrawerContent } from '@tuturuuu/ui/drawer';
```

## Usage

Copy the default usage snippet and adapt labels, state, and event handlers to the product surface.

```tsx theme={null}
import { Drawer, DrawerContent, DrawerTrigger } from '@tuturuuu/ui/drawer';

<Drawer>
  <DrawerTrigger>Open drawer</DrawerTrigger>
  <DrawerContent>Drawer content</DrawerContent>
</Drawer>
```

## Examples

Examples reuse the registry snippets so the docs stay aligned with the component catalog.

### Default

A minimal implementation using the current registry snippet.

```tsx theme={null}
import { Drawer, DrawerContent, DrawerTrigger } from '@tuturuuu/ui/drawer';

<Drawer>
  <DrawerTrigger>Open drawer</DrawerTrigger>
  <DrawerContent>Drawer content</DrawerContent>
</Drawer>
```

### Composition

Use the grouped exports when the primitive has slots, triggers, content regions, or providers.

```tsx theme={null}
import {
  Drawer,
  DrawerTrigger,
  DrawerContent,
} from '@tuturuuu/ui/drawer';
```

### Package import

Import through the public package path so workspace and external apps share the same contract.

```tsx theme={null}
// Public package import
import { Drawer } from '@tuturuuu/ui/drawer';

// Workspace apps should keep importing through the package boundary.
```

## API reference

The public exports currently available from this component entry.

| Export          | Kind      |
| --------------- | --------- |
| `Drawer`        | component |
| `DrawerTrigger` | component |
| `DrawerContent` | component |

## Customization

Common props, states, and composition points to review before using this component.

* Direction
* Snap points
* Handle

## Related components

* [Alert Dialog](./alert-dialog)
* [Context Menu](./context-menu)
* [Dialog](./dialog)


# Dropdown Menu
Source: https://docs.tuturuuu.com/platform/components/ui/dropdown-menu

Preview Dropdown Menu, copy setup snippets, review examples, and inspect API exports for @tuturuuu/ui/dropdown-menu.

<Info>
  Explore the live, interactive preview at [tuturuuu.com/ui/components/dropdown-menu](https://tuturuuu.com/ui/components/dropdown-menu).
</Info>

**Category:** Overlays · **Import:** `@tuturuuu/ui/dropdown-menu` · **Status:** Live preview

## Installation

Install the shared UI package, import global styles once, then import the component from its public subpath.

```bash theme={null}
bun add @tuturuuu/ui
```

```tsx theme={null}
import '@tuturuuu/ui/globals.css';
import { DropdownMenu, DropdownMenuTrigger, DropdownMenuContent } from '@tuturuuu/ui/dropdown-menu';
```

## Usage

Copy the default usage snippet and adapt labels, state, and event handlers to the product surface.

```tsx theme={null}
import { DropdownMenu, DropdownMenuContent, DropdownMenuItem, DropdownMenuTrigger } from '@tuturuuu/ui/dropdown-menu';

<DropdownMenu>
  <DropdownMenuTrigger>Open menu</DropdownMenuTrigger>
  <DropdownMenuContent><DropdownMenuItem>Settings</DropdownMenuItem></DropdownMenuContent>
</DropdownMenu>
```

## Examples

Examples reuse the registry snippets so the docs stay aligned with the component catalog.

### Default

A minimal implementation using the current registry snippet.

```tsx theme={null}
import { DropdownMenu, DropdownMenuContent, DropdownMenuItem, DropdownMenuTrigger } from '@tuturuuu/ui/dropdown-menu';

<DropdownMenu>
  <DropdownMenuTrigger>Open menu</DropdownMenuTrigger>
  <DropdownMenuContent><DropdownMenuItem>Settings</DropdownMenuItem></DropdownMenuContent>
</DropdownMenu>
```

### Composition

Use the grouped exports when the primitive has slots, triggers, content regions, or providers.

```tsx theme={null}
import {
  DropdownMenu,
  DropdownMenuTrigger,
  DropdownMenuContent,
} from '@tuturuuu/ui/dropdown-menu';
```

### Package import

Import through the public package path so workspace and external apps share the same contract.

```tsx theme={null}
// Public package import
import { DropdownMenu } from '@tuturuuu/ui/dropdown-menu';

// Workspace apps should keep importing through the package boundary.
```

## API reference

The public exports currently available from this component entry.

| Export                | Kind      |
| --------------------- | --------- |
| `DropdownMenu`        | component |
| `DropdownMenuTrigger` | component |
| `DropdownMenuContent` | component |

## Customization

Common props, states, and composition points to review before using this component.

* Items
* Checkbox items
* Shortcuts

## Related components

* [Alert Dialog](./alert-dialog)
* [Context Menu](./context-menu)
* [Dialog](./dialog)


# Form
Source: https://docs.tuturuuu.com/platform/components/ui/form

Preview Form, copy setup snippets, review examples, and inspect API exports for @tuturuuu/ui/form.

<Info>
  Explore the live, interactive preview at [tuturuuu.com/ui/components/form](https://tuturuuu.com/ui/components/form).
</Info>

**Category:** Inputs · **Import:** `@tuturuuu/ui/form` · **Status:** Live preview

## Installation

Install the shared UI package, import global styles once, then import the component from its public subpath.

```bash theme={null}
bun add @tuturuuu/ui
```

```tsx theme={null}
import '@tuturuuu/ui/globals.css';
import { Form, FormField, FormItem, FormLabel, FormControl, FormMessage } from '@tuturuuu/ui/form';
```

## Usage

Copy the default usage snippet and adapt labels, state, and event handlers to the product surface.

```tsx theme={null}
import { Form, FormControl, FormField, FormItem, FormLabel } from '@tuturuuu/ui/form';

<Form {...form}>
  <FormField name="name" render={({ field }) => (
    <FormItem><FormLabel>Name</FormLabel><FormControl><Input {...field} /></FormControl></FormItem>
  )} />
</Form>
```

## Examples

Examples reuse the registry snippets so the docs stay aligned with the component catalog.

### Default

A minimal implementation using the current registry snippet.

```tsx theme={null}
import { Form, FormControl, FormField, FormItem, FormLabel } from '@tuturuuu/ui/form';

<Form {...form}>
  <FormField name="name" render={({ field }) => (
    <FormItem><FormLabel>Name</FormLabel><FormControl><Input {...field} /></FormControl></FormItem>
  )} />
</Form>
```

### Composition

Use the grouped exports when the primitive has slots, triggers, content regions, or providers.

```tsx theme={null}
import {
  Form,
  FormField,
  FormItem,
  FormLabel,
  FormControl,
  FormMessage,
} from '@tuturuuu/ui/form';
```

### Package import

Import through the public package path so workspace and external apps share the same contract.

```tsx theme={null}
// Public package import
import { Form } from '@tuturuuu/ui/form';

// Workspace apps should keep importing through the package boundary.
```

## API reference

The public exports currently available from this component entry.

| Export        | Kind      |
| ------------- | --------- |
| `Form`        | component |
| `FormField`   | component |
| `FormItem`    | component |
| `FormLabel`   | component |
| `FormControl` | component |
| `FormMessage` | component |

## Customization

Common props, states, and composition points to review before using this component.

* Validation
* Required
* Description

## Related components

* [Calendar](./calendar)
* [Checkbox](./checkbox)
* [Color Picker](./color-picker)


# Form Required Indicator
Source: https://docs.tuturuuu.com/platform/components/ui/form-required-indicator

Preview Form Required Indicator, copy setup snippets, review examples, and inspect API exports for @tuturuuu/ui/form-required-indicator.

<Info>
  Explore the live, interactive preview at [tuturuuu.com/ui/components/form-required-indicator](https://tuturuuu.com/ui/components/form-required-indicator).
</Info>

**Category:** Inputs · **Import:** `@tuturuuu/ui/form-required-indicator` · **Status:** Live preview

## Installation

Install the shared UI package, import global styles once, then import the component from its public subpath.

```bash theme={null}
bun add @tuturuuu/ui
```

```tsx theme={null}
import '@tuturuuu/ui/globals.css';
import { FormRequiredIndicator } from '@tuturuuu/ui/form-required-indicator';
```

## Usage

Copy the default usage snippet and adapt labels, state, and event handlers to the product surface.

```tsx theme={null}
import { FormRequiredIndicator } from '@tuturuuu/ui/form-required-indicator';

<Label>Name <FormRequiredIndicator /></Label>
```

## Examples

Examples reuse the registry snippets so the docs stay aligned with the component catalog.

### Default

A minimal implementation using the current registry snippet.

```tsx theme={null}
import { FormRequiredIndicator } from '@tuturuuu/ui/form-required-indicator';

<Label>Name <FormRequiredIndicator /></Label>
```

### Package import

Import through the public package path so workspace and external apps share the same contract.

```tsx theme={null}
// Public package import
import { FormRequiredIndicator } from '@tuturuuu/ui/form-required-indicator';

// Workspace apps should keep importing through the package boundary.
```

## API reference

The public exports currently available from this component entry.

| Export                  | Kind      |
| ----------------------- | --------- |
| `FormRequiredIndicator` | component |

## Customization

Common props, states, and composition points to review before using this component.

* Label
* Required
* Accessibility

## Related components

* [Calendar](./calendar)
* [Checkbox](./checkbox)
* [Color Picker](./color-picker)


# Hover Card
Source: https://docs.tuturuuu.com/platform/components/ui/hover-card

Preview Hover Card, copy setup snippets, review examples, and inspect API exports for @tuturuuu/ui/hover-card.

<Info>
  Explore the live, interactive preview at [tuturuuu.com/ui/components/hover-card](https://tuturuuu.com/ui/components/hover-card).
</Info>

**Category:** Overlays · **Import:** `@tuturuuu/ui/hover-card` · **Status:** Live preview

## Installation

Install the shared UI package, import global styles once, then import the component from its public subpath.

```bash theme={null}
bun add @tuturuuu/ui
```

```tsx theme={null}
import '@tuturuuu/ui/globals.css';
import { HoverCard, HoverCardTrigger, HoverCardContent } from '@tuturuuu/ui/hover-card';
```

## Usage

Copy the default usage snippet and adapt labels, state, and event handlers to the product surface.

```tsx theme={null}
import { HoverCard, HoverCardContent, HoverCardTrigger } from '@tuturuuu/ui/hover-card';

<HoverCard>
  <HoverCardTrigger>Hover profile</HoverCardTrigger>
  <HoverCardContent>Profile summary</HoverCardContent>
</HoverCard>
```

## Examples

Examples reuse the registry snippets so the docs stay aligned with the component catalog.

### Default

A minimal implementation using the current registry snippet.

```tsx theme={null}
import { HoverCard, HoverCardContent, HoverCardTrigger } from '@tuturuuu/ui/hover-card';

<HoverCard>
  <HoverCardTrigger>Hover profile</HoverCardTrigger>
  <HoverCardContent>Profile summary</HoverCardContent>
</HoverCard>
```

### Composition

Use the grouped exports when the primitive has slots, triggers, content regions, or providers.

```tsx theme={null}
import {
  HoverCard,
  HoverCardTrigger,
  HoverCardContent,
} from '@tuturuuu/ui/hover-card';
```

### Package import

Import through the public package path so workspace and external apps share the same contract.

```tsx theme={null}
// Public package import
import { HoverCard } from '@tuturuuu/ui/hover-card';

// Workspace apps should keep importing through the package boundary.
```

## API reference

The public exports currently available from this component entry.

| Export             | Kind      |
| ------------------ | --------- |
| `HoverCard`        | component |
| `HoverCardTrigger` | component |
| `HoverCardContent` | component |

## Customization

Common props, states, and composition points to review before using this component.

* Delay
* Side
* Content

## Related components

* [Alert Dialog](./alert-dialog)
* [Context Menu](./context-menu)
* [Dialog](./dialog)


# Input
Source: https://docs.tuturuuu.com/platform/components/ui/input

Preview Input, copy setup snippets, review examples, and inspect API exports for @tuturuuu/ui/input.

<Info>
  Explore the live, interactive preview at [tuturuuu.com/ui/components/input](https://tuturuuu.com/ui/components/input).
</Info>

**Category:** Inputs · **Import:** `@tuturuuu/ui/input` · **Status:** Live preview

## Installation

Install the shared UI package, import global styles once, then import the component from its public subpath.

```bash theme={null}
bun add @tuturuuu/ui
```

```tsx theme={null}
import '@tuturuuu/ui/globals.css';
import { Input } from '@tuturuuu/ui/input';
```

## Usage

Copy the default usage snippet and adapt labels, state, and event handlers to the product surface.

```tsx theme={null}
import { Input } from '@tuturuuu/ui/input';

<Input placeholder="Workspace name" />
```

## Examples

Examples reuse the registry snippets so the docs stay aligned with the component catalog.

### Default

A minimal implementation using the current registry snippet.

```tsx theme={null}
import { Input } from '@tuturuuu/ui/input';

<Input placeholder="Workspace name" />
```

### Package import

Import through the public package path so workspace and external apps share the same contract.

```tsx theme={null}
// Public package import
import { Input } from '@tuturuuu/ui/input';

// Workspace apps should keep importing through the package boundary.
```

## API reference

The public exports currently available from this component entry.

| Export  | Kind      |
| ------- | --------- |
| `Input` | component |

## Customization

Common props, states, and composition points to review before using this component.

* Type
* Placeholder
* Disabled state

## Related components

* [Calendar](./calendar)
* [Checkbox](./checkbox)
* [Color Picker](./color-picker)


# Input OTP
Source: https://docs.tuturuuu.com/platform/components/ui/input-otp

Preview Input OTP, copy setup snippets, review examples, and inspect API exports for @tuturuuu/ui/input-otp.

<Info>
  Explore the live, interactive preview at [tuturuuu.com/ui/components/input-otp](https://tuturuuu.com/ui/components/input-otp).
</Info>

**Category:** Inputs · **Import:** `@tuturuuu/ui/input-otp` · **Status:** Live preview

## Installation

Install the shared UI package, import global styles once, then import the component from its public subpath.

```bash theme={null}
bun add @tuturuuu/ui
```

```tsx theme={null}
import '@tuturuuu/ui/globals.css';
import { InputOTP, InputOTPGroup, InputOTPSlot } from '@tuturuuu/ui/input-otp';
```

## Usage

Copy the default usage snippet and adapt labels, state, and event handlers to the product surface.

```tsx theme={null}
import { InputOTP, InputOTPGroup, InputOTPSlot } from '@tuturuuu/ui/input-otp';

<InputOTP maxLength={6}>
  <InputOTPGroup>{[0, 1, 2].map((index) => <InputOTPSlot key={index} index={index} />)}</InputOTPGroup>
</InputOTP>
```

## Examples

Examples reuse the registry snippets so the docs stay aligned with the component catalog.

### Default

A minimal implementation using the current registry snippet.

```tsx theme={null}
import { InputOTP, InputOTPGroup, InputOTPSlot } from '@tuturuuu/ui/input-otp';

<InputOTP maxLength={6}>
  <InputOTPGroup>{[0, 1, 2].map((index) => <InputOTPSlot key={index} index={index} />)}</InputOTPGroup>
</InputOTP>
```

### Composition

Use the grouped exports when the primitive has slots, triggers, content regions, or providers.

```tsx theme={null}
import {
  InputOTP,
  InputOTPGroup,
  InputOTPSlot,
} from '@tuturuuu/ui/input-otp';
```

### Package import

Import through the public package path so workspace and external apps share the same contract.

```tsx theme={null}
// Public package import
import { InputOTP } from '@tuturuuu/ui/input-otp';

// Workspace apps should keep importing through the package boundary.
```

## API reference

The public exports currently available from this component entry.

| Export          | Kind      |
| --------------- | --------- |
| `InputOTP`      | component |
| `InputOTPGroup` | component |
| `InputOTPSlot`  | component |

## Customization

Common props, states, and composition points to review before using this component.

* Length
* Separator
* Masking

## Related components

* [Calendar](./calendar)
* [Checkbox](./checkbox)
* [Color Picker](./color-picker)


# Kbd
Source: https://docs.tuturuuu.com/platform/components/ui/kbd

Preview Kbd, copy setup snippets, review examples, and inspect API exports for @tuturuuu/ui/kbd.

<Info>
  Explore the live, interactive preview at [tuturuuu.com/ui/components/kbd](https://tuturuuu.com/ui/components/kbd).
</Info>

**Category:** Typography · **Import:** `@tuturuuu/ui/kbd` · **Status:** Live preview

## Installation

Install the shared UI package, import global styles once, then import the component from its public subpath.

```bash theme={null}
bun add @tuturuuu/ui
```

```tsx theme={null}
import '@tuturuuu/ui/globals.css';
import { Kbd } from '@tuturuuu/ui/kbd';
```

## Usage

Copy the default usage snippet and adapt labels, state, and event handlers to the product surface.

```tsx theme={null}
import { Kbd } from '@tuturuuu/ui/kbd';

<Kbd>Cmd K</Kbd>
```

## Examples

Examples reuse the registry snippets so the docs stay aligned with the component catalog.

### Default

A minimal implementation using the current registry snippet.

```tsx theme={null}
import { Kbd } from '@tuturuuu/ui/kbd';

<Kbd>Cmd K</Kbd>
```

### Package import

Import through the public package path so workspace and external apps share the same contract.

```tsx theme={null}
// Public package import
import { Kbd } from '@tuturuuu/ui/kbd';

// Workspace apps should keep importing through the package boundary.
```

## API reference

The public exports currently available from this component entry.

| Export | Kind      |
| ------ | --------- |
| `Kbd`  | component |

## Customization

Common props, states, and composition points to review before using this component.

* Keys
* Size
* Sequence

## Related components

* [Code Block](./codeblock)
* [Markdown](./markdown)
* [Accordion](./accordion)


# Label
Source: https://docs.tuturuuu.com/platform/components/ui/label

Preview Label, copy setup snippets, review examples, and inspect API exports for @tuturuuu/ui/label.

<Info>
  Explore the live, interactive preview at [tuturuuu.com/ui/components/label](https://tuturuuu.com/ui/components/label).
</Info>

**Category:** Inputs · **Import:** `@tuturuuu/ui/label` · **Status:** Live preview

## Installation

Install the shared UI package, import global styles once, then import the component from its public subpath.

```bash theme={null}
bun add @tuturuuu/ui
```

```tsx theme={null}
import '@tuturuuu/ui/globals.css';
import { Label } from '@tuturuuu/ui/label';
```

## Usage

Copy the default usage snippet and adapt labels, state, and event handlers to the product surface.

```tsx theme={null}
import { Label } from '@tuturuuu/ui/label';

<Label htmlFor="workspace">Workspace</Label>
```

## Examples

Examples reuse the registry snippets so the docs stay aligned with the component catalog.

### Default

A minimal implementation using the current registry snippet.

```tsx theme={null}
import { Label } from '@tuturuuu/ui/label';

<Label htmlFor="workspace">Workspace</Label>
```

### Package import

Import through the public package path so workspace and external apps share the same contract.

```tsx theme={null}
// Public package import
import { Label } from '@tuturuuu/ui/label';

// Workspace apps should keep importing through the package boundary.
```

## API reference

The public exports currently available from this component entry.

| Export  | Kind      |
| ------- | --------- |
| `Label` | component |

## Customization

Common props, states, and composition points to review before using this component.

* Label target
* Required
* Disabled state

## Related components

* [Calendar](./calendar)
* [Checkbox](./checkbox)
* [Color Picker](./color-picker)


# Markdown
Source: https://docs.tuturuuu.com/platform/components/ui/markdown

Preview Markdown, copy setup snippets, review examples, and inspect API exports for @tuturuuu/ui/markdown.

<Info>
  Explore the live, interactive preview at [tuturuuu.com/ui/components/markdown](https://tuturuuu.com/ui/components/markdown).
</Info>

**Category:** Typography · **Import:** `@tuturuuu/ui/markdown` · **Status:** Live preview

## Installation

Install the shared UI package, import global styles once, then import the component from its public subpath.

```bash theme={null}
bun add @tuturuuu/ui
```

```tsx theme={null}
import '@tuturuuu/ui/globals.css';
import { MemoizedReactMarkdown } from '@tuturuuu/ui/markdown';
```

## Usage

Copy the default usage snippet and adapt labels, state, and event handlers to the product surface.

```tsx theme={null}
import { MemoizedReactMarkdown } from '@tuturuuu/ui/markdown';

<MemoizedReactMarkdown>{markdown}</MemoizedReactMarkdown>
```

## Examples

Examples reuse the registry snippets so the docs stay aligned with the component catalog.

### Default

A minimal implementation using the current registry snippet.

```tsx theme={null}
import { MemoizedReactMarkdown } from '@tuturuuu/ui/markdown';

<MemoizedReactMarkdown>{markdown}</MemoizedReactMarkdown>
```

### Package import

Import through the public package path so workspace and external apps share the same contract.

```tsx theme={null}
// Public package import
import { MemoizedReactMarkdown } from '@tuturuuu/ui/markdown';

// Workspace apps should keep importing through the package boundary.
```

## API reference

The public exports currently available from this component entry.

| Export                  | Kind      |
| ----------------------- | --------- |
| `MemoizedReactMarkdown` | component |

## Customization

Common props, states, and composition points to review before using this component.

* Components
* Content
* Memoization

## Related components

* [Code Block](./codeblock)
* [Kbd](./kbd)
* [Accordion](./accordion)


# Menubar
Source: https://docs.tuturuuu.com/platform/components/ui/menubar

Preview Menubar, copy setup snippets, review examples, and inspect API exports for @tuturuuu/ui/menubar.

<Info>
  Explore the live, interactive preview at [tuturuuu.com/ui/components/menubar](https://tuturuuu.com/ui/components/menubar).
</Info>

**Category:** Navigation · **Import:** `@tuturuuu/ui/menubar` · **Status:** Live preview

## Installation

Install the shared UI package, import global styles once, then import the component from its public subpath.

```bash theme={null}
bun add @tuturuuu/ui
```

```tsx theme={null}
import '@tuturuuu/ui/globals.css';
import { Menubar, MenubarMenu, MenubarTrigger, MenubarContent } from '@tuturuuu/ui/menubar';
```

## Usage

Copy the default usage snippet and adapt labels, state, and event handlers to the product surface.

```tsx theme={null}
import { Menubar, MenubarContent, MenubarMenu, MenubarTrigger } from '@tuturuuu/ui/menubar';

<Menubar>
  <MenubarMenu><MenubarTrigger>File</MenubarTrigger><MenubarContent /></MenubarMenu>
</Menubar>
```

## Examples

Examples reuse the registry snippets so the docs stay aligned with the component catalog.

### Default

A minimal implementation using the current registry snippet.

```tsx theme={null}
import { Menubar, MenubarContent, MenubarMenu, MenubarTrigger } from '@tuturuuu/ui/menubar';

<Menubar>
  <MenubarMenu><MenubarTrigger>File</MenubarTrigger><MenubarContent /></MenubarMenu>
</Menubar>
```

### Composition

Use the grouped exports when the primitive has slots, triggers, content regions, or providers.

```tsx theme={null}
import {
  Menubar,
  MenubarMenu,
  MenubarTrigger,
  MenubarContent,
} from '@tuturuuu/ui/menubar';
```

### Package import

Import through the public package path so workspace and external apps share the same contract.

```tsx theme={null}
// Public package import
import { Menubar } from '@tuturuuu/ui/menubar';

// Workspace apps should keep importing through the package boundary.
```

## API reference

The public exports currently available from this component entry.

| Export           | Kind      |
| ---------------- | --------- |
| `Menubar`        | component |
| `MenubarMenu`    | component |
| `MenubarTrigger` | component |
| `MenubarContent` | component |

## Customization

Common props, states, and composition points to review before using this component.

* Menus
* Shortcuts
* Radio items

## Related components

* [Breadcrumb](./breadcrumb)
* [Command](./command)
* [Quick Command Center](./quick-command-center)


# Navbar
Source: https://docs.tuturuuu.com/platform/components/ui/navbar

Preview Navbar, copy setup snippets, review examples, and inspect API exports for @tuturuuu/ui/navbar.

<Info>
  Explore the live, interactive preview at [tuturuuu.com/ui/components/navbar](https://tuturuuu.com/ui/components/navbar).
</Info>

**Category:** Navigation · **Import:** `@tuturuuu/ui/navbar` · **Status:** Pattern preview

## Installation

Install the shared UI package, import global styles once, then import the component from its public subpath.

```bash theme={null}
bun add @tuturuuu/ui
```

```tsx theme={null}
import '@tuturuuu/ui/globals.css';
import { Navbar } from '@tuturuuu/ui/navbar';
```

## Usage

Copy the default usage snippet and adapt labels, state, and event handlers to the product surface.

```tsx theme={null}
import { Navbar } from '@tuturuuu/ui/navbar';

<Navbar title="Tuturuuu" navigationMenu={<MainNavigation />} actions={<UserActions />} />
```

## Examples

Examples reuse the registry snippets so the docs stay aligned with the component catalog.

### Default

A minimal implementation using the current registry snippet.

```tsx theme={null}
import { Navbar } from '@tuturuuu/ui/navbar';

<Navbar title="Tuturuuu" navigationMenu={<MainNavigation />} actions={<UserActions />} />
```

### Package import

Import through the public package path so workspace and external apps share the same contract.

```tsx theme={null}
// Public package import
import { Navbar } from '@tuturuuu/ui/navbar';

// Workspace apps should keep importing through the package boundary.
```

## API reference

The public exports currently available from this component entry.

| Export   | Kind      |
| -------- | --------- |
| `Navbar` | component |

## Customization

Common props, states, and composition points to review before using this component.

* Logo
* Actions
* Navigation

## Related components

* [Breadcrumb](./breadcrumb)
* [Command](./command)
* [Quick Command Center](./quick-command-center)


# Navigation Menu
Source: https://docs.tuturuuu.com/platform/components/ui/navigation-menu

Preview Navigation Menu, copy setup snippets, review examples, and inspect API exports for @tuturuuu/ui/navigation-menu.

<Info>
  Explore the live, interactive preview at [tuturuuu.com/ui/components/navigation-menu](https://tuturuuu.com/ui/components/navigation-menu).
</Info>

**Category:** Navigation · **Import:** `@tuturuuu/ui/navigation-menu` · **Status:** Live preview

## Installation

Install the shared UI package, import global styles once, then import the component from its public subpath.

```bash theme={null}
bun add @tuturuuu/ui
```

```tsx theme={null}
import '@tuturuuu/ui/globals.css';
import { NavigationMenu, NavigationMenuList, NavigationMenuItem } from '@tuturuuu/ui/navigation-menu';
```

## Usage

Copy the default usage snippet and adapt labels, state, and event handlers to the product surface.

```tsx theme={null}
import { NavigationMenu, NavigationMenuItem, NavigationMenuList } from '@tuturuuu/ui/navigation-menu';

<NavigationMenu><NavigationMenuList><NavigationMenuItem /></NavigationMenuList></NavigationMenu>
```

## Examples

Examples reuse the registry snippets so the docs stay aligned with the component catalog.

### Default

A minimal implementation using the current registry snippet.

```tsx theme={null}
import { NavigationMenu, NavigationMenuItem, NavigationMenuList } from '@tuturuuu/ui/navigation-menu';

<NavigationMenu><NavigationMenuList><NavigationMenuItem /></NavigationMenuList></NavigationMenu>
```

### Composition

Use the grouped exports when the primitive has slots, triggers, content regions, or providers.

```tsx theme={null}
import {
  NavigationMenu,
  NavigationMenuList,
  NavigationMenuItem,
} from '@tuturuuu/ui/navigation-menu';
```

### Package import

Import through the public package path so workspace and external apps share the same contract.

```tsx theme={null}
// Public package import
import { NavigationMenu } from '@tuturuuu/ui/navigation-menu';

// Workspace apps should keep importing through the package boundary.
```

## API reference

The public exports currently available from this component entry.

| Export               | Kind      |
| -------------------- | --------- |
| `NavigationMenu`     | component |
| `NavigationMenuList` | component |
| `NavigationMenuItem` | component |

## Customization

Common props, states, and composition points to review before using this component.

* Items
* Content
* Viewport

## Related components

* [Breadcrumb](./breadcrumb)
* [Command](./command)
* [Quick Command Center](./quick-command-center)


# Optional Time Picker
Source: https://docs.tuturuuu.com/platform/components/ui/optional-time-picker

Preview Optional Time Picker, copy setup snippets, review examples, and inspect API exports for @tuturuuu/ui/optional-time-picker.

<Info>
  Explore the live, interactive preview at [tuturuuu.com/ui/components/optional-time-picker](https://tuturuuu.com/ui/components/optional-time-picker).
</Info>

**Category:** Inputs · **Import:** `@tuturuuu/ui/optional-time-picker` · **Status:** Live preview

## Installation

Install the shared UI package, import global styles once, then import the component from its public subpath.

```bash theme={null}
bun add @tuturuuu/ui
```

```tsx theme={null}
import '@tuturuuu/ui/globals.css';
import { OptionalTimePicker } from '@tuturuuu/ui/optional-time-picker';
```

## Usage

Copy the default usage snippet and adapt labels, state, and event handlers to the product surface.

```tsx theme={null}
import { OptionalTimePicker } from '@tuturuuu/ui/optional-time-picker';

const [includeTime, setIncludeTime] = useState(true);

<OptionalTimePicker
  date={date}
  setDate={setDate}
  includeTime={includeTime}
  setIncludeTime={setIncludeTime}
  includeTimeLabel="Include time"
/>
```

## Examples

Examples reuse the registry snippets so the docs stay aligned with the component catalog.

### Default

A minimal implementation using the current registry snippet.

```tsx theme={null}
import { OptionalTimePicker } from '@tuturuuu/ui/optional-time-picker';

const [includeTime, setIncludeTime] = useState(true);

<OptionalTimePicker
  date={date}
  setDate={setDate}
  includeTime={includeTime}
  setIncludeTime={setIncludeTime}
  includeTimeLabel="Include time"
/>
```

### Package import

Import through the public package path so workspace and external apps share the same contract.

```tsx theme={null}
// Public package import
import { OptionalTimePicker } from '@tuturuuu/ui/optional-time-picker';

// Workspace apps should keep importing through the package boundary.
```

## API reference

The public exports currently available from this component entry.

| Export               | Kind      |
| -------------------- | --------- |
| `OptionalTimePicker` | component |

## Customization

Common props, states, and composition points to review before using this component.

* Include time
* Timezone
* Time format
* Disabled state

## Related components

* [Calendar](./calendar)
* [Checkbox](./checkbox)
* [Color Picker](./color-picker)


# UI Components
Source: https://docs.tuturuuu.com/platform/components/ui/overview

Reference for every component in the @tuturuuu/ui registry, mirrored from the live UI explorer.

<Info>
  Browse the live, interactive explorer at [tuturuuu.com/ui](https://tuturuuu.com/ui).
</Info>

## Actions

* [Button](./button)
* [Toggle](./toggle)
* [Toggle Group](./toggle-group)

## Inputs

* [Calendar](./calendar)
* [Checkbox](./checkbox)
* [Color Picker](./color-picker)
* [Currency Input](./currency-input)
* [Date Time Picker](./date-time-picker)
* [Optional Time Picker](./optional-time-picker)
* [Form](./form)
* [Form Required Indicator](./form-required-indicator)
* [Input](./input)
* [Input OTP](./input-otp)
* [Label](./label)
* [Radio Group](./radio-group)
* [Select](./select)
* [Slider](./slider)
* [Switch](./switch)
* [Textarea](./textarea)
* [Time Picker Input](./time-picker-input)

## Overlays

* [Alert Dialog](./alert-dialog)
* [Context Menu](./context-menu)
* [Dialog](./dialog)
* [Drawer](./drawer)
* [Dropdown Menu](./dropdown-menu)
* [Hover Card](./hover-card)
* [Popover](./popover)
* [Sheet](./sheet)
* [Tooltip](./tooltip)

## Navigation

* [Breadcrumb](./breadcrumb)
* [Command](./command)
* [Quick Command Center](./quick-command-center)
* [Menubar](./menubar)
* [Navbar](./navbar)
* [Navigation Menu](./navigation-menu)
* [Pagination](./pagination)
* [Sidebar](./sidebar)
* [Tabs](./tabs)

## Feedback

* [Alert](./alert)
* [Avatar](./avatar)
* [Badge](./badge)
* [Progress](./progress)
* [Skeleton](./skeleton)
* [Sonner](./sonner)
* [Sticky Bottom Bar](./sticky-bottom-bar)
* [Toast](./toast)
* [Toaster](./toaster)

## Data

* [Chart](./chart)
* [Diff Viewer](./diff-viewer)
* [Table](./table)

## Layout

* [Accordion](./accordion)
* [Aspect Ratio](./aspect-ratio)
* [Card](./card)
* [Carousel](./carousel)
* [Collapsible](./collapsible)
* [Resizable](./resizable)
* [Scroll Area](./scroll-area)
* [Separator](./separator)

## Typography

* [Code Block](./codeblock)
* [Kbd](./kbd)
* [Markdown](./markdown)

## Advanced

* [Report Problem Dialog](./report-problem-dialog)


# Pagination
Source: https://docs.tuturuuu.com/platform/components/ui/pagination

Preview Pagination, copy setup snippets, review examples, and inspect API exports for @tuturuuu/ui/pagination.

<Info>
  Explore the live, interactive preview at [tuturuuu.com/ui/components/pagination](https://tuturuuu.com/ui/components/pagination).
</Info>

**Category:** Navigation · **Import:** `@tuturuuu/ui/pagination` · **Status:** Live preview

## Installation

Install the shared UI package, import global styles once, then import the component from its public subpath.

```bash theme={null}
bun add @tuturuuu/ui
```

```tsx theme={null}
import '@tuturuuu/ui/globals.css';
import { Pagination, PaginationContent, PaginationItem, PaginationLink } from '@tuturuuu/ui/pagination';
```

## Usage

Copy the default usage snippet and adapt labels, state, and event handlers to the product surface.

```tsx theme={null}
import { Pagination, PaginationContent, PaginationItem, PaginationLink } from '@tuturuuu/ui/pagination';

<Pagination><PaginationContent><PaginationItem><PaginationLink href="#">1</PaginationLink></PaginationItem></PaginationContent></Pagination>
```

## Examples

Examples reuse the registry snippets so the docs stay aligned with the component catalog.

### Default

A minimal implementation using the current registry snippet.

```tsx theme={null}
import { Pagination, PaginationContent, PaginationItem, PaginationLink } from '@tuturuuu/ui/pagination';

<Pagination><PaginationContent><PaginationItem><PaginationLink href="#">1</PaginationLink></PaginationItem></PaginationContent></Pagination>
```

### Composition

Use the grouped exports when the primitive has slots, triggers, content regions, or providers.

```tsx theme={null}
import {
  Pagination,
  PaginationContent,
  PaginationItem,
  PaginationLink,
} from '@tuturuuu/ui/pagination';
```

### Package import

Import through the public package path so workspace and external apps share the same contract.

```tsx theme={null}
// Public package import
import { Pagination } from '@tuturuuu/ui/pagination';

// Workspace apps should keep importing through the package boundary.
```

## API reference

The public exports currently available from this component entry.

| Export              | Kind      |
| ------------------- | --------- |
| `Pagination`        | component |
| `PaginationContent` | component |
| `PaginationItem`    | component |
| `PaginationLink`    | component |

## Customization

Common props, states, and composition points to review before using this component.

* Page
* Siblings
* Disabled state

## Related components

* [Breadcrumb](./breadcrumb)
* [Command](./command)
* [Quick Command Center](./quick-command-center)


# Popover
Source: https://docs.tuturuuu.com/platform/components/ui/popover

Preview Popover, copy setup snippets, review examples, and inspect API exports for @tuturuuu/ui/popover.

<Info>
  Explore the live, interactive preview at [tuturuuu.com/ui/components/popover](https://tuturuuu.com/ui/components/popover).
</Info>

**Category:** Overlays · **Import:** `@tuturuuu/ui/popover` · **Status:** Live preview

## Installation

Install the shared UI package, import global styles once, then import the component from its public subpath.

```bash theme={null}
bun add @tuturuuu/ui
```

```tsx theme={null}
import '@tuturuuu/ui/globals.css';
import { Popover, PopoverTrigger, PopoverContent } from '@tuturuuu/ui/popover';
```

## Usage

Copy the default usage snippet and adapt labels, state, and event handlers to the product surface.

```tsx theme={null}
import { Popover, PopoverContent, PopoverTrigger } from '@tuturuuu/ui/popover';

<Popover><PopoverTrigger>Open</PopoverTrigger><PopoverContent>Popover content</PopoverContent></Popover>
```

## Examples

Examples reuse the registry snippets so the docs stay aligned with the component catalog.

### Default

A minimal implementation using the current registry snippet.

```tsx theme={null}
import { Popover, PopoverContent, PopoverTrigger } from '@tuturuuu/ui/popover';

<Popover><PopoverTrigger>Open</PopoverTrigger><PopoverContent>Popover content</PopoverContent></Popover>
```

### Composition

Use the grouped exports when the primitive has slots, triggers, content regions, or providers.

```tsx theme={null}
import {
  Popover,
  PopoverTrigger,
  PopoverContent,
} from '@tuturuuu/ui/popover';
```

### Package import

Import through the public package path so workspace and external apps share the same contract.

```tsx theme={null}
// Public package import
import { Popover } from '@tuturuuu/ui/popover';

// Workspace apps should keep importing through the package boundary.
```

## API reference

The public exports currently available from this component entry.

| Export           | Kind      |
| ---------------- | --------- |
| `Popover`        | component |
| `PopoverTrigger` | component |
| `PopoverContent` | component |

## Customization

Common props, states, and composition points to review before using this component.

* Side
* Align
* Content

## Related components

* [Alert Dialog](./alert-dialog)
* [Context Menu](./context-menu)
* [Dialog](./dialog)


# Progress
Source: https://docs.tuturuuu.com/platform/components/ui/progress

Preview Progress, copy setup snippets, review examples, and inspect API exports for @tuturuuu/ui/progress.

<Info>
  Explore the live, interactive preview at [tuturuuu.com/ui/components/progress](https://tuturuuu.com/ui/components/progress).
</Info>

**Category:** Feedback · **Import:** `@tuturuuu/ui/progress` · **Status:** Live preview

## Installation

Install the shared UI package, import global styles once, then import the component from its public subpath.

```bash theme={null}
bun add @tuturuuu/ui
```

```tsx theme={null}
import '@tuturuuu/ui/globals.css';
import { Progress } from '@tuturuuu/ui/progress';
```

## Usage

Copy the default usage snippet and adapt labels, state, and event handlers to the product surface.

```tsx theme={null}
import { Progress } from '@tuturuuu/ui/progress';

<Progress value={72} />
```

## Examples

Examples reuse the registry snippets so the docs stay aligned with the component catalog.

### Default

A minimal implementation using the current registry snippet.

```tsx theme={null}
import { Progress } from '@tuturuuu/ui/progress';

<Progress value={72} />
```

### Package import

Import through the public package path so workspace and external apps share the same contract.

```tsx theme={null}
// Public package import
import { Progress } from '@tuturuuu/ui/progress';

// Workspace apps should keep importing through the package boundary.
```

## API reference

The public exports currently available from this component entry.

| Export     | Kind      |
| ---------- | --------- |
| `Progress` | component |

## Customization

Common props, states, and composition points to review before using this component.

* Value
* Indicator
* Label

## Related components

* [Alert](./alert)
* [Avatar](./avatar)
* [Badge](./badge)


# Quick Command Center
Source: https://docs.tuturuuu.com/platform/components/ui/quick-command-center

Preview Quick Command Center, copy setup snippets, review examples, and inspect API exports for @tuturuuu/ui/quick-command-center.

<Info>
  Explore the live, interactive preview at [tuturuuu.com/ui/components/quick-command-center](https://tuturuuu.com/ui/components/quick-command-center).
</Info>

**Category:** Navigation · **Import:** `@tuturuuu/ui/quick-command-center` · **Status:** Live preview

## Installation

Install the shared UI package, import global styles once, then import the component from its public subpath.

```bash theme={null}
bun add @tuturuuu/ui
```

```tsx theme={null}
import '@tuturuuu/ui/globals.css';
import { QuickCommandCenter } from '@tuturuuu/ui/quick-command-center';
```

## Usage

Copy the default usage snippet and adapt labels, state, and event handlers to the product surface.

```tsx theme={null}
import { QuickCommandCenter } from '@tuturuuu/ui/quick-command-center';

<QuickCommandCenter
  open={open}
  onOpenChange={setOpen}
  title="Quick actions"
  placeholder="Search..."
  emptyLabel="No commands found"
  digitShortcuts
  groups={groups}
/>
```

## Examples

Examples reuse the registry snippets so the docs stay aligned with the component catalog.

### Default

A minimal implementation using the current registry snippet.

```tsx theme={null}
import { QuickCommandCenter } from '@tuturuuu/ui/quick-command-center';

<QuickCommandCenter
  open={open}
  onOpenChange={setOpen}
  title="Quick actions"
  placeholder="Search..."
  emptyLabel="No commands found"
  digitShortcuts
  groups={groups}
/>
```

### Package import

Import through the public package path so workspace and external apps share the same contract.

```tsx theme={null}
// Public package import
import { QuickCommandCenter } from '@tuturuuu/ui/quick-command-center';

// Workspace apps should keep importing through the package boundary.
```

## API reference

The public exports currently available from this component entry.

| Export               | Kind      |
| -------------------- | --------- |
| `QuickCommandCenter` | component |

## Customization

Common props, states, and composition points to review before using this component.

* Groups
* Digit shortcuts
* Search value

## Related components

* [Breadcrumb](./breadcrumb)
* [Command](./command)
* [Menubar](./menubar)


# Radio Group
Source: https://docs.tuturuuu.com/platform/components/ui/radio-group

Preview Radio Group, copy setup snippets, review examples, and inspect API exports for @tuturuuu/ui/radio-group.

<Info>
  Explore the live, interactive preview at [tuturuuu.com/ui/components/radio-group](https://tuturuuu.com/ui/components/radio-group).
</Info>

**Category:** Inputs · **Import:** `@tuturuuu/ui/radio-group` · **Status:** Live preview

## Installation

Install the shared UI package, import global styles once, then import the component from its public subpath.

```bash theme={null}
bun add @tuturuuu/ui
```

```tsx theme={null}
import '@tuturuuu/ui/globals.css';
import { RadioGroup, RadioGroupItem } from '@tuturuuu/ui/radio-group';
```

## Usage

Copy the default usage snippet and adapt labels, state, and event handlers to the product surface.

```tsx theme={null}
import { RadioGroup, RadioGroupItem } from '@tuturuuu/ui/radio-group';

<RadioGroup defaultValue="compact"><RadioGroupItem value="compact" /></RadioGroup>
```

## Examples

Examples reuse the registry snippets so the docs stay aligned with the component catalog.

### Default

A minimal implementation using the current registry snippet.

```tsx theme={null}
import { RadioGroup, RadioGroupItem } from '@tuturuuu/ui/radio-group';

<RadioGroup defaultValue="compact"><RadioGroupItem value="compact" /></RadioGroup>
```

### Composition

Use the grouped exports when the primitive has slots, triggers, content regions, or providers.

```tsx theme={null}
import {
  RadioGroup,
  RadioGroupItem,
} from '@tuturuuu/ui/radio-group';
```

### Package import

Import through the public package path so workspace and external apps share the same contract.

```tsx theme={null}
// Public package import
import { RadioGroup } from '@tuturuuu/ui/radio-group';

// Workspace apps should keep importing through the package boundary.
```

## API reference

The public exports currently available from this component entry.

| Export           | Kind      |
| ---------------- | --------- |
| `RadioGroup`     | component |
| `RadioGroupItem` | component |

## Customization

Common props, states, and composition points to review before using this component.

* Orientation
* Default value
* Labels

## Related components

* [Calendar](./calendar)
* [Checkbox](./checkbox)
* [Color Picker](./color-picker)


# Report Problem Dialog
Source: https://docs.tuturuuu.com/platform/components/ui/report-problem-dialog

Preview Report Problem Dialog, copy setup snippets, review examples, and inspect API exports for @tuturuuu/ui/report-problem-dialog.

<Info>
  Explore the live, interactive preview at [tuturuuu.com/ui/components/report-problem-dialog](https://tuturuuu.com/ui/components/report-problem-dialog).
</Info>

**Category:** Advanced · **Import:** `@tuturuuu/ui/report-problem-dialog` · **Status:** Pattern preview

## Installation

Install the shared UI package, import global styles once, then import the component from its public subpath.

```bash theme={null}
bun add @tuturuuu/ui
```

```tsx theme={null}
import '@tuturuuu/ui/globals.css';
import { ReportProblemDialog } from '@tuturuuu/ui/report-problem-dialog';
```

## Usage

Copy the default usage snippet and adapt labels, state, and event handlers to the product surface.

```tsx theme={null}
import { ReportProblemDialog } from '@tuturuuu/ui/report-problem-dialog';

<ReportProblemDialog />
```

## Examples

Examples reuse the registry snippets so the docs stay aligned with the component catalog.

### Default

A minimal implementation using the current registry snippet.

```tsx theme={null}
import { ReportProblemDialog } from '@tuturuuu/ui/report-problem-dialog';

<ReportProblemDialog />
```

### Package import

Import through the public package path so workspace and external apps share the same contract.

```tsx theme={null}
// Public package import
import { ReportProblemDialog } from '@tuturuuu/ui/report-problem-dialog';

// Workspace apps should keep importing through the package boundary.
```

## API reference

The public exports currently available from this component entry.

| Export                | Kind      |
| --------------------- | --------- |
| `ReportProblemDialog` | component |

## Customization

Common props, states, and composition points to review before using this component.

* Products
* Trigger
* Show trigger

## Related components

* [Accordion](./accordion)
* [Alert](./alert)
* [Alert Dialog](./alert-dialog)


# Resizable
Source: https://docs.tuturuuu.com/platform/components/ui/resizable

Preview Resizable, copy setup snippets, review examples, and inspect API exports for @tuturuuu/ui/resizable.

<Info>
  Explore the live, interactive preview at [tuturuuu.com/ui/components/resizable](https://tuturuuu.com/ui/components/resizable).
</Info>

**Category:** Layout · **Import:** `@tuturuuu/ui/resizable` · **Status:** Live preview

## Installation

Install the shared UI package, import global styles once, then import the component from its public subpath.

```bash theme={null}
bun add @tuturuuu/ui
```

```tsx theme={null}
import '@tuturuuu/ui/globals.css';
import { ResizablePanelGroup, ResizablePanel, ResizableHandle } from '@tuturuuu/ui/resizable';
```

## Usage

Copy the default usage snippet and adapt labels, state, and event handlers to the product surface.

```tsx theme={null}
import { ResizableHandle, ResizablePanel, ResizablePanelGroup } from '@tuturuuu/ui/resizable';

<ResizablePanelGroup direction="horizontal">
  <ResizablePanel>Primary</ResizablePanel><ResizableHandle withHandle /><ResizablePanel>Secondary</ResizablePanel>
</ResizablePanelGroup>
```

## Examples

Examples reuse the registry snippets so the docs stay aligned with the component catalog.

### Default

A minimal implementation using the current registry snippet.

```tsx theme={null}
import { ResizableHandle, ResizablePanel, ResizablePanelGroup } from '@tuturuuu/ui/resizable';

<ResizablePanelGroup direction="horizontal">
  <ResizablePanel>Primary</ResizablePanel><ResizableHandle withHandle /><ResizablePanel>Secondary</ResizablePanel>
</ResizablePanelGroup>
```

### Composition

Use the grouped exports when the primitive has slots, triggers, content regions, or providers.

```tsx theme={null}
import {
  ResizablePanelGroup,
  ResizablePanel,
  ResizableHandle,
} from '@tuturuuu/ui/resizable';
```

### Package import

Import through the public package path so workspace and external apps share the same contract.

```tsx theme={null}
// Public package import
import { ResizablePanelGroup } from '@tuturuuu/ui/resizable';

// Workspace apps should keep importing through the package boundary.
```

## API reference

The public exports currently available from this component entry.

| Export                | Kind      |
| --------------------- | --------- |
| `ResizablePanelGroup` | component |
| `ResizablePanel`      | component |
| `ResizableHandle`     | component |

## Customization

Common props, states, and composition points to review before using this component.

* Direction
* Default size
* Handle

## Related components

* [Accordion](./accordion)
* [Aspect Ratio](./aspect-ratio)
* [Card](./card)


# Scroll Area
Source: https://docs.tuturuuu.com/platform/components/ui/scroll-area

Preview Scroll Area, copy setup snippets, review examples, and inspect API exports for @tuturuuu/ui/scroll-area.

<Info>
  Explore the live, interactive preview at [tuturuuu.com/ui/components/scroll-area](https://tuturuuu.com/ui/components/scroll-area).
</Info>

**Category:** Layout · **Import:** `@tuturuuu/ui/scroll-area` · **Status:** Live preview

## Installation

Install the shared UI package, import global styles once, then import the component from its public subpath.

```bash theme={null}
bun add @tuturuuu/ui
```

```tsx theme={null}
import '@tuturuuu/ui/globals.css';
import { ScrollArea, ScrollBar } from '@tuturuuu/ui/scroll-area';
```

## Usage

Copy the default usage snippet and adapt labels, state, and event handlers to the product surface.

```tsx theme={null}
import { ScrollArea } from '@tuturuuu/ui/scroll-area';

<ScrollArea className="h-48">Scrollable content</ScrollArea>
```

## Examples

Examples reuse the registry snippets so the docs stay aligned with the component catalog.

### Default

A minimal implementation using the current registry snippet.

```tsx theme={null}
import { ScrollArea } from '@tuturuuu/ui/scroll-area';

<ScrollArea className="h-48">Scrollable content</ScrollArea>
```

### Composition

Use the grouped exports when the primitive has slots, triggers, content regions, or providers.

```tsx theme={null}
import {
  ScrollArea,
  ScrollBar,
} from '@tuturuuu/ui/scroll-area';
```

### Package import

Import through the public package path so workspace and external apps share the same contract.

```tsx theme={null}
// Public package import
import { ScrollArea } from '@tuturuuu/ui/scroll-area';

// Workspace apps should keep importing through the package boundary.
```

## API reference

The public exports currently available from this component entry.

| Export       | Kind      |
| ------------ | --------- |
| `ScrollArea` | component |
| `ScrollBar`  | component |

## Customization

Common props, states, and composition points to review before using this component.

* Height
* Scrollbar
* Content

## Related components

* [Accordion](./accordion)
* [Aspect Ratio](./aspect-ratio)
* [Card](./card)


# Select
Source: https://docs.tuturuuu.com/platform/components/ui/select

Preview Select, copy setup snippets, review examples, and inspect API exports for @tuturuuu/ui/select.

<Info>
  Explore the live, interactive preview at [tuturuuu.com/ui/components/select](https://tuturuuu.com/ui/components/select).
</Info>

**Category:** Inputs · **Import:** `@tuturuuu/ui/select` · **Status:** Live preview

## Installation

Install the shared UI package, import global styles once, then import the component from its public subpath.

```bash theme={null}
bun add @tuturuuu/ui
```

```tsx theme={null}
import '@tuturuuu/ui/globals.css';
import { Select, SelectTrigger, SelectContent, SelectItem } from '@tuturuuu/ui/select';
```

## Usage

Copy the default usage snippet and adapt labels, state, and event handlers to the product surface.

```tsx theme={null}
import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from '@tuturuuu/ui/select';

<Select><SelectTrigger><SelectValue placeholder="Choose" /></SelectTrigger><SelectContent><SelectItem value="one">One</SelectItem></SelectContent></Select>
```

## Examples

Examples reuse the registry snippets so the docs stay aligned with the component catalog.

### Default

A minimal implementation using the current registry snippet.

```tsx theme={null}
import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from '@tuturuuu/ui/select';

<Select><SelectTrigger><SelectValue placeholder="Choose" /></SelectTrigger><SelectContent><SelectItem value="one">One</SelectItem></SelectContent></Select>
```

### Composition

Use the grouped exports when the primitive has slots, triggers, content regions, or providers.

```tsx theme={null}
import {
  Select,
  SelectTrigger,
  SelectContent,
  SelectItem,
} from '@tuturuuu/ui/select';
```

### Package import

Import through the public package path so workspace and external apps share the same contract.

```tsx theme={null}
// Public package import
import { Select } from '@tuturuuu/ui/select';

// Workspace apps should keep importing through the package boundary.
```

## API reference

The public exports currently available from this component entry.

| Export          | Kind      |
| --------------- | --------- |
| `Select`        | component |
| `SelectTrigger` | component |
| `SelectContent` | component |
| `SelectItem`    | component |

## Customization

Common props, states, and composition points to review before using this component.

* Options
* Placeholder
* Disabled state

## Related components

* [Calendar](./calendar)
* [Checkbox](./checkbox)
* [Color Picker](./color-picker)


# Separator
Source: https://docs.tuturuuu.com/platform/components/ui/separator

Preview Separator, copy setup snippets, review examples, and inspect API exports for @tuturuuu/ui/separator.

<Info>
  Explore the live, interactive preview at [tuturuuu.com/ui/components/separator](https://tuturuuu.com/ui/components/separator).
</Info>

**Category:** Layout · **Import:** `@tuturuuu/ui/separator` · **Status:** Live preview

## Installation

Install the shared UI package, import global styles once, then import the component from its public subpath.

```bash theme={null}
bun add @tuturuuu/ui
```

```tsx theme={null}
import '@tuturuuu/ui/globals.css';
import { Separator } from '@tuturuuu/ui/separator';
```

## Usage

Copy the default usage snippet and adapt labels, state, and event handlers to the product surface.

```tsx theme={null}
import { Separator } from '@tuturuuu/ui/separator';

<Separator orientation="horizontal" />
```

## Examples

Examples reuse the registry snippets so the docs stay aligned with the component catalog.

### Default

A minimal implementation using the current registry snippet.

```tsx theme={null}
import { Separator } from '@tuturuuu/ui/separator';

<Separator orientation="horizontal" />
```

### Package import

Import through the public package path so workspace and external apps share the same contract.

```tsx theme={null}
// Public package import
import { Separator } from '@tuturuuu/ui/separator';

// Workspace apps should keep importing through the package boundary.
```

## API reference

The public exports currently available from this component entry.

| Export      | Kind      |
| ----------- | --------- |
| `Separator` | component |

## Customization

Common props, states, and composition points to review before using this component.

* Orientation
* Spacing
* Decorative

## Related components

* [Accordion](./accordion)
* [Aspect Ratio](./aspect-ratio)
* [Card](./card)


# Sheet
Source: https://docs.tuturuuu.com/platform/components/ui/sheet

Preview Sheet, copy setup snippets, review examples, and inspect API exports for @tuturuuu/ui/sheet.

<Info>
  Explore the live, interactive preview at [tuturuuu.com/ui/components/sheet](https://tuturuuu.com/ui/components/sheet).
</Info>

**Category:** Overlays · **Import:** `@tuturuuu/ui/sheet` · **Status:** Live preview

## Installation

Install the shared UI package, import global styles once, then import the component from its public subpath.

```bash theme={null}
bun add @tuturuuu/ui
```

```tsx theme={null}
import '@tuturuuu/ui/globals.css';
import { Sheet, SheetTrigger, SheetContent } from '@tuturuuu/ui/sheet';
```

## Usage

Copy the default usage snippet and adapt labels, state, and event handlers to the product surface.

```tsx theme={null}
import { Sheet, SheetContent, SheetTrigger } from '@tuturuuu/ui/sheet';

<Sheet><SheetTrigger>Open panel</SheetTrigger><SheetContent side="right">Panel content</SheetContent></Sheet>
```

## Examples

Examples reuse the registry snippets so the docs stay aligned with the component catalog.

### Default

A minimal implementation using the current registry snippet.

```tsx theme={null}
import { Sheet, SheetContent, SheetTrigger } from '@tuturuuu/ui/sheet';

<Sheet><SheetTrigger>Open panel</SheetTrigger><SheetContent side="right">Panel content</SheetContent></Sheet>
```

### Composition

Use the grouped exports when the primitive has slots, triggers, content regions, or providers.

```tsx theme={null}
import {
  Sheet,
  SheetTrigger,
  SheetContent,
} from '@tuturuuu/ui/sheet';
```

### Package import

Import through the public package path so workspace and external apps share the same contract.

```tsx theme={null}
// Public package import
import { Sheet } from '@tuturuuu/ui/sheet';

// Workspace apps should keep importing through the package boundary.
```

## API reference

The public exports currently available from this component entry.

| Export         | Kind      |
| -------------- | --------- |
| `Sheet`        | component |
| `SheetTrigger` | component |
| `SheetContent` | component |

## Customization

Common props, states, and composition points to review before using this component.

* Side
* Size
* Footer

## Related components

* [Alert Dialog](./alert-dialog)
* [Context Menu](./context-menu)
* [Dialog](./dialog)


# Sidebar
Source: https://docs.tuturuuu.com/platform/components/ui/sidebar

Preview Sidebar, copy setup snippets, review examples, and inspect API exports for @tuturuuu/ui/sidebar.

<Info>
  Explore the live, interactive preview at [tuturuuu.com/ui/components/sidebar](https://tuturuuu.com/ui/components/sidebar).
</Info>

**Category:** Navigation · **Import:** `@tuturuuu/ui/sidebar` · **Status:** Pattern preview

## Installation

Install the shared UI package, import global styles once, then import the component from its public subpath.

```bash theme={null}
bun add @tuturuuu/ui
```

```tsx theme={null}
import '@tuturuuu/ui/globals.css';
import { SidebarProvider, Sidebar, SidebarMenu, SidebarTrigger } from '@tuturuuu/ui/sidebar';
```

## Usage

Copy the default usage snippet and adapt labels, state, and event handlers to the product surface.

```tsx theme={null}
import { Sidebar, SidebarProvider, SidebarTrigger } from '@tuturuuu/ui/sidebar';

<SidebarProvider><Sidebar /><SidebarTrigger /></SidebarProvider>
```

## Examples

Examples reuse the registry snippets so the docs stay aligned with the component catalog.

### Default

A minimal implementation using the current registry snippet.

```tsx theme={null}
import { Sidebar, SidebarProvider, SidebarTrigger } from '@tuturuuu/ui/sidebar';

<SidebarProvider><Sidebar /><SidebarTrigger /></SidebarProvider>
```

### Composition

Use the grouped exports when the primitive has slots, triggers, content regions, or providers.

```tsx theme={null}
import {
  SidebarProvider,
  Sidebar,
  SidebarMenu,
  SidebarTrigger,
} from '@tuturuuu/ui/sidebar';
```

### Package import

Import through the public package path so workspace and external apps share the same contract.

```tsx theme={null}
// Public package import
import { SidebarProvider } from '@tuturuuu/ui/sidebar';

// Workspace apps should keep importing through the package boundary.
```

## API reference

The public exports currently available from this component entry.

| Export            | Kind      |
| ----------------- | --------- |
| `SidebarProvider` | provider  |
| `Sidebar`         | component |
| `SidebarMenu`     | component |
| `SidebarTrigger`  | component |

## Customization

Common props, states, and composition points to review before using this component.

* Collapsible
* Variant
* Groups

## Related components

* [Breadcrumb](./breadcrumb)
* [Command](./command)
* [Quick Command Center](./quick-command-center)


# Skeleton
Source: https://docs.tuturuuu.com/platform/components/ui/skeleton

Preview Skeleton, copy setup snippets, review examples, and inspect API exports for @tuturuuu/ui/skeleton.

<Info>
  Explore the live, interactive preview at [tuturuuu.com/ui/components/skeleton](https://tuturuuu.com/ui/components/skeleton).
</Info>

**Category:** Feedback · **Import:** `@tuturuuu/ui/skeleton` · **Status:** Live preview

## Installation

Install the shared UI package, import global styles once, then import the component from its public subpath.

```bash theme={null}
bun add @tuturuuu/ui
```

```tsx theme={null}
import '@tuturuuu/ui/globals.css';
import { Skeleton } from '@tuturuuu/ui/skeleton';
```

## Usage

Copy the default usage snippet and adapt labels, state, and event handlers to the product surface.

```tsx theme={null}
import { Skeleton } from '@tuturuuu/ui/skeleton';

<Skeleton className="h-6 w-32" />
```

## Examples

Examples reuse the registry snippets so the docs stay aligned with the component catalog.

### Default

A minimal implementation using the current registry snippet.

```tsx theme={null}
import { Skeleton } from '@tuturuuu/ui/skeleton';

<Skeleton className="h-6 w-32" />
```

### Package import

Import through the public package path so workspace and external apps share the same contract.

```tsx theme={null}
// Public package import
import { Skeleton } from '@tuturuuu/ui/skeleton';

// Workspace apps should keep importing through the package boundary.
```

## API reference

The public exports currently available from this component entry.

| Export     | Kind      |
| ---------- | --------- |
| `Skeleton` | component |

## Customization

Common props, states, and composition points to review before using this component.

* Shape
* Size
* Layout

## Related components

* [Alert](./alert)
* [Avatar](./avatar)
* [Badge](./badge)


# Slider
Source: https://docs.tuturuuu.com/platform/components/ui/slider

Preview Slider, copy setup snippets, review examples, and inspect API exports for @tuturuuu/ui/slider.

<Info>
  Explore the live, interactive preview at [tuturuuu.com/ui/components/slider](https://tuturuuu.com/ui/components/slider).
</Info>

**Category:** Inputs · **Import:** `@tuturuuu/ui/slider` · **Status:** Live preview

## Installation

Install the shared UI package, import global styles once, then import the component from its public subpath.

```bash theme={null}
bun add @tuturuuu/ui
```

```tsx theme={null}
import '@tuturuuu/ui/globals.css';
import { Slider } from '@tuturuuu/ui/slider';
```

## Usage

Copy the default usage snippet and adapt labels, state, and event handlers to the product surface.

```tsx theme={null}
import { Slider } from '@tuturuuu/ui/slider';

<Slider defaultValue={[64]} max={100} step={1} />
```

## Examples

Examples reuse the registry snippets so the docs stay aligned with the component catalog.

### Default

A minimal implementation using the current registry snippet.

```tsx theme={null}
import { Slider } from '@tuturuuu/ui/slider';

<Slider defaultValue={[64]} max={100} step={1} />
```

### Package import

Import through the public package path so workspace and external apps share the same contract.

```tsx theme={null}
// Public package import
import { Slider } from '@tuturuuu/ui/slider';

// Workspace apps should keep importing through the package boundary.
```

## API reference

The public exports currently available from this component entry.

| Export   | Kind      |
| -------- | --------- |
| `Slider` | component |

## Customization

Common props, states, and composition points to review before using this component.

* Min and max
* Step
* Value

## Related components

* [Calendar](./calendar)
* [Checkbox](./checkbox)
* [Color Picker](./color-picker)


# Sonner
Source: https://docs.tuturuuu.com/platform/components/ui/sonner

Preview Sonner, copy setup snippets, review examples, and inspect API exports for @tuturuuu/ui/sonner.

<Info>
  Explore the live, interactive preview at [tuturuuu.com/ui/components/sonner](https://tuturuuu.com/ui/components/sonner).
</Info>

**Category:** Feedback · **Import:** `@tuturuuu/ui/sonner` · **Status:** Live preview

## Installation

Install the shared UI package, import global styles once, then import the component from its public subpath.

```bash theme={null}
bun add @tuturuuu/ui
```

```tsx theme={null}
import '@tuturuuu/ui/globals.css';
import { Toaster, toast } from '@tuturuuu/ui/sonner';
```

## Usage

Copy the default usage snippet and adapt labels, state, and event handlers to the product surface.

```tsx theme={null}
import { Toaster, toast } from '@tuturuuu/ui/sonner';

toast.success('Saved changes');

<Toaster />
```

## Examples

Examples reuse the registry snippets so the docs stay aligned with the component catalog.

### Default

A minimal implementation using the current registry snippet.

```tsx theme={null}
import { Toaster, toast } from '@tuturuuu/ui/sonner';

toast.success('Saved changes');

<Toaster />
```

### Composition

Use the grouped exports when the primitive has slots, triggers, content regions, or providers.

```tsx theme={null}
import {
  Toaster,
  toast,
} from '@tuturuuu/ui/sonner';
```

### Package import

Import through the public package path so workspace and external apps share the same contract.

```tsx theme={null}
// Public package import
import { Toaster } from '@tuturuuu/ui/sonner';

// Workspace apps should keep importing through the package boundary.
```

## API reference

The public exports currently available from this component entry.

| Export    | Kind      |
| --------- | --------- |
| `Toaster` | component |
| `toast`   | helper    |

## Customization

Common props, states, and composition points to review before using this component.

* Theme
* Position
* Action

## Related components

* [Alert](./alert)
* [Avatar](./avatar)
* [Badge](./badge)


# Sticky Bottom Bar
Source: https://docs.tuturuuu.com/platform/components/ui/sticky-bottom-bar

Preview Sticky Bottom Bar, copy setup snippets, review examples, and inspect API exports for @tuturuuu/ui/sticky-bottom-bar.

<Info>
  Explore the live, interactive preview at [tuturuuu.com/ui/components/sticky-bottom-bar](https://tuturuuu.com/ui/components/sticky-bottom-bar).
</Info>

**Category:** Feedback · **Import:** `@tuturuuu/ui/sticky-bottom-bar` · **Status:** Pattern preview

## Installation

Install the shared UI package, import global styles once, then import the component from its public subpath.

```bash theme={null}
bun add @tuturuuu/ui
```

```tsx theme={null}
import '@tuturuuu/ui/globals.css';
import { StickyBottomBar } from '@tuturuuu/ui/sticky-bottom-bar';
```

## Usage

Copy the default usage snippet and adapt labels, state, and event handlers to the product surface.

```tsx theme={null}
import { StickyBottomBar } from '@tuturuuu/ui/sticky-bottom-bar';

<StickyBottomBar show message="Unsaved changes" actions={<Button>Save</Button>} />
```

## Examples

Examples reuse the registry snippets so the docs stay aligned with the component catalog.

### Default

A minimal implementation using the current registry snippet.

```tsx theme={null}
import { StickyBottomBar } from '@tuturuuu/ui/sticky-bottom-bar';

<StickyBottomBar show message="Unsaved changes" actions={<Button>Save</Button>} />
```

### Package import

Import through the public package path so workspace and external apps share the same contract.

```tsx theme={null}
// Public package import
import { StickyBottomBar } from '@tuturuuu/ui/sticky-bottom-bar';

// Workspace apps should keep importing through the package boundary.
```

## API reference

The public exports currently available from this component entry.

| Export            | Kind      |
| ----------------- | --------- |
| `StickyBottomBar` | component |

## Customization

Common props, states, and composition points to review before using this component.

* Visibility
* Message
* Actions

## Related components

* [Alert](./alert)
* [Avatar](./avatar)
* [Badge](./badge)


# Switch
Source: https://docs.tuturuuu.com/platform/components/ui/switch

Preview Switch, copy setup snippets, review examples, and inspect API exports for @tuturuuu/ui/switch.

<Info>
  Explore the live, interactive preview at [tuturuuu.com/ui/components/switch](https://tuturuuu.com/ui/components/switch).
</Info>

**Category:** Inputs · **Import:** `@tuturuuu/ui/switch` · **Status:** Live preview

## Installation

Install the shared UI package, import global styles once, then import the component from its public subpath.

```bash theme={null}
bun add @tuturuuu/ui
```

```tsx theme={null}
import '@tuturuuu/ui/globals.css';
import { Switch } from '@tuturuuu/ui/switch';
```

## Usage

Copy the default usage snippet and adapt labels, state, and event handlers to the product surface.

```tsx theme={null}
import { Switch } from '@tuturuuu/ui/switch';

<Switch defaultChecked />
```

## Examples

Examples reuse the registry snippets so the docs stay aligned with the component catalog.

### Default

A minimal implementation using the current registry snippet.

```tsx theme={null}
import { Switch } from '@tuturuuu/ui/switch';

<Switch defaultChecked />
```

### Package import

Import through the public package path so workspace and external apps share the same contract.

```tsx theme={null}
// Public package import
import { Switch } from '@tuturuuu/ui/switch';

// Workspace apps should keep importing through the package boundary.
```

## API reference

The public exports currently available from this component entry.

| Export   | Kind      |
| -------- | --------- |
| `Switch` | component |

## Customization

Common props, states, and composition points to review before using this component.

* Checked state
* Disabled state
* Label

## Related components

* [Calendar](./calendar)
* [Checkbox](./checkbox)
* [Color Picker](./color-picker)


# Table
Source: https://docs.tuturuuu.com/platform/components/ui/table

Preview Table, copy setup snippets, review examples, and inspect API exports for @tuturuuu/ui/table.

<Info>
  Explore the live, interactive preview at [tuturuuu.com/ui/components/table](https://tuturuuu.com/ui/components/table).
</Info>

**Category:** Data · **Import:** `@tuturuuu/ui/table` · **Status:** Live preview

## Installation

Install the shared UI package, import global styles once, then import the component from its public subpath.

```bash theme={null}
bun add @tuturuuu/ui
```

```tsx theme={null}
import '@tuturuuu/ui/globals.css';
import { Table, TableHeader, TableRow, TableHead, TableBody, TableCell } from '@tuturuuu/ui/table';
```

## Usage

Copy the default usage snippet and adapt labels, state, and event handlers to the product surface.

```tsx theme={null}
import { Table, TableBody, TableCell, TableHead, TableHeader, TableRow } from '@tuturuuu/ui/table';

<Table><TableHeader><TableRow><TableHead>Name</TableHead></TableRow></TableHeader><TableBody><TableRow><TableCell>Mira</TableCell></TableRow></TableBody></Table>
```

## Examples

Examples reuse the registry snippets so the docs stay aligned with the component catalog.

### Default

A minimal implementation using the current registry snippet.

```tsx theme={null}
import { Table, TableBody, TableCell, TableHead, TableHeader, TableRow } from '@tuturuuu/ui/table';

<Table><TableHeader><TableRow><TableHead>Name</TableHead></TableRow></TableHeader><TableBody><TableRow><TableCell>Mira</TableCell></TableRow></TableBody></Table>
```

### Composition

Use the grouped exports when the primitive has slots, triggers, content regions, or providers.

```tsx theme={null}
import {
  Table,
  TableHeader,
  TableRow,
  TableHead,
  TableBody,
  TableCell,
} from '@tuturuuu/ui/table';
```

### Package import

Import through the public package path so workspace and external apps share the same contract.

```tsx theme={null}
// Public package import
import { Table } from '@tuturuuu/ui/table';

// Workspace apps should keep importing through the package boundary.
```

## API reference

The public exports currently available from this component entry.

| Export        | Kind      |
| ------------- | --------- |
| `Table`       | component |
| `TableHeader` | component |
| `TableRow`    | component |
| `TableHead`   | component |
| `TableBody`   | component |
| `TableCell`   | component |

## Customization

Common props, states, and composition points to review before using this component.

* Columns
* Density
* Empty state

## Related components

* [Chart](./chart)
* [Diff Viewer](./diff-viewer)
* [Accordion](./accordion)


# Tabs
Source: https://docs.tuturuuu.com/platform/components/ui/tabs

Preview Tabs, copy setup snippets, review examples, and inspect API exports for @tuturuuu/ui/tabs.

<Info>
  Explore the live, interactive preview at [tuturuuu.com/ui/components/tabs](https://tuturuuu.com/ui/components/tabs).
</Info>

**Category:** Navigation · **Import:** `@tuturuuu/ui/tabs` · **Status:** Live preview

## Installation

Install the shared UI package, import global styles once, then import the component from its public subpath.

```bash theme={null}
bun add @tuturuuu/ui
```

```tsx theme={null}
import '@tuturuuu/ui/globals.css';
import { Tabs, TabsList, TabsTrigger, TabsContent } from '@tuturuuu/ui/tabs';
```

## Usage

Copy the default usage snippet and adapt labels, state, and event handlers to the product surface.

```tsx theme={null}
import { Tabs, TabsContent, TabsList, TabsTrigger } from '@tuturuuu/ui/tabs';

<Tabs defaultValue="preview"><TabsList><TabsTrigger value="preview">Preview</TabsTrigger></TabsList><TabsContent value="preview">Content</TabsContent></Tabs>
```

## Examples

Examples reuse the registry snippets so the docs stay aligned with the component catalog.

### Default

A minimal implementation using the current registry snippet.

```tsx theme={null}
import { Tabs, TabsContent, TabsList, TabsTrigger } from '@tuturuuu/ui/tabs';

<Tabs defaultValue="preview"><TabsList><TabsTrigger value="preview">Preview</TabsTrigger></TabsList><TabsContent value="preview">Content</TabsContent></Tabs>
```

### Composition

Use the grouped exports when the primitive has slots, triggers, content regions, or providers.

```tsx theme={null}
import {
  Tabs,
  TabsList,
  TabsTrigger,
  TabsContent,
} from '@tuturuuu/ui/tabs';
```

### Package import

Import through the public package path so workspace and external apps share the same contract.

```tsx theme={null}
// Public package import
import { Tabs } from '@tuturuuu/ui/tabs';

// Workspace apps should keep importing through the package boundary.
```

## API reference

The public exports currently available from this component entry.

| Export        | Kind      |
| ------------- | --------- |
| `Tabs`        | component |
| `TabsList`    | component |
| `TabsTrigger` | component |
| `TabsContent` | component |

## Customization

Common props, states, and composition points to review before using this component.

* Default value
* Orientation
* Content

## Related components

* [Breadcrumb](./breadcrumb)
* [Command](./command)
* [Quick Command Center](./quick-command-center)


# Textarea
Source: https://docs.tuturuuu.com/platform/components/ui/textarea

Preview Textarea, copy setup snippets, review examples, and inspect API exports for @tuturuuu/ui/textarea.

<Info>
  Explore the live, interactive preview at [tuturuuu.com/ui/components/textarea](https://tuturuuu.com/ui/components/textarea).
</Info>

**Category:** Inputs · **Import:** `@tuturuuu/ui/textarea` · **Status:** Live preview

## Installation

Install the shared UI package, import global styles once, then import the component from its public subpath.

```bash theme={null}
bun add @tuturuuu/ui
```

```tsx theme={null}
import '@tuturuuu/ui/globals.css';
import { Textarea } from '@tuturuuu/ui/textarea';
```

## Usage

Copy the default usage snippet and adapt labels, state, and event handlers to the product surface.

```tsx theme={null}
import { Textarea } from '@tuturuuu/ui/textarea';

<Textarea placeholder="Write an update..." />
```

## Examples

Examples reuse the registry snippets so the docs stay aligned with the component catalog.

### Default

A minimal implementation using the current registry snippet.

```tsx theme={null}
import { Textarea } from '@tuturuuu/ui/textarea';

<Textarea placeholder="Write an update..." />
```

### Package import

Import through the public package path so workspace and external apps share the same contract.

```tsx theme={null}
// Public package import
import { Textarea } from '@tuturuuu/ui/textarea';

// Workspace apps should keep importing through the package boundary.
```

## API reference

The public exports currently available from this component entry.

| Export     | Kind      |
| ---------- | --------- |
| `Textarea` | component |

## Customization

Common props, states, and composition points to review before using this component.

* Rows
* Placeholder
* Resize

## Related components

* [Calendar](./calendar)
* [Checkbox](./checkbox)
* [Color Picker](./color-picker)


# Time Picker Input
Source: https://docs.tuturuuu.com/platform/components/ui/time-picker-input

Preview Time Picker Input, copy setup snippets, review examples, and inspect API exports for @tuturuuu/ui/time-picker-input.

<Info>
  Explore the live, interactive preview at [tuturuuu.com/ui/components/time-picker-input](https://tuturuuu.com/ui/components/time-picker-input).
</Info>

**Category:** Inputs · **Import:** `@tuturuuu/ui/time-picker-input` · **Status:** Live preview

## Installation

Install the shared UI package, import global styles once, then import the component from its public subpath.

```bash theme={null}
bun add @tuturuuu/ui
```

```tsx theme={null}
import '@tuturuuu/ui/globals.css';
import { TimePickerInput } from '@tuturuuu/ui/time-picker-input';
```

## Usage

Copy the default usage snippet and adapt labels, state, and event handlers to the product surface.

```tsx theme={null}
import { TimePickerInput } from '@tuturuuu/ui/time-picker-input';

<TimePickerInput picker="hours" date={date} setDate={setDate} />
```

## Examples

Examples reuse the registry snippets so the docs stay aligned with the component catalog.

### Default

A minimal implementation using the current registry snippet.

```tsx theme={null}
import { TimePickerInput } from '@tuturuuu/ui/time-picker-input';

<TimePickerInput picker="hours" date={date} setDate={setDate} />
```

### Package import

Import through the public package path so workspace and external apps share the same contract.

```tsx theme={null}
// Public package import
import { TimePickerInput } from '@tuturuuu/ui/time-picker-input';

// Workspace apps should keep importing through the package boundary.
```

## API reference

The public exports currently available from this component entry.

| Export            | Kind      |
| ----------------- | --------- |
| `TimePickerInput` | component |

## Customization

Common props, states, and composition points to review before using this component.

* Picker
* Date
* Keyboard

## Related components

* [Calendar](./calendar)
* [Checkbox](./checkbox)
* [Color Picker](./color-picker)


# Toast
Source: https://docs.tuturuuu.com/platform/components/ui/toast

Preview Toast, copy setup snippets, review examples, and inspect API exports for @tuturuuu/ui/toast.

<Info>
  Explore the live, interactive preview at [tuturuuu.com/ui/components/toast](https://tuturuuu.com/ui/components/toast).
</Info>

**Category:** Feedback · **Import:** `@tuturuuu/ui/toast` · **Status:** Live preview

## Installation

Install the shared UI package, import global styles once, then import the component from its public subpath.

```bash theme={null}
bun add @tuturuuu/ui
```

```tsx theme={null}
import '@tuturuuu/ui/globals.css';
import { Toast, ToastTitle, ToastDescription, ToastProvider } from '@tuturuuu/ui/toast';
```

## Usage

Copy the default usage snippet and adapt labels, state, and event handlers to the product surface.

```tsx theme={null}
import { Toast, ToastDescription, ToastTitle } from '@tuturuuu/ui/toast';

<Toast><ToastTitle>Saved</ToastTitle><ToastDescription>Your changes are live.</ToastDescription></Toast>
```

## Examples

Examples reuse the registry snippets so the docs stay aligned with the component catalog.

### Default

A minimal implementation using the current registry snippet.

```tsx theme={null}
import { Toast, ToastDescription, ToastTitle } from '@tuturuuu/ui/toast';

<Toast><ToastTitle>Saved</ToastTitle><ToastDescription>Your changes are live.</ToastDescription></Toast>
```

### Composition

Use the grouped exports when the primitive has slots, triggers, content regions, or providers.

```tsx theme={null}
import {
  Toast,
  ToastTitle,
  ToastDescription,
  ToastProvider,
} from '@tuturuuu/ui/toast';
```

### Package import

Import through the public package path so workspace and external apps share the same contract.

```tsx theme={null}
// Public package import
import { Toast } from '@tuturuuu/ui/toast';

// Workspace apps should keep importing through the package boundary.
```

## API reference

The public exports currently available from this component entry.

| Export             | Kind      |
| ------------------ | --------- |
| `Toast`            | component |
| `ToastTitle`       | component |
| `ToastDescription` | component |
| `ToastProvider`    | provider  |

## Customization

Common props, states, and composition points to review before using this component.

* Variant
* Action
* Viewport

## Related components

* [Alert](./alert)
* [Avatar](./avatar)
* [Badge](./badge)


# Toaster
Source: https://docs.tuturuuu.com/platform/components/ui/toaster

Preview Toaster, copy setup snippets, review examples, and inspect API exports for @tuturuuu/ui/toaster.

<Info>
  Explore the live, interactive preview at [tuturuuu.com/ui/components/toaster](https://tuturuuu.com/ui/components/toaster).
</Info>

**Category:** Feedback · **Import:** `@tuturuuu/ui/toaster` · **Status:** Live preview

## Installation

Install the shared UI package, import global styles once, then import the component from its public subpath.

```bash theme={null}
bun add @tuturuuu/ui
```

```tsx theme={null}
import '@tuturuuu/ui/globals.css';
import { Toaster } from '@tuturuuu/ui/toaster';
```

## Usage

Copy the default usage snippet and adapt labels, state, and event handlers to the product surface.

```tsx theme={null}
import { Toaster } from '@tuturuuu/ui/toaster';

<Toaster />
```

## Examples

Examples reuse the registry snippets so the docs stay aligned with the component catalog.

### Default

A minimal implementation using the current registry snippet.

```tsx theme={null}
import { Toaster } from '@tuturuuu/ui/toaster';

<Toaster />
```

### Package import

Import through the public package path so workspace and external apps share the same contract.

```tsx theme={null}
// Public package import
import { Toaster } from '@tuturuuu/ui/toaster';

// Workspace apps should keep importing through the package boundary.
```

## API reference

The public exports currently available from this component entry.

| Export    | Kind      |
| --------- | --------- |
| `Toaster` | component |

## Customization

Common props, states, and composition points to review before using this component.

* Provider
* Viewport
* Hooks

## Related components

* [Alert](./alert)
* [Avatar](./avatar)
* [Badge](./badge)


# Toggle
Source: https://docs.tuturuuu.com/platform/components/ui/toggle

Preview Toggle, copy setup snippets, review examples, and inspect API exports for @tuturuuu/ui/toggle.

<Info>
  Explore the live, interactive preview at [tuturuuu.com/ui/components/toggle](https://tuturuuu.com/ui/components/toggle).
</Info>

**Category:** Actions · **Import:** `@tuturuuu/ui/toggle` · **Status:** Live preview

## Installation

Install the shared UI package, import global styles once, then import the component from its public subpath.

```bash theme={null}
bun add @tuturuuu/ui
```

```tsx theme={null}
import '@tuturuuu/ui/globals.css';
import { Toggle, toggleVariants } from '@tuturuuu/ui/toggle';
```

## Usage

Copy the default usage snippet and adapt labels, state, and event handlers to the product surface.

```tsx theme={null}
import { Toggle } from '@tuturuuu/ui/toggle';

<Toggle aria-label="Toggle bold">B</Toggle>
```

## Examples

Examples reuse the registry snippets so the docs stay aligned with the component catalog.

### Default

A minimal implementation using the current registry snippet.

```tsx theme={null}
import { Toggle } from '@tuturuuu/ui/toggle';

<Toggle aria-label="Toggle bold">B</Toggle>
```

### Composition

Use the grouped exports when the primitive has slots, triggers, content regions, or providers.

```tsx theme={null}
import {
  Toggle,
  toggleVariants,
} from '@tuturuuu/ui/toggle';
```

### Package import

Import through the public package path so workspace and external apps share the same contract.

```tsx theme={null}
// Public package import
import { Toggle } from '@tuturuuu/ui/toggle';

// Workspace apps should keep importing through the package boundary.
```

## API reference

The public exports currently available from this component entry.

| Export           | Kind      |
| ---------------- | --------- |
| `Toggle`         | component |
| `toggleVariants` | helper    |

## Customization

Common props, states, and composition points to review before using this component.

* Pressed state
* Variant
* Size

## Related components

* [Button](./button)
* [Toggle Group](./toggle-group)
* [Accordion](./accordion)


# Toggle Group
Source: https://docs.tuturuuu.com/platform/components/ui/toggle-group

Preview Toggle Group, copy setup snippets, review examples, and inspect API exports for @tuturuuu/ui/toggle-group.

<Info>
  Explore the live, interactive preview at [tuturuuu.com/ui/components/toggle-group](https://tuturuuu.com/ui/components/toggle-group).
</Info>

**Category:** Actions · **Import:** `@tuturuuu/ui/toggle-group` · **Status:** Live preview

## Installation

Install the shared UI package, import global styles once, then import the component from its public subpath.

```bash theme={null}
bun add @tuturuuu/ui
```

```tsx theme={null}
import '@tuturuuu/ui/globals.css';
import { ToggleGroup, ToggleGroupItem } from '@tuturuuu/ui/toggle-group';
```

## Usage

Copy the default usage snippet and adapt labels, state, and event handlers to the product surface.

```tsx theme={null}
import { ToggleGroup, ToggleGroupItem } from '@tuturuuu/ui/toggle-group';

<ToggleGroup type="single" defaultValue="list"><ToggleGroupItem value="list">List</ToggleGroupItem></ToggleGroup>
```

## Examples

Examples reuse the registry snippets so the docs stay aligned with the component catalog.

### Default

A minimal implementation using the current registry snippet.

```tsx theme={null}
import { ToggleGroup, ToggleGroupItem } from '@tuturuuu/ui/toggle-group';

<ToggleGroup type="single" defaultValue="list"><ToggleGroupItem value="list">List</ToggleGroupItem></ToggleGroup>
```

### Composition

Use the grouped exports when the primitive has slots, triggers, content regions, or providers.

```tsx theme={null}
import {
  ToggleGroup,
  ToggleGroupItem,
} from '@tuturuuu/ui/toggle-group';
```

### Package import

Import through the public package path so workspace and external apps share the same contract.

```tsx theme={null}
// Public package import
import { ToggleGroup } from '@tuturuuu/ui/toggle-group';

// Workspace apps should keep importing through the package boundary.
```

## API reference

The public exports currently available from this component entry.

| Export            | Kind      |
| ----------------- | --------- |
| `ToggleGroup`     | component |
| `ToggleGroupItem` | component |

## Customization

Common props, states, and composition points to review before using this component.

* Type
* Selection
* Size

## Related components

* [Button](./button)
* [Toggle](./toggle)
* [Accordion](./accordion)


# Tooltip
Source: https://docs.tuturuuu.com/platform/components/ui/tooltip

Preview Tooltip, copy setup snippets, review examples, and inspect API exports for @tuturuuu/ui/tooltip.

<Info>
  Explore the live, interactive preview at [tuturuuu.com/ui/components/tooltip](https://tuturuuu.com/ui/components/tooltip).
</Info>

**Category:** Overlays · **Import:** `@tuturuuu/ui/tooltip` · **Status:** Live preview

## Installation

Install the shared UI package, import global styles once, then import the component from its public subpath.

```bash theme={null}
bun add @tuturuuu/ui
```

```tsx theme={null}
import '@tuturuuu/ui/globals.css';
import { Tooltip, TooltipTrigger, TooltipContent, TooltipProvider } from '@tuturuuu/ui/tooltip';
```

## Usage

Copy the default usage snippet and adapt labels, state, and event handlers to the product surface.

```tsx theme={null}
import { Tooltip, TooltipContent, TooltipTrigger } from '@tuturuuu/ui/tooltip';

<Tooltip><TooltipTrigger>Hover</TooltipTrigger><TooltipContent>Helpful context</TooltipContent></Tooltip>
```

## Examples

Examples reuse the registry snippets so the docs stay aligned with the component catalog.

### Default

A minimal implementation using the current registry snippet.

```tsx theme={null}
import { Tooltip, TooltipContent, TooltipTrigger } from '@tuturuuu/ui/tooltip';

<Tooltip><TooltipTrigger>Hover</TooltipTrigger><TooltipContent>Helpful context</TooltipContent></Tooltip>
```

### Composition

Use the grouped exports when the primitive has slots, triggers, content regions, or providers.

```tsx theme={null}
import {
  Tooltip,
  TooltipTrigger,
  TooltipContent,
  TooltipProvider,
} from '@tuturuuu/ui/tooltip';
```

### Package import

Import through the public package path so workspace and external apps share the same contract.

```tsx theme={null}
// Public package import
import { Tooltip } from '@tuturuuu/ui/tooltip';

// Workspace apps should keep importing through the package boundary.
```

## API reference

The public exports currently available from this component entry.

| Export            | Kind      |
| ----------------- | --------- |
| `Tooltip`         | component |
| `TooltipTrigger`  | component |
| `TooltipContent`  | component |
| `TooltipProvider` | provider  |

## Customization

Common props, states, and composition points to review before using this component.

* Delay
* Side
* Content

## Related components

* [Alert Dialog](./alert-dialog)
* [Context Menu](./context-menu)
* [Dialog](./dialog)


# WorkspaceWrapper Component
Source: https://docs.tuturuuu.com/platform/components/workspace-wrapper

A standardized component for handling workspace ID resolution and validation across the application

The `WorkspaceWrapper` component provides a centralized way to handle workspace ID resolution and validation across the application. It automatically converts legacy workspace identifiers to validated UUIDs and provides the full workspace object to child components.

## Problem Solved

Currently, workspace ID resolution is handled inconsistently across components:

* `'personal'` → resolves to the user's personal workspace UUID
* `'internal'` → resolves to `ROOT_WORKSPACE_ID`
* UUID strings → validates and uses as-is

The `WorkspaceWrapper` centralizes this logic and ensures that child components always receive a validated workspace UUID. After resolution, the `isPersonal` flag is derived from the resolved `workspace.personal` field (not from the original `'personal'` URL string), and `isRoot` is derived by comparing `workspace.id` to `ROOT_WORKSPACE_ID`.

<Note>
  This component is specific to the **Next.js App Router** server-component model in `apps/web` (port `7803`). It relies on async `params`, React Suspense, and server-side `getWorkspace`. The platform is actively migrating `apps/web` to `apps/tanstack-web` (TanStack Start) plus `apps/backend` (Rust); see [/platform/architecture/tanstack-rust-migration](/platform/architecture/tanstack-rust-migration). This wrapper pattern does not carry over verbatim to the TanStack Start app, but the `apps/web` documentation below remains valid for the current platform.
</Note>

## URL Context

The `WorkspaceWrapper` is designed for use in Next.js App Router pages with dynamic segments:

### Basic Pattern

* **File structure**: `apps/web/src/app/[locale]/(dashboard)/[wsId]/page.tsx`
* **User-facing URL**: `/[wsId]/...` (locale handled transparently by middleware)
* **Route params**: `{ wsId: string }`

### Advanced Pattern with Additional Params

* **File structure**: `apps/web/src/app/[locale]/(dashboard)/[wsId]/[datasetId]/page.tsx`
* **User-facing URL**: `/[wsId]/[datasetId]/...`
* **Route params**: `{ wsId: string, datasetId: string }`

The component automatically passes through any additional parameters beyond `wsId` to the children function.

## Installation

The canonical source lives in the shared UI package at `@tuturuuu/ui/custom/workspace-wrapper` (file: `packages/ui/src/components/ui/custom/workspace-wrapper.tsx`).

```tsx theme={null}
// Canonical import (shared package — works in any consumer)
import WorkspaceWrapper, {
  withWorkspace,
  type BaseParams,
  type WorkspaceWrapperProps,
} from '@tuturuuu/ui/custom/workspace-wrapper';
```

Within `apps/web` you may also see the legacy path `@/components/workspace-wrapper`. That module is a thin backward-compatible re-export of the canonical package and exposes the same `default`, `withWorkspace`, `BaseParams`, and `WorkspaceWrapperProps` symbols:

```tsx theme={null}
// Backward-compatible re-export inside apps/web
import WorkspaceWrapper from '@/components/workspace-wrapper';
```

Prefer the `@tuturuuu/ui/custom/workspace-wrapper` import for new code, especially in shared packages and other apps.

## Basic Usage

### Function Children Pattern

```tsx theme={null}
export default async function MyPage({ 
  params 
}: { 
  params: Promise<{ wsId: string }> 
}) {
  return (
    <WorkspaceWrapper params={params}>
      {({ workspace, wsId, isPersonal, isRoot }) => (
        <div>
          <h1>{workspace.name}</h1>
          <p>Workspace UUID: {wsId}</p>
          <p>Is Personal: {isPersonal ? 'Yes' : 'No'}</p>
          <p>Is Root: {isRoot ? 'Yes' : 'No'}</p>
        </div>
      )}
    </WorkspaceWrapper>
  );
}
```

### With Loading Fallback

```tsx theme={null}
import LoadingSpinner from '@/components/loading-spinner';

export default async function MyPage({ 
  params 
}: { 
  params: Promise<{ wsId: string }> 
}) {
  return (
    <WorkspaceWrapper 
      params={params}
      fallback={<LoadingSpinner />}
    >
      {({ workspace, wsId, isPersonal, isRoot }) => (
        <MyWorkspaceContent workspace={workspace} wsId={wsId} />
      )}
    </WorkspaceWrapper>
  );
}
```

## Advanced Usage

### With Additional Route Parameters

For pages with additional dynamic segments beyond `wsId`:

```tsx theme={null}
// File: apps/web/src/app/[locale]/(dashboard)/[wsId]/[datasetId]/page.tsx
// URL: /personal/datasets/123, /550e8400-e29b-41d4-a716-446655440000/datasets/456
export default async function DatasetPage({
  params
}: {
  params: Promise<{ wsId: string; datasetId: string }>
}) {
  return (
    <WorkspaceWrapper params={params}>
      {({ workspace, wsId, isPersonal, isRoot, datasetId }) => (
        <div>
          <h1>{workspace.name} - Dataset {datasetId}</h1>
          <p>Workspace UUID: {wsId}</p>
          <p>Dataset ID: {datasetId}</p>
          <p>Is Personal: {isPersonal ? 'Yes' : 'No'}</p>
        </div>
      )}
    </WorkspaceWrapper>
  );
}
```

The `WorkspaceWrapper` automatically passes through `datasetId` (and any other additional params) to the children function.

### Using withWorkspace Helper

For client components that need workspace context, use the `withWorkspace` helper:

```tsx theme={null}
import { withWorkspace } from '@tuturuuu/ui/custom/workspace-wrapper';
import MyClientComponent from './my-client-component';

export default async function MyPage({
  params
}: {
  params: Promise<{ wsId: string }>
}) {
  const { wsId } = await params;

  return withWorkspace(
    wsId,
    MyClientComponent,
    {
      someProp: 'value',
      anotherProp: 42
    },
    <div>Loading workspace...</div>
  );
}
```

### Client Component Receiving Workspace Props

```tsx theme={null}
'use client';

import type { Workspace, WorkspaceProductTier } from '@tuturuuu/types';

interface MyClientComponentProps {
  workspace: Workspace & {
    joined: boolean;
    tier: WorkspaceProductTier | null;
  };
  wsId: string; // Validated UUID
  isPersonal: boolean;
  isRoot: boolean;
  someProp: string;
  anotherProp: number;
}

export function MyClientComponent({ 
  workspace, 
  wsId, 
  isPersonal,
  isRoot,
  someProp, 
  anotherProp 
}: MyClientComponentProps) {
  // Use workspace and wsId safely - they're guaranteed to be valid
  return (
    <div>
      <h1>{workspace.name}</h1>
      <p>Workspace ID: {wsId}</p>
      <p>Personal: {isPersonal ? 'Yes' : 'No'}</p>
      <p>Root: {isRoot ? 'Yes' : 'No'}</p>
    </div>
  );
}
```

## API Reference

### WorkspaceWrapper Props

| Prop       | Type                                                  | Required | Description                                                                           |
| ---------- | ----------------------------------------------------- | -------- | ------------------------------------------------------------------------------------- |
| `params`   | `Promise<TParams>` where `TParams extends BaseParams` | Yes      | The route params containing `wsId` and any additional params                          |
| `children` | `Function`                                            | Yes      | Function that receives `{ workspace, wsId, isPersonal, isRoot, ...additionalParams }` |
| `fallback` | `ReactNode`                                           | No       | Loading fallback component                                                            |

**Note**: The `params` type is generic and supports additional route parameters beyond the base `locale` and `wsId`.

### withWorkspace Parameters

| Parameter   | Type                  | Required | Description                               |
| ----------- | --------------------- | -------- | ----------------------------------------- |
| `wsId`      | `string`              | Yes      | The workspace identifier (legacy or UUID) |
| `Component` | `React.ComponentType` | Yes      | Client component to render                |
| `props`     | `T`                   | Yes      | Props to pass to the component            |
| `fallback`  | `ReactNode`           | No       | Loading fallback component                |

### Children Function Parameters

| Parameter             | Type                                                                  | Description                                                                                                                     |
| --------------------- | --------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `workspace`           | `Workspace & { joined: boolean; tier: WorkspaceProductTier \| null }` | Full workspace object, including `joined` status and the resolved product `tier` (`null` when the workspace has no active tier) |
| `wsId`                | `string`                                                              | Validated UUID from `workspace.id`                                                                                              |
| `isPersonal`          | `boolean`                                                             | Whether the workspace is a personal workspace                                                                                   |
| `isRoot`              | `boolean`                                                             | Whether the workspace is the root/internal workspace                                                                            |
| `...additionalParams` | `TParams extends BaseParams`                                          | Any additional route parameters beyond `wsId` (e.g., `datasetId`, `taskId`)                                                     |

**Note**: Additional parameters are automatically passed through from the route params object.

## Migration Guide

### Before (Manual Resolution)

```tsx theme={null}
export default async function MyPage({
  params
}: {
  params: Promise<{ wsId: string }>;
}) {
  const { wsId: id } = await params;

  const workspace = await getWorkspace(id);
  if (!workspace) notFound();

  const wsId = workspace.id; // Manual extraction

  return <MyComponent workspace={workspace} wsId={wsId} />;
}
```

### After (With WorkspaceWrapper)

```tsx theme={null}
export default async function MyPage({
  params
}: {
  params: Promise<{ wsId: string }>
}) {
  return (
    <WorkspaceWrapper params={params}>
      {({ workspace, wsId }) => (
        <MyComponent workspace={workspace} wsId={wsId} />
      )}
    </WorkspaceWrapper>
  );
}
```

## Real-World Example

Here's how the dashboard page uses the WorkspaceWrapper:

<CodeGroup>
  ```tsx theme={null}
  // Example 1: Basic Dashboard Page
  // File: apps/web/src/app/[locale]/(dashboard)/[wsId]/dashboard/page.tsx
  // URL: /personal/dashboard, /550e8400-e29b-41d4-a716-446655440000/dashboard
  export default async function DashboardPage({
    params
  }: {
    params: Promise<{ wsId: string }>
  }) {
    return (
      <WorkspaceWrapper params={params}>
        {({ workspace, wsId, isPersonal, isRoot }) => (
          <div className="p-6">
            <h1 className="text-2xl font-bold mb-4">
              {workspace.name || 'Unnamed Workspace'}
            </h1>
            <div className="grid gap-4">
              <div className="p-4 bg-gray-100 rounded">
                <h2 className="font-semibold">Workspace Details</h2>
                <p>ID: {wsId}</p>
                <p>Type: {isPersonal ? 'Personal' : 'Team'}</p>
                <p>Role: {workspace.role}</p>
                <p>Joined: {workspace.joined ? 'Yes' : 'No'}</p>
                <p>Root: {isRoot ? 'Yes' : 'No'}</p>
              </div>
            </div>
          </div>
        )}
      </WorkspaceWrapper>
    );
  }
  ```

  ```tsx theme={null}
  // Example 2: Settings Page with Loading State
  // File: apps/web/src/app/[locale]/(dashboard)/[wsId]/(workspace-settings)/settings/page.tsx
  // URL: /personal/settings, /550e8400-e29b-41d4-a716-446655440000/settings
  export default async function SettingsPage({
    params
  }: {
    params: Promise<{ wsId: string }>
  }) {
    return (
      <WorkspaceWrapper
        params={params}
        fallback={<div className="p-6">Loading workspace settings...</div>}
      >
        {async ({ workspace, wsId }) => {
          const currentUser = await getCurrentUser();
          const { withoutPermission } = await getPermissions({ wsId });

          return (
            <div className="p-6">
              <h1 className="text-2xl font-bold mb-4">Workspace Settings</h1>

              {withoutPermission('manage_workspace') ? (
                <div className="text-red-600">
                  You don't have permission to manage this workspace.
                </div>
              ) : (
                <div className="space-y-4">
                  <div>
                    <label className="block text-sm font-medium mb-2">
                      Workspace Name
                    </label>
                    <input
                      type="text"
                      defaultValue={workspace.name || ''}
                      className="w-full p-2 border rounded"
                    />
                  </div>

                  <div>
                    <label className="block text-sm font-medium mb-2">
                      Workspace ID (Read-only)
                    </label>
                    <input
                      type="text"
                      value={wsId}
                      readOnly
                      className="w-full p-2 border rounded bg-gray-100"
                    />
                  </div>
                </div>
              )}
            </div>
          );
        }}
      </WorkspaceWrapper>
    );
  }
  ```
</CodeGroup>

## Benefits

1. **Centralized Logic**: All workspace ID resolution logic is centralized
2. **Type Safety**: TypeScript ensures proper workspace object structure
3. **Error Handling**: Automatic `notFound()` when workspace doesn't exist
4. **Loading States**: Built-in Suspense support with custom fallbacks
5. **Cleaner Code**: Reduces boilerplate in page components
6. **Future-Proof**: Easy to modify workspace resolution logic in one place

## Error Handling

The `WorkspaceWrapper` automatically handles common error cases:

* Invalid workspace ID → `notFound()`
* User not authenticated → Redirects to login (via `getWorkspace`)
* Workspace not found → `notFound()`
* User not a member → `notFound()`

## Performance Considerations

* The wrapper uses React Suspense for loading states
* Workspace data is fetched once and passed down to children
* Consider using `fallback` prop for better UX during loading
* The component is optimized for server-side rendering

## Best Practices

1. **Always use the validated `wsId`** from the wrapper, not the original parameter
2. **Provide meaningful fallbacks** for better user experience
3. **Use the `withWorkspace` helper** for client components that need workspace context
4. **Keep workspace logic centralized** - don't duplicate workspace resolution elsewhere
5. **Handle loading states gracefully** with appropriate fallback components

## Troubleshooting

### Common Issues

**Issue**: `notFound()` is called unexpectedly
**Solution**: Ensure the user has access to the workspace and the workspace ID is valid

**Issue**: TypeScript errors with workspace object
**Solution**: Make sure you're using the workspace object provided by the wrapper, not importing it separately

**Issue**: Loading state never resolves
**Solution**: Check that the `getWorkspace` function is working correctly and not throwing errors

### Debug Tips

1. Check the browser's Network tab for failed workspace requests
2. Verify the workspace ID in the URL is correct
3. Ensure the user is authenticated and has workspace access
4. Check the console for any error messages from `getWorkspace`


# WorkspaceWrapper Quick Reference
Source: https://docs.tuturuuu.com/platform/components/workspace-wrapper-quick-reference

Quick reference guide for the WorkspaceWrapper component

## Quick Start

```tsx theme={null}
// Canonical shared-package import
import WorkspaceWrapper from '@tuturuuu/ui/custom/workspace-wrapper';
// (`@/components/workspace-wrapper` in apps/web is a thin re-export of the above)

// Basic usage - for pages like /personal/dashboard, /550e8400-e29b-41d4-a716-446655440000/tasks
<WorkspaceWrapper params={params}>
  {({ workspace, wsId, isPersonal, isRoot }) => (
    <div>{workspace.name} - {wsId}</div>
  )}
</WorkspaceWrapper>

// With loading fallback
<WorkspaceWrapper
  params={params}
  fallback={<LoadingSpinner />}
>
  {({ workspace, wsId, isPersonal, isRoot }) => <MyComponent />}
</WorkspaceWrapper>

// With additional params - for pages like /personal/datasets/123
<WorkspaceWrapper params={params}>
  {({ workspace, wsId, isPersonal, isRoot, datasetId }) => (
    <div>{workspace.name} - Dataset {datasetId}</div>
  )}
</WorkspaceWrapper>
```

## withWorkspace Helper

```tsx theme={null}
import { withWorkspace } from '@tuturuuu/ui/custom/workspace-wrapper';

// For client components
return withWorkspace(
  (await params).wsId,
  MyClientComponent,
  { prop1: 'value' },
  <LoadingSpinner />
);
```

## Props Reference

| Prop       | Type                        | Description                                        |
| ---------- | --------------------------- | -------------------------------------------------- |
| `params`   | `Promise<{ wsId: string }>` | Route params containing `wsId`                     |
| `children` | `Function`                  | Receives `{ workspace, wsId, isPersonal, isRoot }` |
| `fallback` | `ReactNode`                 | Loading fallback component                         |

## Children Function

```tsx theme={null}
{({ workspace, wsId, isPersonal, isRoot }) => {
  // workspace: Workspace & { joined: boolean; tier: WorkspaceProductTier | null }
  // wsId: string (validated UUID)
  // isPersonal: boolean
  // isRoot: boolean
}}
```

## Common Patterns

### Dashboard Page

```tsx theme={null}
// File: apps/web/src/app/[locale]/(dashboard)/[wsId]/dashboard/page.tsx
// URL: /personal/dashboard, /550e8400-e29b-41d4-a716-446655440000/dashboard
export default async function Dashboard({ params }) {
  return (
    <WorkspaceWrapper params={params}>
      {({ workspace, wsId, isPersonal, isRoot }) => (
        <DashboardContent workspace={workspace} wsId={wsId} />
      )}
    </WorkspaceWrapper>
  );
}
```

### Settings Page

```tsx theme={null}
// File: apps/web/src/app/[locale]/(dashboard)/[wsId]/(workspace-settings)/settings/page.tsx
// URL: /personal/settings, /550e8400-e29b-41d4-a716-446655440000/settings
export default async function Settings({ params }) {
  return (
    <WorkspaceWrapper params={params}>
      {({ workspace, wsId, isPersonal, isRoot }) => (
        <SettingsForm
          workspace={workspace}
          wsId={wsId}
          onSave={handleSave}
        />
      )}
    </WorkspaceWrapper>
  );
}
```

### Dataset Page (with additional params)

```tsx theme={null}
// File: apps/web/src/app/[locale]/(dashboard)/[wsId]/[datasetId]/page.tsx
// URL: /personal/datasets/123, /550e8400-e29b-41d4-a716-446655440000/datasets/456
export default async function DatasetPage({ params }) {
  return (
    <WorkspaceWrapper params={params}>
      {({ workspace, wsId, isPersonal, isRoot, datasetId }) => (
        <DatasetView
          workspace={workspace}
          wsId={wsId}
          datasetId={datasetId}
        />
      )}
    </WorkspaceWrapper>
  );
}
```

### Client Component Integration

```tsx theme={null}
// Server component - apps/web/src/app/[locale]/(dashboard)/[wsId]/(workspace-settings)/settings/page.tsx
export default async function Page({ params }) {
  return withWorkspace(
    (await params).wsId,
    WorkspaceSettings,
    { theme: 'dark' },
    <div>Loading...</div>
  );
}

// Client component
'use client';
export function WorkspaceSettings({
  workspace,
  wsId,
  isPersonal,
  isRoot,
  theme
}: {
  workspace: Workspace & { joined: boolean; tier: WorkspaceProductTier | null };
  wsId: string;
  isPersonal: boolean;
  isRoot: boolean;
  theme: string;
}) {
  return <div>{workspace.name}</div>;
}
```

## Error Handling

The wrapper automatically handles:

* Invalid workspace ID → `notFound()`
* User not authenticated → Redirects to login
* Workspace not found → `notFound()`
* User not a member → `notFound()`

## Migration Checklist

* [ ] Replace manual `getWorkspace()` calls
* [ ] Pass the route `params` Promise (not `searchParams`) into `WorkspaceWrapper`
* [ ] Use validated `wsId` from wrapper
* [ ] Add appropriate loading fallbacks
* [ ] Update TypeScript types
* [ ] Test error scenarios

## Troubleshooting

| Issue                  | Solution                                                                                  |
| ---------------------- | ----------------------------------------------------------------------------------------- |
| `notFound()` called    | Check workspace access and ID validity (ensure URL like `/personal/dashboard` is correct) |
| TypeScript errors      | Use workspace object from wrapper, not external imports                                   |
| Loading never resolves | Check `getWorkspace` function and network connectivity                                    |
| Props not passed       | Use `withWorkspace` helper for client components                                          |
| Incorrect URL pattern  | Verify using `/[wsId]/...` pattern, not `/en/[wsId]/...`                                  |


# CMS Site Contract v1
Source: https://docs.tuturuuu.com/platform/features/cms-site-contract-v1

The default reusable content and delivery contract for CMS-backed sites.

## Purpose

Use the CMS site contract for new CMS-backed websites. It is the global version
1 schema, not an external-project adapter or project-specific implementation.
External apps retain their own adapter identity and carry this contract through
workspace-scoped template metadata and collection schema/profile metadata.

Backend routes and database objects retain their existing `external-project*`
names for compatibility. Normal CMS UI should use editor-facing site and
content language.

## Standard Collections

The v1 contract starts with `site-settings`, `navigation`, `pages`, `posts`,
`taxonomies`, `landing-sections`, `redirects`, and `media-assets`. Apps may add fields and
collections through the manifest schema without creating another adapter.

The optional `template` object is versioned independently:

```json theme={null}
{
  "kind": "wordpress-replacement",
  "version": 1,
  "editor": {},
  "publicDelivery": {}
}
```

Template metadata is persisted on the workspace binding. It is returned in sync
snapshots and public delivery, but it does not create content diff operations or
destructive changes.

## Public Consumption

The Tuturuuu SDK exports `buildCmsSiteManifest` and
`normalizeCmsSiteDelivery`. The builder creates the standard schema. The
delivery normalizer indexes collections by slug and resolves relative asset
URLs against the public platform origin supplied by the consumer.

Public sites should consume read-only delivery and keep a static fallback for
availability during migration. Do not place site control secrets in public
runtime configuration.

## Migration Safety

Keep the existing site, administration routes, and realtime endpoints
authoritative while mirroring is introduced. Validate imports, reverse replies,
idempotency, retry after platform outage, and health checks on preview or local
canaries first.

Production authority or routing must not switch until the operator explicitly
approves cutover after deployed verification. A healthy bridge is a prerequisite,
not cutover approval. Rollback must restore direct legacy routing without a
database migration.

Visitor context such as route history or network information belongs in
access-controlled dynamic JSON metadata. Do not add fixed columns that reveal
or imply a particular category of confidential data.


# Command Center Dashboard
Source: https://docs.tuturuuu.com/platform/features/command-center-dashboard

A GTD-aligned dashboard with Quick Capture and processing flows to reduce cognitive overload.

## TL;DR

Users are overwhelmed by fragmented information across tools and the mental load of remembering everything they need to do. The Command Center dashboard applies the Getting Things Done (GTD) methodology to centralize daily commitments, capture new ideas instantly, and guide users from brain-dump to organized plans.

## Command Center Dashboard

### Phase 1 – The Consolidated View

* **Feature**: Present all tasks, appointments, and key reminders for the day in a single, glanceable surface.
* **Outcome**: People no longer have to hop between apps to understand their priorities.
* **User Story**: “As a busy professional, I want to see all my tasks and appointments for the day in one place so I can quickly understand my priorities without switching between apps.”

### Phase 2 – Interactive Task Management

* **Feature**: Users interact with the dashboard task list directly—completing tasks, snoozing them, or dragging items to reorder.
* **Outcome**: Daily planning happens in-context without breaking focus.
* **User Story**: “As a project manager, I want to be able to quickly complete and reschedule tasks from my main dashboard so I can efficiently manage my daily workflow.”

## GTD "Quick Capture" Bucket

### Phase 1 – The Basic Bucket

* **Feature**: A lightweight text input that accepts any idea, task, or note without forcing structure upfront. Entries land in a dedicated "Bucket" list.
* **Outcome**: Users can park thoughts instantly, reducing cognitive distractions during deep work.
* **User Story**: “As a creative thinker, I want a place to quickly dump any idea that pops into my head so I don't lose it or get distracted from my current task.”

## From Capture to Clarity

### Actionability First

Every captured item is evaluated with the GTD question: **“Is this actionable?”**

* **If No**: Users choose to trash it, archive it for reference, or send it to a Someday/Maybe list to incubate.
* **If Yes**: Determine the single, physical, visible Next Action required.

### Phase 2 – The Triage View

* **Feature**: A processing workspace dedicated to the Bucket. For each entry, provide controls to assign it to a project, set a due date, add supporting notes, archive it, or drag it directly into the correct project list.
* **Outcome**: Users transform raw thoughts into organized tasks without leaving the triage experience.
* **User Story**: “As a detail-oriented planner, I want a simple way to sort my brain-dumped notes into actionable tasks and assign them to the correct projects so I can build a clear plan of action.”

### Workflow Summary

1. **Capture**: Add anything to the Quick Capture input without worrying about structure.
2. **Clarify**: Decide whether the item is actionable, then define the Next Action.
3. **Organize**: File actionable tasks into projects, schedule them, or archive references directly from the triage workspace.
4. **Reflect**: Use the Command Center dashboard to review what is queued for today and adjust priorities through interactions like snooze or drag-to-reorder.
5. **Engage**: Confidently execute the work knowing the system has captured and clarified every commitment.

By tying the dashboard, Quick Capture Bucket, and Processing Workflow together, the platform helps users offload mental clutter while staying responsive to the day's demands.

## Related Resources

* [Documentation Organization Guide](/overview/organization-guide) – Align workspace conventions and team practices with the Command Center workflows.


# Tuturuuu CMS
Source: https://docs.tuturuuu.com/platform/features/external-project-studio

Site editing, publishing, preview, team access, and internal site-template operations for Tuturuuu CMS.

## TL;DR

Tuturuuu CMS now lives in the dedicated `apps/cms` satellite app.

New CMS-backed sites should use the [global CMS site v1 contract](/platform/features/cms-site-contract-v1). Add
site-specific structure through template and collection metadata instead of a
new adapter unless the integration has genuinely different authentication or
runtime behavior.

* `apps/cms` owns the CMS authoring UI, workspace picker, overview/content/preview/members routes, and the root `/{wsId}/projects` linking console (reached as `/internal/projects` for the root workspace).
* `apps/web` remains the only backend/API owner for CMS and external-project traffic.
* `apps/cms` rewrites `/api/*` to `apps/web`, so proxy behavior and bot protection stay centralized.

## Product Vocabulary

The visible CMS experience is a site/content product, not an implementation
console. Bound-workspace UI should say site, site template, connection, content,
section, URL path, custom details, media, publishing, preview, people,
invitations, and team access.

Avoid implementation terms in normal UI copy, including external project,
canonical, adapter, binding, slug, schema, metadata, profile data, payload, and
JSON. If operators need exact implementation values, show them only in collapsed
Developer details panels or internal root-console advanced controls. Keep code,
API routes, database objects, migration names, and integration docs on the
existing `external-project*` contracts.

## Route Model

The route tree below mirrors `apps/cms/src/app/[locale]/(dashboard)/[wsId]`.
Workspace navigation is defined in
`apps/cms/src/app/[locale]/(dashboard)/[wsId]/navigation.tsx`. Every route is
workspace-scoped under `/{wsId}`; the root workspace uses the `internal` slug
(it resolves to `ROOT_WORKSPACE_ID` via `normalizeWorkspaceId`).

### Root workspace

* `/{wsId}/projects` (reached as `/internal/projects`): internal site-template
  registry, workspace-indexed connection list, and connection audit history.
  The internal workspace is not a bindable content workspace, so its overview,
  content, and `/settings` routes redirect into `/{wsId}/projects`.

### Bound workspaces

* `/{wsId}`: overview / continue-editing home.
* `/{wsId}/content`: primary content operations surface (search, status
  filtering, publishing, reusable content).
* `/{wsId}/content/collections/{collectionId}`: collection (section) detail.
* `/{wsId}/content/entries/{entryId}`: entry (content) detail.
* `/{wsId}/pages`: page-builder surface for landing-style sections.
* `/{wsId}/media`: media library.
* `/{wsId}/products`: product catalog content.
* `/{wsId}/storefront`: storefront configuration.
* `/{wsId}/taxonomy`: taxonomy (terms, categories, tags).
* `/{wsId}/games`: game content surface, shown only when CMS Games is enabled
  for the workspace (`getCmsGamesEnabled`).
* `/{wsId}/preview`: site preview.
* `/{wsId}/members`: workspace member search, invite, removal, role assignment,
  and role/default-permission management.
* `/{wsId}/settings`: redirect-only route. It sends the internal workspace to
  `/{wsId}/projects` and every other workspace to `/{wsId}/members`; CMS has no
  standalone settings screen.

## Root Linking Console

* Treat `/{wsId}/projects` (the root workspace's `/internal/projects`) as a workspace-first control room.
* The main left panel is the searchable workspace list.
* Each row shows the current connection state, site type, site template, and most recent change signal.
* The selected workspace panel owns connect and disconnect actions.
* The site-template registry is secondary and stays on the same page for create/edit flows.
* Binding audits stay anchored to the selected workspace instead of living as a detached global feed.

## Workspace CMS

* Use `/{wsId}` as the concise starting point for continue-editing tasks, launch readiness, attention queues, recent activity, and connected-site context.
* Use `/{wsId}/content` for broader content operations: search, status filtering, publishing queues, collection health, and reusable content.
* Use `/{wsId}/pages` for focused landing-style page edits, page readiness, and preview-first section work.
* Use `/{wsId}/media`, `/{wsId}/products`, `/{wsId}/storefront`, and `/{wsId}/taxonomy` for the corresponding media, catalog, storefront, and taxonomy surfaces.
* Use `/{wsId}/games` for game content when CMS Games is enabled for the workspace.
* Use `/{wsId}/members` for routine collaborator management without leaving CMS.
* Keep collection configuration on `/{wsId}/content/collections/{collectionId}` and entry authoring on `/{wsId}/content/entries/{entryId}`.
* Use `/{wsId}/preview` as the delivered-content surface backed by the existing preview delivery route.
* CMS has no standalone settings screen; `/{wsId}/settings` is a redirect-only route to `/{wsId}/members` (or `/{wsId}/projects` on the internal workspace).

## Member Management In CMS

* Workspace member search, invite, remove, and role-assignment controls now have a dedicated `/{wsId}/members` sidebar route.
* The members surface also absorbs the essentials of the workspace roles page so CMS operators can manage named roles and default permissions without leaving CMS.
* This keeps standalone CMS usable without forcing operators back into the main platform app for routine collaborator changes.
* CMS members data must load through external-project-aware `apps/web` API routes and `@tuturuuu/internal-api` helpers. Reads should authorize by CMS workspace access so app-session users do not hit workspace settings-route 403s; writes still respect member and role management permissions.
* Use CMS copy in this area: team access, people, invites, access levels, member defaults, guest defaults, and Advanced access.

## Implementation Notes

* Keep CMS as a pure satellite frontend. Do not move API ownership into `apps/cms`.
* Continue adding or extending client helpers in `packages/internal-api` for CMS-facing API calls.
* Keep preview sourced from the existing delivery route instead of introducing a second preview payload contract.
* Backend/database naming remains `external-project*`; the product surface is what changed.
* Protect CMS-owned product copy with the CMS copy hygiene test, and add
  explicit admin/developer-detail exceptions only when a staff workflow truly
  needs an implementation value.
* Translation validation now treats `null` leaves as invalid so missing shared keys fail checks instead of silently passing parity.
* External app admin dashboards should call `POST /api/v1/workspaces/{wsId}/external-projects/setup` with their sync manifest before diff/apply. The route uses the existing app-coordination token and requires manage access. If the workspace is already bound to an active canonical project for the same adapter, setup preserves that binding while refreshing the project schema and field definitions; otherwise it creates the canonical `{adapter}-main` project if needed and binds the configured workspace without requiring production Supabase keys in the external app.
* External apps can mark manifest assets with `metadata.publicPath`, `metadata.localAssetPath`, or a relative `sourceUrl` such as `/media/hero.png`.
* Before diff/apply, run the public-folder linker so the manifest stores deterministic Drive paths under `external-projects/{adapter}/{collectionSlug}/{entrySlug}/{filename}`.
* Diff/apply routes are workspace-scoped. They may persist manifest schema into the bound workspace's collections and field definitions, but they must not update `canonical_external_projects` or other root/canonical registry state.
* Before apply, upload those files through the external-project asset app-server upload route. Abort the apply if a local public asset is missing so CMS never receives storage paths for objects that were not uploaded.
* Asset `storagePath`/`storage_path` values must stay under `external-projects/`. Do not point CMS assets at Drive, finance, or other workspace storage namespaces; delivery and admin cleanup only operate on assets that satisfy the CMS namespace invariant.

## Team Guidance

* Link into the CMS-native route map directly.
* Prefer the root `/internal/projects` console (the root workspace's `/{wsId}/projects`) for site-template and workspace-link operations.
* Keep bound-workspace collaborator management on the dedicated `/{wsId}/members` route, and do not surface the root projects console inside non-root workspace sidebars.
* Update both `apps/cms/messages/en.json` and `apps/cms/messages/vi.json`, then run `bun i18n:sort` whenever CMS copy changes.


# Meet calls
Source: https://docs.tuturuuu.com/platform/features/meet-calls

Run Tuturuuu Meet video calls on Cloudflare Realtime SFU, including room signaling, host controls, and in-call recording.

Tuturuuu Meet calls are Google-Meet-style conferences carried by the
**Cloudflare Realtime SFU**. This is a different product from Cloudflare Stream
Live, which powers one-to-many broadcast and is documented separately.

Every participant holds exactly **two peer connections** to the SFU — one
publishing, one subscribing — regardless of room size. Calls are not mesh, so
cost and CPU stay flat as a room grows.

## Pieces

| piece                                            | where                                 |
| ------------------------------------------------ | ------------------------------------- |
| Protocol, permissions, pure room reducer         | `packages/realtime/src/meet/`         |
| Room server (Bun + Docker, port 7816)            | `apps/meet-realtime/src/server.ts`    |
| Room server (Cloudflare Worker + Durable Object) | `apps/meet-realtime/src/worker.ts`    |
| Cloudflare SFU HTTPS client                      | `packages/realtime/src/meet/sfu.ts`   |
| Call client and UI                               | `apps/meet/src/features/call/`        |
| Call route (full-bleed, no sidebar)              | `apps/meet/src/app/[locale]/r/[code]` |

`room.ts` is a pure reducer: it returns the next room snapshot plus the messages
to fan out and any Cloudflare work to perform. Both transports run the same
reducer, so the Bun server and the Durable Object cannot drift.

The app secret never reaches a browser. The client receives only a short-lived
HMAC join token; the room server performs every SFU call on its behalf.

## Running a call locally

Create an SFU app under **Cloudflare dashboard → Realtime → SFU** and put the
values in `apps/meet-realtime/.dev.vars` (gitignored). See the
`apps/meet-realtime` README for variable names.

```bash theme={null}
bun apps/meet-realtime/src/verify-credentials.ts
```

Start the room server and the app, then open a meeting and press **Join call**:

```bash theme={null}
bun apps/meet-realtime/src/index.ts
```

Point the app at it with `NEXT_PUBLIC_MEET_REALTIME_URL`, which defaults to
`ws://127.0.0.1:7816/realtime`.

## Verifying without a full environment

Two checks run against real Cloudflare without needing Supabase, auth or seed
data.

**Signaling and host controls** — boots the room server, connects a host and a
guest, and exercises the lobby, chat, hand raise, force mute and removal:

```bash theme={null}
bun apps/meet-realtime/src/integration-check.ts
```

**Media** — bundles the real client modules, opens two browser peers and proves
audio and video traverse the SFU. Tracks are synthesised from a canvas and an
oscillator, so no camera or microphone permission is needed:

```bash theme={null}
bun apps/meet-realtime/src/media-check.ts
```

Then open `http://127.0.0.1:7898/?peer=a` and `?peer=b`. Each tab reports
`bytesReceived` and `framesDecoded`, and renders the other peer's video.

## Two contract details worth remembering

Both of these were found only by running against the live API, and both produce
confusing errors if reintroduced:

* **Read `transceiver.mid` only after `setLocalDescription()`.** It is `null`
  before that, and publishing without it fails with
  `406 tracks[0]: Missing mid in track`.
* **Do not send a `sessionDescription` when pulling remote tracks.** Cloudflare
  returns the offer, which the client answers via `sfu.renegotiate`. Sending an
  empty SDP is rejected as a malformed event.

Creating a session with no local offer must also send **no request body** at
all; `{}` and `{autoDiscover: true}` are both rejected.

## Attributing remote tracks

An inbound track arrives with an opaque id, so nothing on the
`RTCPeerConnection` says who published it. Attribution comes from the track
name, which is deliberately `<userId>-<kind>`: the subscribe response returns a
`mid` per track, the client maps `mid → userId`, and the `track` event is
matched against that map.

This is load-bearing. Keying inbound streams by the browser's track id instead
means the UI cannot tell participants apart, and every tile ends up rendering
whichever stream arrived first.

One `MediaStream` is accumulated per participant, since their audio and video
arrive as separate tracks but belong to one tile. The map and the streams are
both cleared on reconnect, because mids are only meaningful within a session.

## Reconnection

Signaling drops are expected: servers restart, networks blip, laptops sleep. The
client reconnects with exponential backoff and full jitter, so a room server
restart does not produce a synchronised retry stampede from every participant.

Two details make it actually work:

* **Each attempt fetches a fresh join token** from web's
  `POST /api/v1/workspaces/<wsId>/meetings/<meetingId>/realtime-token`, which
  the satellite proxies. Join
  tokens are short-lived and calls are not, so reusing the original token would
  let a client reconnect for ten minutes and then fail forever on
  "Reconnecting…". Membership is re-checked on every refresh.
* **A reconnect rebuilds room state.** The client re-announces itself with
  `presence.join` and clears its subscription ledger and peer connections, so
  every remote track is pulled again. Without that it would rejoin a room it
  could not see.

A clean close (`1000`) and a host removal (`4403`) are decisions, not blips, and
are never retried.

Media survives a signaling drop: the peer connections to the SFU are
independent, so audio and video keep flowing while signaling is down.

```bash theme={null}
bun apps/meet-realtime/src/reconnect-check.ts
```

That check stops the room server mid-session and asserts the client recovers,
mints a new token for the retry, and stays closed when the close was intentional.

## Meeting codes

Every meeting has a shareable code and a `/r/<code>` link, surfaced by the **Copy invite** button in the call header.

The code is a reversible Crockford base32 encoding of the meeting id rather
than a stored random string, so there is no schema change, no collision risk
and no lookup table — an invalid code is rejected before any query runs.
Decoding tolerates case, spaces, dashes, and the `I`/`L`/`O`/`U` characters
Crockford omits, folding them onto the digits the sender meant.

A code is a convenience for sharing **inside a workspace**, not a bypass:
`/r/<code>` still resolves workspace membership and redirects non-members
away.

**Every participant must be signed in.** There are no anonymous guest links and
none are planned, so a code always resolves against a real Tuturuuu user and a
workspace membership. The lobby (`admission: 'lobby'`) stays in the protocol for
future use, but today every workspace member joins with `admission: 'open'`.

## Recording

A host can record from inside the call. The control creates a row in
`recording_sessions` through the existing `/record` endpoint, captures local
audio with `MediaRecorder`, uploads through the existing `/upload` endpoint, and
broadcasts `recording.state` so every participant sees the indicator.

Because it reuses those endpoints, a call recording is indistinguishable from
one started on the meeting page and feeds the same transcription pipeline.

## Why the Next app stays on Vercel

Only the **realtime server** runs on Cloudflare Workers. `apps/meet` itself
stays on Vercel, deliberately.

Media never traverses the Next app: the browser talks to the Cloudflare SFU
directly, and signaling goes to the room server. Moving the Next app to Workers
would therefore not shorten the media path by a single hop.

It is also not currently possible. `@opennextjs/cloudflare` requires Next
`>=16.2.11`, and the monorepo is on the `16.3.0-preview` line, which npm semver
ranges exclude. Pinning `apps/meet` alone to 16.2.12 was tried and rejected:
16.2's `cacheComponents` is stricter than the preview, and both Tuturuuu Meet
routes fail to prerender with `Uncached data was accessed outside of <Suspense>`. Fixing that means changing `@tuturuuu/ui/legacy/meet/*`, which
other apps share.

Revisit when the monorepo moves to a stable Next 16 line.

## Deploying the Worker

```bash theme={null}
bun wrangler deploy -c apps/meet-realtime/wrangler.jsonc
```

One Durable Object per room gives each room a single authority. The Bun server
keeps rooms in an in-process map, which is only correct for a single replica —
prefer the Worker when running more than one instance.

## URL shapes

Meet matches the other satellites: workspace routes sit directly under the
workspace segment, with no `/workspace` prefix.

| surface                     | URL                                 |
| --------------------------- | ----------------------------------- |
| Workspace plans, meetings   | `/<wsId>/plans`, `/<wsId>/meetings` |
| A call                      | `/r/<code>`                         |
| A public Tuturuuu Meet plan | `/plans/<planId>`                   |

`plans` and `r` are static segments, which is what frees the bare `/<wsId>`
position — public plan pages previously occupied it, so `/<wsId>` and
`/<planId>` could not coexist.

Every retired shape is permanently redirected in `proxy.ts`:
`/workspace/*` → `/*`, `/call/<wsId>/<meetingId>` and `/join/<code>` → `/r/<code>`,
and a bare 32-hex segment → `/plans/<planId>`, so shared plan links keep working.


# Tuturuuu Meet
Source: https://docs.tuturuuu.com/platform/features/meet-together

Tuturuuu Meet helps you find and finalize the best time to meet with everyone.

<img />

<img />

## Usage

To use [Tuturuuu Meet](https://tuturuuu.com/meet), create a plan and invite participants with its canonical sharing link.

This will require you to select the `dates` and `times` that you are available to meet, and optionally change the plan `original timezone` as needed.

<Info>
  Once you have done this, a link will be **automatically generated** for you so
  that you can share with your friends and/or colleagues.
</Info>

They will be able to see the plan and select the dates and times that they are available to meet. Once everyone has selected their availability, you will be able to see the best time to meet with everyone.

## Saved Plans

You can also save your plans by logging in with a [Tuturuuu Account](https://tuturuuu.com/login). This will allow you to access the plan at a later time without having to manage links. Plans that you have filled out will also be automatically saved under your account.

Workspace Meet plans are scoped to their owning workspace. A public workspace
plan link is shareable with workspace members, but it is not globally readable
by ID. Anonymous access is only valid for public plans that are not attached to
a workspace.

## Plan Management

Everyone who has access to the plan will be able to see the plan details and the availability of everyone. Additionally, they will be able to change the plan name and delete the plan.

<Warning>
  Only send the link to people you trust, as they will have access to the plan
  details and the availability of everyone.
</Warning>

<Tip>
  Plans are not automatically deleted, so make sure to delete them once you are
  done with them.
</Tip>

## Limitations

<Warning>
  Timezone support is currently partiallly supported, it's not recommended for
  usage across different timezones yet.
</Warning>

<Warning>
  Mobile support is experimental, so it's recommended to use a desktop browser
  for the best experience.
</Warning>


# Mobile Drive, CRM, And Education
Source: https://docs.tuturuuu.com/platform/features/mobile-workspace-tools

What the mobile app supports for workspace Drive, CRM, Education, and the Apps hub shell.

## Overview

The mobile app now ships first-party workspace surfaces for:

* Drive at `Routes.drive`
* CRM at `Routes.crm`
* Education at `Routes.education`

Both modules are registered in the Apps hub and available through the mini-app navigation system.

The mobile Apps hub now uses a single-column list of equal-priority app cards instead of the older grid treatment. Keep module ordering explicit in the hub view rather than relying on registry insertion order. For workspace modules that need dense controls, prefer the same shell-owned chrome used by Calendar:

* `ShellMiniNav` for mode or section switching
* `ShellChromeActions` for quick actions such as filters, create, sort, and view toggles
* A finance-style overview hero card inside the page body for stats and search
* Compact panel sections in the page body instead of raw admin `Card/ListTile` stacks, so module pages read like first-class mobile products rather than direct dashboard ports

Background warmups for optional products should also respect access state before fetching. Do not let Apps hub or boot-time cache warmups call product endpoints blindly; skip the warmup when the corresponding access cubit is not loaded and enabled, and fail soft on opportunistic `404` responses.

## Mobile App Lock And Web QR Approval

The mobile app supports a device-level app lock from Settings > Session. The
setting is stored in secure storage and uses the OS local authentication prompt
with device PIN/passcode fallback allowed. When enabled, the app locks on an
authenticated cold launch and after at least 30 seconds in the background.

QR session handoff approval is gated by this setting:

* The scanner lives at `Routes.settingsQrLoginScan`.
* The scanner only accepts `tuturuuu://auth/qr-login` payloads from trusted
  Tuturuuu or local development origins.
* The QR challenge must have been created by the same account that is active in
  the mobile app. Public unauthenticated QR sign-in is not supported because it
  would let an attacker poll a victim-approved challenge.
* Before approval, mobile runs local authentication and then calls
  `/api/v1/auth/qr-login/challenges/:id/approve` with the current Bearer
  session.

If a user wants to approve QR session handoff for a different account, both the
creator session and the mobile app must be using that account before scanning.

The mobile app can approve web MFA challenges when the active mobile Supabase
session is already at `aal2`:

* The web MFA screen creates an `/api/v1/auth/mfa/mobile/challenges` request and
  shows a pair code.
* `MobileMfaApprovalListener` is mounted at the app shell and polls
  `/api/v1/auth/mfa/mobile/approvals` while the user is authenticated, the app is
  in the foreground, and app lock is not covering the UI.
* Pending pair codes open an app-level approval dialog. The Settings > Session
  tile remains a manual fallback surface for the same pending approvals.
* Mobile approves through
  `/api/v1/auth/mfa/mobile/challenges/:id/approve`.
* The web poller consumes the approved challenge and sets an HTTP-only
  `ttr_mfa_mobile_approval` cookie. The central auth proxy accepts that cookie
  only for the same user, the hidden web challenge secret, and an unexpired
  consumed `mfa_mobile_approval` challenge.
* After a mobile TOTP challenge succeeds, `AuthCubit.verifyMfa` must sync the
  refreshed `aal2` Supabase session into the active multi-account store. Without
  that sync, later mobile API calls can restore/send an older `aal1` token and
  the approvals endpoint will respond with `requiresMobileMfa`.
* Multi-account removal and all-account logout must treat Supabase
  `auth.signOut()` as required before clearing the local account store or
  emitting an unauthenticated Cubit state. Google/provider logout and stored
  refresh-token revocation can be best-effort, but a failed Supabase logout must
  leave the account visible with an error so the persisted session cannot
  silently reappear later.
* Auth account models may serialize refresh tokens and session JSON only for the
  encrypted secure-storage store. Do not include those raw secrets in
  `Equatable.props`, `toString`, or other Cubit/Bloc state debug output because
  the global Bloc observer logs state changes during development.

## Mobile Drive Coverage

The Drive screen in `apps/mobile` supports the main dashboard Drive flow:

* Workspace permission-gated loading
* Storage analytics summary
* Folder navigation and breadcrumb-style path movement
* Search, sort, grid/list toggle, and pagination
* Folder creation, rename, delete, bulk delete, and upload
* File preview, external open, share, and path copy
* Folder export-link generation and sharing

The mobile implementation talks to the same authenticated workspace storage routes used by the web product:

* `/api/v1/workspaces/:wsId/storage/list`
* `/api/v1/workspaces/:wsId/storage/analytics`
* `/api/v1/workspaces/:wsId/storage/folders`
* `/api/v1/workspaces/:wsId/storage/rename`
* `/api/v1/workspaces/:wsId/storage/object`
* `/api/v1/workspaces/:wsId/storage/share`
* `/api/v1/workspaces/:wsId/storage/export-links`
* `/api/v1/workspaces/:wsId/storage/upload-url`
* `/api/v1/workspaces/:wsId/storage/finalize-upload`

## Mobile CRM Coverage

The CRM screen in `apps/mobile` supports:

* Workspace permission-gated users and audit tabs
* Search, filters, pagination, and audit range filters
* Create, edit, and delete user records
* Avatar upload during create/edit flows
* Feedback create/update/delete flows
* Duplicate detection and merge flows
* CSV import with preview and deduping by email
* CSV export of the currently filtered users dataset

The mobile CRM uses the existing authenticated routes:

* `/api/v1/workspaces/:wsId/users/database`
* `/api/v1/workspaces/:wsId/users`
* `/api/v1/workspaces/:wsId/users/:userId`
* `/api/v1/workspaces/:wsId/users/groups`
* `/api/v1/workspaces/:wsId/users/feedbacks`
* `/api/v1/workspaces/:wsId/users/audit-logs`
* `/api/v1/workspaces/:wsId/users/duplicates/detect`
* `/api/v1/workspaces/:wsId/users/merge`
* `/api/v1/workspaces/:wsId/users/bulk-import`
* `/api/v1/workspaces/:wsId/users/avatar`

For CRM list and duplicate/merge routes, keep workspace resolution request-aware on the web side. Mobile calls authenticate with Bearer tokens rather than dashboard cookies, so routes that resolve the workspace with cookie-only helpers can fail as `Workspace not found` even for valid workspace members.

## Mobile Education Coverage

The Education screen in `apps/mobile` supports:

* An overview dashboard with counts for courses, quizzes, quiz sets, flashcards, and attempts
* Course search, create, edit, delete, and paginated browsing
* Library management for quizzes, quiz sets, and flashcards
* Quiz authoring with answer options, correctness flags, and explanations
* Attempt browsing with status and quiz-set filters plus attempt-detail review

The mobile Education module uses authenticated workspace routes from `apps/web`:

* `/api/v1/workspaces/:wsId/courses`
* `/api/v1/workspaces/:wsId/courses/:courseId`
* `/api/v1/workspaces/:wsId/quizzes`
* `/api/v1/workspaces/:wsId/quizzes/:quizId`
* `/api/v1/workspaces/:wsId/quiz-sets`
* `/api/v1/workspaces/:wsId/quiz-sets/:setId`
* `/api/v1/workspaces/:wsId/flashcards`
* `/api/v1/workspaces/:wsId/flashcards/:flashcardId`
* `/api/v1/workspaces/:wsId/education/attempts`
* `/api/v1/workspaces/:wsId/education/attempts/:attemptId`

For mobile-facing collection APIs, keep list routes request-aware and list-shaped. A cookie-only helper or `.single()` response on a collection endpoint can work in the web dashboard but break mobile Bearer-token callers or pagination assumptions.

The mobile endpoint registry is guarded by `bun check:mobile-api-mappings`.
The check extracts Flutter `/api/*` templates from `api_config.dart` and the
production endpoint catalog used by the `ttr` CLI SDK. It verifies that both
legacy clients still resolve to a canonical owner in a checked-in Next
satellite, the legacy route wrappers, or the Rust/TanStack migration manifest.
The `Mobile API Mappings` workflow runs whenever either client catalog, an app
API route, or the migration manifest changes. If a route is migrated or
removed, update Flutter and the CLI SDK in the same change instead of leaving a
legacy client to discover the break in production.

## Mobile Inventory And Storefront Coverage

Inventory is a native mobile workspace with overview, product CRUD, checkout,
sales, setup, audit-log access, and storefront management. Storefronts support
create/edit/delete, status and visibility controls, public preview, product
listing CRUD, stock-row selection, pricing, and per-order limits through the
same authenticated inventory satellite APIs:

Mobile sales also support workspace sales periods. Operators can create a
season or event such as `Summer 2026` or `TuCon 2026`, filter the mixed
invoice/checkout history by that period, and assign the period during sale
creation or editing. Archiving preserves historical reporting.

* `/api/v1/workspaces/:wsId/inventory/storefronts`
* `/api/v1/workspaces/:wsId/inventory/storefronts/:storefrontId`
* `/api/v1/workspaces/:wsId/inventory/storefronts/:storefrontId/listings`
* `/api/v1/workspaces/:wsId/inventory/storefronts/:storefrontId/listings/:listingId`

Keep Storefront in the five-item Inventory mini navigation. Audit logs remain
discoverable from Inventory Manage so compact phones retain a stable native
navigation bar.

When an Education mobile list needs derived counts from workspace-protected join tables such as `course_module_quiz_sets`, verify workspace membership first with the request-scoped client, then run the joined read on an admin-backed client. Also select real join columns such as `module_id`; do not assume those bridge tables expose a synthetic `id`.

## Import And Export Format Notes

* The web CRM page still has richer spreadsheet tooling, including XLSX-oriented flows.
* Mobile import and export currently use CSV plus native share sheets.
* Keep the server contract for bulk import as a raw JSON array of `{ email, fullName }` rows.

This format choice is intentional for now: the current Flutter dependency graph in `apps/mobile` does not accept a stable XLSX package cleanly without conflicts, so mobile should prefer CSV/share flows unless spreadsheet generation is moved server-side later.

## Verification

For Drive, CRM, or Education mobile changes:

1. Update `apps/mobile/lib/l10n/arb/*.arb` for every new user-facing string.
2. Run `flutter gen-l10n`.
3. Run `bun check:mobile`.


# Progress, Goals & Leaderboards
Source: https://docs.tuturuuu.com/platform/features/progress-goals-leaderboards

TrackBear-style progress tracking for tasks: flexible metrics, target/habit goals, activity heatmaps, leaderboards, and gamification.

## TL;DR

The Tasks app turns everyday work into a motivating, glanceable progress system. Progress is
derived **automatically** from completed tasks and focus sessions, and can also be **logged
manually** in any unit — including writing units like words, pages, and chapters. Goals, an
activity heatmap, leaderboards, and a full achievement/XP layer keep momentum visible.

## Metrics

Every workspace tracks a few automatic metrics (completed tasks, estimate points, focus time,
focus sessions). Teams that write can enable a one-click **Writing pack** that adds Words, Pages,
Chapters, Scenes, and Lines. Metrics support two aggregation styles — summed deltas or a running
total — so you can log either "+500 words today" or "project total is now 12,000".

## Logging progress

* **Automatic**: completing a task or finishing a focus session feeds the relevant metric with no
  manual step.
* **Quick log**: a persistent button (and a mobile floating action button) opens a dialog to record
  an amount for any metric, on any date, with a note and tags. Zero and negative values are allowed
  so a "showed up but wrote nothing" day is distinct from an untracked one, and corrections are easy.

## Goals

Two goal types, mirroring TrackBear:

* **Target** — accumulate toward a total by an optional end date. Shows a progress bar, the expected
  pace ("par"), a projected finish, and an on-track / needs-attention chip.
* **Habit** — write regularly at a chosen cadence (per day / week / month) with an optional
  per-period threshold. Shows a gauge that turns gold when the period is met, plus current, longest,
  and typical streak length and the percentage of periods hit.

## Visualizations

* **Activity heatmap** — a year-long contribution grid; darker cells mean more progress that day.
* **Cumulative chart** — accumulated progress over time, with an optional par line for dated targets.
* **Analytics dashboard** — KPI strip, daily bars, weekday distribution, tag breakdown, best day,
  consistency, and a momentum recommendation.

## Leaderboards

Anyone can create a leaderboard for a metric and period. Members **join by code**, appear on a
podium (top three) with a ranked overflow list, and can be organized into teams. Automatic weekly
leaderboards are synthesized from task activity so a workspace always has something live.

## Gamification

Logging progress unlocks **achievements** (streaks, volume, consistency, milestones, social) across
bronze → platinum tiers, awards **XP**, and raises your **level**. Streak freezes are earned as
streaks grow. Unlocks surface as celebratory toasts and in an achievements card on the Progress and
Analytics views.

## Under the hood

Progress data lives in the `task_progress_*` and `task_leaderboard*` tables, with the gamification
layer in `task_progress_achievements`, `task_progress_user_achievements`, and
`task_progress_user_stats`. XP and achievement evaluation is deterministic and idempotent — it is
recomputed from current activity on every progress write, so it never drifts or double-counts.


# API Reference
Source: https://docs.tuturuuu.com/platform/features/smart-scheduling/api-reference

REST API endpoints for Smart Scheduling

# Smart Scheduling API

The Smart Scheduling API allows you to programmatically trigger scheduling and retrieve scheduling status.

## Endpoints

### Trigger Scheduling

<Endpoint method="POST" />

Triggers the unified scheduler for a workspace, scheduling both habits and tasks.

#### Path Parameters

<ParamField type="string">
  The workspace ID (UUID format)
</ParamField>

#### Request Body

<ParamField type="number">
  How many days into the future to schedule events (7-90)
</ParamField>

<ParamField type="boolean">
  If true, deletes existing auto-generated events and creates new ones
</ParamField>

#### Response

```json theme={null}
{
  "success": true,
  "summary": {
    "habitsScheduled": 5,
    "tasksScheduled": 3,
    "eventsCreated": 12,
    "bumpedHabits": 1,
    "rescheduledHabits": 1,
    "windowDays": 30
  },
  "habits": {
    "events": [
      {
        "habitId": "uuid",
        "habitName": "Morning Meditation",
        "occurrence": "2024-01-15",
        "duration": 20,
        "event": {
          "id": "uuid",
          "start_at": "2024-01-15T07:00:00Z",
          "end_at": "2024-01-15T07:20:00Z"
        }
      }
    ],
    "warnings": []
  },
  "tasks": {
    "events": [
      {
        "taskId": "uuid",
        "taskName": "Complete report",
        "scheduledMinutes": 120,
        "warning": null,
        "events": [
          {
            "id": "uuid",
            "start_at": "2024-01-15T09:00:00Z",
            "end_at": "2024-01-15T11:00:00Z",
            "scheduled_minutes": 120
          }
        ]
      }
    ],
    "bumpedHabits": [
      {
        "habitId": "uuid",
        "habitName": "Reading",
        "occurrence": "2024-01-15",
        "originalEventId": "uuid"
      }
    ],
    "warnings": []
  },
  "rescheduledHabits": [
    {
      "habitId": "uuid",
      "habitName": "Reading",
      "occurrence": "2024-01-15",
      "duration": 30,
      "event": {
        "id": "uuid",
        "start_at": "2024-01-15T19:00:00Z",
        "end_at": "2024-01-15T19:30:00Z"
      }
    }
  ],
  "warnings": []
}
```

#### Example

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://tuturuuu.com/api/v1/workspaces/{wsId}/calendar/schedule" \
    -H "Content-Type: application/json" \
    -H "Cookie: your-session-cookie" \
    -d '{"windowDays": 30, "forceReschedule": false}'
  ```

  ```typescript TypeScript theme={null}
  const response = await fetch(
    `/api/v1/workspaces/${wsId}/calendar/schedule`,
    {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ windowDays: 30, forceReschedule: false }),
    }
  );

  const result = await response.json();
  console.log(`Created ${result.summary.eventsCreated} events`);
  ```
</CodeGroup>

***

### Get Scheduling Status

<Endpoint method="GET" />

Retrieves the current scheduling status and statistics for a workspace.

#### Path Parameters

<ParamField type="string">
  The workspace ID (UUID format)
</ParamField>

#### Response

```json theme={null}
{
  "lastScheduledAt": "2024-01-15T10:30:00Z",
  "lastStatus": "success",
  "lastMessage": "Scheduled 5 habits and 3 tasks",
  "statistics": {
    "habitsScheduled": 5,
    "tasksScheduled": 3,
    "eventsCreated": 12,
    "bumpedHabits": 1,
    "windowDays": 30
  },
  "schedulableItems": {
    "activeHabits": 7,
    "autoScheduleTasks": 4
  }
}
```

#### Example

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://tuturuuu.com/api/v1/workspaces/{wsId}/calendar/schedule" \
    -H "Cookie: your-session-cookie"
  ```

  ```typescript TypeScript theme={null}
  const response = await fetch(
    `/api/v1/workspaces/${wsId}/calendar/schedule`
  );

  const status = await response.json();
  console.log(`Last scheduled: ${status.lastScheduledAt}`);
  ```
</CodeGroup>

***

## Authentication

### User Authentication

Standard user authentication via session cookie. The user must be a member of the workspace.

### Cron Authentication

For background jobs, the API accepts a Bearer token with the cron secret:

```http theme={null}
Authorization: Bearer {CRON_SECRET}
```

This is used by the Vercel cron job that runs scheduling every 6 hours.

The cron secret is read from `process.env.CRON_SECRET ?? process.env.VERCEL_CRON_SECRET`.

## Error Responses

| Status | Description                                                           |
| ------ | --------------------------------------------------------------------- |
| 400    | Invalid workspace ID                                                  |
| 401    | Not authenticated                                                     |
| 403    | Not a workspace member                                                |
| 409    | Safe apply blocked because the schedule still has unresolved warnings |
| 422    | Workspace timezone is not set, or is set to `auto`                    |
| 500    | Internal server error                                                 |

## Rate Limiting

The scheduling endpoint is rate-limited to prevent abuse:

* **Manual triggers**: Limited by standard API rate limits
* **Cron triggers**: A single global cron runs every 6 hours and fans out to eligible workspaces (not per-workspace at the cron level)

## Cron Job

Smart Scheduling runs automatically every 6 hours via Vercel Cron:

```json theme={null}
{
  "path": "/api/cron/calendar/smart-schedule",
  "schedule": "0 */6 * * *"
}
```

The cron job:

1. Finds all workspaces with auto-schedule enabled habits or tasks
2. Calls the scheduling API for each workspace
3. Logs results and any errors

<Info>
  The cron job uses `forceReschedule: false` to avoid disrupting existing schedules. Only new items are scheduled.
</Info>


# Duration Optimization
Source: https://docs.tuturuuu.com/platform/features/smart-scheduling/duration-optimization

How Smart Scheduling optimizes habit duration based on time slot characteristics

# Duration Optimization

Duration optimization is a key feature that makes habit scheduling intelligent. Instead of always using a fixed duration, the system adapts based on the available time slot and your preferences.

## Flexible Duration Bounds

Each habit can have three duration settings:

| Setting       | Description                       | Default                         |
| ------------- | --------------------------------- | ------------------------------- |
| **Preferred** | The ideal duration for this habit | Required                        |
| **Minimum**   | Shortest acceptable duration      | 50% of preferred (min 15 min)   |
| **Maximum**   | Longest beneficial duration       | 150% of preferred (max 180 min) |

<Info>
  If you only set the preferred duration, the system calculates sensible defaults for min and max.
</Info>

## Optimization Strategy

The duration optimizer chooses the optimal duration based on slot characteristics:

### 1. Ideal Time Match

When the slot contains your specified `ideal_time` (e.g., "07:00"):

```
Duration = Maximum
```

The system maximizes duration because you're getting your most valuable time slot. This is when you'll get the most benefit from the habit.

### 2. Time Preference Match

When the slot falls within your preferred time-of-day:

| Preference | Time Range         |
| ---------- | ------------------ |
| Morning    | 6:00 AM - 12:00 PM |
| Afternoon  | 12:00 PM - 5:00 PM |
| Evening    | 5:00 PM - 9:00 PM  |
| Night      | 9:00 PM - 12:00 AM |

```
Duration = Preferred
```

The system uses your standard preferred duration since this is still a good time for the habit.

### 3. Constrained Slot

When the available slot is smaller than your preferred duration:

```
Duration = max(Minimum, Available)
```

The system shrinks to fit while ensuring you still get value from the habit.

### 4. No Special Conditions

When no preferences match:

```
Duration = Preferred
```

Falls back to your standard preferred duration.

## Slot Scoring

When multiple time slots are available, the system scores each one to find the best:

```typescript theme={null}
function scoreSlotForHabit(habit, slot, timezone?, weights?): number {
  const characteristics = getSlotCharacteristics(habit, slot, timezone);
  let score = 0;

  // Ideal time match is best (default +1000, overridable via weights)
  if (characteristics.matchesIdealTime) {
    score += weights?.habitIdealTimeBonus ?? 1000;
  }

  // Time preference match is second best (default +500, overridable)
  if (characteristics.matchesPreference) {
    score += weights?.habitPreferenceBonus ?? 500;
  }

  // Prefer slots that fit preferred duration (+200), else minimum (+100)
  const { preferred, min } = getEffectiveDurationBounds(habit);
  if (slot.maxAvailable >= preferred) {
    score += 200;
  } else if (slot.maxAvailable >= min) {
    score += 100;
  }

  // Tiebreaker (timezone-aware hour):
  // - With a preference set, slightly prefer earlier slots
  // - With no preference, prefer slots closer to noon to spread habits out
  const slotHour = getLocalHour(slot.start, timezone);
  if (habit.time_preference || habit.ideal_time) {
    score -= slotHour * 0.1;
  } else {
    score -= Math.abs(slotHour - 12) * 0.5;
  }

  return score;
}
```

## Examples

### Morning Meditation

```
Habit: Morning Meditation
Preferred: 20 minutes
Minimum: 10 minutes
Maximum: 30 minutes
Ideal Time: 06:30
Preference: Morning
```

| Slot               | Duration   | Reason                            |
| ------------------ | ---------- | --------------------------------- |
| 6:00 AM - 7:00 AM  | **30 min** | Contains ideal time, maximize     |
| 8:00 AM - 9:00 AM  | 20 min     | Morning preference, use preferred |
| 12:00 PM - 1:00 PM | 20 min     | No match, use preferred           |
| 6:00 AM - 6:15 AM  | 15 min     | Constrained, use minimum          |

### Evening Workout

```
Habit: Evening Workout
Preferred: 60 minutes
Minimum: 30 minutes
Maximum: 90 minutes
Ideal Time: null
Preference: Evening
```

| Slot                | Duration   | Reason                            |
| ------------------- | ---------- | --------------------------------- |
| 5:00 PM - 7:00 PM   | **60 min** | Evening preference, use preferred |
| 8:00 PM - 9:00 PM   | 60 min     | Evening preference, use preferred |
| 5:00 PM - 5:45 PM   | 45 min     | Constrained, fit to slot          |
| 10:00 AM - 12:00 PM | 60 min     | No match, use preferred           |

## Implementation Details

The duration optimizer is implemented in `packages/ai/src/scheduling/duration-optimizer.ts`:

```typescript theme={null}
// Key exports (signatures simplified; optional params shown where they matter)
export function getEffectiveDurationBounds(habit): { preferred, min, max };
export function calculateOptimalDuration(habit, slot, characteristics): number;
export function timeMatchesSlot(idealTime: string, slot, timezone?): boolean;
export function slotMatchesPreference(preference: TimeOfDayPreference, slot, timezone?): boolean;
export function getSlotCharacteristics(habit, slot, timezone?): SlotCharacteristics;
export function scoreSlotForHabit(habit, slot, timezone?, weights?): number;
export function findBestSlotForHabit(habit, slots, timezone?, weights?): TimeSlotInfo | null;
```

<Info>
  Most matching and scoring functions accept an optional `timezone` so that
  `ideal_time` and time-of-day preferences are interpreted in the user's local
  time rather than the server's. `scoreSlotForHabit` and `findBestSlotForHabit`
  also accept optional `SchedulingWeights` to override the default ideal-time and
  preference bonuses.
</Info>

## Configuration in Habit Form

When creating or editing a habit, you can configure duration optimization:

<Steps>
  <Step title="Set Preferred Duration">
    The standard duration for this habit (required)
  </Step>

  <Step title="Enable Flexible Duration">
    Toggle to allow min/max bounds
  </Step>

  <Step title="Set Minimum Duration">
    Shortest acceptable duration (optional)
  </Step>

  <Step title="Set Maximum Duration">
    Longest beneficial duration (optional)
  </Step>

  <Step title="Set Ideal Time">
    Specific time of day (optional, format: HH:MM)
  </Step>

  <Step title="Set Time Preference">
    Morning, Afternoon, Evening, or Night (optional)
  </Step>
</Steps>

## Testing

The duration optimizer ships with an extensive unit-test suite (currently 127
cases) covering:

* Duration bounds calculation
* Time matching and preference detection (including timezone-aware extraction)
* Slot scoring and selection
* Integration scenarios for real-world habits

Run tests with:

```bash theme={null}
npx vitest run src/scheduling/duration-optimizer.test.ts
```


# Smart Scheduling Overview
Source: https://docs.tuturuuu.com/platform/features/smart-scheduling/overview

Intelligent, unified scheduling for habits and tasks with priority-aware event placement

# Smart Scheduling

Smart Scheduling is an intelligent system that automatically schedules your habits and tasks on your calendar, respecting priorities, deadlines, and your preferences.

## Key Features

<CardGroup>
  <Card title="Unified Scheduling" icon="calendar-check">
    Habits and tasks are scheduled together in a coordinated manner, ensuring they don't conflict
  </Card>

  <Card title="Priority-Aware" icon="arrow-up-1-9">
    Items are scheduled based on priority, with urgent tasks able to bump lower-priority habits
  </Card>

  <Card title="Deadline Intelligence" icon="clock">
    Automatically infers priority from deadlines - items due soon get scheduled first
  </Card>

  <Card title="Flexible Duration" icon="arrows-left-right">
    Habits can have min/max duration bounds, optimizing time based on slot availability
  </Card>
</CardGroup>

## How It Works

### 1. Priority Calculation

Every habit and task has an **effective priority** that determines scheduling order:

| Priority | Weight | Deadline Inference             |
| -------- | ------ | ------------------------------ |
| Critical | 4      | Overdue or due within 24 hours |
| High     | 3      | Due within 24-48 hours         |
| Normal   | 2      | Due beyond 48 hours            |
| Low      | 1      | No deadline set                |

<Note>
  Explicit priorities always take precedence over inferred priorities. If you manually set a task as "Critical", it stays critical regardless of deadline.
</Note>

### 2. Scheduling Order

Smart Scheduling processes items in this order:

1. **Habits First** - Sorted by priority, then by ideal time preference
2. **Tasks Second** - Sorted by priority, then by deadline proximity
3. **Bumping** - Urgent (critical) tasks can bump lower-priority habit events
4. **Rescheduling** - Bumped habits are rescheduled to the next available slot

### 3. Duration Optimization

For habits with flexible duration (min/max bounds), the system optimizes duration based on slot characteristics:

```
Ideal Time Match → Maximum duration (get most value from preferred time)
Preference Match → Preferred duration (morning/afternoon/evening/night)
Constrained Slot → Minimum viable duration (still complete the habit)
No Match → Preferred duration (default behavior)
```

## Using Smart Schedule

### From the Calendar

Click the **Smart Schedule** button in the calendar toolbar to run scheduling for your workspace:

<Steps>
  <Step title="Click Smart Schedule">
    Find the button in the calendar toolbar with the sparkle icon
  </Step>

  <Step title="Wait for Processing">
    The system analyzes your habits, tasks, and existing events
  </Step>

  <Step title="View Results">
    New calendar events appear automatically, with a toast notification showing the summary
  </Step>
</Steps>

### Automatic Scheduling

Smart Scheduling runs automatically every 6 hours via a background cron job (`/api/cron/calendar/smart-schedule`, scheduled `0 */6 * * *`). This keeps your calendar up to date as you add new habits and tasks. You can always trigger an on-demand run from the calendar toolbar in between cron cycles.

<Info>
  The cron job only schedules items with `auto_schedule` enabled. You can enable/disable auto-scheduling per habit or task.
</Info>

## Configuration Options

### Window Days

Controls how far into the future to schedule events (default: 30 days, clamped to a 7-90 day range).

### Force Reschedule

When enabled, existing scheduled events are deleted and recreated. Use this to completely refresh your schedule.

<Warning>
  Force reschedule will delete all auto-generated calendar events and create new ones. Manual events are not affected.
</Warning>

## Best Practices

<AccordionGroup>
  <Accordion title="Set Explicit Priorities for Important Items">
    While the system infers priority from deadlines, setting explicit priorities ensures your most important work is scheduled first.
  </Accordion>

  <Accordion title="Use Flexible Duration for Habits">
    Set min/max duration bounds instead of fixed durations. This allows the system to optimize scheduling - using more time in ideal slots and less in constrained ones.
  </Accordion>

  <Accordion title="Set Ideal Times for Habits">
    Specify your preferred time (e.g., "07:00" for morning meditation). The system will prioritize these slots and allocate maximum duration when they're available.
  </Accordion>

  <Accordion title="Keep Deadlines Updated">
    The system uses deadlines to infer priority. Keep your task deadlines accurate for optimal scheduling.
  </Accordion>
</AccordionGroup>

## API Reference

Smart Scheduling is available via the REST API:

```bash theme={null}
# Trigger scheduling for a workspace
POST /api/v1/workspaces/{wsId}/calendar/schedule
Content-Type: application/json

{
  "windowDays": 30,
  "forceReschedule": false
}
```

The `windowDays` value is clamped server-side to a minimum of 7 and a maximum of 90 days (default 30). See [API Reference](/platform/features/smart-scheduling/api-reference) for full details.


# Priority System
Source: https://docs.tuturuuu.com/platform/features/smart-scheduling/priority-system

How Smart Scheduling calculates and uses priority for scheduling decisions

# Priority System

The priority system is the foundation of Smart Scheduling. It determines which items get scheduled first and which items can bump others.

## Priority Levels

Smart Scheduling uses four priority levels:

| Level        | Weight | Description                                     |
| ------------ | ------ | ----------------------------------------------- |
| **Critical** | 4      | Must be done immediately, can bump other events |
| **High**     | 3      | Important, scheduled before normal items        |
| **Normal**   | 2      | Standard priority, default for most items       |
| **Low**      | 1      | Can be deferred, scheduled when convenient      |

## Priority Inference

When an item doesn't have an explicit priority set, the system infers it from the deadline:

```typescript theme={null}
function inferPriority(deadline: Date | null): Priority {
  if (!deadline) return 'low';

  const hoursUntilDeadline = (deadline - now) / (1000 * 60 * 60);

  if (hoursUntilDeadline <= 0) return 'critical';  // Overdue
  if (hoursUntilDeadline <= 24) return 'critical'; // Due today
  if (hoursUntilDeadline <= 48) return 'high';     // Due tomorrow
  return 'normal';                                  // Due later
}
```

<Note>
  Explicit priorities always override inferred priorities. If you set a task as "Low" priority, it stays low even if it's overdue.
</Note>

## Priority Score Calculation

For more granular sorting, the system calculates a numeric priority score:

```typescript theme={null}
// Base score from priority level
const baseScores = {
  critical: 4000,
  high: 3000,
  normal: 2000,
  low: 1000
};

// Urgency bonus from deadline proximity (added to the base score)
function getUrgencyBonus(deadline: Date | null): number {
  if (!deadline) return 0;

  const hoursUntil = (deadline - now) / (1000 * 60 * 60);

  if (hoursUntil < 0) return 5000;    // Overdue - highest urgency
  if (hoursUntil < 24) return 2000;   // Due within 24h
  if (hoursUntil < 48) return 1000;   // Due within 48h
  if (hoursUntil < 72) return 500;    // Due within 3 days
  if (hoursUntil < 168) return 200;   // Due within 7 days
  return 0;                            // Due later
}
```

This scoring system ensures that:

* Overdue items are scheduled first (score up to 9000)
* Items due soon are prioritized even within the same priority level
* Low priority items with urgent deadlines can outrank high priority items due later

## Sorting Algorithm

Items are sorted using a multi-level comparison:

<Steps>
  <Step title="Primary: Priority">
    Higher priority items come first (critical > high > normal > low)
  </Step>

  <Step title="Secondary: Deadline">
    Among same priority, earlier deadlines come first
  </Step>

  <Step title="Tertiary: Creation Date">
    Among same priority and deadline, older items come first (FIFO)
  </Step>
</Steps>

## Bumping Rules

Only **critical priority** items can bump other events:

| Bumper Priority | Can Bump          |
| --------------- | ----------------- |
| Critical        | High, Normal, Low |
| High            | Nothing           |
| Normal          | Nothing           |
| Low             | Nothing           |

<Warning>
  Critical items cannot bump other critical items. This prevents infinite bumping loops and ensures all critical work gets done.
</Warning>

### Bumping Process

When a critical task needs a time slot occupied by a lower-priority habit:

1. The habit event is marked for rescheduling
2. The task is scheduled in the freed slot
3. The bumped habit is rescheduled to the next available slot
4. If no suitable slot exists, a warning is generated

## Implementation Details

The priority calculator is implemented in `packages/ai/src/scheduling/priority-calculator.ts`:

```typescript theme={null}
// Key exports
export const PRIORITY_WEIGHTS = {
  critical: 4,
  high: 3,
  normal: 2,
  low: 1,
};

export function getEffectivePriority(item: PrioritizableItem): Priority;
export function comparePriority(a: Priority, b: Priority): number;
export function isHigherPriority(a: Priority, b: Priority): boolean;
export function canBump(bumper: PrioritizableItem, target: PrioritizableItem): boolean;
export function sortByPriority<T extends PrioritizableItem>(items: T[]): T[];
export function calculatePriorityScore(item: PrioritizableItem): number;
```

## Testing

The priority system is thoroughly tested with a comprehensive suite (60 test cases as of this writing) covering:

* Priority weight ordering
* Explicit priority handling
* Deadline-based inference
* Priority comparison functions
* Bumping rules
* Multi-level sorting
* Score calculation with urgency bonuses

Run tests with:

```bash theme={null}
npx vitest run src/scheduling/priority-calculator.test.ts
```


# User Management
Source: https://docs.tuturuuu.com/platform/features/user-management

A central place to manage users, groups, and information about them.

## Post Email Delivery Recovery

The post email queue now treats provider-accepted delivery as durable once it is written to `email_audit`. The `sent_emails` table is still the primary history surface for the product UI, but queue retries must not resend a post email just because the follow-up `sent_emails` insert or `user_group_post_checks.email_id` link failed.

### Recovery Rules

* `email_audit` is created before a send and updated to `sent` immediately after provider success.
* Batch processing checks both `sent_emails` and matching `email_audit` entries for the same post-recipient pair before sending.
* If an audit record proves the email was already sent, the worker marks the queue row as `sent` and backfills `sent_emails` opportunistically instead of resending.
* If provider delivery succeeds but local `sent_emails` persistence fails, the queue row still transitions to `sent` with a warning in `last_error` so the system does not retry the message.

### Claiming Strategy

* The queue worker should only claim rows that it can start in the current processing slice.
* Avoid front-claiming the whole `sendLimit`; stranded `processing` rows interact badly with stale cleanup and can create duplicate delivery attempts after requeue.
* Rejected-recipient cleanup must remain a set-wise private RPC. Scanning every rejected check and updating recipient pairs one at a time can consume the cron's runtime before approved messages are claimed.

### Operations Dashboard

* The infrastructure Post Email Queue page shows approval/delivery backlog health, age buckets, throughput, sanitized failure categories, workspace breakdowns, and recent batch summaries.
* Operators should use the page's Run Now action instead of calling the cron endpoint from the browser. The app route keeps `CRON_SECRET` server-side and invokes `/api/cron/process-post-email-queue` with diagnostic output.
* The cron defaults are tuned for production backlogs: `limit=500` and `sendLimit=200`. Query parameters may still lower those values for focused recovery runs.
* When a recipient is approved but still shown as queued in the Posts dashboard, inspect the selected-recipient delivery diagnostics before assuming approval failed. Queue age over 1 hour is a warning; queue age over 24 hours should be treated as an incident.

## Attendance Exports

The workspace attendance page now supports exporting attendance for everyone across a selected date range.

### Behavior

* The export is inclusive: records on both the start date and end date are included.
* Exports are workspace-wide and include all recorded attendance rows across groups in the selected period.
* The UI builds the file client-side, but the data source remains the authenticated internal API route at `/api/v1/workspaces/:wsId/users/attendance/export`.

### Implementation Notes

* Keep range filtering on the persisted `user_group_attendance.date` string values with `gte(startDate)` and `lte(endDate)` to avoid timezone drift.
* Attendance exports must bind both `workspace_user_groups.ws_id` and joined `workspace_users.ws_id` to the normalized route workspace before returning user names or private email fields.
* Page the API response for large exports instead of assuming a single Supabase page will return every matching row.
* Excel and CSV generation should stay in the client so the page can reuse localized column labels and progress feedback.

## Workspace Member Profiles

Workspace members can have workspace-specific display names, similar to server profiles.

### Behavior

* Member profile display names are stored on `workspace_users.display_name`, not on the global `users.display_name`.
* The workspace members settings page can edit display names for joined members and pending invites.
* Pending email invites may create a `workspace_users` row before the invited platform user joins.
* When the invited user later joins, `workspace_user_linked_users` should reuse exactly one unlinked `workspace_users` row with a matching email in the same workspace.
* If multiple matching workspace profiles exist for an email, runtime linking must not guess. Admin edit APIs should report the ambiguity so duplicate profiles can be resolved explicitly.
* The users database page includes a platform-link repair action for administrators with user-update and private-info permissions. It links only matching platform users who are already workspace members; it never creates workspace membership or merges duplicate workspace profiles.

### Implementation Notes

* Keep members-page writes narrow: update the workspace profile display name only.
* Always verify `manage_workspace_members` before writing member profiles from the members settings UI.
* Enhanced member listing should display the workspace profile name when available and fall back to the platform user display name.
* Auto-linking runs on `workspace_members` insert. If a virtual profile is created or its email is corrected after membership already exists, use the database-page repair action to reconcile the link.
* Repair is conservative: a link is inserted only when one unlinked workspace profile and one existing member platform account share the same normalized email. Missing emails, no member match, duplicate workspace profiles, duplicate platform matches, and platform accounts already linked elsewhere are reported as skipped cases.

## Attendance Manager Counting

Workspace attendance settings include a default-on `ATTENDANCE_COUNT_MANAGERS` flag.

* When enabled, group managers count toward attendance totals in user-group list summaries.
* When disabled, attendance totals on the user-group list subtract group managers from the group member count.
* This is separate from `ATTENDANCE_SHOW_MANAGERS`, which controls whether managers appear in detailed attendance-taking views.

## User Group Activity Audit Logs

User group activity is exposed from the dashboard at `/users/groups?tab=audit-log` and on each group detail page. The feed is normalized from `audit.record_version` through private service-role RPCs so UI code receives one event shape with action, resource type, group, affected user, actor, timestamp, and before/after snapshots.

### Tracked Resources

* Group metadata and status: `workspace_user_groups`.
* Membership and manager role changes: `workspace_user_groups_users`.
* Group tags and default included groups: `workspace_user_group_tag_groups`, `workspace_default_included_user_groups`.
* Posts, post logs, and post checks: `user_group_posts`, `user_group_post_logs`, `user_group_post_checks`.
* Attendance, linked products, metrics, categories, category links, and student metric values: `user_group_attendance`, `user_group_linked_products`, `user_group_metrics`, `user_group_metric_categories`, `user_group_metric_category_links`, `user_indicators`.
* Reports and feedback: `external_user_monthly_reports`, `external_user_monthly_report_logs`, `user_feedbacks`.
* Course content: `workspace_course_modules`, `workspace_course_module_groups`.

### Actor Attribution

* Core group, member, metric, student metric value, and attendance mutations should use the private actor-aware RPCs so service-role writes set `audit.override_auth_uid` before changing rows.
* Other tracked tables still appear when raw audit rows exist. If a route writes with a service-role client and the table does not preserve actor intent in columns such as `creator_id` or `updated_by`, add a focused actor-aware private RPC or route-level activity insert before expanding the UI around that resource.
* Bulk reorder operations are normalized as `reordered` events when the persisted `sort_key` changes.

### Workspace Validation

* Before any admin write, normalize the route `wsId` and verify the target group belongs to that workspace.
* Member writes must also verify every affected `workspace_users.id` belongs to the same normalized workspace before inserting, updating, or deleting membership rows.
* Attendance writes must additionally verify every affected user is already a member of the target `workspace_user_groups_users` row before inserting or deleting `user_group_attendance`.
* Child resource writes should validate their parent group or parent module group before the admin mutation. Do not rely on a raw `group_id` from the URL without checking ownership.

## Topic Announcements

Topic Announcements live under Users and are gated by the workspace secret `ENABLE_TOPIC_ANNOUNCEMENTS=true`.

### Behavior

* Contacts are workspace-scoped and may be raw email contacts or linked to an existing workspace virtual user profile. The linker UI searches workspace users with avatar and email affordances.
* Announcements may optionally reference a real `workspace_user_groups` row through `group_id` for scheduling and reporting context.
* A contact cannot receive announcements until its email is verified through the Tuturuuu internal SES verification flow or through a linked Tuturuuu platform account with a confirmed matching email **and membership in the same workspace**. Platform-wide confirmed accounts must not auto-confirm a contact for another workspace.
* Announcements can include image and PDF attachments. The composer and API enforce the shared email limits: up to 5 files and 10 MB total per announcement.
* Verification emails are sent by the root Tuturuuu sender with normal protected delivery checks, not the rate-limit-bypassing system path.
* Verification links resolve to the public platform origin by default (`https://tuturuuu.com`) so listener hosts such as `0.0.0.0:7803` never leak into recipient inboxes. Set `TOPIC_ANNOUNCEMENT_VERIFICATION_ORIGIN` only when an explicit alternate public origin is required.
* Verification sends enforce a short pending-link cooldown before creating another token, and email delivery applies workspace, user, IP, and recipient limits. The recipient limit is global across workspaces, so one workspace or many workspaces cannot repeatedly send verification links to the same inbox.
* Actual announcements are sent by the enabled workspace sender and are written to `email_audit`.
* The composer and table send flow preview the same server-rendered HTML and text payload that delivery uses. Operators should review that rendered preview before sending or scheduling announcements.
* The first import preset supports foreign-teacher schedule rows with day/date, class, room, time, teacher/contact, email, place, and topic fields. The import UI now uses an editable Excel-like table as the review surface; uploaded spreadsheets, CSV, and direct paste all load into that table so operators can correct every email field before creating drafts or sending valid rows in bulk.
* Workspace-shared **announcement templates** store reusable title, topic starter text, class metadata, optional default group, and default recipient ids. Operators apply a template in the composer, then edit the topic field before sending.
* Operators can fork an existing sent or draft announcement into a new draft. The fork copies title, topic, class context, recipients, and attachment references, but never copies sent, queued, scheduled, or email audit state.
* **Scheduled send** sets `status = queued` and `scheduled_send_at` using the workspace's fixed IANA timezone from calendar settings. Scheduling is blocked while the workspace timezone is still `auto` or unset; use the same calendar timezone gate as the main calendar product.
* The `process-topic-announcement-queue` cron job (every 15 minutes) loads due queued rows and reuses the same `sendTopicAnnouncement` path as manual send. Failed sends keep the existing `failed` / `last_error` handling without infinite retries.
* Announcement list APIs enrich recipient rows with the same `verificationStatus` contract as the contacts list so the table does not treat missing status as unverified.

### Implementation Notes

* Client UI must call `@tuturuuu/internal-api` Topic Announcements helpers; do not add direct client-side fetches.
* Email preview must go through the Topic Announcements preview API and shared renderer instead of a client-only template so previews cannot drift from actual delivery.
* Bulk create/send must keep using the import API plus `send-bulk` helper from `@tuturuuu/internal-api`; do not bypass the shared renderer, recipient verification, or delivery gates for spreadsheet rows.
* Delivery APIs must check the workspace secret, `manage_users`, `send_user_group_post_emails`, recipient verification, and workspace ownership before sending.
* If a contact email changes, previous verification records for the old email must no longer satisfy delivery checks.
* Linked-account auto-confirm checks must join through `workspace_members` for the contact workspace. Do not treat a confirmed Tuturuuu account as sufficient unless that platform user belongs to the same workspace as the linked virtual user.
* Attachment uploads must prepare signed upload URLs through the central workspace storage route, then upload bytes directly to the active storage provider. Do not stream attachment bytes through Topic Announcement-specific Next.js routes.
* User group and course storage uploads are quota-sensitive and must use the server-mediated `uploadWorkspaceUserGroupStorageFile` / group storage multipart route. Do not mint signed upload URLs from this route because the app server cannot verify the final object size after a direct provider upload.
* Attachment rows keep workspace, announcement, storage path, content type, and size metadata. Email delivery downloads the stored files and switches to raw MIME only when attachments exist; regular no-attachment messages should keep the standard SES `SendEmailCommand` path.


# Platform Overview
Source: https://docs.tuturuuu.com/platform/overview

How Tuturuuu products, AI systems, and personalization layers fit together.

# Tuturuuu Platform Overview

The Tuturuuu platform combines proactive AI, unified applications, and automation tooling to help every visionary move from ambition to execution. Use this section to understand how each layer works and where to dive deeper.

<Note>
  Tuturuuu is mid-migration. The Next.js `apps/web` platform (port 7803) is being
  replaced by `apps/tanstack-web` (TanStack Start) plus a dedicated Rust
  `apps/backend` API. Most docs still describe the live `apps/web` shape, which
  remains valid today. See the
  [TanStack Start and Rust migration](/platform/architecture/tanstack-rust-migration)
  for the runtime contract and what moves where.
</Note>

## Explore the Platform

* **Applications** – Tuturuuu ships as a catalog of standalone web apps that each run on their own host, may serve product APIs locally, and can fall back to `apps/web` for unmatched or explicitly central route families. Browse the [Applications catalog](/platform/applications/calendar) covering [Calendar](/platform/applications/calendar), [Finance](/platform/applications/finance), [Drive](/platform/applications/drive), [Chat](/platform/applications/chat), [CMS](/platform/applications/cms), [Inventory](/platform/applications/inventory), [Storefront](/platform/applications/storefront), and the [Apps gateway](/platform/applications/apps).
* **Experience Apps** – See how Tuturuuu Calendar, Tuturuuu Tasks, Tuturuuu Meet, and the Command Center Dashboard deliver daily flow. Start with the [Command Center Dashboard](/platform/features/command-center-dashboard).
* **AI & Automation** – Learn how Mira (our Jarvis), Aurora, Nova, and Rewise power intelligent workflows in the [AI Overview](/platform/ai/structured-data).
* **Shared Components** – Reuse building blocks from the [Component Library](/platform/components/overview).
* **Personalization** – Tailor the workspace using [Themes](/platform/personalization/themes) and [Language settings](/platform/personalization/language).

## Satellite Apps And Central API Ownership

Beyond the experience surfaces, Tuturuuu is organized as a fleet of
**satellite apps** under `apps/` — `calendar`, `finance`, `drive`, `chat`,
`cms`, `inventory`, `storefront`, and more. Each runs as its own standalone host
on its own canonical domain. Satellites may own their product APIs locally;
unmatched or explicitly central route families can fall back to the live
`apps/web` platform. `apps/web` remains authoritative only where a route family
has not been hard-cut over to a satellite or another approved owner.

Use the [satellite app ownership guide](/platform/architecture/satellite-apps)
for local route, proxy, and auth boundaries. The
[TanStack and Rust migration guide](/platform/architecture/tanstack-rust-migration)
tracks the separate frontend and backend cutover model.

The [Apps gateway](/platform/applications/apps) (`apps.tuturuuu.com`) sits in
front of the routable apps as a launcher and redirect layer — it surfaces app
cards and redirects to each app's canonical domain rather than reverse-proxying
them.

## Offline Runtime Ownership

Tuturuuu owns service-worker registration, precache-manifest generation,
worker compilation, navigation fallback, and runtime cache strategies in
`packages/offline`. Applications consume `OfflineProvider`; the live Web app
builds the worker through `createOfflineRoute` and
`getOfflineTurbopackConfig`.

The worker continues to use `/serwist/sw.js` as a compatibility URL so existing
browser registrations upgrade in place. Do not add Serwist packages to an app
or depend on that project's release schedule. Extend the shared internal
runtime and its focused tests instead.

## How It All Fits Together

```mermaid theme={null}
graph TB
    subgraph Apps["Satellite Apps"]
        Cal["Calendar"]
        Fin["Finance"]
        Drive["Drive"]
        Chat["Chat"]
        More["…"]
    end

    subgraph Experience["Experience Layer"]
        CC["Command Center"]
        TuPlan["Tuturuuu Calendar"]
        TuDo["Tuturuuu Tasks"]
        Meet["Tuturuuu Meet"]
    end

    Core["Central Platform API<br/>(apps/web)"]

    subgraph AI["AI Layer"]
        Mira["Mira"]
        Aurora["Aurora"]
        Nova["Nova"]
        Rewise["Rewise"]
    end

    subgraph Auto["Automation Layer"]
        Agents["Agents"]
        Cloud["Cloud Exec"]
        Int["Integrations"]
    end

    Apps -->|/api/*| Core
    Experience --> Core
    Core --> Mira
    Mira --> Agents
    Agents --> Core
    Aurora --> Mira
    Nova --> Mira
    Rewise --> Aurora
    Agents --> Cloud
    Cloud --> Int
    Int --> Core

    style Mira fill:#4f46e5,stroke:#3730a3,color:#fff
    style Agents fill:#4f46e5,stroke:#3730a3,color:#fff
    style Core fill:#4f46e5,stroke:#3730a3,color:#fff
```

<Note>
  The AI- and automation-layer model above (Mira/Aurora/Nova/Rewise) is the
  conceptual organizing picture. In the running platform these flow through the
  central `apps/web` API alongside the satellite apps; the migration to
  `apps/tanstack-web` plus the Rust `apps/backend` is reshaping where this API
  boundary lives.
</Note>

## Next Steps

1. Walk through the [Platform Features](/platform/features/command-center-dashboard) to see how the GTD-aligned dashboard works.
2. Review the [AI Structured Data guide](/platform/ai/structured-data) to understand how we interact with models.
3. Explore [Component docs](/platform/components/overview) when you need reusable UI patterns.

Looking for development workflows? Jump to the [Build](/build/overview) section. Ready to level up your skills? Explore [Learn](/learn/overview).


# Language
Source: https://docs.tuturuuu.com/platform/personalization/language

View Tuturuuu in your preferred language.

## Usage

Language helps you view everything on [Tuturuuu](https://tuturuuu.com) in your preferred language.

### Supported Languages

Currently, we provide first-class support for the following languages:

* **English**
* **Vietnamese**

### How to Change Language

[Tuturuuu](https://tuturuuu.com) will automatically detect your browser's language and set the language accordingly. If you want to change the language, you can do so by clicking on the language switcher in your profile avatar (located at the top right corner of the page).

<Note>The language switcher is only available after you have logged in.</Note>

### Contribute

If you want to help us translate [Tuturuuu](https://tuturuuu.com) into your language, feel free to open a pull request on our [GitHub repository](https://github.com/tutur3u/platform).

Each supported locale lives in a single message bundle under `apps/web/messages/`:

* `apps/web/messages/en.json` for English
* `apps/web/messages/vi.json` for Vietnamese

When you add or change a key, update it in **both** `en.json` and `vi.json` so the bundles stay in sync, then run `bun i18n:sort` to keep the keys ordered consistently before committing.


# Sidebar Navigation
Source: https://docs.tuturuuu.com/platform/personalization/sidebar-navigation

How dashboard sidebar layout preferences work in apps/web.

## Default layout

The dashboard sidebar always keeps **Dashboard** in the root navigation. By default, the root navigation then shows **Tasks**, **Calendar**, and **Finance**.

All other eligible top-level tools are placed under **More tools**. More tools is grouped into durable sections:

* **Work tools**: Habits, Whiteboards, Track, Drive, Forms, Documents
* **AI**: Mind, Hive, Chat, AI Lab
* **Operations**: Workforce, Users, Inventory
* **Utilities**: QR Generator, Google Workspace, Meet, Polls, Mail, Education, Link Shortener

Dashboard is separated from the main root tools. **Settings** is pinned to the bottom of the sidebar, below More tools and Archived (including when Archived is promoted to the root sidebar).

## Managing layout

Users manage start-page navigation, sidebar behavior, sidebar layout, and recent-history visibility from **Settings → Preferences → Navigation & Sidebar**.

## Preference precedence

Sidebar layout preferences use a hybrid model:

1. Workspace override: `user_workspace_configs.SIDEBAR_NAVIGATION_LAYOUT`
2. Account default: `user_configs.SIDEBAR_NAVIGATION_LAYOUT`
3. Authored default layout

The saved layout stores three ordered id lists:

* `root`: first-level tools shown directly in the sidebar
* `more`: first-level tools shown inside More tools
* `hidden`: first-level tools archived from normal sidebar rendering

Unknown or stale ids are ignored when the layout is applied and are dropped the next time the user saves preferences.

## Quick actions

First-level navigation items expose compact hover actions in the sidebar:

* **Pin** moves an item from More tools to the root sidebar.
* **Unpin** moves an item from the root sidebar to More tools.
* **Archive** hides an item from normal sidebar rendering.

Pin, unpin, and archive also appear on tier-gated items that render grayed out in the sidebar. Saving layout preferences does not grant access to unavailable tools.

Dashboard and Settings are locked and cannot be pinned, unpinned, or archived.

Archived items appear in a compact **Archived** dropdown at the bottom of **More tools**. More tools remains visible when archived items exist alongside other visible More tools children.

When every normal More tools child is hidden or unavailable and **Archived** is the only remaining visible child, structure promotion lifts **Archived** to the root sidebar instead of leaving an empty More tools wrapper. Selecting an archived item from that dropdown (or the root Archived entry) restores it to its previous root or More tools placement.

## Visibility rules

Preferences never bypass authorization, feature flags, production gates, root-workspace restrictions, or tier visibility. If a tool is unavailable for the current user or workspace, placing it in root navigation does not make it appear.

Hidden tools remain directly routable. When the current route matches a hidden tool or one of its descendants, the sidebar reveals that item only for the current route and marks it as an active hidden item. This contextual reveal is not saved back into the preference config.

## Recent history

Recent sidebar navigation history is controlled by `user_configs.SIDEBAR_RECENT_NAVIGATION_ENABLED`.

The default is **off**. When disabled, the sidebar does not render recent navigation history and does not record recent visits.


# Themes
Source: https://docs.tuturuuu.com/platform/personalization/themes

Enhance your experience with themes.

## Usage

Themes are a way to customize the look and feel of your experience on [Tuturuuu](https://tuturuuu.com). You can choose from a variety of themes to suit your preferences.

### Modes

Modes are how the entire website looks. You can choose between **light mode**, **dark mode**, and **system mode** (which follows your system settings).

### Basic theme switcher

When you are not logged in, a basic theme switcher will be available which will allow you to switch between standard **dark mode** and **light mode** by clicking on the theme switcher in the top right corner of our website.

### Advanced theme switcher

You can switch between a variety of themes by tapping on your profile picture in the top right corner of our website and selecting the **Theme** option.

<Tip>This switcher is will available when you are logged in.</Tip>

#### Variants

When using **Advanced theme switcher**, you can also choose a variant of the selected mode.

<Note>For example, you can choose dark mode with a blue accent.</Note>

Available variants:

* **Standard** (Default)
* **Pink**
* **Purple**
* **Yellow**
* **Orange**
* **Green**
* **Blue**


# AI Studio API
Source: https://docs.tuturuuu.com/reference/api-reference/ai-studio

OpenAI-compatible Tuturuuu AI endpoints, bearer authentication, streaming, and native extensions.

The AI Studio API is served from `https://ai.tuturuuu.com` and accepts
workspace-scoped `ttr_ai_` credentials through the standard bearer header:

```http theme={null}
Authorization: Bearer ttr_ai_...
```

The plaintext credential is shown once. Store it in a secret manager and never
place it in browser bundles, URLs, logs, or source control.

<Tip>
  For a workspace-aware quickstart with copyable cURL and server-side TypeScript
  examples, open [AI Studio](https://ai.tuturuuu.com), select a workspace, and
  choose **Developer docs**. That module links directly to the same workspace's
  keys, Playground, credits, and run observability.
</Tip>

Creating or rotating a credential requires both the workspace
`manage_ai_keys` permission and a standing platform-admin approval for that
workspace. Listing and revoking existing credentials remain available without
issuance approval. Removing approval does not invalidate existing credentials.

Registered external apps may instead use a short-lived `ttr_app_` access token.
The app registration and issued token must both include `workspace:session` and
`ai:use`; speech requests require `tts:use`. These requests must also send the
normalized workspace ID returned by the app-token exchange:

```http theme={null}
Authorization: Bearer ttr_app_...
X-Tuturuuu-Workspace-Id: 00000000-0000-0000-0000-000000000000
```

The external-app path is temporarily exempt from workspace credit deductions.
It is not unrestricted access: registration status, linked workspace, current
user membership, model policy, payload bounds, workspace request rate, stable
request IDs, and usage auditing remain enforced. Browser sessions, internal
satellite sessions, ordinary Studio keys, and unrecognized callers never
receive this exemption.

## OpenAI-compatible endpoints

| Method | Path                             | Purpose                                 |
| ------ | -------------------------------- | --------------------------------------- |
| `GET`  | `/v1/models`                     | List models visible to the key          |
| `POST` | `/v1/responses`                  | Generate text or structured output      |
| `POST` | `/v1/chat/completions`           | OpenAI chat-completions compatibility   |
| `POST` | `/v1/embeddings`                 | Generate embeddings                     |
| `POST` | `/v1/images/generations`         | Generate images                         |
| `POST` | `/v1/audio/speech`               | Generate downloadable WAV or PCM speech |
| `POST` | `/v1/agents/{agentId}/responses` | Run a versioned workspace agent         |

Requests support stable `x-request-id` values and the `idempotency-key` header.
Streaming responses use server-sent events. Errors use an OpenAI-compatible
`error` object and include the stable request ID for support correlation.

Model access is the intersection of the globally enabled catalog, global Studio
defaults, workspace policy, plan or root grants, and the key's own model
restrictions. A model visible elsewhere in Tuturuuu is not necessarily
available to a Studio key.

The legacy global/workspace Studio enablement switches no longer gate model
execution. Credit availability, model policy, credential status, budgets, rate
limits, and abuse controls remain authoritative.

## Native extensions

Tuturuuu-native response metadata reports billed workspace credits, provider
cost when permitted, run and trace IDs, token or media units, and timing
information. These fields extend the compatible response without changing the
standard OpenAI fields.

Text endpoints accept an optional bounded tool-loop extension:

```json theme={null}
{
  "tuturuuu": {
    "max_steps": 4,
    "tools": ["calculator", "current_time"]
  }
}
```

`max_steps` must be between 1 and 8. The listed tools are deterministic,
server-owned demonstration tools; arbitrary HTTP requests and code execution
are not accepted. Non-streaming responses include
`tuturuuu.steps` with only the ordered step number, type, name, status, and
latency. Streaming responses emit the same sanitized trace in the final
`response.completed` event before `[DONE]`.

Workspace Studio dashboards combine settled `ai_studio_runs` with unmatched
deductions from `ai_credit_transactions`. This includes ordinary workspace
deductions and the signed-in member's personal deductions when a free workspace
uses a personal credit balance, without double-counting ledger rows linked to a
Studio run. Billed credits and settled provider cost are shown separately;
registered external-app runs therefore report provider cost while showing zero
billed workspace credits.

The usage and run-log responses include identifiers, model, feature, credential
source, status, token or media units, settled credits and cost, and timing
metadata. They never include raw prompts, model outputs, tool payloads, ledger
metadata, or unsanitized provider errors.

The legacy `/api/ai/generate` endpoint remains available as a compatibility
adapter. New integrations should use the `/v1` Studio endpoints.

### Speech

`POST /v1/audio/speech` accepts `input`, optional `voice`, optional
`response_format` (`wav` or `pcm`), and the
`google/gemini-3.1-flash-tts-preview` model. The response is downloadable audio
and is never cached. Google currently prices the model by text input tokens and
audio output tokens; Tuturuuu records both provider cost and generated audio
duration-derived token usage.

## Retention and content capture

Metadata logging is enabled by default. Prompt, output, and tool content is
captured only when the workspace enables content capture. Use the Studio
retention controls to review the active policy before submitting sensitive
data.


# Generate AI Completion
Source: https://docs.tuturuuu.com/reference/api-reference/endpoint/generate

Public Tuturuuu endpoint for generating text completions with supported Gemini models using a workspace API key.

# POST /api/ai/generate

This public API endpoint allows you to generate text completions using supported AI models (e.g., Gemini). You must provide a valid access key for authentication.

## Endpoint

```
POST https://tuturuuu.com/api/ai/generate
```

## Request Body

Send a JSON object with the following fields:

| Field       | Type   | Required | Description                                                             |
| ----------- | ------ | -------- | ----------------------------------------------------------------------- |
| `prompt`    | string | Yes      | The prompt text to generate a completion for.                           |
| `accessKey` | object | Yes      | Your API access key object. Must include `id` and `value` fields.       |
| `configs`   | object | No       | (Optional) Configuration object for the request. See below for details. |

### `accessKey` object

| Field   | Type   | Required | Description          |
| ------- | ------ | -------- | -------------------- |
| `id`    | string | Yes      | Your API access ID.  |
| `value` | string | Yes      | Your API access key. |

### `configs` object

| Field             | Type    | Required | Default                 | Description                                                            |
| ----------------- | ------- | -------- | ----------------------- | ---------------------------------------------------------------------- |
| `wsId`            | string  | No       | ROOT\_WORKSPACE\_ID     | Workspace ID.                                                          |
| `model`           | string  | No       | "gemini-2.0-flash-lite" | The model to use (see Supported Models). Must be allowed for your key. |
| `systemPrompt`    | string  | No       | ""                      | (Optional) System instructions for the model.                          |
| `thinkingBudget`  | number  | No       | 0                       | (Optional) Budget for model "thinking" (advanced).                     |
| `includeThoughts` | boolean | No       | false                   | (Optional) Include model "thoughts" in the response (advanced).        |

## Supported Models

* `gemini-2.0-flash`
* `gemini-2.0-flash-lite`
* `gemini-2.5-flash`
* `gemini-2.5-flash-lite`
* `gemini-2.5-pro`

## Example Request

```json theme={null}
{
  "prompt": "The Swedish buyout firm has sold its remaining 22.4 percent stake, almost eighteen months after taking the company public in Finland.",
  "accessKey": {
    "id": "00000000-0000-0000-0000-000000000000",
    "value": "00000000-0000-0000-0000-000000000000"
  },
  "configs": {
    "model": "gemini-2.5-pro",
    "systemPrompt": "Analyze the sentiment of the text and return a JSON object with the following format: {\"sentiment\": positive|negative|neutral,\"confidence_scores\":{\"positive\": <float between 0.0 and 1.0>, \"negative\": <float between 0.0 and 1.0>, \"neutral\": <float between 0.0 and 1.0>}, \"explanation\": \"<brief explanation of the sentiment>\"}.\n\nEnsure no extra text outside the JSON."
  }
}
```

## Example Response

```json theme={null}
{
  "input": "The Swedish buyout firm has sold its remaining 22.4 percent stake, almost eighteen months after taking the company public in Finland.",
  "output": "{\"sentiment\":\"neutral\",\"confidence_scores\":{\"positive\":0.12,\"negative\":0.10,\"neutral\":0.78},\"explanation\":\"The text is factual and does not express a clear positive or negative sentiment.\"}",
  "usage": {
    "inputTokens": 45,
    "outputTokens": 60,
    "reasoningTokens": 10,
    "totalTokens": 115
  },
  "finishReason": "stop",
  "cost": {
    "inputCost": "$0.00005625",
    "outputCost": "$0.00060000",
    "reasoningCost": "$0.00010000",
    "totalCost": "$0.00075625"
  }
}
```

## Errors

* `400 Missing accessKey` — You must provide both `id` and `value` in the accessKey object.
* `400 Invalid model` — The model is not allowed for your key.
* `400 Invalid accessKey` — The credentials are invalid.
* `400 Missing prompt` — The prompt field is required.
* `400 Missing API key` — Internal error, contact support.

## Notes

* You must have a valid access key with the required model scope.
* The response includes the original input, the model output, token usage, cost breakdown, and the finish reason.


# API Reference
Source: https://docs.tuturuuu.com/reference/api-reference/introduction

Overview of the public Tuturuuu HTTP API, authentication, and where the canonical OpenAPI contract lives.

# API Reference

This section documents the public Tuturuuu HTTP API. It is reference material for
integrators calling Tuturuuu endpoints from outside the platform.

<Note>
  Tuturuuu is mid-migration from the legacy `apps/web` Next.js platform
  (port `7803`) to a TanStack Start frontend plus a dedicated Rust backend
  (port `7820`). Endpoint hosts and paths may shift as routes move behind the
  Rust backend. See
  [Tanstack + Rust migration](/platform/architecture/tanstack-rust-migration)
  for the current state.
</Note>

## What this API covers

This section documents the OpenAI-compatible **AI Studio API**, including
responses, chat completions, embeddings, images, and versioned agents. See
[AI Studio API](/reference/api-reference/ai-studio). The older
[Generate AI Completion](/reference/api-reference/endpoint/generate) endpoint
remains available as a compatibility adapter.

The full surface of internal and migrated platform routes is defined by the
backend OpenAPI contract rather than enumerated here.

## Authentication

Authentication depends on the endpoint:

* **AI-only bearer keys.** AI Studio endpoints authenticate with a hash-only
  `ttr_ai_` workspace credential in the `Authorization: Bearer` header. These
  keys can call only AI Studio endpoints and are restricted by workspace,
  model, expiry, rate, and optional credit-budget policy.
* **Legacy workspace API keys.** The compatibility AI generate endpoint still
  accepts its existing request-body `accessKey` contract while integrations
  migrate to AI Studio.
* **Bearer tokens / session cookies.** Migrated platform routes behind the Rust
  backend authenticate the caller's Supabase session — either a browser session
  cookie or a `Bearer` token — and some accept app-session tokens. These routes
  are not general-purpose public endpoints; they back first-party Tuturuuu apps.

Never commit API keys or tokens. Reference credentials by environment variable
name and supply them at request time.

## Canonical OpenAPI specification

The authoritative machine-readable contract for the Rust backend lives in the
repository at:

```
apps/backend/api/openapi.yaml
```

This `Tuturuuu Rust Backend API` spec is the source of truth for migrated routes,
their request/response schemas, security requirements, and status codes. The
legacy public API also lives under `apps/web/src/app/api/v1` until the
corresponding routes finish moving behind the Rust backend.


# Database Migrations Guide
Source: https://docs.tuturuuu.com/reference/database/migrations-guide

Best practices for creating, testing, and deploying Supabase migrations

The Tuturuuu platform uses Supabase migrations to manage database schema changes with version control and reproducibility.

## Migration Workflow

```
┌─────────────────────────────────────────────────────┐
│  1. Make schema changes locally                      │
│     ├─ Edit tables in Supabase Studio               │
│     ├─ OR write SQL migration manually              │
│     └─ Test changes                                  │
└─────────────────┬───────────────────────────────────┘
                  │
┌─────────────────▼───────────────────────────────────┐
│  2. Generate migration                               │
│     ├─ bun sb:diff (from Studio changes)            │
│     ├─ OR bun sb:new (blank migration)              │
│     └─ Review generated SQL                          │
└─────────────────┬───────────────────────────────────┘
                  │
┌─────────────────▼───────────────────────────────────┐
│  3. Test migration locally                           │
│     ├─ bun sb:reset (fresh DB)                      │
│     ├─ Verify schema                                │
│     └─ Test RLS policies                            │
└─────────────────┬───────────────────────────────────┘
                  │
┌─────────────────▼───────────────────────────────────┐
│  4. Commit migration                                 │
│     ├─ git add apps/database/supabase/migrations/          │
│     ├─ git commit                                    │
│     └─ Push to repository                           │
└─────────────────┬───────────────────────────────────┘
                  │
┌─────────────────▼───────────────────────────────────┐
│  5. Deploy (USER ONLY - AGENTS NEVER)               │
│     ├─ bun sb:push (production)                     │
│     ├─ OR apply via CI/CD                           │
│     └─ Verify in production                         │
└─────────────────────────────────────────────────────┘
```

## Creating Migrations

### Method 1: Generate from Studio Changes

**Best for:** Visual schema editing, quick table creation

1. **Make changes in Supabase Studio:**
   ```bash theme={null}
   bun sb:start
   # Open http://localhost:8003
   # Make changes in Table Editor
   ```

2. **Generate migration:**
   ```bash theme={null}
   bun sb:diff
   ```

3. **Review generated file:**
   ```bash theme={null}
   # apps/database/supabase/migrations/20250101120000_add_new_table.sql
   ```

### Method 2: Manual SQL Migration

**Best for:** Complex changes, custom functions, data migrations

1. **Create blank migration:**
   ```bash theme={null}
   bun sb:new add_custom_function
   ```

2. **Edit migration file:**
   ```sql theme={null}
   -- apps/database/supabase/migrations/20250101120000_add_custom_function.sql

   -- Create custom function
   CREATE OR REPLACE FUNCTION get_user_task_count(user_uuid uuid)
   RETURNS integer AS $$
     SELECT COUNT(*)::integer
     FROM workspace_tasks
     WHERE created_by = user_uuid;
   $$ LANGUAGE sql SECURITY DEFINER;
   ```

## Migration File Structure

### Naming Convention

```
[timestamp]_[descriptive_name].sql
```

Examples:

```
20250101120000_create_tasks_table.sql
20250101130000_add_task_priority_column.sql
20250101140000_update_task_rls_policies.sql
```

Keep new migration timestamps ahead of the latest migration already on `main`,
`staging`, and `production`. Supabase refuses to apply a local migration that
sorts before the last remote migration unless the operator passes
`--include-all`. Staging and production CI intentionally run
`supabase db push --include-all` so each project can converge after migration
history changes, but ordinary forward deploys should still keep timestamps
monotonic. After a rebase, merge, or hotfix, re-list
`apps/database/supabase/migrations` and rename any still-unapplied local
migration forward instead of treating `--include-all` as permission to edit or
replay old migration history.

### File Template

```sql theme={null}
-- Migration: [Description]
-- Created: [Date]
-- Author: [Name]

-- Create table
CREATE TABLE IF NOT EXISTS table_name (
  id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
  created_at timestamptz DEFAULT now()
);

-- Add indexes
CREATE INDEX idx_table_name_column ON table_name(column);

-- Enable RLS
ALTER TABLE table_name ENABLE ROW LEVEL SECURITY;

-- Add RLS policies
CREATE POLICY "policy_name"
ON table_name
FOR SELECT
USING (true);

-- Add comments
COMMENT ON TABLE table_name IS 'Description of table';
COMMENT ON COLUMN table_name.column IS 'Description of column';
```

## Common Migration Patterns

### Creating Tables

```sql theme={null}
-- Create workspace-scoped table
CREATE TABLE workspace_resources (
  id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
  ws_id text NOT NULL REFERENCES workspaces(id) ON DELETE CASCADE,
  name text NOT NULL,
  description text,
  created_by uuid REFERENCES workspace_users(id) ON DELETE SET NULL,
  created_at timestamptz DEFAULT now(),
  updated_at timestamptz DEFAULT now()
);

-- Add indexes
CREATE INDEX idx_workspace_resources_ws_id ON workspace_resources(ws_id);
CREATE INDEX idx_workspace_resources_created_by ON workspace_resources(created_by);

-- Enable RLS
ALTER TABLE workspace_resources ENABLE ROW LEVEL SECURITY;

-- Add policies
CREATE POLICY "workspace_members_can_view"
ON workspace_resources FOR SELECT
USING (
  ws_id IN (
    SELECT ws_id FROM workspace_members WHERE user_id = auth.uid()
  )
);

CREATE POLICY "permission_required_to_modify"
ON workspace_resources FOR ALL
USING (
  ws_id IN (
    SELECT wm.ws_id FROM workspace_members wm
    JOIN workspace_role_permissions wrp
      ON wrp.ws_id = wm.ws_id AND wrp.role_id = wm.role
    WHERE wm.user_id = auth.uid()
      AND wrp.permission = 'manage_resources'
  )
);
```

### Adding Columns

```sql theme={null}
-- Add nullable column
ALTER TABLE workspace_tasks
ADD COLUMN priority integer;

-- Add column with default
ALTER TABLE workspace_tasks
ADD COLUMN status text DEFAULT 'pending';

-- Add NOT NULL column (requires default or backfill)
ALTER TABLE workspace_tasks
ADD COLUMN category text DEFAULT 'general' NOT NULL;

-- Update existing rows (if needed)
UPDATE workspace_tasks
SET category = 'important'
WHERE priority >= 4;
```

### Modifying Columns

```sql theme={null}
-- Rename column
ALTER TABLE workspace_tasks
RENAME COLUMN old_name TO new_name;

-- Change column type
ALTER TABLE workspace_tasks
ALTER COLUMN priority TYPE smallint USING priority::smallint;

-- Add constraint
ALTER TABLE workspace_tasks
ADD CONSTRAINT priority_range CHECK (priority BETWEEN 0 AND 5);

-- Drop constraint
ALTER TABLE workspace_tasks
DROP CONSTRAINT priority_range;
```

### Creating Indexes

```sql theme={null}
-- Standard index
CREATE INDEX idx_tasks_ws_id ON workspace_tasks(ws_id);

-- Composite index
CREATE INDEX idx_tasks_ws_list ON workspace_tasks(ws_id, list_id);

-- Partial index
CREATE INDEX idx_incomplete_tasks
ON workspace_tasks(ws_id)
WHERE completed = false;

-- Unique index
CREATE UNIQUE INDEX idx_unique_task_name
ON workspace_tasks(ws_id, name);

-- GIN index for JSONB
CREATE INDEX idx_metadata_gin ON workspace_tasks USING GIN (metadata);

-- Text search index
CREATE INDEX idx_tasks_search
ON workspace_tasks USING GIN (to_tsvector('english', name || ' ' || COALESCE(description, '')));
```

### Creating Functions

```sql theme={null}
-- Simple function
CREATE OR REPLACE FUNCTION get_workspace_task_count(workspace_id text)
RETURNS integer AS $$
  SELECT COUNT(*)::integer
  FROM workspace_tasks
  WHERE ws_id = workspace_id;
$$ LANGUAGE sql SECURITY DEFINER;

-- Function with complex logic
CREATE OR REPLACE FUNCTION complete_task_with_notification(task_uuid uuid)
RETURNS void AS $$
DECLARE
  task_name text;
  task_ws_id text;
BEGIN
  -- Update task
  UPDATE workspace_tasks
  SET completed = true, completed_at = now()
  WHERE id = task_uuid
  RETURNING name, ws_id INTO task_name, task_ws_id;

  -- Create notification (example)
  INSERT INTO notifications (ws_id, message, type)
  VALUES (task_ws_id, format('Task "%s" completed', task_name), 'success');
END;
$$ LANGUAGE plpgsql SECURITY DEFINER;
```

### Creating Triggers

```sql theme={null}
-- Update updated_at timestamp trigger
CREATE OR REPLACE FUNCTION update_updated_at()
RETURNS trigger AS $$
BEGIN
  NEW.updated_at = now();
  RETURN NEW;
END;
$$ LANGUAGE plpgsql;

CREATE TRIGGER trigger_update_workspace_tasks_updated_at
  BEFORE UPDATE ON workspace_tasks
  FOR EACH ROW
  EXECUTE FUNCTION update_updated_at();
```

### Creating Enums

```sql theme={null}
-- Create enum
CREATE TYPE task_status AS ENUM ('pending', 'in_progress', 'completed', 'cancelled');

-- Add enum column
ALTER TABLE workspace_tasks
ADD COLUMN status task_status DEFAULT 'pending';

-- Modify enum (add value)
ALTER TYPE task_status ADD VALUE 'on_hold';

-- Cannot remove enum values - requires recreation
```

## Data Migrations

### Safe Data Migration Pattern

```sql theme={null}
-- 1. Add new column
ALTER TABLE workspace_tasks
ADD COLUMN new_priority integer;

-- 2. Backfill data
UPDATE workspace_tasks
SET new_priority = CASE
  WHEN old_priority = 'high' THEN 5
  WHEN old_priority = 'medium' THEN 3
  WHEN old_priority = 'low' THEN 1
  ELSE 0
END;

-- 3. Make NOT NULL (if needed)
ALTER TABLE workspace_tasks
ALTER COLUMN new_priority SET NOT NULL;

-- 4. Drop old column (in separate migration after verification)
-- ALTER TABLE workspace_tasks DROP COLUMN old_priority;
```

### Batch Processing Large Migrations

```sql theme={null}
-- For tables with millions of rows, batch the updates
DO $$
DECLARE
  batch_size integer := 1000;
  rows_updated integer;
BEGIN
  LOOP
    UPDATE workspace_tasks
    SET new_column = calculate_value(old_column)
    WHERE id IN (
      SELECT id FROM workspace_tasks
      WHERE new_column IS NULL
      LIMIT batch_size
    );

    GET DIAGNOSTICS rows_updated = ROW_COUNT;
    EXIT WHEN rows_updated = 0;

    -- Commit after each batch
    COMMIT;
  END LOOP;
END $$;
```

## Testing Migrations

### Local Testing

```bash theme={null}
# Reset to clean state
bun sb:reset

# Verify schema
bun sb:status

# Check migration list
ls apps/database/supabase/migrations/

# Test specific queries
psql -h localhost -U postgres -d postgres -c "SELECT * FROM workspace_tasks LIMIT 5;"
```

### Test RLS Policies

```sql theme={null}
-- Set user context for testing
SET request.jwt.claim.sub = 'user-uuid-here';

-- Test query with RLS
SELECT * FROM workspace_tasks WHERE ws_id = 'workspace-123';

-- Reset context
RESET request.jwt.claim.sub;
```

### Verify Indexes

```sql theme={null}
-- Check if index is being used
EXPLAIN ANALYZE
SELECT * FROM workspace_tasks WHERE ws_id = 'workspace-123';

-- List all indexes on table
SELECT indexname, indexdef
FROM pg_indexes
WHERE tablename = 'workspace_tasks';
```

## Migration Checklist

Before committing a migration:

* [ ] Migration file has descriptive name
* [ ] All tables have RLS enabled
* [ ] RLS policies are tested
* [ ] Indexes added for foreign keys
* [ ] Indexes added for frequently queried columns
* [ ] Comments added for complex logic
* [ ] Data migration is idempotent
* [ ] Migration tested with `bun sb:reset`
* [ ] Type generation updated (`bun sb:typegen`)
* [ ] Breaking changes documented

## Deploying Migrations

### ⚠️ AGENTS: NEVER RUN THESE COMMANDS

Agents should prepare migrations but NEVER deploy them. Only users should run:

```bash theme={null}
# Link to remote project (one-time setup)
bun sb:link

# Push migrations to production
bun sb:push
```

### Agent Workflow

**Agents should:**

1. Create migration file
2. Test locally with `bun sb:reset`
3. Run `bun sb:typegen`
4. Commit files
5. **Instruct user to run `bun sb:push`**

**Agents should NEVER:**

* Run `bun sb:push`
* Run `bun sb:linkpush`
* Deploy to production

## Rollback Strategy

### Simple Rollback

```sql theme={null}
-- Create reverse migration
-- apps/database/supabase/migrations/20250101150000_rollback_add_priority.sql

ALTER TABLE workspace_tasks DROP COLUMN priority;
```

### Complex Rollback

```sql theme={null}
-- apps/database/supabase/migrations/20250101150000_rollback_task_status_enum.sql

-- 1. Add back old column
ALTER TABLE workspace_tasks ADD COLUMN old_status text;

-- 2. Convert data
UPDATE workspace_tasks
SET old_status = CASE
  WHEN status = 'pending' THEN 'todo'
  WHEN status = 'in_progress' THEN 'doing'
  WHEN status = 'completed' THEN 'done'
END;

-- 3. Drop new column
ALTER TABLE workspace_tasks DROP COLUMN status;

-- 4. Rename old column
ALTER TABLE workspace_tasks RENAME COLUMN old_status TO status;

-- 5. Drop enum type
DROP TYPE task_status;
```

## Common Issues

### Issue: Migration Fails on Production

**Cause:** Local Supabase version differs from production

**Solution:**

```bash theme={null}
# Check Supabase version
bun sb:status

# Update Supabase CLI
bun add -g supabase

# Recreate local instance
bun sb:stop
bun sb:start
```

### Issue: Type Generation Fails

**Cause:** Migration has syntax errors

**Solution:**

```bash theme={null}
# Reset database
bun sb:reset

# Check migration syntax
cat apps/database/supabase/migrations/[migration-file].sql

# Fix errors and retry
bun sb:typegen
```

### Issue: RLS Policy Conflicts

**Cause:** Multiple policies on same table/operation

**Solution:**

```sql theme={null}
-- List all policies
SELECT policyname, permissive, roles, cmd, qual
FROM pg_policies
WHERE tablename = 'workspace_tasks';

-- Drop conflicting policy
DROP POLICY "old_policy" ON workspace_tasks;
```

## Best Practices

### ✅ DO

1. **Use descriptive names**
   ```sql theme={null}
   20250101_add_task_priority_with_validation.sql
   ```

2. **Add indexes for foreign keys**
   ```sql theme={null}
   CREATE INDEX idx_tasks_ws_id ON workspace_tasks(ws_id);
   ```

3. **Enable RLS on all tables**
   ```sql theme={null}
   ALTER TABLE table_name ENABLE ROW LEVEL SECURITY;
   ```

4. **Add comments for clarity**
   ```sql theme={null}
   COMMENT ON TABLE workspace_tasks IS 'User tasks within workspaces';
   ```

5. **Test migrations locally first**
   ```bash theme={null}
   bun sb:reset
   ```

6. **Materialize replacement-table rows before rewiring child foreign keys**
   ```sql theme={null}
   -- When replacing a parent table, copy or upsert the source rows first.
   INSERT INTO workspace_user_groups (id, ws_id, name)
   SELECT id, ws_id, name
   FROM workspace_courses
   ON CONFLICT (id) DO UPDATE
   SET name = EXCLUDED.name;

   -- Then backfill the child FK, validate it, and only afterwards drop the legacy column/table.
   ALTER TABLE workspace_course_modules ADD COLUMN group_id uuid;

   UPDATE workspace_course_modules
   SET group_id = course_id
   WHERE group_id IS NULL;

   -- Verify the backfill before dropping or rewiring the legacy FK in a follow-up migration.
   -- SELECT COUNT(*) FILTER (WHERE group_id IS NULL) AS unmigrated
   -- FROM workspace_course_modules;
   ```

### ❌ DON'T

1. **Don't skip RLS**
   ```sql theme={null}
   -- ❌ Bad: No RLS
   CREATE TABLE table_name (...);
   ```

2. **Don't use DROP without backup**
   ```sql theme={null}
   -- ❌ Dangerous
   DROP TABLE important_data;
   ```

3. **Don't modify old migrations**
   ```sql theme={null}
   -- ❌ Bad: Modifying committed migration
   ```

4. **Don't deploy without testing**
   ```bash theme={null}
   # ❌ Bad: Skip local testing
   bun sb:push
   ```

## Related Documentation

* [Database Schema Overview](/reference/database/schema-overview)
* [RLS Policies](/reference/database/rls-policies)
* [Supabase Client](/reference/packages/supabase)

## External Resources

* [Supabase Migrations](https://supabase.com/docs/guides/cli/local-development#database-migrations)
* [PostgreSQL ALTER TABLE](https://www.postgresql.org/docs/current/sql-altertable.html)


# Row-Level Security (RLS) Policies
Source: https://docs.tuturuuu.com/reference/database/rls-policies

Security model and RLS policy patterns in the Tuturuuu platform

The Tuturuuu platform implements comprehensive Row-Level Security (RLS) policies to enforce workspace-based multi-tenancy and granular permission controls.

## Security Model Overview

### Core Principles

1. **Workspace Isolation**: All workspace-scoped resources are isolated via RLS policies
2. **Permission-Based Access**: Actions require specific workspace role permissions
3. **User Ownership**: Users can only access resources they own or have permission to view
4. **Fail-Secure Default**: No access unless explicitly granted by policy

### Architecture

```
┌─────────────────────────────────────────┐
│         PostgreSQL Database             │
│  ┌───────────────────────────────────┐  │
│  │   RLS Policies (113+ policies)     │  │
│  ├───────────────────────────────────┤  │
│  │  1. Workspace Membership Check     │  │
│  │  2. Permission Verification        │  │
│  │  3. Ownership Validation           │  │
│  └───────────────────────────────────┘  │
└─────────────────────────────────────────┘
```

## Policy Patterns

### Pattern 1: Workspace Membership Check

**Use Case:** User must be a member of the workspace to access resources.

**Example:** `workspace_tasks` SELECT policy

```sql theme={null}
CREATE POLICY "Users can view tasks in their workspaces"
ON workspace_tasks
FOR SELECT
USING (
  ws_id IN (
    SELECT ws_id
    FROM workspace_members
    WHERE user_id = (select auth.uid())
      AND type = 'MEMBER'
  )
);
```

**Key Components:**

* `auth.uid()`: Gets the authenticated user's ID
* Subquery checks `workspace_members` table
* Returns only rows matching user's workspaces

### Pattern 2: Permission-Based Access

**Use Case:** User needs specific workspace permission to perform action.

**Example:** Task UPDATE policy

```sql theme={null}
CREATE POLICY "Users can update tasks with manage_projects permission"
ON workspace_tasks
FOR UPDATE
USING (
  EXISTS (
    SELECT 1
    FROM workspace_members wm
    WHERE wm.ws_id = workspace_tasks.ws_id
      AND wm.user_id = (select auth.uid())
      AND wm.type = 'MEMBER'
  )
  AND public.has_workspace_permission(
    workspace_tasks.ws_id,
    (select auth.uid()),
    'manage_projects'
  )
)
WITH CHECK (
  EXISTS (
    SELECT 1
    FROM workspace_members wm
    WHERE wm.ws_id = workspace_tasks.ws_id
      AND wm.user_id = (select auth.uid())
      AND wm.type = 'MEMBER'
  )
  AND public.has_workspace_permission(
    workspace_tasks.ws_id,
    (select auth.uid()),
    'manage_projects'
  )
);
```

**Permission Enum Values:**

Permissions come from the `workspace_role_permission` enum. The generated list
is the single source of truth — see the `workspace_role_permission` array in
`packages/types/src/supabase.ts` (regenerated by `bun sb:typegen`) rather than
hard-coding values, since the set evolves with new features. A representative
subset at the time of writing:

* `manage_workspace_settings`
* `manage_workspace_roles`
* `manage_workspace_members`
* `manage_workspace_security`
* `manage_workspace_audit_logs`
* `manage_projects`
* `manage_calendar`
* `manage_documents`
* `manage_drive`
* `manage_users`
* `manage_finance`
* `manage_inventory`
* `ai_chat`
* `ai_lab`

<Note>
  Task and project access is governed by `manage_projects`; there is no
  `manage_tasks` permission. Several values that older docs referenced
  (`manage_infrastructure_settings`, `manage_user_groups`, `manage_user_roles`,
  `ai_lab_assistant`, `view_disabled_users`, `disable_user`) are no longer part
  of the enum. Always confirm a permission string against the generated enum
  before using it in a policy — a typo or removed value will fail the
  `permission::workspace_role_permission` cast at runtime.
</Note>

### Pattern 3: User Ownership

**Use Case:** User can only access resources they created.

**Example:** `notes` policies

```sql theme={null}
-- SELECT
CREATE POLICY "Users can view their own notes"
ON notes
FOR SELECT
USING (created_by = auth.uid());

-- INSERT
CREATE POLICY "Users can create their own notes"
ON notes
FOR INSERT
WITH CHECK (created_by = auth.uid());

-- UPDATE
CREATE POLICY "Users can update their own notes"
ON notes
FOR UPDATE
USING (created_by = auth.uid());

-- DELETE
CREATE POLICY "Users can delete their own notes"
ON notes
FOR DELETE
USING (created_by = auth.uid());
```

### Pattern 4: Combined Workspace + Permission

**Use Case:** Workspace membership AND specific permission required.

**Example:** Calendar event management

```sql theme={null}
CREATE POLICY "Users can manage calendar events with permission"
ON workspace_calendar_events
FOR ALL
USING (
  EXISTS (
    SELECT 1
    FROM workspace_members wm
    WHERE wm.ws_id = workspace_calendar_events.ws_id
      AND wm.user_id = (select auth.uid())
      AND wm.type = 'MEMBER'
  )
  AND (
    public.has_workspace_permission(
      workspace_calendar_events.ws_id,
      (select auth.uid()),
      'manage_calendar'
    )
    OR public.has_workspace_permission(
      workspace_calendar_events.ws_id,
      (select auth.uid()),
      'manage_workspace_settings'
    )
  )
)
WITH CHECK (
  EXISTS (
    SELECT 1
    FROM workspace_members wm
    WHERE wm.ws_id = workspace_calendar_events.ws_id
      AND wm.user_id = (select auth.uid())
      AND wm.type = 'MEMBER'
  )
  AND (
    public.has_workspace_permission(
      workspace_calendar_events.ws_id,
      (select auth.uid()),
      'manage_calendar'
    )
    OR public.has_workspace_permission(
      workspace_calendar_events.ws_id,
      (select auth.uid()),
      'manage_workspace_settings'
    )
  )
);
```

### Pattern 5: Public Read, Restricted Write

**Use Case:** All workspace members can view, only privileged users can modify.

**Example:** Workspace settings

```sql theme={null}
-- Read: any workspace member
CREATE POLICY "Members can view workspace settings"
ON workspaces
FOR SELECT
USING (
  EXISTS (
    SELECT 1 FROM workspace_members wm
    WHERE wm.ws_id = workspaces.id
      AND wm.user_id = (select auth.uid())
  )
);

-- Write: requires permission
CREATE POLICY "Users can update workspace with permission"
ON workspaces
FOR UPDATE
USING (
  EXISTS (
    SELECT 1
    FROM workspace_members wm
    WHERE wm.ws_id = workspaces.id
      AND wm.user_id = (select auth.uid())
      AND wm.type = 'MEMBER'
  )
  AND public.has_workspace_permission(
    workspaces.id,
    (select auth.uid()),
    'manage_workspace_settings'
  )
)
WITH CHECK (
  EXISTS (
    SELECT 1
    FROM workspace_members wm
    WHERE wm.ws_id = workspaces.id
      AND wm.user_id = (select auth.uid())
      AND wm.type = 'MEMBER'
  )
  AND public.has_workspace_permission(
    workspaces.id,
    (select auth.uid()),
    'manage_workspace_settings'
  )
);
```

### Pattern 6: Cross-Table Permission Inheritance

**Use Case:** Permission check depends on related table's policies.

**Example:** Task project members inherit from project permissions

```sql theme={null}
CREATE POLICY "Project members can view project tasks"
ON task_project_tasks
FOR SELECT
USING (
  project_id IN (
    SELECT id FROM task_projects
    -- task_projects has its own RLS policy checking workspace membership
  )
);
```

### Pattern 7: Platform User Profile Visibility

**Use Case:** Platform profile rows are useful for names and avatars, but the
Data API must not let any authenticated user enumerate every account.

`public.users` is not a globally readable directory. Authenticated callers can
read their own row and rows for users who share at least one workspace with
them. Private account fields such as email and full name belong in
`public.user_private_details`. Account state and preferences such as
`services`, `timezone`, `first_day_of_week`, `time_format`, and `deleted` also
belong there instead of on the public profile row.

`public.user_private_details` may be used for self-profile and shared-workspace
profile lookups, but the policy must correlate the target user to the current
requesting user. Do not use an uncorrelated `EXISTS` check that only proves the
target user belongs to some workspace.

Use a `SECURITY DEFINER` helper for the shared-workspace check so the profile
policy does not recurse through `workspace_members` RLS under the caller's
permissions.

Do not restore a policy equivalent to `USING (true)` on `public.users`. If a
feature needs a global user directory or public profile page, expose only the
intended columns through an application route or a purpose-built API contract
instead of widening the table policy.

```sql theme={null}
CREATE POLICY "Enable read access for current user and workspace members"
ON public.users
FOR SELECT
TO authenticated
USING (
  (select auth.uid()) is not null
  and (
    id = (select auth.uid())
    or public.current_user_shares_workspace_with(users.id)
  )
);
```

### Pattern 8: Client-Facing Public Views

**Use Case:** A view in the exposed `public` schema is granted to `anon` or
`authenticated`.

Postgres views are security definer by default when created by privileged
owners. In Supabase, that means a public view can bypass RLS on the underlying
tables even when every base table has RLS enabled. Any public-schema view that
is directly selectable by `anon` or `authenticated` must be created or altered
with `security_invoker = true`.

Do not use a public view as a shortcut around table policies. If a view needs
privileged data such as audit records or private profile details, revoke direct
client-role `SELECT` and expose the data through a permission-checked API route
or RPC instead.

```sql theme={null}
CREATE OR REPLACE VIEW public.workspace_safe_summary
WITH (security_invoker = true) AS
SELECT ...
FROM public.workspace_scoped_table;

REVOKE SELECT ON public.audit_logs FROM anon, authenticated;
```

New public views should be covered by `public-view-security.sql`, which fails
when a Data API-exposed view is missing `security_invoker`.

### Pattern 9: Workspace-Scoped Security Definer RPCs

**Use Case:** An RPC must run with elevated database privileges to read audit,
private, or RLS-protected tables.

Every workspace-scoped `SECURITY DEFINER` RPC that is reachable through the
Supabase Data API must enforce authorization inside the database function. Page,
route, or server action permission checks are not sufficient because clients can
call exposed RPCs directly.

Required controls:

* Read the caller with `auth.uid()` and deny missing callers unless the JWT role
  is `service_role`.
* Verify workspace membership and the workspace permission in the function
  before reading sensitive rows. Do not rely on permission helpers alone when a
  default permission could be enabled workspace-wide.
* For identity-linking flows, resolve candidate identity inside the function
  from the current verified `auth.users` row. Gate privileged lookups with the
  workspace feature config before returning candidate IDs, and do not accept
  caller-supplied emails or user-editable profile fields as proof of identity.
* Revoke direct execution from `public` and `anon`.
* Avoid exposing lower-level privileged helper functions to `authenticated` when
  they do not perform their own permission check.
* Cover the grant matrix and allowed/denied calls with pgTAP when practical.

```sql theme={null}
create or replace function public.authorize_workspace_sensitive_rpc(
  p_ws_id uuid
)
returns void
language plpgsql
security definer
set search_path = ''
as $$
begin
  if auth.role() = 'service_role' then
    return;
  end if;

  if auth.uid() is null then
    raise exception 'auth_required' using errcode = '42501';
  end if;

  if not exists (
    select 1
    from public.workspace_members workspace_member
    where workspace_member.ws_id = p_ws_id
      and workspace_member.user_id = auth.uid()
  ) then
    raise exception 'permission_denied' using errcode = '42501';
  end if;

  if not public.has_workspace_permission(
    p_ws_id,
    auth.uid(),
    'manage_workspace_audit_logs'
  ) then
    raise exception 'permission_denied' using errcode = '42501';
  end if;
end;
$$;

revoke execute on function public.authorize_workspace_sensitive_rpc(uuid) from public;
revoke execute on function public.authorize_workspace_sensitive_rpc(uuid) from anon;
revoke execute on function public.authorize_workspace_sensitive_rpc(uuid) from authenticated;
```

### Pattern 10: API-Only Workspace Tables

**Use Case:** The `apps/web` API performs stricter permission checks than a
plain workspace membership policy can express safely, then reads or writes with
`createAdminClient()`.

For these tables, do not grant `anon` or `authenticated` direct Data API access
and do not leave member-only RLS policies in place. A browser or REST client can
call exposed Supabase tables directly with the publishable key, bypassing route
checks such as `manage_users` or `send_user_group_post_emails`.

Required controls:

* Revoke table privileges from `public`, `anon`, and `authenticated`.
* Keep table access behind service-role API routes that perform the workspace
  permission check first.
* Keep service-role grants explicit. The proxy route is the public contract; the
  table is not a browser, mobile, REST, or GraphQL contract.
* Drop permissive member-only RLS policies on the underlying tables; use
  service-role-only policies when an explicit policy is useful for review.
* Add the tables to `PROXY_ONLY_PUBLIC_TABLES` in
  `packages/supabase/src/next/protected-tables.ts` so deprecated direct clients
  fail loudly during app development.
* Revoke direct `EXECUTE` from exposed helper RPCs unless the function performs
  its own caller authorization.

The migration `20260522172925_harden_proxy_only_public_tables.sql` applies this
transition guardrail to the current `PROXY_ONLY_PUBLIC_TABLES` set and also
revokes automatic grants for future `public` tables, functions, and sequences.
New migrations that intentionally expose a public Data API surface must now add
the matching explicit `GRANT` statements in the same migration.

```sql theme={null}
revoke all privileges on table public.sensitive_workspace_table
from public, anon, authenticated;

drop policy if exists "Allow workspace members to manage sensitive workspace table"
  on public.sensitive_workspace_table;

create policy "Allow service role to manage sensitive workspace table"
  on public.sensitive_workspace_table
  for all
  to service_role
  using (true)
  with check (true);
```

### Pattern 11: Private Schema Server-Owned Tables

**Use Case:** A table, helper function, or protected query surface is only
needed by cron jobs, service-role routes, Tuturuuu API routes, or database
internals and should not be exposed through Supabase's generated REST API at
all.

Default new protected database access to the existing `private` schema unless
the data is intentionally public. Do not add `private` to the Supabase Data API
exposed schemas or extra search path. New migrations should prefer direct
server-owned access from `apps/web`: call private RPCs through the server-side
Supabase admin client with `schema('private').rpc(...)`, and use
`getPlatformSql()` only for private table access that is not modeled as an RPC.
This keeps browser and mobile consumers on centralized `apps/web` API routes
while avoiding new Supabase REST endpoints for private data.

Legacy `public` bridging RPCs may exist while older code is migrated, but do
not add new public RPCs for tables or protected helper queries that can be
reached through the server-side database connection.

If a public table has no app/package consumers and is not part of an active
database contract, prefer dropping it in a forward migration instead of moving
dead schema surface into `private`.

Notification delivery queue internals follow this pattern:
`private.notification_batches` and `private.notification_delivery_log` are
processed only by the server-owned batch cron, immediate-send route, and
service-role notification helper functions.

Required controls:

* Keep `anon` and `authenticated` without `USAGE` on `private`.
* Revoke direct table privileges from `public`, `anon`, and `authenticated`.
* Keep RLS enabled with service-role-only policies for reviewability.
* Keep private table reads and writes inside server-only modules used by
  `apps/web` routes, server actions, or server components.
* Cover private placement, table privileges, and schema usage with pgTAP tests.

```sql theme={null}
create schema if not exists private;

revoke all on schema private from public, anon, authenticated;
grant usage on schema private to service_role;

alter table if exists public.server_owned_table
  set schema private;

revoke all on table private.server_owned_table
from public, anon, authenticated;

alter table private.server_owned_table enable row level security;

create policy "Service role can manage server-owned table"
  on private.server_owned_table
  for all
  to service_role
  using (true)
  with check (true);
```

## Common RLS Helpers

### Get User Workspaces

```sql theme={null}
CREATE FUNCTION get_user_workspaces(user_uuid uuid)
RETURNS TABLE(ws_id text) AS $$
  SELECT ws_id
  FROM workspace_members
  WHERE user_id = user_uuid
    AND pending = false;
$$ LANGUAGE sql SECURITY DEFINER;
```

### Check Workspace Permission

The deployed helper is `public.has_workspace_permission(p_ws_id, p_user_id, p_permission)`.
The workspace id comes first, the user id second, and the permission is passed as
`text` (cast inside the function to `workspace_role_permission`). It checks both
role-based grants (`workspace_role_members` → `workspace_role_permissions`) and
workspace-wide default permissions (`workspace_default_permissions`), and only
counts rows where `enabled = true`. Match this signature when calling it from
policies or RPCs (see Pattern 9).

```sql theme={null}
-- Mirrors apps/database/.../add_has_workspace_permission.sql
CREATE OR REPLACE FUNCTION public.has_workspace_permission(
  p_ws_id uuid,
  p_user_id uuid,
  p_permission text
)
RETURNS boolean
LANGUAGE plpgsql
SECURITY DEFINER
STABLE
AS $$
BEGIN
  RETURN EXISTS (
    -- Role-based grant
    SELECT 1
    FROM workspace_role_members wrm
    JOIN workspace_role_permissions wrp
      ON wrp.role_id = wrm.role_id
      AND wrp.ws_id = p_ws_id
    WHERE wrm.user_id = p_user_id
      AND wrp.permission = p_permission::public.workspace_role_permission
      AND wrp.enabled = true

    UNION

    -- Workspace-wide default grant
    SELECT 1
    FROM workspace_default_permissions wdp
    WHERE wdp.ws_id = p_ws_id
      AND wdp.permission = p_permission::public.workspace_role_permission
      AND wdp.enabled = true
  );
END;
$$;
```

<Note>
  Call it as `public.has_workspace_permission(ws_id, auth.uid(), 'manage_projects')`.
  Argument order matters: `(p_ws_id, p_user_id, p_permission)`. Passing the user
  id and workspace id in the wrong order silently checks the wrong workspace.
</Note>

## Policy Testing

### Enable RLS (Always Required)

```sql theme={null}
ALTER TABLE table_name ENABLE ROW LEVEL SECURITY;
```

### Test Policy as User

```sql theme={null}
-- Impersonate user for testing
SET request.jwt.claim.sub = 'user-uuid-here';

-- Run queries to verify policy
SELECT * FROM workspace_tasks WHERE ws_id = 'workspace-123';

-- Reset
RESET request.jwt.claim.sub;
```

### Verify Policy Coverage

```sql theme={null}
-- Check if all tables have RLS enabled
SELECT tablename
FROM pg_tables
WHERE schemaname = 'public'
  AND tablename NOT IN (
    SELECT tablename
    FROM pg_tables t
    JOIN pg_class c ON c.relname = t.tablename
    WHERE c.relrowsecurity = true
  );
```

## Security Best Practices

### 1. Always Enable RLS

```sql theme={null}
-- ✅ Good
CREATE TABLE my_table (...);
ALTER TABLE my_table ENABLE ROW LEVEL SECURITY;

-- ❌ Bad
CREATE TABLE my_table (...);
-- Forgot to enable RLS!
```

### 2. Use SECURITY DEFINER Carefully

Only use `SECURITY DEFINER` for helper functions that need elevated privileges:

```sql theme={null}
-- ✅ Good: Helper needs admin access
CREATE FUNCTION admin_helper() ... SECURITY DEFINER;

-- ❌ Bad: Bypasses RLS unnecessarily
CREATE FUNCTION simple_query() ... SECURITY DEFINER;
```

### 3. Test Policies Thoroughly

Always test:

* ✅ Users can access their own data
* ✅ Users cannot access other workspaces' data
* ✅ Permission checks work correctly
* ✅ Edge cases (pending invites, disabled users)

### 4. Avoid Policy Conflicts

```sql theme={null}
-- ❌ Bad: Multiple policies may conflict
CREATE POLICY "policy_1" ON table FOR SELECT USING (...);
CREATE POLICY "policy_2" ON table FOR SELECT USING (...);
-- Which one applies?

-- ✅ Good: One comprehensive policy per operation
CREATE POLICY "select_policy" ON table FOR SELECT USING (
  condition_1 OR condition_2
);
```

### 5. Performance Considerations

```sql theme={null}
-- ❌ Bad: Subquery runs for every row
CREATE POLICY "slow_policy" ON table FOR SELECT USING (
  column IN (SELECT id FROM expensive_query)
);

-- ✅ Good: Use indexed foreign keys
CREATE POLICY "fast_policy" ON table FOR SELECT USING (
  ws_id = (SELECT ws_id FROM workspace_members WHERE user_id = auth.uid() LIMIT 1)
);
```

## Common Policy Patterns by Table Type

### Workspace-Scoped Resources

```sql theme={null}
ALTER TABLE resource ENABLE ROW LEVEL SECURITY;

CREATE POLICY "workspace_members_can_view"
ON resource FOR SELECT
USING (ws_id IN (SELECT ws_id FROM workspace_members WHERE user_id = auth.uid()));

CREATE POLICY "permission_required_to_modify"
ON resource FOR ALL
USING (
  EXISTS (
    SELECT 1 FROM workspace_members wm
    WHERE wm.ws_id = resource.ws_id
      AND wm.user_id = (select auth.uid())
      AND wm.type = 'MEMBER'
  )
  AND public.has_workspace_permission(
    resource.ws_id,
    (select auth.uid()),
    'manage_projects'
  )
)
WITH CHECK (
  EXISTS (
    SELECT 1 FROM workspace_members wm
    WHERE wm.ws_id = resource.ws_id
      AND wm.user_id = (select auth.uid())
      AND wm.type = 'MEMBER'
  )
  AND public.has_workspace_permission(
    resource.ws_id,
    (select auth.uid()),
    'manage_projects'
  )
);
```

### User-Owned Resources

```sql theme={null}
ALTER TABLE user_resource ENABLE ROW LEVEL SECURITY;

CREATE POLICY "users_can_manage_own"
ON user_resource FOR ALL
USING (user_id = auth.uid());
```

### Public Read Resources

```sql theme={null}
ALTER TABLE public_resource ENABLE ROW LEVEL SECURITY;

CREATE POLICY "anyone_can_read"
ON public_resource FOR SELECT
USING (true);

CREATE POLICY "admin_can_write"
ON public_resource FOR ALL
USING (
  EXISTS (
    SELECT 1 FROM workspace_members wm
    WHERE wm.ws_id = public_resource.ws_id
      AND wm.user_id = (select auth.uid())
      AND wm.type = 'MEMBER'
  )
  AND public.has_workspace_permission(
    public_resource.ws_id,
    (select auth.uid()),
    'manage_workspace_settings'
  )
)
WITH CHECK (
  EXISTS (
    SELECT 1 FROM workspace_members wm
    WHERE wm.ws_id = public_resource.ws_id
      AND wm.user_id = (select auth.uid())
      AND wm.type = 'MEMBER'
  )
  AND public.has_workspace_permission(
    public_resource.ws_id,
    (select auth.uid()),
    'manage_workspace_settings'
  )
);
```

## Debugging RLS Issues

### Check Active Policies

```sql theme={null}
SELECT schemaname, tablename, policyname, permissive, roles, cmd, qual
FROM pg_policies
WHERE tablename = 'your_table_name';
```

### Test as Specific User

```sql theme={null}
-- In Supabase SQL Editor
SELECT set_config('request.jwt.claim.sub', 'user-uuid', false);
SELECT * FROM workspace_tasks; -- Runs with RLS as that user
```

### Bypass RLS for Admin Operations

Use `createAdminClient()` from `@tuturuuu/supabase` in server-side code:

```typescript theme={null}
import { createAdminClient } from '@tuturuuu/supabase/next/server';

const sbAdmin = createAdminClient(); // synchronous - do not await
// This client bypasses RLS - use carefully!
```

Always name `createAdminClient()` locals `sbAdmin`, not `supabase`, so service-role access is visually distinct from request-scoped clients during review.

## Migration Example

When adding a new table, always include RLS:

```sql theme={null}
-- Create table
CREATE TABLE new_feature (
  id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
  ws_id uuid REFERENCES workspaces(id) ON DELETE CASCADE,
  name text NOT NULL,
  created_by uuid REFERENCES workspace_users(id),
  created_at timestamptz DEFAULT now()
);

-- Enable RLS
ALTER TABLE new_feature ENABLE ROW LEVEL SECURITY;

-- Add policies
CREATE POLICY "workspace_members_can_view"
ON new_feature FOR SELECT
USING (ws_id IN (
  SELECT ws_id FROM workspace_members
  WHERE user_id = (select auth.uid())
    AND type = 'MEMBER'
));

CREATE POLICY "permission_required_to_modify"
ON new_feature FOR ALL
USING (
  EXISTS (
    SELECT 1 FROM workspace_members wm
    WHERE wm.ws_id = new_feature.ws_id
      AND wm.user_id = (select auth.uid())
      AND wm.type = 'MEMBER'
  )
  AND public.has_workspace_permission(
    new_feature.ws_id,
    (select auth.uid()),
    'manage_projects'
  )
)
WITH CHECK (
  EXISTS (
    SELECT 1 FROM workspace_members wm
    WHERE wm.ws_id = new_feature.ws_id
      AND wm.user_id = (select auth.uid())
      AND wm.type = 'MEMBER'
  )
  AND public.has_workspace_permission(
    new_feature.ws_id,
    (select auth.uid()),
    'manage_projects'
  )
);

-- Add indexes for policy performance
CREATE INDEX idx_new_feature_ws_id ON new_feature(ws_id);
CREATE INDEX idx_new_feature_created_by ON new_feature(created_by);
```

## Privilege Grants vs RLS Scope

RLS policies only apply after SQL privileges have already allowed the role to
touch a table. For sensitive workspace configuration tables, avoid granting
`insert`, `update`, or `delete` to the broad `authenticated` role when the
matching RLS policies only check workspace membership.

Keep `authenticated` grants read-only unless the table policy itself enforces
the same granular permission that the application route requires. Route
privileged writes through permission-gated API handlers using elevated
service-role access.

## Related Documentation

* [Database Schema Overview](/reference/database/schema-overview)
* [Permission System](/platform/architecture/authorization)
* [Supabase Client Usage](/reference/packages/supabase)


# Database Schema Overview
Source: https://docs.tuturuuu.com/reference/database/schema-overview

Complete reference for the Tuturuuu platform database schema

The Tuturuuu platform uses Supabase (PostgreSQL) with a comprehensive multi-tenant architecture. This document provides an overview of the database schema, organized by domain.

## Core Architecture

### Multi-Tenancy Model

The database implements **workspace-based multi-tenancy** where:

* Each workspace is isolated via Row-Level Security (RLS) policies
* Users can belong to multiple workspaces
* Resources are scoped to workspaces using `ws_id` foreign keys
* Permissions are managed through workspace roles and granular permissions

### Key Design Principles

1. **Security First**: All tables have RLS policies enforcing workspace isolation
2. **Audit Trails**: Many tables include `created_at` and `updated_at` timestamps
3. **Soft Deletes**: Critical tables support soft deletion patterns
4. **Hierarchical Structures**: Support for nested organizational structures (tasks, calendars, etc.)

### Private Schema Operations

Private tables and RPCs used by `apps/web` are exposed to server-side Supabase
clients through PostgREST's configured private schema. After production
migrations add private tables, RPC signatures, or columns that the app reads
through `.schema('private')`, reload the PostgREST schema cache:

```sql theme={null}
notify pgrst, 'reload schema';
```

Local Supabase restarts usually refresh this cache automatically, so stale-cache
failures can appear only in production after otherwise successful migrations.

## Schema Domains

### User & Workspace Management

#### `workspace_users`

Primary user table with workspace association.

**Key Fields:**

* `id` (uuid, PK)
* `display_name` (text)
* `email` (text)
* `phone` (text)
* `avatar_url` (text)

#### `workspaces`

Workspace container for multi-tenant organization.

**Key Fields:**

* `id` (text, PK)
* `name` (text)
* `logo_url` (text)
* `created_at` (timestamptz)

#### `workspace_members`

Links users to workspaces with roles.

**Key Fields:**

* `id` (uuid, PK)
* `ws_id` (text, FK → workspaces)
* `user_id` (uuid, FK → workspace\_users)
* `role` (text)
* `pending` (boolean) - invitation status

#### `workspace_role_permissions`

Granular permission system for workspace roles.

**Key Fields:**

* `ws_id` (text, FK → workspaces)
* `role_id` (text)
* `permission` (workspace\_role\_permission enum)
* `created_at` (timestamptz)

**Available Permissions:**

<Warning>
  The `workspace_role_permission` enum is large (100+ values) and evolves
  frequently as new product surfaces ship. The generated TypeScript union is the
  single source of truth — do **not** hand-copy permission names from this page
  into RLS policies, role seeds, or app code. Read the live union instead:

  ```typescript theme={null}
  import type { Database } from '@tuturuuu/types';

  type WorkspacePermission =
    Database['public']['Enums']['workspace_role_permission'];
  ```

  In SQL, the canonical definition lives in the `workspace_role_permission` enum
  type (defined by the migrations under `apps/database/supabase/migrations/`).
</Warning>

The values below are a representative snapshot grouped by domain (accurate as of
this page's `updatedAt`, but treat the generated type as authoritative):

* **Workspace administration**: `manage_workspace_settings`,
  `manage_workspace_roles`, `manage_workspace_members`,
  `manage_workspace_security`, `manage_workspace_integrations`,
  `manage_workspace_billing`, `manage_workspace_audit_logs`,
  `manage_workspace_secrets`, `manage_subscription`, `manage_api_keys`,
  `manage_e2ee`, `admin`
* **Infrastructure**: `view_infrastructure`, `manage_external_migrations`,
  `manage_infrastructure_stress_tests`, `manage_mobile_deployment_vault`
* **Users & groups**: `manage_users`, `create_users`, `update_users`,
  `delete_users`, `export_users_data`, `view_users_public_info`,
  `view_users_private_info`, `view_user_groups`, `create_user_groups`,
  `update_user_groups`, `delete_user_groups`, `send_user_group_post_emails`,
  `manage_user_report_templates`, `manage_user_profile_links`
* **Finance**: `manage_finance`, `export_finance_data`, `view_finance_stats`,
  `view_transactions`, `create_transactions`, `update_transactions`,
  `delete_transactions`, `view_invoices`, `view_expenses`, `view_incomes`,
  `create_wallets`, `update_wallets`, `delete_wallets`, `change_finance_wallets`,
  `view_confidential_amount`, `view_confidential_description`
* **Inventory**: `manage_inventory`, `view_inventory`, `create_inventory`,
  `update_inventory`, `delete_inventory`, `view_inventory_catalog`,
  `manage_inventory_catalog`, `view_inventory_stock`, `adjust_inventory_stock`,
  `view_inventory_sales`, `view_inventory_analytics`
* **AI**: `ai_chat`, `ai_lab`
* **Chat**: `view_chat`, `create_chat`, `manage_chat`, `moderate_chat`
* **Projects, docs & drive**: `manage_projects`, `manage_documents`,
  `manage_drive`, `view_drive`, `manage_drive_tasks_directory`,
  `manage_external_projects`, `publish_external_projects`
* **Calendar & time tracking**: `manage_calendar`,
  `manage_time_tracking_requests`, `bypass_time_tracking_request_approval`
* **Workforce & payroll**: `manage_workforce`, `view_workforce`,
  `manage_payroll`, `view_payroll`, `check_user_attendance`,
  `update_user_attendance`
* **Forms & changelog**: `manage_forms`, `view_form_analytics`,
  `manage_changelog`

The previously documented permissions `manage_infrastructure_settings`,
`ai_lab_assistant`, `manage_user_groups`, `manage_user_roles`,
`manage_external_users`, `view_disabled_users`, and `disable_user` have been
**removed or renamed** in the current enum — do not reference them in new policies.

### Authentication & Credential Handoffs

#### `private.cross_app_tokens`

Private short-lived tokens for cross-app authentication handoffs. Client and
satellite apps should use the existing public RPC helpers or central
`apps/web` verification route; do not read or write the table through public
Supabase REST access.

**Key Fields:**

* `id` (uuid, PK)
* `user_id` (uuid, FK → users)
* `token` (text, unique)
* `origin_app` (text)
* `target_app` (text)
* `expires_at` (timestamptz)
* `used_at` (timestamptz)
* `session_data` (jsonb)

#### `private.internal_email_api_keys`

Private API credentials for the internal mail send route. The
`apps/web` route reads these keys with the server-side admin client and keeps
credential validation behind the application proxy.

**Key Fields:**

* `id` (uuid, PK)
* `creator_id` (uuid, FK → users)
* `user_id` (uuid, FK → users)
* `value` (text)
* `allowed_emails` (text\[])
* `created_at` (timestamptz)

### Notification Delivery Internals

#### `private.notification_batches`

Private operational queue rows for email and push notification delivery.
Server-owned `apps/web` cron and immediate-send routes read and update these
rows through the service-role client; browser, mobile, and satellite apps should
not query them directly.

**Key Fields:**

* `id` (uuid, PK)
* `ws_id` (uuid, FK → workspaces, nullable for pending-email flows)
* `user_id` (uuid, FK → users, nullable for pending-email flows)
* `email` (text)
* `channel` (text)
* `delivery_mode` (notification\_delivery\_mode)
* `status` (text)
* `window_start` / `window_end` (timestamptz)

#### `private.notification_delivery_log`

Private delivery-attempt records linked to persisted notifications and optional
batches. The table is intentionally excluded from public Data API and Realtime
access; inspect or mutate it through centralized notification APIs only.

**Key Fields:**

* `id` (uuid, PK)
* `notification_id` (uuid, FK → notifications)
* `batch_id` (uuid, FK → private.notification\_batches)
* `channel` (text)
* `status` (text)
* `retry_count` (integer)
* `sent_at` (timestamptz)

### Task Management Hierarchy

The platform implements a 6-level hierarchical task management system:

```
Workspaces (top-level)
└── Task Initiatives (strategic grouping)
    └── Task Projects (cross-board coordination)
        └── Workspace Boards (kanban boards)
            └── Task Lists (columns)
                └── Workspace Tasks (work items)
```

#### `notes`

Unstructured notes that can be converted to tasks or projects (Bucket Dump feature).

**Key Fields:**

* `id` (uuid, PK)
* `ws_id` (text, FK → workspaces)
* `title` (text)
* `content` (text)
* `created_by` (uuid, FK → workspace\_users)

#### `task_initiatives`

Strategic initiatives grouping multiple projects.

**Key Fields:**

* `id` (text, PK)
* `ws_id` (text, FK → workspaces)
* `name` (text)
* `description` (text)
* `start_date` (date)
* `end_date` (date)

#### `task_projects`

Cross-functional projects coordinating tasks across boards.

**Key Fields:**

* `id` (text, PK)
* `ws_id` (text, FK → workspaces)
* `name` (text)
* `description` (text)

**Relationships:**

* `task_project_initiatives` - links projects to initiatives
* `task_project_tasks` - links tasks to projects

#### `workspace_boards`

Kanban-style task boards.

**Key Fields:**

* `id` (uuid, PK)
* `ws_id` (text, FK → workspaces)
* `name` (text)
* `description` (text)
* `created_at` (timestamptz)

#### `task_lists`

Columns within boards (e.g., "To Do", "In Progress", "Done").

**Key Fields:**

* `id` (text, PK)
* `board_id` (uuid, FK → workspace\_boards)
* `name` (text)
* `position` (integer) - display order

#### `workspace_tasks`

Individual work items.

**Key Fields:**

* `id` (text, PK)
* `ws_id` (text, FK → workspaces)
* `list_id` (text, FK → task\_lists)
* `name` (text)
* `description` (text)
* `priority` (integer)
* `completed` (boolean)
* `start_date` (date)
* `due_date` (date)
* `created_by` (uuid, FK → workspace\_users)

**Related Tables:**

* `task_cycles` - sprint/iteration grouping
* `task_labels` - categorization tags
* `task_estimates` - effort estimation (fibonacci, exponential, linear, t-shirt)
* `task_statuses` - custom status definitions per board

### AI Features

#### `private.ai_providers`

Legacy supported AI providers retained for historical foreign-key compatibility.
Active model catalog APIs should use `private.ai_gateway_models` through centralized
`apps/web` routes instead of Supabase REST/PostgREST.

**Key Fields:**

* `id` (text, PK)
* `name` (text)
* `created_at` (timestamptz)

#### `private.ai_models`

Legacy AI models per provider retained for historical foreign-key compatibility.
Active model catalog APIs should use `private.ai_gateway_models` through centralized
`apps/web` routes instead of Supabase REST/PostgREST.

**Key Fields:**

* `id` (text, PK)
* `provider` (text, FK → private.ai\_providers)
* `name` (text)
* `enabled` (boolean)

#### `ai_chats`

Persistent chat sessions.

**Key Fields:**

* `id` (uuid, PK)
* `title` (text)
* `model` (text) - free-text AI Gateway model id in `provider/model` form
  (e.g. `google/gemini-2.5-flash`). No longer a foreign key — the legacy
  `ai_chats.model → private.ai_models` constraint was dropped, and
  `private.ai_gateway_models` is now the single source of truth for the active
  model catalog.
* `creator_id` (uuid, FK → workspace\_users)

#### `ai_chat_messages`

Individual messages within chat sessions.

**Key Fields:**

* `id` (uuid, PK)
* `chat_id` (uuid, FK → ai\_chats)
* `role` (text) - user, assistant, system
* `content` (text)
* `created_at` (timestamptz)

#### `workspace_ai_executions`

Token usage tracking for billing.

**Key Fields:**

* `id` (uuid, PK)
* `ws_id` (text, FK → workspaces)
* `model_id` (text, FK → private.ai\_models) - retains the legacy `ai_models`
  reference for historical executions; the active model catalog now lives in
  `private.ai_gateway_models`, and pricing helpers map identifiers accordingly
* `input_tokens` (integer)
* `output_tokens` (integer)
* `total_tokens` (integer)

#### `private.ai_whitelisted_emails`

Server-owned email whitelist for AI feature access. This table is kept outside
the Supabase REST-exposed `public` schema; apps should check or manage access
through centralized `apps/web` APIs.

### Private Reference Tables

#### `private.currencies`

Finance reference data retained for foreign-key compatibility with
`private.workspace_wallets` and `currency_exchange_rates`. Runtime consumers should use
centralized app APIs or package currency constants instead of Supabase REST.

#### `private.field_types`

Workspace user-field reference data retained for historical foreign keys.
Management should go through centralized app APIs instead of direct public table
access.

#### `private.healthcare_diagnoses`

Legacy healthcare diagnosis records retained for historical checkup foreign keys.
Server-side helpers own access; the public count RPC is restricted to
`service_role` and reads from the private schema.

#### `private.personal_notes`

Legacy per-user notes retained for historical compatibility. Active personal
task-note behavior should stay behind centralized app flows instead of Supabase
REST table access.

#### `private.team_members`

Legacy team membership data retained for historical foreign-key compatibility.
Active membership flows should use workspace or Nova team tables.

#### `private.timezones`

Timezone synchronization records for infrastructure management. The dashboard
continues to source canonical timezone data from package constants and reaches
stored records only through `apps/web` APIs.

### Calendar System

#### `workspace_calendar_events`

Calendar events with Google Calendar sync support.

**Key Fields:**

* `id` (uuid, PK)
* `ws_id` (text, FK → workspaces)
* `title` (text)
* `description` (text)
* `start_at` (timestamptz)
* `end_at` (timestamptz)
* `location` (text)
* `google_event_id` (text) - for sync
* `creator_id` (uuid, FK → workspace\_users)

#### `private.calendar_event_participants`

Legacy event-attendee projection retained for historical compatibility and
service-role workflows. Current application code does not query this legacy
participant model directly.

**Key Fields:**

* `event_id` (uuid, FK → workspace\_calendar\_events)
* `participant_id` (uuid, FK → users, workspace\_users, or workspace\_user\_groups)
* `going` (boolean, nullable for participant groups)

#### `calendar_sync_states`

Tracks synchronization state with Google Calendar.

**Key Fields:**

* `ws_id` (text, PK, FK → workspaces)
* `sync_token` (text) - Google sync token
* `last_synced_at` (timestamptz)
* `is_syncing` (boolean) - prevents concurrent syncs

#### `calendar_auth_tokens`

OAuth tokens for Google Calendar integration.

**Key Fields:**

* `user_id` (uuid, PK, FK → workspace\_users)
* `access_token` (text, encrypted)
* `refresh_token` (text, encrypted)
* `expires_at` (timestamptz)

#### `private.workspace_calendar_sync_log`

Private operational audit trail for calendar sync jobs. Access this table
through service-role infrastructure routes instead of Supabase REST table
access.

**Key Fields:**

* `id` (uuid, PK)
* `ws_id` (uuid, FK → workspaces)
* `google_account_email` (text)
* `sync_started_at` (timestamptz)
* `sync_ended_at` (timestamptz)
* `status` (text) - success, failed, in\_progress, cancelled, partial\_success
* `error_message` (text)
* `event_snapshot_before` (jsonb)

### Finance Management

#### `private.workspace_wallets`

Primary wallet for workspace financial tracking. Wallet rows are owned by
server-side finance APIs that verify workspace permissions before using
service-role private schema access.

**Key Fields:**

* `id` (uuid, PK)
* `ws_id` (text, FK → workspaces)
* `name` (text)
* `balance` (numeric)
* `currency` (text)

#### `credit_wallets`

Credit-based wallet system.

**Key Fields:**

* `id` (uuid, PK)
* `ws_id` (text, FK → workspaces)
* `balance` (numeric) - credit amount
* `currency` (text)

#### `wallet_transactions`

Financial transaction history.

**Key Fields:**

* `id` (uuid, PK)
* `wallet_id` (uuid, FK → private.workspace\_wallets)
* `amount` (numeric)
* `description` (text)
* `type` (text) - income, expense, transfer
* `category_id` (uuid, FK → transaction\_categories)
* `created_at` (timestamptz)

#### `workspace_role_wallet_whitelist`

Role-based wallet access control with time-bounded viewing windows.

**Purpose:** Controls which workspace roles can access specific wallets and defines the historical data viewing window for each role-wallet pairing.

**Key Fields:**

* `id` (uuid, PK)
* `role_id` (uuid, FK → workspace\_roles) - the role granted access
* `wallet_id` (uuid, FK → private.workspace\_wallets) - the wallet being accessed
* `viewing_window` (text) - allowed values: `1_day`, `3_days`, `7_days`, `2_weeks`, `1_month`, `1_quarter`, `1_year`, `custom`
* `custom_days` (integer) - required when `viewing_window = 'custom'`; must be > 0; must be NULL otherwise
* `created_at` (timestamptz)

**Constraints:**

* Unique constraint on `(role_id, wallet_id)` - one whitelist entry per role-wallet pair
* CHECK constraint on `viewing_window` - enforces allowed literal values
* CHECK constraint on `custom_days` - ensures presence/positivity when `viewing_window = 'custom'` and NULL otherwise

**Access Control:**

* RLS policies restrict access to users with `manage_workspace_roles` permission
* INSERT policy validates wallet belongs to the same workspace as the role
* UPDATE policy enforces wallet-workspace consistency via WITH CHECK clause

### Meeting Management

#### `meeting_plans`

Scheduled meetings with metadata.

**Key Fields:**

* `id` (uuid, PK)
* `ws_id` (text, FK → workspaces)
* `title` (text)
* `description` (text)
* `start_time` (timestamptz)
* `end_time` (timestamptz)

#### `meeting_plan_timeblocks`

Time allocations within meetings.

**Key Fields:**

* `id` (uuid, PK)
* `meeting_id` (uuid, FK → meeting\_plans)
* `title` (text)
* `duration` (integer) - minutes
* `position` (integer)

#### `meeting_guest_accounts`

External participant management.

**Key Fields:**

* `id` (uuid, PK)
* `email` (text)
* `display_name` (text)
* `ws_id` (text, FK → workspaces)

#### `meeting_recordings`

Meeting transcription and recording storage.

**Key Fields:**

* `id` (uuid, PK)
* `meeting_id` (uuid, FK → meeting\_plans)
* `transcription` (text)
* `summary` (text) - AI-generated
* `recording_url` (text)

### Nova Platform (Prompt Engineering)

#### `nova_problems`

Prompt engineering challenge problems.

**Key Fields:**

* `id` (uuid, PK)
* `title` (text)
* `description` (text)
* `difficulty` (text) - easy, medium, hard
* `created_by` (uuid, FK → workspace\_users)

#### `nova_challenges`

Specific challenge instances.

**Key Fields:**

* `id` (uuid, PK)
* `problem_id` (uuid, FK → nova\_problems)
* `title` (text)
* `start_time` (timestamptz)
* `end_time` (timestamptz)

#### `nova_test_cases`

Test cases for validating prompt submissions.

**Key Fields:**

* `id` (uuid, PK)
* `problem_id` (uuid, FK → nova\_problems)
* `input` (jsonb)
* `expected_output` (jsonb)
* `is_hidden` (boolean) - public vs private tests

#### `nova_submissions`

User prompt submissions.

**Key Fields:**

* `id` (uuid, PK)
* `challenge_id` (uuid, FK → nova\_challenges)
* `user_id` (uuid, FK → workspace\_users)
* `prompt` (text)
* `score` (numeric)
* `submitted_at` (timestamptz)

#### `nova_sessions`

Active problem-solving sessions.

**Key Fields:**

* `id` (uuid, PK)
* `user_id` (uuid, FK → workspace\_users)
* `problem_id` (uuid, FK → nova\_problems)
* `started_at` (timestamptz)
* `completed_at` (timestamptz)

### Education System

#### `courses`

Educational course catalog.

**Key Fields:**

* `id` (uuid, PK)
* `ws_id` (text, FK → workspaces)
* `title` (text)
* `description` (text)
* `instructor_id` (uuid, FK → workspace\_users)

#### `course_modules`

Course content structure.

**Key Fields:**

* `id` (uuid, PK)
* `course_id` (uuid, FK → courses)
* `title` (text)
* `content` (text)
* `position` (integer)

#### `course_module_completion_status`

Student progress tracking.

**Key Fields:**

* `user_id` (uuid, FK → workspace\_users)
* `module_id` (uuid, FK → course\_modules)
* `completed_at` (timestamptz)

#### `course_certificates`

Achievement certificates.

**Key Fields:**

* `id` (uuid, PK)
* `user_id` (uuid, FK → workspace\_users)
* `course_id` (uuid, FK → courses)
* `template` (text) - elegant, modern, original
* `issued_at` (timestamptz)

#### `quiz_sets`

Quiz collections.

**Key Fields:**

* `id` (uuid, PK)
* `ws_id` (text, FK → workspaces)
* `title` (text)
* `questions` (jsonb)

#### `quiz_attempts`

User quiz submissions.

**Key Fields:**

* `id` (uuid, PK)
* `quiz_id` (uuid, FK → quiz\_sets)
* `user_id` (uuid, FK → workspace\_users)
* `score` (numeric)
* `answers` (jsonb)
* `completed_at` (timestamptz)

#### `flashcard_sets`

Flashcard study materials.

**Key Fields:**

* `id` (uuid, PK)
* `ws_id` (text, FK → workspaces)
* `title` (text)
* `cards` (jsonb) - array of `{front, back}`

### Time Tracking

#### `time_tracking_sessions`

Hierarchical time tracking with daily structure.

**Key Fields:**

* `id` (uuid, PK)
* `ws_id` (text, FK → workspaces)
* `user_id` (uuid, FK → workspace\_users)
* `task_id` (text, FK → workspace\_tasks)
* `start_time` (timestamptz)
* `end_time` (timestamptz)
* `duration` (integer) - seconds
* `date` (date) - for daily hierarchy

**Related Tables:**

* `workspace_calendar_hour_settings` - categorizes hours (work, meeting, personal)

### URL Shortener

#### `shortened_links`

Short URL mappings.

**Key Fields:**

* `id` (uuid, PK)
* `ws_id` (text, FK → workspaces)
* `short_code` (text, unique)
* `original_url` (text)
* `created_by` (uuid, FK → workspace\_users)
* `expires_at` (timestamptz)

#### `shortened_link_analytics`

Click tracking.

**Key Fields:**

* `id` (uuid, PK)
* `link_id` (uuid, FK → shortened\_links)
* `clicked_at` (timestamptz)
* `ip_address` (inet)
* `user_agent` (text)
* `referrer` (text)

### Subscriptions & Billing

#### `workspace_subscriptions`

Workspace subscription status.

**Key Fields:**

* `ws_id` (text, PK, FK → workspaces)
* `product_id` (text, FK → private.workspace\_subscription\_products)
* `status` (text) - active, canceled, expired
* `started_at` (timestamptz)
* `expires_at` (timestamptz)

#### `private.workspace_subscription_products`

Private subscription tiers managed through billing and Polar server helpers.

**Key Fields:**

* `id` (text, PK)
* `name` (text)
* `price` (numeric)
* `currency` (text)
* `features` (jsonb)

#### `private.workspace_subscription_errors`

Private subscription failure state used by billing overview RPCs and
service-role repair helpers.

**Key Fields:**

* `id` (uuid, PK)
* `ws_id` (uuid, FK → workspaces)
* `error_message` (text)
* `error_source` (text)
* `created_at` (timestamptz)
* `resolved_at` (timestamptz)

### Additional Features

#### `user_referrals`

Referral tracking system (added September 2025).

**Key Fields:**

* `id` (uuid, PK)
* `referrer_id` (uuid, FK → workspace\_users)
* `referred_id` (uuid, FK → workspace\_users)
* `created_at` (timestamptz)

#### `whiteboards`

Real-time collaborative whiteboard (added June 2025).

**Key Fields:**

* `id` (uuid, PK)
* `ws_id` (text, FK → workspaces)
* `title` (text)
* `content` (jsonb) - whiteboard state

#### `support_inquiries`

Support ticket system.

**Key Fields:**

* `id` (uuid, PK)
* `type` (text) - bug, feature-request, job-application, support
* `subject` (text)
* `description` (text)
* `status` (text) - open, in-progress, resolved
* `created_by` (uuid, FK → workspace\_users)

#### `discord_guild_integrations`

Discord server integration metadata.

**Key Fields:**

* `guild_id` (text, PK)
* `ws_id` (text, FK → workspaces)
* `enabled` (boolean)

## Database Functions

The schema includes several PostgreSQL functions for complex operations:

### `atomic_sync_token_operation`

Atomically updates calendar sync tokens to prevent race conditions.

**Usage:** Calendar synchronization coordination

### `get_wallet_viewing_window_days`

Converts viewing window literals to day counts for wallet access control.

**Signature:**

```sql theme={null}
public.get_wallet_viewing_window_days(
  p_viewing_window TEXT,
  p_custom_days INTEGER DEFAULT NULL
) RETURNS INTEGER
```

**Return Type:** INTEGER - number of days in the viewing window

**Semantics:**

* Maps viewing window literals (`1_day`, `3_days`, `7_days`, `2_weeks`, `1_month`, `1_quarter`, `1_year`) to day counts
* For `viewing_window = 'custom'`, returns `p_custom_days` value (defaults to 30 if invalid)
* Defaults to 30 days for unknown `viewing_window` values
* Function is `IMMUTABLE` - safe for indexing and optimization

**Example:**

```sql theme={null}
SELECT public.get_wallet_viewing_window_days('1_month', NULL); -- Returns 30
SELECT public.get_wallet_viewing_window_days('custom', 45);    -- Returns 45
SELECT public.get_wallet_viewing_window_days('1_year', NULL);  -- Returns 365
```

### `user_has_wallet_access_via_role`

Checks if a user has wallet access through role whitelisting and returns viewing window details.

**Signature:**

```sql theme={null}
public.user_has_wallet_access_via_role(
  p_user_id UUID,
  p_wallet_id UUID,
  p_ws_id UUID
) RETURNS TABLE (
  has_access BOOLEAN,
  viewing_window TEXT,
  custom_days INTEGER,
  window_start_date TIMESTAMPTZ
)
```

**Parameters:**

* `p_user_id` - the user to check (caller can only query their own ID unless they are a workspace admin)
* `p_wallet_id` - the wallet to check access for
* `p_ws_id` - the workspace context

**Return Columns:**

* `has_access` - `TRUE` if user has access via any role whitelist, `FALSE` otherwise
* `viewing_window` - the viewing window setting from the whitelist (e.g., `1_month`, `custom`)
* `custom_days` - the custom day count (NULL if not using `custom` window)
* `window_start_date` - calculated start of the viewing window (rolling from current timestamp)

**Security:**

* Function is `SECURITY DEFINER` - runs with elevated privileges
* **Authorization gate:** Callers can only query their own `user_id` OR must be a workspace admin (ADMIN/OWNER role)
* Raises exception `Permission denied` if caller attempts to query another user without admin privileges

**Access Logic:**

* When multiple roles grant access to the same wallet, selects the **widest access window** (most days)
* Tie-breaking: uses highest `custom_days` value, then `id` for deterministic ordering
* Calculates rolling window start date by subtracting window days from current timestamp

**Example Usage:**

```sql theme={null}
-- Check if current user has access to a specific wallet
SELECT * FROM public.user_has_wallet_access_via_role(
  auth.uid(),
  '550e8400-e29b-41d4-a716-446655440000'::uuid,
  'workspace-123'::text
);

-- Admin checking access for another user
SELECT * FROM public.user_has_wallet_access_via_role(
  '123e4567-e89b-12d3-a456-426614174000'::uuid,  -- another user
  '550e8400-e29b-41d4-a716-446655440000'::uuid,  -- wallet
  'workspace-123'::text
);

-- Filter transactions by viewing window
WITH access AS (
  SELECT * FROM public.user_has_wallet_access_via_role(
    auth.uid(),
    '550e8400-e29b-41d4-a716-446655440000'::uuid,
    'workspace-123'::text
  )
)
SELECT t.*
FROM wallet_transactions t
CROSS JOIN access a
WHERE t.wallet_id = '550e8400-e29b-41d4-a716-446655440000'::uuid
  AND a.has_access = TRUE
  AND t.created_at >= a.window_start_date;
```

### User Creation Triggers

Automatically create related records when new users are added.

### Task Board Member Management

Helper functions for managing board access permissions.

### AI Pricing Helpers

Calculate AI model costs based on token usage.

## Migration Management

Migrations are stored in `/apps/database/supabase/migrations/` with timestamp prefixes:

```
20250929042000_add_notes.sql
20250929060000_add_task_cycles.sql
20250911083732_add_task_labels_and_estimates.sql
...
```

See [Migration Guide](/reference/database/migrations-guide) for workflow details.

## Related Documentation

* [RLS Policies](/reference/database/rls-policies) - Security model and policy patterns
* [Migration Guide](/reference/database/migrations-guide) - Migration workflow

## Type Generation

After schema changes, regenerate TypeScript types:

```bash theme={null}
bun sb:typegen
```

Generated types are exported from `@tuturuuu/types`:

```typescript theme={null}
import type { Database } from '@tuturuuu/types';

type Task = Database['public']['Tables']['workspace_tasks']['Row'];
type PrivateConfig = Database['private']['Tables']['notification_email_config']['Row'];
type StorageObject = Database['storage']['Tables']['objects']['Row'];
```


# Reference
Source: https://docs.tuturuuu.com/reference/overview

Authoritative references for APIs and contracts.

# Reference

This section collects stable contracts—APIs, schemas, database internals, and package integration guides.

## Database

* **[Schema Overview](/reference/database/schema-overview)** – Core tables, relationships, and conventions across the Tuturuuu platform database.
* **[Row-Level Security Policies](/reference/database/rls-policies)** – The security model and RLS patterns that gate workspace data access.
* **[Migrations Guide](/reference/database/migrations-guide)** – Creating, testing, and deploying Supabase migrations safely.

## Packages

* **[`tuturuuu` SDK](/reference/packages/sdk)** – Official TypeScript/JavaScript SDK for the platform.
* **[`@tuturuuu/masonry`](/reference/packages/masonry)** – High-performance, responsive masonry grid component for React.
* **[`@tuturuuu/utils/effect`](/reference/packages/utils-effect)** – Curated Effect entrypoint and Tuturuuu error helpers for typed server orchestration.
* **[`@tuturuuu/supabase`](/reference/packages/supabase)** – Supabase client creation patterns and utilities.
* **[`@tuturuuu/trigger`](/reference/packages/trigger)** – Calendar provider-sync and scheduling helpers used by Vercel Cron routes.

## API Reference

* **[Generate API](/reference/api-reference/endpoint/generate)** – Request and response schemas for the AI generate endpoint.

<Note>
  The platform is mid-migration from `apps/web` (Next.js, port 7803) toward `apps/tanstack-web` (TanStack Start) plus `apps/backend` (Rust). Some package and database reference pages—especially [`@tuturuuu/supabase`](/reference/packages/supabase) and [`@tuturuuu/trigger`](/reference/packages/trigger)—document `apps/web` patterns. The backend/TanStack equivalents are tracked in the [TanStack + Rust migration guide](/platform/architecture/tanstack-rust-migration).
</Note>

If you need implementation guides, jump to [Build](/build/overview); for product tours, explore [Platform](/platform/overview).


# @tuturuuu/masonry
Source: https://docs.tuturuuu.com/reference/packages/masonry

A high-performance, responsive masonry grid component for React applications

## Overview

The `@tuturuuu/masonry` package provides a Pinterest-style masonry grid component for React with modern ResizeObserver-based measurement. The current release (0.4.3) ships only CI/release-pipeline fixes on top of 0.3.10 — the public component API is unchanged. Version 0.3.10 introduced ultra-aggressive optimization for near-perfect visual balance with 50 passes and 0.5%/5px tolerance. Version 0.3.2 brought rock-solid stability with aggressive debouncing and auto-stop mechanisms. Version 0.3.0 brought major performance improvements (50-70% CPU reduction), fixed the columns prop bug, and added advanced configuration options. It offers two distribution strategies: a fast count-based approach for uniform content, and an intelligent height-based balancing algorithm with event-driven measurement, ultra-aggressive exhaustive optimization, and memoized calculations.

## Installation

<CodeGroup>
  ```bash npm theme={null}
  npm install @tuturuuu/masonry
  ```

  ```bash yarn theme={null}
  yarn add @tuturuuu/masonry
  ```

  ```bash pnpm theme={null}
  pnpm add @tuturuuu/masonry
  ```

  ```bash bun theme={null}
  bun add @tuturuuu/masonry
  ```
</CodeGroup>

## Features

* 🎨 **Pinterest-style Layout**: Creates beautiful masonry grids with balanced columns
* 📱 **Responsive Design**: Optional responsive behavior with customizable breakpoints
* ⚖️ **Smart Distribution**: Two strategies - fast count-based or height-balanced
* 🖼️ **Modern Measurement**: ResizeObserver-based event-driven updates (50-70% faster)
* 💾 **Memoized Calculations**: Optimized performance with React memoization
* 🛡️ **Robust Validation**: Validates measurements with intelligent fallbacks
* 🎯 **TypeScript Support**: Fully typed with TypeScript
* ⚡ **Lightweight**: Zero external dependencies besides React
* 🔧 **Highly Customizable**: Flexible column, gap, breakpoint, and balance threshold configuration
* ✨ **Smooth Transitions**: Optional CSS transitions during redistribution
* 🐛 **Fixed Columns Prop**: Works correctly without requiring breakpoints (v0.3.0)
* 🔄 **Auto-cleanup**: Proper ResizeObserver disconnection on unmount

## Basic Usage

```tsx theme={null}
import { Masonry } from '@tuturuuu/masonry';

export function Gallery() {
  return (
    <Masonry columns={3} gap={16}>
      <div>Item 1</div>
      <div>Item 2</div>
      <div>Item 3</div>
      <div>Item 4</div>
    </Masonry>
  );
}
```

<Note>
  **v0.3.0+ Change**: The `columns` prop now works as expected without requiring breakpoints. Previously, default breakpoints would override the columns setting based on screen width.

  **v0.3.10 Improvement**: Ultra-aggressive optimization - 50 passes (vs 20) with ultra-tight 0.5%/5px tolerance (vs 1%/10px) ensures near-perfect balance. Column heights differ by ≤5px for professional appearance.

  **v0.3.2 Improvement**: Aggressive stability controls (500ms debounce, 10px threshold, max 10 redistributions, auto-stop after images load) ensure rock-solid layouts that settle and stay settled.
</Note>

## API Reference

### Props

<ResponseField name="children" type="ReactNode[]">
  Array of React elements to display in the masonry grid. Each child will be distributed across columns using the shortest-column algorithm.
</ResponseField>

<ResponseField name="columns" type="number">
  Number of columns to display. In v0.3.0+, this works as expected without requiring breakpoints configuration. Will be overridden by breakpoint configurations only if the `breakpoints` prop is explicitly provided.
</ResponseField>

<ResponseField name="gap" type="number">
  Gap between items in pixels. This applies both horizontally (between columns) and vertically (between items within a column).
</ResponseField>

<ResponseField name="breakpoints" type="object">
  **Optional** responsive breakpoint configuration. Keys are viewport widths in pixels, values are the number of columns to display at or above that width.

  **v0.3.0 Breaking Change**: Now optional (default: `undefined`). When not provided, uses fixed `columns` value.

  Example configuration:

  * `640px`: 1 column (mobile)
  * `768px`: 2 columns (tablet)
  * `1024px`: 3 columns (desktop)
  * `1280px`: 4 columns (large desktop)
</ResponseField>

<ResponseField name="className" type="string">
  Additional CSS classes to apply to the masonry container element.
</ResponseField>

<ResponseField name="strategy" type="'balanced' | 'count'">
  Strategy for distributing items across columns:

  * `'count'` (default): Distributes items based on item count. Fastest with no measurement overhead and no layout shift.
  * `'balanced'`: Distributes items based on actual measured heights using modern ResizeObserver API. Provides better visual balance with event-driven updates.

  Use `'balanced'` when visual balance is critical (e.g., image galleries with varying aspect ratios). Use `'count'` for best performance.
</ResponseField>

<ResponseField name="balanceThreshold" type="number">
  **New in v0.3.0**: Variance threshold (0-1) for redistribution in balanced mode. Only redistributes when column height variance exceeds this threshold.

  * Lower values (e.g., `0.01`): Stricter balance, more redistributions
  * Higher values (e.g., `0.1`): More lenient, fewer redistributions
  * Default: `0.05` (5% variance tolerance)
</ResponseField>

<ResponseField name="smoothTransitions" type="boolean">
  **New in v0.3.0**: Enable smooth CSS transitions during redistribution. Adds \~300ms animation duration for visual smoothness. Disable for instant updates.
</ResponseField>

## Examples

### Image Gallery

```tsx theme={null}
import { Masonry } from '@tuturuuu/masonry';

interface Image {
  id: number;
  url: string;
  title: string;
}

export function ImageGallery({ images }: { images: Image[] }) {
  return (
    <Masonry
      columns={4}
      gap={12}
      breakpoints={{
        640: 1,
        768: 2,
        1024: 3,
        1280: 4,
      }}
    >
      {images.map((image) => (
        <div key={image.id} className="overflow-hidden rounded-lg">
          <img
            src={image.url}
            alt={image.title}
            className="h-auto w-full"
          />
        </div>
      ))}
    </Masonry>
  );
}
```

### Card Grid

```tsx theme={null}
import { Masonry } from '@tuturuuu/masonry';

interface CardProps {
  title: string;
  description: string;
  image?: string;
}

export function CardGrid({ cards }: { cards: CardProps[] }) {
  return (
    <Masonry columns={3} gap={20} className="my-8">
      {cards.map((card, index) => (
        <div
          key={index}
          className="rounded-lg bg-white p-6 shadow-lg dark:bg-gray-800"
        >
          {card.image && (
            <img
              src={card.image}
              alt={card.title}
              className="mb-4 h-auto w-full rounded"
            />
          )}
          <h3 className="mb-2 text-xl font-bold">{card.title}</h3>
          <p className="text-gray-600 dark:text-gray-300">
            {card.description}
          </p>
        </div>
      ))}
    </Masonry>
  );
}
```

### Custom Breakpoints

```tsx theme={null}
import { Masonry } from '@tuturuuu/masonry';

export function CustomBreakpointGallery() {
  return (
    <Masonry
      columns={5}
      gap={24}
      breakpoints={{
        480: 1,    // Extra small screens
        768: 2,    // Small screens
        1024: 3,   // Medium screens
        1440: 4,   // Large screens
        1920: 5,   // Extra large screens
      }}
    >
      {items.map((item) => (
        <div key={item.id}>{item.content}</div>
      ))}
    </Masonry>
  );
}
```

### Fixed Columns (v0.3.0+)

In v0.3.0+, the `columns` prop works without requiring breakpoints:

```tsx theme={null}
import { Masonry } from '@tuturuuu/masonry';

// This now works correctly - always shows 4 columns
export function FixedColumnGrid() {
  return (
    <Masonry columns={4} gap={16}>
      {items.map((item) => (
        <div key={item.id}>{item.content}</div>
      ))}
    </Masonry>
  );
}

// You can also explicitly pass empty breakpoints (same result)
export function AlternativeFixedGrid() {
  return (
    <Masonry columns={4} gap={16} breakpoints={{}}>
      {items.map((item) => (
        <div key={item.id}>{item.content}</div>
      ))}
    </Masonry>
  );
}
```

### Balanced vs Count Strategy

Choose between fast count-based distribution or height-based balancing:

```tsx theme={null}
import { Masonry } from '@tuturuuu/masonry';

// Count-based (default) - Fast, no layout shift
export function CountBasedGallery() {
  return (
    <Masonry columns={3} gap={16} strategy="count">
      {items.map((item) => (
        <div key={item.id} style={{ height: item.height }}>
          {item.content}
        </div>
      ))}
    </Masonry>
  );
}

// Height-based - Better visual balance for varying heights
export function BalancedGallery() {
  return (
    <Masonry columns={3} gap={16} strategy="balanced">
      {items.map((item) => (
        <div key={item.id} style={{ height: item.height }}>
          {item.content}
        </div>
      ))}
    </Masonry>
  );
}
```

The `balanced` strategy is particularly useful for image galleries where images have varying aspect ratios, while `count` works well for uniform content like cards or tiles.

### With Smooth Transitions (v0.3.0+)

Enable smooth CSS transitions for visual refinement during redistribution:

```tsx theme={null}
import { Masonry } from '@tuturuuu/masonry';

export function SmoothTransitionsExample() {
  const items = Array.from({ length: 16 }, (_, i) => ({
    id: i,
    height: [120, 180, 150, 200][i % 4],
  }));

  return (
    <Masonry
      columns={4}
      gap={16}
      strategy="balanced"
      smoothTransitions={true}
      balanceThreshold={0.05}
    >
      {items.map((item) => (
        <div
          key={item.id}
          style={{ height: `${item.height}px` }}
          className="flex items-center justify-center rounded-lg bg-blue-500 text-white"
        >
          Item {item.id + 1}
        </div>
      ))}
    </Masonry>
  );
}
```

### Custom Balance Threshold (v0.3.0+)

Fine-tune distribution sensitivity:

```tsx theme={null}
import { Masonry } from '@tuturuuu/masonry';

export function CustomThresholdExample() {
  return (
    <Masonry
      columns={3}
      gap={20}
      strategy="balanced"
      balanceThreshold={0.1} // Higher = more tolerance for imbalance
    >
      {items.map((item) => (
        <div key={item.id}>{item.content}</div>
      ))}
    </Masonry>
  );
}
```

## How It Works

The masonry component uses an **optimized shortest-column algorithm** to distribute items:

### Count Strategy Algorithm

1. Creates the specified number of columns
2. Iterates through all items
3. Places each item in the column with the fewest items
4. Uses strict comparison for deterministic distribution
5. **Memoized** - only recalculates when children or columns change

### Balanced Strategy Algorithm (v0.3.0+)

1. **Immediate Multi-Column Render**: Items appear instantly in their target columns
2. **ResizeObserver Setup**: Observes all masonry items for size changes
3. **Event-Driven Measurement**: Captures height changes as they happen (images loading, etc.)
4. **Intelligent Distribution**:
   * Calculates running average for unmeasured items
   * Uses threshold-based greedy algorithm
   * Considers balance threshold for tie-breaking
   * Tracks coefficient of variation for quality
5. **Ultra-Aggressive Optimization** (v0.3.10 enhanced):
   * Phase 1: Min-Max placement (evaluates all placements)
   * Phase 2: Exhaustive search (tries moving EVERY item to EVERY column)
   * Phase 3: Best-move selection (applies single best improvement)
   * Phase 4: Build layout from optimized assignments
   * Up to **50 passes** exploring all N×M possibilities (vs previous 20)
   * Stops only when columns within **0.5% or 5px** of each other (vs previous 1% or 10px)
   * Near-perfect balance with ≤5px difference between columns
6. **Smart Redistribution** (v0.3.2 enhanced):
   * Debounced 500ms after last change for maximum stability
   * Only triggers when heights change >10px (ignores all minor fluctuations)
   * Maximum 10 redistributions to prevent endless movement
   * Stops observing after all images load
   * Stops observing after 2 seconds of stability
   * Uses `requestAnimationFrame` for smooth visual updates
   * Memoized to prevent unnecessary calculations
7. **Automatic Cleanup**: Observer disconnects on unmount or strategy change

### Responsive Behavior

* **Without breakpoints**: Uses fixed `columns` value
* **With breakpoints**: Adjusts columns based on viewport width

The height-based strategy provides better visual balance for items with varying heights, while the count-based strategy is faster with zero measurement overhead.

## Performance Considerations

### v0.3.0 Performance Improvements

| Metric         | v0.2.x (Interval)       | v0.3.0 (ResizeObserver)  | Improvement              |
| -------------- | ----------------------- | ------------------------ | ------------------------ |
| CPU Usage      | 15-20%                  | 2-5%                     | **50-70% reduction**     |
| Update Latency | 100ms intervals         | Instant (event-driven)   | **Immediate**            |
| Memory         | Growing event listeners | Single observer instance | **Minimal footprint**    |
| Battery Impact | Continuous polling      | Event-driven only        | **Significantly better** |

### Strategy Performance

* **Count Strategy (Default)**: Fastest option. No height measurements, no layout shift, zero overhead. Ideal for most use cases and 100+ items.
* **Balanced Strategy (v0.3.10)**: Modern ResizeObserver API with ultra-aggressive exhaustive optimization and rock-solid stability controls. Event-driven with exhaustive search (tries all item×column moves in up to 50 passes) for near-perfect visual balance, 500ms debounce, 10px threshold, max 10 redistributions, and auto-stop after images load. Professional layouts with column heights differing by ≤5px and ultra-tight 0.5% tolerance.

### Memoization Benefits

* **Distribution calculation**: Only runs when dependencies change
* **Average height calculation**: Cached between renders
* **Column wrappers**: Prevents unnecessary array allocations
* **Result**: Smooth 60fps even with 100+ items

### When to Use Each Strategy

| Use Case              | Recommended Strategy             | Reason                             |
| --------------------- | -------------------------------- | ---------------------------------- |
| Uniform cards/tiles   | `count`                          | Fastest, no measurement overhead   |
| Image galleries       | `balanced`                       | Better visual balance              |
| Mixed content heights | `balanced`                       | Optimizes for equal column heights |
| 100+ items            | `count`                          | Scales better, deterministic       |
| Dynamic content       | `balanced` + `smoothTransitions` | Smooth visual updates              |

For best performance with many items or frequent updates, use the default `strategy="count"`. Use `strategy="balanced"` when visual balance is more important, knowing that v0.3.0's ResizeObserver implementation is significantly more efficient than previous versions.

## Styling

The component uses inline styles for core layout functionality and accepts a `className` prop for custom styling:

```tsx theme={null}
<Masonry
  columns={3}
  gap={16}
  className="mx-auto max-w-7xl px-4"
>
  {items.map((item) => (
    <div
      key={item.id}
      className="rounded-lg bg-linear-to-br from-blue-500 to-purple-600 p-4"
    >
      {item.content}
    </div>
  ))}
</Masonry>
```

## Best Practices

<AccordionGroup>
  <Accordion title="Use consistent item widths">
    For best results, ensure all items have the same width. The masonry layout handles varying heights automatically, but varying widths can break the grid.
  </Accordion>

  <Accordion title="Set appropriate gap values">
    Choose gap values that match your design system. Common values are 8px, 12px, 16px, or 24px.
  </Accordion>

  <Accordion title="Configure breakpoints thoughtfully">
    Consider your content and screen sizes. More columns work well for small items (like thumbnails), while fewer columns suit larger content cards.
  </Accordion>

  <Accordion title="Use keys properly">
    Always provide unique `key` props to direct children of Masonry to ensure proper React reconciliation.
  </Accordion>

  <Accordion title="Choose the right distribution strategy">
    * Use `strategy="count"` (default) for best performance with uniform or near-uniform content. Zero layout shift, instant rendering.
    * Use `strategy="balanced"` for image galleries or content with varying heights. Renders immediately with count-based distribution, then progressively optimizes to height-balanced layout as images load. No hidden measurement phase - content is visible from first render.
  </Accordion>

  <Accordion title="Optimize images for progressive loading">
    When using `strategy="balanced"` with images:

    * Items render immediately using count-based distribution
    * As images load, the layout progressively rebalances every 100ms
    * Final balanced distribution achieved once all images complete loading
    * No flash or hidden content - smooth progressive enhancement
  </Accordion>
</AccordionGroup>

## How Balanced Strategy Works (v0.3.0+)

The `strategy="balanced"` mode uses modern ResizeObserver API for event-driven measurement:

1. **Immediate Multi-Column Render**: Items appear instantly in their target columns (no single-column phase)
2. **ResizeObserver Setup**: Creates observer to monitor all masonry items for size changes
3. **Event-Driven Measurement**: Captures height changes automatically when they occur (images loading, dynamic content)
4. **Accurate Measurement**: Uses `entry.contentRect.height` from ResizeObserver for precision
5. **Validation & Fallbacks**: Validates measurements; uses running average for missing/invalid values
6. **Smart Change Detection** (v0.3.2): Only redistributes when heights change by >10px (completely ignores minor fluctuations)
7. **Item Migration** (v0.3.8 new):
   * Phase 1: Min-Max placement minimizes height range
   * Phase 2: Up to 10 iterative balancing passes
   * Each pass moves best item from tallest to shortest column
   * Stops when range \< max(20px, 5% of shortest)
   * Direct migration achieves excellent column equality
8. **Aggressive Debouncing** (v0.3.2): 500ms debounce + `requestAnimationFrame` ensures maximum stability
9. **Redistribution Limits** (v0.3.2): Maximum 10 redistributions prevents endless movement
10. **Image Load Tracking** (v0.3.2): Automatically stops observing once all images finish loading
11. **Stability Detection** (v0.3.2): Stops observing after 2 seconds of no changes
12. **Memoized Calculations**: Distribution only recalculates when dependencies actually change
13. **Auto-Cleanup**: Observer automatically disconnects on unmount or strategy change

This v0.3.0+ approach provides:

* ✅ **50-70% faster** - event-driven vs polling (100ms intervals in v0.2.x)
* ✅ **Instant response** - no 100ms delay for updates
* ✅ **Better battery life** - no continuous polling
* ✅ **Minimal memory** - single observer instance vs growing listeners
* ✅ **Memoized calculations** - prevents unnecessary work
* ✅ **Smooth 60fps** - even with 100+ items
* ✅ **Robust validation** - handles edge cases gracefully
* ✅ **No layout shift** - multi-column from first render
* ✅ **Item Migration** (v0.3.8) - Direct balancing moves items from tall to short columns
* ✅ **Iterative optimization** (v0.3.8) - Up to 10 passes with smart stopping for excellent balance
* ✅ **Aggressive debouncing** (v0.3.2) - 500ms wait ensures rock-solid stability
* ✅ **High thresholds** (v0.3.2) - 10px minimum change completely ignores minor adjustments
* ✅ **Auto-stop** (v0.3.2) - Stops observing after images load or 2s of stability
* ✅ **Redistribution limit** (v0.3.2) - Maximum 10 redistributions prevents endless movement

### Browser Support for ResizeObserver

* **Supported**: All modern browsers (Chrome 64+, Firefox 69+, Safari 13.1+)
* **Fallback**: Logs warning and gracefully degrades to count strategy if unavailable

## Additional Performance Notes

* The component uses React state and effects efficiently
* Resize events are properly debounced through React's rendering cycle
* Count strategy: No DOM measurements, instant rendering, zero overhead
* Balanced strategy (v0.3.3):
  * Event-driven measurement (no polling)
  * Change detection (>10px) completely ignores minor fluctuations
  * 500ms debounce ensures maximum stability
  * Maximum 10 redistributions prevents endless movement
  * Auto-stops after all images load
  * Auto-stops after 2 seconds of stability
  * Memoized distribution prevents recalculation unless dependencies change
  * Proper ResizeObserver cleanup on unmount
* Minimal re-renders when breakpoints change

## TypeScript

The package is written in TypeScript and exports all necessary types:

```tsx theme={null}
import { Masonry } from '@tuturuuu/masonry';
import type { ReactNode } from 'react';

interface MasonryProps {
  children: ReactNode[];
  columns?: number;
  gap?: number;
  breakpoints?: {
    [key: number]: number;
  };
  className?: string;
  strategy?: 'balanced' | 'count';
  balanceThreshold?: number;  // v0.3.0+
  smoothTransitions?: boolean; // v0.3.0+
}
```

## Accessibility

The masonry component renders semantic HTML and preserves the DOM order of items. Screen readers will encounter items in the order they appear in the `children` array, not in their visual column order.

For improved accessibility:

* Ensure items have proper semantic markup
* Use ARIA labels where appropriate
* Maintain logical tab order in interactive elements

## Browser Support

The package supports all modern browsers that support:

* React 19+
* CSS Flexbox
* ES2015+ JavaScript features

## Troubleshooting

<AccordionGroup>
  <Accordion title="Columns are uneven in height">
    With the default `strategy="count"`, this is expected behavior. The algorithm balances by item count, not pixel height.

    For better visual balance with varying item heights, use `strategy="balanced"` which measures actual heights and distributes items to achieve equal column heights.
  </Accordion>

  <Accordion title="Breakpoints not working">
    Ensure you're passing an object with numeric keys. The component checks `window.innerWidth`, so it won't work in SSR without hydration.
  </Accordion>

  <Accordion title="Items not appearing">
    Make sure you're passing an array of valid React elements to the `children` prop. Check console for any React warnings.
  </Accordion>

  <Accordion title="Unexpected column count">
    **Fixed in v0.3.0**: The `columns` prop now works as expected without breakpoints.

    If you're seeing unexpected column counts:

    * **v0.3.0+**: `<Masonry columns={4} />` always shows 4 columns
    * **v0.2.x and earlier**: Default breakpoints would override the columns prop
    * **Migration**: If you relied on default responsive behavior, explicitly add `breakpoints` prop
  </Accordion>

  <Accordion title="Columns prop not working (v0.2.x and earlier)">
    This was fixed in v0.3.0. Upgrade to the latest version:

    ```bash theme={null}
    bun add @tuturuuu/masonry@latest
    ```

    In v0.3.0+, the `columns` prop works correctly without requiring breakpoints configuration.
  </Accordion>

  <Accordion title="Images taking time to balance">
    **v0.3.0 Improvement**: Much faster than previous versions!

    The component uses modern ResizeObserver API for instant response:

    * Items render immediately in multi-column layout
    * Redistributes automatically as images load (event-driven, no polling)
    * Instant updates (no 100ms delay like in v0.2.x)
    * Achieves optimal balance once all images complete

    If instant rendering is more important than perfect balance, use `strategy="count"` (default).
  </Accordion>

  <Accordion title="Component stuck in single column with balanced strategy">
    This was fixed in v0.3.0. Items now render in multi-column layout immediately.

    If you're still experiencing this:

    * Update to the latest version (`bun add @tuturuuu/masonry@latest`)
    * Check that items have measurable height (not `display: none` or `height: 0`)
    * Ensure images have proper `src` attributes
    * Verify ResizeObserver is available in your browser (all modern browsers support it)
  </Accordion>

  <Accordion title="Performance concerns with balanced strategy">
    **v0.3.0 solved this!** Performance is dramatically improved:

    * **50-70% less CPU usage** compared to v0.2.x
    * Event-driven updates (no continuous polling)
    * Memoized calculations prevent unnecessary work
    * Smooth 60fps even with 100+ items

    If you're still experiencing performance issues:

    * Ensure you're on v0.3.0+ (`bun add @tuturuuu/masonry@latest`)
    * Check browser DevTools for ResizeObserver support
    * Consider using `strategy="count"` for 200+ items if balance isn't critical
  </Accordion>
</AccordionGroup>

## Source Code

The package is open source and available on GitHub:

* [View on GitHub](https://github.com/tutur3u/platform/tree/main/packages/masonry)
* [Report Issues](https://github.com/tutur3u/platform/issues)

## Migration Guide

### Migrating from v0.2.x to v0.3.0

**Breaking Change**: Breakpoints are now optional (default: `undefined` instead of default object).

```tsx theme={null}
// ❌ v0.2.x - Might show fewer columns than expected
<Masonry columns={4} />
// Default breakpoints override columns based on screen width

// ✅ v0.3.0 - Works as expected
<Masonry columns={4} />
// Always shows 4 columns

// If you want responsive behavior, explicitly provide breakpoints:
<Masonry 
  columns={4}
  breakpoints={{ 640: 1, 768: 2, 1024: 3, 1280: 4 }}
/>
```

**Migration Steps:**

1. **Test your layouts**: If you were relying on default breakpoints, explicitly add them
2. **Update imports**: No changes needed
3. **Check columns prop**: Should now work as expected without breakpoints
4. **Optional**: Consider using new `balanceThreshold` and `smoothTransitions` props

**No Action Needed If:**

* You were already passing explicit `breakpoints` prop
* You were passing empty breakpoints `breakpoints={{}}`
* Your layouts already work correctly

**New Features You Can Use:**

* `balanceThreshold` - Fine-tune distribution sensitivity
* `smoothTransitions` - Add CSS animations during redistribution
* Better performance with ResizeObserver (automatic)

## Changelog

For the canonical, machine-generated changelog see [`packages/masonry/CHANGELOG.md`](https://github.com/tutur3u/platform/blob/main/packages/masonry/CHANGELOG.md).

### 0.4.1 – 0.4.3 (Current - CI/Release Fixes)

These releases contain **no public API changes** — the `Masonry` component, props, and
distribution algorithms are identical to 0.3.10. They are release-pipeline and build
recovery fixes only:

* **0.4.3**: `fix(ci)` auto-recover package release dependencies
* **0.4.2**: `fix(ci)` recover releases and package `tsgo` builds
* **0.4.1**: Release-pipeline recovery (no source changes)

No migration or code changes are required when upgrading from 0.3.10 to 0.4.x.

### 0.3.10 (Near-Perfect Balance Release)

**Ultra-Aggressive Optimization:**

* 🎯 **50 optimization passes**: Thoroughly explores solution space (vs previous 20)
* 📊 **Very tight threshold**: Stops only when columns within **0.5% or 5px** (vs previous 1% or 10px)
* ⚖️ **Near-perfect balance**: Relentless optimization until near-identical column heights
* 🎨 **Professional appearance**: Column heights differ by ≤5px in most cases
* ⚡ **No compromise**: Ultra-tight tolerance for best visual quality

**Algorithm Details:**

* **Phase 1**: Min-Max greedy (initial placement)
* **Phase 2**: Ultra-aggressive optimization (up to 50 passes, 0.5% tolerance)
* **Phase 3**: Early stop when near-perfectly balanced (0.5% or 5px)
* **Phase 4**: Build final layout

**Why Ultra-Tight Tolerance Works:**

* 5px maximum difference ensures visually identical column heights
* 0.5% threshold prevents premature stopping on large layouts
* 50 passes ensure we find improvements even in edge cases
* No compromise on visual quality

**Results:**

* ✅ **Near-perfect balance**: Column heights differ by ≤5px in most cases
* ✅ **Thorough optimization**: 50 passes ensure no improvement missed
* ✅ **Professional appearance**: Visually indistinguishable column heights

### 0.3.9 (Optimal Balance Release)

**Global Optimization with Exhaustive Search:**

* 🎯 **Exhaustive search**: Tries moving EVERY item to EVERY column (not limited to tallest→shortest)
* 📊 **Best-move selection**: Always picks the single move that improves balance the most
* ⚖️ **Optimal balance**: Finds near-optimal distribution by exploring full solution space
* 🎨 **Tighter threshold**: Stops when columns within 1% or 10px (vs previous 5% or 20px)
* ⚡ **Guaranteed convergence**: Can't get stuck in local optima

**Algorithm Details:**

* **Phase 1**: Min-Max greedy (initial placement)
* **Phase 2**: Global optimization (try all possible moves, pick best)
* **Phase 3**: Early stop when perfectly balanced (1% or 10px)
* **Phase 4**: Build final layout

**Why Exhaustive Search Works Better:**

* Not limited to moves between tallest and shortest columns
* Considers the entire solution space at each step
* Finds truly optimal moves, not just locally good ones
* Can escape local optima that previous algorithms got stuck in

**Results:**

* ✅ **Near-optimal balance**: Explores all possibilities to find best distribution
* ✅ **No local optima**: Can always find improving move if one exists
* ✅ **Tighter tolerance**: Achieves balance within 1% or 10px

### 0.3.8 (Perfect Balance Release)

**Direct Balancing with Item Migration:**

* 🎯 **Item migration**: Moves items from tallest to shortest column (not just swapping)
* 📊 **Iterative optimization**: Up to 10 passes moving best item each time
* ⚖️ **Excellent balance**: Directly reduces height differences
* 🎨 **Smart stopping**: Stops when columns within 5% or 20px of each other
* ⚡ **More effective**: Migration is simpler and more direct than pair swaps

**Algorithm Details:**

* **Phase 1**: Min-Max greedy (initial placement)
* **Phase 2**: Iterative balancing (move items from tallest to shortest)
* **Phase 3**: Early stop when well-balanced
* **Phase 4**: Build final layout

**Why Migration Works Better:**

* Directly addresses the problem (move from tall to short)
* Doesn't require finding matching pairs to swap
* Can move any item that improves balance
* Converges faster to good solution

**Results:**

* ✅ **Better balance**: More direct approach reduces extremes
* ✅ **Simpler logic**: Migration is conceptually clearer than swapping
* ✅ **Faster convergence**: Gets to good solution in fewer iterations

### 0.3.7 (Perfect Balance Release)

**Best-First Optimization Enhancement:**

* 🎯 **Best-first search**: Each pass finds and applies the BEST swap, not just first improvement
* 📊 **Exhaustive optimization**: Up to 5 passes with thorough swap evaluation
* ⚖️ **Near-perfect equality**: Achieves virtually identical column heights
* 🎨 **Systematic refinement**: Guarantees finding local optimum through greedy best-first approach
* ⚡ **Smart threshold**: Accepts any improvement >0.5px for fine-grained optimization

**Algorithm Details:**

* Each optimization pass evaluates ALL possible swaps
* Picks and applies only the BEST swap per pass
* Continues for up to 5 passes or until no improvements >0.5px remain
* Lower threshold (0.5px vs 2px) catches more refinement opportunities

**Results:**

* ✅ **Excellent balance**: Systematically finds near-optimal distribution
* ✅ **Consistent quality**: Best-first guarantees good results
* ✅ **Handles edge cases**: 5 passes catch difficult distributions

### 0.3.6 (Perfect Balance Release)

**Hybrid Algorithm with Post-Optimization:**

* 🎯 **Two-phase approach**: Min-Max placement + swap-based refinement
* 📊 **Post-optimization**: Up to 2 passes swapping items to reduce variance further
* ⚖️ **Near-perfect equality**: Achieves virtually identical column heights
* 🎨 **Best of both worlds**: Global Min-Max + local swap optimization
* ⚡ **Still efficient**: Limited refinement passes maintain performance

**Algorithm Details:**

* **Phase 1**: Min-Max greedy (evaluates all placements, minimizes height range)
* **Phase 2**: Post-optimization (swaps items between columns if it improves balance ≥2px)
* **Phase 3**: Build final layout from optimized assignments

**Results:**

* ✅ **Virtually perfect balance**: Columns end at nearly identical heights
* ✅ **Hybrid superiority**: Outperforms pure Min-Max with refinement pass
* ✅ **Minimal overhead**: Only 2 optimization passes

### 0.3.5 (Perfect Balance Release)

**Major Algorithm Improvements:**

* 🎯 **Min-Max Balanced Greedy**: Advanced algorithm that minimizes height range across all columns
* 📊 **Look-ahead optimization**: Evaluates all possible placements before choosing
* ⚖️ **Superior balance**: Minimizes max column height difference, not just finds shortest column
* 🎨 **Visual perfection**: Columns end at nearly identical heights for professional galleries
* ⚡ **Smart & efficient**: O(n log n) sort + O(n·k²) placement with intelligent tie-breaking

**Algorithm Details:**

* **Phase 1**: Sort items by height in descending order (largest first)
* **Phase 2**: For each item, try placing in every column
* **Phase 3**: Calculate resulting height range (max - min) for each option
* **Phase 4**: Choose column that minimizes the range (most balanced result)
* **Phase 5**: Tie-breaker prefers shorter columns when ranges are equal

**Why Min-Max Works Better:**

* Considers the **global balance** of all columns, not just local shortest
* Actively minimizes the difference between tallest and shortest columns
* Produces significantly more even distributions than simple greedy
* Large items placed strategically to enable better balance
* Small items fill gaps optimally

**Results:**

* ✅ **Near-perfect balance**: Columns end at nearly identical heights
* ✅ **Superior to LFD**: Outperforms simple greedy by considering future balance
* ✅ **Handles any sizes**: Excellent for highly varied aspect ratios
* ✅ **Still fast**: Slightly more computation but dramatically better results

### 0.3.4 (Optimal Distribution Release)

### 0.3.3 (Multi-Pass Optimization - Superseded)

**Note**: This version implemented swap-based optimization which was replaced in v0.3.4 with the more effective Largest First Decreasing algorithm.

### 0.3.2 (Rock-Solid Stability Release)

**Critical UX Fixes:**

* 🎭 **Aggressive debouncing**: 500ms debounce ensures layout stability (up from 200ms in v0.3.1)
* 📏 **High threshold**: 10px change threshold completely ignores minor fluctuations (up from 3px in v0.3.1)
* 🛑 **Maximum redistributions**: Hard limit of 10 redistributions prevents endless movement
* 🖼️ **Image load tracking**: Automatically stops observing once all images finish loading
* ⏱️ **Stability detection**: Stops observing after 2 seconds of no changes
* ✨ **Rock-solid experience**: Layout settles quickly and stays settled permanently

**Bug Fixes:**

* ✅ **Non-stop repositioning**: Fixed items constantly moving around even after images loaded (critical UX issue)
* ✅ **Stable layout**: Layout now properly stabilizes and never changes again
* ✅ **Performance**: Stops wasting resources after layout is stable

### 0.3.1 (UX Polish Release)

**Initial UX Improvements:**

* 🎭 **Debounced updates**: 200ms debounce prevents jerky movement
* 📏 **Smart thresholds**: 3px change threshold ignores minor font rendering differences
* ✨ **Smoother experience**: Items settle into place smoothly

**Bug Fixes:**

* ✅ **Excessive redistributions**: Fixed items moving around too frequently
* ✅ **Stable layout**: Layout settles properly once images finish loading

### 0.3.0 (Major Performance & Bug Fix Release)

**Breaking Changes:**

* 🔧 **Breakpoints now optional**: Default changed from object to `undefined`. Columns prop now works without breakpoints!
* 🎯 **Migration needed**: If you relied on default responsive behavior, explicitly add breakpoints

**Major Improvements:**

* ⚡ **ResizeObserver API**: Replaced interval-based measurement with modern ResizeObserver (50-70% CPU reduction)
* 💾 **Memoization**: Distribution calculations now memoized for better performance
* 🎨 **Improved algorithm**: Better tie-breaking and variance tracking for more balanced columns
* 🚀 **No layout shift**: Items appear in target columns immediately (removed single-column initial render)
* ✨ **Smooth transitions**: New `smoothTransitions` prop for CSS-animated redistributions
* 🎯 **Balance threshold**: New `balanceThreshold` prop for fine-tuning distribution sensitivity

**Bug Fixes:**

* ✅ **Fixed columns prop**: `<Masonry columns={4} />` now correctly shows 4 columns (was showing 1-3 based on screen width)
* ✅ **Event-driven updates**: Instant response to size changes instead of 100ms polling
* ✅ **Better cleanup**: Proper ResizeObserver disconnection on unmount

**Performance:**

* 📊 50-70% reduction in CPU usage during measurement phase
* 🔋 Significantly better battery life (event-driven vs continuous polling)
* 💨 Instant update latency instead of 100ms intervals
* 🧠 Minimal memory footprint with single observer instance

### 0.2.1

Critical bug fix for initialization:

* **Fixed single column stuck issue**: Component now properly initializes multi-column layout
* **More lenient initialization**: Requires only 50% valid measurements instead of 100%
* **Faster initial render**: Switches to multi-column as soon as minimum threshold is met
* **Better edge case handling**: Won't get stuck if some items have zero height initially

### 0.2.0

Major improvements to measurement and distribution system:

* **Robust measurement validation**: Dual measurement approach with validation
* **Smart change detection**: Only updates when heights change by >1px
* **Intelligent fallbacks**: Uses average height for unmeasured items
* **Performance safety limits**: Maximum 50 measurement cycles (5 seconds)
* **Better image handling**: Proper event listeners with `naturalHeight` validation
* **Improved greedy algorithm**: Better column distribution
* **Immediate image updates**: Redistributes as each image loads

### 0.1.7

* **Fixed distribution algorithm**: Proper strict `<` comparison for better balance
* Prevents items from piling up in later columns

### 0.1.6

* **Fixed measurement tracking**: Added `data-item-index` for accurate height mapping
* Measurements now correctly correlate after redistribution

### 0.1.5

* **Fixed infinite rendering issue**: Proper cleanup of measurement intervals
* Removed problematic component remounting from key prop changes
* Improved lifecycle management with better effect dependencies
* Stable rendering once all images are loaded

### 0.1.4

* **Visible-first rendering**: Removed hidden measurement phase
* Items now appear immediately - no more delayed visibility
* Background measurement and progressive optimization
* Zero layout shift with count strategy, smooth progressive improvement with balanced

### 0.1.3

* **Optimized progressive loading**: Periodic redistribution every 100ms while images load
* Smooth, continuous layout improvements as images become available
* Final perfect distribution after all images are fully loaded
* Better visual experience with gradual optimization instead of sudden changes
* Eliminates janky single-redistribution in favor of smooth progressive refinement

### 0.1.2

* **Progressive image loading**: Distribution now recalculates as each image loads instead of waiting for all
* Smoother user experience with incremental layout improvements
* Better handling of mixed content (images and non-image items)
* Eliminates long wait times for image-heavy galleries

### 0.1.1

* **Fixed image support in balanced strategy**: Now waits for all images to load before measuring heights
* Handles both loaded and unloaded images gracefully
* Prevents measurement of images before they have dimensions
* Improved reliability for image galleries with `strategy="balanced"`

### 0.1.0

* **STABLE RELEASE**: Production-ready masonry grid component
* Fixed infinite rendering loop in balanced strategy
* Implemented proper two-phase measurement approach for balanced distribution
* Fixed column distribution to properly rotate through equal-height columns
* Improved visual balance with varying item heights (100+ items tested)
* Balanced strategy now uses hidden measurement phase for accurate height calculations
* Performance optimizations: measurement happens once, distribution is stable

### 0.0.4

* Added `strategy` prop with `'count'` and `'balanced'` modes
* `'balanced'` mode uses ResizeObserver to measure heights for better visual balance
* `'count'` mode (default) provides best performance with no layout shift

### 0.0.3

* Fixed unbalanced column distribution using shortest-column algorithm
* Improved visual balance across all column heights

### 0.0.2

* Added build configuration for proper module distribution
* Published compiled JavaScript and TypeScript declarations

### 0.0.1

* Initial release with basic masonry layout functionality


# tuturuuu
Source: https://docs.tuturuuu.com/reference/packages/sdk

Official TypeScript/JavaScript SDK for the Tuturuuu platform

# Tuturuuu SDK

Official TypeScript/JavaScript SDK for interacting with the Tuturuuu platform. Provides type-safe access to workspace storage, files, documents, and agent-friendly task workflows.

## Installation

<CodeGroup>
  ```bash npm theme={null}
  npm install tuturuuu
  ```

  ```bash yarn theme={null}
  yarn add tuturuuu
  ```

  ```bash pnpm theme={null}
  pnpm add tuturuuu
  ```

  ```bash bun theme={null}
  bun add tuturuuu
  ```
</CodeGroup>

## Quick Start

```typescript theme={null}
import { TuturuuuClient } from 'tuturuuu';

// Initialize the client with your API key
const client = new TuturuuuClient('ttr_your_api_key');

// List files in workspace
const files = await client.storage.list({
  path: 'documents',
  limit: 50
});

// Upload a file
const file = new File(['content'], 'example.txt');
const result = await client.storage.upload(file, {
  path: 'documents'
});

// Create a document
const doc = await client.documents.create({
  name: 'My Document',
  content: { text: 'Hello World' }
});
```

## Features

<CardGroup>
  <Card title="Bun CLI" icon="terminal">
    Use `ttr` for browser login, workspace discovery, and task workflows
  </Card>

  <Card title="Headless Login" icon="copy">
    Copy a short-lived CLI token from the browser when a local callback is not
    available
  </Card>

  <Card title="Storage Operations" icon="folder">
    Upload, download, list, and delete files and folders
  </Card>

  <Card title="Document Management" icon="file-alt">
    Create, read, update, and delete workspace documents
  </Card>

  <Card title="Signed URLs" icon="link">
    Generate temporary shareable links for files
  </Card>

  <Card title="Image Resizing" icon="image">
    Apply Supabase image transformations during share and download
  </Card>

  <Card title="Analytics" icon="chart-bar">
    Track storage usage, file counts, and limits
  </Card>
</CardGroup>

## CLI

The SDK package includes a native Bun-powered CLI. `ttr` is the primary command,
and `tuturuuu` plus `tutur3u` are aliases for the same binary.

```bash theme={null}
ttr --help
ttr login
ttr upgrade
ttr --version
ttr whoami
ttr host current
ttr host use local --port 7803
ttr workspaces
ttr workspaces use
ttr boards
ttr boards use
ttr lists use
ttr tasks use
ttr tasks --board <board-id>
ttr tasks --compact
ttr tasks search "deadline review"
ttr tasks search "deadline review" --mode text
ttr tasks search "deadline review" --mode semantic
ttr tasks create "Add Tuturuuu CLI"
ttr tasks create --list <list-id> --name "Write release notes"
ttr tasks done <task-id>
ttr tasks close <task-id>
ttr tasks update <task-id> --json-payload '{"completed":true}'
ttr finance wallets
ttr finance wallets balance --all
ttr finance transactions --page-size 10
ttr finance transactions create --amount 150000 --wallet <wallet-id> --taken-at 2026-05-09
ttr finance transfers migrate --from-transaction <tx-id> --to-transaction <tx-id> --from-wallet <wallet-id> --to-wallet <wallet-id> --amount 150000 --taken-at 2026-05-09
ttr finance budgets status
ttr calendar events list --start 2026-06-11T00:00:00Z --end 2026-06-12T00:00:00Z
ttr calendar events create "Focus block" --start 2026-06-11T09:00:00+07:00 --duration-minutes 90
ttr calendar schedule preview --window-days 14 --timezone Asia/Ho_Chi_Minh
```

`ttr login` opens the browser and creates a Tuturuuu-managed CLI app-session
JWT pair through `apps/web`. The terminal and browser confirmation page show the
signed-in account email when the web session exposes it. The CLI stores that
session and selected workspace, board, list, task, label, and project in the OS
app config directory. `personal` is the default workspace after login and when
no workspace has been selected:

Use `ttr host use` to switch between Tuturuuu origins. `production` and `prod`
resolve to `https://tuturuuu.com`; `local` and `localhost` prefer safe local
environment URLs from `TUTURUUU_LOCAL_BASE_URL`, `PORTLESS_URL`, `WEB_APP_URL`,
`NEXT_PUBLIC_WEB_APP_URL`, or `NEXT_PUBLIC_APP_URL`, then fall back to
`https://tuturuuu.localhost`. Pass `--port <port>` for
`http://localhost:<port>`, or `--portless --port <port>` for
`https://tuturuuu.localhost:<port>`. Changing origins clears the saved session
and selected workspace context because both are origin-specific.

`ttr config set-base-url <url>` remains available for compatibility and uses the
same host normalization and context-clearing behavior. The CLI normalizes
`0.0.0.0` and unspecified IPv6 origins to `localhost` so the browser login flow
does not open a blocked address.

On Dockerized production deployments, the web auth start route also rewrites
wildcard bind origins such as `0.0.0.0:7803` to the forwarded public host or the
configured app URL (`WEB_APP_URL`, `NEXT_PUBLIC_WEB_APP_URL`,
`NEXT_PUBLIC_APP_URL`, `COOLIFY_URL`, or `COOLIFY_FQDN`) before sending users to
`/login`. If those environment values are unset and no public forwarded host is
available, `https://tuturuuu.com` is the default fallback.

* macOS: `~/Library/Application Support/Tuturuuu/config.json`
* Linux: `$XDG_CONFIG_HOME/tuturuuu/config.json` or `~/.config/tuturuuu/config.json`
* Windows: `%APPDATA%\Tuturuuu\config.json`

For headless agent environments, use copy-token mode:

```bash theme={null}
ttr login --copy
```

Open the printed URL in an authenticated browser, copy the returned CLI token,
and paste it into the terminal. Set `TUTURUUU_CONFIG` to use a custom config
file, or use `ttr host use <target>` to target a local, production, or explicit
URL origin.

The CLI checks the npm registry at most once per hour and writes a notice to
stderr when a newer `tuturuuu` version is available. This keeps `--json` output
machine-readable for agents. Use `ttr upgrade` to run `bun i -g tuturuuu`. Use
`--no-update-check` on a single command, or set `TUTURUUU_DISABLE_UPDATE_CHECK=1`,
to disable the check.

CLI sessions are dedicated Tuturuuu gateway JWTs, separate from normal browser
and Supabase Auth sessions. The CLI stores a short-lived app-session access JWT
plus a longer-lived refresh JWT, refreshes shortly before access-token expiry,
updates the saved config with the rotated refresh token, and retries once after a
`401` response. Refresh JWTs only carry the CLI refresh scope, so they cannot be
used directly as API bearer tokens. If refresh fails because the user no longer
exists or the refresh JWT has expired, run `ttr login` again.

The SDK fetch wrapper must attach CLI bearer tokens, refresh sessions, and retry
`401` responses only for relative Tuturuuu API paths or absolute URLs whose
origin exactly matches the configured CLI base URL. Cross-origin absolute URLs
must be delegated without `Authorization` headers.

API routes used by `ttr` must accept the CLI app-session access JWT from the
`Authorization: Bearer ...` header. For `apps/web` routes, prefer
`withSessionAuth` with `targetApp: 'platform'` and
`requiredScope: 'cli:access'` when the route is CLI-only; shared user profile
routes can include the platform target alongside satellite app targets. Shared
API routes should verify the CLI app-session token before falling back to
Supabase session auth and then keep workspace membership checks explicit.
When a handler lives in `packages/apis` and is reused by multiple apps, keep
`@tuturuuu/auth` imports in the app-owned route wrapper and pass a
pre-authenticated context into the shared handler so package builds do not form
an auth/UI/API cycle.

SDK version and changelog PRs are generated by
`.github/workflows/release-please.yaml` from Conventional Commits on
`production`. Release Please tracks the SDK in `release-please-config.json` as
the `sdk` component, records the current version in
`.release-please-manifest.json`, and updates `packages/sdk/package.json` in the
combined monorepo release PR. SDK releases are then published automatically from
`.github/workflows/release-sdk-package.yaml` when that version bump lands on
`production` or when the release workflow itself changes. The same publish
workflow can be dispatched manually to catch up a version that already landed on
`production`. Manual dispatches from any other ref are rejected before
dependency installation, packaging, or npm trusted publishing can run. The
workflow runs the SDK tests, skips publication if the exact package version
already exists on npm, waits for publishable Tuturuuu workspace dependencies to
be visible on npm, prepares a tarball with `npm pack` outside the
trusted-publish job, and then publishes that tarball through
[npm trusted publishing](https://docs.npmjs.com/trusted-publishers). Only the
final `publish-npm` job requests `id-token: write`, so GitHub Actions mints the
short-lived OIDC token after dependency installation, package builds, and version
checks have already finished. That job downloads the prepared artifact, verifies
its package `name` and `version`, confirms the bundled `npm` CLI supports trusted
publishing, runs `npm publish ./<tarball> --ignore-scripts`, and polls `npm view`
until the exact SDK version is visible without using an `NPM_TOKEN`. npm treats
the downloaded artifact as a local file path. The job
targets the GitHub environment `sdk-release-production`; keep that environment
restricted to the `production` branch in repository settings, and keep the npm
trusted publisher bound to the same environment name so a branch-selected
workflow cannot mint a matching npm publish identity. Do not add `bun install`,
`npm install -g`, package builds, package lifecycle scripts, or repository
secrets to the SDK release workflow. Because the `tuturuuu` package is public
and `tutur3u/platform` is a public repository, npm also generates and attaches
build provenance attestations automatically. The package manifest inside the
tarball must keep repository metadata aligned with the provenance repository:
`repository.url` is `https://github.com/tutur3u/platform`, and
`repository.directory` points at the package directory.

`.github/workflows/sdk-version-bump.yaml` is retired and no longer generates
patch-version PRs. Do not restore checksum or package-only bump automation for
the SDK; release-please must remain the version/changelog source of truth.

The SDK imports `@tuturuuu/devbox`, `@tuturuuu/types`, and
`@tuturuuu/internal-api` through package exports that point at their git-ignored
`dist/` directories. The release workflow must build those workspace packages in
the non-OIDC build and prepare jobs before running SDK tests or creating the
`npm pack` tarball; otherwise a clean Actions checkout cannot resolve the SDK
imports. The workflow then runs
`node scripts/ci/prepare-npm-package-manifest.js packages/sdk` before
`npm pack` so the published manifest contains concrete npm versions instead of
local `workspace:` protocol ranges. Keep matching npm release workflows for the
SDK runtime workspace dependencies so consumers can install the published SDK.
When release-please bumps the SDK and one of those dependencies in the same
production push, the SDK workflow waits for the dependency versions before it
packs and publishes. If a dependency release workflow for the same SHA fails,
the SDK wait fails immediately instead of waiting for npm visibility until
timeout.

The matching npm-side trusted publisher must stay configured at
`https://www.npmjs.com/package/tuturuuu/access` with these exact values:

* **Provider**: GitHub Actions
* **Organization or user**: `tutur3u`
* **Repository**: `platform`
* **Workflow filename**: `release-sdk-package.yaml`
* **Environment name**: `sdk-release-production`

If the npm-side configuration drifts (for example after a repo rename, missing
first-publish setup, package access drift, or after moving the publish step into
another workflow file), `npm publish` can fail with `ENEEDAUTH`, `E404`, or
permission text. Update the npm package access or trusted publisher entry first;
do not paper over the failure by reintroducing a long-lived `NPM_TOKEN`. After
confirming a trusted-publisher release works end to end, the npm package
settings should keep `Require two-factor authentication and disallow tokens`
enabled so the package cannot be published with classic tokens.

### Devbox Setup

Use `ttr box setup` on self-hosted runner machines before offloading expensive
checks, Supabase workflows, or E2E suites. The command clones or reuses
`https://github.com/tutur3u/platform.git` at `~/Documents/tuturuuu`, runs
`bun install --frozen-lockfile`, starts the local Supabase stack with
`bun sb:start`, reads `supabase status -o json`, and upserts local Supabase
connection values into ignored `apps/*/.env.local` files with secret values
redacted from CLI output.

```bash theme={null}
ttr box doctor
ttr box setup
ttr box setup --dir .
ttr box repair --dir .
ttr box repair --dir . --dry-run
```

`ttr box doctor` stays read-only. Use `ttr box setup --yes` only when the host
should install detected missing prerequisites through its package manager.
Use `ttr box repair --dir .` after a CLI upgrade to repair an existing runner
service without registering a new runner token.

### Scoped Help

Use scoped help when you know the area but not the exact flags. Help commands do
not require login, do not read the saved config, and do not run the update check.

```bash theme={null}
ttr --help
ttr upgrade --help
ttr box --help
ttr calendar --help
ttr calendar events --help
ttr finance --help
ttr finance transactions --help
ttr tasks --help
ttr tasks search --help
ttr tasks create --help
ttr task-templates --help
ttr task-templates import --help
ttr task-templates export --help
ttr tasks done --help
ttr tasks close --help
ttr tasks update --help
ttr workspaces --help
ttr help tasks create
```

Global help shows the command map. Group help explains defaults and shared
flags. Action help focuses on a single operation, including required ids,
payload flags, and practical examples.

### Agent-Friendly Discovery

For autonomous engineering workflows, start by discovering the current account
and selected context:

```bash theme={null}
ttr whoami
ttr whoami --json
ttr workspaces --json --no-update-check
ttr tasks --json --no-update-check
```

`ttr whoami` shows login state, account email, current workspace, selected
board/list/task/label/project ids, base URL, config path, and the `Tuturuuu CLI`
session label. Use `--json --no-update-check` when another agent is going to
parse stdout.

The v1 task surface covers workspaces, boards, lists, tasks, labels, projects,
relationships, moves, and bulk task updates. Read-oriented groups list by
default, so `ttr tasks` and `ttr workspaces` are equivalent to their explicit
`list` forms. `ttr boards` shows active, unarchived boards by default; use
`ttr boards --archived`, `ttr boards --deleted`, or `ttr boards --all` when an
agent needs archived or deleted board inventory. Unscoped `ttr tasks` starts
from the personal workspace and lists personal tasks plus open tasks assigned to
the user in other accessible workspaces; selecting a board/list or passing
`--workspace` scopes the result back to that context. `ttr tasks` shows open
tasks by default by excluding rows with `completed_at` or `closed_at` and by
limiting task-list statuses to `not_started` and `active`. That default hides
tasks in `documents`, `review`, `done`, and `closed` lists, and tasks from
archived boards; use `--all`, `--include-archived`, `--documents`, `--review`,
`--done`, `--closed`, `--include-documents`, `--include-review`,
`--include-done`, or `--include-closed` to adjust that filter. Results are
paginated at 50 tasks by default; use
`--page`/`--page-size` or `--limit`/`--offset` to page through larger task sets.
Human-readable task lists show a footer with the total task count and current
page/max page. Add `--compact` to task lists when an agent only needs the task
title, task list name, and per-task workspace name. Task lists are ordered by
priority and due date, with prettier due dates and configured task-list colors
in table output. Human-readable tables use smooth box borders, respect the
terminal width, and wrap long cell content so task titles stay readable instead
of overflowing narrow panes. Add `--json`
when another agent or script needs machine-readable output.

Use `ttr tasks search <query>` for ranked task search. Search defaults to
`--mode hybrid`, accepts `--mode text` for PostgreSQL full-text search only and
`--mode semantic` for embedding similarity only, and supports
`--query`/`--q`, `--limit`/`--match-count`, `--threshold`/`--match-threshold`,
`--workspace`/`--ws`, `--compact`, and `--json`. Search output preserves API
relevance order and shows the score when available. Existing list filtering
with `ttr tasks --q <query>` is unchanged and remains the lightweight list text
filter.

`tasks create`, `boards create`, and `lists create` accept a quoted positional name as
a shorthand for `--name`. Task CRUD accepts either the task UUID or the board
identifier shown in the UI, such as `VHP-12`; prefixed identifiers resolve
within the selected workspace even when another list is selected, and matching
human-readable output keeps that prefixed identifier visible. Marking a task
completed stamps `completed_at` so Tuturuuu moves it to the first `done` list;
pass `--list <done-list-id>` or include `list_id` in `--json-payload` to choose
another done destination. Use `ttr tasks done [task-id]` as the quick shortcut.
Use `ttr tasks close [task-id]` to stamp `closed_at`; pass `--list <closed-list-id>` to choose a specific closed destination.

Task templates are single-task starters, separate from board templates.
Workspace templates are managed with
`ttr task-templates list/show/create/update/delete/use` and can be imported
from or exported to local markdown files. Local templates live under
`.tuturuuu/task-templates/*.md`, use YAML frontmatter for fields such as `key`,
`name`, `task_name`, `priority`, `label_ids`, `assignee_ids`, and
`project_ids`, and use the markdown body as the task description. Markdown
descriptions from `--description-format markdown` and local template bodies
support GFM pipe tables and are stored as TipTap/Yjs table content for the web
editor. `ttr tasks create --template <key-or-path>` resolves workspace keys or
local markdown paths; explicit flags such as `--name`, `--list`, `--priority`,
`--labels`, and `--projects` override template defaults.

```markdown theme={null}
---
key: qa-handoff
name: QA handoff
task_name: Verify release handoff
priority: high
---

| Field | Value |
| --- | --- |
| Owner | Platform |
| Environment | Staging |
```

### Finance CLI

Finance commands use the selected workspace and the same authenticated internal
APIs as the web app. Use `--workspace` or `--ws` to target a different
workspace, and use `--json-payload` when a script needs to send fields that do
not have dedicated flags yet. Finance list output is paginated by default; use
`--page`/`--page-size` or `--limit`/`--offset` to move through larger result
sets.

Finance API routes that back `ttr finance` should resolve access through
`getFinanceRouteContext` from `@tuturuuu/apis/finance/request-access`, with
app-owned routes passing `resolveFinanceRouteAuthContext(request)` from
`apps/web/src/lib/finance-route-auth.ts` when they need CLI app-session bearer
token support. Keep CLI token verification in the app layer so `@tuturuuu/apis`
does not depend on `@tuturuuu/auth`; `getFinanceRouteContext` still keeps the
pre-authenticated actor, browser Supabase sessions, `personal` workspace
resolution, and finance permission checks on the same path.

```bash theme={null}
# Wallet CRUD.
ttr finance wallets
ttr finance wallets --page 2 --page-size 10
ttr finance wallets get <wallet-id>
ttr finance wallets balance <wallet-id>
ttr finance wallets balance --all
ttr finance wallets create "Cash" --currency VND --balance 0 --type STANDARD
ttr finance wallets update <wallet-id> --name "Operating Cash"
ttr finance wallets delete <wallet-id>

# Transaction CRUD and reporting helpers.
ttr finance transactions --page-size 10
ttr finance transactions --limit 25 --offset 50
ttr finance transactions get <transaction-id>
ttr finance transactions create --amount 150000 --wallet <wallet-id> --taken-at 2026-05-09
ttr finance transactions update <transaction-id> --category <category-id>
ttr finance transactions delete <transaction-id>
ttr finance transactions export --wallets <wallet-id> --start 2026-05-01 --end 2026-05-31
ttr finance transactions stats --start 2026-05-01 --end 2026-05-31

# Transfer creation, update, and id-preserving migration.
ttr finance transfers create --from-wallet <wallet-id> --to-wallet <wallet-id> --amount 150000 --taken-at 2026-05-09
ttr finance transfers update --from-transaction <tx-id> --to-transaction <tx-id> --from-wallet <wallet-id> --to-wallet <wallet-id> --amount 150000 --taken-at 2026-05-09
ttr finance transfers migrate --from-transaction <tx-id> --to-transaction <tx-id> --from-wallet <wallet-id> --to-wallet <wallet-id> --amount 150000 --taken-at 2026-05-09

# Categories, budgets, and recurring transactions.
ttr finance categories create "Travel" --expense --color blue --description "Trips and commuting"
ttr finance budgets create "Marketing" --amount 1000000 --period monthly --start-date 2026-05-01
ttr finance budgets status
ttr finance recurring create "Rent" --amount 5000000 --wallet <wallet-id> --frequency monthly --start-date 2026-05-01
ttr finance recurring upcoming --days-ahead 30
```

### Calendar CLI

Calendar commands use the selected workspace and the same authenticated calendar
APIs as the web app. Use `--workspace` or `--ws` to target a different
workspace, and use `--json` when scripts need the raw structured response.
Human output renders resource-specific tables for events, calendars, categories,
accounts, provider calendars, connections, sources, and schedulable tasks.

Event time input is exact ISO datetime only. `events create` requires `--start`
and exactly one of `--end` or `--duration-minutes`; `events update --duration-minutes` also requires `--start`. Source flags map to provider
payloads: use `--source-provider tuturuuu --calendar <workspace-calendar-id>`
for workspace calendars, or `--source-provider google|microsoft --connection <connection-id>` for connected provider calendars. `calendar calendars reset`
is destructive and requires `--yes`.

```bash theme={null}
# Event CRUD.
ttr calendar events list --start 2026-06-11T00:00:00Z --end 2026-06-12T00:00:00Z
ttr calendar events get <event-id>
ttr calendar events create "Focus block" --start 2026-06-11T09:00:00+07:00 --duration-minutes 90
ttr calendar events update <event-id> --title "Focus block" --locked true
ttr calendar events delete <event-id>

# Default source and workspace calendar administration.
ttr calendar sources list
ttr calendar sources use --source-provider tuturuuu --calendar <calendar-id>
ttr calendar calendars create "Team" --color BLUE
ttr calendar calendars update <calendar-id> --name "Team Calendar"
ttr calendar calendars reset --yes

# Categories and provider connections.
ttr calendar categories create "Focus" --color BLUE
ttr calendar categories reorder --json-payload '{"categories":[{"id":"...","position":0}]}'
ttr calendar accounts list
ttr calendar auth google
ttr calendar auth microsoft
ttr calendar provider-calendars list --account <account-id>
ttr calendar connections create --calendar-id primary --calendar-name "Primary" --account <account-id>

# Scheduling.
ttr calendar schedule status
ttr calendar schedule tasks --q roadmap
ttr calendar schedule preview --window-days 14 --timezone Asia/Ho_Chi_Minh
ttr calendar schedule apply --mode safe-apply --scope impacted-only --window-days 14 --timezone Asia/Ho_Chi_Minh
```

Common task workflows:

```bash theme={null}
# List open tasks in the selected workspace.
ttr tasks

# List active boards only; pass --archived, --deleted, or --all for other states.
ttr boards

# Compact human output: task title, task list, and workspace.
ttr tasks --compact

# Machine-readable output for agents.
ttr tasks --json --no-update-check

# Ranked full-text, semantic, or hybrid search.
ttr tasks search "deadline review"
ttr tasks search "deadline review" --mode hybrid --limit 20 --threshold 0.25
ttr tasks search --query "deadline review" --mode text --json --no-update-check

# Create from the selected board/list, prompting when needed.
ttr tasks create "Add Tuturuuu CLI"

# Create directly into a known list.
ttr tasks create --list <list-id> --name "Write release notes"

# Create and use task templates.
ttr task-templates list
ttr task-templates create "Bug report" --key bug-report --title "Investigate bug" --priority high
ttr task-templates export bug-report --file .tuturuuu/task-templates/bug-report.md
ttr task-templates import .tuturuuu/task-templates/bug-report.md
ttr tiptap parse --text "| Field | Value |\n| --- | --- |\n| Owner | Platform |" --format markdown --output json
ttr tasks create --template bug-report --list <list-id> --name "Investigate checkout bug"
ttr tasks create "QA handoff" --description-file table.md --description-format markdown

# Move with the keyboard picker.
ttr tasks move

# Move directly to a done list.
ttr tasks move VHP-12 --list <done-list-id>

# Quick mark done and use the first done list on the task board when available.
ttr tasks done VHP-12

# Quick mark done with an explicit done destination.
ttr tasks done <task-id> --list <done-list-id>

# Quick mark closed and use the first closed list on the task board when available.
ttr tasks close VHP-12

# Quick mark closed with an explicit closed destination.
ttr tasks close <task-id> --list <closed-list-id>

# Mark completed and let Tuturuuu choose the default done list.
ttr tasks update VHP-12 --json-payload '{"completed":true}'

# Mark completed and choose a specific done destination.
ttr tasks update <task-id> --list <done-list-id> --json-payload '{"completed":true}'
```

For terminal workflows, omit an id from `use`, `get`, `update`, `delete`, or
`move` commands to pick a workspace, board, list, task, label, or project with
the keyboard. The interactive picker shows one-based indexes, colored badges
such as `[FREE] Tuturuuu` and `[PRO] Personal`, task-list color swatches, the
selected row, and muted metadata. Use up/down or `j`/`k` to move, space/enter to
select, and escape/`q` to cancel. Interactive selection is disabled for `--json`
output. Picker labels, descriptions, badges, and color names derived from
platform data must visibly escape terminal control characters before rendering.
Use `ttr -v` or `ttr --version` to print the installed CLI version.

## Client Initialization

### Basic Usage

```typescript theme={null}
const client = new TuturuuuClient('ttr_your_api_key');
```

### With Custom Configuration

```typescript theme={null}
const client = new TuturuuuClient({
  apiKey: 'ttr_your_api_key',
  baseUrl: 'https://tuturuuu.com/api/v1', // optional
  timeout: 30000 // optional, default 30s
});
```

## Storage API

### List Files

Lists files and folders in the workspace drive.

```typescript theme={null}
const files = await client.storage.list({
  path: 'documents', // folder path (optional)
  search: 'report', // search term (optional)
  limit: 50, // max results (optional, default 100)
  offset: 0, // pagination offset (optional)
  sortBy: 'created_at', // sort field (optional)
  sortOrder: 'desc' // sort direction (optional)
});

console.log(files.data); // Array of StorageObject
console.log(files.pagination); // Pagination info
```

### Upload File

Uploads a file to the workspace drive.

```typescript theme={null}
const file = new File(['content'], 'document.pdf');

const result = await client.storage.upload(file, {
  path: 'documents', // destination folder (optional)
  upsert: true // overwrite if exists (optional)
});

console.log(result.data.path); // Relative path
console.log(result.data.fullPath); // Full storage path
```

### Download File

Downloads a file as a Blob.

```typescript theme={null}
const blob = await client.storage.download('documents/report.pdf');

// Save to disk (Node.js)
const buffer = Buffer.from(await blob.arrayBuffer());
await fs.writeFile('report.pdf', buffer);

// Create download link (Browser)
const url = URL.createObjectURL(blob);
const a = document.createElement('a');
a.href = url;
a.download = 'report.pdf';
a.click();
```

Apply an image transform during download:

```typescript theme={null}
const blob = await client.storage.download('images/photo.png', {
  transform: {
    width: 320,
    height: 180,
    resize: 'cover',
    quality: 80
  }
});
```

### Delete Files

Deletes one or more files or folders.

```typescript theme={null}
const result = await client.storage.delete([
  'documents/old-report.pdf',
  'images/screenshot.png'
]);

console.log(result.data.deleted); // Number of files deleted
console.log(result.data.paths); // Array of deleted paths
```

### Create Folder

Creates a new folder in the workspace drive.

```typescript theme={null}
const result = await client.storage.createFolder(
  'documents', // parent path
  'reports' // folder name
);

console.log(result.data.path); // "documents/reports"
```

### Share File

Generates a signed URL for temporary file sharing.

```typescript theme={null}
const result = await client.storage.share('documents/report.pdf', {
  expiresIn: 3600 // 1 hour in seconds (default 3600, max 604800)
});

console.log(result.data.signedUrl); // Temporary URL
console.log(result.data.expiresAt); // ISO timestamp
console.log(result.data.expiresIn); // Seconds until expiration
```

Apply an image transform before generating the signed URL:

```typescript theme={null}
const result = await client.storage.share('images/photo.png', {
  expiresIn: 3600,
  transform: {
    width: 320,
    height: 180,
    resize: 'contain',
    quality: 85
  }
});
```

### Get Analytics

Retrieves storage usage statistics for the workspace.

```typescript theme={null}
const analytics = await client.storage.getAnalytics();

console.log(analytics.data.totalSize); // Total bytes used
console.log(analytics.data.fileCount); // Number of files
console.log(analytics.data.storageLimit); // Storage limit in bytes
console.log(analytics.data.usagePercentage); // Usage percentage
console.log(analytics.data.largestFile); // Largest file info
console.log(analytics.data.smallestFile); // Smallest file info
```

## Documents API

### List Documents

Lists documents in the workspace with optional filters.

```typescript theme={null}
const docs = await client.documents.list({
  search: 'meeting', // search in names (optional)
  limit: 20, // max results (optional, default 50)
  offset: 0, // pagination offset (optional)
  isPublic: false // filter by visibility (optional)
});

console.log(docs.data); // Array of Document
console.log(docs.pagination); // Pagination info
```

### Create Document

Creates a new document in the workspace.

```typescript theme={null}
const doc = await client.documents.create({
  name: 'Meeting Notes',
  content: {
    text: 'Discussion points...',
    attendees: ['Alice', 'Bob']
  },
  isPublic: false // optional, default false
});

console.log(doc.data.id); // Document ID
console.log(doc.data.name); // Document name
console.log(doc.data.content); // JSONB content
```

### Get Document

Retrieves a document by its ID.

```typescript theme={null}
const doc = await client.documents.get('document-id-123');

console.log(doc.data.name);
console.log(doc.data.content);
console.log(doc.data.created_at);
```

### Update Document

Updates an existing document.

```typescript theme={null}
const doc = await client.documents.update('document-id-123', {
  name: 'Updated Meeting Notes', // optional
  content: { text: 'New content' }, // optional
  isPublic: true // optional
});

console.log(doc.data); // Updated document
```

### Delete Document

Deletes a document permanently.

```typescript theme={null}
await client.documents.delete('document-id-123');
```

### Search Documents

Searches documents by name (alias for `list()` with search).

```typescript theme={null}
const results = await client.documents.search('meeting notes', {
  limit: 10,
  isPublic: false
});

console.log(results.data); // Matching documents
```

## CMS Delivery

The SDK also exposes the external-project delivery client that powers Tuturuuu CMS preview surfaces and branded external apps.

```typescript theme={null}
const delivery = await client.externalProjects.getDelivery('workspace-id');

if (delivery.loadingData?.adapter === 'yoola') {
  console.log(delivery.loadingData.featuredArtwork?.title);
  console.log(delivery.loadingData.singletonSections.about?.bodyMarkdown);
}

const yoolaLoadingData =
  await client.externalProjects.getYoolaLoadingData('workspace-id');
console.log(yoolaLoadingData.artworkCategories);
```

For the Yoola adapter, `artworkCategories` comes from the configured gallery taxonomy on `singleton-sections/gallery` (`profile_data.categoryOptions`) rather than being inferred from every artwork entry.

External app admin dashboards can auto-create and bind the workspace studio before their first diff/apply when the workspace ID is configured and the app token has `external-projects:*` or manage scope:

```typescript theme={null}
await client.externalProjects.sync.setup('workspace-id', { manifest });
```

Operators can use the authenticated CLI instead of app-local token scripts:

```bash theme={null}
ttr external projects summary --workspace <workspace-id> --json
ttr external projects delivery --workspace <workspace-id> --preview --out tmp/delivery.json
ttr external projects snapshot --workspace <workspace-id> --out tmp/snapshot.json
ttr external projects setup --workspace <workspace-id> --manifest external-project.json
ttr external projects diff --workspace <workspace-id> --manifest external-project.json --json
ttr external projects apply --workspace <workspace-id> --manifest external-project.json --confirm APPLY_EXTERNAL_PROJECT_SYNC
```

### Public Folder Asset Sync

External apps can keep seed media in their local `public/` folder and still publish it through Tuturuuu Drive. Mark each manifest asset with `metadata.publicPath`, `metadata.localAssetPath`, `metadata.sourcePublicPath`, or a relative `sourceUrl`.

```typescript theme={null}
import { linkExternalProjectPublicFolderAssets } from 'tuturuuu';
import { uploadExternalProjectPublicFolderAssets } from 'tuturuuu/external-projects/public-assets';

const linkedManifest = linkExternalProjectPublicFolderAssets(manifest);

const sync = await uploadExternalProjectPublicFolderAssets(
  client.externalProjects,
  'workspace-id',
  manifest,
  { publicDir: './public' }
);

console.log(sync.uploaded.length);
console.log(linkedManifest.content.entries[0]?.assets?.[0]?.storagePath);
```

The linker writes deterministic storage paths under `external-projects/{adapter}/{collectionSlug}/{entrySlug}/{filename}`. External apps can upload those assets through signed upload URLs, or through the external-project asset multipart route when they need the app server to stream the file with a server-owned bearer token. Production Supabase keys are not needed in external apps.

### TanStack Query

For React apps, keep the SDK as the delivery boundary and TanStack Query as the cache owner:

```typescript theme={null}
import { useQuery } from '@tanstack/react-query';
import {
  getEpmDeliveryQueryOptions,
  getYoolaLoadingDataQueryOptions
} from 'tuturuuu';

const deliveryQuery = useQuery({
  ...getEpmDeliveryQueryOptions(client.externalProjects, 'workspace-id'),
  staleTime: 60_000
});

const yoolaLoadingQuery = useQuery({
  ...getYoolaLoadingDataQueryOptions(client.externalProjects, 'workspace-id'),
  staleTime: 60_000
});
```

In external Next.js apps, prefer hydrating the delivery query once near the root layout and deriving page-level view models from that shared cache instead of letting each route perform its own SDK fetch.

## Error Handling

The SDK provides specific error classes for different scenarios:

```typescript theme={null}
import {
  AuthenticationError,
  AuthorizationError,
  NotFoundError,
  ConflictError,
  RateLimitError,
  NetworkError,
  ValidationError
} from 'tuturuuu';

try {
  await client.storage.upload(file);
} catch (error) {
  if (error instanceof AuthenticationError) {
    // Invalid or expired API key
    console.error('Authentication failed:', error.message);
  } else if (error instanceof AuthorizationError) {
    // Insufficient permissions
    console.error('Forbidden:', error.message);
  } else if (error instanceof NotFoundError) {
    // Resource not found
    console.error('Not found:', error.message);
  } else if (error instanceof ConflictError) {
    // Resource already exists
    console.error('Conflict:', error.message);
  } else if (error instanceof RateLimitError) {
    // Rate limit exceeded
    console.error('Rate limited:', error.message);
  } else if (error instanceof NetworkError) {
    // Network or timeout error
    console.error('Network error:', error.message);
  } else if (error instanceof ValidationError) {
    // Invalid input
    console.error('Validation error:', error.message);
  }
}
```

### Error Properties

All error classes include:

* `message` - Human-readable error description
* `code` - Machine-readable error code
* `statusCode` - HTTP status code
* `name` - Error class name

```typescript theme={null}
try {
  await client.storage.delete([]);
} catch (error) {
  if (error instanceof ValidationError) {
    console.log(error.message); // "At least one path is required"
    console.log(error.code); // "VALIDATION_ERROR"
    console.log(error.statusCode); // 400
    console.log(error.name); // "ValidationError"
  }
}
```

## TypeScript Support

The SDK is fully typed with TypeScript:

```typescript theme={null}
import type {
  StorageObject,
  Document,
  ListStorageOptions,
  UploadOptions,
  ShareOptions,
  CreateDocumentData,
  UpdateDocumentData,
  ListDocumentsOptions
} from 'tuturuuu';

// Type-safe options
const options: ListStorageOptions = {
  path: 'documents',
  sortBy: 'created_at',
  sortOrder: 'desc'
};

// Type-safe document data
const docData: CreateDocumentData = {
  name: 'My Doc',
  content: { text: 'Content' },
  isPublic: false
};
```

## API Key Management

### Creating an API Key

1. Log in to your Tuturuuu workspace
2. Navigate to **Settings** → **API Keys**
3. Click **"Create API Key"**
4. Set a descriptive name
5. Assign a **Workspace Role** (determines permissions)
6. Optionally set an expiration date
7. Copy the generated key (starts with `ttr_`)
8. Store securely (you won't see it again)

### Best Practices

<Warning>
  **Never commit API keys to version control!** Use environment variables or
  secret management services.
</Warning>

```bash theme={null}
# .env
TUTURUUU_API_KEY=ttr_your_api_key_here
```

```typescript theme={null}
// app.ts
const client = new TuturuuuClient(process.env.TUTURUUU_API_KEY!);
```

### Permissions

API keys inherit permissions from their assigned **Workspace Role**. The role determines what operations the key can perform.

**Required Permissions:**

| Operation                                                                      | Required Role Permission             |
| ------------------------------------------------------------------------------ | ------------------------------------ |
| Storage Operations (list, upload, download, delete, folders, share, analytics) | `manage_drive`                       |
| Document Operations (list, create, get, update, delete, search)                | `manage_documents`                   |
| API Key Management                                                             | `manage_api_keys` (Owner/Admin only) |

**Note:** Permissions are managed through workspace roles, not individual API keys. To modify what an API key can do, update its assigned role's permissions in **Settings** → **Roles**.

## Security Best Practices

<Warning>
  **CRITICAL: Never expose API keys in client-side code!** API keys must remain
  server-side only.
</Warning>

### ❌ Insecure (NEVER do this)

```typescript theme={null}
// BAD: Exposes API key to browser!
'use client'; // Client component

const client = new TuturuuuClient(process.env.NEXT_PUBLIC_API_KEY);
// ❌ Anyone can inspect network requests and steal your key!
```

### ✅ Secure (Recommended patterns)

#### Next.js App Router (Recommended)

Create server-side API routes that proxy SDK calls:

```typescript theme={null}
// app/api/storage/list/route.ts (SERVER-SIDE)
import { TuturuuuClient } from 'tuturuuu';
import { NextResponse } from 'next/server';

const client = new TuturuuuClient(process.env.TUTURUUU_API_KEY);

export async function GET(request: Request) {
  const { searchParams } = new URL(request.url);
  const path = searchParams.get('path') || '';

  const files = await client.storage.list({ path, limit: 50 });
  return NextResponse.json(files);
}
```

Then call from your client component:

```typescript theme={null}
// app/components/FileList.tsx (CLIENT COMPONENT - SAFE)
'use client';

export function FileList() {
  const [files, setFiles] = useState([]);

  useEffect(() => {
    fetch('/api/storage/list?path=documents')
      .then(res => res.json())
      .then(setFiles);
  }, []);

  return <div>{/* Render files */}</div>;
}
```

#### Node.js/Express Backend

```typescript theme={null}
// server.js
import { TuturuuuClient } from 'tuturuuu';
import express from 'express';

const client = new TuturuuuClient(process.env.TUTURUUU_API_KEY);
const app = express();

app.get('/api/files', async (req, res) => {
  const files = await client.storage.list();
  res.json(files);
});

app.listen(3000);
```

#### Serverless Functions (Netlify, Vercel, AWS Lambda)

```typescript theme={null}
// netlify/functions/storage.ts
import { TuturuuuClient } from 'tuturuuu';

export const handler = async (event) => {
  const client = new TuturuuuClient(process.env.TUTURUUU_API_KEY);
  const files = await client.storage.list();

  return {
    statusCode: 200,
    body: JSON.stringify(files)
  };
};
```

### Security Checklist

<AccordionGroup>
  <Accordion title="✅ DO: Use server-side code">
    Always use the SDK in server-side contexts:

    * Next.js API Routes (App Router or Pages Router)
    * Node.js backend servers
    * Serverless functions
    * Server Components (React Server Components)
  </Accordion>

  <Accordion title="✅ DO: Use environment variables">
    Store API keys in environment variables:

    ```bash theme={null}
    # .env.local (server-side only)
    TUTURUUU_API_KEY=ttr_your_key_here
    TUTURUUU_BASE_URL=https://tuturuuu.com/api/v1
    ```

    **Never** use `NEXT_PUBLIC_` prefix for API keys!
  </Accordion>

  <Accordion title="✅ DO: Add .env.local to .gitignore">
    Ensure secrets never get committed: `gitignore # .gitignore .env.local
          .env*.local `
  </Accordion>

  <Accordion title="❌ DON'T: Use NEXT_PUBLIC_ prefix">
    This exposes the variable to the browser: `bash # BAD - Exposed to client!
          NEXT_PUBLIC_TUTURUUU_API_KEY=ttr_key `
  </Accordion>

  <Accordion title="❌ DON'T: Import SDK in client components">
    Never import the SDK in files with `'use client'` directive.
  </Accordion>

  <Accordion title="❌ DON'T: Hardcode API keys">
    Never commit keys to version control:

    ```typescript theme={null}
    // BAD
    const client = new TuturuuuClient('ttr_1234567890abcdef');
    ```
  </Accordion>
</AccordionGroup>

### Complete Example

See the [external app example](https://github.com/tutur3u/platform/tree/main/apps/external) for a complete implementation showcasing:

* ✅ Secure server-side API routes
* ✅ File upload with progress
* ✅ Storage analytics dashboard
* ✅ Proper error handling
* ✅ Environment variable configuration

## Rate Limiting

The API enforces rate limits per API key to ensure fair usage and system stability:

### Rate Limits by Operation

| Operation            | Limit        | Window     |
| -------------------- | ------------ | ---------- |
| Storage Upload       | 20 requests  | per minute |
| Storage Download     | 50 requests  | per minute |
| Signed Upload URLs   | 30 requests  | per minute |
| All Other Operations | 100 requests | per minute |

### Rate Limit Headers

Every API response includes rate limit information in the headers:

* `X-RateLimit-Limit` - Maximum requests allowed in the time window
* `X-RateLimit-Remaining` - Number of requests remaining in current window
* `X-RateLimit-Reset` - Unix timestamp when the rate limit resets

```typescript theme={null}
const result = await client.storage.list();

// Access rate limit info from headers (if using direct API calls)
console.log('Limit:', result.headers.get('X-RateLimit-Limit'));
console.log('Remaining:', result.headers.get('X-RateLimit-Remaining'));
console.log(
  'Resets at:',
  new Date(Number.parseInt(result.headers.get('X-RateLimit-Reset')) * 1000)
);
```

### Handling Rate Limits

When you exceed the rate limit, the API returns a `429 Too Many Requests` response:

```typescript theme={null}
try {
  await client.storage.upload(file);
} catch (error) {
  if (error instanceof RateLimitError) {
    console.error('Rate limited! Try again later.');
    console.error('Retry after:', error.retryAfter, 'seconds');

    // Implement exponential backoff
    await new Promise((resolve) =>
      setTimeout(resolve, error.retryAfter * 1000)
    );
  }
}
```

### Workspace-Specific Rate Limits

Workspace administrators can configure custom rate limits for their workspace through **Workspace Secrets**. These override the default limits for all API keys in that workspace.

To set custom rate limits:

1. Navigate to **Settings** → **Workspace Settings** → **Secrets**
2. Add one or more of these secrets:

| Secret Name               | Description                 | Example Value              |
| ------------------------- | --------------------------- | -------------------------- |
| `RATE_LIMIT_WINDOW_MS`    | Time window in milliseconds | `60000` (1 minute)         |
| `RATE_LIMIT_MAX_REQUESTS` | Max requests per window     | `200` (double the default) |

**Example Configuration:**

```
RATE_LIMIT_WINDOW_MS = 60000
RATE_LIMIT_MAX_REQUESTS = 500
```

This configuration allows 500 requests per minute for all API keys in the workspace, instead of the default 100.

<Note>
  Workspace-specific rate limits only apply to operations that don't have
  explicit per-operation limits. For operations like uploads and downloads, the
  operation-specific limits still apply.
</Note>

### Best Practices

<Tip>
  **Implement exponential backoff** when handling rate limits to avoid hammering
  the API with retries.
</Tip>

```typescript theme={null}
async function uploadWithRetry(file: File, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      return await client.storage.upload(file);
    } catch (error) {
      if (error instanceof RateLimitError && attempt < maxRetries - 1) {
        // Exponential backoff: 1s, 2s, 4s
        const delay = Math.pow(2, attempt) * 1000;
        await new Promise((resolve) => setTimeout(resolve, delay));
        continue;
      }
      throw error;
    }
  }
}
```

<Tip>
  **Monitor rate limit headers** to track your usage and avoid hitting limits:

  ```typescript theme={null}
  // Check remaining requests after each call
  const response = await fetch('https://tuturuuu.com/api/v1/storage/list', {
    headers: { 'Authorization': `Bearer ${apiKey}` }
  });

  const remaining = response.headers.get('X-RateLimit-Remaining');
  const limit = response.headers.get('X-RateLimit-Limit');

  console.log(`API calls remaining: ${remaining}/${limit}`);

  // Slow down if close to limit
  if (Number(remaining) < Number(limit) \* 0.1) {
  await new Promise(resolve => setTimeout(resolve, 1000));
  }

  ```
</Tip>

## Examples

<CardGroup>
  <Card title="Basic Usage" icon="play" href="https://github.com/tutur3u/platform/blob/main/packages/sdk/examples/basic-usage.ts">
    Complete example of all SDK operations
  </Card>

  <Card title="Error Handling" icon="triangle-exclamation" href="https://github.com/tutur3u/platform/blob/main/packages/sdk/examples/error-handling.ts">
    Comprehensive error handling patterns
  </Card>
</CardGroup>

## Support

<CardGroup>
  <Card title="GitHub" icon="github" href="https://github.com/tutur3u/platform">
    Source code and issues
  </Card>

  <Card title="Discord" icon="discord" href="https://discord.gg/tuturuuu">
    Community support
  </Card>

  <Card title="Docs" icon="book" href="https://docs.tuturuuu.com">
    Full documentation
  </Card>
</CardGroup>

## Changelog

The package version is managed by Release Please, and the full, authoritative
changelog is generated per release. For the complete history (currently shipping
the `0.10.x` line), see the maintained changelog rather than this page:

<CardGroup>
  <Card title="CHANGELOG.md" icon="github" href="https://github.com/tutur3u/platform/blob/main/packages/sdk/CHANGELOG.md">
    Full per-release changelog (source of truth)
  </Card>

  <Card title="npm" icon="npm" href="https://www.npmjs.com/package/tuturuuu">
    Published versions and release tags
  </Card>
</CardGroup>

**Highlights since the initial release:**

* Storage operations (list, upload, download, delete, folders, share, analytics)
* Document operations (CRUD, search)
* `ttr` CLI with workspace, host switching, and session-based auth
* Finance commands (wallets, transactions, transfers, tags, wallet checkpoints)
* Calendar commands
* External projects support and remote devbox tooling
* Comprehensive error handling, full TypeScript types, and Zod validation

<Note>
  Do not treat any version number quoted in this page as exact — the SDK is on a
  fast release cadence. Always check the linked changelog or npm for the current
  version.
</Note>

## License

MIT


# @tuturuuu/supabase
Source: https://docs.tuturuuu.com/reference/packages/supabase

Supabase client creation patterns and utilities

# @tuturuuu/supabase

The `@tuturuuu/supabase` package provides type-safe Supabase client utilities for the Tuturuuu platform with different privilege levels and execution contexts.

## Installation

```bash theme={null}
# Already included in monorepo workspace
import { createClient, createAdminClient } from '@tuturuuu/supabase/next/server';
```

## Client Types

### `createClient()` - User-Scoped Client

**Use Case:** Standard operations respecting Row-Level Security (RLS) policies.

**Context:** Server Components, Server Actions, API Routes

**Privilege Level:** Current authenticated user

```typescript theme={null}
import { createClient } from '@tuturuuu/supabase/next/server';

export default async function TaskPage() {
  const supabase = await createClient();

  // Queries respect RLS policies
  const { data: tasks } = await supabase
    .from('workspace_tasks')
    .select('*')
    .eq('ws_id', 'workspace-id');

  // User can only see tasks they have permission to view
  return <div>{tasks?.length} tasks</div>;
}
```

**Important:**

* ✅ Respects RLS policies
* ✅ Safe for user-initiated operations
* ❌ Cannot bypass workspace isolation
* ❌ Cannot perform privileged operations

### `createAdminClient()` - Service Role Client

**Use Case:** Privileged operations bypassing RLS (admin tasks, system operations).

**Context:** Server-side only (never expose to client)

**Privilege Level:** Service role (bypasses RLS)

```typescript theme={null}
import { createAdminClient } from '@tuturuuu/supabase/next/server';

export async function createWorkspace(name: string, ownerId: string) {
  const sbAdmin = await createAdminClient();

  // Bypasses RLS - can insert into any workspace
  const { data: workspace } = await sbAdmin
    .from('workspaces')
    .insert({ name })
    .select()
    .single();

  // Add owner as member
  await sbAdmin
    .from('workspace_members')
    .insert({
      ws_id: workspace.id,
      user_id: ownerId,
      role: 'owner',
    });

  return workspace;
}
```

**⚠️ Critical Security Warning:**

* ✅ Only use server-side
* ✅ Only for privileged operations
* ❌ NEVER expose to client
* ❌ NEVER use for user-initiated queries (always prefer `createClient()`)

> **Return type note:** `createAdminClient()` has the signature
> `({ noCookie }?: { noCookie?: boolean }) => SupabaseClient | Promise<SupabaseClient>`.
> The default call (`createAdminClient()` with `noCookie: false`) resolves cookies
> via `next/headers`, so it returns a `Promise` — `await` it as shown above. The
> `createAdminClient({ noCookie: true })` variant returns a client synchronously.
> Awaiting either form is safe (`await` on a non-Promise is a no-op), so prefer
> `await createAdminClient()` everywhere for consistency.

### `createDynamicClient()` - Middleware Client

**Use Case:** Middleware and edge runtime contexts.

**Context:** Next.js middleware, edge functions

```typescript theme={null}
import { createDynamicClient } from '@tuturuuu/supabase/next/server';
import { NextRequest } from 'next/server';

export async function proxy(request: NextRequest) {
  const supabase = await createDynamicClient();

  const { data: { user } } = await supabase.auth.getUser();

  if (!user) {
    return Response.redirect('/login');
  }
}
```

## Common Patterns

### Authentication

#### Revalidated Session User

Use `resolveAuthenticatedSessionUser()` from
`@tuturuuu/supabase/next/auth-session-user` when shared server code needs the
current Supabase session user. The helper may probe `auth.getClaims()` for
compatibility or timing context, but it must revalidate the session with
`auth.getUser()` before returning a user.

Treat JWT claims as verified token contents, not current account state. Do not
authorize privileged routes, staff-only checks, or `createAdminClient()` flows
from claim-derived `email`, `role`, or metadata alone. For those paths, make the
authorization decision from the Auth-server user returned by `getUser()` so
revoked, deleted, or offboarded sessions are rejected before any service-role
operation runs.

#### Get Current User

```typescript theme={null}
import { createClient } from '@tuturuuu/supabase/next/server';

export async function getCurrentUser() {
  const supabase = await createClient();
  const { data: { user }, error } = await supabase.auth.getUser();

  if (error || !user) {
    return null;
  }

  return user;
}
```

#### Server Action with Auth Check

```typescript theme={null}
'use server';

import { createClient } from '@tuturuuu/supabase/next/server';

export async function createTask(formData: FormData) {
  const supabase = await createClient();

  // Check authentication
  const { data: { user } } = await supabase.auth.getUser();
  if (!user) {
    throw new Error('Unauthorized');
  }

  // Perform operation (RLS policies apply)
  const { data, error } = await supabase
    .from('workspace_tasks')
    .insert({
      name: formData.get('name') as string,
      ws_id: formData.get('wsId') as string,
      created_by: user.id,
    })
    .select()
    .single();

  if (error) throw error;
  return data;
}
```

### Workspace Operations

#### Get User's Workspaces

```typescript theme={null}
import { createClient } from '@tuturuuu/supabase/next/server';

export async function getUserWorkspaces(userId: string) {
  const supabase = await createClient();

  const { data: memberships } = await supabase
    .from('workspace_members')
    .select(`
      ws_id,
      role,
      pending,
      workspaces (
        id,
        name,
        logo_url
      )
    `)
    .eq('user_id', userId)
    .eq('pending', false);

  return memberships?.map((m) => m.workspaces) || [];
}
```

#### Check Workspace Permission

```typescript theme={null}
import { createClient } from '@tuturuuu/supabase/next/server';
import type { Database } from '@tuturuuu/types';

type Permission = Database['public']['Enums']['workspace_role_permission'];

export async function hasPermission(
  userId: string,
  wsId: string,
  permission: Permission
): Promise<boolean> {
  const supabase = await createClient();

  const { data } = await supabase
    .from('workspace_members')
    .select(`
      role,
      workspace_role_permissions!inner (
        permission
      )
    `)
    .eq('user_id', userId)
    .eq('ws_id', wsId)
    .eq('workspace_role_permissions.permission', permission)
    .limit(1);

  return (data?.length || 0) > 0;
}
```

### Data Fetching

#### Paginated Query

```typescript theme={null}
import { createClient } from '@tuturuuu/supabase/next/server';

export async function getTasks(wsId: string, page = 0, pageSize = 20) {
  const supabase = await createClient();

  const from = page * pageSize;
  const to = from + pageSize - 1;

  const { data: tasks, error, count } = await supabase
    .from('workspace_tasks')
    .select('*', { count: 'exact' })
    .eq('ws_id', wsId)
    .order('created_at', { ascending: false })
    .range(from, to);

  if (error) throw error;

  return {
    tasks,
    totalCount: count,
    currentPage: page,
    totalPages: Math.ceil((count || 0) / pageSize),
  };
}
```

#### Filtered Query with Relations

```typescript theme={null}
import { createClient } from '@tuturuuu/supabase/next/server';

export async function getTasksWithAssignees(wsId: string, completed?: boolean) {
  const supabase = await createClient();

  let query = supabase
    .from('workspace_tasks')
    .select(`
      *,
      task_assignees (
        workspace_users (
          id,
          display_name,
          avatar_url
        )
      ),
      task_lists (
        id,
        name
      )
    `)
    .eq('ws_id', wsId);

  if (completed !== undefined) {
    query = query.eq('completed', completed);
  }

  const { data, error } = await query;
  if (error) throw error;

  return data;
}
```

### Realtime Subscriptions

The browser `createClient()` from `@tuturuuu/supabase/next/client` is
**synchronous** (returns a `SupabaseClient`, not a `Promise`), so it is used
without `await`. Note this client is deprecated for general CRUD/storage — route
those through `@tuturuuu/internal-api` — but it remains valid for realtime
channel subscriptions, which are not covered by the internal API client.

```typescript theme={null}
'use client';

import { createClient } from '@tuturuuu/supabase/next/client';
import { useEffect, useState } from 'react';
import type { Database } from '@tuturuuu/types';

type Task = Database['public']['Tables']['workspace_tasks']['Row'];

export function useTaskSubscription(wsId: string) {
  const [tasks, setTasks] = useState<Task[]>([]);
  const supabase = createClient();

  useEffect(() => {
    // Initial fetch
    supabase
      .from('workspace_tasks')
      .select('*')
      .eq('ws_id', wsId)
      .then(({ data }) => setTasks(data || []));

    // Subscribe to changes
    const channel = supabase
      .channel(`workspace-tasks-${wsId}`)
      .on(
        'postgres_changes',
        {
          event: '*',
          schema: 'public',
          table: 'workspace_tasks',
          filter: `ws_id=eq.${wsId}`,
        },
        (payload) => {
          if (payload.eventType === 'INSERT') {
            setTasks((prev) => [...prev, payload.new as Task]);
          } else if (payload.eventType === 'UPDATE') {
            setTasks((prev) =>
              prev.map((task) =>
                task.id === payload.new.id ? (payload.new as Task) : task
              )
            );
          } else if (payload.eventType === 'DELETE') {
            setTasks((prev) => prev.filter((task) => task.id !== payload.old.id));
          }
        }
      )
      .subscribe();

    return () => {
      channel.unsubscribe();
    };
  }, [wsId]);

  return tasks;
}
```

## Type Safety

### Using Generated Types

```typescript theme={null}
import type { Database } from '@tuturuuu/types';
import { createClient } from '@tuturuuu/supabase/next/server';

type Task = Database['public']['Tables']['workspace_tasks']['Row'];
type TaskInsert = Database['public']['Tables']['workspace_tasks']['Insert'];
type TaskUpdate = Database['public']['Tables']['workspace_tasks']['Update'];

export async function createTypedTask(task: TaskInsert): Promise<Task> {
  const supabase = await createClient();

  const { data, error } = await supabase
    .from('workspace_tasks')
    .insert(task)
    .select()
    .single();

  if (error) throw error;
  return data;
}
```

### Custom Type Helpers

```typescript theme={null}
import type { Database } from '@tuturuuu/types';

// Extract table types
export type Tables<T extends keyof Database['public']['Tables']> =
  Database['public']['Tables'][T]['Row'];

export type Enums<T extends keyof Database['public']['Enums']> =
  Database['public']['Enums'][T];

// Usage
type Task = Tables<'workspace_tasks'>;
type Permission = Enums<'workspace_role_permission'>;
```

## Error Handling

### Standard Pattern

```typescript theme={null}
import { createClient } from '@tuturuuu/supabase/next/server';

export async function getTask(taskId: string) {
  const supabase = await createClient();

  const { data, error } = await supabase
    .from('workspace_tasks')
    .select('*')
    .eq('id', taskId)
    .single();

  if (error) {
    console.error('Failed to fetch task:', error);
    throw new Error(`Task not found: ${taskId}`);
  }

  return data;
}
```

### With Try-Catch

```typescript theme={null}
import { createClient } from '@tuturuuu/supabase/next/server';

export async function safeGetTask(taskId: string) {
  try {
    const supabase = await createClient();

    const { data, error } = await supabase
      .from('workspace_tasks')
      .select('*')
      .eq('id', taskId)
      .single();

    if (error) throw error;
    return { data, error: null };
  } catch (error) {
    console.error('Error fetching task:', error);
    return { data: null, error };
  }
}
```

## Storage Operations

### Upload File

```typescript theme={null}
import { createClient } from '@tuturuuu/supabase/next/server';

export async function uploadAvatar(userId: string, file: File) {
  const supabase = await createClient();

  const fileName = `${userId}-${Date.now()}.${file.name.split('.').pop()}`;
  const filePath = `avatars/${fileName}`;

  const { data, error } = await supabase.storage
    .from('public')
    .upload(filePath, file, {
      cacheControl: '3600',
      upsert: false,
    });

  if (error) throw error;

  const { data: { publicUrl } } = supabase.storage
    .from('public')
    .getPublicUrl(filePath);

  return publicUrl;
}
```

### Download File

```typescript theme={null}
import { createClient } from '@tuturuuu/supabase/next/server';

export async function downloadFile(path: string) {
  const supabase = await createClient();

  const { data, error } = await supabase.storage
    .from('public')
    .download(path);

  if (error) throw error;
  return data; // Blob
}
```

## Best Practices

### ✅ DO

1. **Use `createClient()` by default**
   ```typescript theme={null}
   const supabase = await createClient(); // Respects RLS
   ```

2. **Check authentication early**
   ```typescript theme={null}
   const { data: { user } } = await supabase.auth.getUser();
   if (!user) throw new Error('Unauthorized');
   ```

3. **Handle errors explicitly**
   ```typescript theme={null}
   const { data, error } = await supabase.from('table').select();
   if (error) throw error;
   ```

4. **Use TypeScript types**
   ```typescript theme={null}
   import type { Database } from '@tuturuuu/types';
   ```

5. **Limit data fetching**
   ```typescript theme={null}
   .select('id, name, created_at') // Only needed fields
   .limit(20) // Pagination
   ```

### ❌ DON'T

1. **Never use `createAdminClient()` for user operations**
   ```typescript theme={null}
   // ❌ Bad: Bypasses RLS
   const sbAdmin = await createAdminClient();
   const tasks = await sbAdmin.from('workspace_tasks').select();
   ```

2. **If you must use `createAdminClient()`, enforce membership and RBAC before the admin-backed operation**
   ```typescript theme={null}
   const member = await verifyWorkspaceMembershipType({
     wsId,
     userId: user.id,
     supabase: requestScopedSupabase,
   });
   if (!member.ok) {
     return NextResponse.json({ error: 'Forbidden' }, { status: 403 });
   }

   const permissions = await getPermissions({ wsId, user });
   if (!permissions?.containsPermission('manage_projects')) {
     return NextResponse.json(
       { error: "You don't have permission" },
       { status: 403 }
     );
   }
   ```

3. **Keep workspace-scoped admin mutations filtered by workspace ID**
   ```typescript theme={null}
   await sbAdmin
     .from('workspace_boards')
     .update({ deleted_at: new Date().toISOString() })
     .eq('id', boardId)
     .eq('ws_id', wsId);
   ```

4. **Don't expose service role key**
   ```typescript theme={null}
   // ❌ Bad: Never do this
   const client = createClient(process.env.SUPABASE_SECRET_KEY);
   ```

5. **Don't ignore errors**
   ```typescript theme={null}
   // ❌ Bad: Silent failure
   const { data } = await supabase.from('table').select();
   return data; // Could be null!
   ```

6. **Don't fetch unnecessary data**
   ```typescript theme={null}
   // ❌ Bad: Over-fetching
   .select('*')
   .order('created_at')
   // No limit!
   ```

## Testing

### Mock Supabase Client

```typescript theme={null}
// __mocks__/@tuturuuu/supabase/next/server.ts
export const createClient = vi.fn(() => ({
  from: vi.fn(() => ({
    select: vi.fn(() => ({
      eq: vi.fn(() => ({
        single: vi.fn(() => Promise.resolve({ data: mockData, error: null })),
      })),
    })),
  })),
  auth: {
    getUser: vi.fn(() =>
      Promise.resolve({ data: { user: mockUser }, error: null })
    ),
  },
}));
```

### Test Example

```typescript theme={null}
import { describe, it, expect, vi } from 'vitest';
import { getTask } from './tasks';

vi.mock('@tuturuuu/supabase/next/server');

describe('getTask', () => {
  it('should fetch task by ID', async () => {
    const task = await getTask('task-123');
    expect(task).toBeDefined();
    expect(task.id).toBe('task-123');
  });
});
```

## Related Documentation

* [Database Schema](/reference/database/schema-overview)
* [RLS Policies](/reference/database/rls-policies)
* [Authentication](/platform/architecture/authentication)
* [Authorization](/platform/architecture/authorization)

## External Resources

* [Supabase JavaScript Client Docs](https://supabase.com/docs/reference/javascript/introduction)
* [Supabase Auth Helpers](https://supabase.com/docs/guides/auth/auth-helpers/nextjs)


# @tuturuuu/trigger
Source: https://docs.tuturuuu.com/reference/packages/trigger

Calendar provider-sync and scheduling helpers

# @tuturuuu/trigger

`@tuturuuu/trigger` is the historical package name for Tuturuuu's reusable
Calendar provider-sync and scheduling helpers. It does not depend on or deploy
to Trigger.dev.

Production recurring work is scheduled by Vercel Cron. The cron route owns
authentication, cadence, observability, and orchestration; this package owns
the testable provider and scheduling operations invoked by that route.

## Calendar provider sync

Use the direct helpers from a server-only route or service:

```ts theme={null}
import { performFullSyncForWorkspace } from "@tuturuuu/trigger/google-calendar-full-sync";
import { performIncrementalSyncForWorkspace } from "@tuturuuu/trigger/google-calendar-incremental-sync";

await performIncrementalSyncForWorkspace(
  calendarId,
  workspaceId,
  accessToken,
  refreshToken,
);
```

The lower-level `google-calendar-sync` export contains token persistence,
Google event normalization, and batched database synchronization.

## Scheduling helpers

The package also exposes `schedulableTasksHelper` and
`unifiedScheduleHelper`. Call these from authenticated server routes rather
than adding another scheduler:

```ts theme={null}
import {
  schedulableTasksHelper,
  unifiedScheduleHelper,
} from "@tuturuuu/trigger";

await schedulableTasksHelper(workspaceId);
await unifiedScheduleHelper(workspaceId, {
  windowDays: 30,
  forceReschedule: false,
});
```

## Cron ownership

Calendar provider sync is configured in `apps/web/cron.config.json` and served
through `/api/cron/calendar/provider-sync`. Keep `apps/web/vercel.json`
generated from that configuration with:

```bash theme={null}
node scripts/sync-web-crons.js
```

Do not add task-runner wrappers, provider-specific recurring jobs, or a second
source of cadence inside this package.

## Validation

```bash theme={null}
bun run --filter @tuturuuu/trigger test
bun run --filter @tuturuuu/trigger type-check
```


# @tuturuuu/utils/effect
Source: https://docs.tuturuuu.com/reference/packages/utils-effect

Curated Effect entrypoint and Tuturuuu error helpers

# @tuturuuu/utils/effect

`@tuturuuu/utils/effect` is the platform entrypoint for [Effect](https://effect.website/docs/quickstart).
It keeps Effect adoption consistent across Tuturuuu apps and services while
preserving existing React, TanStack Query, Zod, and Supabase conventions.

```ts theme={null}
import {
  Effect,
  fromDataError,
  runEffectAsResult,
  TuturuuuEffectError,
} from '@tuturuuu/utils/effect';
```

## Exports

The entrypoint re-exports the Effect modules that Tuturuuu code should use by
default:

* `Effect`
* `Data`
* `Context`
* `Layer`
* `Schedule`
* `Duration`
* `Option`
* `Either`
* `Cause`

It also exports Tuturuuu helpers:

* `TuturuuuEffectError`
* `toTuturuuuEffectError`
* `serializeTuturuuuEffectError`
* `fromDataError`
* `fromPromise`
* `withTuturuuuRetry`
* `withTuturuuuTimeout`
* `forEachConcurrently`
* `runEffectAsResult`

## Expected Errors

Use `TuturuuuEffectError` for expected, typed failures that can cross a
server/action/API boundary in a sanitized shape.

```ts theme={null}
import { Effect, TuturuuuEffectError } from '@tuturuuu/utils/effect';

const requireWorkspace = (wsId?: string) =>
  wsId
    ? Effect.succeed(wsId)
    : Effect.fail(
        new TuturuuuEffectError({
          code: 'WORKSPACE_REQUIRED',
          message: 'Workspace ID is required.',
          status: 400,
        })
      );
```

## Supabase-Style Results

Use `fromDataError` for APIs that return `{ data, error }`, including Supabase
queries and RPC calls.

```ts theme={null}
const program = fromDataError(
  () =>
    supabase
      .from('workspaces')
      .select('id')
      .eq('id', wsId)
      .maybeSingle(),
  {
    code: 'WORKSPACE_READ_FAILED',
    message: 'Workspace read failed.',
    context: { wsId },
  }
);
```

`fromDataError` preserves service-specific `code`, `message`, `details`, and
`hint` fields when present, then falls back to the provided Tuturuuu metadata.

## Promise Results

Use `fromPromise` for async work that can throw or reject.

```ts theme={null}
const response = fromPromise(
  () => fetch(url, { cache: 'no-store' }),
  {
    code: 'UPSTREAM_REQUEST_FAILED',
    message: 'Upstream request failed.',
    context: { url },
  }
);
```

`fromPromise` receives the Effect-managed `AbortSignal`. Pass it into
`fetch`, SDK calls, or other abortable APIs so timeouts and fiber interruption
can cancel the underlying work.

## Retry And Timeout

Use `withTuturuuuRetry` and `withTuturuuuTimeout` when a server/service workflow
needs explicit resilience policy with Tuturuuu error metadata.

```ts theme={null}
const resilient = withTuturuuuRetry(
  withTuturuuuTimeout(response, {
    code: 'UPSTREAM_TIMEOUT',
    duration: '10 seconds',
    message: 'Upstream timed out.',
  }),
  {
    times: 2,
    delay: '250 millis',
    while: (error) => error.code === 'UPSTREAM_REQUEST_FAILED',
  }
);
```

Keep retry predicates narrow. Retry transient network, timeout, and temporary
upstream failures. Do not retry validation, permission, or tenant-boundary
errors unless the domain package documents idempotency.

## Controlled Concurrency

Use `forEachConcurrently` for bounded parallel work. It defaults to Tuturuuu's
shared concurrency value and can be tightened per service.

```ts theme={null}
const enrichedRows = forEachConcurrently(
  rows,
  (row) => enrichRowEffect(row),
  { concurrency: 4 }
);
```

## Boundary Conversion

Use `runEffectAsResult` at route, action, or helper boundaries that already
return result objects.

```ts theme={null}
const result = await runEffectAsResult(program);

if (!result.ok) {
  return Response.json({ error: result.error.message }, { status: 500 });
}

return Response.json(result.data);
```

Do not expose raw upstream diagnostics, secrets, URLs with credentials, stack
traces, or filesystem paths in public responses. Add safe metadata to
`context`, and keep detailed diagnostics in the existing server logging path.