# marvinlerouge/portfolio-engineering-radar architecture

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

- Interactive diagram: https://gitdiagram.com/marvinlerouge/portfolio-engineering-radar
- Repository: https://github.com/marvinlerouge/portfolio-engineering-radar

## Overview

Portfolio Engineering Radar combines a local audit engine, a shared evidence-and-scoring data model, an API, and a dashboard. The primary workflow is to select a local repository, discover applicable subprojects and run analysis tools, normalize their results into findings and scores, then expose repository reports, findings, and roadmap data through the API for dashboard review. The README also describes portfolio comparison, historical tracking, and AI-assisted prioritization as intended capabilities; these are not all implemented in the sampled runtime. Connections below are limited to relationships shown by excerpts, SOURCE INDEX references, or the README.

Main entry points: [`radar-audit/src/radar_audit/orchestrator.py`](https://github.com/marvinlerouge/portfolio-engineering-radar/blob/main/radar-audit/src/radar_audit/orchestrator.py) (Audit orchestration), [`radar-api/src/radar_api/main.py`](https://github.com/marvinlerouge/portfolio-engineering-radar/blob/main/radar-api/src/radar_api/main.py) (FastAPI application), [`radar-api/src/radar_api/routers/repositories.py`](https://github.com/marvinlerouge/portfolio-engineering-radar/blob/main/radar-api/src/radar_api/routers/repositories.py) (Repository reports), [`radar-audit/src/radar_audit/cli.py`](https://github.com/marvinlerouge/portfolio-engineering-radar/blob/main/radar-audit/src/radar_audit/cli.py) (Audit CLI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_audit["Repository audits"]
  node_cli["Audit CLI<br/>[cli.py]"]
  node_discovery["Subproject discovery<br/>[discovery.py]"]
  node_orchestrator["Audit orchestration<br/>[orchestrator.py]"]
  node_tool_runners["Analysis tool runners"]
  node_runner_contract["Runner contract<br/>[runner.py]"]
end

subgraph group_assessment["Quality assessment"]
  node_taxonomy["Versioned taxonomy<br/>[seed.py]"]
  node_normalizers["Evidence normalizers"]
  node_scoring["Scoring engine"]
  node_reports["Audit reporting"]
end

subgraph group_persistence["Shared data model"]
  node_db[("Local database<br/>[db.py]")]
  node_repository_model["Repository records<br/>[repository.py]"]
  node_audit_model["Audit results<br/>[audit.py]"]
  node_methodology_model["Methodology records<br/>[methodology.py]"]
  node_finding_model["Findings and evidence<br/>[finding.py]"]
  node_scoring_model["Scores and snapshots<br/>[scoring.py]"]
  node_roadmap_model["Roadmap records<br/>[roadmap.py]"]
end

subgraph group_api["API services"]
  node_api["FastAPI application<br/>[main.py]"]
  node_api_auth["API key authentication<br/>[auth.py]"]
  node_repository_routes["Repository reports<br/>[repositories.py]"]
  node_finding_routes["Finding endpoints<br/>[findings.py]"]
  node_roadmap_routes["Roadmap endpoints<br/>[roadmap.py]"]
end

subgraph group_dashboard["Local dashboard"]
  node_dashboard_app["Dashboard shell<br/>[App.vue]"]
  node_api_client["API client<br/>[client.ts]"]
  node_repository_store["Repository state<br/>[repositories.ts]"]
  node_repository_views["Repository views"]
  node_finding_views["Finding components"]
  node_roadmap_view["Roadmap view<br/>[RoadmapItemRow.vue]"]
end

node_developer(("Engineer"))
node_local_repos["Local repositories"]

node_developer -->|"starts audit"| node_cli
node_local_repos -->|"provides paths"| node_cli
node_cli -->|"invokes"| node_orchestrator
node_orchestrator -->|"discovers projects"| node_discovery
node_orchestrator -->|"runs tools"| node_tool_runners
node_tool_runners -->|"implements"| node_runner_contract
node_orchestrator -->|"seeds methodology"| node_taxonomy
node_cli -->|"opens database"| node_db
node_orchestrator -->|"resolves repository"| node_repository_model
node_orchestrator -->|"records audit results"| node_audit_model
node_orchestrator -->|"seeds taxonomy"| node_methodology_model
node_orchestrator -.->|"normalizes evidence"| node_normalizers
node_normalizers -->|"creates findings"| node_finding_model
node_normalizers -->|"creates scores"| node_scoring_model
node_scoring -->|"uses normalization helpers"| node_normalizers
node_cli -->|"renders reports"| node_reports
node_developer -->|"reviews portfolio"| node_dashboard_app
node_dashboard_app -->|"uses client"| node_api_client
node_repository_store -.->|"requests data"| node_api_client
node_repository_views -->|"uses state"| node_repository_store
node_repository_views -.->|"renders findings"| node_finding_views
node_roadmap_view -.->|"requests roadmap"| node_api_client
node_api_client -.->|"calls API"| node_api
node_api -->|"registers routes"| node_repository_routes
node_api -->|"registers routes"| node_finding_routes
node_api -->|"registers routes"| node_roadmap_routes
node_repository_routes -.->|"requires key"| node_api_auth
node_finding_routes -->|"requires key"| node_api_auth
node_roadmap_routes -->|"requires key"| node_api_auth
node_repository_routes -->|"reads repositories"| node_repository_model
node_repository_routes -->|"reads scores"| node_scoring_model
node_repository_routes -->|"reads findings"| node_finding_model
node_finding_routes -->|"uses findings"| node_finding_model
node_roadmap_routes -->|"uses roadmap"| node_roadmap_model
node_api -->|"provides sessions"| node_db
node_developer -->|"maintains code"| node_local_repos
node_orchestrator -->|"stores audit context"| node_repository_model
node_scoring -.->|"persists assessment"| node_scoring_model

click node_cli "https://github.com/marvinlerouge/portfolio-engineering-radar/blob/main/radar-audit/src/radar_audit/cli.py"
click node_discovery "https://github.com/marvinlerouge/portfolio-engineering-radar/blob/main/radar-audit/src/radar_audit/discovery.py"
click node_orchestrator "https://github.com/marvinlerouge/portfolio-engineering-radar/blob/main/radar-audit/src/radar_audit/orchestrator.py"
click node_tool_runners "https://github.com/marvinlerouge/portfolio-engineering-radar/tree/main/radar-audit/src/radar_audit/runners"
click node_runner_contract "https://github.com/marvinlerouge/portfolio-engineering-radar/blob/main/radar-audit/src/radar_audit/runner.py"
click node_taxonomy "https://github.com/marvinlerouge/portfolio-engineering-radar/blob/main/radar-audit/src/radar_audit/taxonomy/seed.py"
click node_db "https://github.com/marvinlerouge/portfolio-engineering-radar/blob/main/radar-core/src/radar_core/db.py"
click node_repository_model "https://github.com/marvinlerouge/portfolio-engineering-radar/blob/main/radar-core/src/radar_core/models/repository.py"
click node_audit_model "https://github.com/marvinlerouge/portfolio-engineering-radar/blob/main/radar-core/src/radar_core/models/audit.py"
click node_methodology_model "https://github.com/marvinlerouge/portfolio-engineering-radar/blob/main/radar-core/src/radar_core/models/methodology.py"
click node_finding_model "https://github.com/marvinlerouge/portfolio-engineering-radar/blob/main/radar-core/src/radar_core/models/finding.py"
click node_scoring_model "https://github.com/marvinlerouge/portfolio-engineering-radar/blob/main/radar-core/src/radar_core/models/scoring.py"
click node_roadmap_model "https://github.com/marvinlerouge/portfolio-engineering-radar/blob/main/radar-core/src/radar_core/models/roadmap.py"
click node_api "https://github.com/marvinlerouge/portfolio-engineering-radar/blob/main/radar-api/src/radar_api/main.py"
click node_api_auth "https://github.com/marvinlerouge/portfolio-engineering-radar/blob/main/radar-api/src/radar_api/auth.py"
click node_repository_routes "https://github.com/marvinlerouge/portfolio-engineering-radar/blob/main/radar-api/src/radar_api/routers/repositories.py"
click node_finding_routes "https://github.com/marvinlerouge/portfolio-engineering-radar/blob/main/radar-api/src/radar_api/routers/findings.py"
click node_roadmap_routes "https://github.com/marvinlerouge/portfolio-engineering-radar/blob/main/radar-api/src/radar_api/routers/roadmap.py"
click node_dashboard_app "https://github.com/marvinlerouge/portfolio-engineering-radar/blob/main/radar-dashboard/src/App.vue"
click node_api_client "https://github.com/marvinlerouge/portfolio-engineering-radar/blob/main/radar-dashboard/src/api/client.ts"
click node_repository_store "https://github.com/marvinlerouge/portfolio-engineering-radar/blob/main/radar-dashboard/src/stores/repositories.ts"
click node_repository_views "https://github.com/marvinlerouge/portfolio-engineering-radar/tree/main/radar-dashboard/src/views"
click node_finding_views "https://github.com/marvinlerouge/portfolio-engineering-radar/tree/main/radar-dashboard/src/components"
click node_roadmap_view "https://github.com/marvinlerouge/portfolio-engineering-radar/blob/main/radar-dashboard/src/components/RoadmapItemRow.vue"

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_cli,node_discovery,node_orchestrator,node_tool_runners,node_runner_contract toneBlue
class node_taxonomy,node_normalizers,node_scoring,node_reports toneAmber
class node_db,node_repository_model,node_audit_model,node_methodology_model,node_finding_model,node_scoring_model,node_roadmap_model toneMint
class node_api,node_api_auth,node_repository_routes,node_finding_routes,node_roadmap_routes toneRose
class node_dashboard_app,node_api_client,node_repository_store,node_repository_views,node_finding_views,node_roadmap_view,node_developer,node_local_repos toneIndigo
```

## Components

### Repository audits

- [Audit CLI](https://github.com/marvinlerouge/portfolio-engineering-radar/blob/main/radar-audit/src/radar_audit/cli.py): `radar-audit/src/radar_audit/cli.py`
- [Subproject discovery](https://github.com/marvinlerouge/portfolio-engineering-radar/blob/main/radar-audit/src/radar_audit/discovery.py): `radar-audit/src/radar_audit/discovery.py`
- [Audit orchestration](https://github.com/marvinlerouge/portfolio-engineering-radar/blob/main/radar-audit/src/radar_audit/orchestrator.py): `radar-audit/src/radar_audit/orchestrator.py`
- [Analysis tool runners](https://github.com/marvinlerouge/portfolio-engineering-radar/tree/main/radar-audit/src/radar_audit/runners): `radar-audit/src/radar_audit/runners`
- [Runner contract](https://github.com/marvinlerouge/portfolio-engineering-radar/blob/main/radar-audit/src/radar_audit/runner.py): `radar-audit/src/radar_audit/runner.py`

### Quality assessment

- [Versioned taxonomy](https://github.com/marvinlerouge/portfolio-engineering-radar/blob/main/radar-audit/src/radar_audit/taxonomy/seed.py): `radar-audit/src/radar_audit/taxonomy/seed.py`
- **Evidence normalizers**
- **Scoring engine**
- **Audit reporting**

### Shared data model

- [Local database](https://github.com/marvinlerouge/portfolio-engineering-radar/blob/main/radar-core/src/radar_core/db.py): `radar-core/src/radar_core/db.py`
- [Repository records](https://github.com/marvinlerouge/portfolio-engineering-radar/blob/main/radar-core/src/radar_core/models/repository.py): `radar-core/src/radar_core/models/repository.py`
- [Audit results](https://github.com/marvinlerouge/portfolio-engineering-radar/blob/main/radar-core/src/radar_core/models/audit.py): `radar-core/src/radar_core/models/audit.py`
- [Methodology records](https://github.com/marvinlerouge/portfolio-engineering-radar/blob/main/radar-core/src/radar_core/models/methodology.py): `radar-core/src/radar_core/models/methodology.py`
- [Findings and evidence](https://github.com/marvinlerouge/portfolio-engineering-radar/blob/main/radar-core/src/radar_core/models/finding.py): `radar-core/src/radar_core/models/finding.py`
- [Scores and snapshots](https://github.com/marvinlerouge/portfolio-engineering-radar/blob/main/radar-core/src/radar_core/models/scoring.py): `radar-core/src/radar_core/models/scoring.py`
- [Roadmap records](https://github.com/marvinlerouge/portfolio-engineering-radar/blob/main/radar-core/src/radar_core/models/roadmap.py): `radar-core/src/radar_core/models/roadmap.py`

### API services

- [FastAPI application](https://github.com/marvinlerouge/portfolio-engineering-radar/blob/main/radar-api/src/radar_api/main.py): `radar-api/src/radar_api/main.py`
- [API key authentication](https://github.com/marvinlerouge/portfolio-engineering-radar/blob/main/radar-api/src/radar_api/auth.py): `radar-api/src/radar_api/auth.py`
- [Repository reports](https://github.com/marvinlerouge/portfolio-engineering-radar/blob/main/radar-api/src/radar_api/routers/repositories.py): `radar-api/src/radar_api/routers/repositories.py`
- [Finding endpoints](https://github.com/marvinlerouge/portfolio-engineering-radar/blob/main/radar-api/src/radar_api/routers/findings.py): `radar-api/src/radar_api/routers/findings.py`
- [Roadmap endpoints](https://github.com/marvinlerouge/portfolio-engineering-radar/blob/main/radar-api/src/radar_api/routers/roadmap.py): `radar-api/src/radar_api/routers/roadmap.py`

### Local dashboard

- [Dashboard shell](https://github.com/marvinlerouge/portfolio-engineering-radar/blob/main/radar-dashboard/src/App.vue): `radar-dashboard/src/App.vue`
- [API client](https://github.com/marvinlerouge/portfolio-engineering-radar/blob/main/radar-dashboard/src/api/client.ts): `radar-dashboard/src/api/client.ts`
- [Repository state](https://github.com/marvinlerouge/portfolio-engineering-radar/blob/main/radar-dashboard/src/stores/repositories.ts): `radar-dashboard/src/stores/repositories.ts`
- [Repository views](https://github.com/marvinlerouge/portfolio-engineering-radar/tree/main/radar-dashboard/src/views): `radar-dashboard/src/views`
- [Finding components](https://github.com/marvinlerouge/portfolio-engineering-radar/tree/main/radar-dashboard/src/components): `radar-dashboard/src/components`
- [Roadmap view](https://github.com/marvinlerouge/portfolio-engineering-radar/blob/main/radar-dashboard/src/components/RoadmapItemRow.vue): `radar-dashboard/src/components/RoadmapItemRow.vue`

### Other components

- **Engineer**
- **Local repositories**

## Connections

- Engineer → Audit CLI: starts audit (evidence: `README.md`)
- Local repositories → Audit CLI: provides paths (evidence: `README.md`)
- Audit CLI → Audit orchestration: invokes (evidence: `radar-audit/src/radar_audit/cli.py`)
- Audit orchestration → Subproject discovery: discovers projects (evidence: `radar-audit/src/radar_audit/orchestrator.py`)
- Audit orchestration → Analysis tool runners: runs tools (evidence: `radar-audit/src/radar_audit/orchestrator.py`)
- Analysis tool runners → Runner contract: implements (evidence: `radar-audit/src/radar_audit/runners/pnpm_audit_runner.py`)
- Audit orchestration → Versioned taxonomy: seeds methodology (evidence: `radar-audit/src/radar_audit/orchestrator.py`)
- Audit CLI → Local database: opens database (evidence: `radar-audit/src/radar_audit/cli.py`)
- Audit orchestration → Repository records: resolves repository (evidence: `radar-audit/src/radar_audit/orchestrator.py`)
- Audit orchestration → Audit results: records audit results (evidence: `radar-audit/src/radar_audit/orchestrator.py`)
- Audit orchestration → Methodology records: seeds taxonomy
- Audit orchestration → Evidence normalizers: normalizes evidence
- Evidence normalizers → Findings and evidence: creates findings
- Evidence normalizers → Scores and snapshots: creates scores
- Scoring engine → Evidence normalizers: uses normalization helpers
- Audit CLI → Audit reporting: renders reports
- Engineer → Dashboard shell: reviews portfolio (evidence: `README.md`)
- Dashboard shell → API client: uses client
- Repository state → API client: requests data
- Repository views → Repository state: uses state (evidence: `radar-dashboard/src/views/RepositoryListView.vue`)
- Repository views → Finding components: renders findings
- Roadmap view → API client: requests roadmap
- API client → FastAPI application: calls API
- FastAPI application → Repository reports: registers routes (evidence: `radar-api/src/radar_api/main.py`)
- FastAPI application → Finding endpoints: registers routes (evidence: `radar-api/src/radar_api/main.py`)
- FastAPI application → Roadmap endpoints: registers routes (evidence: `radar-api/src/radar_api/main.py`)
- Repository reports → API key authentication: requires key
- Finding endpoints → API key authentication: requires key (evidence: `radar-api/src/radar_api/routers/findings.py`)
- Roadmap endpoints → API key authentication: requires key (evidence: `radar-api/src/radar_api/routers/roadmap.py`)
- Repository reports → Repository records: reads repositories (evidence: `radar-api/src/radar_api/routers/repositories.py`)
- Repository reports → Scores and snapshots: reads scores (evidence: `radar-api/src/radar_api/routers/repositories.py`)
- Repository reports → Findings and evidence: reads findings (evidence: `radar-api/src/radar_api/routers/repositories.py`)
- Finding endpoints → Findings and evidence: uses findings (evidence: `radar-api/src/radar_api/routers/findings.py`)
- Roadmap endpoints → Roadmap records: uses roadmap (evidence: `radar-api/src/radar_api/routers/roadmap.py`)
- FastAPI application → Local database: provides sessions
- Engineer → Local repositories: maintains code (evidence: `README.md`)
- Audit orchestration → Repository records: stores audit context (evidence: `radar-audit/src/radar_audit/orchestrator.py`)
- Scoring engine → Scores and snapshots: persists assessment
