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
│   ├── storage/             # Object storage helpers (Railway buckets)
│   ├── api/                 # Shared API contracts
│   └── 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:

Deeper guides: Database, Auth & Access, File Storage.

Database Access

Apps use the pg library (not Prisma client) for runtime database queries. Use the getDb() helper from the template and always use parameterized queries ($1, $2, …) to prevent SQL injection:

import { getDb } from '@/app/_lib/db';

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

Note: Database queries only execute in deployed environments (PR preview or production). See Database for the full schema and migration workflow.

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. You don't run apps locally — everything runs on staging and production after you open a PR (see Deployment). The one command you do run locally is the build, to reproduce the CI check before committing:

# Verify the build passes before committing (same check CI runs)
pnpm build: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