mirror of https://github.com/johndoe6345789/metabuilder.git synced 2026-04-25 14:25:02 +00:00

Files

2026-01-21 17:53:36 +00:00

29 KiB

Raw Blame History

AI Agent Development Guide for MetaBuilder

START HERE: This document guides AI agents working on any part of MetaBuilder. Read the sections relevant to your task.

Finding Tech Debt → See /TECH_DEBT.md (bot-actionable task list with explicit instructions)
Starting Development → Core Principles + Scoped Rules
Working on DBAL → DBAL Development
Working on Frontend → Frontend Development
Working on Packages → Package Development
Running Tests → Testing Strategy
Deploying Code → Deployment
Troubleshooting → Troubleshooting

Core Principles

These principles apply to all development work on MetaBuilder:

1. Data-Driven Architecture (95% Rule)

MetaBuilder is 95% JSON/YAML configuration, not code:

5% TypeScript = Infrastructure, adapters, frameworks, bootstrapping
95% JSON/YAML = UI definitions, business logic, configurations, database schemas

When choosing between code and config: always prefer config.

// ❌ WRONG: Hardcoded UI
function HomePage() {
  return <div>Welcome to MetaBuilder</div>
}

// ✅ CORRECT: JSON definition
// File: packages/ui_home/seed/metadata.json
{
  "pages": [{
    "id": "home",
    "path": "/",
    "component": "DeclaredComponent",
    "config": { "title": "Welcome to MetaBuilder" }
  }]
}

2. One Lambda Per File

Every file should be one focused unit:

// ✅ CORRECT
// File: src/lib/users/createUser.ts
export async function createUser(username: string): Promise<User> {
  // Single responsibility
}

// ✅ CORRECT (class as container)
// File: src/lib/users/UserManager.ts
export class UserManager {
  static async create = createUser
  static async list = listUsers
}

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

See .github/prompts/LAMBDA_PROMPT.md for detailed guidance.

3. Schema-First Development

Always define schema before implementation:

1. Define in YAML/JSON schema (source of truth)
2. Generate types from schema
3. Implement code that conforms to types
4. Add tests

Never generate schema from code or hardcode types.

4. Multi-Tenant Safety

Every query must include tenant filtering:

// ❌ WRONG: No tenant filter
const users = await db.users.list()

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

5. ACL (Access Control) First

Every database operation must check permissions:

// Always use DBAL which includes ACL checks
const db = getDBALClient()
const users = await db.users.list() // ACL applied automatically

Scoped Rules

CRITICAL: Before starting work, check for scoped AGENTS.md or similar files in your working directory:

Location	Purpose
`AGENTS.md` (root)	Start here - General MetaBuilder guidance for AI agents
`CLAUDE.md` (root)	Overall project instructions (more detailed than AGENTS.md)
`ARCHITECTURE.md`	System architecture and data flow
`dbal/docs/`	DBAL-specific documentation and guides
`dbal/shared/docs/AGENTS.md`	YAML schema development rules (if exists)
`dbal/development/docs/AGENTS.md`	TypeScript DBAL rules (if exists)
`frontends/nextjs/AGENTS.md`	Next.js frontend rules (if exists)
`packages/[name]/AGENTS.md`	Package-specific rules (if exists)

Pattern:

Find the directory/subsystem you're editing
Search for AGENTS.md or similar guidance files in that directory or parents
Scoped rules override general guidance
Read completely before starting work

DBAL Development (Phase 2 & Phase 3)

The DBAL (Database Abstraction Layer) is a language-agnostic contract system:

Phase 2 (Current): TypeScript in /dbal/development/ with Prisma adapter
Phase 3 (Future): C++ daemon in /dbal/production/ with security isolation

DBAL Architecture Philosophy

1. API Definition (YAML) ← Source of truth
       ↓
2. Development Implementation (TypeScript) ← Fast iteration
       ↓
3. Production Implementation (C++) ← Security & performance
       ↓
4. Conformance Tests ← Guarantee parity

