# fullerzz/smolvault architecture

> Architecture diagram of the GitHub repository fullerzz/smolvault, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/fullerzz/smolvault
- Repository: https://github.com/fullerzz/smolvault

## Overview

##### Project type and purpose
- Smolvault is a backend‐only, self‐hosted file storage service. It’s a Python REST API built with FastAPI, designed to run on a Raspberry Pi.
- Responsibilities: manage users, store file metadata in SQLite, store file contents in S3, and cache files locally for faster subsequent downloads.

##### File structure
- Top‐level:
- src/smolvault – core application code
– auth/ (token decoding, auth models)
– cache/ (cache_manager.py)
– clients/ (AWS S3 & SQLite DB clients)
– main.py, config.py, models.py, validators/
- scripts/ – startup/test shell scripts
- terraform/ – IaC to provision AWS IAM roles, policies & S3 bucket
- tests/ – pytest suite covering API endpoints, cache, security
- CI config in .github/workflows
- Key configuration: logging.conf, pyproject.toml, requirements.txt

##### README for additional insights
- Confirms FastAPI, SQLite for metadata, AWS S3 for storage, local file caching on server.
- Terraform directory provisions IAM resources & S3 bucket.

- Client (curl/HTTP client)
- FastAPI Application
– Authentication Module
– Request Validation
– Business Logic
– Cache Manager
- SQLite Database (metadata store)
- Local File Cache (filesystem on Raspberry Pi)
- AWS S3 Bucket (remote object store)
- AWS IAM (roles/policies provisioned by Terraform)
- Terraform (IaC controller)
- CI/CD pipelines (GitHub Actions) – optional overlay

b. Relationships & interactions:
1. Client → FastAPI (HTTPS)
2. Auth Module ↔ JWT Decoder → validators
3. FastAPI → SQLite Client → metadata table
4. FastAPI → AWS S3 Client → S3 bucket (PUT/GET)
5. File GET: check Local Cache → hit? serve. miss? fetch from S3 → write Local Cache → serve.
6. Terraform → AWS (IAM & S3 provisioning)
7. GitHub Actions → on push: run tests, linters, gitleaks

c. Architectural patterns & principles:
- Layered API design (routing → validation → business logic → data access)
- Dependency‐injection via FastAPI’s DI for clients & config
- Separation of concerns: auth, caching, storage, validation modules
- Infrastructure as code for repeatable AWS resource provisioning

d. Relevant technologies & frameworks:
- FastAPI, Pydantic (models & validation)
- SQLite (sqlite3 or SQLAlchemy client)
- boto3 (AWS S3)
- Terraform (IaC)
- pytest, pytest-factoryboy for testing
- GitHub Actions for CI/CD

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Client
    Client["HTTP Client (curl)"]:::external

    %% Raspberry Pi Host
    subgraph "Raspberry Pi Host"
        subgraph "FastAPI Application"
            main["main.py"]:::app
            config["config.py"]:::app
            subgraph "Authentication Module"
                decoder["decoder.py"]:::app
                auth_models["models.py"]:::app
            end
            validator["operation_validator.py"]:::app
            subgraph "Business Logic"
                core_models["models.py"]:::app
                tasks["tasks.py"]:::app
            end
            cache_mgr["cache_manager.py"]:::app
            db_client["database.py"]:::app
            aws_client["aws.py"]:::app
        end
        LocalCache["Local File Cache\n(filesystem)"]:::external
        SQLiteDB["SQLite DB File"]:::external
    end

    %% AWS Services
    S3["AWS S3 Bucket"]:::external
    IAM["AWS IAM Roles & Policies"]:::external

    %% IaC and CI/CD
    Terraform["Terraform IaC"]:::devops
    CICD["GitHub Actions CI/CD"]:::devops

    %% Connections
    Client -->|"HTTPS"| main
    main -->|"loads config"| config
    main -->|"calls Auth"| decoder
    main -->|"uses Auth Models"| auth_models
    main -->|"validates requests"| validator
    main -->|"invokes business logic"| core_models
    main -->|"runs tasks"| tasks
    core_models -->|"uses cache"| cache_mgr
    cache_mgr -->|"reads/writes"| LocalCache
    core_models -->|"queries metadata"| db_client
    db_client -->|"reads/writes"| SQLiteDB
    core_models -->|"uploads/downloads"| aws_client
    aws_client -->|"PUT/GET via boto3"| S3

    Terraform -->|"provisions"| IAM
    Terraform -->|"provisions"| S3

    CICD -->|"on push: tests, linters, scans"| main

    %% Click Events
    click main "https://github.com/fullerzz/smolvault/blob/main/src/smolvault/main.py"
    click config "https://github.com/fullerzz/smolvault/blob/main/src/smolvault/config.py"
    click decoder "https://github.com/fullerzz/smolvault/blob/main/src/smolvault/auth/decoder.py"
    click auth_models "https://github.com/fullerzz/smolvault/blob/main/src/smolvault/auth/models.py"
    click validator "https://github.com/fullerzz/smolvault/blob/main/src/smolvault/validators/operation_validator.py"
    click core_models "https://github.com/fullerzz/smolvault/blob/main/src/smolvault/models.py"
    click tasks "https://github.com/fullerzz/smolvault/blob/main/tasks.py"
    click cache_mgr "https://github.com/fullerzz/smolvault/blob/main/src/smolvault/cache/cache_manager.py"
    click db_client "https://github.com/fullerzz/smolvault/blob/main/src/smolvault/clients/database.py"
    click aws_client "https://github.com/fullerzz/smolvault/blob/main/src/smolvault/clients/aws.py"
    click Terraform "https://github.com/fullerzz/smolvault/tree/main/terraform/"
    click CICD "https://github.com/fullerzz/smolvault/tree/main/.github/workflows/"

    %% Styles
    classDef app fill:#ccffcc,stroke:#006600,stroke-width:1px
    classDef external fill:#cce5ff,stroke:#004085,stroke-width:1px
    classDef devops fill:#ffe5cc,stroke:#cc5200,stroke-width:1px
```
