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

Platform Architecture

At a glance, the platform centralizes authentication, keeps app data separate from core booking data (the dual-database model), and connects to algoritmi-core for booking, property, and room data. Individual apps under apps/ are omitted here because they change over time.

Apps Spanning vibe-coding-platform and algoritmi-core

Several apps deliberately span both repos: they read live booking data from algoritmi-core while keeping their own state in the vibe database. There are two patterns.

Pattern A — Read core data read-only (dual database)

These apps open a read-only connection to the core booking database (CORE_DATABASE_URL_RO) for booking/room/property context, and write only to their own tables in the vibe database. No guest PII is stored.

Pattern B — Check-in: register & view ID photos via check-in-api

The check-in apps register guests through algoritmi-core's check-in-api. The check-in-tablet uploads passport and ID photos (POST /v1/register-check-in), which check-in-api stores in an S3 bucket and records in check_in_terminal_input. reception then lists check-ins and streams the images back (GET /v1/check-ins, GET /v1/objects), and a webhook from the tablet pushes a real-time refresh to reception over SSE. (Authentication via short-lived JWT is omitted here for clarity.)

Pattern C — AI agent via the core MCP

The external dynamic-pricing-agent (a separate repo) reads the core MCP with a Bearer token and posts pricing proposals back to the dynamic-pricing app.

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