master-ai/TURBOREPO_MIGRATION_PLAN.md

Turborepo Monorepo Per-Project Migration Plan

Why We Are Making This Change

The core thesis of this platform is that one AI controls everything in one project. For that to work, the AI needs a complete mental model of the project — all apps, all shared code, all dependencies — in a single coherent context.

The current architecture creates separate Gitea repos per app (frontend repo, API repo, etc.), which fragments that context. The AI has to context-switch across repos, cross-repo dependencies are manual and brittle, and shared code has no clean home.

By adopting Turborepo monorepo per project, every project becomes a single repo containing all of its apps (product, website, admin) and shared packages (ui, types, config). The AI operates across the entire project simultaneously. Build orchestration, deployment, and shared code all become coherent automatically.

The structure every project will have:

{project-slug}/
  apps/
    product/        ← the core user-facing app
    website/        ← marketing / landing site
    admin/          ← internal admin tool
  packages/
    ui/             ← shared component library
    types/          ← shared TypeScript types
    config/         ← shared eslint, tsconfig
  turbo.json
  package.json      ← workspace root (pnpm workspaces)
  .gitignore
  README.md

This is not a Vercel dependency. Turborepo is MIT-licensed, runs anywhere, and costs nothing. Remote caching is optional and can be self-hosted on Coolify.

---

Scope of Changes

1. Project Scaffold Templates

What: Create a set of template files that get written into a new Gitea repo when a project is created.

Files to create: platform/scripts/templates/turborepo/

