Tuturuuu Platform
Tuturuuu is an open-source intelligent workspace platform for modern work and
life. It brings tasks, calendars, meetings, documents, storage, finance,
inventory, learning, automation, and AI-assisted workflows into one connected
operating layer.
The goal is to reduce digital friction: capture what matters, clarify the next
action, keep teams in sync, and let software handle more of the coordination
load. This monorepo contains the apps, shared packages, mobile client, SDK,
CLI, documentation, local services, and deployment tooling behind that system.
Migration Progress
Generated from apps/tanstack-web/migration/route-manifest.json. Refresh with bun migration:tanstack:readme after route ownership changes.
| Track | Progress | Terminal | Migrated | Removed | Remaining |
|---|
| Overall | [#####---------------] 26.41% | 230 / 871 | 216 | 14 | 641 |
| Rust backend | [##------------------] 12.44% | 80 / 643 | 68 | 12 | 563 |
| TanStack Start | [#############-------] 65.79% | 150 / 228 | 148 | 2 | 78 |
| Kind | Progress | Terminal | Remaining |
|---|
| api | [##--------------] 11.94% | 75 / 628 | 553 |
| page | [##########------] 64.74% | 101 / 156 | 55 |
| layout | [###########-----] 69.12% | 47 / 68 | 21 |
| cron | [###-------------] 20% | 2 / 10 | 8 |
| route-handler | [############----] 75% | 3 / 4 | 1 |
| error | [########--------] 50% | 1 / 2 | 1 |
| loading | [----------------] 0% | 0 / 1 | 1 |
| trpc | [----------------] 0% | 0 / 1 | 1 |
| not-found | [################] 100% | 1 / 1 | 0 |
| Route | Owner | Methods | Source |
|---|
/api/ai/chat | Rust backend | POST | apps/web/src/legacy-api-routes/ai/chat/route.ts |
/api/ai/chat/delete-file | Rust backend | POST | apps/web/src/legacy-api-routes/ai/chat/delete-file/route.ts |
/api/ai/chat/file-urls | Rust backend | POST | apps/web/src/legacy-api-routes/ai/chat/file-urls/route.ts |
/api/ai/chat/google | Rust backend | POST | apps/web/src/legacy-api-routes/ai/chat/google/route.ts |
/api/ai/chat/google/new | Rust backend | POST | apps/web/src/legacy-api-routes/ai/chat/google/new/route.ts |
What Tuturuuu Builds
| Product layer | What it does | Where to start |
|---|
| Command Center | Daily workspace view for tasks, appointments, reminders, quick capture, and GTD-style triage | Command Center docs |
| Workspace apps | Tasks, Calendar, Meet, Finance, Inventory, CMS, Track, Shortener, Learn, Teach, Rewise, Nova, Hive, and more | Platform overview |
| AI and automation | Mira, Nova, Rewise, model routing, structured data, workflow automation, and research surfaces like Hive | AI docs |
| Mobile | Flutter workspace tools for Drive, CRM, Education, QR login approval, MFA approval, and mobile-first modules | Mobile workspace tools |
| SDK and CLI | TypeScript SDK plus the native ttr CLI for workspace, task, finance, storage, and automation workflows | SDK reference |
| Docs and operations | Product docs, architecture notes, local development, Docker, CI, deployment, and runbooks | Build docs |
Start Here
Repository Map
apps/
web/ Main platform app, dashboard, and centralized APIs
mobile/ Flutter app for iOS and Android
docs/ Mintlify documentation site
database/ Supabase migrations, seeds, tests, and typegen
calendar|cms|finance|inventory|meet|tasks|track|... Satellite apps
hive|hive-realtime Research world editor and realtime service
redis|discord|backend|storage-unzip-proxy|... Supporting services
packages/
ui|icons|hooks|utils|types|supabase|auth|internal-api Shared product foundation
ai|trigger|workflows|sdk|payment|apis|... AI, automation, SDK, and integrations
scripts/
check, Docker, CI, local environment, release, and developer tooling
Tuturuuu uses a Turborepo monorepo so product changes can move atomically across
apps, database schema, generated types, shared packages, tests, and docs.
Internal packages use workspace:*; prefer shared packages before introducing
app-local duplicates.
Technology Foundation
| Layer | Choices |
|---|
| Runtime and package manager | Bun (packageManager pin), Node.js 26.12.1 (.node-version) |
| Monorepo orchestration | Turborepo |
| Web apps | Next.js 16 App Router, React 19, TypeScript |
| Local app routing | Portless, stable https://*.tuturuuu.localhost origins |
| UI | Tailwind CSS 4, Radix/Shadcn patterns, @tuturuuu/ui, @tuturuuu/icons |
| Data | Supabase PostgreSQL with RLS and generated database types |
| Client state | TanStack Query, Jotai, nuqs |
| APIs | Next.js Route Handlers, tRPC, @tuturuuu/internal-api |
| AI | Vercel AI SDK and provider-specific packages |
| Mobile | Flutter, Dart, BLoC/Cubit |
| Tests and checks | Vitest, Playwright, Biome, tsc, Flutter checks |
| Deployment | Vercel, GitHub Actions, Docker blue/green workflow |
Quick Start
Install the required tools:
- Bun 1.3.x
- Node.js 26.12.1, pinned in
.node-version (the
engines floor is 22.13; see
Node.js runtime pin)
- Docker for Supabase, Redis, and Dockerized web
workflows
- Flutter SDK for
apps/mobile
- Rust toolchain for
apps/backend
- Python and
uv for apps/discord
Clone and install:
git clone https://github.com/tutur3u/platform.git
cd platform
bun i
Create only the environment files needed for the apps you plan to run. Most web
work starts with:
cp apps/web/.env.example apps/web/.env.local
Then fill in Supabase, auth, AI, email, storage, and integration variables as
needed. Keep secrets in local env files or deployment secret stores, never in
git.
Local Development
The default local experience uses Portless, so apps get stable HTTPS subdomains
instead of relying on fallback ports:
| App | Local URL |
|---|
| Platform | https://tuturuuu.localhost |
| Calendar | https://calendar.tuturuuu.localhost |
| CMS | https://cms.tuturuuu.localhost |
| External | https://external.tuturuuu.localhost |
| Finance | https://finance.tuturuuu.localhost |
| Hive | https://hive.tuturuuu.localhost |
| Inventory | https://inventory.tuturuuu.localhost |
| Learn | https://learn.tuturuuu.localhost |
| Meet | https://meet.tuturuuu.localhost |
| Nova | https://nova.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 |
Run the main platform:
bun dev:web
Start local Supabase first when you need a local database:
bun sb:start
bun dev:web
Use convenience scripts when you want the workflow to manage Supabase:
bun devx:web # start Supabase, then run web
bun devrs:web # reset and seed Supabase, then run web
Run a focused app from the root when a matching script exists:
bun dev:calendar
bun dev:cms
bun dev:finance
bun dev:inventory
bun dev:meet
bun dev:nova
bun dev:rewise
bun dev:shortener
bun dev:tasks
bun dev:track
bun dev:learn
bun dev:teach
bun dev:hive
bun dev:external
Use bun dev:edu when working on Learn and Teach together with the central web
app for cross-app login. Run mobile and docs separately:
bun dev:mobile
bun dev:docs
Do not run long-lived development servers or build commands in automation unless
the task explicitly calls for them.
Data And Local Services
Supabase lives in apps/database and is exposed through root scripts:
| Command | Purpose |
|---|
bun sb:start | Start local Supabase |
bun sb:stop | Stop local Supabase |
bun sb:reset | Reset local Supabase and regenerate types |
bun sb:new | Create a migration |
bun sb:up | Apply local migrations and regenerate types |
bun sb:typegen | Regenerate database types |
bun redis:start | Start local Redis and the Serverless Redis HTTP proxy |
bun redis:stop | Stop local Redis services |
Production Supabase pushes are not part of the normal contributor flow. Prepare
migrations in the repo and let the release operator apply them.
Docker And Deployment
The web app has Docker workflows for development, production-like local runs,
and self-hosted blue/green deployment.
| Command | Purpose |
|---|
bun dev:web:docker | Run the web development workflow inside Docker |
bun devx:web:docker | Start local Supabase, then run Docker web development |
bun devrs:web:docker | Reset local Supabase, then run Docker web development |
bun dev:web:docker:down | Stop the Docker development stack |
bun serve:web:docker | Run the production web image in place |
bun serve:web:docker:bg | Run blue/green production deployment |
bun serve:web:docker:bg:watch | Poll the tracked branch and deploy new fast-forwards |
bun serve:web:docker:down | Stop the production Docker stack |
bun serve:web:docker:bg:down | Stop blue/green runtime state |
Dockerized web commands read apps/web/.env.local. Redis is enabled by default
inside the Docker web flow and can be disabled with --without-redis when
testing Redis-unavailable behavior. In that mode, apps/web fails open for
Redis-backed route rate limits and IP-block enforcement while preserving normal
auth, authorization, payload-size, Turnstile, suspension, and validation checks.
See the Web Docker Deployment
runbook for flags, lock recovery, BuildKit throttling, blue/green cutover, and
runtime file details.
SDK And CLI
The tuturuuu package in packages/sdk ships the public TypeScript SDK and the
native Bun-powered ttr CLI.
Use the repo-local CLI during development:
bun ttr --help
bun ttr whoami --no-update-check
bun ttr tasks --json --no-update-check
Use the globally installed ttr for normal user workflows, login, and upgrade
management:
ttr login
ttr workspaces
ttr tasks --compact
ttr finance wallets
The SDK covers workspace storage, files, documents, EPM delivery and management,
task workflows, finance workflows, and agent-friendly JSON output.
Quality Gates
Use the narrowest focused check first, then the repo-level check when your
change touches TypeScript, JavaScript, root scripts, or shared config.
| Command | Purpose |
|---|
bun format:fix <files> | Format specific files with Biome |
bun i18n:sort | Sort message files after translation edits |
bun test | Run package test tasks through Turbo |
bun test:scripts | Run root script tests |
bun type-check | Run type-check tasks through Turbo |
bun validate | Run the repository validation suite |
bun check:docker | Validate Docker web configuration |
bun check:mobile | Run Flutter mobile validation |
git diff --check | Catch whitespace issues before commit |
For Markdown-only changes, keep the file manually formatted and run
git diff --check. For product, API, schema, or shared package changes, follow
the focused verification for that surface and the guardrails in AGENTS.md.
Contributor Expectations
Before making broad or automated changes, read AGENTS.md. It is
the operating manual for this checkout and includes the full guardrail set.
The short version:
- Check
git status --short before editing and avoid unrelated dirty files.
- Use Conventional Commit style for authored commits.
- Default to Server Components in Next.js; use client components only for
browser state, browser APIs, or interaction.
- Use TanStack Query for client-side data fetching and mutations.
- Put authenticated app API access behind
packages/internal-api/src/*.
- Import shared database row shapes from
@tuturuuu/types/db where possible.
- Update both English and Vietnamese message bundles for user-facing strings.
- Add dashboard routes to the relevant
navigation.tsx aliases, children,
icons, and permissions.
- Keep durable workflow, deployment, architecture, debugging, and operations
knowledge in
apps/docs.
CI, Security, And License
GitHub Actions cover branch naming, Biome, type checks, tests, CodeQL, mobile
builds, Supabase checks, Vercel preview and production deployments, package
releases, Docker setup checks, and Discord Modal deployment.
Production web deployments primarily target Vercel. The Docker workflow exists
for local production simulation and self-hosted blue/green operation.
Security issues should be reported through SECURITY.md.
This project is licensed under the Apache License, Version 2.0. See
LICENSE for details.
