TracerTM 🚀

Agent-native, multi-view requirements traceability and project management system.

TracerTM is a comprehensive requirements traceability matrix (RTM) system designed for modern software development workflows. It provides a "Defense in Depth" approach to project governance, linking requirements to code, tests, and deployments across multiple architectural lenses.

---

📋 Table of Contents

• Key Features
• Architecture
• Getting Started
  • Prerequisites
  • Quick Start
• Observability & APM
• Governance & Hardening
• Testing & Quality
• Documentation
• Docs Deploy
• Contributing
• License

---

✨ Key Features

• 🔍 Multi-View Traceability: View projects through code, API, database, deployment, and documentation lenses.
• 🤖 Agent-Native Design: Built-in support for AI-assisted analysis and automated traceability maintenance.
• ⚡ Real-Time Sync: WebSocket-based live updates across all management interfaces.
• 📊 Graph Visualization: Interactive dependency graphs and impact analysis powered by Neo4j.
• 🛡 Hardened Governance: SLSA provenance, signed attestations, and automated quality gates.
• 📈 Full Observability: Integrated metrics (Prometheus), logs (Loki), and tracing (Jaeger).

---

🏗 Architecture

TracerTM uses a high-performance, polyglot architecture:

• Backend (Go): High-performance API server managing core business logic and integrations.
• Python Services: Specialized services for data analysis, CLI/TUI tools, and background processing.
• Frontend (React/TS): Modern SPA with TanStack Router, Zustand, and interactive visualizations.
• Persistence: PostgreSQL (Relational), Neo4j (Graph), Redis (Cache), and NATS (Messaging).

---

🚀 Getting Started

Prerequisites

• Go 1.21+, Python 3.11+, Node.js/Bun
• PostgreSQL 17+, Redis 7+, Neo4j 5.0+, NATS 2.9+
• Task (Task runner) and Process Compose

Quick Start (Native Environment)

# 1. Install all dependencies
task install

# 2. Run database migrations
task db:migrate

# 3. Start all services with interactive TUI dashboard
task dev:tui

# 4. Access the Unified Gateway
# http://localhost:4000 (Frontend, API, and Docs)

---

📊 Observability & APM

TracerTM includes enterprise-grade monitoring out of the box:

• Metrics: http://localhost:3000 (Grafana) / http://localhost:9090 (Prometheus)
• Tracing: http://localhost:16686 (Jaeger UI) - Track requests across Go and Python.
• Logs: Centralized log aggregation via Loki and Promtail.

---

🛡 Governance & Hardening

TracerTM operates at a critical quality tier:

1. Automated Quality Gates: Ruff, Go build/vet, golangci-lint, TSC, and Tach boundaries.
2. Provenance: All builds generate SLSA attestations with digital signatures.
3. Verification Policy: Defined dispute workflows for quality gate decisions in VERIFICATION_POLICY.md.
4. Security Scanning: Automated govulncheck, bandit, and security audits.

---

🧪 Testing & Quality

We maintain a rigorous multi-layer testing strategy:

• Unit & Integration: go test ./... and pytest tests/
• Frontend: bun test and E2E via Playwright.
• Complexity Audit: Automated tracking of code complexity (Radon) and naming conventions.
• Path Protection: Architectural boundary enforcement via tach.

---

📚 Documentation

• Docsets — Role-specific technical docsets.
  • Developer (Internal)
  • Developer (External)
  • Technical User
  • Agent Operator
• First Run Checklist — New clone setup.
• Changelog Process — How entries are added and released.
• Changelog Entry Template — Copy/paste snippet for new entries.
• Project Setup Style — Standardized repo command/process baseline.
• API Documentation — Interactive API explorer.
• Architecture Overview — Deep dive into internals.
• Verification Policy — Quality standards and dispute workflows.

Documentation Hub

For a unified view of all Kush ecosystem projects, visit the Docs Hub.

---

🚢 Docs Deploy

Local VitePress docs site:

cd docs
npm install
npm run docs:dev
npm run docs:build

GitHub Pages:

• Workflow: .github/workflows/vitepress-pages.yml
• URL convention: https://<owner>.github.io/trace/

---

🤝 Contributing

We welcome community contributions! Please see CONTRIBUTING.md (coming soon) for details on our development workflow and quality requirements.

---

📜 License

Distributed under the MIT License. See LICENSE for more information.

---

Built with ❤️ by the community