# 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 a single Gitea repo per project with no enforced internal structure. The AI has no reliable way to know where apps live, what shares code with what, or how to trigger a targeted build for one part of the project.

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

**The structure every user project repo will have:**

```
{project-slug}/               ← one Gitea repo per project
  apps/
    product/                  ← core user-facing app (Next.js)
    website/                  ← marketing / landing site (Next.js)
    admin/                    ← internal admin tool (Next.js)
    storybook/                ← component browser and design system
  packages/
    ui/                       ← shared React component library
    tokens/                   ← design tokens (colors, spacing, typography)
    types/                    ← shared TypeScript types
    config/                   ← shared eslint, tsconfig
  turbo.json
  package.json                ← pnpm workspace root
  .gitignore
  README.md
```

Turborepo is MIT-licensed, runs anywhere, and costs nothing. No Vercel dependency.

---

## Infrastructure Context

Everything runs on a single GCP VM (`34.19.250.135`, Montreal) via Docker + Traefik:

| Service | URL | Repo |
|---|---|---|
| Platform frontend | `vibnai.com` | `git.vibnai.com/mark/vibn-frontend` |
| Gitea | `git.vibnai.com` | — |
| Coolify | `coolify.vibnai.com` | — |
| PostgreSQL | internal | — |

**All platform logic lives in `vibn-frontend`** (Next.js). There is no separate control plane service. The backend is Next.js API routes in `app/api/`. Storage is PostgreSQL via raw SQL queries (no ORM layer in use for project data).

**Integrations that already exist and should not be replaced:**
- `lib/gitea.ts` — full Gitea API client (create repo, webhooks, signature verification)
- `lib/coolify.ts` — full Coolify API client (projects, databases, applications, deployments)
- `app/api/projects/create/route.ts` — project creation flow (creates Gitea repo)
- `app/api/webhooks/gitea/route.ts` — receives Gitea push/PR events
- `app/api/webhooks/coolify/route.ts` — receives Coolify deployment events
- `app/api/ai/chat/route.ts` — AI chat with Gemini
- `lib/auth/authOptions.ts` — NextAuth v4 with Prisma adapter

---

## Scope of Changes

### 1. Scaffold Templates

**What:** A set of template files written into the user's Gitea repo when a project is created, giving every project the standard Turborepo monorepo structure.

**Where:** `vibn-frontend/lib/scaffold/turborepo/`

**Files to create:**
- `turbo.json` — pipeline: `build`, `dev`, `lint`, `type-check`, `test`
- `package.json` — pnpm workspace root pointing to `apps/*` and `packages/*`
- `.gitignore`
- `README.md` — project-specific (name injected at scaffold time)
- `apps/product/` — Next.js 15, references shared `ui`, `tokens`, `types`
- `apps/website/` — Next.js 15
- `apps/admin/` — Next.js 15
- `apps/storybook/` — Storybook 8
- `packages/ui/` — Button, Card, Input, Badge components using CSS token vars
- `packages/tokens/` — design tokens as TS + CSS custom properties
- `packages/types/` — shared `User`, `ApiResponse`, `PaginatedResponse` types
- `packages/config/` — `tsconfig.base.json` and `eslint.config.js`

**Status:** Templates were written and are ready. Need to be moved to `vibn-frontend/lib/scaffold/turborepo/`.

---

### 2. Project Creation Route — Add Scaffold Push

**What:** The existing `app/api/projects/create/route.ts` already creates a Gitea repo. It needs one additional step: push the Turborepo scaffold as the initial commit.

**File to update:** `vibn-frontend/app/api/projects/create/route.ts`

**Current flow:**
1. Create Gitea repo (`auto_init: true` — creates empty repo with README)
2. Register webhook
3. Save project record to PostgreSQL

**New step to add after repo creation:**
- Read scaffold template files from `lib/scaffold/turborepo/`
- Replace `{{project-slug}}` and `{{project-name}}` placeholders
- Push each file to the Gitea repo via the contents API
- This replaces the default empty `auto_init` commit

