# vovanbl411/gentoo-update-intelligence architecture

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

- Interactive diagram: https://gitdiagram.com/vovanbl411/gentoo-update-intelligence
- Repository: https://github.com/vovanbl411/gentoo-update-intelligence

## Overview

Gentoo Update Intelligence accepts an emerge plan and returns a persisted, evidence-bearing package-change report; it does not install or update packages. The main workflow is HTTP submission, background parsing and rule analysis, pinned Gentoo metadata lookup or preparation, comparison, and report retrieval in the frontend. The graph also preserves the CLI and the metadata-worker path. Some internal wiring is documented rather than shown in excerpts, so those relationships cite the README; unsampled implementation details are not inferred.

Main entry points: [`frontend/src/main.ts`](https://github.com/vovanbl411/gentoo-update-intelligence/blob/main/frontend/src/main.ts) (Web interface), [`backend/cmd/gentoo-update-intelligence-server/main.go`](https://github.com/vovanbl411/gentoo-update-intelligence/blob/main/backend/cmd/gentoo-update-intelligence-server/main.go) (HTTP server), [`backend/internal/planservice/planservice.go`](https://github.com/vovanbl411/gentoo-update-intelligence/blob/main/backend/internal/planservice/planservice.go) (Plan coordinator), [`backend/internal/analysishttp/handler.go`](https://github.com/vovanbl411/gentoo-update-intelligence/blob/main/backend/internal/analysishttp/handler.go) (Analysis API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry points"]
  node_server["HTTP server<br/>[main.go]"]
  node_cli["Analysis CLI<br/>[run.go]"]
  node_config["Backend config<br/>[config.go]"]
end

subgraph group_analysis["Plan analysis"]
  node_parser["Plan parser<br/>[parser.go]"]
  node_analyzer["Rule analyzer<br/>[analyzer.go]"]
  node_planservice["Plan coordinator<br/>[planservice.go]"]
  node_reportservice["Entry reports<br/>[reportservice.go]"]
  node_changereport["Change report<br/>[changereport.go]"]
  node_metadatadiff["Metadata diff<br/>[compare.go]"]
end

subgraph group_metadata["Metadata acquisition"]
  node_repo["Repository pinning<br/>[manager.go]"]
  node_provider["Metadata provider<br/>[provider.go]"]
  node_cache[("Metadata cache<br/>[store.go]")]
  node_resolver["Ebuild resolver<br/>[resolver.go]"]
  node_worker["Metadata worker<br/>[main.go]"]
  node_generator["Cache generator<br/>[generator.go]"]
end

subgraph group_delivery["Reports and UI"]
  node_http["Analysis API<br/>[handler.go]"]
  node_store[("Job storage<br/>[postgres.go]")]
  node_frontend["Web interface<br/>[main.ts]"]
  node_api["HTTP client<br/>[api.ts]"]
  node_model["Response model<br/>[model.ts]"]
  node_render["Report renderer<br/>[report.ts]"]
  node_api_types["API types<br/>[api-types.ts]"]
end

node_user(("Plan author"))
node_browser(("Report reader"))

node_user -->|"submits plan"| node_frontend
node_frontend -->|"calls"| node_api
node_api -->|"HTTP requests"| node_http
node_server -->|"serves"| node_http
node_server -->|"opens"| node_store
node_http -->|"persists jobs"| node_store
node_http -->|"dispatches analysis"| node_planservice
node_planservice -->|"parses plan"| node_parser
node_planservice -->|"applies rules"| node_analyzer
node_planservice -->|"builds entries"| node_reportservice
node_reportservice -->|"builds report"| node_changereport
node_reportservice -->|"requests metadata"| node_provider
node_changereport -->|"compares snapshots"| node_metadatadiff
node_server -->|"loads settings"| node_config
node_server -->|"configures pinning"| node_repo
node_provider -->|"checks cache"| node_cache
node_worker -->|"resolves ebuild"| node_resolver
node_worker -->|"prepares cache"| node_generator
node_provider -.->|"requests preparation"| node_worker
node_browser -->|"opens report"| node_frontend
node_frontend -->|"validates responses"| node_model
node_frontend -->|"renders report"| node_render
node_render -->|"loads details"| node_api
node_model -->|"uses types"| node_api_types
node_cli -.->|"analyzes plan"| node_parser

click node_server "https://github.com/vovanbl411/gentoo-update-intelligence/blob/main/backend/cmd/gentoo-update-intelligence-server/main.go"
click node_cli "https://github.com/vovanbl411/gentoo-update-intelligence/blob/main/backend/cmd/gentoo-update-intelligence/run.go"
click node_http "https://github.com/vovanbl411/gentoo-update-intelligence/blob/main/backend/internal/analysishttp/handler.go"
click node_store "https://github.com/vovanbl411/gentoo-update-intelligence/blob/main/backend/internal/analysisstore/postgres.go"
click node_parser "https://github.com/vovanbl411/gentoo-update-intelligence/blob/main/backend/internal/parser/parser.go"
click node_analyzer "https://github.com/vovanbl411/gentoo-update-intelligence/blob/main/backend/internal/analyzer/analyzer.go"
click node_planservice "https://github.com/vovanbl411/gentoo-update-intelligence/blob/main/backend/internal/planservice/planservice.go"
click node_reportservice "https://github.com/vovanbl411/gentoo-update-intelligence/blob/main/backend/internal/reportservice/reportservice.go"
click node_changereport "https://github.com/vovanbl411/gentoo-update-intelligence/blob/main/backend/internal/changereport/changereport.go"
click node_metadatadiff "https://github.com/vovanbl411/gentoo-update-intelligence/blob/main/backend/internal/metadatadiff/compare.go"
click node_config "https://github.com/vovanbl411/gentoo-update-intelligence/blob/main/backend/internal/backendconfig/config.go"
click node_repo "https://github.com/vovanbl411/gentoo-update-intelligence/blob/main/backend/internal/repositorymanager/manager.go"
click node_provider "https://github.com/vovanbl411/gentoo-update-intelligence/blob/main/backend/internal/metadataprovider/provider.go"
click node_cache "https://github.com/vovanbl411/gentoo-update-intelligence/blob/main/backend/internal/metadatacache/store.go"
click node_resolver "https://github.com/vovanbl411/gentoo-update-intelligence/blob/main/backend/internal/ebuildresolver/resolver.go"
click node_worker "https://github.com/vovanbl411/gentoo-update-intelligence/blob/main/backend/cmd/metadata-worker/main.go"
click node_generator "https://github.com/vovanbl411/gentoo-update-intelligence/blob/main/backend/internal/metadatagenerator/generator.go"
click node_frontend "https://github.com/vovanbl411/gentoo-update-intelligence/blob/main/frontend/src/main.ts"
click node_api "https://github.com/vovanbl411/gentoo-update-intelligence/blob/main/frontend/src/api.ts"
click node_model "https://github.com/vovanbl411/gentoo-update-intelligence/blob/main/frontend/src/model.ts"
click node_render "https://github.com/vovanbl411/gentoo-update-intelligence/blob/main/frontend/src/report.ts"
click node_api_types "https://github.com/vovanbl411/gentoo-update-intelligence/blob/main/frontend/src/api-types.ts"

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_server,node_cli,node_config toneBlue
class node_parser,node_analyzer,node_planservice,node_reportservice,node_changereport,node_metadatadiff toneAmber
class node_repo,node_provider,node_cache,node_resolver,node_worker,node_generator toneMint
class node_http,node_store,node_frontend,node_api,node_model,node_render,node_api_types toneRose
class node_user,node_browser toneIndigo
```

## Components

### Entry points

- [HTTP server](https://github.com/vovanbl411/gentoo-update-intelligence/blob/main/backend/cmd/gentoo-update-intelligence-server/main.go): `backend/cmd/gentoo-update-intelligence-server/main.go`
- [Analysis CLI](https://github.com/vovanbl411/gentoo-update-intelligence/blob/main/backend/cmd/gentoo-update-intelligence/run.go): `backend/cmd/gentoo-update-intelligence/run.go`
- [Backend config](https://github.com/vovanbl411/gentoo-update-intelligence/blob/main/backend/internal/backendconfig/config.go): `backend/internal/backendconfig/config.go`

### Plan analysis

- [Plan parser](https://github.com/vovanbl411/gentoo-update-intelligence/blob/main/backend/internal/parser/parser.go): `backend/internal/parser/parser.go`
- [Rule analyzer](https://github.com/vovanbl411/gentoo-update-intelligence/blob/main/backend/internal/analyzer/analyzer.go): `backend/internal/analyzer/analyzer.go`
- [Plan coordinator](https://github.com/vovanbl411/gentoo-update-intelligence/blob/main/backend/internal/planservice/planservice.go): `backend/internal/planservice/planservice.go`
- [Entry reports](https://github.com/vovanbl411/gentoo-update-intelligence/blob/main/backend/internal/reportservice/reportservice.go): `backend/internal/reportservice/reportservice.go`
- [Change report](https://github.com/vovanbl411/gentoo-update-intelligence/blob/main/backend/internal/changereport/changereport.go): `backend/internal/changereport/changereport.go`
- [Metadata diff](https://github.com/vovanbl411/gentoo-update-intelligence/blob/main/backend/internal/metadatadiff/compare.go): `backend/internal/metadatadiff/compare.go`

### Metadata acquisition

- [Repository pinning](https://github.com/vovanbl411/gentoo-update-intelligence/blob/main/backend/internal/repositorymanager/manager.go): `backend/internal/repositorymanager/manager.go`
- [Metadata provider](https://github.com/vovanbl411/gentoo-update-intelligence/blob/main/backend/internal/metadataprovider/provider.go): `backend/internal/metadataprovider/provider.go`
- [Metadata cache](https://github.com/vovanbl411/gentoo-update-intelligence/blob/main/backend/internal/metadatacache/store.go): `backend/internal/metadatacache/store.go`
- [Ebuild resolver](https://github.com/vovanbl411/gentoo-update-intelligence/blob/main/backend/internal/ebuildresolver/resolver.go): `backend/internal/ebuildresolver/resolver.go`
- [Metadata worker](https://github.com/vovanbl411/gentoo-update-intelligence/blob/main/backend/cmd/metadata-worker/main.go): `backend/cmd/metadata-worker/main.go`
- [Cache generator](https://github.com/vovanbl411/gentoo-update-intelligence/blob/main/backend/internal/metadatagenerator/generator.go): `backend/internal/metadatagenerator/generator.go`

### Reports and UI

- [Analysis API](https://github.com/vovanbl411/gentoo-update-intelligence/blob/main/backend/internal/analysishttp/handler.go): `backend/internal/analysishttp/handler.go`
- [Job storage](https://github.com/vovanbl411/gentoo-update-intelligence/blob/main/backend/internal/analysisstore/postgres.go): `backend/internal/analysisstore/postgres.go`
- [Web interface](https://github.com/vovanbl411/gentoo-update-intelligence/blob/main/frontend/src/main.ts): `frontend/src/main.ts`
- [HTTP client](https://github.com/vovanbl411/gentoo-update-intelligence/blob/main/frontend/src/api.ts): `frontend/src/api.ts`
- [Response model](https://github.com/vovanbl411/gentoo-update-intelligence/blob/main/frontend/src/model.ts): `frontend/src/model.ts`
- [Report renderer](https://github.com/vovanbl411/gentoo-update-intelligence/blob/main/frontend/src/report.ts): `frontend/src/report.ts`
- [API types](https://github.com/vovanbl411/gentoo-update-intelligence/blob/main/frontend/src/api-types.ts): `frontend/src/api-types.ts`

### Other components

- **Plan author**
- **Report reader**

## Connections

- Plan author → Web interface: submits plan
- Web interface → HTTP client: calls (evidence: `frontend/src/main.ts`)
- HTTP client → Analysis API: HTTP requests
- HTTP server → Analysis API: serves (evidence: `backend/cmd/gentoo-update-intelligence-server/main.go`)
- HTTP server → Job storage: opens (evidence: `backend/cmd/gentoo-update-intelligence-server/main.go`)
- Analysis API → Job storage: persists jobs
- Analysis API → Plan coordinator: dispatches analysis
- Plan coordinator → Plan parser: parses plan
- Plan coordinator → Rule analyzer: applies rules
- Plan coordinator → Entry reports: builds entries (evidence: `backend/internal/planservice/planservice.go`)
- Entry reports → Change report: builds report (evidence: `backend/internal/reportservice/reportservice.go`)
- Entry reports → Metadata provider: requests metadata (evidence: `backend/internal/reportservice/reportservice.go`)
- Change report → Metadata diff: compares snapshots
- HTTP server → Backend config: loads settings (evidence: `backend/cmd/gentoo-update-intelligence-server/main.go`)
- HTTP server → Repository pinning: configures pinning (evidence: `backend/cmd/gentoo-update-intelligence-server/main.go`)
- Metadata provider → Metadata cache: checks cache
- Metadata worker → Ebuild resolver: resolves ebuild (evidence: `backend/cmd/metadata-worker/main.go`)
- Metadata worker → Cache generator: prepares cache (evidence: `backend/cmd/metadata-worker/main.go`)
- Metadata provider → Metadata worker: requests preparation
- Report reader → Web interface: opens report
- Web interface → Response model: validates responses (evidence: `frontend/src/main.ts`)
- Web interface → Report renderer: renders report (evidence: `frontend/src/main.ts`)
- Report renderer → HTTP client: loads details (evidence: `frontend/src/report.ts`)
- Response model → API types: uses types (evidence: `frontend/src/model.ts`)
- Analysis CLI → Plan parser: analyzes plan