# alvin20082003/code-doctor architecture

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

- Interactive diagram: https://gitdiagram.com/alvin20082003/code-doctor
- Repository: https://github.com/alvin20082003/code-doctor

## Overview

Code Doctor analyzes Python backend code for complexity, performance, and security issues, then proposes an AI rewrite and checks it before presenting a scored report. The main workflow runs from the React workspace through the FastAPI job pipeline to live progress and results. The graph also preserves report views and the documented behavior check. Source excerpts do not show every API route or the behavior-check implementation, so those relationships are documented from the README rather than inferred from unsampled code.

Main entry points: [`backend/main.py`](https://github.com/alvin20082003/code-doctor/blob/main/backend/main.py) (FastAPI Jobs), [`backend/agents/optimizer.py`](https://github.com/alvin20082003/code-doctor/blob/main/backend/agents/optimizer.py) (Rewrite and Verify), [`frontend/src/App.jsx`](https://github.com/alvin20082003/code-doctor/blob/main/frontend/src/App.jsx) (App State), [`frontend/src/components/ReportPanel.jsx`](https://github.com/alvin20082003/code-doctor/blob/main/frontend/src/components/ReportPanel.jsx) (Report View)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Analysis Workspace"]
  node_app["App State<br/>[App.jsx]"]
  node_landing["Landing<br/>[Landing.jsx]"]
  node_workspace["Workspace<br/>[Workspace.jsx]"]
  node_pipeline_ui["Pipeline View<br/>[PipelinePanel.jsx]"]
  node_report_ui["Report View<br/>[ReportPanel.jsx]"]
  node_complexity_view["Complexity Charts<br/>[ComplexityTab.jsx]"]
  node_finding_views["Finding Tabs<br/>[FindingTabs.jsx]"]
  node_optimizer_view["Optimizer Diff<br/>[OptimizerTab.jsx]"]
end

subgraph group_api["Analysis Service"]
  node_api["FastAPI Jobs<br/>[main.py]"]
end

subgraph group_checks["Analysis and Verification"]
  node_complexity["Complexity Analysis<br/>[complexity.py]"]
  node_performance["Performance Analysis<br/>[performance.py]"]
  node_security["Security Analysis<br/>[security.py]"]
  node_optimizer["Rewrite and Verify<br/>[optimizer.py]"]
  node_validation["Behavior Check<br/>[validation.py]"]
  node_llm["LLM Adapter<br/>[llm.py]"]
end

subgraph group_results["Scoring and Reports"]
  node_scoring["Scale Score and Growth<br/>[scoring.py]"]
end

node_developer(("Developer"))
node_ollama["Ollama"]
node_watsonx["watsonx.ai"]

node_developer -->|"starts analysis"| node_app
node_app -->|"renders"| node_landing
node_app -->|"renders"| node_workspace
node_workspace -->|"renders"| node_pipeline_ui
node_workspace -->|"renders"| node_report_ui
node_app -->|"submits code"| node_api
node_api -->|"streams results"| node_app
node_report_ui -->|"renders"| node_complexity_view
node_report_ui -->|"renders"| node_finding_views
node_report_ui -->|"renders"| node_optimizer_view
node_api -->|"runs analysis"| node_complexity
node_api -->|"runs analysis"| node_performance
node_api -->|"runs analysis"| node_security
node_api -->|"requests rewrite"| node_optimizer
node_optimizer -->|"rechecks rewrite"| node_complexity
node_optimizer -->|"rechecks rewrite"| node_performance
node_optimizer -->|"rechecks rewrite"| node_security
node_optimizer -->|"checks behavior"| node_validation
node_optimizer -->|"requests completion"| node_llm
node_llm -->|"sends prompt"| node_ollama
node_llm -.->|"sends prompt"| node_watsonx
node_api -->|"scores findings"| node_scoring
node_scoring -->|"provides report data"| node_report_ui

click node_app "https://github.com/alvin20082003/code-doctor/blob/main/frontend/src/App.jsx"
click node_landing "https://github.com/alvin20082003/code-doctor/blob/main/frontend/src/components/Landing.jsx"
click node_workspace "https://github.com/alvin20082003/code-doctor/blob/main/frontend/src/components/Workspace.jsx"
click node_pipeline_ui "https://github.com/alvin20082003/code-doctor/blob/main/frontend/src/components/PipelinePanel.jsx"
click node_report_ui "https://github.com/alvin20082003/code-doctor/blob/main/frontend/src/components/ReportPanel.jsx"
click node_complexity_view "https://github.com/alvin20082003/code-doctor/blob/main/frontend/src/components/tabs/ComplexityTab.jsx"
click node_finding_views "https://github.com/alvin20082003/code-doctor/blob/main/frontend/src/components/tabs/FindingTabs.jsx"
click node_optimizer_view "https://github.com/alvin20082003/code-doctor/blob/main/frontend/src/components/tabs/OptimizerTab.jsx"
click node_api "https://github.com/alvin20082003/code-doctor/blob/main/backend/main.py"
click node_complexity "https://github.com/alvin20082003/code-doctor/blob/main/backend/analyzers/complexity.py"
click node_performance "https://github.com/alvin20082003/code-doctor/blob/main/backend/analyzers/performance.py"
click node_security "https://github.com/alvin20082003/code-doctor/blob/main/backend/analyzers/security.py"
click node_optimizer "https://github.com/alvin20082003/code-doctor/blob/main/backend/agents/optimizer.py"
click node_validation "https://github.com/alvin20082003/code-doctor/blob/main/backend/validation.py"
click node_llm "https://github.com/alvin20082003/code-doctor/blob/main/backend/agents/llm.py"
click node_scoring "https://github.com/alvin20082003/code-doctor/blob/main/backend/scoring.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_app,node_landing,node_workspace,node_pipeline_ui,node_report_ui,node_complexity_view,node_finding_views,node_optimizer_view toneBlue
class node_api toneAmber
class node_complexity,node_performance,node_security,node_optimizer,node_validation,node_llm toneMint
class node_scoring toneRose
class node_developer,node_ollama,node_watsonx toneIndigo
```

## Components

### Analysis Workspace

- [App State](https://github.com/alvin20082003/code-doctor/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Landing](https://github.com/alvin20082003/code-doctor/blob/main/frontend/src/components/Landing.jsx): `frontend/src/components/Landing.jsx`
- [Workspace](https://github.com/alvin20082003/code-doctor/blob/main/frontend/src/components/Workspace.jsx): `frontend/src/components/Workspace.jsx`
- [Pipeline View](https://github.com/alvin20082003/code-doctor/blob/main/frontend/src/components/PipelinePanel.jsx): `frontend/src/components/PipelinePanel.jsx`
- [Report View](https://github.com/alvin20082003/code-doctor/blob/main/frontend/src/components/ReportPanel.jsx): `frontend/src/components/ReportPanel.jsx`
- [Complexity Charts](https://github.com/alvin20082003/code-doctor/blob/main/frontend/src/components/tabs/ComplexityTab.jsx): `frontend/src/components/tabs/ComplexityTab.jsx`
- [Finding Tabs](https://github.com/alvin20082003/code-doctor/blob/main/frontend/src/components/tabs/FindingTabs.jsx): `frontend/src/components/tabs/FindingTabs.jsx`
- [Optimizer Diff](https://github.com/alvin20082003/code-doctor/blob/main/frontend/src/components/tabs/OptimizerTab.jsx): `frontend/src/components/tabs/OptimizerTab.jsx`

### Analysis Service

- [FastAPI Jobs](https://github.com/alvin20082003/code-doctor/blob/main/backend/main.py): `backend/main.py`

### Analysis and Verification

- [Complexity Analysis](https://github.com/alvin20082003/code-doctor/blob/main/backend/analyzers/complexity.py): `backend/analyzers/complexity.py`
- [Performance Analysis](https://github.com/alvin20082003/code-doctor/blob/main/backend/analyzers/performance.py): `backend/analyzers/performance.py`
- [Security Analysis](https://github.com/alvin20082003/code-doctor/blob/main/backend/analyzers/security.py): `backend/analyzers/security.py`
- [Rewrite and Verify](https://github.com/alvin20082003/code-doctor/blob/main/backend/agents/optimizer.py): `backend/agents/optimizer.py`
- [Behavior Check](https://github.com/alvin20082003/code-doctor/blob/main/backend/validation.py): `backend/validation.py`
- [LLM Adapter](https://github.com/alvin20082003/code-doctor/blob/main/backend/agents/llm.py): `backend/agents/llm.py`

### Scoring and Reports

- [Scale Score and Growth](https://github.com/alvin20082003/code-doctor/blob/main/backend/scoring.py): `backend/scoring.py`

### Other components

- **Developer**
- **Ollama**
- **watsonx.ai**

## Connections

- Developer → App State: starts analysis (evidence: `frontend/src/App.jsx`)
- App State → Landing: renders (evidence: `frontend/src/App.jsx`)
- App State → Workspace: renders (evidence: `frontend/src/App.jsx`)
- Workspace → Pipeline View: renders (evidence: `frontend/src/components/Workspace.jsx`)
- Workspace → Report View: renders (evidence: `frontend/src/components/Workspace.jsx`)
- App State → FastAPI Jobs: submits code (evidence: `frontend/src/App.jsx`)
- FastAPI Jobs → App State: streams results (evidence: `README.md`)
- Report View → Complexity Charts: renders (evidence: `frontend/src/components/ReportPanel.jsx`)
- Report View → Finding Tabs: renders (evidence: `frontend/src/components/ReportPanel.jsx`)
- Report View → Optimizer Diff: renders (evidence: `frontend/src/components/ReportPanel.jsx`)
- FastAPI Jobs → Complexity Analysis: runs analysis (evidence: `README.md`)
- FastAPI Jobs → Performance Analysis: runs analysis (evidence: `README.md`)
- FastAPI Jobs → Security Analysis: runs analysis (evidence: `README.md`)
- FastAPI Jobs → Rewrite and Verify: requests rewrite (evidence: `backend/main.py`)
- Rewrite and Verify → Complexity Analysis: rechecks rewrite (evidence: `backend/agents/optimizer.py`)
- Rewrite and Verify → Performance Analysis: rechecks rewrite (evidence: `backend/agents/optimizer.py`)
- Rewrite and Verify → Security Analysis: rechecks rewrite (evidence: `backend/agents/optimizer.py`)
- Rewrite and Verify → Behavior Check: checks behavior (evidence: `README.md`)
- Rewrite and Verify → LLM Adapter: requests completion (evidence: `backend/agents/optimizer.py`)
- LLM Adapter → Ollama: sends prompt (evidence: `backend/agents/llm.py`)
- LLM Adapter → watsonx.ai: sends prompt (evidence: `backend/agents/llm.py`)
- FastAPI Jobs → Scale Score and Growth: scores findings (evidence: `backend/main.py`)
- Scale Score and Growth → Report View: provides report data (evidence: `README.md`)
