NovaTrek Adventures — Continuous Architecture Platform Roadmap¶

1. Vision¶

The Continuous Architecture Platform replaces point-in-time architecture documentation with a living, interconnected architecture knowledge base that grows with every ticket. The platform ensures that:

• Every solution design is published, indexed, and cross-linked
• Business capabilities accumulate intelligence from every ticket
• Architecture decisions maintain full traceability from ticket to capability
• AI agents can discover prior art, detect conflicts, and suggest capability mappings
• The portal is the single source of truth for NovaTrek Adventures architecture

The core insight: Architecture amnesia — where valuable solution designs are produced, reviewed, approved, and then forgotten — is eliminated by making capability rollup a natural byproduct of the solution design workflow, enforced by branch protection and PR review.

2. Current State¶

What Exists¶

What Is Missing¶

3. Business Capability Map¶

NovaTrek Adventures has 7 Level 1 capability domains encompassing 34 Level 2 capabilities.

Coverage Summary¶

Level 1 Domains¶

Priority Gaps¶

4. Architecture Practice Model¶

Solution Design Lifecycle¶

Ticket Assigned
  |
  v
Create Branch: solution/NTK-XXXXX-slug
  |
  v
Create Solution in: architecture/solutions/_NTK-XXXXX-slug/
  |-- Master document (overview, component architecture)
  |-- 1.requirements/ (ticket report)
  |-- 2.analysis/ (simple explanation)
  |-- 3.solution/
  |   |-- a.assumptions/
  |   |-- c.capabilities/ (capability mapping -- REQUIRED)
  |   |-- d.decisions/ (MADR format)
  |   |-- g.guidance/ (implementation advice -- optional)
  |   |-- i.impacts/ (per-service impact assessments)
  |   |-- r.risks/
  |   |-- u.user.stories/
  |   |-- 00.component.diagram.puml
  |   |-- *.puml, *.svg (sequence diagrams)
  |
  v
Update Metadata (same branch):
  |-- architecture/metadata/capabilities.yaml (new L3 entries)
  |-- architecture/metadata/capability-changelog.yaml (append entry)
  |-- architecture/metadata/cross-service-calls.yaml (if new integrations)
  |-- decisions/ADR-NNN-*.md (promoted ADRs)
  |
  v
Open Pull Request
  |-- CI validates YAML, builds portal preview
  |-- Reviewer applies architecture checklist
  |
  v
Merge to Main --> Portal Publishes --> Architecture Grows

Branching Strategy¶

Every solution design is developed on a dedicated branch (solution/NTK-XXXXX-slug) and delivered through a pull request. This enforces:

• Review gate — PR is the architecture review
• Portal integrity — only main is published; drafts are invisible
• Concurrent work — multiple architects work without conflicts
• Atomic delivery — solution + metadata + ADRs reviewed and merged together
• CI validation — YAML syntax, portal build, cross-link validation before merge
• Rollback safety — revert merge commit cleanly removes everything

Content Separation Rules¶

Capability Rollup Model¶

Solution Design (ticket-scoped)
  --> Capability Mapping (which L1/L2 capabilities touched)
    --> L3 Capabilities (emergent features from the solution)
      --> Capability Changelog (append-only history)
        --> Capability Page in Portal (auto-generated timeline)

L1 and L2 capabilities are top-down and stable. L3 capabilities emerge bottom-up from ticket work. The changelog bridges bottom-up work into top-down visibility.

5. Ticketing Strategy¶

Recommended Tool: Vikunja¶

Starting Approach: YAML-First¶

Before deploying Vikunja, start with architecture/metadata/tickets.yaml as the source of truth. This validates the information architecture without infrastructure cost. Vikunja becomes the UI layer when broader team adoption requires it.

Ticket Structure¶

Every ticket uses structured user story format with:

• User story (As a / I want / So that)
• Use cases with preconditions, main flow, postconditions
• Acceptance criteria
• Capability mapping (CAP-X.Y with impact type)
• Affected services table

AI Access to Tickets¶

6. Portal Publishing Architecture¶

Portal Sections (Target State)¶

Confluence Mirror (Read-Only)¶

Every page published to Azure SWA is simultaneously published to Confluence Cloud as a read-only mirror. Git remains the single source of truth. The mark CLI tool (Go binary) converts portal Markdown to Confluence Storage Format and publishes via the Confluence REST API. A pre-processing script (confluence-prepare.py) injects mark metadata headers, rewrites internal links to Confluence page titles, converts MkDocs Material syntax (admonitions, content tabs, <object> SVGs) to Confluence-compatible equivalents, and adds a "do-not-edit" banner. Pages are locked after publish so only the CI service account can modify them. See CONFLUENCE-PUBLISHING-PLAN.md for the complete design.

Cross-Linking Web¶

When fully implemented, every artifact connects:

• Solution pages link to impacted services, capabilities, and decisions
• Capability pages show timeline of all solutions that shaped them
• Microservice pages list all solutions affecting them
• Decision pages trace back to originating solution
• Ticket pages link to solution, capabilities, and services

7. Phased Implementation Plan¶

Phase 0: Data Isolation Cleanup (Immediate)¶

Scrub corporate identifiers from all published content.

Phase 1: Foundation (Immediate)¶

Build the metadata backbone and establish the solution design workflow.

Outcome: Solution designs have a canonical home, the template supports capability rollup, the metadata backbone exists, and the branch-based review workflow is documented.

Phase 2: Portal Publishing (Short Term)¶

Build generators and publish solution designs, capabilities, and tickets to the portal.

Outcome: Solution designs, capability pages, and ticket pages are live on the portal with cross-links. Branch CI validates solutions before merge.

