# adityadugad/securevault architecture

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

- Interactive diagram: https://gitdiagram.com/adityadugad/securevault
- Repository: https://github.com/adityadugad/securevault

## Overview

1. **Top-level shape**
   - SecureVault is a two-tier system: a **FastAPI backend** in `app/` and a **static browser frontend** in `static/`.
   - The frontend is not a SPA framework; it is a set of HTML pages plus JS modules for auth, notes, passwords, todos, OTP, and PQC views.

2. **Backend composition and startup**
   - `app/main.py` is the composition root: it creates the FastAPI app, registers middleware, wires routers, and triggers startup initialization.
   - Startup depends on three schema/bootstrap modules: `app/models.py` for core user tables, `app/vault/vault_models.py` for vault tables and migrations, and the security tables described in the README.
   - `render.yaml` indicates deployment on a managed platform, while `securevault.db` shows the app uses a local SQLite file in development or single-instance deployment.

3. **Request routing boundaries**
   - The backend is divided into feature routers:
     - `app/auth/auth_routes.py` for signup, login, OTP, reset-password
     - `app/vault/vault_routes.py` for notes, passwords, todos, and admin-encrypted-db access
     - README-described security routes for sessions/dashboard/risk views
     - `app/pqc/metrics.py` for live PQC benchmarking
   - Shared dependencies live in utility modules rather than a service layer, so most business logic is orchestrated directly from route handlers.

4. **Authentication flow**
   - Authentication is multi-step: **password → OTP → JWT**.
   - `app/auth/auth_utils.py` handles Argon2 hashing and JWT creation/validation.
   - `app/auth/otp_utils.py` manages one-time codes stored in the database, and `app/auth/email_utils.py` sends those codes through an email provider.
   - `app/auth/jwt_dependency.py` provides an alternate bearer-token dependency; the README notes both JWT validators target the same token shape.

5. **Session and security controls**
   - The system is designed to be stricter than a standard stateless JWT app: the README describes a parallel session/history layer, account lockouts, and security-event logging.
   - Rate limiting is central to the security boundary, with sensitive endpoints capped by IP in the SlowAPI-based limiter described in the README.
   - Security events such as failed login, wrong OTP, decrypt abuse, and multi-IP access feed a rolling risk score and lockout logic.

6. **Encrypted vault subsystem**
   - `app/vault/vault_routes.py` and `app/vault/vault_utils.py` implement the core encrypted storage model for notes, passwords, and tasks.
   - The database never stores plaintext secrets; records store ciphertext plus encryption metadata such as nonce, optional KEM ciphertext, and encryption type.
   - `app/vault/vault_models.py` creates and migrates the vault tables so older databases can be upgraded in place.

7. **Hybrid cryptography path**
   - The primary encryption design is **ML-KEM / Kyber + AES-256-GCM**.
   - `vault_utils.py` obtains or reconstructs an AES key through an external Kyber service, then performs symmetric encryption with AES-GCM.
   - If the Kyber service is unavailable, the code falls back to a locally derived backup AES key, so the storage layer remains usable even when the post-quantum service is down.

8. **PQC service boundary**
   - The README shows the Kyber component is not embedded in-process; it is reached over HTTP as an external microservice.
   - `app/pqc/kyber.py` appears to be an alternate or legacy PQC path, while `app/pqc/metrics.py` provides live benchmark measurements for key generation and encrypt/decrypt timings.
   - This creates a clean boundary between the main app and the PQC crypto backend.

9. **Persistence model**
   - SQLite is the only database technology in the repo, accessed via a raw connection object in `app/database.py` rather than an ORM.
   - Data is organized into user identity, OTP, vault content, session/history, and security-log tables.
   - The ownership key across most tables is the user email, which acts as the primary application-level partition key.

10. **Password intelligence**
   - `app/ml/password_strength_model.py` wraps a persisted scikit-learn SVM model stored in `app/ml/password_strength_svm.pkl`.
   - This subsystem is used as a password quality classifier, separate from the normal auth flow, to score user-chosen passwords as weak/medium/strong.
   - It is a local inference component; there is no training pipeline in the repo tree.

11. **Frontend-to-backend data flow**
   - The static pages map directly to backend capabilities: signup/login/OTP/reset for auth, dashboard/security views, and dedicated notes/passwords/todos pages for the vault.
   - JavaScript files under `static/js/` call the API endpoints and drive the user experience around authentication, encrypted CRUD, and password checks.
   - Media assets in `static/img/` are presentation-only and do not affect backend architecture.

