# krishnakumarkris/ai-technical-debt-agent architecture

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

- Interactive diagram: https://gitdiagram.com/krishnakumarkris/ai-technical-debt-agent
- Repository: https://github.com/krishnakumarkris/ai-technical-debt-agent

## Overview

#### Purpose and Entry Point
This is a Python backend for analyzing Java projects. It combines structural source scanning, dependency extraction, and technical-debt rule evaluation. The likely application entry point is `backend/main.py`; `backend/api/__init__.py` and `backend/app/__init__.py` indicate API/application packaging, though no route modules are present.

#### Project Scan Orchestration
The scanner pipeline is centered on `backend/scanner/project_scanner.py` and `backend/scanner/scanner_service.py`. It accepts a Java project directory, locates relevant files, parses source/dependency metadata, and produces a project-level representation. Scan configuration and file traversal boundaries are defined in `backend/scanner/config.py` and `backend/scanner/utils/file_utils.py`.

#### Java Source Parsing and Structural Model
Java source files are transformed into an internal project model through `backend/scanner/java_parser/java_ast_parser.py`. The resulting domain structure is represented by `backend/scanner/models/project_model.py`, which is the boundary between language-specific AST parsing and downstream analysis. Sample uploaded input follows a Maven layout under `backend/scanner/uploads/SampleProject/src/`.

#### Dependency and Relationship Graph Construction
`backend/scanner/graph_builder.py` builds relationships from parsed project data, likely including class-level references, inheritance, and dependencies. `backend/scanner/dependency_parser.py` participates in extracting dependency information for the scanning pipeline. This graph/model output is the key shared substrate for code-quality and debt analysis.

#### Build Dependency Scanner
A separate dependency-analysis subsystem supports Maven and Gradle descriptors: `backend/dependency_scanner/dependency_scanner_service.py`, `backend/dependency_scanner/maven_parser.py`, and `backend/dependency_scanner/gradle_parser.py`. Its models live in `backend/dependency_scanner/models.py`; framework/library recognition is isolated in `backend/dependency_scanner/framework_signatures.py`, and vulnerability-related data in `backend/dependency_scanner/vulnerability_data.py`.

#### Technical-Debt Analysis Engine
`backend/debt_analyzer/debt_engine.py` coordinates rule execution against parsed/scanned project information. Findings use shared types in `backend/debt_analyzer/models.py`, then are normalized or prioritized by `backend/debt_analyzer/scoring.py` and policy thresholds in `backend/debt_analyzer/thresholds.py`.

#### Rule-Based Quality Signals
Individual code-smell rules are modular implementations behind `backend/debt_analyzer/rules/base_rule.py`. Architecturally significant rules cover size, complexity, coupling, inheritance, duplication, and API surface: `long_method.py`, `god_class.py`, `high_coupling.py`, `deep_inheritance.py`, `duplicate_code.py`, `large_class.py`, and `long_parameter_list.py`. This enables new rules without changing the engine’s core orchestration.

#### Inputs, Outputs, and Runtime Boundaries
The system runs as a Python service with dependencies declared in `backend/requirements.txt`. Primary external inputs are Java source trees plus Maven `pom.xml` or Gradle build files. Uploaded projects are stored under `backend/scanner/uploads/`; scan artifacts are written under `backend/scanner/output/`, illustrated by `backend/scanner/output/SampleProject_scan.json`. No database, message broker, cloud runtime, or external vulnerability API integration is evidenced by the tree.