Phase 3: AI Integration (Short Term)¶

Make the AI agent fully aware of the continuous architecture workflow.

Outcome: AI agent automatically produces capability-mapped solutions on dedicated branches with the same review workflow as human architects.

Phase 4: Ticketing Infrastructure (Medium Term)¶

Deploy Vikunja as the ticketing UI.

Outcome: Vikunja provides a UI for ticket management. sync-tickets.py keeps tickets.yaml in sync. Portal pages generated from YAML as before.

Phase 5: Advanced Features (Medium Term)¶

Outcome: The portal becomes an intelligent architecture knowledge base with rich navigation, discovery, and real-time AI integration.

Phase 6: Confluence Publishing (Short Term)¶

Publish the NovaTrek Architecture Portal as a read-only mirror in Confluence Cloud. The same git push that deploys to Azure SWA also publishes to Confluence — one pipeline, two outputs, zero manual steps. See CONFLUENCE-PUBLISHING-PLAN.md for the full design, tool evaluation, and transformation pipeline.

Tool: mark by Kovetskiy (Go binary, MIT license) — purpose-built for Git Markdown to Confluence publishing.

Architecture:

Git Push to main
      │
      ▼
  GitHub Actions
      │
  ┌───┴───┐
  │       │
  ▼       ▼
Azure   mark
 SWA    publish
  │       │
  ▼       ▼
Portal  Confluence
(primary) (mirror)

Drift Prevention (4 layers):

1. Page restrictions — only CI service account can edit
2. do-not-edit label — visual signal on every page
3. Banner warning — every page starts with "auto-generated from Git" notice
4. Overwrite on deploy — mark replaces full page body on every pipeline run

What will look different in Confluence:

Cost: $0/month (Confluence Cloud free tier, 10 users, 2 GB storage)

Outcome: Enterprise stakeholders consume architecture documentation in their standard wiki. Content is always identical to the portal. Zero manual synchronization.

Future Initiatives Summary¶

All Phases 0-6 are COMPLETE. The following initiatives represent the next wave of work, consolidated from plan documents, reminders, and proposed enhancements across the repository. Each initiative has a detailed companion document linked below.

CALM — Automated Architecture Governance (Top Priority)¶

Status: Planned | Companion: docs/CALM-INTEGRATION-PLAN.md | Reminder: architecture/reminders/CALM-EVALUATION.md

CALM (Common Architecture Language Model) is the next major evolution of the platform. It adds a formal, machine-validatable topology layer on top of the existing architecture practice.

Architects do not write CALM. CALM documents are automatically generated from the artifacts architects already maintain — OpenAPI specs, AsyncAPI specs, and metadata YAML files (domains.yaml, cross-service-calls.yaml, data-stores.yaml, events.yaml, actors.yaml). Bridge scripts transform these into the CALM format, and calm validate runs in CI to enforce architecture rules automatically.

Why auto-generate instead of hand-author?

1. No new format to learn — architects stay in YAML and OpenAPI specs, which are already the source of truth
2. Validation is the value, not authoring — CALM patterns and controls catch violations (shared databases, missing team ownership, undeclared cross-service calls) regardless of whether CALM was hand-written or generated
3. No drift by construction — a single source of truth (specs + metadata YAML) feeds both the portal generators and the CALM topology; two representations cannot diverge
4. Incremental adoption — existing workflows are unchanged; CALM is a CI-layer addition, not a workflow replacement

What CALM delivers:

5-phase rollout: Pilot (1 domain) -> Full topology (all 22 services) -> Generator integration (portal consumes CALM) -> Governance automation (6+ CI-enforced rules) -> Advanced capabilities (blast radius, drift detection, timeline visualization)

See CALM Integration Plan for the full phased implementation with JSON examples, CI integration, and migration strategy.

Priority: HIGH¶

Priority: MEDIUM¶

Priority: LOW¶

Completed Initiatives (Reference)¶

Reminders (Architecture Parking Lot)¶

These are deferred evaluations and operational items tracked in architecture/reminders/:

8. Architecture Review Checklist¶

This checklist is applied during PR review of every solution design:

Completeness¶

• Master document has Overview and Component Architecture
• All impacted services have impact assessment files
• At least 2 options considered in each decision (MADR format)

Capability Rollup¶

• Capability IDs declared in master document header
• 3.solution/c.capabilities/capabilities.md exists with impact types
• New L3 capabilities identified and named (if applicable)
• capability-changelog.yaml entry drafted
• All affected metadata YAML files identified for update

Content Separation¶

• Impact files describe WHAT, not WHY or HOW
• Decision files describe WHY, not HOW
• Guidance files describe HOW (if present)
• User stories describe WHO benefits, not technical details

Metadata Consistency¶

• YAML changes match the solution content
• Cross-service calls updated if new integrations added
• Backward compatibility addressed for all API changes

9. Success Criteria¶

Six months from now, an architect picking up a new check-in ticket should be able to:

1. Open the capability page for CAP-2.1 in the portal
2. See a timeline of every solution that has touched this capability
3. Read the L3 capabilities that emerged from prior work
4. Click through to any prior solution design to understand what was decided and why
5. See which ADRs shaped the check-in domain
6. Understand the current service state through microservice pages referencing all impacting solutions
7. Start their new solution with full context -- not from a blank page, but from accumulated knowledge
8. Find the same content in Confluence if that is their preferred consumption surface — always in sync, never diverged

That is continuous architecture. Not documentation that decays, but knowledge that compounds.

10. Companion Analysis Documents¶

This roadmap synthesizes three detailed analysis documents: