Artifact Registry¶

This page documents every artifact in the NovaTrek Architecture Platform -- what is hand-authored (source of truth), what is generated, and how each actor changes and publishes them.

Actors¶

Defined Artifacts (Source of Truth)¶

These files are hand-authored. All generated pages, diagrams, and portal content derive from them.

Architecture Metadata¶

API Contracts¶

Solution Designs¶

Architecture Decisions¶

Hand-Authored Diagrams¶

Wireframes¶

Configuration¶

Service Source Code¶

Portal Configuration¶

Infrastructure¶

Hand-Authored Documentation¶

CI/CD Workflows¶

Generated Artifacts¶

These are produced by scripts from the defined artifacts above. Never edit generated files directly -- they will be overwritten on the next build.

Portal Pages (Markdown)¶

CALM Topology¶

Metadata Loader¶

Confluence Mirror¶

Multi-Site Sync¶

MkDocs HTML Site¶

Build Pipeline¶

All generation runs through a single entry point:

bash portal/scripts/generate-all.sh

This executes 11 stages in order:

1. Swagger UI pages
2. Microservice pages (Markdown + PlantUML + SVG)
3. Application pages (Markdown + PlantUML + SVG)
4. Wireframe pages (Excalidraw to SVG + HTML + Markdown)
5. AsyncAPI event pages
6. Solution design pages
7. Business capability pages
8. Ticket pages
9. CALM topology generation + validation + domain subsets
10. Standalone PlantUML diagram SVGs
11. MkDocs build + asset copy to site/

After building, deployment uses:

swa deploy site --deployment-token "<token>" --env production

Or via CI: the docs-deploy.yml GitHub Action handles build + deployment automatically on push to main.

How to Change and Publish: Solution Architect¶

Change architecture metadata¶

1. Edit the relevant YAML file in architecture/metadata/
2. Commit and push to main
3. CI runs generate-all.sh automatically, regenerates all affected portal pages, and deploys

Local preview (optional):

bash portal/scripts/generate-all.sh
cd portal && python3 -m mkdocs serve

Change an API contract¶

1. Edit the OpenAPI spec in architecture/specs/{svc-name}.yaml
2. Verify backward compatibility (new required fields break consumers)
3. Commit and push to main
4. CI regenerates Swagger UI pages, microservice deep-dive pages, and sequence diagrams

Add a new service¶

1. Add the service to architecture/metadata/domains.yaml (assign to a domain)
2. Create architecture/specs/{svc-name}.yaml (OpenAPI spec)
3. Add entries to data-stores.yaml, cross-service-calls.yaml, and label-to-svc.yaml
4. Add entries to events.yaml if the service produces or consumes events
5. Add nav entry to portal/mkdocs.yml under Services > Microservices
6. Commit and push -- CI generates the new microservice page, diagrams, and Swagger UI

Create a solution design¶

1. Create branch: git checkout -b solution/NTK-XXXXX-slug
2. Create folder: architecture/solutions/_NTK-XXXXX-slug/
3. Populate the standard folder structure (see Solution Designs table above)
4. Add entry to architecture/metadata/capability-changelog.yaml
5. Update architecture/metadata/tickets.yaml if needed
6. Push branch, open PR, merge to main
7. CI generates the solution page and updates capability/ticket pages

Add or update a diagram¶

Hand-crafted diagram:

1. Edit or create .puml file in architecture/diagrams/{System,Components,Sequence,Tickets}/
2. Follow C4 notation (use !include <c4/C4_Container> or !include ../theme.puml)
3. Commit and push -- CI renders to SVG via generate-svgs.sh

Endpoint diagram override:

1. Create .puml file in architecture/diagrams/endpoints/ matching the generated filename
2. The generator checks this directory first and uses the override instead of auto-generating
3. Commit and push -- CI uses the override

Add an architecture decision¶

