Skip to content

tracker-implementation-roadmap.md

Latest commit

 

History

History
311 lines (217 loc) · 11.3 KB

tracker-implementation-roadmap.md

File metadata and controls

311 lines (217 loc) · 11.3 KB

Evolith Tracker — Implementation Roadmap

Bilingual Navigation: English (this document) · Versión en Español

Document Status: Draft
Type: Implementation Plan
Satellite: Evolith Tracker
Upstream: Evolith Core
Date: 2026-06-07
Author: Architect Agent (BMAD)

1. Roadmap Overview

1.1 Phases Summary

Phase Focus Duration Key Deliverables
Phase 0 Analysis & Foundation M (2 weeks) Repository, CI/CD, shared domain primitives, PostgreSQL schemas, MCP Server skeleton
Phase 1 Core Sync + Auth + CLI Foundation M (2 weeks) Core SDK adapter, UMS auth adapter, permission guards, CLI foundation (evolith init, auth, --format=json), MCP Server bootstrap
Phase 2 Discovery + Design + CLI M (2 weeks) Initiative, Backlog, Blueprint, Contract, ADR modules, Discovery CLI commands
Phase 3 Construction + QA + CLI M (2 weeks) Cycle, Story, PeerReview, TestCycle, Execution, Defect, Design CLI commands
Phase 4 Release + Governance + CLI M (2 weeks) ReleasePackage, Deployment, SatelliteProduct, SDLCExecution, Construction CLI commands
Phase 5 QA + MCP Tool Suite M (2 weeks) QA module completion, QA CLI commands, MCP tool suite finalization, agent SDK
Phase 6 Metrics + Scorecards + CLI M (2 weeks) DORA/SPACE computation, drift alerts, dashboards, Release CLI commands
Phase 7 Integrations + Gate CLI M (2 weeks) GitHub ACL, Jira ACL, webhook handlers, Gate & Agent CLI commands, MCP Tool Suite complete
Phase 8 Hardening + Release M (2 weeks) Security audit, E2E tests, Helm charts, production readiness

Total Estimated Duration: ~18.5 weeks (~4.6 months)

1.2 Effort Estimates

Module Stories Points Complexity
Discovery 13 48 Medium
Design 11 37 Medium
Construction 14 48 High
QA 11 35 Medium
Release 10 30 Medium
Governance 11 35 Medium
Artifacts 7 18 Low
Metrics 6 19 Low
Integration 8 26 High
Infrastructure 10 34 Medium
CLI + MCP 12 42 High
Total 114 372 —

2. Phase 0: Foundation (Week 1)

2.1 Goal

Establish the monorepo, CI/CD pipeline, shared domain primitives, and PostgreSQL schema infrastructure.

2.2 Deliverables

  • Monorepo workspace (npm workspaces or Nx)
  • NestJS API app bootstrap with TypeScript strict mode
  • React Web app with Vite + TanStack Query + Zustand
  • Shared libs/domain with base classes (AggregateRoot, BaseDomainEvent, Result)
  • 10 PostgreSQL schemas created with DDL migrations
  • RLS policies configured for multi-tenancy
  • GitHub Actions CI pipeline (lint, typecheck, test)
  • Docker Compose for local development
  • Helm chart skeleton for Kubernetes deployment
  • MCP Server skeleton package (@evolith/tracker-mcp scaffold)

2.3 Key Decisions

  • ORM: TypeORM (per ADR-0043)
  • API versioning: URI prefix (/api/v1/)
  • Validation: class-validator (presentation), zod (application)

3. Phase 1: Core Sync + Auth + CLI Foundation (Weeks 2-3)

3.1 Goal

Integrate with Evolith Core (rulesets, artifact definitions) and UMS (JWT validation, permission resolution). Establish CLI foundation and MCP Server bootstrap so agents can interact from Phase 1.

3.2 Deliverables

  • CoreIntegrationService with REST client, caching, version tracking
  • CoreCacheService with Redis + in-memory fallback
  • JwksService for JWT signature verification
  • UmsSecurityAdapter with authorization graph fetching
  • PermissionMapper (UMS → Tracker canonical permissions)
  • JwtAuthGuard + TrackerPermissionGuard for NestJS
  • Permission context provider for React
  • Auth store with token refresh logic
  • evolith CLI package skeleton (evolith init, auth login, --format=json global flag)
  • MCP Server bootstrap with @evolith/tracker-mcp basic tools

3.3 Dependencies

  • Requires Core BFF Gateway URL and B2B API credentials (per Core ADR-0008/0030/0075)
  • Requires UMS JWKS endpoint access

4. Phase 2: Discovery + Design + CLI (Weeks 4-5)

4.1 Goal

Implement Gate 1 (Discovery) and Gate 2 (Design) bounded contexts with their CLI commands.

4.2 Discovery Deliverables

  • Initiative aggregate with create, approve, reject, generateBacklog
  • Backlog aggregate with story ordering
  • Epic aggregate with external references
  • UserStory aggregate with priority, estimation
  • Discovery CQRS commands and queries
  • Discovery canvas form (React)

4.3 Design Deliverables

  • TechnicalBlueprint aggregate with approval workflow
  • TechnicalContract aggregate with content validation
  • ADR aggregate with status lifecycle
  • DataSchema aggregate
  • Design CQRS commands and queries
  • Design review board (React)

4.4 CLI Deliverables

  • Discovery CLI commands (evolith discovery submit, evolith backlog list)
  • Design CLI commands (evolith blueprint create, evolith adr list)

