From a3bb1b3dd6c12b8275587fb8ba15677fa944f86f Mon Sep 17 00:00:00 2001
From: Kharec <sandro@cazzaniga.fr>
Date: Thu, 6 Nov 2025 07:53:45 +0100
Subject: [PATCH] docs: add readme

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

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..0ee56c2
--- /dev/null
+++ b/README.md
@@ -0,0 +1,143 @@
+# Flado
+
+Flado is the usual todo list app project everyone does once (or more) in their lives, here built with Python, Flask, and SQLite.
+
+I hacked it overnight, mainly to refresh my (very poor) frontend skills.
+
+<img width="849" height="744" alt="flado-screen" src="https://github.com/user-attachments/assets/021125e3-d0db-4263-a9e9-3c943ea4dd47" />
+
+## Highlights
+
+- Minimal, responsive UI on desktop and mobile.
+- Fast task capture with inline editing and keyboard shortcuts.
+- Smart filters for today, upcoming, completed, and custom views.
+- SQLite-powered persistence with a lightweight schema that is easy to deploy anywhere.
+- Uses Flask-WTF for CSRF protection.
+- Clean Flask blueprints and service layers.
+
+## Quick Start (for development)
+
+```bash
+# 1. Create and activate a virtual environment
+python -m venv .venv
+source .venv/bin/activate  # On Windows use `.venv\Scripts\activate`
+
+# 2. Install dependencies
+pip install -r requirements.txt
+
+# 3. Set environment variables for Flask
+export FLASK_APP=flado.app:create_app
+export FLASK_DEBUG=1
+
+# 4. Initialize the SQLite database (instance/flado.sqlite by default)
+flask db init
+flask db migrate -m "Initial migration"
+flask db upgrade
+
+# 5. Run the development server
+flask run --debug
+```
+
+The SQLite database file is stored in the `instance/` directory (it remains outside of version control by default).
+
+## Configuration
+
+Environment variables can tweak runtime behavior:
+
+- `FLASK_DEBUG`: Set to `1`, `true`, `yes` to enable debug mode (development mode). When not set or set to any other value, production mode is enabled.
+- `FLADO_DATABASE_URI`: Override the default SQLite path (`sqlite:///instance/flado.sqlite`).
+- `FLADO_SECRET_KEY`: Provide a secret key for session cookies.
+- `FLADO_THEME`: Switch between built-in themes such as `light`, `dark`, or `auto`.
+
+So you can create a `.env` file if you want:
+
+```bash
+cp .env.example .env
+```
+
+Note that `FLADO_SECRET_KEY` is **mandatory in production mode** (when not running in debug mode).
+
+## Usage
+
+- **Add tasks:** Use the quick-add form at the top of the list and press <kbd>Enter</kbd> to save it instantly.
+- **Organize:** Drag and drop to reorder, toggle completion with a single click, and assign due dates or notes in the details panel.
+- **Focus:** Switch to _Today_ or _Upcoming_ filters to keep attention on what matters.
+
+## Project Structure
+
+```
+flado/
+├── flado/                    # Main application package
+│   ├── app.py                # Flask app factory/entry point
+│   ├── blueprints.py         # Blueprint registration and routes
+│   ├── models.py             # SQLAlchemy models
+│   ├── services.py           # Business logic helpers
+│   └── templates/            # Jinja2 HTML templates
+├── instance/                 # Instance directory (SQLite DB lives here)
+├── migrations/               # Alembic migration files
+├── static/                   # CSS, JS, images, favicon, etc.
+├── Dockerfile                # Docker build file
+├── .env.example              # Example environment config for Docker/production
+├── README.md                 # This file
+├── requirements.txt          # Python dependencies
+└── wsgi.py                   # WSGI entry point for production deployment (optional)
+```
+
+## Deployment
+
+If you want to deploy this on your own VPS because you love this application so much (it's your right), then you can use the Dockerfile to build the Docker image:
+
+```bash
+docker build -t flado .
+```
+
+And run the container either in the most simple way (`FLADO_SECRET_KEY` is mandatory in production mode):
+
+```bash
+docker run --name flado -d -p 5000:5000 -e FLADO_SECRET_KEY=your-secret-key flado
+```
+
+To use environment variables from `.env`:
+
+```bash
+docker run --name flado -d -p 5000:5000 --env-file .env flado
+```
+
+To use just one variable without `.env`:
+
+```bash
+docker run --name flado -d -p 5000:5000 -e FLADO_THEME=dark flado
+```
+
+To use a volume to persist the database:
+
+```bash
+docker run --name flado -d -p 5000:5000 -v flado-data:/app/instance flado
+```
+
+Because Flado relies on SQLite, you can deploy on small VPS instances or use `sqlite3` backups to keep data portable.
+
+## Gunicorn (production)
+
+If you want to use Gunicorn to serve the application, setup `.env` with a `FLADO_SECRET_KEY` and use the following command:
+
+```bash
+gunicorn --bind 0.0.0.0:5000 --workers 2 --timeout 120 --access-logfile - --error-logfile - wsgi:app
+```
+
+This will start the application with 2 workers and a timeout of 120 seconds.
+
+## Contributing
+
+Pull requests and feedback are welcome! Open an issue to discuss new ideas or fixes.
+
+When submitting changes, please follow these steps:
+
+1. Fork and clone the repository.
+2. Create a feature branch (`git checkout -b feature/amazing-idea`).
+3. Add tests if you want to (optional).
+4. Submit a pull request describing your changes.
+
+## License
+
+This project is released under the [BSD 3-Clause License](LICENSE).