1. Determine the next ADR number from decisions/
2. Create decisions/ADR-{NNN}-{slug}.md using MADR format from standards/madr/adr-template.md
3. If the decision belongs to a solution, also add it to 3.solution/d.decisions/decisions.md
4. Commit and push

Update a wireframe¶

1. Edit the .excalidraw file in architecture/wireframes/{app}/ using the VS Code Excalidraw extension or excalidraw.com
2. Commit only the .excalidraw source file
3. Push -- CI generates SVG + HTML + Markdown wrapper automatically

Add an event¶

1. Add the event to the producer's AsyncAPI spec in architecture/events/{svc-name}.events.yaml
2. Add the event to architecture/metadata/events.yaml (producer, consumers, topic)
3. Commit and push -- CI regenerates event catalog pages and updates microservice pages

Update portal navigation¶

1. Edit portal/mkdocs.yml under the nav: section
2. Commit and push

How to Change and Publish: Software Developer¶

Change service source code¶

1. Edit files in services/{svc-name}/
2. Run tests locally: cd services/{svc-name} && ./mvnw test
3. Commit and push -- CI runs service-ci.yml (build + test)

NOTE: Source code changes do not affect the architecture portal. If the implementation reveals an API contract gap (missing field, new endpoint, changed behavior), propose the contract change separately.

Propose an API contract change¶

1. Create a branch
2. Edit the OpenAPI spec in architecture/specs/{svc-name}.yaml
3. If the change affects cross-service calls, update architecture/metadata/cross-service-calls.yaml
4. Push the branch and open a pull request
5. The Solution Architect reviews and approves the contract change
6. On merge, CI regenerates all affected portal pages

Propose a metadata change¶

1. Create a branch
2. Edit the relevant file in architecture/metadata/
3. Push and open a pull request for Solution Architect review
4. On merge, CI regenerates affected portal pages

Add a new service implementation¶

1. Copy services/template/ to services/{svc-name}/
2. Implement the API contract defined in architecture/specs/{svc-name}.yaml
3. Write contract tests against the OpenAPI spec (ADR-013)
4. Add database migrations to infra/db/ if needed
5. Push and open a pull request

Update infrastructure¶

1. Edit Bicep files in infra/
2. Test locally: az deployment group what-if
3. Push -- CI runs infra-deploy.yml

Update CI/CD workflows¶

1. Edit .github/workflows/*.yml
2. Push to a branch and verify via GitHub Actions "dry run" or test workflow

Run the portal build locally¶

# Activate virtual environment
source .venv/bin/activate

# Install dependencies (first time only)
pip install -r requirements-docs.txt

# Generate all artifacts and build
bash portal/scripts/generate-all.sh

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

Regenerate a single artifact type¶

# Only microservice pages
python3 portal/scripts/generate-microservice-pages.py

# Only capability pages
python3 portal/scripts/generate-capability-pages.py

# Only CALM topology
python3 scripts/generate-calm.py

# Only hand-crafted diagram SVGs
bash portal/scripts/generate-svgs.sh

Key Rules¶

1. Never edit generated files. They live in portal/docs/microservices/, portal/docs/applications/, portal/docs/solutions/, portal/docs/capabilities/, portal/docs/tickets/, portal/docs/topology/, portal/docs/services/api/, portal/docs/events/, portal/docs/actors/, and portal/docs/diagrams/svg/. Edit the source files instead.

2. Solution Architects own all architecture metadata. Software Developers propose changes via pull request.

3. One push rebuilds everything. The CI pipeline runs the full generate-all.sh on every push to main that touches architecture or documentation files.

4. Capability changes go in the changelog. Every solution that affects capabilities must add an entry to architecture/metadata/capability-changelog.yaml -- this is the single source of truth for L3 capability emergence.

5. API contracts are the shared boundary. Solution Architects define the contract (OpenAPI spec). Software Developers implement it. Contract tests (ADR-013) verify alignment.