# teudanrichard/clamav-rest architecture

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

- Interactive diagram: https://gitdiagram.com/teudanrichard/clamav-rest
- Repository: https://github.com/teudanrichard/clamav-rest

## Overview

ClamAV HTTP Gateway accepts scan requests, enforces bounded streaming and concurrency, speaks ClamAV’s INSTREAM protocol, and returns typed clean/infected results. The graph covers both upload modes, health/version endpoints, optional OIDC, and observability. Source excerpts establish the application’s calls; deployment and Helm capabilities are documented in the README, but their runtime wiring is not sampled, so they are represented as a separate documented subsystem with limited links.

Main entry points: [`app/main.py`](https://github.com/teudanrichard/clamav-rest/blob/main/app/main.py) (HTTP Routes), [`app/socket_client.py`](https://github.com/teudanrichard/clamav-rest/blob/main/app/socket_client.py) (Socket Protocol Client), [`compose.yaml`](https://github.com/teudanrichard/clamav-rest/blob/main/compose.yaml) (Container and Compose), [`charts/clamav-rest`](https://github.com/teudanrichard/clamav-rest/tree/main/charts/clamav-rest) (Kubernetes Helm Chart)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["HTTP Gateway"]
  node_app["HTTP Routes<br/>[main.py]"]
  node_models["API Models<br/>[models.py]"]
  node_config["Runtime Settings<br/>[config.py]"]
  node_version["Release Version<br/>[version.py]"]
end

subgraph group_scan["Scan Processing"]
  node_stream["Raw Stream Scan<br/>[main.py]"]
  node_multipart["Multipart Scan<br/>[main.py]"]
  node_admission["Scan Admission<br/>[main.py]"]
end

subgraph group_backend["ClamAV Backend"]
  node_socket["Socket Protocol Client<br/>[socket_client.py]"]
  node_clamd{{"ClamAV Daemon"}}
  node_health["Health and Readiness<br/>[main.py]"]
  node_clamversion["Engine Version Route<br/>[main.py]"]
end

subgraph group_security["Authentication"]
  node_authboundary["Auth Dependency<br/>[__init__.py]"]
  node_oidc["OIDC Verifier<br/>[oidc.py]"]
end

subgraph group_ops["Operations"]
  node_observability["Request Observability<br/>[observability.py]"]
  node_metrics["Prometheus Metrics<br/>[observability.py]"]
  node_deployment["Container and Compose<br/>[compose.yaml]"]
  node_helm["Kubernetes Helm Chart"]
  node_signatures[("Signature Storage")]
end

node_client(("API Client"))
node_provider{{"OIDC Provider"}}

node_client -->|"calls API"| node_app
node_app -->|"returns typed results"| node_models
node_app -->|"loads settings"| node_config
node_config -->|"reads version"| node_version
node_app -->|"routes raw body"| node_stream
node_app -->|"routes file upload"| node_multipart
node_stream -->|"acquires scan slot"| node_admission
node_multipart -->|"acquires upload slot"| node_admission
node_admission -->|"scans chunks"| node_socket
node_health -->|"pings daemon"| node_socket
node_clamversion -->|"requests version"| node_socket
node_socket -->|"sends protocol commands"| node_clamd
node_app -->|"serves probes"| node_health
node_app -->|"serves version"| node_clamversion
node_app -->|"protects routes"| node_authboundary
node_authboundary -->|"validates when enabled"| node_oidc
node_oidc -->|"fetches discovery and keys"| node_provider
node_app -->|"installs middleware"| node_observability
node_app -->|"mounts when enabled"| node_metrics
node_deployment -->|"runs separate service"| node_clamd
node_deployment -->|"persists signatures"| node_signatures
node_helm -.->|"optional sidecar service"| node_clamd
node_helm -->|"supports persistent signatures"| node_signatures

click node_app "https://github.com/teudanrichard/clamav-rest/blob/main/app/main.py"
click node_models "https://github.com/teudanrichard/clamav-rest/blob/main/app/models.py"
click node_config "https://github.com/teudanrichard/clamav-rest/blob/main/app/config.py"
click node_version "https://github.com/teudanrichard/clamav-rest/blob/main/app/version.py"
click node_stream "https://github.com/teudanrichard/clamav-rest/blob/main/app/main.py"
click node_multipart "https://github.com/teudanrichard/clamav-rest/blob/main/app/main.py"
click node_admission "https://github.com/teudanrichard/clamav-rest/blob/main/app/main.py"
click node_socket "https://github.com/teudanrichard/clamav-rest/blob/main/app/socket_client.py"
click node_health "https://github.com/teudanrichard/clamav-rest/blob/main/app/main.py"
click node_clamversion "https://github.com/teudanrichard/clamav-rest/blob/main/app/main.py"
click node_authboundary "https://github.com/teudanrichard/clamav-rest/blob/main/app/auth/__init__.py"
click node_oidc "https://github.com/teudanrichard/clamav-rest/blob/main/app/auth/oidc.py"
click node_observability "https://github.com/teudanrichard/clamav-rest/blob/main/app/observability.py"
click node_metrics "https://github.com/teudanrichard/clamav-rest/blob/main/app/observability.py"
click node_deployment "https://github.com/teudanrichard/clamav-rest/blob/main/compose.yaml"
click node_helm "https://github.com/teudanrichard/clamav-rest/tree/main/charts/clamav-rest"

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_models,node_config,node_version,node_client toneBlue
class node_stream,node_multipart,node_admission toneAmber
class node_socket,node_clamd,node_health,node_clamversion toneMint
class node_authboundary,node_oidc toneRose
class node_observability,node_metrics,node_deployment,node_helm,node_signatures,node_provider toneIndigo
```

## Components

### HTTP Gateway

- [HTTP Routes](https://github.com/teudanrichard/clamav-rest/blob/main/app/main.py): `app/main.py`
- [API Models](https://github.com/teudanrichard/clamav-rest/blob/main/app/models.py): `app/models.py`
- [Runtime Settings](https://github.com/teudanrichard/clamav-rest/blob/main/app/config.py): `app/config.py`
- [Release Version](https://github.com/teudanrichard/clamav-rest/blob/main/app/version.py): `app/version.py`

### Scan Processing

- [Raw Stream Scan](https://github.com/teudanrichard/clamav-rest/blob/main/app/main.py): `app/main.py`
- [Multipart Scan](https://github.com/teudanrichard/clamav-rest/blob/main/app/main.py): `app/main.py`
- [Scan Admission](https://github.com/teudanrichard/clamav-rest/blob/main/app/main.py): `app/main.py`

### ClamAV Backend

- [Socket Protocol Client](https://github.com/teudanrichard/clamav-rest/blob/main/app/socket_client.py): `app/socket_client.py`
- **ClamAV Daemon**
- [Health and Readiness](https://github.com/teudanrichard/clamav-rest/blob/main/app/main.py): `app/main.py`
- [Engine Version Route](https://github.com/teudanrichard/clamav-rest/blob/main/app/main.py): `app/main.py`

### Authentication

- [Auth Dependency](https://github.com/teudanrichard/clamav-rest/blob/main/app/auth/__init__.py): `app/auth/__init__.py`
- [OIDC Verifier](https://github.com/teudanrichard/clamav-rest/blob/main/app/auth/oidc.py): `app/auth/oidc.py`

### Operations

- [Request Observability](https://github.com/teudanrichard/clamav-rest/blob/main/app/observability.py): `app/observability.py`
- [Prometheus Metrics](https://github.com/teudanrichard/clamav-rest/blob/main/app/observability.py): `app/observability.py`
- [Container and Compose](https://github.com/teudanrichard/clamav-rest/blob/main/compose.yaml): `compose.yaml`
- [Kubernetes Helm Chart](https://github.com/teudanrichard/clamav-rest/tree/main/charts/clamav-rest): `charts/clamav-rest`
- **Signature Storage**

### Other components

- **API Client**
- **OIDC Provider**

## Connections

- API Client → HTTP Routes: calls API (evidence: `README.md`)
- HTTP Routes → API Models: returns typed results (evidence: `app/main.py`)
- HTTP Routes → Runtime Settings: loads settings (evidence: `app/main.py`)
- Runtime Settings → Release Version: reads version (evidence: `app/config.py`)
- HTTP Routes → Raw Stream Scan: routes raw body (evidence: `app/main.py`)
- HTTP Routes → Multipart Scan: routes file upload (evidence: `app/main.py`)
- Raw Stream Scan → Scan Admission: acquires scan slot (evidence: `app/main.py`)
- Multipart Scan → Scan Admission: acquires upload slot (evidence: `app/main.py`)
- Scan Admission → Socket Protocol Client: scans chunks (evidence: `app/main.py`)
- Health and Readiness → Socket Protocol Client: pings daemon (evidence: `app/main.py`)
- Engine Version Route → Socket Protocol Client: requests version (evidence: `app/main.py`)
- Socket Protocol Client → ClamAV Daemon: sends protocol commands (evidence: `README.md`)
- HTTP Routes → Health and Readiness: serves probes (evidence: `app/main.py`)
- HTTP Routes → Engine Version Route: serves version (evidence: `app/main.py`)
- HTTP Routes → Auth Dependency: protects routes (evidence: `app/main.py`)
- Auth Dependency → OIDC Verifier: validates when enabled (evidence: `app/auth/__init__.py`)
- OIDC Verifier → OIDC Provider: fetches discovery and keys (evidence: `app/auth/oidc.py`)
- HTTP Routes → Request Observability: installs middleware (evidence: `app/main.py`)
- HTTP Routes → Prometheus Metrics: mounts when enabled (evidence: `app/main.py`)
- Container and Compose → ClamAV Daemon: runs separate service (evidence: `README.md`)
- Container and Compose → Signature Storage: persists signatures (evidence: `README.md`)
- Kubernetes Helm Chart → ClamAV Daemon: optional sidecar service (evidence: `README.md`)
- Kubernetes Helm Chart → Signature Storage: supports persistent signatures (evidence: `README.md`)