From fc76d15de0045f994fcf5737bc8abdeb1b0f234f Mon Sep 17 00:00:00 2001 From: johndoe6345789 Date: Fri, 16 Jan 2026 15:01:31 +0000 Subject: [PATCH] Update CLAUDE.md with complete seed & package architecture MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Key updates to Proper Data Flow: - Clarify Root DBAL Seed as MINIMAL (package list + permissions only) - Clarify Package Entity Seed as EVERYTHING (all entity data lives here) - Document DBAL ownership (owns schema + orchestration, NOT entity data) - Mention JSON schema validation at package level Update Project Structure Overview: - Show /schemas/seed-data/ with all JSON validation schemas - Show /packages/[packageId]/ with entity-type folders (page-config, workflow, etc.) - Show /dbal/shared/seeds/ as root DBAL seed (minimal) - Add PACKAGE_STRUCTURE.md and SEED_FORMAT.md documentation Update Further Reading section: - Add "Seed System Architecture" section with 8 key documents - Add "Core Entity Definitions" section - Reorganize with proper hierarchy and descriptions - Highlight ⭐ key documents (SEED_SCHEMAS.md, PACKAGE_STRUCTURE.md) This establishes the complete architecture: 1. Root DBAL = package list + system permissions (minimal) 2. Packages = all entity data organized by type (page-config, workflow, etc.) 3. Schemas = YAML for entities, JSON for seed validation 4. Orchestration = DBAL reads package list, loads entity folders Co-Authored-By: Claude Haiku 4.5 --- CLAUDE.md | 114 ++++++++++++++++++++++++++++++++++++------------------ 1 file changed, 76 insertions(+), 38 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index b439446ec..c79f1d27a 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -280,27 +280,30 @@ See `seed/packages/core-packages.yaml` for full order. ### Proper Data Flow (Detailed) -1. **Base Seed Data** (`/dbal/shared/seeds/database/`) - - YAML files for system bootstrap (not package-specific) - - `installed_packages.yaml` - List of 12 packages to install at bootstrap - - `package_permissions.yaml` - Permission/access control seed data +1. **Root DBAL Seed Data** (`/dbal/shared/seeds/database/` - MINIMAL) + - `installed_packages.yaml` - List of 12 core packages to install at bootstrap + - `package_permissions.yaml` - System-wide permissions and roles + - That's it. Nothing else belongs here. - Loaded during `POST /api/bootstrap` via `seedDatabase()` -2. **Package Entity Seed Data** (`/packages/[packageId]/[entity-type]/`) - - One folder per entity type: `page-config/`, `workflow/`, `credential/`, etc. - - `metadata.json` - Describes the entity folder (entity type, packageId, description) - - `*.json` - Data files (e.g., `home.json`, `dashboard.json` in page-config folder) - - Simple JSON arrays, not code or schemas +2. **Package Entity Seed Data** (`/packages/[packageId]/[entity-type]/` - EVERYTHING) + - One folder per entity type: `page-config/`, `workflow/`, `credential/`, `notification/`, `component/` + - `metadata.json` - Describes entity folder (entity type, packageId, description) + - `*.json` - Actual seed data (e.g., `home.json`, `dashboard.json` in page-config/) + - Simple JSON arrays, validated by `/schemas/seed-data/` JSON schemas - Loaded automatically for packages listed in `installed_packages.yaml` - - Examples: ui_home/page-config/, dashboard/page-config/, etc. + - Each package self-contained with all its seed data + - Examples: ui_home/page-config/, dashboard/page-config/, user_manager/workflow/ 3. **DBAL** (Phase 2: TypeScript, Phase 3: C++) - - **OWNS:** Database schema (YAML source of truth) + - **OWNS:** Database schema definitions (YAML source of truth in `/dbal/shared/api/schema/entities/`) - **OWNS:** Prisma schema (auto-generated from YAML) - - **OWNS:** Seed orchestration (loading from /seed/) + - **OWNS:** Seed orchestration (reads `installed_packages.yaml`, loads package entity folders) - **OWNS:** Client factories, adapters, entity operations + - **OWNS:** Root seed data only (`/dbal/shared/seeds/database/` - package list + permissions) - **EXPORTS:** `getDBALClient()`, `seedDatabase()`, etc. - **PROVIDES:** Type-safe entity operations + - **DOES NOT DEFINE:** Entity seed data (belongs in packages) 4. **Frontend** (`/frontends/nextjs/`) - Uses DBALClient from DBAL @@ -340,23 +343,46 @@ See `seed/packages/core-packages.yaml` for full order. │ ├── tools/ [Schema generation tools] │ └── backends/ [Database connection utilities] │ -├── schemas/ [Package system schemas] -│ └── package-schemas/ [JSON schema definitions] -│ ├── metadata_schema.json -│ ├── entities_schema.json -│ ├── components_schema.json -│ └── ... (14+ more schemas) +├── schemas/ [All schemas - validation + definitions] +│ ├── seed-data/ [JSON seed validation schemas] +│ │ ├── page-config.schema.json +│ │ ├── workflow.schema.json +│ │ ├── credential.schema.json +│ │ ├── notification.schema.json +│ │ ├── component.schema.json +│ │ └── README.md +│ ├── package-schemas/ [Package system definitions] +│ │ ├── metadata_schema.json +│ │ ├── entities_schema.json +│ │ ├── components_schema.json +│ │ └── ... (14+ more schemas) +│ └── SEED_SCHEMAS.md [Two-layer schema explanation] │ -├── seed/ [Base bootstrap data] -│ ├── database/ -│ │ ├── installed_packages.yaml -│ │ └── package_permissions.yaml -│ └── config/ +├── packages/ [Modular packages - ALL ENTITY DATA] +│ ├── [packageId]/ +│ │ ├── page-config/ [Routes/pages] +│ │ │ ├── metadata.json +│ │ │ └── *.json +│ │ ├── workflow/ [Workflows] +│ │ │ ├── metadata.json +│ │ │ └── *.json +│ │ ├── credential/ [API credentials] +│ │ │ ├── metadata.json +│ │ │ └── *.json +│ │ ├── notification/ [Notifications] +│ │ │ ├── metadata.json +│ │ │ └── *.json +│ │ ├── component/ [Components] +│ │ │ ├── metadata.json +│ │ │ └── *.json +│ │ └── package.json +│ ├── PACKAGE_STRUCTURE.md [Package organization guide] +│ └── SEED_FORMAT.md [Seed format specification] │ -├── packages/ [Modular packages] -│ └── */ -│ ├── seed/metadata.json [Package-specific seed data] -│ └── ... +├── dbal/shared/seeds/ [Root DBAL seed - MINIMAL] +│ └── database/ +│ ├── installed_packages.yaml [12 core packages to install] +│ └── package_permissions.yaml [System permissions] │ └── frontends/ └── nextjs/ [Next.js frontend] @@ -1109,18 +1135,30 @@ cmake --build build 16. **dbal/shared/docs/PHASE2_IMPLEMENTATION.md** - Phase 2 detailed guide 17. **dbal/production/docs/PHASE3_DAEMON.md** - Phase 3 design (future) -### Seed System & Package Data -18. **packages/SEED_FORMAT.md** - ⭐ Seed data structure, format, and best practices -19. **packages/PACKAGE_AUDIT.md** - Audit of all 51 packages (12 with seed, 39 optional) -20. **dbal/shared/seeds/database/** - Base bootstrap data (installed_packages.yaml, etc.) +### Seed System Architecture (Complete & Production-Ready) +18. **schemas/SEED_SCHEMAS.md** - ⭐ Two-layer schema system (YAML + JSON validation) +19. **dbal/shared/seeds/README.md** - Root DBAL seed architecture (minimal bootstrap only) +20. **packages/PACKAGE_STRUCTURE.md** - ⭐ Package organization (entity-type folders) +21. **packages/SEED_FORMAT.md** - Seed data file format and best practices +22. **packages/PACKAGE_AUDIT.md** - Audit of all 51 packages (12 core, 39 optional) +23. **schemas/seed-data/README.md** - JSON schema usage and integration +24. **schemas/seed-data/** - JSON validation schemas: + - `page-config.schema.json` - Route/page definitions + - `workflow.schema.json` - Automation workflows + - `credential.schema.json` - API credentials + - `notification.schema.json` - Notification templates + - `component.schema.json` - Reusable components -### Schema & Package System -21. **schemas/SCHEMAS_README.md** - Package system definitions -22. **schemas/QUICKSTART.md** - Package system quick start -23. **schemas/package-schemas/** - Complete schema definitions: - - `script_schema.json` - JSON Script language specification (v2.2.0, planned n8n migration) +### Core Entity Definitions +25. **dbal/shared/api/schema/entities/** - YAML entity schemas (source of truth for both phases) +26. **dbal/shared/seeds/database/installed_packages.yaml** - List of 12 core packages +27. **dbal/shared/seeds/database/package_permissions.yaml** - System permissions + +### Package System & Schemas +28. **schemas/SCHEMAS_README.md** - Package system overview +29. **schemas/QUICKSTART.md** - Package system quick start +30. **schemas/package-schemas/** - Package definition schemas: + - `script_schema.json` - JSON Script language (v2.2.0, planned n8n migration) - `metadata_schema.json` - Package structure - `entities_schema.json` - Database models - Plus 15 more schemas for components, APIs, validation, permissions, etc. -24. **dbal/shared/api/schema/** - YAML schema sources (both phases) -25. **dbal/shared/seeds/database/installed_packages.yaml** - List of 12 packages to install at bootstrap