How code6yte/privshare works
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 Flask app · cli.py CLI tools · storage.py Storage layer · crypto_utils.py Crypto utils
Components 16
Presentation
Server-rendered pages and browser assets
- Templates · Rendered pages for upload, success, download, expired, 404, and about
templates - Static assets · JavaScript and CSS for form behavior and UI styling
static
Application Core
Flask request handling and sharing workflow
- Flask app · Main Flask application with public routes for upload, file access, and health checks
app.py - Upload flow · Coordinates ingest, validation, cleanup, encryption, persistence, and share-link generation
- Download flow · Validates token, checks expiry, asks for password, decrypts, and serves the file
Security
Cleaning and encryption boundary
- Metadata cleaner · Removes file metadata using ExifTool and fallback handlers for different formats
metadata_cleaner.py - Crypto utils · AES-256-GCM encryption and PBKDF2-HMAC-SHA256 key derivation
crypto_utils.py
Data Layer
Database and filesystem persistence
- SQLite DB · Persists token records, expiry, download counts, and file references
db.py - Storage layer · Abstracts working paths and encrypted artifact storage
storage.py - Temp files · Transient staging area for uploads before sealing
storage/tmp - Encrypted blobs · Final encrypted artifacts stored on disk
storage/encrypted_files
Operations
Maintenance and command-line entrypoints
- Cleanup tasks · Expired-file and temp-file cleanup logic
cleanup.py - CLI tools · Database init, record listing, cleanup, and encryption smoke tests
cli.py - Crypto tests · Focused tests for the cryptography subsystem
tests/test_crypto.py
Deploy
Runtime and packaging artifacts
- Config · Central runtime configuration loaded from environment
config.py - Deploy files · Container and process definitions for Docker, Gunicorn, and hosted deployment
Dockerfile
Connections 22
- 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