monorepo-structure

Monorepo Structure - Critical Rules

NEVER PUT BUSINESS LOGIC IN apps/web/src/lib/

VIOLATION EXAMPLE (DO NOT DO THIS):

// ❌ WRONG: apps/web/src/lib/crawler.ts
export async function crawlWebsite() {
  // Database operations, AI calls, etc.
}

CORRECT APPROACH:

// ✅ CORRECT: packages/api/src/actions/crawling/worker.ts
export async function crawlSingleWebsite() {
  // Business logic belongs here
}

// ✅ CORRECT: apps/web/src/pages/api/crawl.ts (thin wrapper only)
import { crawlSingleWebsite } from '@app/api'
export const POST: APIRoute = async ({ request }) => {
  const result = await crawlSingleWebsite(params)
  return new Response(JSON.stringify(result))
}

Directory Rules

packages/api/src/ - Business Logic ONLY

packages/api/src/
├── actions/               # ✅ All business logic here
│   ├── crawling/         # ✅ Crawling operations
│   ├── extraction/        # ✅ AI/data processing
│   ├── browser/           # ✅ External service clients
│   └── seeding/           # ✅ Database seeding
├── routers/               # ✅ tRPC API routes
├── schemas/               # ✅ Zod validation schemas
└── index.ts               # ✅ Export everything for apps

apps/web/src/ - Frontend + Thin API Wrappers ONLY

apps/web/src/
├── components/            # ✅ React UI components only
├── hooks/                 # ✅ Frontend React hooks only
├── pages/api/             # ✅ Thin API wrappers only (no business logic)
├── client/                # ✅ tRPC client setup only
├── lib/utils.ts           # ✅ Frontend utilities only
└── server/                # ✅ Astro server config only

MANDATORY PATTERNS

1. Business Logic → packages/api

• Database operations
• AI/ML processing
• External API clients (Browserless, OpenAI, GCS)
• Data transformation
• Validation schemas
• Complex algorithms

2. API Routes → Thin Wrappers Only

// ✅ CORRECT: Thin wrapper pattern
export const POST: APIRoute = async ({ request }) => {
  // 1. Auth validation only
  // 2. Parse request with Zod
  // 3. Call packages/api function
  // 4. Return response
}