# Content-as-Code Metadata System: Architecture Diagrams --- ## 1. Metadata Resolution Cascade ``` ┌──────────────────────────────────────────────────────────────┐ │ File: /context/specs/authentication-spec.md │ │ Frontmatter: { title, author, status } │ └──────────────────────────────────────────────────────────────┘ ↓ ┌──────────────────────────────────────────────────────────────┐ │ LAYER 1: Global Defaults │ │ /context/data/_defaults.yml │ │ { copyright, license, audience, internal_only, ... } │ └──────────────────────────────────────────────────────────────┘ ↓ [MERGE: defaults] ↓ ┌──────────────────────────────────────────────────────────────┐ │ LAYER 2: Scope Defaults │ │ /context/specs/data/_defaults.yml │ │ { roadcrew_type: "spec", test_coverage_target: 80 } │ └──────────────────────────────────────────────────────────────┘ ↓ [MERGE: override] ↓ ┌──────────────────────────────────────────────────────────────┐ │ LAYER 3: File Frontmatter │ │ { title, author, status } # Only differences │ └──────────────────────────────────────────────────────────────┘ ↓ [MERGE: override] ↓ ┌──────────────────────────────────────────────────────────────┐ │ Merged Metadata (before reference resolution) │ │ { title, author: "sam.henry", license: "MIT", ... } │ └──────────────────────────────────────────────────────────────┘ ↓ ┌──────────────────────────────────────────────────────────────┐ │ LAYER 4: Reference Resolution │ │ Fetch full objects from data files │ │ author: "sam.henry" → { name, email, role, ... } │ │ license: "MIT" → { name, url, spdx_id, ... } │ └──────────────────────────────────────────────────────────────┘ ↓ ┌──────────────────────────────────────────────────────────────┐ │ LAYER 5: Validation │ │ Check required fields, references, bidirectional links │ └──────────────────────────────────────────────────────────────┘ ↓ ✅ FINAL METADATA { title, author: {...}, license: {...}, copyright, ... } ``` --- ## 2. Directory Structure Hierarchy ``` /roadcrew-internal ├── /context # Primary content storage │ ├── /data # Global data files (inherited by all) │ │ ├── _defaults.yml # Global default metadata │ │ ├── authors.yml # Author registry │ │ ├── licenses.yml # License definitions │ │ ├── roadcrew-config.yml # Roadcrew version config │ │ └── tags.yml # Standard tags │ │ │ ├── /specs # Technical specifications │ │ ├── /data # Specs-specific overrides │ │ │ └── _defaults.yml # Specs inherit: roadcrew_type, test_coverage_target │ │ ├── auth-spec.md # Content + minimal frontmatter │ │ ├── payment-spec.md │ │ └── ... │ │ │ ├── /epics # Epic documents │ │ ├── /data │ │ │ └── _defaults.yml │ │ ├── epic-1171.md │ │ └── ... │ │ │ ├── /brds # Business requirements │ │ ├── /data │ │ │ └── _defaults.yml │ │ └── ... │ │ │ ├── /prds # Product requirements │ │ ├── /data │ │ │ └── _defaults.yml │ │ └── ... │ │ │ └── /releases # Release documents │ ├── /data │ │ └── _defaults.yml │ └── ... │ ├── /memory-bank # Living documentation │ ├── /data │ │ ├── _defaults.yml │ │ └── contributors.yml │ ├── activeContext.md │ ├── systemPatterns.md │ └── ... │ ├── /templates/roadcrew # Template files │ ├── /data │ │ ├── _defaults.yml │ │ └── template-types.yml │ ├── spec.template.md │ └── ... │ └── /commands # CLI commands ├── /data │ ├── _defaults.yml │ └── command-stages.yml ├── 01-analysis/ │ └── analyze-repo.md └── ... ``` --- ## 3. Data File Dependencies ``` ┌─────────────────────────┐ │ authors.yml │ │ ──────────────── │ │ sam.henry: │ │ name, email, role... │ └────────────┬────────────┘ │ Referenced by: ↓ ┌─────────────────────────────────────┐ │ File Frontmatter (any markdown) │ │ ───────────────────────── │ │ author: "sam.henry" ← resolves │ └─────────────────────────────────────┘ ┌─────────────────────────┐ │ licenses.yml │ │ ────────────── │ │ MIT: │ │ name, url, spdx... │ └────────────┬────────────┘ │ Referenced by: ↓ ┌─────────────────────────────────────┐ │ File Frontmatter (any markdown) │ │ ───────────────────────── │ │ license: "MIT" ← resolves │ └─────────────────────────────────────┘ ┌─────────────────────────┐ │ tags.yml │ │ ────────────── │ │ categories: │ │ feature, bug, ... │ │ domains: │ │ auth, payment, ... │ └────────────┬────────────┘ │ Referenced by: ↓ ┌─────────────────────────────────────┐ │ File Frontmatter (any markdown) │ │ ───────────────────────── │ │ tags: ["auth", "security"] │ │ ↑ resolve to full objects │ └─────────────────────────────────────┘ ``` --- ## 4. Publishing Pipeline ``` Internal Development (roadcrew-internal) │ ├─ Specs, Epics, Docs ├─ Internal-only files ├─ Full metadata └─ Private information │ ↓ [Pre-Publish Audit] │ - Validate frontmatter │ - Check internal_only flags │ - Verify references ↓ [PUBLISH DECISION] │ ├─── [File 1: public] ────→ [SANITIZE] ────→ [STRIP INTERNAL] │ ↓ │ { title, content, │ status, tags, ... } │ ↓ │ [Remove: author_email, │ internal_notes, │ budget_code, ...] │ ├─── [File 2: internal_only=true] ────→ [SKIP] (Don't publish) │ └─── [File 3: public] ────→ [SANITIZE] ────→ [Output] ↓ Customer-Facing Repo (.roadcrew/ in customer projects) ``` --- ## 5. Rendering Format Decision Tree ``` Source File │ ├─ Parse frontmatter ├─ Resolve metadata ├─ Validate │ └─ Render as? │ ├──→ [Markdown] │ ├─ Add title header │ ├─ Add breadcrumb navigation │ ├─ Include content │ └─ Add metadata footer │ Output: README.md │ ├──→ [HTML] │ ├─ Generate with meta tags │ ├─ Include navigation sidebar │ ├─ Render content body │ ├─ Add footer with copyright/license │ └─ Apply CSS styling │ Output: index.html │ ├──→ [JSON] │ ├─ Serialize metadata │ ├─ Include content (raw + html) │ ├─ Add navigation links │ └─ Format for API │ Output: content.json │ └──→ [GitHub Issue] ├─ Extract title from frontmatter ├─ Format body as GitHub issue ├─ Extract labels from tags ├─ Assign to author └─ Create issue Output: GitHub issue #123 ``` --- ## 6. Metadata Inheritance Example (Specs) ``` ┌──────────────────────────────────┐ │ GLOBAL (_defaults.yml) │ ├──────────────────────────────────┤ │ copyright: "© 2025 NSH" │ │ license: "LicenseRef-..." │ │ audience: "all" │ │ status: "draft" │ │ internal_only: false │ │ version: "1.0.0" │ └──────────────────────────────────┘ ↑ inherited by │ ┌──────────────────────────────────┐ │ SPECS SCOPE (_defaults.yml) │ ├──────────────────────────────────┤ │ roadcrew_type: "spec" │ │ test_coverage_target: 80 │ │ acceptance_criteria: required │ │ │ │ [Inherits from global] │ │ copyright, license, audience, .. │ └──────────────────────────────────┘ ↑ inherited/overridden by │ ┌──────────────────────────────────┐ │ FILE (auth-spec.md frontmatter) │ ├──────────────────────────────────┤ │ title: "Authentication Spec" │ │ author: "sam.henry" │ │ status: "active" ← overrides │ │ │ │ [Inherits from scope + global] │ │ roadcrew_type, test_coverage... │ │ copyright, license, audience.. │ └──────────────────────────────────┘ ↓ FINAL METADATA (merged) ┌──────────────────────────────────┐ │ Complete Resolved Metadata │ ├──────────────────────────────────┤ │ title: "Authentication Spec" │ │ author: "sam.henry" → {...} │ │ status: "active" ← from file │ │ copyright: "© 2025..." ← global │ │ license: "LicenseRef..." ← global │ roadcrew_type: "spec" ← scope │ │ test_coverage_target: 80 ← scope│ │ audience: "all" ← global │ │ internal_only: false ← global │ │ version: "1.0.0" ← global │ └──────────────────────────────────┘ ``` --- ## 7. Reference Resolution Flow ``` File Frontmatter │ ├─ author: "sam.henry" │ │ │ └─→ [Load authors.yml] │ └─→ sam.henry: │ name: "Sam Henry" │ email: "sam@..." │ role: "Technical PM" │ github: "samhenry" │ ... │ │ Result: author = { ...full object... } │ ├─ license: "MIT" │ │ │ └─→ [Load licenses.yml] │ └─→ MIT: │ name: "MIT License" │ spdx_id: "MIT" │ url: "https://..." │ ... │ │ Result: license = { ...full object... } │ ├─ tags: ["auth", "api"] │ │ │ └─→ [Load tags.yml + validate] │ └─→ Resolve each tag to full metadata │ │ Result: tags = [ {...}, {...} ] │ └─ parent: "EPIC-1171" │ └─→ [Find file by ID] └─→ Extract title and path └─→ Validate bidirectional link Result: parent = { id, title, path } ``` --- ## 8. Validation & Quality Checks ``` Input: Resolved Metadata │ ├─→ [Syntax Check] │ ✓ Valid YAML structure │ ✓ UTF-8 encoding │ ├─→ [Required Fields] │ ✓ title present │ ✓ author present │ ├─→ [Reference Validation] │ ✓ author exists in authors.yml │ ✓ license exists in licenses.yml │ ✓ parent file exists │ ✓ tags are valid │ ├─→ [Relationship Integrity] │ ✓ If A.parent = B, then B.children ⊇ A │ ✓ No circular references │ ✓ No orphaned specs │ ├─→ [Publishing Safety] │ ✓ No internal_only=true in dist/ │ ✓ No sensitive email addresses published │ ✓ All template {{}} replaced │ └─→ [Performance] ✓ Checksum matches (no manual changes) ✓ File encoding valid ✓ No suspicious metadata patterns ↓ ✅ PASS: All checks successful ❌ FAIL: Display errors with remediation hints ``` --- ## 9. Content Pipeline: Spec Lifecycle ``` DRAFT │ ├─ Created: /context/specs/feature-x-spec.md ├─ Frontmatter: { title, author, status: "draft" } ├─ Metadata: Resolved but not validated for publishing └─ Internal: [shared with team only] ↓ [Team Review] ACTIVE ├─ Updated: status: "active" ├─ Metadata: Full validation passes ├─ Ready: Can publish to customers └─ Published: Appears in dist/ ↓ [Feature Implementation Complete] DEPRECATED ├─ Updated: status: "deprecated" ├─ Replaced by: [link to newer spec] ├─ Metadata: Marked for removal └─ Publishing: Still in dist/ but marked as old ↓ [Next Major Release] ARCHIVED ├─ Moved: /context/specs/archived/ ├─ Metadata: Not in active queries ├─ Git: Still in history (version control) └─ Publishing: Never published again ``` --- ## 10. Build Time vs Runtime ``` BUILD TIME (When spec is created/published) │ ├─→ Parse frontmatter + load data files ├─→ Resolve all references ├─→ Validate relationships ├─→ Run quality checks ├─→ Decide if publishable ├─→ Render to target formats └─→ Generate navigation/meta tags ↓ Output: Static rendered files (no runtime processing needed) RUNTIME (When customer uses template) │ ├─ Customer runs: `/create-spec` ├─ Command: Reads pre-validated spec template ├─ No metadata parsing needed (already resolved) ├─ Just substitute {{VARIABLES}} └─ Output: Complete spec with correct metadata ✅ Fast (no cascading/validation at runtime) ``` --- ## 11. Publishing Safety: Internal vs Public ``` Source File │ ├─ Frontmatter: { title, author, internal_only: false } │ └─→ [Check: internal_only?] │ ├─ YES → [SKIP] │ └─ Do not publish to dist/ or .roadcrew/ │ └─ Keep in roadcrew-internal only │ └─ Customers never see this │ └─ NO → [PUBLISH] │ └─→ [Sanitize Metadata] │ ├─ KEEP: title, status, tags, category, test_plan │ └─ REMOVE: author_email, internal_notes, budget_code, cost_estimate, etc. ↓ [Output to dist/ and .roadcrew/] │ └─ Customer gets clean, safe spec └─ No internal metadata leaked └─ Can see overview but not author email ``` --- ## 12. System Interaction Map ``` ┌─────────────────┐ │ Git Submodule │ │ (.roadcrew/) │ └────────┬────────┘ │ Customers clone ↓ ┌─────────────────────────┐ │ Customer Project │ │ .roadcrew/commands/ │ │ .roadcrew/templates/ │ │ .roadcrew/rules/ │ └────────┬────────────────┘ │ Uses ↓ ┌─────────────────────────┐ │ Template Substitution │ │ {{PROJECT_NAME}} │ │ {{GITHUB_REPO}} │ │ (Metadata pre-filled) │ └────────┬────────────────┘ │ Generates ↓ ┌─────────────────────────┐ │ Customer Specs │ │ /context/specs/ │ │ (Metadata inherited) │ └─────────────────────────┘ ↑ --- Meanwhile, in Internal --- ┌─────────────────────────┐ │ roadcrew-internal │ │ /context/data/ │ │ Metadata definitions │ └────────┬────────────────┘ │ Feeds into ↓ ┌─────────────────────────┐ │ Metadata Resolver │ │ (cascade + validate) │ └────────┬────────────────┘ │ Outputs ↓ ┌─────────────────────────┐ │ dist/ (public files) │ │ Published to roadcrew │ │ repo for customers │ └─────────────────────────┘ ```