Key Rules for DBAL Work

1. Schema First (API Contract is Source of Truth)

# CORRECT workflow:
1. Edit: /dbal/shared/api/schema/entities/user.yaml
2. Generate: npm --prefix dbal/development run codegen:prisma
3. Push: npm --prefix dbal/development run db:push
4. Implement TypeScript code
5. Add tests

# WRONG:
❌ Edit Prisma schema directly
❌ Hardcode fields in TypeScript
❌ Generate schema from code

2. File Organization

YAML Schemas (source of truth):

/dbal/shared/api/schema/
├── entities/
│   ├── core/          (User, Session, Workflow, etc.)
│   ├── access/        (Credential, PageConfig, etc.)
│   └── packages/      (Package-specific entities)
├── operations/        (Operation definitions)
└── capabilities.yaml  (Adapter capabilities)

TypeScript Implementation (Phase 2):

/dbal/development/src/
├── core/              (Client, types, errors)
├── adapters/          (Database adapters: Prisma, SQLite, etc.)
├── runtime/           (Config, secrets, telemetry)
└── seeds/             (Seed orchestration)

C++ Implementation (Phase 3):

/dbal/production/
├── include/dbal/      (Public headers)
├── src/               (Implementation)
└── tests/             (Tests)

3. Code Generation

Phase 2 (TypeScript - Current):

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

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

# Rebuild types
npm --prefix dbal/development run build

Never edit generated files manually:

/prisma/schema.prisma - Auto-generated
/dbal/development/src/core/types.ts - Auto-generated

4. Using DBAL Client

// CORRECT: Use factory from DBAL
import { getDBALClient } from '@/dbal'

const db = getDBALClient()
const users = await db.users.list()

// WRONG:
❌ import { prisma } from '@/lib/prisma'  // Direct Prisma access
❌ import { getAdapter } from '@/lib/dbal-client/adapter'  // Old adapter

5. Adding Entities/Fields

# 1. Update YAML schema
vim /dbal/shared/api/schema/entities/core/user.yaml
# Add: avatar_url: { type: string, optional: true }

# 2. Regenerate Prisma
npm --prefix dbal/development run codegen:prisma

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

# 4. Update TypeScript code to use new field
# (Types auto-generated, so just use the field)

# 5. Add tests
# Update test files to cover new functionality

6. Security Considerations

❌ Never:

Expose database credentials to user code
Allow raw SQL queries from user input
Skip ACL checks
Trust user input without validation
Log sensitive data (passwords, tokens, PII)

✅ Always:

Validate input against schema
Enforce row-level security (multi-tenant)
Use parameterized queries (Prisma handles this)
Log security-relevant operations
Test with malicious input

Frontend Development

Next.js Frontend (`/frontends/nextjs/`)

Key Rules

Use DBAL for all database access:

// CORRECT
import { getDBALClient } from '@/dbal'
const db = getDBALClient()
const users = await db.users.list()

// WRONG
❌ Direct Prisma access
❌ SQL queries
❌ Old adapter patterns

Follow one lambda per file:

src/lib/users/createUser.ts    (single function)
src/lib/users/UserManager.ts   (class as container)
src/api/users/route.ts         (single handler)

Keep API routes thin:

// ✅ CORRECT: API route delegates to DBAL
export async function GET(request: Request) {
  const db = getDBALClient()
  const users = await db.users.list()
  return Response.json(users)
}

// ❌ WRONG: Complex logic in route
export async function POST(request: Request) {
  const data = await request.json()
  // Complex validation, transformation, etc.
  // Should be in a separate function
}

E2E Tests with Playwright:

# Generate schema
npm --prefix dbal/development run codegen:prisma

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

# Run tests
npm run test:e2e

See TESTING.md for comprehensive E2E testing guide.

Component Documentation (Storybook)

🚨 CRITICAL GUARDRAIL: Stories Are Data, Not Code

Like tests, Storybook stories must be JSON, not TypeScript!

❌ WRONG: Writing new .stories.tsx files

// DON'T DO THIS - No new .stories.tsx files!
export const HomePage: Story = {
  render: () => <HomePage title="Welcome" />
}

✅ CORRECT: JSON story definitions in packages

// packages/ui_home/storybook/stories.json
{
  "$schema": "https://metabuilder.dev/schemas/package-storybook.schema.json",
  "title": "Home Page Components",
  "stories": [{
    "name": "HomePage",
    "render": "home_page",
    "description": "Complete home page",
    "args": {
      "title": "Welcome to MetaBuilder"
    }
  }]
}

Story Location Rules:

✅ packages/{package_name}/storybook/stories.json - Package stories (PREFERRED)
✅ storybook/src/stories/*.stories.tsx - Existing stories (legacy, don't add more)
❌ NEVER create new .stories.tsx files - use JSON instead!

JSON Story Loader:

Stories defined in packages/*/storybook/stories.json are auto-discovered
storybook/json-loader/ loads and renders JSON stories directly
No code generation - JSON is rendered at runtime
Uses DynamicStory component to render from JSON definitions

See storybook/json-loader/README.md for complete guide.

Project Structure

frontends/nextjs/src/
├── app/                    (Next.js App Router)
│   ├── api/               (API routes - keep thin)
│   ├── (pages)/           (Pages)
│   └── layout.tsx         (Root layout)
├── lib/
│   ├── db-client.ts       (DBAL integration)
│   └── [feature]/         (Feature-specific utilities)
├── components/            (React components)
└── styles/                (CSS/styling)

Package Development

Creating New Packages (`/packages/[name]/`)

A package is a self-contained feature with UI, configuration, and optional database entities.

Package Structure

packages/my_feature/
├── seed/
│   └── metadata.json      (Package definition & seed data)
├── components/            (Optional: package-specific components)
├── public/                (Static assets)
└── README.md              (Package documentation)

Package Metadata (`seed/metadata.json`)

{
  "packageId": "my_feature",
  "name": "My Feature",
  "version": "1.0.0",
  "permissions": {
    "required": ["feature:read", "feature:write"]
  },
  "pages": [{
    "id": "main",
    "path": "/my-feature",
    "title": "My Feature",
    "component": "DeclaredComponent",
    "config": { }
  }],
  "entities": [],
  "scripts": [],
  "migrations": []
}

Development Workflow

Create package structure:

mkdir -p packages/my_feature/seed

Define metadata (seed/metadata.json):

{
  "packageId": "my_feature",
  "name": "My Feature",
  "version": "1.0.0"
}

Add to installed packages:

# Edit: seed/database/installed_packages.yaml
- packageId: my_feature
  source: packages/my_feature

Run bootstrap:

./deployment/scripts/bootstrap-system.sh

Test:

npm run test:e2e

Key Rules

95% of package definition is JSON, not code
Use DeclaredComponent for all UI
Define configuration in JSON, not hardcoded
One responsibility per component
Test packages with E2E tests

Testing Strategy

Test Pyramid

           ↑
           │  E2E Tests (Playwright)
           │  - Full app flow
           │  - Real database
           │  - Real users
           │
           │  Integration Tests
           │  - Component + DBAL
           │  - SQLite/test DB
           │
           │  Unit Tests
           │  - Individual functions
           │  - Mocked dependencies
           │
           └─────────────────────

Running Tests

Unit tests (DBAL):

npm --prefix dbal/development run test:unit

Integration tests (DBAL):

npm --prefix dbal/development run test:integration

E2E tests (Full app):

# 1. Generate schema
npm --prefix dbal/development run codegen:prisma

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

# 3. Run E2E tests
npm run test:e2e

Writing Tests

🚨 CRITICAL GUARDRAIL: Tests Are Data, Not Code

MetaBuilder follows the 95% JSON rule for tests too. Tests must be defined as JSON, not TypeScript!

❌ WRONG: Writing new .spec.ts files

// DON'T DO THIS - No new .spec.ts files!
test('should login', async ({ page }) => {
  await page.goto('/login')
  await page.fill('[name="username"]', 'user')
})

✅ CORRECT: JSON test definitions in packages

// packages/auth/playwright/tests.json
{
  "$schema": "https://metabuilder.dev/schemas/package-playwright.schema.json",
  "package": "auth",
  "tests": [{
    "name": "should login",
    "tags": ["@auth", "@smoke"],
    "steps": [
      {"action": "navigate", "url": "/login"},
      {"action": "fill", "label": "Username", "value": "user"},
      {"action": "click", "role": "button", "text": "Login"}
    ]
  }]
}

Test Location Rules:

✅ packages/{package_name}/playwright/tests.json - Package-scoped tests (NEW)
✅ e2e/*.spec.ts - Existing manual tests (legacy, don't add more)
✅ e2e/json-packages.spec.ts - Auto-loads all package JSON tests
❌ NEVER create new .spec.ts files - use JSON instead!

JSON Test Runner:

Tests defined in packages/*/playwright/tests.json are auto-discovered
e2e/json-runner/playwright-json-runner.ts interprets and executes JSON directly
No code generation - JSON is executed at runtime
Changes to JSON tests take effect immediately

Running JSON Tests:

npm run test:e2e:json              # All package JSON tests
npm run test:e2e -- e2e/json-packages.spec.ts  # Same thing, explicit

Unit test example (still TypeScript):

// tests/lib/users/createUser.test.ts
import { createUser } from '@/lib/users/createUser'

describe('createUser', () => {
  it('should create a user', async () => {
    const user = await createUser('john', 'john@example.com')
    expect(user.username).toBe('john')
  })
})

See TESTING.md and e2e/json-runner/README.md for comprehensive testing guide.

Deployment Guidelines

Development Deployment

# Terminal 1: Frontend
cd frontends/nextjs
npm run dev  # http://localhost:3000

# Terminal 2: Generate and push schema (once)
npm --prefix dbal/development run codegen:prisma
npm --prefix dbal/development run db:push

# Terminal 3: Run tests
npm run test:e2e

Production Deployment

# Using deployment script
./deployment/deploy.sh all --bootstrap

# Or docker-compose with GHCR images
docker compose -f docker-compose.ghcr.yml up -d

What gets deployed:

PostgreSQL 16 (database)
C++ DBAL daemon (Phase 3 when ready)
Next.js frontend
C++ Media daemon (FFmpeg, ImageMagick)
Redis 7 (caching)
Nginx (reverse proxy, SSL/TLS)
Optional: Prometheus, Grafana, Loki (monitoring)

Schema Management

Local development:

# Edit YAML schema
vim /dbal/shared/api/schema/entities/core/user.yaml

# Regenerate Prisma
npm --prefix dbal/development run codegen:prisma

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

Before committing:

Always regenerate schema from YAML
Push to ensure tables exist
Run E2E tests
Commit generated schema changes

Troubleshooting

"The table X does not exist"

# Solution: Generate and push schema
npm --prefix dbal/development run codegen:prisma
npm --prefix dbal/development run db:push

"Cannot find module '@/dbal'"

# Solution: Verify DBAL exports
cat dbal/development/src/index.ts | grep getDBALClient

E2E tests fail with database errors

# Solution: Regenerate schema, push, then test
npm --prefix dbal/development run codegen:prisma
npm --prefix dbal/development run db:push
npm run test:e2e

TypeScript type errors in DBAL

# Solution: Rebuild DBAL
npm --prefix dbal/development run build
npm --prefix dbal/development run codegen:prisma

Package not loading

# Check: Is package in installed_packages.yaml?
cat seed/database/installed_packages.yaml | grep packageId

# Check: Is metadata.json valid JSON?
cat packages/[name]/seed/metadata.json | jq .

# Solution: Run bootstrap
./deployment/scripts/bootstrap-system.sh

Tests fail with "seed not loaded"

