> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tuturuuu.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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