Main entry points: [`backend/scanner/scanner_service.py`](https://github.com/krishnakumarkris/ai-technical-debt-agent/blob/main/backend/scanner/scanner_service.py) (Scanner service), [`backend/debt_analyzer/debt_engine.py`](https://github.com/krishnakumarkris/ai-technical-debt-agent/blob/main/backend/debt_analyzer/debt_engine.py) (Debt engine), [`backend/scanner/project_scanner.py`](https://github.com/krishnakumarkris/ai-technical-debt-agent/blob/main/backend/scanner/project_scanner.py) (Project scanner), [`backend/scanner/models/project_model.py`](https://github.com/krishnakumarkris/ai-technical-debt-agent/blob/main/backend/scanner/models/project_model.py) (Project model)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Service Runtime"]
  node_main["Application entry<br/>Python service<br/>[main.py]"]
end

subgraph group_scan["Project Scanner"]
  node_scan_service["Scanner service<br/>orchestrator<br/>[scanner_service.py]"]
  node_project_scanner["Project scanner<br/>scan pipeline<br/>[project_scanner.py]"]
  node_scan_config["Scan configuration<br/>[config.py]"]
  node_file_traversal["File traversal<br/>file discovery<br/>[file_utils.py]"]
  node_java_parser["Java AST parser<br/>language parser<br/>[java_ast_parser.py]"]
  node_project_model["Project model<br/>domain model<br/>[project_model.py]"]
  node_relationship_graph{{"Relationship graph<br/>analysis graph<br/>[graph_builder.py]"}}
  node_source_dependencies["Source dependency parser<br/>dependency extraction"]
end

subgraph group_dependencies["Build Dependencies"]
  node_build_scanner["Dependency scanner<br/>orchestrator"]
  node_build_parsers["Maven and Gradle parsers<br/>build parsers<br/>[maven_parser.py]"]
  node_dependency_models["Dependency models<br/>domain model<br/>[models.py]"]
end

subgraph group_debt["Debt Analysis"]
  node_debt_engine["Debt engine<br/>rule orchestrator<br/>[debt_engine.py]"]
  node_quality_rules["Quality rules<br/>rule modules<br/>[base_rule.py]"]
  node_findings["Debt findings<br/>findings model<br/>[models.py]"]
  node_scoring["Scoring and thresholds<br/>prioritization<br/>[scoring.py]"]
end

node_java_project["Java project tree<br/>external input"]
node_scan_artifact["Scan artifact<br/>JSON output"]

node_main -->|"invokes"| node_scan_service
node_java_project -->|"submitted project"| node_scan_service
node_scan_service -->|"orchestrates"| node_project_scanner
node_project_scanner -.->|"uses"| node_scan_config
node_project_scanner -->|"discovers files"| node_file_traversal
node_file_traversal -->|"Java files"| node_java_parser
node_java_parser -->|"builds"| node_project_model
node_project_scanner -->|"extracts references"| node_source_dependencies
node_project_model -->|"structural data"| node_relationship_graph
node_source_dependencies -->|"dependencies"| node_relationship_graph
node_java_project -->|"pom.xml / Gradle files"| node_build_scanner
node_build_scanner -->|"selects parser"| node_build_parsers
node_build_parsers -->|"produces"| node_dependency_models
node_scan_service -->|"analyzes scan"| node_debt_engine
node_project_model -->|"project structure"| node_debt_engine
node_relationship_graph -->|"relationships"| node_debt_engine
node_dependency_models -->|"build dependencies"| node_debt_engine
node_debt_engine -->|"executes"| node_quality_rules
node_quality_rules -->|"reports"| node_findings
node_findings -->|"prioritized by"| node_scoring
node_scan_service -->|"writes"| node_scan_artifact

click node_main "https://github.com/krishnakumarkris/ai-technical-debt-agent/blob/main/backend/main.py"
click node_scan_service "https://github.com/krishnakumarkris/ai-technical-debt-agent/blob/main/backend/scanner/scanner_service.py"
click node_project_scanner "https://github.com/krishnakumarkris/ai-technical-debt-agent/blob/main/backend/scanner/project_scanner.py"
click node_scan_config "https://github.com/krishnakumarkris/ai-technical-debt-agent/blob/main/backend/scanner/config.py"
click node_file_traversal "https://github.com/krishnakumarkris/ai-technical-debt-agent/blob/main/backend/scanner/utils/file_utils.py"
click node_java_parser "https://github.com/krishnakumarkris/ai-technical-debt-agent/blob/main/backend/scanner/java_parser/java_ast_parser.py"
click node_project_model "https://github.com/krishnakumarkris/ai-technical-debt-agent/blob/main/backend/scanner/models/project_model.py"
click node_relationship_graph "https://github.com/krishnakumarkris/ai-technical-debt-agent/blob/main/backend/scanner/graph_builder.py"
click node_source_dependencies "https://github.com/krishnakumarkris/ai-technical-debt-agent/blob/main/backend/scanner/dependency_parser.py"
click node_build_scanner "https://github.com/krishnakumarkris/ai-technical-debt-agent/blob/main/backend/dependency_scanner/dependency_scanner_service.py"
click node_build_parsers "https://github.com/krishnakumarkris/ai-technical-debt-agent/blob/main/backend/dependency_scanner/maven_parser.py"
click node_dependency_models "https://github.com/krishnakumarkris/ai-technical-debt-agent/blob/main/backend/dependency_scanner/models.py"
click node_debt_engine "https://github.com/krishnakumarkris/ai-technical-debt-agent/blob/main/backend/debt_analyzer/debt_engine.py"
click node_quality_rules "https://github.com/krishnakumarkris/ai-technical-debt-agent/blob/main/backend/debt_analyzer/rules/base_rule.py"
click node_findings "https://github.com/krishnakumarkris/ai-technical-debt-agent/blob/main/backend/debt_analyzer/models.py"
click node_scoring "https://github.com/krishnakumarkris/ai-technical-debt-agent/blob/main/backend/debt_analyzer/scoring.py"
click node_scan_artifact "https://github.com/krishnakumarkris/ai-technical-debt-agent/blob/main/backend/scanner/output/SampleProject_scan.json"

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_main toneBlue
class node_scan_service,node_project_scanner,node_scan_config,node_file_traversal,node_java_parser,node_project_model,node_relationship_graph,node_source_dependencies toneAmber
class node_build_scanner,node_build_parsers,node_dependency_models toneMint
class node_debt_engine,node_quality_rules,node_findings,node_scoring toneRose
class node_java_project,node_scan_artifact toneNeutral
```

## Components

### Service Runtime

- [Application entry](https://github.com/krishnakumarkris/ai-technical-debt-agent/blob/main/backend/main.py): Python service · `backend/main.py`

### Project Scanner

- [Scanner service](https://github.com/krishnakumarkris/ai-technical-debt-agent/blob/main/backend/scanner/scanner_service.py): orchestrator · `backend/scanner/scanner_service.py`
- [Project scanner](https://github.com/krishnakumarkris/ai-technical-debt-agent/blob/main/backend/scanner/project_scanner.py): scan pipeline · `backend/scanner/project_scanner.py`
- [Scan configuration](https://github.com/krishnakumarkris/ai-technical-debt-agent/blob/main/backend/scanner/config.py): configuration · `backend/scanner/config.py`
- [File traversal](https://github.com/krishnakumarkris/ai-technical-debt-agent/blob/main/backend/scanner/utils/file_utils.py): file discovery · `backend/scanner/utils/file_utils.py`
- [Java AST parser](https://github.com/krishnakumarkris/ai-technical-debt-agent/blob/main/backend/scanner/java_parser/java_ast_parser.py): language parser · `backend/scanner/java_parser/java_ast_parser.py`
- [Project model](https://github.com/krishnakumarkris/ai-technical-debt-agent/blob/main/backend/scanner/models/project_model.py): domain model · Language-neutral boundary for downstream analysis. · `backend/scanner/models/project_model.py`
- [Relationship graph](https://github.com/krishnakumarkris/ai-technical-debt-agent/blob/main/backend/scanner/graph_builder.py): analysis graph · `backend/scanner/graph_builder.py`
- [Source dependency parser](https://github.com/krishnakumarkris/ai-technical-debt-agent/blob/main/backend/scanner/dependency_parser.py): dependency extraction · `backend/scanner/dependency_parser.py`

### Build Dependencies

- [Dependency scanner](https://github.com/krishnakumarkris/ai-technical-debt-agent/blob/main/backend/dependency_scanner/dependency_scanner_service.py): orchestrator · `backend/dependency_scanner/dependency_scanner_service.py`
- [Maven and Gradle parsers](https://github.com/krishnakumarkris/ai-technical-debt-agent/blob/main/backend/dependency_scanner/maven_parser.py): build parsers · `backend/dependency_scanner/maven_parser.py`
- [Dependency models](https://github.com/krishnakumarkris/ai-technical-debt-agent/blob/main/backend/dependency_scanner/models.py): domain model · Includes framework signatures and vulnerability data. · `backend/dependency_scanner/models.py`

### Debt Analysis

- [Debt engine](https://github.com/krishnakumarkris/ai-technical-debt-agent/blob/main/backend/debt_analyzer/debt_engine.py): rule orchestrator · `backend/debt_analyzer/debt_engine.py`
- [Quality rules](https://github.com/krishnakumarkris/ai-technical-debt-agent/blob/main/backend/debt_analyzer/rules/base_rule.py): rule modules · Size, complexity, coupling, inheritance, duplication, and API-surface checks. · `backend/debt_analyzer/rules/base_rule.py`
- [Debt findings](https://github.com/krishnakumarkris/ai-technical-debt-agent/blob/main/backend/debt_analyzer/models.py): findings model · `backend/debt_analyzer/models.py`
- [Scoring and thresholds](https://github.com/krishnakumarkris/ai-technical-debt-agent/blob/main/backend/debt_analyzer/scoring.py): prioritization · `backend/debt_analyzer/scoring.py`

### Other components

- **Java project tree**: external input · Java sources plus Maven or Gradle descriptors.
- [Scan artifact](https://github.com/krishnakumarkris/ai-technical-debt-agent/blob/main/backend/scanner/output/SampleProject_scan.json): JSON output · `backend/scanner/output/SampleProject_scan.json`

## Connections

- Application entry → Scanner service: invokes
- Java project tree → Scanner service: submitted project
- Scanner service → Project scanner: orchestrates
- Project scanner → Scan configuration: uses
- Project scanner → File traversal: discovers files
- File traversal → Java AST parser: Java files
- Java AST parser → Project model: builds
- Project scanner → Source dependency parser: extracts references
- Project model → Relationship graph: structural data
- Source dependency parser → Relationship graph: dependencies
- Java project tree → Dependency scanner: pom.xml / Gradle files
- Dependency scanner → Maven and Gradle parsers: selects parser
- Maven and Gradle parsers → Dependency models: produces
- Scanner service → Debt engine: analyzes scan
- Project model → Debt engine: project structure
- Relationship graph → Debt engine: relationships
- Dependency models → Debt engine: build dependencies
- Debt engine → Quality rules: executes
- Quality rules → Debt findings: reports
- Debt findings → Scoring and thresholds: prioritized by
- Scanner service → Scan artifact: writes