Skip to content

VISION.md

Latest commit

 

History

History
333 lines (249 loc) · 12.6 KB

VISION.md

File metadata and controls

333 lines (249 loc) · 12.6 KB
Raw

CodeCohesion API - Vision

What is the CodeCohesion API?

The CodeCohesion API provides programmatic access to repository analysis data generated by CodeCohesion's processor. It exposes cohesion metrics, contributor activity, file statistics, and temporal coupling data through a RESTful HTTP interface.

While the CodeCohesion viewer provides interactive 3D visualization for humans, the API enables:

  • Automated queries - CI/CD pipelines checking churn thresholds
  • Integrations - Slack bots reporting weekly hotspots
  • Dashboards - Team metrics and repository health displays
  • Tooling - VS Code extensions showing file coupling data
  • Analysis - Custom scripts extracting contributor patterns

The API reads existing analysis files generated by the processor and provides flexible querying capabilities without requiring direct file access or JSON parsing.

Who is this for?

Primary Audiences

DevOps/Platform Engineers

  • Query contributor activity for automated reports
  • Check churn metrics in CI/CD gates
  • Monitor repository health trends
  • Integrate cohesion data into existing dashboards

Technical Leads/Architects

  • Extract hotspot data for architecture reviews
  • Track coupling metrics over time
  • Analyze team ownership patterns
  • Generate reports for stakeholders

Tool Builders

  • Create IDE extensions showing file relationships
  • Build Slack/Discord bots with cohesion insights
  • Develop custom visualization tools
  • Integrate with existing developer tooling

Consultants

  • Programmatically analyze multiple client repositories
  • Generate consistent reports across projects
  • Build client-specific dashboards
  • Extract metrics for architecture assessments

What problem does it solve?

The Current State: CodeCohesion generates rich JSON analysis files containing:

  • File-level metrics (churn, contributors, coupling, LOC)
  • Repository statistics (commit counts, contributor lists, language distribution)
  • Timeline data (commit history, file changes over time)
  • Coupling clusters (files that change together)

