# ezioauditore027/crypto-secure-model-service architecture

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

- Interactive diagram: https://gitdiagram.com/ezioauditore027/crypto-secure-model-service
- Repository: https://github.com/ezioauditore027/crypto-secure-model-service

## Overview

This is a secure ML model-serving application: users register, receive approval, establish a KEM-based encrypted session, submit classification queries, and may send feedback; administrators manage access and retrain the classifier. The HTTP API dispatches operations to a central service, which coordinates session security, inference, feedback, and persistence. The graph also preserves the documented web and CLI clients, classical KEM fallback, and feedback-driven model rebuilding. Some UI-to-API wiring and unsampled service operations are documented but not shown in excerpts, so those links are marked unverified.

Main entry points: [`server/service.py`](https://github.com/ezioauditore027/crypto-secure-model-service/blob/main/server/service.py) (Service Manager), [`server/app.py`](https://github.com/ezioauditore027/crypto-secure-model-service/blob/main/server/app.py) (HTTP API), [`crypto/channel.py`](https://github.com/ezioauditore027/crypto-secure-model-service/blob/main/crypto/channel.py) (Secure Session), [`run_user.py`](https://github.com/ezioauditore027/crypto-secure-model-service/blob/main/run_user.py) (User CLI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["User and Admin Clients"]
  node_user_web["User Web Portal<br/>[user.html]"]
  node_admin_web["Admin Web Portal<br/>[admin.html]"]
  node_user_cli["User CLI<br/>[run_user.py]"]
  node_admin_cli["Admin CLI<br/>[run_admin.py]"]
end

subgraph group_api["HTTP and Orchestration"]
  node_http_api["HTTP API<br/>[app.py]"]
  node_service["Service Manager<br/>[service.py]"]
end

subgraph group_security["Secure Channel"]
  node_kem["KEM Algorithms<br/>[kem.py]"]
  node_session["Secure Session<br/>[channel.py]"]
  node_kdf["HKDF<br/>[kdf.py]"]
  node_aead["ChaCha20-Poly1305<br/>[aead.py]"]
end

subgraph group_mlstate["ML and Persistence"]
  node_dataset["Training and Feedback Data<br/>[dataset.py]"]
  node_model["Classifier and Retraining<br/>[model.py]"]
  node_database[("SQLite State<br/>[database.py]")]
end

node_user(("Authorized User"))
node_admin(("Owner / Admin"))

node_user -->|"uses"| node_user_web
node_user -->|"uses"| node_user_cli
node_admin -->|"uses"| node_admin_web
node_admin -->|"uses"| node_admin_cli
node_user_web -.->|"calls API"| node_http_api
node_admin_web -.->|"calls API"| node_http_api
node_user_cli -->|"sends requests"| node_http_api
node_admin_cli -.->|"calls API"| node_http_api
node_http_api -->|"dispatches"| node_service
node_service -->|"reads and writes"| node_database
node_service -->|"selects and uses"| node_kem
node_service -->|"manages sessions"| node_session
node_service -->|"runs inference"| node_model
node_service -->|"loads training data"| node_dataset
node_service -->|"stores feedback"| node_database
node_service -->|"rebuilds classifier"| node_model
node_session -->|"derives keys"| node_kdf
node_session -->|"encrypts and decrypts"| node_aead
node_kem -->|"derives shared key"| node_kdf
node_database -.->|"stores model blob"| node_model
node_user_cli -->|"encapsulates key"| node_kem
node_user_cli -->|"creates session"| node_session
node_http_api -->|"parses secure packet"| node_session
node_service -->|"encrypts response"| node_session

click node_user_web "https://github.com/ezioauditore027/crypto-secure-model-service/blob/main/web/user.html"
click node_admin_web "https://github.com/ezioauditore027/crypto-secure-model-service/blob/main/web/admin.html"
click node_user_cli "https://github.com/ezioauditore027/crypto-secure-model-service/blob/main/run_user.py"
click node_admin_cli "https://github.com/ezioauditore027/crypto-secure-model-service/blob/main/run_admin.py"
click node_http_api "https://github.com/ezioauditore027/crypto-secure-model-service/blob/main/server/app.py"
click node_service "https://github.com/ezioauditore027/crypto-secure-model-service/blob/main/server/service.py"
click node_kem "https://github.com/ezioauditore027/crypto-secure-model-service/blob/main/crypto/kem.py"
click node_session "https://github.com/ezioauditore027/crypto-secure-model-service/blob/main/crypto/channel.py"
click node_kdf "https://github.com/ezioauditore027/crypto-secure-model-service/blob/main/crypto/kdf.py"
click node_aead "https://github.com/ezioauditore027/crypto-secure-model-service/blob/main/crypto/aead.py"
click node_dataset "https://github.com/ezioauditore027/crypto-secure-model-service/blob/main/ml/dataset.py"
click node_model "https://github.com/ezioauditore027/crypto-secure-model-service/blob/main/ml/model.py"
click node_database "https://github.com/ezioauditore027/crypto-secure-model-service/blob/main/server/database.py"

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_user_web,node_admin_web,node_user_cli,node_admin_cli,node_user toneBlue
class node_http_api,node_service toneAmber
class node_kem,node_session,node_kdf,node_aead toneMint
class node_dataset,node_model,node_database toneRose
class node_admin toneIndigo
```

## Components

### User and Admin Clients

- [User Web Portal](https://github.com/ezioauditore027/crypto-secure-model-service/blob/main/web/user.html): `web/user.html`
- [Admin Web Portal](https://github.com/ezioauditore027/crypto-secure-model-service/blob/main/web/admin.html): `web/admin.html`
- [User CLI](https://github.com/ezioauditore027/crypto-secure-model-service/blob/main/run_user.py): `run_user.py`
- [Admin CLI](https://github.com/ezioauditore027/crypto-secure-model-service/blob/main/run_admin.py): `run_admin.py`

### HTTP and Orchestration

- [HTTP API](https://github.com/ezioauditore027/crypto-secure-model-service/blob/main/server/app.py): `server/app.py`
- [Service Manager](https://github.com/ezioauditore027/crypto-secure-model-service/blob/main/server/service.py): `server/service.py`

### Secure Channel

- [KEM Algorithms](https://github.com/ezioauditore027/crypto-secure-model-service/blob/main/crypto/kem.py): `crypto/kem.py`
- [Secure Session](https://github.com/ezioauditore027/crypto-secure-model-service/blob/main/crypto/channel.py): `crypto/channel.py`
- [HKDF](https://github.com/ezioauditore027/crypto-secure-model-service/blob/main/crypto/kdf.py): `crypto/kdf.py`
- [ChaCha20-Poly1305](https://github.com/ezioauditore027/crypto-secure-model-service/blob/main/crypto/aead.py): `crypto/aead.py`

### ML and Persistence

- [Training and Feedback Data](https://github.com/ezioauditore027/crypto-secure-model-service/blob/main/ml/dataset.py): `ml/dataset.py`
- [Classifier and Retraining](https://github.com/ezioauditore027/crypto-secure-model-service/blob/main/ml/model.py): `ml/model.py`
- [SQLite State](https://github.com/ezioauditore027/crypto-secure-model-service/blob/main/server/database.py): `server/database.py`

### Other components

- **Authorized User**
- **Owner / Admin**

## Connections

- Authorized User → User Web Portal: uses (evidence: `README.md`)
- Authorized User → User CLI: uses (evidence: `README.md`)
- Owner / Admin → Admin Web Portal: uses (evidence: `README.md`)
- Owner / Admin → Admin CLI: uses (evidence: `README.md`)
- User Web Portal → HTTP API: calls API
- Admin Web Portal → HTTP API: calls API
- User CLI → HTTP API: sends requests (evidence: `run_user.py`)
- Admin CLI → HTTP API: calls API
- HTTP API → Service Manager: dispatches (evidence: `server/app.py`)
- Service Manager → SQLite State: reads and writes (evidence: `server/service.py`)
- Service Manager → KEM Algorithms: selects and uses (evidence: `server/service.py`)
- Service Manager → Secure Session: manages sessions (evidence: `server/service.py`)
- Service Manager → Classifier and Retraining: runs inference (evidence: `server/service.py`)
- Service Manager → Training and Feedback Data: loads training data (evidence: `server/service.py`)
- Service Manager → SQLite State: stores feedback (evidence: `server/service.py`)
- Service Manager → Classifier and Retraining: rebuilds classifier (evidence: `server/service.py`)
- Secure Session → HKDF: derives keys (evidence: `crypto/channel.py`)
- Secure Session → ChaCha20-Poly1305: encrypts and decrypts (evidence: `crypto/channel.py`)
- KEM Algorithms → HKDF: derives shared key (evidence: `crypto/kem.py`)
- SQLite State → Classifier and Retraining: stores model blob
- User CLI → KEM Algorithms: encapsulates key (evidence: `run_user.py`)
- User CLI → Secure Session: creates session (evidence: `run_user.py`)
- HTTP API → Secure Session: parses secure packet (evidence: `server/app.py`)
- Service Manager → Secure Session: encrypts response (evidence: `server/service.py`)