Spaces:
Running
Running
| # TextBro — Flask Backend | |
| The Python/Flask service that powers Text→Video, HTML→Video, and Image/PDF→Video | |
| generation. Originally lived in | |
| [`shiv12345678901/yt-project`](https://github.com/shiv12345678901/yt-project); | |
| now colocated with the React frontend in this repo. | |
| ## Running locally | |
| ```bash | |
| cd backend | |
| python -m venv .venv && source .venv/bin/activate | |
| pip install -r requirements.txt | |
| playwright install chromium | |
| cp config/config.example.py config/config.py # add your API_KEY/API_URL/MODEL | |
| cp .env.example .env # tweak security knobs | |
| python start.py | |
| # → http://127.0.0.1:5000 | |
| ``` | |
| By default the server binds to **127.0.0.1** only — there's no shared-secret | |
| auth out of the box, so don't expose it on a LAN until you set `API_KEY`. | |
| ## Running in production | |
| Use a real WSGI server. The repo ships `wsgi.py` and pins both `gunicorn` | |
| (Linux/Mac) and `waitress` (Windows) in `requirements.txt`: | |
| ```bash | |
| # Linux/Mac | |
| gunicorn -w 4 -b 127.0.0.1:5000 wsgi:app | |
| # Windows | |
| waitress-serve --listen=127.0.0.1:5000 wsgi:app | |
| ``` | |
| `app.run(debug=True)` is **never** invoked unless `FLASK_DEBUG=1` is set, and | |
| `start.py` will refuse to enable debug mode on a non-loopback host. | |
| ## Security configuration | |
| All knobs live in `backend/.env` (see `.env.example`). Defaults are safe for | |
| local dev: | |
| | Variable | Default | Purpose | | |
| | --- | --- | --- | | |
| | `FLASK_DEBUG` | `0` | `1` enables Werkzeug debug + reloader. NEVER on in prod (PIN-protected RCE shell). | | |
| | `FLASK_HOST` | `127.0.0.1` | Bind address. Override only behind an authenticating reverse proxy. | | |
| | `PORT` | `5000` | Listen port. | | |
| | `ALLOWED_ORIGINS` | `http://localhost:5173,http://127.0.0.1:5173,http://localhost:5000,http://127.0.0.1:5000` | CORS allowlist (comma-separated). Wildcard intentionally unsupported. | | |
| | `API_KEY` | _(unset)_ | Shared secret. When set, every non-public request must carry `X-API-Key`. | | |
| | `RATE_LIMIT_DEFAULT` | `200 per hour;30 per minute` | Per-IP global limit. | | |
| | `RATE_LIMIT_HEAVY` | `20 per hour;5 per minute` | Tighter limit on `/generate*`, `/extract-from-image`, `/image-to-screenshots-sse`, `/regenerate`. | | |
| | `RATE_LIMIT_STORAGE_URI` | `memory://` | Switch to e.g. `redis://localhost:6379` when running multiple workers. | | |
| | `MAX_CONTENT_LENGTH_BYTES` | `33554432` | 32 MiB cap on uploaded files. | | |
| ### Public paths (always reachable) | |
| - `GET /healthz` — liveness probe (200 if process is alive). | |
| - `GET /` — index page. | |
| - `GET /static/...` — static assets. | |
| Every other route (including `/screenshots/*` and `/html/*`) requires the API | |
| key when one is configured. | |
| ### Threat model | |
| This is a single-tenant developer tool. The defaults assume: | |
| - The process runs on a trusted machine on a trusted network. | |
| - Only a small group of operators hits the AI / screenshot endpoints. | |
| - Production deployment puts the app behind a reverse proxy that adds TLS | |
| and (optionally) further auth. `API_KEY` is a coarse-grained shared secret, | |
| not user-level auth. | |
| If you need multi-tenant access, swap the `_enforce_api_key` `before_request` | |
| hook for a real auth middleware (OIDC, JWT, etc.). | |
| ## Project layout | |
| ``` | |
| backend/ | |
| ├── app.py # Flask app factory + security middleware | |
| ├── start.py # Dev launcher with preflight checks | |
| ├── wsgi.py # Production WSGI entrypoint (gunicorn / waitress) | |
| ├── requirements.txt | |
| ├── .env.example | |
| ├── config/ | |
| │ └── config.example.py # copy to config.py and fill in | |
| ├── routes/ # generate / html / image / resources blueprints | |
| ├── src/ | |
| │ ├── core/ # AI + vision clients | |
| │ ├── screenshot_engines/ # Playwright wrapper | |
| │ └── utils/ # cache, metrics, ETA, retry helpers | |
| ├── static/ | |
| └── templates/ | |
| ``` | |
| ## Backend endpoints used by the React frontend | |
| | Path | Method | Purpose | | |
| | ----------------------------- | ------ | -------------------------------- | | |
| | `/healthz` | GET | Liveness probe | | |
| | `/generate-sse` | POST | Text → HTML → screenshots (SSE) | | |
| | `/generate-html` | POST | HTML → screenshots | | |
| | `/image-to-screenshots-sse` | POST | Image/PDF → screenshots (SSE) | | |
| | `/cancel/<operation_id>` | POST | Cancel an in-progress generation | | |
| | `/beautify`, `/minify` | POST | HTML helpers | | |
| | `/screenshots/<filename>` | GET | Serve screenshot PNG | | |
| | `/html/<filename>` | GET | Serve HTML | | |
| | `/download-zip` | POST | Bundle files into a ZIP | | |
| | `/list` | GET | List generated files | | |
| | `/delete/<type>/<filename>` | DELETE | Delete a file | | |
| | `/history` | GET | Generation history | | |
| | `/cache/stats`, `/cache/clear` | GET/POST | AI response cache | | |