How krishnakumarkris/ai-technical-debt-agent works
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: scanner_service.py Scanner service · debt_engine.py Debt engine · project_scanner.py Project scanner · project_model.py Project model
Components 18
Service Runtime
- Application entry
backend/main.py
Project Scanner
- Scanner service
backend/scanner/scanner_service.py - Project scanner
backend/scanner/project_scanner.py - Scan configuration
backend/scanner/config.py - File traversal
backend/scanner/utils/file_utils.py - Java AST parser
backend/scanner/java_parser/java_ast_parser.py - Project model · Language-neutral boundary for downstream analysis.
backend/scanner/models/project_model.py - Relationship graph
backend/scanner/graph_builder.py - Source dependency parser
backend/scanner/dependency_parser.py
Build Dependencies
- Dependency scanner
backend/dependency_scanner/dependency_scanner_service.py - Maven and Gradle parsers
backend/dependency_scanner/maven_parser.py - Dependency models · Includes framework signatures and vulnerability data.
backend/dependency_scanner/models.py
Debt Analysis
- Debt engine
backend/debt_analyzer/debt_engine.py - Quality rules · Size, complexity, coupling, inheritance, duplication, and API-surface checks.
backend/debt_analyzer/rules/base_rule.py - Debt findings
backend/debt_analyzer/models.py - Scoring and thresholds
backend/debt_analyzer/scoring.py
Other components
- Java project tree · Java sources plus Maven or Gradle descriptors.
- Scan artifact
backend/scanner/output/SampleProject_scan.json
Connections 21
- 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