Bilingual Navigation: Versión en Español
↑ Evolith Tracker position within the E2E Product Vision · MD3 — click to enlarge
Evolith Tracker is the Governance Control Plane satellite of Evolith Core.
The Core defines. Providers execute. Evaluators assess. Tracker decides and audits.
- What is Evolith Tracker?
- Why Tracker?
- Core Capabilities
- How It Fits in Evolith
- Main Workflows
- Interface Overview
- Architecture Integration
- Quick Start
- Configuration
- Documentation
- Roadmap
- Contributing
- License
Evolith Tracker is a web application that turns ideas into governed, auditable products.
It tracks every step of the Software Development Lifecycle — from the first idea through strategic intake, discovery, design, construction, QA, and release — enforcing gates, collecting evidence, and making decisions at each phase boundary.
Tracker is a satellite of Evolith Core. The Core sets the rules. Tracker applies them and audits results.
Most teams lose visibility between strategy and execution. Ideas live in spreadsheets, decisions get buried in chat, and SDLC phases happen without formal gates or evidence.
Tracker solves this by providing:
- A single source of truth for product lifecycle state.
- Governed gates that require evidence before a phase can advance.
- Full traceability from an initial idea to a deployed release.
- Architectural awareness — every product is linked to its topologies, ADRs, blueprints, and GAPs.
| Capability | Description |
|---|---|
| Idea to Product | Capture raw ideas, evaluate feasibility, and promote them to tracked initiatives |
| SDLC Phases | Six sequential phases: Intake → Discovery → Design → Construction → QA → Release |
| Phase Gates | Each phase has a gate with criteria, checklists, and required artifacts before advancement |
| Artifacts & Evidence | Attach, version, and validate deliverables at every phase |
| Status Tracking | Real-time status per product, phase, gate, and artifact |
| Validations | Automated and manual validations against Core rulesets and OPA policies |
| Topology Management | Visualize and manage multi-topology architecture configurations |
| ADRs | Capture, navigate, and enforce Architectural Decision Records |
| Blueprints | Reference and apply standardized architecture blueprints per product |
| GAP Tracking | Register, classify, and follow up on architecture and compliance gaps |
| Satellite Repositories | Link and monitor GitHub satellite repositories per product |
Tracker sits at the center of the Evolith ecosystem and connects with:
| Component | Role |
|---|---|
| Evolith Core | Root authority for governance rules, rulesets, topologies, and schemas |
| Core-API | REST API (/api/v1) that Tracker calls to evaluate gates and fetch reference data |
| SmartCLI | Command-line interface for triggering evaluations and querying Tracker state |
| MCP | Model Context Protocol gateway — enables AI agents to query and act on Tracker data |
| Rulesets | OPA-backed policy bundles consumed from Core to validate artifacts and phases |
| OPA | Open Policy Agent engine that executes wasm rule bundles during gate evaluation |
| Schemas | Canonical domain schemas (satellite manifest, evaluation verdict, phase IDs) owned by Core |
| Manifests | evolith.satellite.json — machine-readable declaration of Tracker's boundaries and invariants |
| AI Agents | BMAD agent suite for PO, SM, Architect, Dev, QA roles — orchestrated through CLI and MCP |
The responsibility model is simple: Core defines. Providers execute. CLI and MCP evaluate. Tracker decides and audits.
Capture a business opportunity → run feasibility → approve as initiative → track through all 6 phases.
Advance a product through each SDLC phase by satisfying gate criteria, attaching required artifacts, and collecting evidence.
Browse the topology map of a product — bounded contexts, layers, integrations, and satellite repositories.
Create and link Architectural Decision Records to a product. Apply reference blueprints to guide design decisions.
Register architecture or compliance gaps discovered during audits. Track status, priority, and resolution path.
Link GitHub repositories to a product. Fetch metadata, monitor compliance state, and run evaluations from Tracker.
Use the SmartCLI or MCP to query product architecture, evaluate a satellite manifest, or ask an AI agent for a governance assessment — without opening the UI.
Tracker is a React 19 + NestJS 11 monorepo application.
The UI is organized around four main areas:
- Dashboard — global view of all products, statuses, and pending gates.
- Product Detail — per-product view with phases, gates, artifacts, and history.
- Architecture Hub — topology visualization, ADRs, blueprints, and GAP register.
- Settings — tenant configuration, integrations, and satellite repository links.
Access is permission-driven: roles determine what each user can view, transition, or approve.
Tracker implements the Governed Composition architecture:
- Tracker is a satellite — it owns its own domain, microservices, and database.
- All governance rules come from Evolith Core via the Core API Exposure Layer (
ADR-0074). - The BFF / Application Gateway lives in Tracker and is the only authenticated perimeter.
- Core never receives user tokens or credentials — only
repositoryRef,workspaceRef, andoperationId(ADR-0080). - An Anti-Corruption Layer (ACL) translates Core contracts into Tracker view-models.
- Gate decisions are made exclusively by Tracker — Core only produces technical evidence (
EvaluationVerdict).
For the full boundary definition, see evolith.satellite.json and DECISIONS.md.
Prerequisites: Node.js 20+, npm 10+, PostgreSQL 16+.
# Clone the repository
git clone https://github.com/beyondnetcode/evolith_tracker.git
cd evolith_tracker
# Install dependencies
npm install
# Configure environment variables
cp .env.example .env
# Edit .env with your database and Core-API settings
# Run database migrations
npm run db:migrate
# Start the development server (frontend + backend)
npm run devThe frontend runs at http://localhost:5173 and the API at http://localhost:3000.
| Variable | Description |
|---|---|
DATABASE_URL |
PostgreSQL connection string |
CORE_API_BASE_URL |
Evolith Core API base URL (/api/v1) |
UMS_JWKS_URI |
UMS JWKS endpoint for JWT validation |
TENANT_ID |
Default tenant identifier |
See .env.example for the full list of available variables.
For Core-API integration details, see the Core Integration Design.
| Document | Description |
|---|---|
| MASTER_INDEX.md | Full documentation index with role-based navigation |
| DECISIONS.md | Architectural Decision Records — local and inherited from Core |
| Satellite Manifest | Machine-readable boundary declaration (role, invariants, ADRs) |
| Target Architecture | Master architecture: bounded contexts, domain model, layers |
| Implementation Roadmap | 8-phase build roadmap with effort estimates and risk register |
| PRD | Product Requirements Document: epics, stories, CLI, MCP |
| User Stories | 123 stories · 409 pts · 12 modules · Gherkin criteria |
| GAP Register | Architecture and compliance gaps with status and priority |
| Phase 00 — Intake Hub | Strategic Intake phase documentation |
| Phase 01 — Discovery Hub | Discovery phase documentation |
| Phase 02 — Design Hub | Design phase documentation |
Tracker follows an 8-phase implementation roadmap:
- Phase 1 — Core infrastructure: monorepo setup, database, auth, BFF
- Phase 2 — Intake & Discovery modules
- Phase 3 — Design module + Core integration (ADRs, blueprints)
- Phase 4 — Gate engine + artifact system
- Phase 5 — Construction & QA modules
- Phase 6 — Release module + Re-Do flow
- Phase 7 — CLI + MCP integration
- Phase 8 — AI agent orchestration (BMAD suite)
For the full roadmap with effort estimates and risks, see the Implementation Roadmap.
Before contributing, read:
AGENTS.md— Agent rules, conventions, and BMAD rolesDECISIONS.md— Architectural decisions — local and inheritedevolith.satellite.json— Satellite boundary and invariants- Gaps & Opportunities — Open gaps and improvement areas
Core governance rules are defined upstream in Evolith Core. Do not redefine them here.
Dual licensed. See LICENSE and NOTICE.