Monorepo Overview

Understanding the monorepo structure and how apps are organized.

What is a Monorepo?

A monorepo (monolithic repository) is a single repository that contains multiple projects, applications, and shared code. Instead of having separate repositories for each app, everything lives together in one place.

Benefits for Vibe Coders

• Shared code: Common utilities, types, and configurations are shared across all apps
• Consistent patterns: All apps follow the same structure and conventions
• Single source of truth: One CLAUDE.md file contains all the guidelines
• Easier collaboration: Claude can understand the entire codebase context

Repository Structure

vibe-coding-platform/
├── apps/                    # All applications live here
│   ├── checkin-board/       # Example app
│   ├── breakfast-tracker/   # Another app
│   └── your-new-app/        # Your app goes here
├── shared/                  # Shared resources
│   ├── database/            # Database schema (Prisma)
│   ├── auth/                # Authentication services
│   └── types/               # Shared TypeScript types
├── templates/               # App templates for new projects
├── CLAUDE.md                # AI development guidelines
└── package.json             # Root workspace configuration

The apps/ Directory

Each app in the apps/ directory is a standalone Next.js application with its own:

• package.json - Dependencies and scripts
• app/ directory - Next.js App Router pages
• deploy.config.yml - Railway deployment configuration

App Naming Convention

Apps use kebab-case (lowercase with hyphens):

The shared/ Directory

Shared resources that multiple apps can use:

Database Access

Apps use the pg library (not Prisma client) for database queries:

import { pool } from '@/lib/db/connection';

const result = await pool.query(
  'SELECT * FROM users WHERE id = $1',
  [userId]
);

Note: Database queries only execute in deployed environments (PR preview or production). Local development runs without database access. See App Setup for details.

Key Files to Know

CLAUDE.md (Root)

The most important file for AI development. Contains:

• Coding standards and conventions
• Git workflow rules
• Database guidelines
• Deployment instructions

App-Specific Files

Each app may have its own documentation:

Working with the Monorepo

Running Commands

Always run commands from the repository root:

# Start development server
pnpm dev:your-app-name

# Build the app
pnpm build:your-app-name

# Run tests (if available)
pnpm test:your-app-name

Installing Dependencies

Never run pnpm install inside an app directory:

# ✅ Correct: Run from repository root
pnpm install

# ❌ Wrong: Don't run inside app directory
cd apps/my-app && pnpm install

Adding a New Dependency

# Add to a specific app
pnpm --filter my-app-name add date-fns

# Add as dev dependency
pnpm --filter my-app-name add -D @types/some-package

Quiz

Next Steps

• Learn about Branching & PRs for the git workflow
• Review the Workflow for day-to-day development