4.5 Phase Gate 1 & 2

  • Gate 1 evaluator with requirement checklist
  • Gate 2 evaluator with ADR compliance check
  • Phase advancement logic in SDLCExecution

5. Phase 3: Construction + QA + CLI (Weeks 6-7)

5.1 Goal

Implement Gate 3 (Construction) and Gate 4 (QA) bounded contexts with their CLI commands.

5.2 Construction Deliverables

  • ImplementationCycle aggregate with sprint management
  • TechnicalStory aggregate with time logging
  • PeerReview aggregate with GitHub webhook integration
  • Drift detection service (DriftDetectionService)
  • Construction board with drift index overlay (React)

5.3 QA Deliverables

  • TestCycle aggregate with pass rate calculation
  • TestExecution aggregate with result logging
  • Defect aggregate with severity/priority lifecycle
  • .harness ACL adapter (pending API inspection)
  • QA Command Center (React)

5.4 CLI Deliverables

  • Construction CLI commands (evolith task list, evolith drift status)
  • QA CLI commands (evolith test run, evolith defect list)

5.5 Phase Gate 3 & 4

  • Gate 3 evaluator with peer review + DoD check
  • Gate 4 evaluator with test pass rate + defect threshold

6. Phase 4: Release + Governance + CLI (Weeks 8-9)

6.1 Goal

Implement Gate 5 (Release) and Governance contexts with their CLI commands.

6.2 Release Deliverables

  • ReleasePackage aggregate with version management
  • DeploymentRecord aggregate (independent for CI/CD async updates)
  • Environment entity
  • Re-Do flow engine
  • Release planner calendar (React)

6.3 Governance Deliverables

  • SatelliteProduct aggregate for tenant tracking
  • SDLCExecution aggregate for phase state management
  • PhaseGateState aggregate with criteria tracking
  • ExceptionRequest aggregate for gate exception handling
  • Pipeline view (React) — the primary home screen

6.4 CLI Deliverables

  • Release CLI commands (evolith release plan, evolith deployment status)
  • Governance CLI commands (evolith gate status, evolith exception list)

7. Phase 5: QA + MCP Tool Suite (Weeks 10-11)

7.1 Goal

Complete QA module and finalize the MCP Tool Suite. QA CLI commands ship with the QA module, and the remaining MCP tools are finished.

7.2 QA CLI Deliverables

  • QA CLI commands (evolith qa status, evolith qa run, evolith qa report)
  • QA module completion per Phase 3 QA deliverables

7.3 MCP Tool Suite Deliverables

  • @evolith/tracker-mcp full tool suite
  • Tool definitions: initiative, design, construction, qa, release, gate
  • MCP polling/sampling endpoint for domain events
  • Agent SDK for agent integration

8. Phase 6: Metrics + Scorecards + CLI (Weeks 12-13)

8.1 Goal

Implement DORA/SPACE metrics, drift alerts, dashboards, and their CLI commands.

8.2 Deliverables

  • ScorecardDefinition aggregate
  • MetricSnapshot aggregate with computed values
  • DriftAlert aggregate with resolution tracking
  • Metrics computation service (deployment frequency, lead time, etc.)
  • Scorecard dashboard (React)
  • Drift alert notification system
  • Metrics CLI commands (evolith metrics scorecard, evolith drift alerts)

9. Phase 7: Integrations + Gate CLI (Weeks 14-15)

9.1 Goal

Implement ACL adapters for external systems (GitHub, Jira, Azure DevOps). Finalize Gate and Agent CLI commands and complete the MCP Tool Suite.

9.2 Deliverables

  • IntegrationEndpoint aggregate for external system config
  • SyncRecord aggregate for sync history
  • GitHub ACL (PR events → PeerReview updates)
  • Jira ACL (issues → Initiative imports)
  • Webhook handler for external system events
  • External checkpoint registration endpoint (US-INT-008)
  • Outbound sync for defect management
  • Gate CLI commands (evolith gate evaluate, evolith gate approve)
  • Agent CLI commands (evolith agent status, evolith agent assign)
  • MCP Tool Suite finalization (all tool definitions, polling/sampling, agent SDK)

10. Phase 8: Hardening + Release (Weeks 16-17)

10.1 Goal

Production readiness, security audit, and release preparation.

10.2 Deliverables

  • Security audit (OWASP Top 10 review, penetration testing)
  • E2E tests (Playwright) for critical user journeys
  • Performance testing (k6) for API load handling
  • Helm chart finalized with production values
  • Observability (OpenTelemetry traces, metrics, logs)
  • Production runbook documentation
  • SLO/SLA definitions

11. Risk Register

Risk Impact Likelihood Mitigation
UMS Authorization Graph schema differs from design High Medium Prototype integration early; fallback to JWT claims
Core SDK not available when Phase 1 starts Medium Medium Implement REST client with manual types as fallback
.harness API unknown High High Raise gap to Core immediately; design abstract adapter
PostgreSQL RLS performance at scale Medium Low Test with 1000+ tenants; optimize indexes
BMAD agent protocol changes Medium Low Version MCP tools; implement graceful degradation

12. Dependencies on Upstream

Dependency Impact Owner Status
Evolith Core REST API All phases Core team Not available
UMS JWKS endpoint Phase 1 UMS team Not confirmed
UMS Authorization Graph API Phase 1 UMS team Not inspected
Core SDK (if available) Phase 1 Core team Not confirmed

References