# Solution: Ensure global.setup.ts runs
# Check playwright.config.ts has: globalSetup: './e2e/global.setup.ts'

# Manual fix: Call seed endpoint
curl http://localhost:3000/api/setup

Best Practices Summary

✅ Schema-first - Define in YAML, generate code
✅ 95% config, 5% code - Prefer JSON/YAML over TypeScript
✅ One lambda per file - Small, focused units
✅ Multi-tenant safe - Always filter by tenantId
✅ ACL-first - Every operation checks permissions
✅ Use DBAL - Never bypass database abstraction
✅ Test thoroughly - Unit → Integration → E2E
✅ Document scoped rules - Create AGENTS.md for subsystems
✅ Principle of least privilege - Minimal permissions
✅ Security by default - Validate early, fail fast

Key Documents

Read These First:

CLAUDE.md - Comprehensive project instructions
ARCHITECTURE.md - System architecture and data flow
.github/copilot-instructions.md - AI-specific development patterns

Subsystem Guides:

dbal/shared/docs/ - DBAL implementation guides
dbal/docs/ - DBAL-specific rules
TESTING.md - E2E testing guide
DBAL_REFACTOR_PLAN.md - Phase 2 cleanup roadmap

Schemas:

/dbal/shared/api/schema/ - DBAL entity definitions (YAML)
/schemas/package-schemas/ - Package system definitions (JSON)
/.github/prompts/LAMBDA_PROMPT.md - Code organization pattern
/.github/prompts/WORKFLOW_PROMPTS/ - Development workflow guides

Quick Reference:

README.md - System overview
ROADMAP.md - Project vision and evolution

Project Structure

