From aa0f79fe757319cef419f20de87f16a89f8060bf Mon Sep 17 00:00:00 2001 From: zwitschi Date: Sat, 30 May 2026 19:51:30 +0200 Subject: [PATCH] feat: update documentation, adjust numbering of arc42 files --- backend/README.md | 68 +++++++++++++++++++ ...-goals.md => 01-introduction-and-goals.md} | 0 docs/{2-constraints.md => 02-constraints.md} | 0 ...t-and-scope.md => 03-context-and-scope.md} | 0 ...on-strategy.md => 04-solution-strategy.md} | 0 ...lock-view.md => 05-building-block-view.md} | 0 .../{6-runtime-view.md => 06-runtime-view.md} | 0 ...ployment-view.md => 07-deployment-view.md} | 0 ...oncepts.md => 08-crosscutting-concepts.md} | 0 .../{8.1-openrouter.md => 08.1-openrouter.md} | 0 docs/{8.2-database.md => 08.2-database.md} | 0 ...sions.md => 09-architectural-decisions.md} | 0 docs/ARCHITECTURE.md | 20 +++--- frontend/README.md | 57 ++++++++++++++++ 14 files changed, 135 insertions(+), 10 deletions(-) create mode 100644 backend/README.md rename docs/{1-introduction-and-goals.md => 01-introduction-and-goals.md} (100%) rename docs/{2-constraints.md => 02-constraints.md} (100%) rename docs/{3-context-and-scope.md => 03-context-and-scope.md} (100%) rename docs/{4-solution-strategy.md => 04-solution-strategy.md} (100%) rename docs/{5-building-block-view.md => 05-building-block-view.md} (100%) rename docs/{6-runtime-view.md => 06-runtime-view.md} (100%) rename docs/{7-deployment-view.md => 07-deployment-view.md} (100%) rename docs/{8-crosscutting-concepts.md => 08-crosscutting-concepts.md} (100%) rename docs/{8.1-openrouter.md => 08.1-openrouter.md} (100%) rename docs/{8.2-database.md => 08.2-database.md} (100%) rename docs/{9-architectural-decisions.md => 09-architectural-decisions.md} (100%) create mode 100644 frontend/README.md diff --git a/backend/README.md b/backend/README.md new file mode 100644 index 0000000..036d0de --- /dev/null +++ b/backend/README.md @@ -0,0 +1,68 @@ +# Backend — FastAPI REST API + +REST API for authentication, user management, AI generation (text/image/video), and admin operations. + +## Tech Stack + +| Layer | Choice | +| ----------- | ----------------------------- | +| Framework | FastAPI | +| Database | DuckDB (embedded) | +| HTTP client | httpx (OpenRouter proxy) | +| Auth | JWT (access + refresh tokens) | +| Server | uvicorn | + +## Project Structure + +```txt +backend/ + app/ + __init__.py Package init (empty) + main.py FastAPI app — lifespan, CORS, router registration + db.py DuckDB singleton, schema migrations, write lock + dependencies.py Dependency injection (get_current_user, etc.) + models/ Pydantic + DB models + __init__.py + auth.py Auth schemas (login, register, token) + users.py User schemas + ai.py AI generation request/response schemas + routers/ API route handlers + __init__.py + auth.py POST /auth/login, /auth/register, /auth/logout + users.py GET/PUT /users/me, admin user management + admin.py GET /admin/stats, video job admin CRUD + ai.py GET /models + generate.py POST /generate/text, /generate/image, /generate/video + images.py GET/POST /images, /images//file + models.py Model cache management + services/ Business logic + __init__.py + auth.py Auth logic (password hashing, JWT) + users.py User CRUD + openrouter.py OpenRouter API client + models.py Model listing and cache + video_worker.py Background video generation worker + tests/ pytest suite + Dockerfile Production container + requirements.txt Runtime dependencies + requirements-dev.txt Dev dependencies +``` + +## Running locally + +```bash +cd backend +uvicorn app.main:app --reload --port 12015 +``` + +API docs at [http://localhost:12015/docs](http://localhost:12015/docs). + +## Running tests + +```bash +pytest backend/tests/ +``` + +## Architecture + +See [docs/ARCHITECTURE.md](../docs/ARCHITECTURE.md) for full documentation (arc42 template). diff --git a/docs/1-introduction-and-goals.md b/docs/01-introduction-and-goals.md similarity index 100% rename from docs/1-introduction-and-goals.md rename to docs/01-introduction-and-goals.md diff --git a/docs/2-constraints.md b/docs/02-constraints.md similarity index 100% rename from docs/2-constraints.md rename to docs/02-constraints.md diff --git a/docs/3-context-and-scope.md b/docs/03-context-and-scope.md similarity index 100% rename from docs/3-context-and-scope.md rename to docs/03-context-and-scope.md diff --git a/docs/4-solution-strategy.md b/docs/04-solution-strategy.md similarity index 100% rename from docs/4-solution-strategy.md rename to docs/04-solution-strategy.md diff --git a/docs/5-building-block-view.md b/docs/05-building-block-view.md similarity index 100% rename from docs/5-building-block-view.md rename to docs/05-building-block-view.md diff --git a/docs/6-runtime-view.md b/docs/06-runtime-view.md similarity index 100% rename from docs/6-runtime-view.md rename to docs/06-runtime-view.md diff --git a/docs/7-deployment-view.md b/docs/07-deployment-view.md similarity index 100% rename from docs/7-deployment-view.md rename to docs/07-deployment-view.md diff --git a/docs/8-crosscutting-concepts.md b/docs/08-crosscutting-concepts.md similarity index 100% rename from docs/8-crosscutting-concepts.md rename to docs/08-crosscutting-concepts.md diff --git a/docs/8.1-openrouter.md b/docs/08.1-openrouter.md similarity index 100% rename from docs/8.1-openrouter.md rename to docs/08.1-openrouter.md diff --git a/docs/8.2-database.md b/docs/08.2-database.md similarity index 100% rename from docs/8.2-database.md rename to docs/08.2-database.md diff --git a/docs/9-architectural-decisions.md b/docs/09-architectural-decisions.md similarity index 100% rename from docs/9-architectural-decisions.md rename to docs/09-architectural-decisions.md diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index be47d2c..3e2b0eb 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -1,6 +1,6 @@ # Architecture Documentation -This file is the entry point for the architecture documentation of **All You Can GET AI Biz**. +This file is the entry point for the architecture documentation of **ai.allucanget.biz**. The documentation follows the [arc42 template](https://arc42.org/overview) and is split into 12 section files, each covering a specific aspect of the architecture. Read the sections in order for a full picture, or jump directly to the section most relevant to you. @@ -8,15 +8,15 @@ The documentation follows the [arc42 template](https://arc42.org/overview) and i | Section | File | Description | | ------- | ---------------------------------------------------------------- | ----------------------------------------------------- | -| 1 | [1-introduction-and-goals.md](1-introduction-and-goals.md) | Requirements, quality goals, stakeholders | -| 2 | [2-constraints.md](2-constraints.md) | Technical, organizational, and convention constraints | -| 3 | [3-context-and-scope.md](3-context-and-scope.md) | System boundaries and external interfaces | -| 4 | [4-solution-strategy.md](4-solution-strategy.md) | Fundamental technology and design decisions | -| 5 | [5-building-block-view.md](5-building-block-view.md) | Static decomposition of the system | -| 6 | [6-runtime-view.md](6-runtime-view.md) | Key runtime scenarios and request flows | -| 7 | [7-deployment-view.md](7-deployment-view.md) | Infrastructure and deployment topology | -| 8 | [8-crosscutting-concepts.md](8-crosscutting-concepts.md) | Security, logging, error handling, configuration | -| 9 | [9-architectural-decisions.md](9-architectural-decisions.md) | Architecture Decision Records (ADRs) | +| 1 | [01-introduction-and-goals.md](01-introduction-and-goals.md) | Requirements, quality goals, stakeholders | +| 2 | [02-constraints.md](02-constraints.md) | Technical, organizational, and convention constraints | +| 3 | [03-context-and-scope.md](03-context-and-scope.md) | System boundaries and external interfaces | +| 4 | [04-solution-strategy.md](04-solution-strategy.md) | Fundamental technology and design decisions | +| 5 | [05-building-block-view.md](05-building-block-view.md) | Static decomposition of the system | +| 6 | [06-runtime-view.md](06-runtime-view.md) | Key runtime scenarios and request flows | +| 7 | [07-deployment-view.md](07-deployment-view.md) | Infrastructure and deployment topology | +| 8 | [08-crosscutting-concepts.md](08-crosscutting-concepts.md) | Security, logging, error handling, configuration | +| 9 | [09-architectural-decisions.md](09-architectural-decisions.md) | Architecture Decision Records (ADRs) | | 10 | [10-quality-requirements.md](10-quality-requirements.md) | Quality scenarios and acceptance criteria | | 11 | [11-risks-and-technical-debt.md](11-risks-and-technical-debt.md) | Known risks and technical debt | | 12 | [12-glossary.md](12-glossary.md) | Domain and technical terms | diff --git a/frontend/README.md b/frontend/README.md new file mode 100644 index 0000000..8cb38ea --- /dev/null +++ b/frontend/README.md @@ -0,0 +1,57 @@ +# Frontend — Flask Web UI + +Server-rendered UI powered by Flask + Jinja2 + Tailwind CSS. + +## Tech Stack + +| Layer | Choice | +| ----------- | -------------------------------- | +| Framework | Flask | +| Templates | Jinja2 | +| Styling | Tailwind CSS (CDN) + custom CSS | +| HTTP client | httpx | +| Server | gunicorn (prod), Flask dev (dev) | + +## Project Structure + +```txt +frontend/ + app/ + __init__.py App factory (create_app) + main.py Entry point — calls create_app() + config.py Configuration (secret key, backend URL) + filters.py Jinja2 template filters (fromisoformat, humantime) + helpers.py API client (_api), auth decorators, model helpers + routes/ Blueprint route handlers + __init__.py register_blueprints() + auth.py /login, /register, /logout, / + dashboard.py /dashboard + gallery.py /gallery, image/video/upload detail, /images//file + generate.py /generate/text, /generate/image, /generate/video + admin.py /admin, /admin/models, /api/admin/* + profile.py /users/profile + templates/ Jinja2 HTML templates + admin/ Admin sub-templates (models, videos) + static/ CSS (style.css), JS (app.js) + tests/ pytest suite + Dockerfile Production container + requirements.txt Runtime dependencies + requirements-dev.txt Dev dependencies +``` + +## Running locally + +```bash +cd frontend +flask --app app.main run --port 12016 --debug +``` + +## Running tests + +```bash +pytest frontend/tests/ +``` + +## Architecture + +See [docs/ARCHITECTURE.md](../docs/ARCHITECTURE.md) for full documentation (arc42 template).