**Note:** Change `auto_init: true` to `auto_init: false` since we are pushing the scaffold ourselves.

---

### 3. Project Data Model — Add App Tracking

**What:** The `fs_projects` table stores project data as a JSONB `data` column. The `data` object needs two new fields to track the monorepo apps and their Coolify services.

**Fields to add to the project `data` JSONB:**

```typescript
apps: Array<{
  name: string;           // "product" | "website" | "admin" | "storybook"
  path: string;           // "apps/product"
  coolifyServiceUuid?: string;
  domain?: string;
}>
turboVersion: string;     // e.g. "2.3.3"
```

No schema migration needed — it's JSONB, just include these fields when inserting/updating.

---

### 4. Coolify — Per-App Service Provisioning

**What:** When a project is created, each app in the monorepo gets its own Coolify service with the correct Turbo build filter. This extends the existing `lib/coolify.ts`.

**File to update:** `vibn-frontend/lib/coolify.ts`

**Add function:**

```typescript
createMonorepoAppService(opts: {
  projectUuid: string;
  appName: string;          // e.g. "product"
  gitRepo: string;          // the project's Gitea clone URL
  domain: string;           // e.g. "product-taskmaster.vibnai.com"
}): Promise<CoolifyApplication>
```

Build command: `pnpm install && turbo run build --filter={appName}`

**Wire into project creation:** After Gitea repo is created and scaffold is pushed, create one Coolify service per app and store the `coolifyServiceUuid` in the project's `apps` array.

---

### 5. Deploy API Route

**What:** A new API route that triggers a Coolify deployment for a specific app within a project.

**File to create:** `vibn-frontend/app/api/projects/[projectId]/deploy/route.ts`

```
POST /api/projects/{projectId}/deploy
Body: { app_name: "product" | "website" | "admin" | "storybook" }
```

Flow:
1. Load project from PostgreSQL
2. Find the app's `coolifyServiceUuid`
3. Call `deployApplication(uuid)` from `lib/coolify.ts`
4. Return deployment UUID

---

### 6. AI Chat — Project Context Injection

**What:** The existing `app/api/ai/chat/route.ts` handles Gemini chat. It needs to inject monorepo structure context when a `projectId` is present in the request.

**File to update:** `vibn-frontend/app/api/ai/chat/route.ts`

**Add to chat request handling:**
- Accept optional `projectId`
- When present, load the project from PostgreSQL
- Inject into the system prompt:
  - Project name, slug, repo URL
  - List of apps and their domains
  - Shared packages available
  - Turbo version and build command pattern
- Add two new Gemini tools:
  - `deploy_app` — triggers `POST /api/projects/{projectId}/deploy`
  - `scaffold_app` — adds a new app folder to the monorepo via Gitea contents API

---

## Implementation Order

| Step | Task | File | Depends On |
|------|------|------|-----------|
| 1 | Move scaffold templates into `vibn-frontend/lib/scaffold/` | `lib/scaffold/turborepo/**` | — |
| 2 | Update project creation to push scaffold | `app/api/projects/create/route.ts` | Step 1 |
| 3 | Add app tracking fields to project data | `app/api/projects/create/route.ts` | Step 2 |
| 4 | Add `createMonorepoAppService` to Coolify lib | `lib/coolify.ts` | — |
| 5 | Wire Coolify per-app provisioning into project creation | `app/api/projects/create/route.ts` | Steps 3, 4 |
| 6 | Add deploy route | `app/api/projects/[projectId]/deploy/route.ts` | Step 4 |
| 7 | Inject monorepo context into AI chat | `app/api/ai/chat/route.ts` | Step 3 |

---

## What Does Not Change

- Gitea as source control — same, one repo per project (already the case)
- Coolify as deployment host — same, extended with per-app services
- NextAuth for auth — unchanged
- PostgreSQL + JSONB for project storage — unchanged
- `lib/gitea.ts` and `lib/coolify.ts` — extended, not replaced
- No Vercel dependency anywhere