metabuilder/docs/CLAUDE.md

MetaBuilder Development Guide for AI Assistants

Last Updated: 2026-01-21 Status: Phase 2 Complete, Monorepo Consolidated Overall Health: 82/100 Vision: Universal Platform - One cohesive system for code, 3D, graphics, media, and system administration Structure: Monorepo containing MetaBuilder core + 15 standalone projects

---

Table of Contents

1. Universal Platform Vision
2. Before Starting Any Task
3. Core Principles
4. Architecture Overview
5. JSON-First Philosophy
6. Multi-Tenant & Security
7. Code Organization
8. What NOT to Do
9. Quick Reference

---

Universal Platform Vision

MetaBuilder is evolving into a Universal Platform - a userland operating environment that provides everything through a unified data model and consistent interface.

The Premise

Modern computing is fragmented. Users need dozens of apps, each with its own paradigms, file formats, and learning curves. MetaBuilder provides one cohesive system for code editing, 3D modeling, game development, graphics work, system administration, and media production.

System Architecture

┌─────────────────────────────────────────────────────────────────────────────┐
│                              FRONTENDS                                       │
├─────────────────┬─────────────────────┬─────────────────────────────────────┤
│   CLI Frontend  │   Qt6 Frontend      │   Web Frontend (Next.js)            │
│   (Commander)   │   (Native Desktop)  │   (Browser/Electron/Tauri)          │
└────────┬────────┴──────────┬──────────┴──────────────────┬──────────────────┘
         │                   │                              │
         └───────────────────┼──────────────────────────────┘
                             │
                    ┌────────▼────────┐
                    │  FRONTEND BUS   │
                    │  (WebSocket/IPC)│
                    └────────┬────────┘
                             │
┌────────────────────────────▼────────────────────────────────────────────────┐
│                           METABUILDER CORE                                   │
│  ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐        │
│  │ State Machine│ │ Command Bus  │ │ Event Stream │ │ Entity Graph │        │
│  │ (XState-like)│ │ (CQRS)       │ │ (Pub/Sub)    │ │ (DBAL)       │        │
│  └──────────────┘ └──────────────┘ └──────────────┘ └──────────────┘        │
│  ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐        │
│  │ Undo/Redo    │ │ Job Scheduler│ │ Plugin Host  │ │ VFS Layer    │        │
│  │ (Event Src)  │ │ (DAG Engine) │ │ (Registry)   │ │ (Abstraction)│        │
│  └──────────────┘ └──────────────┘ └──────────────┘ └──────────────┘        │
└─────────────────────────────────┬───────────────────────────────────────────┘
                                  │
┌─────────────────────────────────▼───────────────────────────────────────────┐
│                        CAPABILITY MODULES                                    │
├─────────────┬─────────────┬─────────────┬─────────────┬─────────────────────┤
│   CODE      │   GRAPHICS  │    3D       │   MEDIA     │   SYSTEM            │
│   ────      │   ────────  │    ──       │   ─────     │   ──────            │
│ • Editor    │ • Raster    │ • Modeling  │ • Audio     │ • Files             │
│ • LSP Host  │ • Vector    │ • Sculpting │ • Video     │ • Processes         │
│ • Debugger  │ • Compositor│ • Animation │ • Streaming │ • Network           │
│ • Builder   │ • Filters   │ • Physics   │ • Recording │ • Hardware          │
│ • VCS       │ • AI Gen    │ • Rendering │ • Encoding  │ • Containers        │
├─────────────┼─────────────┼─────────────┼─────────────┼─────────────────────┤
│   GAME      │   DATA      │   DOCS      │   COMMS     │   AI                │
│   ────      │   ────      │   ────      │   ─────     │   ──                │
│ • Engine    │ • Database  │ • Writer    │ • Chat      │ • Local LLM         │
│ • Physics   │ • Sheets    │ • Slides    │ • Email     │ • Image Gen         │
│ • Audio     │ • Graphs    │ • Diagrams  │ • Calendar  │ • Code Assist       │
│ • Assets    │ • ETL       │ • PDF       │ • Tasks     │ • Agents            │
│ • Scripting │ • Analytics │ • Publishing│ • Contacts  │ • Embeddings        │
└─────────────┴─────────────┴─────────────┴─────────────┴─────────────────────┘
                                  │