metabuilder/
├── 📋 Core Documentation
│   ├── AGENTS.md                   ⭐ START HERE - AI agent guide for all subsystems
│   ├── CLAUDE.md                   Comprehensive project instructions for AI assistants
│   ├── ARCHITECTURE.md             System architecture, data flow, deployment stack
│   ├── ROADMAP.md                  Project vision, evolution (Spark → Next.js)
│   ├── README.md                   System overview, quick start
│   └── TESTING.md                  E2E testing guide with Playwright
│
├── 🗄️ Database (DBAL)
│   ├── dbal/
│   │   ├── development/            ⭐ Phase 2: TypeScript DBAL implementation
│   │   │   ├── src/                Core client, adapters, seeds
│   │   │   ├── tests/              Unit & integration tests
│   │   │   └── prisma/             Prisma schema (auto-generated)
│   │   ├── production/             Phase 3: C++ DBAL daemon (future)
│   │   │   ├── include/dbal/       C++ public headers
│   │   │   ├── src/                C++ implementation
│   │   │   └── tests/              C++ tests
│   │   ├── shared/                 ⭐ Shared between Phase 2 & 3
│   │   │   ├── api/schema/         YAML entity & operation definitions (source of truth)
│   │   │   ├── backends/           Database connection utilities
│   │   │   ├── docs/               DBAL implementation guides
│   │   │   └── tools/              Code generation scripts
│   │   └── docs/                   DBAL-specific documentation
│
├── 🎨 Frontend
│   ├── frontends/
│   │   ├── nextjs/                 ⭐ Main Next.js application (Phase 2)
│   │   │   ├── src/app/            Next.js App Router (pages, API routes)
│   │   │   ├── src/lib/            Utilities (DBAL client integration, etc.)
│   │   │   ├── src/components/     React components
│   │   │   └── e2e/                Playwright E2E tests
│   │   ├── cli/                    CLI frontend (optional)
│   │   ├── qt6/                    Qt6 frontend (optional)
│   │   └── dbal/                   DBAL exports for frontend use
│
├── 📦 Packages
│   ├── packages/                   ⭐ Modular feature packages
│   │   ├── ui_home/                Landing page
│   │   ├── ui_header/              App header/navbar
│   │   ├── ui_footer/              App footer
│   │   ├── ui_login/               Login UI
│   │   ├── dashboard/              User dashboard
│   │   ├── user_manager/           User management (Admin)
│   │   ├── package_manager/        Package installation (God level)
│   │   ├── database_manager/       Database admin (Supergod level)
│   │   ├── schema_editor/          Schema editor (Supergod level)
│   │   └── [40+ other packages]/   Feature-specific packages with JSON metadata
│
├── 🌱 Seed Data
│   ├── seed/
│   │   ├── database/               Base bootstrap YAML data
│   │   │   ├── installed_packages.yaml  Package installation records
│   │   │   └── package_permissions.yaml Permission seed data
│   │   ├── packages/               Package-specific seed order
│   │   └── config/                 Configuration files
│
├── 📋 Schemas
│   ├── schemas/
│   │   ├── package-schemas/        ⭐ Package system JSON schemas (18+ files)
│   │   │   ├── metadata_schema.json    Package structure
│   │   │   ├── entities_schema.json    Database models from packages
│   │   │   ├── components_schema.json  UI component definitions
│   │   │   ├── script_schema.json      JSON Script language spec (v2.2.0)
│   │   │   └── [13+ more schemas]     API, validation, permissions, jobs, etc.
│   │   └── yaml-schema.yaml        DBAL YAML schema validator
│
├── 🚀 Deployment
│   ├── deployment/
│   │   ├── deploy.sh               ⭐ Main deployment orchestration script
│   │   ├── docker/                 Docker images & compose files
│   │   │   ├── Dockerfile.app      Next.js production image
│   │   │   ├── Dockerfile.app.dev  Dev environment image
│   │   │   └── docker-compose.*.yml Development, production, monitoring
│   │   ├── scripts/                Bootstrap, schema, backup scripts
│   │   │   ├── bootstrap-system.sh Core package installation
│   │   │   ├── init-db.sh          Database initialization
│   │   │   └── backup-database.sh  Backup utilities
│   │   └── config/                 Configuration templates
│   │       ├── dbal/               DBAL daemon config
│   │       ├── nginx/              Reverse proxy config
│   │       ├── prometheus/         Monitoring config
│   │       └── grafana/            Dashboards config
│
├── 🧪 Testing
│   ├── e2e/                        ⭐ End-to-end tests (Playwright)
│   │   ├── global.setup.ts         Database initialization
│   │   ├── auth/                   Authentication flows
│   │   ├── crud/                   CRUD operations
│   │   ├── api/                    API endpoint tests
│   │   ├── dbal-daemon/            DBAL daemon tests
│   │   └── *.spec.ts               Individual test suites
│   ├── playwright.config.ts        E2E test configuration
│   ├── config/test/                Test configuration directory
│   └── spec/                       TLA+ formal specifications
│
├── 🔧 Configuration
│   ├── config/
│   │   ├── package.json            ⭐ Root package definitions
│   │   ├── lint/                   ESLint configuration
│   │   └── test/                   Test tool configurations
│   ├── .github/
│   │   ├── prompts/                AI agent development workflows
│   │   │   ├── workflow/           Feature planning, review, docs
│   │   │   ├── implement/          Implementation guides (DBAL, components, etc.)
│   │   │   ├── test/               Testing guides
│   │   │   ├── deploy/             Deployment procedures
│   │   │   └── maintain/           Maintenance & debugging guides
│   │   ├── copilot-instructions.md AI development patterns
│   │   └── TEMPLATES.md            PR/issue templates
│
├── 📚 Documentation
│   ├── docs/                       Additional documentation
│   │   ├── TESTING_GUIDE.md        TDD methodology, test pyramid
│   │   ├── CONTAINER_IMAGES.md     Docker image registry
│   │   ├── PIPELINE_CONSOLIDATION.md CI/CD pipeline
│   │   └── archive/                Historical documentation
│   ├── DBAL_REFACTOR_PLAN.md       Phase 2 cleanup roadmap
│   ├── SEED_SYSTEM_OVERHAUL.md     Seed system improvements
│   └── README files in each subsystem
│
├── 🎭 Other Frontends (Reference)
│   ├── fakemui/                    QML/UI component library (reference)
│   ├── storybook/                  Component documentation (archived)
│   └── old/                        Legacy Spark implementation (archived)
│
├── 📡 Services
│   ├── services/
│   │   └── media_daemon/           C++ FFmpeg/ImageMagick daemon (future)
│
├── 🔬 Specifications
│   ├── spec/                       TLA+ formal specifications
│   │   ├── metabuilder.tla         Core system behavior
│   │   ├── package_system.tla      Package loading & management
│   │   ├── workflow_system.tla     Workflow execution
│   │   └── integrations.tla        Integration patterns
│
├── 🛠️ Scripts & Tools
│   ├── scripts/                    Utility scripts
│   │   ├── generate-package.ts     Package scaffolding
│   │   └── check-dbal-prisma-sync.py Schema validation
│
├── 💾 Database Files
│   ├── prisma/
│   │   ├── schema.prisma           ⭐ AUTO-GENERATED from YAML schemas
│   │   └── schema-registry.json    Schema version tracking
│   ├── test-prisma-adapter.js      Adapter tests
│
└── 📦 Root Configuration
    ├── package.json                ⭐ Root dependencies
    ├── package-lock.json           Dependency lock file
    ├── playwright.config.ts        E2E test configuration
    ├── docker-compose.ghcr.yml     GHCR image deployment
    └── Jenkinsfile                 CI/CD pipeline definition

