# gobblergang/server architecture

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

- Interactive diagram: https://gitdiagram.com/gobblergang/server
- Repository: https://github.com/gobblergang/server

## Overview

##### Project Type & Purpose
- This is a monolithic, full-stack backend application written in Python (likely Flask or similar), exposing a RESTful API for secure file sharing.
- Its responsibilities include user authentication, file encryption/decryption, access control, certificate generation (PAC), and persistence in a MySQL/MariaDB database plus the file system.

##### File Structure
- Top-level files:
– run.py (entry point launching the HTTPS server)
– generate_sql.py (build-time script that emits `server_db_schema.sql`)
– server_db_schema.sql (DB schema import artifact)
– requirements.txt (Python dependencies)
– uploads/ (encrypted file store)
- app/ directory:
– __init__.py (app factory or Flask initialization)
– auth.py (nonce-based challenge/response, login/logout, registration)
– files.py (upload, download, share, revoke, delete flows)
– models.py (ORM mappings for users, files, PACs, nonces, etc.)

##### README for Additional Insights
- Security features: end-to-end encryption, digital signatures, PAC system, nonce cleanup job.
- SSL in dev vs. production is fronted by Nginx or reverse proxy.
- Core API endpoints for auth and file operations.

##### Main Components & Their Relationships
a. Clients
- Web/browser or any HTTPS-capable client
- Requests JSON payloads to `/api/...`
b. API Server (Flask app in run.py/app/)
- Modules:
– Authentication (app/auth.py)
– File Service (app/files.py)
– Data Models & ORM (app/models.py)
– Background job (nonce cleanup)
- Encryption/Decryption Library (integrated within file service)
c. Database (MySQL/MariaDB)
- Stores user records, file metadata, PAC certificates, nonces
d. File Storage (local uploads/ folder, encrypted blobs)
e. Certificate Authority Logic (PAC generation & validation inside the app)
f. (Optional Production Nginx Reverse Proxy)
- SSL offload, rate limiting, security headers

##### Architectural Patterns & Design Principles
- Monolithic REST API (container)
- MVC-style separation:
- Models (ORM layer)
- Controllers (auth.py, files.py)
- E2E Encryption ensures that file payloads are encrypted before persistence
- Nonce-based challenge/response for replay protection
- PAC system as an internal certificate authority micro-subsystem
- Background scheduler or cron-like job for nonce cleanup

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Systems
    Client["Client (Web Browser/HTTPS)"]:::external
    Proxy["Nginx Reverse Proxy"]:::external
    Client -->|"HTTPS JSON"| Proxy

    %% API Container
    subgraph "Secure File Sharing API"
        direction TB
        entry["run.py\nApp Entry Point"]:::script
        init["Flask Init\napp/__init__.py"]:::script

        subgraph "Modules & Components"
            direction TB
            Auth["Auth Module"]:::component
            Files["File Service Module"]:::component
            PAC["PAC Logic"]:::component
            Models["Models Layer"]:::component
            Cleanup["Nonce Cleanup Job"]:::component
        end

        entry --> init
        init --> Auth
        init --> Files
        Auth -->|"ORM Calls"| Models
        Files -->|"ORM Calls"| Models
        Files -->|"Invoke PAC"| PAC
        PAC -->|"Persist/Fetch"| Models
        Auth -->|"SQL Queries"| Models
        Cleanup -->|"Cleanup Nonces via ORM"| Models
    end

    Proxy -->|"HTTPS JSON"| entry

    %% Databases & Storage
    DB["MySQL/MariaDB"]:::db
    FS["File Storage\n(uploads/)"]:::storage
    Models -->|"SQL INSERT/SELECT"| DB
    Files -->|"Read/Write Encrypted Blob"| FS

    %% Build & Provisioning
    GenSQL["generate_sql.py"]:::script
    Schema["server_db_schema.sql"]:::script
    GenSQL --> Schema
    Schema --> DB

    %% Project Files
    Req["requirements.txt"]:::script
    Readme["README.md"]:::script

    %% Click Events
    click Auth "https://github.com/gobblergang/server/blob/main/app/auth.py"
    click Files "https://github.com/gobblergang/server/blob/main/app/files.py"
    click Models "https://github.com/gobblergang/server/blob/main/app/models.py"
    click init "https://github.com/gobblergang/server/blob/main/app/__init__.py"
    click entry "https://github.com/gobblergang/server/blob/main/run.py"
    click GenSQL "https://github.com/gobblergang/server/blob/main/generate_sql.py"
    click Schema "https://github.com/gobblergang/server/blob/main/server_db_schema.sql"
    click FS "https://github.com/gobblergang/server/tree/main/uploads/"
    click Req "https://github.com/gobblergang/server/blob/main/requirements.txt"
    click Readme "https://github.com/gobblergang/server/blob/main/README.md"

    %% Styles
    classDef external fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef component fill:#90EE90,stroke:#333,stroke-width:1px
    classDef script fill:#D3D3D3,stroke:#333,stroke-width:1px
    classDef db fill:#ADD8E6,stroke:#333,stroke-width:1px,shape:cylinder
    classDef storage fill:#ADD8E6,stroke:#333,stroke-width:1px,shape:cylinder
```