But accessing this data requires:

  • Direct file system access to processor/output/*.json
  • Custom JSON parsing logic
  • Understanding the internal data format
  • Manual filtering and aggregation

The Problem: Teams want to:

  • "Show me all contributors to React in the last 90 days"
  • "Which files have the highest churn in my codebase?"
  • "Alert me when a file's contributor count exceeds 10"
  • "Track repository complexity metrics over time"

Without an API, each use case requires custom scripting and file parsing.

The Solution: A REST API that:

  • Abstracts the data format - Query by repository URL, not file names
  • Provides flexible filtering - Date ranges, path patterns, metric thresholds
  • Enables integrations - Standard HTTP interface for any tool or language
  • Supports automation - Machine-readable responses for CI/CD and monitoring
  • Remains lightweight - No database required initially, reads existing JSON files

Core Use Cases

1. Contributor Activity Queries

Scenario: "Who worked on this repository in the last 30 days?"

curl "https://codecohesion-api.railway.app/api/contributors?url=https://github.com/facebook/react&days=30"

Use cases:

  • Generate weekly team activity reports
  • Identify active contributors for code review assignments
  • Track team velocity by contributor count
  • Onboard new team members by showing recent contributors

2. Hotspot Detection

Scenario: "Which files are changed most frequently and might need refactoring?"

curl "https://codecohesion-api.railway.app/api/repos/react/hotspots?limit=10"

Use cases:

  • Architecture review preparation
  • Technical debt prioritization
  • Test coverage gap analysis
  • Refactoring candidate identification

3. Repository Health Metrics

Scenario: "What's the overall health of our codebase?"

curl "https://codecohesion-api.railway.app/api/repos/react/stats"

Use cases:

  • Executive dashboards showing LOC, commit counts, contributor diversity
  • Trend analysis (are we growing complexity or reducing it?)
  • Team capacity planning (active contributor counts)
  • Cross-repository comparisons

4. CI/CD Integration

Scenario: "Fail the build if a file exceeds churn threshold"

# In GitHub Actions workflow
curl "https://codecohesion-api.railway.app/api/repos/my-app/files?metric=churn" \
  | jq '.files[] | select(.commitCount > 50) | .path'

Use cases:

  • Enforce architecture guardrails
  • Alert on high-coupling patterns
  • Track complexity metrics over time
  • Automated code quality gates

5. Team Dashboards

Scenario: "Display real-time team metrics on office screens"

// Dashboard fetches data every hour
const response = await fetch(
  'https://codecohesion-api.railway.app/api/repos/my-app/stats'
);
const data = await response.json();
displayMetrics(data.stats);

Use cases:

  • Team room displays
  • Project management tool integrations
  • Leadership reporting dashboards
  • Retrospective preparation

6. Coupling & Impact Analysis

Scenario: "Which files should we test together in this PR?"

# Coupling partners for a specific file
curl "http://localhost:3001/api/repos/my-app/coupling/src/auth.ts"

# Blast radius — what breaks if I change this file?
curl "http://localhost:3001/api/repos/my-app/impact/src/auth.ts"

# Full file context — ownership, imports, functions, coupling
curl "http://localhost:3001/api/repos/my-app/context/src/auth.ts"

Use cases:

  • Test scope recommendations
  • Bounded context detection
  • Monolith decomposition planning
  • Impact analysis for changes
  • Code review preparation

Why REST over Direct File Access?

Authentication & Access Control

Future versions can add API keys, rate limiting, and per-user permissions without changing client code.

Stability

The internal JSON format can evolve without breaking API consumers. The API provides a stable contract.

Convenience

Consumers don't need to:

  • Parse JSON manually
  • Understand internal data structures
  • Handle file paths across platforms
  • Implement date filtering logic

Discoverability

RESTful endpoints are self-documenting and browseable. Tools like Postman, curl, and Swagger work out-of-the-box.

Deployment Flexibility

The API can run anywhere (Railway, AWS Lambda, local network) without requiring shared file system access.

Integration-Friendly

Every language has HTTP libraries. Any tool (CI/CD, Slack, VS Code) can consume the API without custom file parsing.

Why Not a GraphQL API?

Decision: Start with REST

While GraphQL offers flexible querying, REST is:

  • Simpler to implement - No schema definition language, resolvers, or specialized tooling
  • More familiar - Every developer knows REST; GraphQL has a steeper learning curve
  • Easier to cache - Standard HTTP caching works out-of-the-box
  • Better for small APIs - GraphQL shines with complex nested data; our API is relatively flat

We may revisit GraphQL if:

  • Clients need to compose complex queries across multiple resources
  • Network efficiency becomes critical (reducing round-trips)
  • The data model becomes significantly more nested

For now, REST + JSON provides the best balance of simplicity and functionality.

Design Principles

1. Progressive Enhancement

Start with minimal functionality (read JSON files, expose basic endpoints) and add features incrementally based on real usage patterns.

2. Minimal Tooling

Use TypeScript + Express + Node.js - technologies already in the CodeCohesion stack. No new languages, no heavy frameworks.

3. Deployment Simplicity

Deploy to Railway (same as existing prototypes). No complex infrastructure, no database required initially.

4. Backward Compatibility

The API should work with both static snapshots and timeline V2 formats. Support existing analysis files without requiring re-analysis.

5. Intuitive Endpoints

Use URL-based lookups (what consumers know) rather than opaque IDs. Support both convenience endpoints (/api/contributors?url=...) and efficient ID-based queries.

6. Standard HTTP Conventions

Use proper status codes (200, 404, 400, 500), follow REST naming conventions, return JSON consistently.

Current State & Future Direction

Implemented

  • Core API — 19 endpoints covering repos, stats, contributors, files, hotspots, imports, structure, complexity, coupling, impact, context, health
  • On-Demand Analysis — POST /api/process with SSE progress streaming, supports head/timeline/coupling/structure/complexity modes
  • OpenAPI 3.1 — machine-readable spec at /api/docs, interactive Swagger UI at /api/docs/ui
  • Health Scoring — composite 0-100 score with weighted metrics and graceful degradation
  • HATEOAS Navigation — all repo listings include links to available endpoints

Future

  • Persistence — PostgreSQL storage for historical comparisons and trend tracking
  • Advanced Queries — Search DSL, commit comparison, aggregations, pagination
  • Notifications — Webhook subscriptions, threshold alerts, scheduled analysis
  • Integrations — GitHub App, Slack/Discord bot, VS Code extension, Grafana connectors
  • Intelligence — Bounded context recommendations via coupling clustering

Success Metrics

We'll know the API is successful when:

  1. Adoption - 10+ distinct use cases built on top of the API
  2. Simplicity - New users can make their first successful query within 5 minutes
  3. Reliability - 99.9% uptime on Railway deployment
  4. Performance - Sub-200ms response times for typical queries
  5. Integration - Used in at least 3 different contexts (CI/CD, dashboard, bot)
  6. Documentation - API docs are linked from README and discoverable

Non-Goals (Current)

Out of Scope:

  • Authentication/authorization (open API, add later if needed)
  • Database persistence (JSON files work well for current use case)
  • Rate limiting (trust-based, add if abuse occurs)
  • API versioning (stable contract, no v2 planning yet)
  • Historical tracking (compare analyses over time — future feature)

Relationship to Existing Components

┌─────────────────────────────────────────────────────┐
│                  CodeCohesion                       │
├─────────────────────────────────────────────────────┤
│                                                     │
│  processor/              viewer/              api/  │
│  ┌──────────┐         ┌──────────┐       ┌────────┐│
│  │ Analyze  │────────▶│ 3D Viz   │       │ REST   ││
│  │ Git Repo │ .json   │ (Human)  │       │ API    ││
│  └──────────┘         └──────────┘       └────────┘│
│       │                                       │     │
│       │                                       │     │
│       └───────────────────────────────────────┘     │
│                    Reads JSON files                 │
│                                                     │
│  Users:                                             │
│  - Processor: Architects, devs analyzing repos      │
│  - Viewer: Teams exploring visualization           │
│  - API: CI/CD, dashboards, integrations, bots       │
│                                                     │
└─────────────────────────────────────────────────────┘

Key Insight: The API doesn't replace the processor or viewer - it complements them by enabling programmatic access to the same analysis data.

Target Timeline

Summary

The CodeCohesion API transforms rich repository analysis data into an accessible, queryable service. It enables automation, integrations, and tooling without requiring direct file access or custom parsing logic.

Core Value Proposition:

  • 19 endpoints covering the full analysis surface (structure, complexity, coupling, impact, health)
  • On-demand processing with SSE progress streaming
  • Self-documenting via OpenAPI 3.1 spec and Swagger UI
  • Graceful degradation when optional data is missing
  • HATEOAS links for API navigation

The API makes CodeCohesion data actionable for teams, tools, and automation systems.