12. **External services and operational dependencies**
   - The system depends on three notable external services:
     - an email delivery API for OTPs and security alerts
     - the Kyber/ML-KEM microservice for hybrid key establishment
     - the hosting/runtime environment that serves the FastAPI app and SQLite file
   - Uvicorn is the expected ASGI runtime, and the app likely serves static content alongside API routes in the same deployment unit.

13. **Important architectural takeaway**
   - The dominant boundary in SecureVault is not “frontend vs backend”; it is **plaintext vs protected data**.
   - Every meaningful data path either ends in encrypted storage or in a security-control subsystem, and the design intentionally avoids persisting secrets in clear text.

Main entry points: [`app/main.py`](https://github.com/adityadugad/securevault/blob/main/app/main.py) (App main), [`app/auth/auth_routes.py`](https://github.com/adityadugad/securevault/blob/main/app/auth/auth_routes.py) (Auth routes), [`app/database.py`](https://github.com/adityadugad/securevault/blob/main/app/database.py) (SQLite layer), [`app/vault/vault_routes.py`](https://github.com/adityadugad/securevault/blob/main/app/vault/vault_routes.py) (Vault routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_backend["Backend"]
  node_main["App main<br/>composition root<br/>[main.py]"]
  node_models["User models<br/>schema bootstrap<br/>[models.py]"]
  node_vault_models["Vault models<br/>schema migration<br/>[vault_models.py]"]
  node_auth_routes["Auth routes<br/>API routes<br/>[auth_routes.py]"]
  node_auth_utils["Auth utils<br/>auth crypto<br/>[auth_utils.py]"]
  node_otp_utils["OTP utils<br/>otp store<br/>[otp_utils.py]"]
  node_email_utils["Email adapter<br/>notification adapter<br/>[email_utils.py]"]
  node_jwt_dep["JWT dependency<br/>bearer auth<br/>[jwt_dependency.py]"]
  node_security{{"Security layer<br/>risk control"}}
  node_vault_routes["Vault routes<br/>API routes<br/>[vault_routes.py]"]
  node_vault_utils["Vault crypto<br/>encrypted storage<br/>[vault_utils.py]"]
  node_pqc_metrics["PQC metrics<br/>benchmark api<br/>[metrics.py]"]
  node_kyber["Kyber path<br/>pqc adapter<br/>[kyber.py]"]
  node_ml_model["Password model<br/>ml inference"]
end

subgraph group_frontend["Frontend"]
  node_static_pages["Static pages<br/>browser ui<br/>[index.html]"]
  node_static_js["Client scripts<br/>frontend modules<br/>[auth.js]"]
end

subgraph group_data["Data"]
  node_db[("SQLite layer<br/>database access<br/>[database.py]")]
  node_securevault_db[("Local DB file<br/>sqlite file<br/>[securevault.db]")]
  node_render_yaml["Deploy config<br/>deployment manifest<br/>[render.yaml]"]
end

subgraph group_external["External"]
  node_email_service(("Email service<br/>external api"))
  node_pqc_service(("PQC service<br/>external microservice"))
  node_runtime(("Hosting runtime<br/>deployment platform"))
end

node_main -->|"bootstraps"| node_models
node_main -->|"bootstraps"| node_vault_models
node_main -->|"registers"| node_auth_routes
node_main -->|"registers"| node_vault_routes
node_main -->|"registers"| node_pqc_metrics
node_main -->|"enforces"| node_security
node_auth_routes -->|"uses"| node_auth_utils
node_auth_routes -->|"uses"| node_otp_utils
node_auth_routes -->|"uses"| node_email_utils
node_auth_routes -->|"protects"| node_jwt_dep
node_otp_utils -->|"persists"| node_db
node_vault_routes -->|"uses"| node_vault_utils
node_vault_routes -->|"monitors"| node_security
node_vault_utils -->|"persists"| node_db
node_vault_utils -->|"requests key"| node_kyber
node_kyber -.->|"http service"| node_pqc_service
node_security -->|"records"| node_db
node_security -->|"alerts"| node_email_utils
node_email_utils -.->|"email api"| node_email_service
node_ml_model -->|"independent of"| node_db
node_static_pages -->|"loads"| node_static_js
node_static_js -->|"calls api"| node_main
node_render_yaml -.->|"deploys"| node_runtime
node_securevault_db -.->|"backing file"| node_db
node_main -.->|"runs on"| node_runtime

click node_main "https://github.com/adityadugad/securevault/blob/main/app/main.py"
click node_models "https://github.com/adityadugad/securevault/blob/main/app/models.py"
click node_vault_models "https://github.com/adityadugad/securevault/blob/main/app/vault/vault_models.py"
click node_auth_routes "https://github.com/adityadugad/securevault/blob/main/app/auth/auth_routes.py"
click node_auth_utils "https://github.com/adityadugad/securevault/blob/main/app/auth/auth_utils.py"
click node_otp_utils "https://github.com/adityadugad/securevault/blob/main/app/auth/otp_utils.py"
click node_email_utils "https://github.com/adityadugad/securevault/blob/main/app/auth/email_utils.py"
click node_jwt_dep "https://github.com/adityadugad/securevault/blob/main/app/auth/jwt_dependency.py"
click node_vault_routes "https://github.com/adityadugad/securevault/blob/main/app/vault/vault_routes.py"
click node_vault_utils "https://github.com/adityadugad/securevault/blob/main/app/vault/vault_utils.py"
click node_pqc_metrics "https://github.com/adityadugad/securevault/blob/main/app/pqc/metrics.py"
click node_kyber "https://github.com/adityadugad/securevault/blob/main/app/pqc/kyber.py"
click node_ml_model "https://github.com/adityadugad/securevault/blob/main/app/ml/password_strength_model.py"
click node_static_pages "https://github.com/adityadugad/securevault/blob/main/static/index.html"
click node_static_js "https://github.com/adityadugad/securevault/blob/main/static/js/auth.js"
click node_db "https://github.com/adityadugad/securevault/blob/main/app/database.py"
click node_securevault_db "https://github.com/adityadugad/securevault/blob/main/securevault.db"
click node_render_yaml "https://github.com/adityadugad/securevault/blob/main/render.yaml"

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_main,node_models,node_vault_models,node_auth_routes,node_auth_utils,node_otp_utils,node_email_utils,node_jwt_dep,node_security,node_vault_routes,node_vault_utils,node_pqc_metrics,node_kyber,node_ml_model toneBlue
class node_static_pages,node_static_js toneAmber
class node_db,node_securevault_db,node_render_yaml toneMint
class node_email_service,node_pqc_service,node_runtime toneRose
```

## Components

### Backend

FastAPI application and internal feature subsystems.

- [App main](https://github.com/adityadugad/securevault/blob/main/app/main.py): composition root · Creates the FastAPI app, registers middleware and routers, and runs startup initialization. · `app/main.py`
- [User models](https://github.com/adityadugad/securevault/blob/main/app/models.py): schema bootstrap · Core user and identity tables initialized at startup. · `app/models.py`
- [Vault models](https://github.com/adityadugad/securevault/blob/main/app/vault/vault_models.py): schema migration · Encrypted vault tables and in-place migration logic. · `app/vault/vault_models.py`
- [Auth routes](https://github.com/adityadugad/securevault/blob/main/app/auth/auth_routes.py): API routes · Signup, login, OTP, and password reset endpoints. · `app/auth/auth_routes.py`
- [Auth utils](https://github.com/adityadugad/securevault/blob/main/app/auth/auth_utils.py): auth crypto · Argon2 hashing plus JWT creation and validation. · `app/auth/auth_utils.py`
- [OTP utils](https://github.com/adityadugad/securevault/blob/main/app/auth/otp_utils.py): otp store · Generates and verifies one-time codes persisted in SQLite. · `app/auth/otp_utils.py`
- [Email adapter](https://github.com/adityadugad/securevault/blob/main/app/auth/email_utils.py): notification adapter · Sends OTP and security emails through an external provider. · `app/auth/email_utils.py`
- [JWT dependency](https://github.com/adityadugad/securevault/blob/main/app/auth/jwt_dependency.py): bearer auth · Alternate bearer-token dependency for protected routes. · `app/auth/jwt_dependency.py`
- **Security layer**: risk control · Session history, lockouts, rate limits, and security-event logging described in the README.
- [Vault routes](https://github.com/adityadugad/securevault/blob/main/app/vault/vault_routes.py): API routes · Notes, passwords, todos, and admin-encrypted database access endpoints. · `app/vault/vault_routes.py`
- [Vault crypto](https://github.com/adityadugad/securevault/blob/main/app/vault/vault_utils.py): encrypted storage · Encrypts and decrypts vault data with metadata such as nonce and KEM ciphertext. · `app/vault/vault_utils.py`
- [PQC metrics](https://github.com/adityadugad/securevault/blob/main/app/pqc/metrics.py): benchmark api · Live benchmark measurements for PQC key generation and encrypt/decrypt timings. · `app/pqc/metrics.py`
- [Kyber path](https://github.com/adityadugad/securevault/blob/main/app/pqc/kyber.py): pqc adapter · Alternate or legacy post-quantum crypto path in the application tree. · `app/pqc/kyber.py`
- [Password model](https://github.com/adityadugad/securevault/blob/main/app/ml/password_strength_model.py): ml inference · Loads a persisted SVM classifier to score password strength. · `app/ml/password_strength_model.py`

### Frontend

Static HTML and JavaScript client pages.

- [Static pages](https://github.com/adityadugad/securevault/blob/main/static/index.html): browser ui · HTML pages for auth, dashboard, vault views, PQC, and password reset. · `static/index.html`
- [Client scripts](https://github.com/adityadugad/securevault/blob/main/static/js/auth.js): frontend modules · JavaScript modules that call API endpoints and drive the browser experience. · `static/js/auth.js`

### Data

SQLite persistence, local files, and deployment manifest.

- [SQLite layer](https://github.com/adityadugad/securevault/blob/main/app/database.py): database access · Raw SQLite connection layer shared across the app. · `app/database.py`
- [Local DB file](https://github.com/adityadugad/securevault/blob/main/securevault.db): sqlite file · Bundled SQLite database used in development or single-instance deployment. · `securevault.db`
- [Deploy config](https://github.com/adityadugad/securevault/blob/main/render.yaml): deployment manifest · Managed-platform deployment configuration. · `render.yaml`

### External

Outside services and boundaries the app integrates with.

- **Email service**: external api · External provider used for OTP and security notifications.
- **PQC service**: external microservice · External Kyber or ML-KEM service reached over HTTP.
- **Hosting runtime**: deployment platform · ASGI hosting environment serving the FastAPI app and static assets.

## Connections

- App main → User models: bootstraps · Initializes core user tables during app startup.
- App main → Vault models: bootstraps · Initializes encrypted vault tables and migrations.
- App main → Auth routes: registers · Mounts authentication endpoints into the FastAPI app.
- App main → Vault routes: registers · Mounts vault endpoints into the FastAPI app.
- App main → PQC metrics: registers · Exposes PQC benchmarking endpoints.
- App main → Security layer: enforces · Applies middleware and request-level security controls.
- Auth routes → Auth utils: uses · Hashes passwords and issues or validates JWTs.
- Auth routes → OTP utils: uses · Creates and checks one-time passwords.
- Auth routes → Email adapter: uses · Delivers OTP and alert emails.
- Auth routes → JWT dependency: protects · Shares bearer-token validation for guarded auth flows.
- OTP utils → SQLite layer: persists · Stores OTP records in SQLite.
- Vault routes → Vault crypto: uses · Performs encrypted CRUD for vault content.
- Vault routes → Security layer: monitors · Feeds decrypt abuse, lockouts, and access-risk events.
- Vault crypto → SQLite layer: persists · Stores ciphertext and encryption metadata in SQLite.
- Vault crypto → Kyber path: requests key · Obtains or reconstructs the AES key via the PQC boundary.
- Kyber path → PQC service: http service · Reached as an external Kyber or ML-KEM microservice.
- Security layer → SQLite layer: records · Writes session, history, and security logs.
- Security layer → Email adapter: alerts · Can trigger security notifications through email.
- Email adapter → Email service: email api · Uses an external delivery provider.
- Password model → SQLite layer: independent of · Runs locally and does not rely on the main auth flow.
- Static pages → Client scripts: loads · Pages are driven by page-specific JavaScript modules.
- Client scripts → App main: calls api · Browser modules invoke the FastAPI backend.
- Deploy config → Hosting runtime: deploys · Describes the managed deployment entrypoint.
- Local DB file → SQLite layer: backing file · Local SQLite file used by the database layer.
- App main → Hosting runtime: runs on · FastAPI application is served by the deployment runtime.