Workspace Setup Complete:
- Added dbal/development to root package.json workspaces
- Added @metabuilder/dbal dependency to frontends/nextjs (file reference)
- Updated TypeScript paths in frontend to resolve via node_modules
- Installed workspace dependencies successfully
Structure Now In Place:
✅ dbal/development is registered as workspace
✅ @metabuilder/dbal dependency declared in frontend
✅ Path aliases configured for @/dbal resolution
✅ npm install works with all dependencies
Pre-existing DBAL Build Issues Found:
⚠️ src/core/foundation/types/types.generated missing
⚠️ CodeGen script (tsx ../shared/tools/codegen/gen_types.ts) failing
⚠️ exactOptionalPropertyTypes causing TypeScript errors in KV operations
These are pre-existing issues in DBAL code, not related to workspace setup.
Will need separate DBAL build fix task.
For now, workspace structure is ready for when DBAL build is fixed.
Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
Fixes for accuracy and completeness:
- Update DBAL usage example from old getAdapter() to new getDBALClient() pattern
- Clarify Phase 2 is TypeScript-only (C++ daemon is Phase 3, future work)
- Fix rate limiting claim - mark as in-progress (TD-2) instead of implemented
- Add developer routing section at top ("For Different Audiences")
- Restructure "Learn More" section with clear categories and links to all key docs
- Add "Current Status" section showing Phase 2 completion % and current tech debt
- Link prominently to AGENTS.md, CLAUDE.md, and TECH_DEBT.md for developers
- Note about TypeScript DBAL being current approach in development workflow
Now README serves both end users (setup, concepts) and developers (guidance, status, task list).
Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
Add explicit, step-by-step instructions for each tech debt item so bots know exactly what to do:
- TD-1: DBAL Refactoring (🔴 CRITICAL) - Move database logic from frontend to DBAL (13 steps)
- TD-2: Rate limiting (🟡 HIGH) - Protect API endpoints from abuse
- TD-3: OpenAPI/Swagger (🟡 HIGH) - API contract visibility and client generation
- TD-4: Error handling docs (🟡 MEDIUM) - Consistent error response patterns
Also included 9 Phase 3+ tasks (TD-5 through TD-13) for future reference.
Each task includes:
- Current status and priority
- Clear problem statement
- Impact analysis
- Bot-actionable instructions (step-by-step)
- Expected outcomes
Updated ROADMAP.md, CLAUDE.md, and AGENTS.md to reference TECH_DEBT.md.
Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
Introduced a comprehensive AGENTS.md at the project root to provide unified guidance for all AI agents, covering core principles, DBAL, frontend, package development, testing, deployment, and troubleshooting. Updated CLAUDE.md to reference the new AGENTS.md location and its expanded scope, clarified the pattern for scoped rules, and improved quick reference tables. Replaced dbal/docs/AGENTS.md with a redirect notice pointing to the new root AGENTS.md. Minor update to .claude/settings.local.json to allow 'tree' command.
Added comprehensive guidance to prevent bot confusion:
- Complete .github/prompts/ workflow reference (8-step development process)
- Scoped rules for AGENTS.md files in subdirectories (mandatory read before editing)
- One-lambda-per-file code organization pattern with examples
- 95% JSON/Lua architecture principle (vs. 5% TypeScript infrastructure)
- Multi-tenant-first principle (always filter by tenantId)
- New Mistake #7: Using TypeScript instead of JSON/Lua
- Expanded onboarding steps with clear sequencing
- References to EEK-STUCK.md recovery guide
- References to TEMPLATES.md for PR/issue guidelines
- References to dbal/docs/AGENTS.md for DBAL-specific rules
Addresses user feedback: "Project been messed up by bots, need clear foundation"
This documentation should prevent future bot confusion by being explicit about:
- Development workflow (.github/prompts/ organization)
- Code organization patterns (lambda pattern)
- Data-driven architecture (JSON/Lua, not TS)
- Scoped rules (AGENTS.md files override general guidance)
Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
ROADMAP.md contains:
- Project vision and core philosophy
- Project history (evolution from Spark-based version to Next.js)
- Migration path and what was preserved/reimplemented
- Features and enhancements (52 packages, multi-tenancy, etc.)
- Current status (MVP achieved, Phase 2 in progress)
This helps bots understand the project evolution and long-term vision.
Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
Added Complete Coverage:
- Core MetaBuilder concepts (mental model, principles)
- Available packages (8 packages with purpose and permission levels)
- 6-level permission system (Public to Supergod)
- Production deployment stack (PostgreSQL, DBAL, Media daemon, Redis, Nginx)
- Bootstrap process (7 phases with package installation order)
- One-command deployment instructions (./deployment/deploy.sh)
- Development setup (root and nextjs options)
- Docker deployment with GHCR images
- Development workflow with multiple terminal instructions
- C++ daemon build instructions
Documentation Improvements:
- Added 18 "Further Reading" references
- Included testing guide reference
- Referenced deployment automation scripts
- Added bootstrap package order from core-packages.yaml
- Explained what production stack includes
- Clarified Phase 2 vs Phase 3 differences with actual services
- Added development workflow setup
This prevents bot errors like:
- Not knowing about deployment/deploy.sh
- Not understanding bootstrap process with 7 phases
- Not knowing about production services (Media daemon, Redis, Nginx)
- Not understanding 6-level permission system
- Not knowing about available packages
- Not understanding how to deploy with Docker
- Not knowing about GHCR container images
Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
Added Complete Coverage:
- Phase 2 (Current): TypeScript DBAL in /dbal/development/
- Phase 3 (Future): C++ DBAL daemon in /dbal/production/
- Shared architecture: /dbal/shared/ (YAML schemas, docs, tools)
- Project structure overview with all directories
- Explanation of three-layer DBAL system
Key Documentation Improvements:
- 6 detailed common mistakes with examples
- Complete file location guide (TypeScript, C++, YAML, seeds)
- Instructions for Phase 2 cleanup work
- References to DBAL shared documentation
- Phase status clearly marked (current vs future)
- Warnings about C++ code organization
Architecture Clarifications:
- Explained Phase 2 vs Phase 3 differences
- WebSocket RPC protocol planned for Phase 3
- Credential isolation and security hardening goals
- Multiple database adapters planned for C++
- Current in-memory store in C++ vs production goals
This prevents bot errors like:
- Modifying Phase 3 C++ code without understanding phases
- Ignoring YAML schemas in /dbal/shared/
- Missing documentation about project structure
- Not understanding hybrid Phase 2 + future Phase 3 design
Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
Add DBAL_REFACTOR_PLAN.md:
- Analysis of current architecture issues (duplicate adapters, Prisma in frontend, scattered seeding)
- Three-phase refactoring plan with concrete code examples
- Phase 1: DBAL improvements (schema ownership, factory patterns, seeding)
- Phase 2: Next.js cleanup (remove workarounds, use DBAL directly)
- Phase 3: Build system updates (workspace configuration)
- Verification checklist and benefits after refactoring
Update CLAUDE.md:
- Add prominent refactoring notice at top
- Update DO NOTs for Bots to reference refactoring plan
- Clarify which code paths are being removed
- Emphasize DBAL as single source of truth for database
This establishes the proper architectural direction and provides clear guidance for future implementation. No code has been moved yet - this is the planning phase.
Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
- Add CLAUDE.md: AI assistant instructions for MetaBuilder project architecture
- Add TESTING.md: Comprehensive E2E testing guide and troubleshooting
Core changes:
- Create Playwright global.setup.ts to seed database before E2E tests
- Add /api/setup endpoint to trigger database seeding via HTTP
- Implement seed-home-page.ts module loaded from ui_home package metadata
- Create ui_home/seed/metadata.json defining home page PageConfig seed data
Architecture established:
- Packages define seed data in seed/metadata.json
- Seed functions are idempotent (check before creating)
- Global setup calls /api/setup before running tests
- Database schema must be created via 'npm run db:push' before seeding
Test flow:
1. Playwright starts webServer (generates Prisma client, starts Next.js)
2. Global setup waits for server, calls POST /api/setup
3. Seeding creates default data from packages
4. E2E tests run against seeded database
This establishes proper separation of concerns:
- DBAL adapter for database access (not raw Prisma)
- Package-driven seed data (not hardcoded in code)
- HTTP endpoint for explicit database initialization
- Idempotent seeds (safe to rerun)
Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
