# schmouli/ai-sdlc architecture

> Architecture diagram of the GitHub repository schmouli/ai-sdlc, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/schmouli/ai-sdlc
- Repository: https://github.com/schmouli/ai-sdlc

## Overview

AI-SDLC is a reusable AI-assisted development toolkit. Its sampled runtime branches include a Code Knowledge Graph that builds repository structure and supports retrieval and review digests, and SkillBox, whose telemetry supports learning extraction, proposed overlays, human review, and approved instruction injection. The README also documents Spec-Kit and EGM, but their directories are absent from the supplied tree, so they are not mapped here. Lifecycle-map and SDLC-pane generation are included as product capabilities. Some internal relationships are limited to README or source-index evidence.

Main entry points: [`src/skillbox/cli.py`](https://github.com/schmouli/ai-sdlc/blob/main/src/skillbox/cli.py) (SkillBox CLI), [`src/kg/graph_builder.py`](https://github.com/schmouli/ai-sdlc/blob/main/src/kg/graph_builder.py) (Graph builder), [`src/skillbox/overlays.py`](https://github.com/schmouli/ai-sdlc/blob/main/src/skillbox/overlays.py) (Overlay library), [`src/skillbox/telemetry.py`](https://github.com/schmouli/ai-sdlc/blob/main/src/skillbox/telemetry.py) (Event and session store)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_kg["Code Knowledge Graph"]
  node_kg_cli["KG commands"]
  node_kg_parser["Source parser<br/>[parser.py]"]
  node_kg_builder["Graph builder<br/>[graph_builder.py]"]
  node_kg_models["Graph model<br/>[models.py]"]
  node_kg_similarity["Lexical similarity<br/>[similarity.py]"]
  node_kg_retrieval["Graph retrieval<br/>[retrieval.py]"]
  node_kg_pagerank["PageRank<br/>[pagerank.py]"]
  node_kg_coedit["Co-edit links<br/>[coedit.py]"]
  node_kg_digest["Review digest<br/>[digest.py]"]
  node_kg_report["KG reporting<br/>[report.py]"]
  node_kg_eval["Retrieval evaluation<br/>[evaluation.py]"]
end

subgraph group_skillbox["SkillBox"]
  node_skill_cli["SkillBox CLI<br/>[cli.py]"]
  node_skill_config["Runtime configuration<br/>[config.py]"]
  node_skill_telemetry[("Event and session store<br/>[telemetry.py]")]
  node_skill_context["Project context<br/>[context.py]"]
  node_skill_registry["Skill registry<br/>[registry.py]"]
  node_skill_compose["Skill composition<br/>[compose.py]"]
  node_skill_learning["Learning extraction<br/>[learning.py]"]
  node_skill_metrics["Outcome metrics<br/>[metrics.py]"]
  node_skill_overlays["Overlay library<br/>[overlays.py]"]
  node_skill_review["Human review<br/>[review.py]"]
  node_skill_inject["Instruction injection<br/>[inject.py]"]
  node_skill_reports["SkillBox reports<br/>[reports.py]"]
  node_skill_mlflow["MLflow sink<br/>[mlflow_sink.py]"]
  node_skill_sweep["Skill sweep<br/>[sweep.py]"]
end

subgraph group_measurement["SDLC Measurement"]
  node_lifecycle_map["Lifecycle map"]
  node_sdlc_pane["SDLC measurement pane"]
end

node_user(("Developer/operator"))
node_mlflow(("MLflow service"))
node_developer(("AI development activity"))

node_user -->|"runs commands"| node_kg_cli
node_kg_cli -->|"builds graph"| node_kg_builder
node_kg_cli -->|"retrieves nodes"| node_kg_retrieval
node_kg_cli -->|"renders digest"| node_kg_digest
node_kg_cli -->|"evaluates retrieval"| node_kg_eval
node_kg_builder -->|"parses source"| node_kg_parser
node_kg_builder -->|"creates graph"| node_kg_models
node_kg_builder -->|"adds co-edits"| node_kg_coedit
node_kg_builder -->|"uses similarity"| node_kg_similarity
node_kg_retrieval -->|"anchors query"| node_kg_similarity
node_kg_retrieval -->|"ranks results"| node_kg_pagerank
node_kg_retrieval -->|"traverses snapshot"| node_kg_models
node_kg_digest -->|"selects top files"| node_kg_pagerank
node_kg_eval -->|"tests retrieval"| node_kg_retrieval
node_kg_eval -->|"uses similarity"| node_kg_similarity
node_kg_builder -->|"reports failures"| node_kg_report
node_user -->|"runs commands"| node_skill_cli
node_skill_cli -->|"loads settings"| node_skill_config
node_skill_cli -->|"records events"| node_skill_telemetry
node_skill_cli -->|"detects context"| node_skill_context
node_skill_cli -->|"lists skills"| node_skill_registry
node_skill_cli -->|"extracts learnings"| node_skill_learning
node_skill_cli -->|"stages overlays"| node_skill_overlays
node_skill_cli -->|"routes decisions"| node_skill_review
node_skill_cli -->|"reports metrics"| node_skill_metrics
node_skill_cli -->|"renders reports"| node_skill_reports
node_skill_cli -->|"refreshes instructions"| node_skill_inject
node_skill_cli -.->|"pushes telemetry"| node_skill_mlflow
node_skill_compose -->|"records composition"| node_skill_telemetry
node_skill_compose -->|"loads skill"| node_skill_registry
node_skill_compose -->|"uses context"| node_skill_context
node_skill_compose -->|"applies overlays"| node_skill_overlays
node_skill_learning -->|"analyzes events"| node_skill_telemetry
node_skill_metrics -->|"reads outcomes"| node_skill_telemetry
node_skill_learning -->|"informs staging"| node_skill_overlays
node_skill_overlays -->|"checks audit"| node_skill_review
node_skill_review -->|"approves versions"| node_skill_overlays
node_skill_inject -->|"loads approved versions"| node_skill_overlays
node_skill_inject -->|"reads approvals"| node_skill_telemetry
node_skill_mlflow -.->|"sends metrics"| node_mlflow
node_skill_sweep -.->|"schedules learning"| node_skill_learning
node_developer -->|"generates activity"| node_skill_telemetry
node_developer -->|"measures lifecycle"| node_lifecycle_map
node_developer -->|"views measurements"| node_sdlc_pane

click node_kg_cli "https://github.com/schmouli/ai-sdlc/blob/main/scripts/run_knowledge_graph.py"
click node_kg_parser "https://github.com/schmouli/ai-sdlc/blob/main/src/kg/parser.py"
click node_kg_builder "https://github.com/schmouli/ai-sdlc/blob/main/src/kg/graph_builder.py"
click node_kg_models "https://github.com/schmouli/ai-sdlc/blob/main/src/kg/models.py"
click node_kg_similarity "https://github.com/schmouli/ai-sdlc/blob/main/src/kg/similarity.py"
click node_kg_retrieval "https://github.com/schmouli/ai-sdlc/blob/main/src/kg/retrieval.py"
click node_kg_pagerank "https://github.com/schmouli/ai-sdlc/blob/main/src/kg/pagerank.py"
click node_kg_coedit "https://github.com/schmouli/ai-sdlc/blob/main/src/kg/coedit.py"
click node_kg_digest "https://github.com/schmouli/ai-sdlc/blob/main/src/kg/digest.py"
click node_kg_report "https://github.com/schmouli/ai-sdlc/blob/main/src/kg/report.py"
click node_kg_eval "https://github.com/schmouli/ai-sdlc/blob/main/src/kg/evaluation.py"
click node_skill_cli "https://github.com/schmouli/ai-sdlc/blob/main/src/skillbox/cli.py"
click node_skill_config "https://github.com/schmouli/ai-sdlc/blob/main/src/skillbox/config.py"
click node_skill_telemetry "https://github.com/schmouli/ai-sdlc/blob/main/src/skillbox/telemetry.py"
click node_skill_context "https://github.com/schmouli/ai-sdlc/blob/main/src/skillbox/context.py"
click node_skill_registry "https://github.com/schmouli/ai-sdlc/blob/main/src/skillbox/registry.py"
click node_skill_compose "https://github.com/schmouli/ai-sdlc/blob/main/src/skillbox/compose.py"
click node_skill_learning "https://github.com/schmouli/ai-sdlc/blob/main/src/skillbox/learning.py"
click node_skill_metrics "https://github.com/schmouli/ai-sdlc/blob/main/src/skillbox/metrics.py"
click node_skill_overlays "https://github.com/schmouli/ai-sdlc/blob/main/src/skillbox/overlays.py"
click node_skill_review "https://github.com/schmouli/ai-sdlc/blob/main/src/skillbox/review.py"
click node_skill_inject "https://github.com/schmouli/ai-sdlc/blob/main/src/skillbox/inject.py"
click node_skill_reports "https://github.com/schmouli/ai-sdlc/blob/main/src/skillbox/reports.py"
click node_skill_mlflow "https://github.com/schmouli/ai-sdlc/blob/main/src/skillbox/mlflow_sink.py"
click node_skill_sweep "https://github.com/schmouli/ai-sdlc/blob/main/src/skillbox/sweep.py"
click node_lifecycle_map "https://github.com/schmouli/ai-sdlc/blob/main/scripts/generate_lifecycle_map.py"
click node_sdlc_pane "https://github.com/schmouli/ai-sdlc/blob/main/scripts/generate_sdlc_pane.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_kg_cli,node_kg_parser,node_kg_builder,node_kg_models,node_kg_similarity,node_kg_retrieval,node_kg_pagerank,node_kg_coedit,node_kg_digest,node_kg_report,node_kg_eval toneBlue
class node_skill_cli,node_skill_config,node_skill_telemetry,node_skill_context,node_skill_registry,node_skill_compose,node_skill_learning,node_skill_metrics,node_skill_overlays,node_skill_review,node_skill_inject,node_skill_reports,node_skill_mlflow,node_skill_sweep toneAmber
class node_lifecycle_map,node_sdlc_pane toneMint
class node_user,node_mlflow,node_developer toneIndigo
```

## Components

### Code Knowledge Graph

- [KG commands](https://github.com/schmouli/ai-sdlc/blob/main/scripts/run_knowledge_graph.py): `scripts/run_knowledge_graph.py`
- [Source parser](https://github.com/schmouli/ai-sdlc/blob/main/src/kg/parser.py): `src/kg/parser.py`
- [Graph builder](https://github.com/schmouli/ai-sdlc/blob/main/src/kg/graph_builder.py): `src/kg/graph_builder.py`
- [Graph model](https://github.com/schmouli/ai-sdlc/blob/main/src/kg/models.py): `src/kg/models.py`
- [Lexical similarity](https://github.com/schmouli/ai-sdlc/blob/main/src/kg/similarity.py): `src/kg/similarity.py`
- [Graph retrieval](https://github.com/schmouli/ai-sdlc/blob/main/src/kg/retrieval.py): `src/kg/retrieval.py`
- [PageRank](https://github.com/schmouli/ai-sdlc/blob/main/src/kg/pagerank.py): `src/kg/pagerank.py`
- [Co-edit links](https://github.com/schmouli/ai-sdlc/blob/main/src/kg/coedit.py): `src/kg/coedit.py`
- [Review digest](https://github.com/schmouli/ai-sdlc/blob/main/src/kg/digest.py): `src/kg/digest.py`
- [KG reporting](https://github.com/schmouli/ai-sdlc/blob/main/src/kg/report.py): `src/kg/report.py`
- [Retrieval evaluation](https://github.com/schmouli/ai-sdlc/blob/main/src/kg/evaluation.py): `src/kg/evaluation.py`

### SkillBox

- [SkillBox CLI](https://github.com/schmouli/ai-sdlc/blob/main/src/skillbox/cli.py): `src/skillbox/cli.py`
- [Runtime configuration](https://github.com/schmouli/ai-sdlc/blob/main/src/skillbox/config.py): `src/skillbox/config.py`
- [Event and session store](https://github.com/schmouli/ai-sdlc/blob/main/src/skillbox/telemetry.py): `src/skillbox/telemetry.py`
- [Project context](https://github.com/schmouli/ai-sdlc/blob/main/src/skillbox/context.py): `src/skillbox/context.py`
- [Skill registry](https://github.com/schmouli/ai-sdlc/blob/main/src/skillbox/registry.py): `src/skillbox/registry.py`
- [Skill composition](https://github.com/schmouli/ai-sdlc/blob/main/src/skillbox/compose.py): `src/skillbox/compose.py`
- [Learning extraction](https://github.com/schmouli/ai-sdlc/blob/main/src/skillbox/learning.py): `src/skillbox/learning.py`
- [Outcome metrics](https://github.com/schmouli/ai-sdlc/blob/main/src/skillbox/metrics.py): `src/skillbox/metrics.py`
- [Overlay library](https://github.com/schmouli/ai-sdlc/blob/main/src/skillbox/overlays.py): `src/skillbox/overlays.py`
- [Human review](https://github.com/schmouli/ai-sdlc/blob/main/src/skillbox/review.py): `src/skillbox/review.py`
- [Instruction injection](https://github.com/schmouli/ai-sdlc/blob/main/src/skillbox/inject.py): `src/skillbox/inject.py`
- [SkillBox reports](https://github.com/schmouli/ai-sdlc/blob/main/src/skillbox/reports.py): `src/skillbox/reports.py`
- [MLflow sink](https://github.com/schmouli/ai-sdlc/blob/main/src/skillbox/mlflow_sink.py): `src/skillbox/mlflow_sink.py`
- [Skill sweep](https://github.com/schmouli/ai-sdlc/blob/main/src/skillbox/sweep.py): `src/skillbox/sweep.py`

### SDLC Measurement

- [Lifecycle map](https://github.com/schmouli/ai-sdlc/blob/main/scripts/generate_lifecycle_map.py): `scripts/generate_lifecycle_map.py`
- [SDLC measurement pane](https://github.com/schmouli/ai-sdlc/blob/main/scripts/generate_sdlc_pane.py): `scripts/generate_sdlc_pane.py`

### Other components

- **Developer/operator**
- **MLflow service**
- **AI development activity**

## Connections

- Developer/operator → KG commands: runs commands (evidence: `README.md`)
- KG commands → Graph builder: builds graph (evidence: `scripts/run_knowledge_graph.py`)
- KG commands → Graph retrieval: retrieves nodes (evidence: `scripts/run_knowledge_graph.py`)
- KG commands → Review digest: renders digest (evidence: `scripts/run_knowledge_graph.py`)
- KG commands → Retrieval evaluation: evaluates retrieval (evidence: `scripts/run_knowledge_graph.py`)
- Graph builder → Source parser: parses source (evidence: `src/kg/graph_builder.py`)
- Graph builder → Graph model: creates graph (evidence: `src/kg/graph_builder.py`)
- Graph builder → Co-edit links: adds co-edits (evidence: `src/kg/graph_builder.py`)
- Graph builder → Lexical similarity: uses similarity (evidence: `src/kg/graph_builder.py`)
- Graph retrieval → Lexical similarity: anchors query (evidence: `src/kg/retrieval.py`)
- Graph retrieval → PageRank: ranks results (evidence: `src/kg/retrieval.py`)
- Graph retrieval → Graph model: traverses snapshot (evidence: `README.md`)
- Review digest → PageRank: selects top files (evidence: `src/kg/digest.py`)
- Retrieval evaluation → Graph retrieval: tests retrieval (evidence: `src/kg/evaluation.py`)
- Retrieval evaluation → Lexical similarity: uses similarity (evidence: `src/kg/evaluation.py`)
- Graph builder → KG reporting: reports failures (evidence: `src/kg/graph_builder.py`)
- Developer/operator → SkillBox CLI: runs commands (evidence: `README.md`)
- SkillBox CLI → Runtime configuration: loads settings (evidence: `src/skillbox/cli.py`)
- SkillBox CLI → Event and session store: records events (evidence: `src/skillbox/cli.py`)
- SkillBox CLI → Project context: detects context (evidence: `src/skillbox/cli.py`)
- SkillBox CLI → Skill registry: lists skills (evidence: `src/skillbox/cli.py`)
- SkillBox CLI → Learning extraction: extracts learnings (evidence: `src/skillbox/cli.py`)
- SkillBox CLI → Overlay library: stages overlays (evidence: `src/skillbox/cli.py`)
- SkillBox CLI → Human review: routes decisions (evidence: `src/skillbox/cli.py`)
- SkillBox CLI → Outcome metrics: reports metrics (evidence: `src/skillbox/cli.py`)
- SkillBox CLI → SkillBox reports: renders reports (evidence: `src/skillbox/cli.py`)
- SkillBox CLI → Instruction injection: refreshes instructions (evidence: `src/skillbox/cli.py`)
- SkillBox CLI → MLflow sink: pushes telemetry (evidence: `src/skillbox/cli.py`)
- Skill composition → Event and session store: records composition (evidence: `src/skillbox/compose.py`)
- Skill composition → Skill registry: loads skill (evidence: `src/skillbox/compose.py`)
- Skill composition → Project context: uses context (evidence: `src/skillbox/compose.py`)
- Skill composition → Overlay library: applies overlays (evidence: `src/skillbox/compose.py`)
- Learning extraction → Event and session store: analyzes events (evidence: `src/skillbox/learning.py`)
- Outcome metrics → Event and session store: reads outcomes (evidence: `src/skillbox/metrics.py`)
- Learning extraction → Overlay library: informs staging (evidence: `src/skillbox/learning.py`)
- Overlay library → Human review: checks audit (evidence: `src/skillbox/overlays.py`)
- Human review → Overlay library: approves versions (evidence: `src/skillbox/review.py`)
- Instruction injection → Overlay library: loads approved versions (evidence: `src/skillbox/inject.py`)
- Instruction injection → Event and session store: reads approvals (evidence: `src/skillbox/inject.py`)
- MLflow sink → MLflow service: sends metrics
- Skill sweep → Learning extraction: schedules learning
- AI development activity → Event and session store: generates activity (evidence: `README.md`)
- AI development activity → Lifecycle map: measures lifecycle (evidence: `README.md`)
- AI development activity → SDLC measurement pane: views measurements (evidence: `README.md`)