• turbo.json — pipeline config defining build, dev, lint, test tasks and their dependencies
• package.json — workspace root with pnpm workspaces pointing to apps/* and packages/*
• .gitignore — covering node_modules, dist, .turbo cache
• apps/product/package.json — Next.js app skeleton
• apps/website/package.json — Astro or Next.js skeleton
• apps/admin/package.json — Next.js app skeleton
• packages/ui/package.json — shared component library stub
• packages/types/package.json — shared types stub
• packages/config/ — shared tsconfig.json and eslint base configs

Notes:

• Templates should be stack-agnostic at the shell level — the turbo.json pipeline is what matters, inner frameworks can vary
• Stack choices (Next.js vs Astro, etc.) can be parameterised later when we add a project creation wizard

---

2. Control Plane — Project Data Model Update

What: The current data model stores multiple Gitea repos per project. This changes to one repo per project.

File: platform/backend/control-plane/src/types.ts

Changes:

• Remove repos: Array<{ gitea_repo, path }> from ProjectRecord (or update it)
• Add repo: string — single Gitea repo URL for the project
• Add apps: Array<{ name: string; path: string; coolify_service_uuid?: string }> — tracks each app inside the monorepo and its Coolify service
• Add turbo: { version: string } — tracks which Turborepo version the project was scaffolded with

---

3. Control Plane — New Project Routes

What: Add project management endpoints to the control plane API.

File to create: platform/backend/control-plane/src/routes/projects.ts

Endpoints:

Method	Path	Purpose
POST	/projects	Create project — scaffold Turborepo repo in Gitea, register in DB
GET	/projects/:project_id	Get project record
GET	/projects/:project_id/apps	List apps within the monorepo
POST	/projects/:project_id/apps	Add a new app to the monorepo
POST	/projects/:project_id/deploy	Trigger Turbo build + Coolify deploy for one or all apps

Project creation flow (POST /projects):

1. Validate request (name, tenant_id, optional app selections)
2. Create Gitea repo via Gitea API
3. Scaffold Turborepo structure from templates, push initial commit
4. Register webhook: Gitea repo → control plane /webhooks/gitea
5. Create Coolify project
6. Create one Coolify service per app (with correct build filter)
7. Save project record to storage
8. Return project record with repo URL and app list

---

4. Control Plane — Storage Layer Updates

What: Add project storage operations alongside existing runs/tools storage.

File to update: platform/backend/control-plane/src/storage/memory.ts
File to update: platform/backend/control-plane/src/storage/firestore.ts
File to update: platform/backend/control-plane/src/storage/index.ts

New operations to add:

• saveProject(project: ProjectRecord): Promise<void>
• getProject(projectId: string): Promise<ProjectRecord | null>
• listProjects(tenantId: string): Promise<ProjectRecord[]>
• updateProjectApp(projectId: string, app: AppRecord): Promise<void>

---

5. Gitea Integration Service

What: New service to abstract all Gitea API calls. Currently there is no Gitea integration in the control plane.

File to create: platform/backend/control-plane/src/gitea.ts

Responsibilities:

• Create repo for a project
• Push initial scaffolded files (initial commit)
• Register webhooks
• Read file tree (so AI can understand the project structure)
• Read/write individual files (so AI can make edits)

Config needed in config.ts:

• giteaUrl — from GITEA_URL env var (e.g. https://git.vibnai.com)
• giteaToken — from GITEA_TOKEN env var (admin token for repo creation)

---

6. Coolify Integration Service

What: New service to abstract all Coolify API calls. Currently the deploy executor calls Coolify but there is no central integration.

File to create: platform/backend/control-plane/src/coolify.ts

Responsibilities:

• Create a Coolify project
• Create a Coolify application service linked to a Gitea repo
• Set the build command to turbo run build --filter={app-name}
• Set the publish directory per app
• Trigger a deployment
• Get deployment status

Config needed in config.ts:

• coolifyUrl — from COOLIFY_URL env var
• coolifyToken — from COOLIFY_TOKEN env var

---

7. Deploy Executor — Monorepo Awareness

What: The existing deploy executor (platform/backend/executors/deploy) currently deploys a single service. It needs to understand the monorepo structure and use turbo run build --filter to target the right app.

File to update: platform/backend/executors/deploy/src/index.ts

Changes:

• Accept app_name in the input payload (e.g. "product", "website", "admin")
• Build command becomes turbo run build --filter={app_name} instead of npm run build
• Pass the root of the monorepo as the build context, not an app subdirectory

---

8. AI Context — Project-Aware Prompting

What: The Gemini chat integration currently has no awareness of which project the user is in. It needs project context so the AI can reason across the whole monorepo.

File to update: platform/backend/control-plane/src/gemini.ts
File to update: platform/backend/control-plane/src/routes/chat.ts

Changes:

• Add project_id to ChatRequest
• On chat requests with a project_id, fetch the project record and inject:
  • Repo structure (app names, package names)
  • Recent deployment status per app
  • turbo.json pipeline config
• Add a new Gemini tool: scaffold_app — lets the AI add a new app to the user's monorepo
• Add a new Gemini tool: deploy_app — lets the AI trigger a Coolify deploy for a specific app by name

---

9. Theia Workspace — Single Repo Mode

What: The current Theia docker-compose opens a multi-root workspace across multiple repos. With one repo per project, this simplifies to a single workspace root.

File to update: theia-docker-compose.yml (and the Coolify service config for Theia)

Changes:

• Workspace path points to the cloned monorepo root
• Git remote is the project's single Gitea repo
• Theia extensions should be aware of the turbo.json to surface run targets in the UI (future)

---

10. Local Dev — Replace start-all.sh with Turbo

What: The current platform/scripts/start-all.sh manually starts each service with &. Once the platform itself is in a Turborepo, this can be replaced with turbo run dev.

Note: This is a nice-to-have follow-on. The priority is getting user project scaffolding right first. The platform's own internal structure can be migrated to Turborepo in a separate pass.

---

Implementation Order

Step	Task	Depends On
1	Create scaffold templates	Nothing
2	Add ProjectRecord type + storage ops	Step 1
3	Build Gitea integration service	Step 2
4	Build Coolify integration service	Step 2
5	Add project routes to control plane	Steps 2, 3, 4
6	Update deploy executor for monorepo	Step 5
7	Update AI chat with project context	Step 5
8	Update Theia workspace config	Step 5
9	Migrate platform itself to Turborepo	All of the above

---

What Does Not Change

• Gitea as the source control host — same, just one repo per project instead of many
• Coolify as the deployment host — same, just configured with Turbo build filters
• Theia as the IDE — same, just opens one repo instead of multi-root
• The control plane API architecture (Fastify, in-memory/Firestore storage) — same, just extended
• Auth model — unchanged
• No Vercel dependency anywhere in this plan