# code6yte/privshare architecture

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

- Interactive diagram: https://gitdiagram.com/code6yte/privshare
- Repository: https://github.com/code6yte/privshare

## Overview

1. **Overall shape**
   - This is a single-service Flask application for privacy-preserving file sharing.
   - The core pipeline is: **upload file + password → remove metadata → encrypt → persist encrypted artifact + DB record → share token link → receiver supplies password → decrypt → download**.

2. **HTTP application boundary**
   - `app.py` is the main web entrypoint and exposes the public routes documented in the README:
     - `/` upload form
     - `/upload` handle file ingest and link generation
     - `/file/<token>` password entry and download flow
     - `/health` readiness/health check
   - The app is served locally via Flask and in production via Gunicorn or Docker.

3. **Presentation layer**
   - `templates/` contains the server-rendered pages for upload, success, download, expired, 404, and about.
   - `static/` holds the client-side assets (`script.js`, `style.css`), which appear to support form behavior and UI polish rather than being the primary application boundary.

4. **File ingest and sharing workflow**
   - The upload path likely coordinates several steps in sequence:
     1. accept uploaded file from the form
     2. validate and stage it in `storage/tmp/`
     3. strip metadata where possible
     4. encrypt the cleaned file
     5. store final ciphertext in `storage/encrypted_files/`
     6. persist a record in SQLite
     7. return a tokenized share link
   - The token, not the password, identifies the shared file.

5. **Security and cryptography subsystem**
   - `crypto_utils.py` contains the encryption primitives.
   - The README indicates **AES-256-GCM** for authenticated encryption and **PBKDF2-HMAC-SHA256** with 390,000 iterations for key derivation.
   - The security boundary is important: the password is used to derive a key, but is **never stored** and is **not placed in URLs**.
   - `tests/test_crypto.py` suggests this module is tested separately from the web layer.

6. **Metadata cleaning subsystem**
   - `metadata_cleaner.py` and `cleanup.py` implement the privacy-preserving preprocessing step.
   - The README names the cleaning tools and fallbacks:
     - ExifTool as the main metadata remover
     - Pillow for image fallback
     - pypdf for PDF fallback
     - Office document docProps stripping
     - ZIP extraction/rewrapping for archives
   - This subsystem sits between upload and encryption, reducing leakage before files are sealed.

7. **Persistence and file storage**
   - `db.py` manages the SQLite database.
   - `storage.py` likely abstracts filesystem paths and record/file operations.
   - The storage layout is split into:
     - `storage/tmp/` for transient working files
     - `storage/encrypted_files/` for final encrypted blobs
   - This creates a clear boundary between intermediate processing and durable storage.

8. **Operational/maintenance boundary**
   - `cli.py` provides administrative commands:
     - initialize the database
     - clean expired files
     - list file records
     - run an encryption smoke test
   - `cleanup.py` likely supports the expired-file deletion lifecycle.
   - This means expiration is not just a request-time concern; there is also a batch maintenance path.

9. **Configuration and deployment**
   - `config.py` centralizes runtime settings.
   - `.env.example` indicates environment-driven configuration.
   - Deployment artifacts include:
     - `Dockerfile`
     - `docker-compose.yml`
     - `Procfile`
     - `render.yaml`
   - The README also mentions Docker, Gunicorn, and Render/Railway, so the app is designed to run as a containerized web service with externalized config.

10. **Data model and lifecycle concerns**
   - From the README, the DB likely tracks token, filename, expiry, and download count.
   - The system supports configurable link expiry and file download tracking, so the database is part of the security/retention model, not just metadata storage.

11. **Security model**
   - `SECURITY.md` and `THREAT_MODEL.md` indicate explicit security documentation.
   - The important architectural trust boundaries are:
     - browser/client vs server
     - plaintext upload vs cleaned/encrypted storage
     - token link vs password
     - active file vs expired/deleted file
   - The design intentionally minimizes server-side knowledge of user secrets.

12. **Repository-level testing and validation**
   - Current test coverage is focused on crypto (`tests/test_crypto.py`), implying cryptographic correctness is a critical invariant.
   - The presence of docs like `ARCHITECTURE.md` and `PROJECT.md` suggests the repo treats architecture and operational behavior as first-class concerns.

13. **External dependencies that materially affect architecture**
   - ExifTool is a required system dependency and materially shapes the metadata-cleaning stage.
   - SQLite is the persistence engine.
   - Gunicorn is the production WSGI server.
   - Docker is used to package the app and its native dependency footprint.

