From 5beef03233605a1cafdccdd106ebdf847a85a4fa Mon Sep 17 00:00:00 2001
From: OpenCode Bot <bot@example.com>
Date: Wed, 29 Apr 2026 22:45:15 +0800
Subject: [PATCH] docs(readme): add project README with setup, features, and
 usage

---
 README.md | 76 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 76 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..f4eed37
--- /dev/null
+++ b/README.md
@@ -0,0 +1,76 @@
+# Temp File Transfer Service
+
+A Flask-based personal temporary file sharing service with a Web UI, API access, and SQLite-backed metadata.
+
+What it does
+- Upload files via a Web UI or an API endpoint
+- Choose an expiry: 1 hour, 24 hours, or 7 days
+- Generate a share URL (UUID) for downloaded access
+- File data stored on disk; metadata stored in SQLite
+- Web-based download page and a simple API for programmatic uploads
+
+Tech stack
+- Flask (Python)
+- SQLite (metadata)
+- Filesystem storage for actual file data
+
+Local development setup
+1. Prerequisites
+- Python 3.8+ (the project currently uses Python 3.x in this environment)
+- pip
+
+2. Install dependencies
+```bash
+pip install -r requirements.txt
+```
+
+3. Run the server
+```bash
+python app.py
+```
+
+4. Access
+- Web UI: http://localhost:5000
+- API: see /api/upload and /api/file endpoints
+
+Project layout
+- app.py               # Flask application
+- config.py            # Configuration constants
+- database.py          # SQLite helpers and data access
+- requirements.txt     # Python dependencies
+- templates/            # Jinja templates (index.html, download.html)
+- upload_client.py      # Simple API client example for testing
+- uploads/              # Storage for uploaded files (created at runtime)
+
+Data model (SQLite)
+- Table: files
+  - id TEXT PRIMARY KEY
+  - filename TEXT
+  - filepath TEXT
+  - filesize INTEGER
+  - expiry_hours INTEGER
+  - created_at TIMESTAMP
+  - expires_at TIMESTAMP
+
+Expiry and cleanup
+- Expiry options are defined as 1h, 24h, 7d in config
+- A cleanup operation removes expired files from disk and deletes DB rows
+- Cleanup is invoked on access endpoints (and can be wired to a cron/daemon later)
+
+Security notes
+- Do not commit secrets. Secrets should be provided via environment variables in production.
+- This repository currently avoids embedding credentials.
+
+Next steps (optional)
+- Add authentication for admin/API usage
+- Add rate limiting and upload size limits per user
+- Add automated tests and CI integration
+
+License
+- MIT or your preferred license (update as needed)
+
+Contributing
+- Pull requests are welcome. Please follow the project style and ensure tests pass.
+
+Contact
+- If you need to reach the maintainer, use your preferred channel.