Metadata and Artifacts¶

Architecture at NovaTrek is modeled as structured data, not prose. This page explains the metadata-driven approach, what files you edit, and how those edits flow through to the portal.

The Metadata-Driven Approach¶

Instead of writing free-form documentation, architects maintain 15 YAML metadata files that describe the architecture. Generator scripts read these files and produce portal pages, diagrams, topology views, and capability maps.

This approach provides:

• Consistency — every service page follows the same structure because a script generates them all
• Cross-linking — generators create links between services, events, actors, and capabilities automatically
• Validation — YAML schema can be validated; prose cannot
• Drift prevention — the portal always reflects what's in the YAML; there's no way for documentation to silently diverge from the architecture
• Automation — CI/CD regenerates everything on every push to main

Metadata Files Reference¶

All files live in architecture/metadata/.

Domain and Service Structure¶

People and Systems¶

Events and Integration¶

Capabilities and Tickets¶

Operations and Compliance¶

Hand-Authored vs. Generated Artifacts¶

Understanding this distinction is critical. Never edit generated files — they will be overwritten on the next build.

You Edit (Source of Truth)¶

Scripts Generate (Do Not Edit)¶

The Central Loader¶

All generators import from portal/scripts/load_metadata.py, which loads all 15 metadata YAML files into Python data structures. If you add a new metadata file, it needs a loader function here.

How to Add a New Service¶

This is the most common metadata operation. Follow these steps in order:

1. Add to domains.yaml — assign the service to a domain and team
2. Create the OpenAPI spec — architecture/specs/svc-new-service.yaml
3. Add to data-stores.yaml — define the database, schema, and tables
4. Add to cross-service-calls.yaml — document all API calls to/from other services
5. Add to label-to-svc.yaml — map display label to service name
6. Add to events.yaml — if the service produces or consumes events
7. Add nav entry — add the service to mkdocs.yml under Microservices
8. Regenerate — run bash portal/scripts/generate-all.sh

How to Add a New Event¶

1. Create or update the AsyncAPI spec — architecture/events/svc-producer.events.yaml
2. Add to events.yaml — declare the producer, consumers, topic, and event name
3. Regenerate — run bash portal/scripts/generate-all.sh

How Schema Changes Flow to Production¶

Database index and schema changes follow a specific workflow from architecture metadata to production deployment. See the Database Index Change Workflow for the complete 5-step process.

Validation¶

CALM topology validation¶

After changing metadata, validate the generated CALM topology:

python3 scripts/validate-calm.py

This checks referential integrity — every service referenced in cross-service calls exists in domains, every event producer exists, etc.

Portal build validation¶

cd portal && python3 -m mkdocs build --strict

The --strict flag treats warnings as errors, catching broken links and missing references.

For More Detail¶

• Artifact Registry — complete inventory with actor ownership
• Metadata Registry Standard — why YAML, not prose
• Portal Publishing — build and deploy workflow