# amramer101/vulnera architecture

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

- Interactive diagram: https://gitdiagram.com/amramer101/vulnera
- Repository: https://github.com/amramer101/vulnera

## Overview

Vulnera is a Rust HTTP API for dependency and repository vulnerability analysis. The main flow accepts a manifest or repository request, parses package dependencies, looks up vulnerabilities across advisory sources, and returns an analysis report with optional safe-version recommendations. Separate branches cover vulnerability browsing, popular packages, health/metrics, repository fetching, caching, and registry version lookup. The graph follows the documented layered design; edges are limited to relationships shown in excerpts, the source index, or README. Many parser and controller details were not sampled, so their internal links are omitted.

Main entry points: [`src/application/services.rs`](https://github.com/amramer101/vulnera/blob/main/src/application/services.rs) (Analysis Services), [`src/presentation/routes.rs`](https://github.com/amramer101/vulnera/blob/main/src/presentation/routes.rs) (HTTP Routes), [`src/presentation/controllers/analysis.rs`](https://github.com/amramer101/vulnera/blob/main/src/presentation/controllers/analysis.rs) (Analysis Controller), [`src/infrastructure/api_clients`](https://github.com/amramer101/vulnera/tree/main/src/infrastructure/api_clients) (Advisory Clients)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["HTTP API"]
  node_routes["HTTP Routes<br/>[routes.rs]"]
  node_analysis["Analysis Controller<br/>[analysis.rs]"]
  node_health["Health Controller<br/>[health.rs]"]
  node_models["API Models<br/>[models.rs]"]
  node_middleware["HTTP Middleware<br/>[middleware.rs]"]
end

subgraph group_app["Analysis Application"]
  node_services["Analysis Services<br/>[services.rs]"]
  node_usecases["Use Cases<br/>[use_cases.rs]"]
  node_config["Configuration<br/>[config.rs]"]
end

subgraph group_infra["Infrastructure"]
  node_parsers["Manifest Parsers"]
  node_repo_source["Repository Fetching"]
  node_advisory_repo["Advisory Repository<br/>[repositories.rs]"]
  node_api_clients["Advisory Clients"]
  node_cache[("Filesystem Cache<br/>[file_cache.rs]")]
  node_registries["Package Registries<br/>[mod.rs]"]
  node_resilience["Resilience<br/>[resilience.rs]"]
end

subgraph group_domain["Domain Model"]
  node_package["Package Data<br/>[entities.rs]"]
  node_domain_services["Domain Services<br/>[services.rs]"]
  node_value_objects["Domain Values<br/>[value_objects.rs]"]
end

node_client(("API Client"))
node_osv{{"OSV"}}
node_nvd{{"NVD"}}
node_ghsa{{"GitHub Advisories"}}

node_client -->|"sends requests"| node_routes
node_routes -->|"routes analysis"| node_analysis
node_routes -->|"routes health"| node_health
node_analysis -->|"uses DTOs"| node_models
node_analysis -->|"invokes analysis"| node_services
node_analysis -->|"analyzes repositories"| node_repo_source
node_routes -->|"applies middleware"| node_middleware
node_services -->|"parses manifests"| node_parsers
node_services -->|"fetches repository files"| node_repo_source
node_services -.->|"queries advisories"| node_advisory_repo
node_services -->|"reads and writes"| node_cache
node_services -->|"looks up versions"| node_registries
node_services -.->|"processes packages"| node_package
node_advisory_repo -->|"uses clients"| node_api_clients
node_api_clients -->|"queries advisories"| node_osv
node_api_clients -->|"queries advisories"| node_nvd
node_api_clients -->|"queries advisories"| node_ghsa
node_parsers -.->|"creates packages"| node_package
node_repo_source -->|"fetches repository"| node_client
node_services -.->|"uses domain logic"| node_domain_services
node_package -->|"uses values"| node_value_objects
node_health -->|"returns health data"| node_models

click node_routes "https://github.com/amramer101/vulnera/blob/main/src/presentation/routes.rs"
click node_analysis "https://github.com/amramer101/vulnera/blob/main/src/presentation/controllers/analysis.rs"
click node_health "https://github.com/amramer101/vulnera/blob/main/src/presentation/controllers/health.rs"
click node_models "https://github.com/amramer101/vulnera/blob/main/src/presentation/models.rs"
click node_middleware "https://github.com/amramer101/vulnera/blob/main/src/presentation/middleware.rs"
click node_services "https://github.com/amramer101/vulnera/blob/main/src/application/services.rs"
click node_usecases "https://github.com/amramer101/vulnera/blob/main/src/application/use_cases.rs"
click node_config "https://github.com/amramer101/vulnera/blob/main/src/config.rs"
click node_parsers "https://github.com/amramer101/vulnera/tree/main/src/infrastructure/parsers"
click node_repo_source "https://github.com/amramer101/vulnera/tree/main/src/infrastructure/repository_source"
click node_advisory_repo "https://github.com/amramer101/vulnera/blob/main/src/infrastructure/repositories.rs"
click node_api_clients "https://github.com/amramer101/vulnera/tree/main/src/infrastructure/api_clients"
click node_cache "https://github.com/amramer101/vulnera/blob/main/src/infrastructure/cache/file_cache.rs"
click node_registries "https://github.com/amramer101/vulnera/blob/main/src/infrastructure/registries/mod.rs"
click node_resilience "https://github.com/amramer101/vulnera/blob/main/src/infrastructure/resilience.rs"
click node_package "https://github.com/amramer101/vulnera/blob/main/src/domain/entities.rs"
click node_domain_services "https://github.com/amramer101/vulnera/blob/main/src/domain/services.rs"
click node_value_objects "https://github.com/amramer101/vulnera/blob/main/src/domain/value_objects.rs"

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_health,node_models,node_middleware,node_client toneBlue
class node_services,node_usecases,node_config toneAmber
class node_parsers,node_repo_source,node_advisory_repo,node_api_clients,node_cache,node_registries,node_resilience toneMint
class node_package,node_domain_services,node_value_objects toneRose
class node_osv,node_nvd,node_ghsa toneIndigo
```

## Components

### HTTP API

- [HTTP Routes](https://github.com/amramer101/vulnera/blob/main/src/presentation/routes.rs): `src/presentation/routes.rs`
- [Analysis Controller](https://github.com/amramer101/vulnera/blob/main/src/presentation/controllers/analysis.rs): `src/presentation/controllers/analysis.rs`
- [Health Controller](https://github.com/amramer101/vulnera/blob/main/src/presentation/controllers/health.rs): `src/presentation/controllers/health.rs`
- [API Models](https://github.com/amramer101/vulnera/blob/main/src/presentation/models.rs): `src/presentation/models.rs`
- [HTTP Middleware](https://github.com/amramer101/vulnera/blob/main/src/presentation/middleware.rs): `src/presentation/middleware.rs`

### Analysis Application

- [Analysis Services](https://github.com/amramer101/vulnera/blob/main/src/application/services.rs): `src/application/services.rs`
- [Use Cases](https://github.com/amramer101/vulnera/blob/main/src/application/use_cases.rs): `src/application/use_cases.rs`
- [Configuration](https://github.com/amramer101/vulnera/blob/main/src/config.rs): `src/config.rs`

### Infrastructure

- [Manifest Parsers](https://github.com/amramer101/vulnera/tree/main/src/infrastructure/parsers): `src/infrastructure/parsers`
- [Repository Fetching](https://github.com/amramer101/vulnera/tree/main/src/infrastructure/repository_source): `src/infrastructure/repository_source`
- [Advisory Repository](https://github.com/amramer101/vulnera/blob/main/src/infrastructure/repositories.rs): `src/infrastructure/repositories.rs`
- [Advisory Clients](https://github.com/amramer101/vulnera/tree/main/src/infrastructure/api_clients): `src/infrastructure/api_clients`
- [Filesystem Cache](https://github.com/amramer101/vulnera/blob/main/src/infrastructure/cache/file_cache.rs): `src/infrastructure/cache/file_cache.rs`
- [Package Registries](https://github.com/amramer101/vulnera/blob/main/src/infrastructure/registries/mod.rs): `src/infrastructure/registries/mod.rs`
- [Resilience](https://github.com/amramer101/vulnera/blob/main/src/infrastructure/resilience.rs): `src/infrastructure/resilience.rs`

### Domain Model

- [Package Data](https://github.com/amramer101/vulnera/blob/main/src/domain/entities.rs): `src/domain/entities.rs`
- [Domain Services](https://github.com/amramer101/vulnera/blob/main/src/domain/services.rs): `src/domain/services.rs`
- [Domain Values](https://github.com/amramer101/vulnera/blob/main/src/domain/value_objects.rs): `src/domain/value_objects.rs`

### Other components

- **API Client**
- **OSV**
- **NVD**
- **GitHub Advisories**

## Connections

- API Client → HTTP Routes: sends requests (evidence: `README.md`)
- HTTP Routes → Analysis Controller: routes analysis (evidence: `src/presentation/routes.rs`)
- HTTP Routes → Health Controller: routes health (evidence: `src/presentation/routes.rs`)
- Analysis Controller → API Models: uses DTOs (evidence: `src/presentation/controllers/analysis.rs`)
- Analysis Controller → Analysis Services: invokes analysis (evidence: `src/presentation/controllers/analysis.rs`)
- Analysis Controller → Repository Fetching: analyzes repositories (evidence: `README.md`)
- HTTP Routes → HTTP Middleware: applies middleware (evidence: `src/presentation/routes.rs`)
- Analysis Services → Manifest Parsers: parses manifests (evidence: `src/application/services.rs`)
- Analysis Services → Repository Fetching: fetches repository files (evidence: `src/application/services.rs`)
- Analysis Services → Advisory Repository: queries advisories
- Analysis Services → Filesystem Cache: reads and writes (evidence: `src/application/services.rs`)
- Analysis Services → Package Registries: looks up versions (evidence: `src/application/services.rs`)
- Analysis Services → Package Data: processes packages
- Advisory Repository → Advisory Clients: uses clients (evidence: `src/infrastructure/repositories.rs`)
- Advisory Clients → OSV: queries advisories (evidence: `README.md`)
- Advisory Clients → NVD: queries advisories (evidence: `README.md`)
- Advisory Clients → GitHub Advisories: queries advisories (evidence: `README.md`)
- Manifest Parsers → Package Data: creates packages
- Repository Fetching → API Client: fetches repository (evidence: `README.md`)
- Analysis Services → Domain Services: uses domain logic
- Package Data → Domain Values: uses values (evidence: `src/domain/entities.rs`)
- Health Controller → API Models: returns health data (evidence: `src/presentation/controllers/health.rs`)
