docs/ARCHITECTURE.md

Architecture

TextBro is a React/Vite client backed by the importable backend Python package. Flask owns HTTP transport; queued workflows own generation; SQLite owns metadata; generated media remains on disk.

Export flow

1. A client posts text, HTML, YouTube metadata, or screenshots to /runs/*.
2. The backend creates a persisted run and queues a WorkflowContext job.
3. AI, Playwright, and export stages publish one normalized event format.
4. /runs/<run_id>/events streams those events. Polling /runs/<run_id> is a safe fallback after network interruption.
5. Linux selects direct FFmpeg. Static/cut-only slides use sparse VFR frames; transitions use FFmpeg filters. Voiceovers, narration, music, watermarks, and intro/outro clips stay in FFmpeg. MoviePy is compatibility-only.
6. Windows retains the PowerPoint COM engine.

POST /generate-sse is a deprecated transport adapter. It submits to the same tracked run pipeline and translates persisted events; it contains no active generation orchestration.

Runtime boundaries

• backend/src/settings.py: immutable typed environment settings.
• backend/src/core: queue, workflows, AI clients, and run lifecycle.
• backend/src/storage: SQLite schema, migration, and retention.
• backend/src/video_engine.py: engine selection and media composition.
• backend/routes: HTTP validation and response translation.
• frontend/src/api: the supported browser contract.

The contract is available at GET /openapi.json. Request logs are JSON and carry request_id; workflow logs add run_id, operation_id, engine, stage, progress, and ETA.