┌─────────────────────────────────▼───────────────────────────────────────────┐
│                         RUNTIME LAYER                                        │
│  ┌────────────┐ ┌────────────┐ ┌────────────┐ ┌────────────┐                │
│  │ Native     │ │ WASM       │ │ Workflow   │ │ GPU        │                │
│  │ (C++/TS)   │ │ (Portable) │ │ (JSON DAG) │ │ (Compute)  │                │
│  └────────────┘ └────────────┘ └────────────┘ └────────────┘                │
└─────────────────────────────────────────────────────────────────────────────┘

Mapping to Current Implementation

Architecture Layer	Current Component	Location
Entity Graph	DBAL	dbal/
Job Scheduler	DAG Executor	workflow/executor/ts/executor/
Plugin Host	Node Executor Registry	workflow/executor/ts/registry/
Workflow Runtime	Python/TS Plugins	workflow/plugins/
Web Frontend	Next.js App	frontends/nextjs/

Core Subsystems (To Build)

Subsystem	Purpose	Status
State Machine	Central state management (XState-like)	Planned
Command Bus	CQRS command/query separation	Planned
Event Stream	Pub/sub for cross-module communication	Planned
VFS Layer	Virtual filesystem abstraction	Planned
Frontend Bus	WebSocket/IPC for frontend sync	Planned

Capability Categories

• Code: Editor, LSP, debugger, builder, VCS
• Graphics: Raster, vector, compositor, filters, AI generation
• 3D: Modeling, sculpting, animation, physics, rendering
• Media: Audio, video, streaming, recording, encoding
• System: Files, processes, network, hardware, containers
• Game: Engine, physics, audio, assets, scripting
• Data: Database, sheets, graphs, ETL, analytics
• Docs: Writer, slides, diagrams, PDF, publishing
• Comms: Chat, email, calendar, tasks, contacts
• AI: Local LLM, image generation, code assist, agents, embeddings

Full architecture details: See docs/UNIVERSAL_PLATFORM_ARCHITECTURE.md

---

Before Starting Any Task

MANDATORY: Perform exploration BEFORE any implementation work. Do NOT skip this step or go shallow.

Exploration is NOT Optional

• Many task failures occur because exploration was skipped or done superficially
• Shallow exploration (reading only 1-2 files) misses critical context and conventions
• Proper exploration prevents rework, security issues, and architectural mistakes
• Use the Explore agent for codebase questions - it goes deep systematically

For EVERY Task - Follow This Sequence

1. Understand the Task Domain

• Read /CLAUDE.md (this file) - core principles and patterns
• Read /AGENTS.md - domain-specific rules for your task type
• Read /README.md - project overview
• Check recent git commits: What was done recently in this area?

2. Map the Relevant Codebase (Use Explore Agent)

The exploration depth depends on task type:

For Feature/Package Work:

• Examine /packages/{packageId}/ structure - all directories and files
• Review similar existing packages for patterns
• Check /schemas/package-schemas/ for validation rules
• Look at /dbal/shared/api/schema/entities/ if new entities needed

For API/Backend Work:

• Review /frontends/nextjs/src/app/api/v1/[...slug]/route.ts - main router
• Check /frontends/nextjs/src/lib/middleware/ - rate limiting, auth, multi-tenant
• Examine /dbal/development/src/adapters/ - database patterns
• Check /dbal/shared/api/schema/operations/ - operation specifications
• Review rate limiting setup in /docs/RATE_LIMITING_GUIDE.md

For Frontend/UI Work:

• Review target /packages/{packageId}/component/ structure
• Check /frontends/nextjs/src/lib/ for rendering and utilities
• Examine similar UI packages for component patterns
• Understand the JSON→React rendering flow

For Database/Schema Work:

• Review all 27 YAML entity definitions in /dbal/shared/api/schema/entities/
• Check /schemas/package-schemas/ for JSON validation schemas
• Understand the two-layer schema system (YAML source → Prisma → JSON validation)
• Review /docs/MULTI_TENANT_AUDIT.md for tenant filtering patterns

For Testing Work:

• Check /playwright.config.ts and /e2e/ structure
• Review test patterns in /packages/{packageId}/playwright/ and tests/
• Understand schema validation in /schemas/package-schemas/tests/
• Check how tests handle multi-tenancy

3. Identify Patterns & Conventions