14. **How to draw the diagram**
   - A good architecture diagram would show:
     - **Browser/UI** on the left
     - **Flask app** in the center with routes/controllers
     - separate internal boxes for **metadata cleaning**, **encryption/key derivation**, **storage**, and **SQLite DB**
     - **CLI/maintenance jobs** as a parallel operational path
     - **encrypted files on disk** as the durable artifact
     - **expired-file cleanup** as a scheduled or manual background action
   - The main arrowed flow should emphasize that the server handles plaintext only transiently, then persists only cleaned/encrypted data.

Main entry points: [`app.py`](https://github.com/code6yte/privshare/blob/main/app.py) (Flask app), [`cli.py`](https://github.com/code6yte/privshare/blob/main/cli.py) (CLI tools), [`storage.py`](https://github.com/code6yte/privshare/blob/main/storage.py) (Storage layer), [`crypto_utils.py`](https://github.com/code6yte/privshare/blob/main/crypto_utils.py) (Crypto utils)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_presentation["Presentation"]
  node_tmpl["Templates<br/>server pages"]
  node_assets["Static assets<br/>client assets"]
end

subgraph group_core["Application Core"]
  node_app["Flask app<br/>web entrypoint<br/>[app.py]"]
  node_upload_flow["Upload flow<br/>request pipeline"]
  node_share_flow["Download flow<br/>request pipeline"]
end

subgraph group_security["Security"]
  node_cleaner["Metadata cleaner<br/>sanitizer"]
  node_crypto["Crypto utils<br/>AEAD + KDF<br/>[crypto_utils.py]"]
end

subgraph group_data["Data Layer"]
  node_db[("SQLite DB<br/>metadata store<br/>[db.py]")]
  node_storage["Storage layer<br/>filesystem adapter<br/>[storage.py]"]
  node_tmpdir["Temp files<br/>scratch space"]
  node_encdir[("Encrypted blobs<br/>durable files")]
end

subgraph group_ops["Operations"]
  node_cleanup["Cleanup tasks<br/>retention<br/>[cleanup.py]"]
  node_cli["CLI tools<br/>admin commands<br/>[cli.py]"]
  node_tests_crypto["Crypto tests<br/>verification<br/>[test_crypto.py]"]
end

subgraph group_deploy["Deploy"]
  node_config["Config<br/>settings<br/>[config.py]"]
  node_docker["Deploy files<br/>runtime packaging"]
end

node_app -->|"renders"| node_tmpl
node_app -->|"uses"| node_assets
node_app -->|"handles"| node_upload_flow
node_app -->|"handles"| node_share_flow
node_upload_flow -->|"stages"| node_tmpdir
node_upload_flow -->|"cleans"| node_cleaner
node_upload_flow -->|"encrypts"| node_crypto
node_upload_flow -->|"persists"| node_storage
node_storage -->|"writes"| node_encdir
node_storage -->|"records"| node_db
node_share_flow -->|"looks up"| node_db
node_share_flow -->|"decrypts"| node_crypto
node_share_flow -->|"reads"| node_storage
node_cleanup -->|"prunes"| node_db
node_cleanup -->|"deletes"| node_encdir
node_cli -->|"manages"| node_db
node_cli -->|"invokes"| node_cleanup
node_cli -->|"tests"| node_crypto
node_config -->|"configures"| node_app
node_config -->|"configures"| node_cli
node_docker -->|"packages"| node_app
node_tests_crypto -->|"verifies"| node_crypto

click node_app "https://github.com/code6yte/privshare/blob/main/app.py"
click node_tmpl "https://github.com/code6yte/privshare/tree/main/templates"
click node_assets "https://github.com/code6yte/privshare/tree/main/static"
click node_cleaner "https://github.com/code6yte/privshare/blob/main/metadata_cleaner.py"
click node_cleanup "https://github.com/code6yte/privshare/blob/main/cleanup.py"
click node_crypto "https://github.com/code6yte/privshare/blob/main/crypto_utils.py"
click node_db "https://github.com/code6yte/privshare/blob/main/db.py"
click node_storage "https://github.com/code6yte/privshare/blob/main/storage.py"
click node_tmpdir "https://github.com/code6yte/privshare/tree/main/storage/tmp"
click node_encdir "https://github.com/code6yte/privshare/tree/main/storage/encrypted_files"
click node_cli "https://github.com/code6yte/privshare/blob/main/cli.py"
click node_config "https://github.com/code6yte/privshare/blob/main/config.py"
click node_docker "https://github.com/code6yte/privshare/tree/main/Dockerfile"
click node_tests_crypto "https://github.com/code6yte/privshare/blob/main/tests/test_crypto.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_tmpl,node_assets toneBlue
class node_app,node_upload_flow,node_share_flow toneAmber
class node_cleaner,node_crypto toneMint
class node_db,node_storage,node_tmpdir,node_encdir toneRose
class node_cleanup,node_cli,node_tests_crypto toneIndigo
class node_config,node_docker toneTeal
```

## Components

### Presentation

Server-rendered pages and browser assets

- [Templates](https://github.com/code6yte/privshare/tree/main/templates): server pages · Rendered pages for upload, success, download, expired, 404, and about · `templates`
- [Static assets](https://github.com/code6yte/privshare/tree/main/static): client assets · JavaScript and CSS for form behavior and UI styling · `static`

### Application Core

Flask request handling and sharing workflow

- [Flask app](https://github.com/code6yte/privshare/blob/main/app.py): web entrypoint · Main Flask application with public routes for upload, file access, and health checks · `app.py`
- **Upload flow**: request pipeline · Coordinates ingest, validation, cleanup, encryption, persistence, and share-link generation
- **Download flow**: request pipeline · Validates token, checks expiry, asks for password, decrypts, and serves the file

### Security

Cleaning and encryption boundary

- [Metadata cleaner](https://github.com/code6yte/privshare/blob/main/metadata_cleaner.py): sanitizer · Removes file metadata using ExifTool and fallback handlers for different formats · `metadata_cleaner.py`
- [Crypto utils](https://github.com/code6yte/privshare/blob/main/crypto_utils.py): AEAD + KDF · AES-256-GCM encryption and PBKDF2-HMAC-SHA256 key derivation · `crypto_utils.py`

### Data Layer

Database and filesystem persistence

- [SQLite DB](https://github.com/code6yte/privshare/blob/main/db.py): metadata store · Persists token records, expiry, download counts, and file references · `db.py`
- [Storage layer](https://github.com/code6yte/privshare/blob/main/storage.py): filesystem adapter · Abstracts working paths and encrypted artifact storage · `storage.py`
- [Temp files](https://github.com/code6yte/privshare/tree/main/storage/tmp): scratch space · Transient staging area for uploads before sealing · `storage/tmp`
- [Encrypted blobs](https://github.com/code6yte/privshare/tree/main/storage/encrypted_files): durable files · Final encrypted artifacts stored on disk · `storage/encrypted_files`

### Operations

Maintenance and command-line entrypoints

- [Cleanup tasks](https://github.com/code6yte/privshare/blob/main/cleanup.py): retention · Expired-file and temp-file cleanup logic · `cleanup.py`
- [CLI tools](https://github.com/code6yte/privshare/blob/main/cli.py): admin commands · Database init, record listing, cleanup, and encryption smoke tests · `cli.py`
- [Crypto tests](https://github.com/code6yte/privshare/blob/main/tests/test_crypto.py): verification · Focused tests for the cryptography subsystem · `tests/test_crypto.py`

### Deploy

Runtime and packaging artifacts

- [Config](https://github.com/code6yte/privshare/blob/main/config.py): settings · Central runtime configuration loaded from environment · `config.py`
- [Deploy files](https://github.com/code6yte/privshare/tree/main/Dockerfile): runtime packaging · Container and process definitions for Docker, Gunicorn, and hosted deployment · `Dockerfile`

## Connections

- Flask app → Templates: renders · Serves HTML pages for upload, success, download, and error states
- Flask app → Static assets: uses · Loads client-side JavaScript and CSS
- Flask app → Upload flow: handles · Upload request processing
- Flask app → Download flow: handles · Token/password download request processing
- Upload flow → Temp files: stages · Writes temporary working files during preprocessing
- Upload flow → Metadata cleaner: cleans · Strips metadata before sealing
- Upload flow → Crypto utils: encrypts · Derives a key and encrypts the cleaned file
- Upload flow → Storage layer: persists · Stores encrypted artifacts and file references
- Storage layer → Encrypted blobs: writes · Places final ciphertext on disk
- Storage layer → SQLite DB: records · Stores token and lifecycle metadata
- Download flow → SQLite DB: looks up · Resolves token, expiry, and file metadata
- Download flow → Crypto utils: decrypts · Uses the submitted password to derive the decryption key
- Download flow → Storage layer: reads · Fetches encrypted blobs for download
- Cleanup tasks → SQLite DB: prunes · Removes expired records
- Cleanup tasks → Encrypted blobs: deletes · Removes expired encrypted files
- CLI tools → SQLite DB: manages · Initializes and inspects the database
- CLI tools → Cleanup tasks: invokes · Runs maintenance workflows
- CLI tools → Crypto utils: tests · Runs encryption smoke checks
- Config → Flask app: configures · Feeds runtime settings into the web app
- Config → CLI tools: configures · Feeds runtime settings into command-line tools
- Deploy files → Flask app: packages · Defines the production runtime and container deployment
- Crypto tests → Crypto utils: verifies · Covers cryptographic primitives and invariants