Key Directory Roles

Core Development (Always Active):

dbal/development/ - TypeScript DBAL implementation
frontends/nextjs/ - Next.js frontend application
packages/ - Feature packages
dbal/shared/api/schema/ - Entity & operation definitions (YAML)

Supporting Systems:

deployment/ - Deployment automation and Docker
e2e/ - Playwright E2E tests
seed/ - Bootstrap data and seeding
.github/prompts/ - AI agent workflow guidance

Configuration (Do Not Edit):

prisma/schema.prisma - AUTO-GENERATED from YAML
dbal/development/src/core/types.ts - AUTO-GENERATED types

Reference/Archive:

old/ - Legacy Spark implementation
fakemui/ - Legacy QML components
storybook/ - Archived component documentation
spec/ - TLA+ formal specifications

Questions?

Stuck? See .github/prompts/misc/EEK-STUCK.md recovery guide
Need help? Use /help command in Claude Code
Report issues: https://github.com/anthropics/claude-code/issues

29 KiB Raw Blame History

AI Agent Development Guide for MetaBuilder

Quick Navigation

Core Principles

1. Data-Driven Architecture (95% Rule)

2. One Lambda Per File

3. Schema-First Development

4. Multi-Tenant Safety

5. ACL (Access Control) First

Scoped Rules

DBAL Development (Phase 2 & Phase 3)

DBAL Architecture Philosophy

Key Rules for DBAL Work

1. Schema First (API Contract is Source of Truth)

2. File Organization

3. Code Generation

4. Using DBAL Client

5. Adding Entities/Fields

6. Security Considerations

Frontend Development

Next.js Frontend (/frontends/nextjs/)

Key Rules

Component Documentation (Storybook)

Project Structure

Package Development

Creating New Packages (/packages/[name]/)

Package Structure

Package Metadata (seed/metadata.json)

Development Workflow

Key Rules

Testing Strategy

Test Pyramid

Running Tests

Writing Tests

Deployment Guidelines

Development Deployment

Production Deployment

Schema Management

Troubleshooting

"The table X does not exist"

"Cannot find module '@/dbal'"

E2E tests fail with database errors

TypeScript type errors in DBAL

Package not loading

Tests fail with "seed not loaded"

Best Practices Summary

Key Documents

Project Structure

Key Directory Roles

Questions?

29 KiB

Raw Blame History

Next.js Frontend (`/frontends/nextjs/`)

Creating New Packages (`/packages/[name]/`)

Package Metadata (`seed/metadata.json`)