• Look at 2-3 similar completed implementations
• Identify: naming conventions, directory structure, file organization, code patterns
• Check what's in /schemas/ and /dbal/ for your task area
• Note any TODOs or FIXMEs related to your task

4. Check for Existing Work/Documentation

• Search for related documentation files
• Check git log for similar work: git log --grep="keyword"
• Look for ADRs (Architecture Decision Records) or implementation guides
• Note if there are Phase reports or migration docs relevant to your task

5. Identify Blockers & Dependencies

• Check /TECH_DEBT.md and /SYSTEM_HEALTH_ASSESSMENT.md for known issues
• Verify dependencies are installed and buildable
• Check if related packages/modules already exist
• Understand what's needed before you can start

What "Going 1 Level Deep" Really Means

Insufficient Exploration (❌ Don't Do This):

- Only reading CLAUDE.md
- Checking 1 file and starting to code
- Skipping package structure inspection
- Missing schema validation files
- Not checking existing patterns

Proper Exploration (✅ Do This):

# For package work:
✓ Read package.json file structure
✓ Examine component/ directory and sample files
✓ Check page-config/ for routing patterns
✓ Review workflow/ for existing JSON Script patterns
✓ Look at tests/ and playwright/ for test patterns
✓ Compare with 2-3 similar packages
✓ Check /schemas/package-schemas/ for validation rules

# For API work:
✓ Review main router ([...slug]/route.ts)
✓ Check middleware implementations
✓ Examine 2-3 similar API endpoints
✓ Review rate limiting patterns
✓ Understand multi-tenant filtering
✓ Check DBAL client usage patterns

# For schema work:
✓ Review all 27 YAML entities (/dbal/shared/api/schema/entities/)
✓ Check JSON validation schemas (/schemas/package-schemas/)
✓ Understand entity operations specifications
✓ Review existing entity implementations
✓ Check how tenantId is used everywhere

When to Use the Explore Agent

Use the Explore agent for:

• Understanding codebase structure and patterns
• Finding where code lives (searching across files)
• Mapping dependencies and integrations
• Answering "How does X work?" questions
• Identifying similar existing implementations
• Understanding architecture layers

Do NOT use Explore for:

• Simple file reads (use Read tool directly)
• Known file paths (use Read/Glob/Grep)
• Trivial searches (use Glob for patterns)

Common Exploration Mistakes (And How to Fix Them)

Mistake	Impact	Fix
Not reading /CLAUDE.md principles first	Violates 95/5 rule, multi-tenant issues	Always start with Core Principles section
Skipping schema review	Missing validation requirements, data structure issues	Review /schemas/package-schemas/ before coding
Not checking existing patterns	Inconsistent code, duplicate work	Examine 2-3 similar implementations
Ignoring multi-tenant requirements	Data leaks, security issues	Read Multi-Tenant section, check all DB queries have tenantId filter
Missing rate limiting	API abuse risk	Review /docs/RATE_LIMITING_GUIDE.md for new endpoints
Not understanding JSON-first philosophy	TypeScript bloat, wrong patterns	Review JSON-First Philosophy section
Assuming you know the structure	Wrong file locations, wasted effort	Use Explore agent to map the actual structure

---

Core Principles

1. 95% Data, 5% Code

MetaBuilder is 95% configuration/data in JSON, 5% infrastructure code in TypeScript.

• UI components defined as JSON
• Workflows defined as JSON Script
• Pages/routes defined as JSON
• Business logic in JSON, not TypeScript
• Code only handles rendering and persistence

2. Schema-First Development

Two-layer schema system - YAML entities + JSON validation schemas.

Layer 1: Core Database Schemas (YAML)

• Source of truth for database structure
• Location: /dbal/shared/api/schema/entities/ (27 files)
• 5 core system entities (User, Session, Workflow, Package, UIPage)
• 3 access control entities (Credential, ComponentNode, PageConfig)
• 6 package-specific entities (Forum, Notification, AuditLog, Media, IRC, Streaming)
• 4 domain-specific entities (Product, Game, Artist, Video)

Layer 2: JSON Validation Schemas (JSON Schema)

• Location: /schemas/package-schemas/ (27 files)
• Validates package files: metadata, entities, types, scripts, components, API, events, etc.
• Reference: SCHEMAS_COMPREHENSIVE.md

Development Workflow:

# 1. Define entity schema in YAML
# /dbal/shared/api/schema/entities/core/my-entity.yaml

# 2. Generate Prisma from YAML
npm --prefix dbal/development run codegen:prisma

# 3. Push to database
npm --prefix dbal/development run db:push

# 4. Create package files with proper schemas
# Use schemas/package-schemas/*.json for validation

# 5. Code follows the schema

3. Multi-Tenant by Default

Every entity has tenantId - no exceptions.

// ✅ CORRECT: Filter by tenant
const db = getDBALClient()
const records = await db.users.list({
  filter: { tenantId: user.tenantId }
})

// ❌ WRONG: Missing tenant filter (data leak!)
const records = await db.users.list()

4. Use JSON Script, Not TypeScript for Logic

Business logic lives in JSON Script v2.2.0, not TypeScript.

{
  "version": "2.2.0",
  "nodes": [
    {
      "id": "filter",
      "type": "operation",
      "op": "filter",
      "condition": "{{ $json.status === 'active' }}"
    }
  ]
}

Why: Non-technical users understand JSON, GUIs can generate it, no compilation needed.

5. One Lambda Per File

Each file = one focused function, period.

// ✅ CORRECT
// src/lib/users/createUser.ts
export async function createUser(data: UserData): Promise<User> { ... }

// src/lib/users/listUsers.ts
export async function listUsers(): Promise<User[]> { ... }

// ❌ WRONG: Multiple functions in one file
// src/lib/users.ts
export function createUser() { ... }
export function listUsers() { ... }
export function deleteUser() { ... }

6. DBAL > Prisma > Raw SQL

Use highest abstraction level available.

// ✅ HIGHEST (handles multi-tenant, ACL, caching)
const db = getDBALClient()
const users = await db.users.list()

// ⚠️ MIDDLE (only if DBAL doesn't support)
const prisma = getPrismaClient()
const users = await prisma.user.findMany()

// ❌ LOWEST (never do this)
const query = "SELECT * FROM user"

---

Repository Structure (Quick Reference)

Monorepo Directory Tree:

metabuilder/
├── cadquerywrapper/      # CadQuery 3D CAD wrapper (Python)
├── caproverforge/        # CapRover mobile client (Android/Kotlin)
├── codegen/              # Code generation tools
├── config/               # Lint, test, misc configs
├── dbal/                 # Database Abstraction Layer
│   ├── development/      # DBAL TypeScript implementation
│   ├── production/       # Production build
│   └── shared/api/schema/# YAML entities (SOURCE OF TRUTH)
├── deployment/           # Docker & infrastructure
├── dockerterminal/       # Docker Swarm management (Next.js)
├── docs/                 # Documentation (organized)
│   ├── analysis/         # Status reports, assessments
│   ├── architecture/     # System design docs
│   ├── guides/           # Quick references, how-tos
│   ├── implementation/   # Implementation details
│   ├── packages/         # Package-specific docs
│   ├── phases/           # Phase completion reports
│   ├── testing/          # E2E and test docs
│   └── workflow/         # Workflow engine docs
├── e2e/                  # End-to-end Playwright tests
├── fakemui/              # Material UI clone (React/QML)
├── frontends/            # Multiple frontends
│   ├── cli/              # Command-line interface
│   ├── nextjs/           # Primary web UI
│   └── qt6/              # Desktop application
├── gameengine/           # SDL3 C++ game engine
├── mojo/                 # Mojo examples (systems programming)
│   └── examples/         # Official Modular examples
├── packagerepo/          # Package repository service
├── packages/             # 62+ feature packages
├── pastebin/             # Snippet pastebin (Next.js)
├── pcbgenerator/         # PCB design library (Python)
├── postgres/             # PostgreSQL utilities
├── repoforge/            # GitHub Android client (Kotlin)
├── schemas/              # JSON validation schemas
├── scripts/              # Build and migration scripts
├── services/             # Background services
├── smtprelay/            # SMTP relay (Python/Twisted)
├── sparkos/              # Minimal Linux distro + Qt6 app
├── storybook/            # Component stories
├── workflow/             # Workflow engine
│   ├── executor/         # Multi-language executors
│   │   ├── ts/           # TypeScript core engine
│   │   ├── python/       # Python executor
│   │   └── cpp/          # C++ executor (planned)
│   ├── examples/         # Workflow examples
│   └── plugins/          # Workflow plugins
└── [root files]          # CLAUDE.md, README.md, etc.

Standalone Projects in Monorepo:

Project	Purpose	Tech Stack
cadquerywrapper/	Parametric 3D CAD modeling	Python, CadQuery
caproverforge/	CapRover PaaS mobile client	Android, Kotlin
codegen/	Visual code generation studio	React, Vite, TypeScript
dockerterminal/	Docker Swarm management	Next.js, TypeScript
fakemui/	Material UI clone (React + QML)	React, QML, TypeScript
gameengine/	2D/3D game engine	C++, SDL3
mojo/	Systems programming examples	Mojo (Python superset)
packagerepo/	Package repository service	Python, FastAPI
pastebin/	Code snippet sharing	Next.js, TypeScript
pcbgenerator/	PCB design automation	Python
postgres/	PostgreSQL admin dashboard	Next.js, Drizzle ORM
repoforge/	GitHub client for Android	Kotlin, Compose
smtprelay/	Email relay server	Python, Twisted
sparkos/	Minimal Linux + Qt6 app	C++, Qt6, Linux
storybook/	Component documentation	React, Vite, Storybook

Critical Root Files:

• CLAUDE.md - THIS FILE (in docs/)
• AGENTS.md - Domain-specific rules (in docs/)
• README.md - Project overview (in docs/)
• package.json - Workspace configuration
• playwright.config.ts - E2E test config

Understanding the Structure:

• Schemas drive development: YAML entities → Prisma schema → JSON validation → Code
• Packages are modular: Each package is self-contained with its own structure
• Multi-layer architecture: Database layer (DBAL) → API (Next.js) → Frontend (React/CLI/Qt6)
• Everything multi-tenant: Every entity has tenantId - mandatory filtering
• Standalone projects: Integrated into monorepo but maintain independence

---

Architecture Overview

Three-Tier System

Frontend (Next.js/CLI/Qt6)
  ↓
DBAL (TypeScript Phase 2, C++ Phase 3)
  ↓
Database (SQLite dev, PostgreSQL prod)

Routing Pattern

/api/v1/{tenant}/{package}/{entity}[/{id}[/{action}]]

GET  /api/v1/acme/forum_forge/posts          → List
POST /api/v1/acme/forum_forge/posts          → Create
GET  /api/v1/acme/forum_forge/posts/123      → Get
PUT  /api/v1/acme/forum_forge/posts/123      → Update
DELETE /api/v1/acme/forum_forge/posts/123    → Delete
POST /api/v1/acme/forum_forge/posts/123/like → Custom action

---

JSON-First Philosophy

UI Components as JSON

{
  "id": "comp_hero",
  "name": "Hero Section",
  "render": {
    "type": "Container",
    "props": { "variant": "primary" },
    "children": [
      {
        "type": "Heading",
        "props": { "text": "Welcome" }
      }
    ]
  }
}

Pages as JSON

{
  "id": "page_home",
  "path": "/",
  "title": "Home",
  "tenantId": "acme",
  "component": "home_page",
  "isPublished": true
}

Workflows as JSON Script

{
  "version": "2.2.0",
  "nodes": [
    {
      "id": "step1",
      "type": "operation",
      "op": "transform_data",
      "input": "{{ $json }}",
      "output": "{{ $utils.flatten($json) }}"
    }
  ]
}

No hardcoded TypeScript UI logic! Everything is JSON that GUIs can generate.

---

Multi-Tenant & Security

Rate Limiting (Always Apply)

import { applyRateLimit } from '@/lib/middleware'

export async function POST(request: NextRequest) {
  // Apply rate limit
  const limitResponse = applyRateLimit(request, 'mutation')
  if (limitResponse) return limitResponse
  
  // Rest of handler
}

Rate limits:

• Login: 5 attempts/minute
• Register: 3 attempts/minute
• List: 100 requests/minute
• Mutations: 50 requests/minute
• Bootstrap: 1 attempt/hour

Multi-Tenant Filtering (Always Apply)

// ✅ CORRECT
const filter = tenantId !== undefined ? { tenantId } : {}
const records = await adapter.list(entity, { filter })

// ❌ WRONG: Data leak!
const records = await adapter.list(entity)

Rule: Every database query filters by tenantId. No exceptions.

---

Code Organization

Directory Structure

/dbal/
  /development/src/
    /core/client/      # DBAL implementation
    /adapters/         # Prisma adapter
    /seeds/            # Seed logic
  /shared/api/schema/  # YAML schemas (source of truth)
    /entities/         # 27 entity definitions
    /operations/       # 7 operation specs

/frontends/nextjs/
  /src/lib/
    /middleware/       # Express-style middleware
    /routing/          # API routing helpers
    /db-client.ts      # DBAL singleton
  /app/api/
    /v1/[...slug]/     # RESTful API

/packages/             # 62 packages total
  /{packageId}/
    /page-config/      # Routes
    /workflow/         # Workflows (JSON Script v2.2.0)
    /component/        # Components
    /permissions/      # Roles & permissions
    /styles/           # Design tokens
    /tests/            # Unit tests
    /playwright/       # E2E tests
    package.json       # Package metadata + file inventory

/schemas/
  /package-schemas/    # 27 JSON schemas for validation
    /{schema}.json     # Metadata, entities, types, scripts, components, etc.
    /examples/         # Reference templates (minimal, complete, advanced)
  README.md            # Schema overview
  SEED_SCHEMAS.md      # Seed data validation guide
  yaml-schema.yaml     # YAML meta-schema

What Goes Where

Item	Location	Format
Entity definitions	/dbal/shared/api/schema/entities/	YAML (27 files)
Entity operations	/dbal/shared/api/schema/operations/	YAML (7 files)
API routes	/frontends/nextjs/src/app/api/	TypeScript
UI definitions	/packages/{pkg}/component/	JSON
Workflows	/packages/{pkg}/workflow/	JSON Script v2.2.0
Pages/routes	/packages/{pkg}/page-config/	JSON
Package metadata	/packages/{pkg}/package.json	JSON (with file inventory)
Schema validation	/schemas/package-schemas/	JSON Schema (27 files)

Package File Inventory

Each package.json now includes a files section documenting all contained files:

{
  "packageId": "my_package",
  "files": {
    "directories": ["components", "page-config", "tests", ...],
    "byType": {
      "components": ["components/ui.json"],
      "pages": ["page-config/page-config.json"],
      "workflows": ["workflow/init.jsonscript"],
      "tests": ["tests/test.json", "playwright/tests.json"],
      "config": ["package.json"],
      "permissions": ["permissions/roles.json"],
      "styles": ["styles/tokens.json"],
      "schemas": ["entities/schema.json"]
    }
  }
}

See PACKAGE_INVENTORY_GUIDE.md for usage examples.

---

What NOT to Do

❌ Don't Use Prisma Directly

// ❌ WRONG
import { prisma } from '@/lib/config/prisma'
const users = await prisma.user.findMany()

// ✅ CORRECT
const db = getDBALClient()
const users = await db.users.list()

❌ Don't Hardcode Configuration

// ❌ WRONG: Hardcoded routes
const routes = [
  { path: '/', component: 'home' },
  { path: '/about', component: 'about' }
]

// ✅ CORRECT: In database/JSON
// /packages/my_package/page-config/routes.json

❌ Don't Skip tenantId Filtering

// ❌ WRONG: Data leak!
const users = await db.users.list()

// ✅ CORRECT
const users = await db.users.list({
  filter: { tenantId }
})

❌ Don't Put Multiple Functions in One File

// ❌ WRONG
// src/lib/users.ts
export function create() { ... }
export function list() { ... }
export function delete() { ... }

// ✅ CORRECT
// src/lib/users/create.ts
export function createUser() { ... }

// src/lib/users/list.ts
export function listUsers() { ... }

// src/lib/users/delete.ts
export function deleteUser() { ... }

❌ Don't Use TypeScript for Business Logic

// ❌ WRONG: TypeScript workflow logic
export function processOrder(order) {
  if (order.status === 'pending') {
    // Complex TypeScript logic
  }
}

// ✅ CORRECT: JSON Script
{
  "nodes": [
    {
      "op": "filter",
      "condition": "{{ $json.status === 'pending' }}"
    }
  ]
}

❌ Don't Forget Rate Limiting on APIs

// ❌ WRONG: Missing rate limit
export async function POST(request: NextRequest) {
  // No protection!
}

// ✅ CORRECT
export async function POST(request: NextRequest) {
  const limitResponse = applyRateLimit(request, 'mutation')
  if (limitResponse) return limitResponse
}

❌ Don't Ignore YAML Schemas

// ❌ WRONG: Schema in code
interface User {
  id: string
  name: string
}

// ✅ CORRECT: YAML source of truth
// /dbal/shared/api/schema/entities/core/user.yaml

---

Quick Reference

Common Commands

# Development
npm run dev                 # Start dev server
npm run typecheck          # Check TypeScript
npm run build              # Build production
npm run test:e2e           # Run tests

# Database
npm --prefix dbal/development run codegen:prisma    # YAML → Prisma
npm --prefix dbal/development run db:push           # Apply schema

# Documentation
http://localhost:3000/api/docs     # API docs

Key Files

• Rate Limiting: frontends/nextjs/src/lib/middleware/rate-limit.ts
• DBAL Client: frontends/nextjs/src/lib/db-client.ts
• API Routes: frontends/nextjs/src/app/api/v1/[...slug]/route.ts
• YAML Schemas: dbal/shared/api/schema/entities/ (source of truth)
• JSON Schemas: schemas/package-schemas/ (validation & documentation)

Documentation

Core Principles & Development:

• This file: CLAUDE.md (core principles)
• Rate Limiting: /docs/RATE_LIMITING_GUIDE.md
• Multi-Tenant: /docs/MULTI_TENANT_AUDIT.md
• API Reference: /docs/API_DOCUMENTATION_GUIDE.md
• Strategic Guide: /STRATEGIC_POLISH_GUIDE.md

Schemas & Package Documentation:

• All Schemas: SCHEMAS_COMPREHENSIVE.md - 27 JSON schemas + 27 YAML entities
• Quick Start: schemas/package-schemas/QUICKSTART.md - 30-second patterns
• Schema Reference: schemas/package-schemas/SCHEMAS_README.md - Complete 16 schema overview
• Package Inventory: PACKAGES_INVENTORY.md - All 62 packages with files
• Package Guide: PACKAGE_INVENTORY_GUIDE.md - How to use package.json files section
• Seed Schemas: schemas/SEED_SCHEMAS.md - Seed data validation & entity types
• Root Schemas: schemas/README.md - Schema overview & core database structure

---

Development Workflow

Phase 1: Explore (MANDATORY - Never Skip)

1. Read Foundation Docs (15 min)

   • /CLAUDE.md core principles
   • /AGENTS.md for your domain
   • /README.md project overview

2. Map the Codebase (30-45 min)

   • Use Explore agent to understand structure
   • Identify where similar work exists
   • Check relevant schemas and types
   • Review 2-3 similar implementations

3. Verify Dependencies (10 min)

   • Build passes: npm run build
   • Tests pass: npm run test
   • No blocking issues in /TECH_DEBT.md

Checklist Before Moving to Phase 2:

• You can explain the existing pattern for your task type
• You've found 2-3 examples of similar work
• You understand the directory structure
• You know what schemas/types are involved
• You've identified any blockers or dependencies

Phase 2: Design (Before Coding)

1. Schema Design (if needed)

   • Update YAML in /dbal/shared/api/schema/entities/
   • Generate Prisma: npm --prefix dbal/development run codegen:prisma
   • Create validation schemas in /schemas/package-schemas/

2. Architecture Design

   • Sketch file structure and naming
   • Identify multi-tenant filtering points
   • Plan rate limiting strategy
   • Document any deviations from existing patterns

3. Get Alignment

   • If patterns unclear, ask for clarification
   • If task scope seems large, break it down
   • Verify assumptions about dependencies

Phase 3: Implementation

1. Start Implementation with Code Review Agent proactively
2. Apply multi-tenant filtering to ALL database queries
3. Add rate limiting to sensitive endpoints
4. Follow one-function-per-file pattern
5. Use JSON Script for business logic, not TypeScript

Before Committing

• TypeScript compiles: npm run typecheck
• Tests pass (99%+): npm run test:e2e
• Build succeeds: npm run build
• One function per file rule followed
• Multi-tenant filtering applied everywhere (tenantId check)
• Rate limiting on sensitive endpoints
• No Prisma direct usage (use DBAL)
• Business logic in JSON Script, not TypeScript
• Documentation updated
• Code review completed

---

Status: Production Ready (Phase 2 Complete) Next: Universal Platform - Core Infrastructure (State Machine, Command Bus, Event Stream, VFS, Frontend Bus)