# naveens-prog/entropy architecture

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

- Interactive diagram: https://gitdiagram.com/naveens-prog/entropy
- Repository: https://github.com/naveens-prog/entropy

## Overview

Entropy is a deterministic static analyzer for architectural security debt: it discovers repository files, parses supported languages without executing repository code, produces rule-backed findings, and reports explainable scores. The primary workflow runs through the backend scan and analysis services; the API and dashboard expose results. Additional product branches cover scan comparison and trends, policy evaluation, AI explanations, and GitHub pull-request checks. The source index and excerpts support the central orchestration and persistence links; some unsampled integrations are shown only as unverified.

Main entry points: [`backend/app/services/repository_service.py`](https://github.com/naveens-prog/entropy/blob/main/backend/app/services/repository_service.py) (Repository service), [`backend/app/github/service.py`](https://github.com/naveens-prog/entropy/blob/main/backend/app/github/service.py) (GitHub PR workflow), [`frontend/app/page.tsx`](https://github.com/naveens-prog/entropy/blob/main/frontend/app/page.tsx) (Dashboard), [`backend/app/services/analysis_service.py`](https://github.com/naveens-prog/entropy/blob/main/backend/app/services/analysis_service.py) (Analysis coordinator)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["Scan ingestion"]
  node_scanner["Repository scanner<br/>[scanner.py]"]
  node_repository_service["Repository service"]
  node_parser["Language parsers"]
  node_scan_service["Scan coordinator<br/>[scan_service.py]"]
end

subgraph group_analysis["Static analysis"]
  node_analysis_service["Analysis coordinator"]
  node_analyzer_registry["Analyzer registry<br/>[registry.py]"]
  node_analyzer_families["Debt analyzers"]
  node_domain_findings["Finding models<br/>[finding.py]"]
end

subgraph group_results["Results and policy"]
  node_scoring["Debt scoring<br/>[service.py]"]
  node_policy["Policy evaluation<br/>[service.py]"]
  node_comparison["Scan comparison<br/>[service.py]"]
  node_database[("Scan database<br/>[database.py]")]
end

subgraph group_integrations["Product integrations"]
  node_ai["AI explanations<br/>[service.py]"]
  node_github_workflow["GitHub PR workflow<br/>[service.py]"]
  node_sarif["SARIF output<br/>[formatter.py]"]
end

subgraph group_interface["User interface"]
  node_api["REST API<br/>[router.py]"]
  node_dashboard["Dashboard<br/>[page.tsx]"]
  node_api_client["Typed API client<br/>[api.ts]"]
  node_findings_view["Findings viewer<br/>[FindingsViewer.tsx]"]
  node_score_view["Score dashboard<br/>[ScoreBanner.tsx]"]
  node_comparison_view["Comparison view"]
  node_pr_view["PR workflow view<br/>[PRWorkflowView.tsx]"]
end

node_developer(("Developer"))
node_repository["Code repository"]
node_github(("GitHub"))

node_developer -.->|"reviews results"| node_dashboard
node_repository -.->|"provides source"| node_repository_service
node_api -.->|"routes scans"| node_repository_service
node_repository_service -->|"scans source"| node_scanner
node_repository_service -->|"persists scans"| node_database
node_repository_service -->|"parses files"| node_parser
node_scan_service -.->|"coordinates scans"| node_repository_service
node_analysis_service -->|"loads and saves"| node_repository_service
node_analysis_service -->|"dispatches analyzers"| node_analyzer_registry
node_analyzer_registry -.->|"registers analyzers"| node_analyzer_families
node_analyzer_families -.->|"produces findings"| node_domain_findings
node_scoring -.->|"scores analysis"| node_analysis_service
node_scoring -.->|"scores scans"| node_repository_service
node_policy -->|"evaluates comparisons"| node_comparison
node_policy -.->|"loads policy data"| node_database
node_comparison -->|"reads scan history"| node_database
node_github -.->|"sends PR events"| node_github_workflow
node_github_workflow -->|"acquires and scans source"| node_repository_service
node_github_workflow -->|"analyzes scans"| node_analysis_service
node_github_workflow -->|"compares scans"| node_comparison
node_github_workflow -.->|"tracks PR state"| node_database
node_github_workflow -->|"evaluates policy"| node_policy
node_dashboard -.->|"requests data"| node_api_client
node_api_client -.->|"calls endpoints"| node_api
node_dashboard -.->|"renders findings"| node_findings_view
node_dashboard -.->|"renders scores"| node_score_view
node_dashboard -.->|"renders comparisons"| node_comparison_view
node_dashboard -.->|"renders PR workflow"| node_pr_view
node_ai -.->|"explains analysis"| node_analysis_service
node_developer -.->|"exports results"| node_sarif

click node_api "https://github.com/naveens-prog/entropy/blob/main/backend/app/api/v1/router.py"
click node_dashboard "https://github.com/naveens-prog/entropy/blob/main/frontend/app/page.tsx"
click node_api_client "https://github.com/naveens-prog/entropy/blob/main/frontend/lib/api.ts"
click node_scanner "https://github.com/naveens-prog/entropy/blob/main/backend/app/repository/scanner.py"
click node_repository_service "https://github.com/naveens-prog/entropy/blob/main/backend/app/services/repository_service.py"
click node_parser "https://github.com/naveens-prog/entropy/tree/main/backend/app/parser"
click node_scan_service "https://github.com/naveens-prog/entropy/blob/main/backend/app/services/scan_service.py"
click node_analysis_service "https://github.com/naveens-prog/entropy/blob/main/backend/app/services/analysis_service.py"
click node_analyzer_registry "https://github.com/naveens-prog/entropy/blob/main/backend/app/analyzers/registry.py"
click node_analyzer_families "https://github.com/naveens-prog/entropy/tree/main/backend/app/analyzers"
click node_domain_findings "https://github.com/naveens-prog/entropy/blob/main/backend/app/models/domain/finding.py"
click node_scoring "https://github.com/naveens-prog/entropy/blob/main/backend/app/scoring/service.py"
click node_policy "https://github.com/naveens-prog/entropy/blob/main/backend/app/policy/service.py"
click node_comparison "https://github.com/naveens-prog/entropy/blob/main/backend/app/comparison/service.py"
click node_database "https://github.com/naveens-prog/entropy/blob/main/backend/app/persistence/database.py"
click node_ai "https://github.com/naveens-prog/entropy/blob/main/backend/app/ai/service.py"
click node_github_workflow "https://github.com/naveens-prog/entropy/blob/main/backend/app/github/service.py"
click node_sarif "https://github.com/naveens-prog/entropy/blob/main/backend/app/sarif/formatter.py"
click node_findings_view "https://github.com/naveens-prog/entropy/blob/main/frontend/components/findings/FindingsViewer.tsx"
click node_score_view "https://github.com/naveens-prog/entropy/blob/main/frontend/components/dashboard/ScoreBanner.tsx"
click node_comparison_view "https://github.com/naveens-prog/entropy/blob/main/frontend/components/comparison/ScanComparisonView.tsx"
click node_pr_view "https://github.com/naveens-prog/entropy/blob/main/frontend/components/github/PRWorkflowView.tsx"

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_scanner,node_repository_service,node_parser,node_scan_service toneBlue
class node_analysis_service,node_analyzer_registry,node_analyzer_families,node_domain_findings toneAmber
class node_scoring,node_policy,node_comparison,node_database toneMint
class node_ai,node_github_workflow,node_sarif toneRose
class node_api,node_dashboard,node_api_client,node_findings_view,node_score_view,node_comparison_view,node_pr_view,node_developer,node_repository,node_github toneIndigo
```

## Components

### Scan ingestion

- [Repository scanner](https://github.com/naveens-prog/entropy/blob/main/backend/app/repository/scanner.py): `backend/app/repository/scanner.py`
- [Repository service](https://github.com/naveens-prog/entropy/blob/main/backend/app/services/repository_service.py): `backend/app/services/repository_service.py`
- [Language parsers](https://github.com/naveens-prog/entropy/tree/main/backend/app/parser): `backend/app/parser`
- [Scan coordinator](https://github.com/naveens-prog/entropy/blob/main/backend/app/services/scan_service.py): `backend/app/services/scan_service.py`

### Static analysis

- [Analysis coordinator](https://github.com/naveens-prog/entropy/blob/main/backend/app/services/analysis_service.py): `backend/app/services/analysis_service.py`
- [Analyzer registry](https://github.com/naveens-prog/entropy/blob/main/backend/app/analyzers/registry.py): `backend/app/analyzers/registry.py`
- [Debt analyzers](https://github.com/naveens-prog/entropy/tree/main/backend/app/analyzers): `backend/app/analyzers`
- [Finding models](https://github.com/naveens-prog/entropy/blob/main/backend/app/models/domain/finding.py): `backend/app/models/domain/finding.py`

### Results and policy

- [Debt scoring](https://github.com/naveens-prog/entropy/blob/main/backend/app/scoring/service.py): `backend/app/scoring/service.py`
- [Policy evaluation](https://github.com/naveens-prog/entropy/blob/main/backend/app/policy/service.py): `backend/app/policy/service.py`
- [Scan comparison](https://github.com/naveens-prog/entropy/blob/main/backend/app/comparison/service.py): `backend/app/comparison/service.py`
- [Scan database](https://github.com/naveens-prog/entropy/blob/main/backend/app/persistence/database.py): `backend/app/persistence/database.py`

### Product integrations

- [AI explanations](https://github.com/naveens-prog/entropy/blob/main/backend/app/ai/service.py): `backend/app/ai/service.py`
- [GitHub PR workflow](https://github.com/naveens-prog/entropy/blob/main/backend/app/github/service.py): `backend/app/github/service.py`
- [SARIF output](https://github.com/naveens-prog/entropy/blob/main/backend/app/sarif/formatter.py): `backend/app/sarif/formatter.py`

### User interface

- [REST API](https://github.com/naveens-prog/entropy/blob/main/backend/app/api/v1/router.py): `backend/app/api/v1/router.py`
- [Dashboard](https://github.com/naveens-prog/entropy/blob/main/frontend/app/page.tsx): `frontend/app/page.tsx`
- [Typed API client](https://github.com/naveens-prog/entropy/blob/main/frontend/lib/api.ts): `frontend/lib/api.ts`
- [Findings viewer](https://github.com/naveens-prog/entropy/blob/main/frontend/components/findings/FindingsViewer.tsx): `frontend/components/findings/FindingsViewer.tsx`
- [Score dashboard](https://github.com/naveens-prog/entropy/blob/main/frontend/components/dashboard/ScoreBanner.tsx): `frontend/components/dashboard/ScoreBanner.tsx`
- [Comparison view](https://github.com/naveens-prog/entropy/blob/main/frontend/components/comparison/ScanComparisonView.tsx): `frontend/components/comparison/ScanComparisonView.tsx`
- [PR workflow view](https://github.com/naveens-prog/entropy/blob/main/frontend/components/github/PRWorkflowView.tsx): `frontend/components/github/PRWorkflowView.tsx`

### Other components

- **Developer**
- **Code repository**
- **GitHub**

## Connections

- Developer → Dashboard: reviews results
- Code repository → Repository service: provides source
- REST API → Repository service: routes scans (evidence: `backend/app/api/v1/router.py`)
- Repository service → Repository scanner: scans source (evidence: `backend/app/services/repository_service.py`)
- Repository service → Scan database: persists scans (evidence: `backend/app/services/repository_service.py`)
- Repository service → Language parsers: parses files (evidence: `backend/app/services/repository_service.py`)
- Scan coordinator → Repository service: coordinates scans
- Analysis coordinator → Repository service: loads and saves (evidence: `backend/app/services/analysis_service.py`)
- Analysis coordinator → Analyzer registry: dispatches analyzers (evidence: `backend/app/services/analysis_service.py`)
- Analyzer registry → Debt analyzers: registers analyzers
- Debt analyzers → Finding models: produces findings
- Debt scoring → Analysis coordinator: scores analysis (evidence: `backend/app/scoring/service.py`)
- Debt scoring → Repository service: scores scans (evidence: `backend/app/scoring/service.py`)
- Policy evaluation → Scan comparison: evaluates comparisons (evidence: `backend/app/policy/service.py`)
- Policy evaluation → Scan database: loads policy data (evidence: `backend/app/policy/service.py`)
- Scan comparison → Scan database: reads scan history (evidence: `backend/app/comparison/service.py`)
- GitHub → GitHub PR workflow: sends PR events
- GitHub PR workflow → Repository service: acquires and scans source (evidence: `backend/app/github/service.py`)
- GitHub PR workflow → Analysis coordinator: analyzes scans (evidence: `backend/app/github/service.py`)
- GitHub PR workflow → Scan comparison: compares scans (evidence: `backend/app/github/service.py`)
- GitHub PR workflow → Scan database: tracks PR state (evidence: `backend/app/github/service.py`)
- GitHub PR workflow → Policy evaluation: evaluates policy (evidence: `backend/app/github/service.py`)
- Dashboard → Typed API client: requests data
- Typed API client → REST API: calls endpoints
- Dashboard → Findings viewer: renders findings
- Dashboard → Score dashboard: renders scores
- Dashboard → Comparison view: renders comparisons
- Dashboard → PR workflow view: renders PR workflow
- AI explanations → Analysis coordinator: explains analysis (evidence: `backend/app/ai/service.py`)
- Developer → SARIF output: exports results
