Architecture Metadata Registry¶

What Is the Metadata Registry?¶

The architecture/metadata/ directory contains 15 YAML files that together form a complete, machine-readable model of the NovaTrek platform. Every service, domain, capability, integration, data store, actor, event, application, ticket, and deployment status is captured as structured data.

This is not documentation in the traditional sense. These files are the single source of truth that portal pages, CALM topology, sequence diagrams, and capability maps are all generated from. Editing a YAML file and pushing to main triggers CI to regenerate the entire architecture portal automatically.

Why YAML Instead of Documentation?¶

The problem with prose¶

Traditional architecture documentation is a collection of wiki pages, Word documents, and diagrams maintained by hand. This approach has well-known failure modes:

• Drift — documentation falls behind reality within weeks of being written
• Duplication — the same fact (e.g., "svc-payments is in the Support domain") appears in 12 places and is updated in 3 of them
• No validation — a wiki page can claim anything; there is no way to lint or test it
• No generation — every downstream artifact (diagrams, capability maps, service catalogs) must be manually maintained in parallel

The metadata-driven alternative¶

By encoding architecture facts as structured YAML, NovaTrek gains:

The core principle: edit the data, not the documents. Documents are generated outputs.

File Reference¶

Domain and Service Model¶

Business Capabilities¶

Actors and Applications¶

Events¶

Tickets and Delivery¶

How These Files Power the Portal¶

Every portal page is a generated output of these metadata files. Nothing is maintained by hand in the portal.

architecture/metadata/*.yaml
        │
        ▼
  Generator Scripts
  (portal/scripts/)
        │
        ├──► Microservice deep-dive pages (22 pages, 139 sequence diagrams)
        ├──► Application pages with screen flows
        ├──► Service Catalog with Swagger UI links
        ├──► Business Capability map
        ├──► Solution design pages
        ├──► Ticket pages
        ├──► CALM topology JSON (74 nodes, 146 relationships)
        └──► Event Catalog

Which scripts consume which files¶

All generators use the shared load_metadata.py module which validates and caches metadata on load.

Who Edits These Files — and How?¶

The architect workflow¶

Architects do not typically edit YAML metadata by hand. Instead, the AI agent (GitHub Copilot or Roo Code) modifies these files as part of executing the solution design workflow. Here is the typical flow:

Architect receives ticket (e.g., NTK-10005)
        │
        ▼
Architect prompts AI agent to design a solution
        │
        ▼
AI agent reads ticket, specs, and metadata
        │
        ▼
AI agent produces solution design documents AND
updates YAML files as a side effect:
  • capability-changelog.yaml  (new capability entries)
  • tickets.yaml               (status → Solved, solution link)
  • cross-service-calls.yaml   (new integration points)
  • OpenAPI specs              (new/modified endpoints)
  • data-stores.yaml           (new tables or columns)
        │
        ▼
Architect reviews YAML changes in PR diff
        │
        ▼
Merge to main → CI regenerates portal

The architect's role is to prompt, review, and approve — not to author YAML by hand. The AI agent understands the file formats, referential integrity rules, and naming conventions, so it produces structurally correct updates that the architect validates in a pull request diff.

When would an architect edit YAML manually?¶

Rarely, but it happens for structural or bootstrapping changes:

For anything involving analysis, cross-referencing, or producing multiple coordinated changes (the common case during solution design), the AI agent handles the updates.

Are these files generated from code?¶

No. These metadata files are authored data, not generated outputs. They are not extracted from running services, source code, or infrastructure. The flow is:

Authored inputs:                    Generated outputs:
─────────────────                   ───────────────────
architecture/metadata/*.yaml   ──►  portal/docs/ (Markdown pages)
architecture/specs/*.yaml      ──►  portal/docs/microservices/ (deep-dive pages)
                               ──►  portal/docs/microservices/svg/ (sequence diagrams)
                               ──►  architecture/calm/ (CALM topology JSON)
                               ──►  portal/docs/services/api/ (Swagger UI)

The YAML files are inputs. The portal pages, diagrams, and CALM topology are outputs. This is the opposite of many "docs-as-code" approaches that extract documentation from source code — here, the architecture model is the primary artifact, and everything else is derived from it.

CI/CD integration¶

1. Edit YAML files (typically via AI agent during solution design, occasionally by hand)
2. Commit and push to main
3. CI regenerates all portal pages automatically via generate-all.sh

For local preview before pushing:

# Regenerate all portal pages from metadata
bash portal/scripts/generate-all.sh

# Build the portal locally
cd portal && python3 -m mkdocs build

# Or serve locally for preview
cd portal && python3 -m mkdocs serve

Validation rules¶

• Referential integrity: Service names in cross-service-calls.yaml must exist in domains.yaml
• No duplication: Solved ticket capabilities go in capability-changelog.yaml only, never duplicated in tickets.yaml
• Consistent identifiers: Service names use svc- prefix everywhere (e.g., svc-check-in, never check-in)
• ISO 8601 dates: All date fields use YYYY-MM-DD format

Relationship Between Metadata and OpenAPI Specs¶

The metadata registry and the OpenAPI specs are complementary:

OpenAPI specs define the contract surface (endpoints, schemas, parameters). Metadata files define the architecture topology (how services relate to each other, to domains, to capabilities, and to actors). Together they form the complete architecture model.