# mertkocakaplan/qualiguard architecture

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

- Interactive diagram: https://gitdiagram.com/mertkocakaplan/qualiguard
- Repository: https://github.com/mertkocakaplan/qualiguard

## Overview

QualiGuard is a Flask service for per-file defect and code-smell risk prediction, with PASS/REVIEW/BLOCK quality-gate results and project health indicators. Its interactive workflow accepts a GitHub repository or a ZIP containing .git, analyzes files and history, then serves predictions. A separate offline workflow discovers and processes GitHub projects to build training data and models. The graph combines excerpts, SOURCE INDEX references, and README-documented capabilities; unsampled subsystems are represented only where the README supports them.

Main entry points: [`app/analyzer.py`](https://github.com/mertkocakaplan/qualiguard/blob/master/app/analyzer.py) (Repository Analysis), [`pipeline/project_processor.py`](https://github.com/mertkocakaplan/qualiguard/blob/master/pipeline/project_processor.py) (Project Processing), [`scripts/train_final.py`](https://github.com/mertkocakaplan/qualiguard/blob/master/scripts/train_final.py) (Model Training), [`pipeline/dataset_builder.py`](https://github.com/mertkocakaplan/qualiguard/blob/master/pipeline/dataset_builder.py) (Dataset Builder)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_serving["Web Analysis"]
  node_routes["Web Routes<br/>[routes.py]"]
  node_analysis["Repository Analysis<br/>[analyzer.py]"]
  node_zip["ZIP Handling<br/>[zip_handler.py]"]
  node_predictor["Risk Predictor<br/>[predictor.py]"]
  node_health["Project Health<br/>[health.py]"]
end

subgraph group_acquisition["Repository Acquisition"]
  node_discovery["GitHub Discovery<br/>[discovery.py]"]
  node_clone["Repository Cloning<br/>[cloning.py]"]
  node_rate["API Rate Guard<br/>[rate_limit.py]"]
end

subgraph group_extraction["Metric Extraction"]
  node_processor["Project Processing"]
  node_git["Git History Metrics<br/>[git_metrics.py]"]
  node_static["Static Metrics<br/>[static_metrics.py]"]
  node_smells["AST Smell Detection<br/>[code_smells.py]"]
  node_szz["SZZ Labels<br/>[szz.py]"]
  node_cicd["CI/CD Signals<br/>[ci_cd.py]"]
end

subgraph group_modeling["Dataset and Models"]
  node_dataset["Dataset Builder<br/>[dataset_builder.py]"]
  node_categories["Project Categories<br/>[categories.py]"]
  node_training["Model Training<br/>[train_final.py]"]
  node_modelutils["Model Utilities<br/>[model_utils.py]"]
  node_stats["Project Statistics<br/>[project_stats.py]"]
  node_config["Shared Configuration<br/>[config.py]"]
end

node_user(("User"))
node_github{{"GitHub"}}

node_user -->|"submits analysis"| node_routes
node_routes -->|"starts analysis"| node_analysis
node_analysis -->|"validates upload"| node_zip
node_analysis -->|"clones repository"| node_clone
node_analysis -->|"reads history"| node_git
node_analysis -->|"extracts metrics"| node_static
node_analysis -->|"detects smells"| node_smells
node_analysis -->|"requests predictions"| node_predictor
node_analysis -->|"computes health"| node_health
node_predictor -->|"loads settings"| node_config
node_discovery -->|"searches projects"| node_github
node_discovery -->|"guards API calls"| node_rate
node_user -.->|"selects repository"| node_github
node_training -->|"uses modeling utilities"| node_modelutils
node_training -->|"uses project statistics"| node_stats
node_training -->|"loads settings"| node_config
node_dataset -->|"assigns categories"| node_categories
node_dataset -->|"adds CI signals"| node_cicd
node_processor -->|"clones project"| node_clone
node_processor -->|"collects history metrics"| node_git
node_processor -->|"calculates static metrics"| node_static
node_processor -->|"collects smell data"| node_smells
node_processor -->|"derives defect labels"| node_szz
node_processor -->|"collects CI signals"| node_cicd
node_discovery -.->|"hands off projects"| node_processor
node_processor -.->|"builds project data"| node_dataset
node_dataset -.->|"provides training data"| node_training
node_training -->|"produces serving models"| node_predictor

click node_routes "https://github.com/mertkocakaplan/qualiguard/blob/master/app/routes.py"
click node_analysis "https://github.com/mertkocakaplan/qualiguard/blob/master/app/analyzer.py"
click node_zip "https://github.com/mertkocakaplan/qualiguard/blob/master/pipeline/zip_handler.py"
click node_predictor "https://github.com/mertkocakaplan/qualiguard/blob/master/app/predictor.py"
click node_health "https://github.com/mertkocakaplan/qualiguard/blob/master/app/health.py"
click node_discovery "https://github.com/mertkocakaplan/qualiguard/blob/master/pipeline/discovery.py"
click node_clone "https://github.com/mertkocakaplan/qualiguard/blob/master/pipeline/cloning.py"
click node_rate "https://github.com/mertkocakaplan/qualiguard/blob/master/pipeline/rate_limit.py"
click node_processor "https://github.com/mertkocakaplan/qualiguard/blob/master/pipeline/project_processor.py"
click node_git "https://github.com/mertkocakaplan/qualiguard/blob/master/pipeline/git_metrics.py"
click node_static "https://github.com/mertkocakaplan/qualiguard/blob/master/pipeline/static_metrics.py"
click node_smells "https://github.com/mertkocakaplan/qualiguard/blob/master/pipeline/code_smells.py"
click node_szz "https://github.com/mertkocakaplan/qualiguard/blob/master/pipeline/szz.py"
click node_cicd "https://github.com/mertkocakaplan/qualiguard/blob/master/pipeline/ci_cd.py"
click node_dataset "https://github.com/mertkocakaplan/qualiguard/blob/master/pipeline/dataset_builder.py"
click node_categories "https://github.com/mertkocakaplan/qualiguard/blob/master/pipeline/categories.py"
click node_training "https://github.com/mertkocakaplan/qualiguard/blob/master/scripts/train_final.py"
click node_modelutils "https://github.com/mertkocakaplan/qualiguard/blob/master/pipeline/model_utils.py"
click node_stats "https://github.com/mertkocakaplan/qualiguard/blob/master/pipeline/project_stats.py"
click node_config "https://github.com/mertkocakaplan/qualiguard/blob/master/pipeline/config.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_routes,node_analysis,node_zip,node_predictor,node_health,node_user toneBlue
class node_discovery,node_clone,node_rate toneAmber
class node_processor,node_git,node_static,node_smells,node_szz,node_cicd toneMint
class node_dataset,node_categories,node_training,node_modelutils,node_stats,node_config toneRose
class node_github toneIndigo
```

## Components

### Web Analysis

- [Web Routes](https://github.com/mertkocakaplan/qualiguard/blob/master/app/routes.py): `app/routes.py`
- [Repository Analysis](https://github.com/mertkocakaplan/qualiguard/blob/master/app/analyzer.py): `app/analyzer.py`
- [ZIP Handling](https://github.com/mertkocakaplan/qualiguard/blob/master/pipeline/zip_handler.py): `pipeline/zip_handler.py`
- [Risk Predictor](https://github.com/mertkocakaplan/qualiguard/blob/master/app/predictor.py): `app/predictor.py`
- [Project Health](https://github.com/mertkocakaplan/qualiguard/blob/master/app/health.py): `app/health.py`

### Repository Acquisition

- [GitHub Discovery](https://github.com/mertkocakaplan/qualiguard/blob/master/pipeline/discovery.py): `pipeline/discovery.py`
- [Repository Cloning](https://github.com/mertkocakaplan/qualiguard/blob/master/pipeline/cloning.py): `pipeline/cloning.py`
- [API Rate Guard](https://github.com/mertkocakaplan/qualiguard/blob/master/pipeline/rate_limit.py): `pipeline/rate_limit.py`

### Metric Extraction

- [Project Processing](https://github.com/mertkocakaplan/qualiguard/blob/master/pipeline/project_processor.py): `pipeline/project_processor.py`
- [Git History Metrics](https://github.com/mertkocakaplan/qualiguard/blob/master/pipeline/git_metrics.py): `pipeline/git_metrics.py`
- [Static Metrics](https://github.com/mertkocakaplan/qualiguard/blob/master/pipeline/static_metrics.py): `pipeline/static_metrics.py`
- [AST Smell Detection](https://github.com/mertkocakaplan/qualiguard/blob/master/pipeline/code_smells.py): `pipeline/code_smells.py`
- [SZZ Labels](https://github.com/mertkocakaplan/qualiguard/blob/master/pipeline/szz.py): `pipeline/szz.py`
- [CI/CD Signals](https://github.com/mertkocakaplan/qualiguard/blob/master/pipeline/ci_cd.py): `pipeline/ci_cd.py`

### Dataset and Models

- [Dataset Builder](https://github.com/mertkocakaplan/qualiguard/blob/master/pipeline/dataset_builder.py): `pipeline/dataset_builder.py`
- [Project Categories](https://github.com/mertkocakaplan/qualiguard/blob/master/pipeline/categories.py): `pipeline/categories.py`
- [Model Training](https://github.com/mertkocakaplan/qualiguard/blob/master/scripts/train_final.py): `scripts/train_final.py`
- [Model Utilities](https://github.com/mertkocakaplan/qualiguard/blob/master/pipeline/model_utils.py): `pipeline/model_utils.py`
- [Project Statistics](https://github.com/mertkocakaplan/qualiguard/blob/master/pipeline/project_stats.py): `pipeline/project_stats.py`
- [Shared Configuration](https://github.com/mertkocakaplan/qualiguard/blob/master/pipeline/config.py): `pipeline/config.py`

### Other components

- **User**
- **GitHub**

## Connections

- User → Web Routes: submits analysis
- Web Routes → Repository Analysis: starts analysis (evidence: `app/routes.py`)
- Repository Analysis → ZIP Handling: validates upload (evidence: `app/analyzer.py`)
- Repository Analysis → Repository Cloning: clones repository (evidence: `app/analyzer.py`)
- Repository Analysis → Git History Metrics: reads history (evidence: `app/analyzer.py`)
- Repository Analysis → Static Metrics: extracts metrics (evidence: `app/analyzer.py`)
- Repository Analysis → AST Smell Detection: detects smells (evidence: `app/analyzer.py`)
- Repository Analysis → Risk Predictor: requests predictions (evidence: `app/analyzer.py`)
- Repository Analysis → Project Health: computes health (evidence: `app/analyzer.py`)
- Risk Predictor → Shared Configuration: loads settings (evidence: `app/predictor.py`)
- GitHub Discovery → GitHub: searches projects (evidence: `pipeline/discovery.py`)
- GitHub Discovery → API Rate Guard: guards API calls (evidence: `pipeline/discovery.py`)
- User → GitHub: selects repository
- Model Training → Model Utilities: uses modeling utilities (evidence: `scripts/train_final.py`)
- Model Training → Project Statistics: uses project statistics (evidence: `scripts/train_final.py`)
- Model Training → Shared Configuration: loads settings (evidence: `scripts/train_final.py`)
- Dataset Builder → Project Categories: assigns categories (evidence: `pipeline/dataset_builder.py`)
- Dataset Builder → CI/CD Signals: adds CI signals (evidence: `pipeline/dataset_builder.py`)
- Project Processing → Repository Cloning: clones project (evidence: `pipeline/project_processor.py`)
- Project Processing → Git History Metrics: collects history metrics (evidence: `pipeline/project_processor.py`)
- Project Processing → Static Metrics: calculates static metrics (evidence: `pipeline/project_processor.py`)
- Project Processing → AST Smell Detection: collects smell data (evidence: `pipeline/project_processor.py`)
- Project Processing → SZZ Labels: derives defect labels (evidence: `pipeline/project_processor.py`)
- Project Processing → CI/CD Signals: collects CI signals (evidence: `pipeline/project_processor.py`)
- GitHub Discovery → Project Processing: hands off projects
- Project Processing → Dataset Builder: builds project data
- Dataset Builder → Model Training: provides training data
- Model Training → Risk Predictor: produces serving models (evidence: `scripts/train_final.py`)