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):

✅ Correct❌ Incorrect
checkin-boardCheckinBoard
breakfast-trackerbreakfast_tracker
my-new-appmyNewApp

The shared/ Directory

Shared resources that multiple apps can use:

DirectoryPurposeWho Can Edit
shared/database/Prisma schema for all tablesVibe coders (with review)
shared/auth/Authentication servicesDevelopers only
shared/types/Shared TypeScript typesVibe coders (with review)

Database Access

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

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

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

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
Ask Claude to explain CLAUDE.md
Claude prompt
Read the CLAUDE.md file and summarize the key rules I need to follow as a vibe coder.

App-Specific Files

Each app may have its own documentation:

FilePurpose
README.mdApp overview and setup instructions
CLAUDE.mdApp-specific AI guidelines
PLAN.mdDevelopment progress and planned work

Working with the Monorepo

Running Commands

Always run commands from the repository root:

Running app commands from rootbash
# 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:

Installing dependenciesbash
# ✅ Correct: Run from repository root
pnpm install

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

Adding a New Dependency

Ask Claude to add a dependency
Claude prompt
Add the "date-fns" package as a dependency to my-app-name.
Or run it yourselfbash
# 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

Quiz

Where should you run pnpm install?

Next Steps