diff --git a/README.md b/README.md
index ce23eca..5c47e2b 100644
--- a/README.md
+++ b/README.md
@@ -1,7 +1,16 @@
-# AI
+# All You Can GET AI
 
 A multi-modal AI web application. Users can choose between different AI models for text generation, text-to-image, text-to-video, and image-to-video generation, powered by [openrouter.ai](https://openrouter.ai).
 
+Key features:
+
+- Multi-modal AI generation (text, images, videos)
+- User authentication and role-based access control
+- Admin dashboard for managing users, models, and video jobs
+- Gallery for viewing generated images and videos
+- Chat interface with message history
+- Image upload and preview functionality
+
 ## Components
 
 | Component | Technology        | Description                                              |
@@ -31,33 +40,58 @@ python -m venv .venv
 # Linux/macOS
 source .venv/bin/activate
 
-# Install dependencies
+# Install core dependencies
 pip install -r requirements.txt
 
-# Copy and fill in environment variables
+# Install development dependencies
+pip install -r backend/requirements-dev.txt
+pip install -r frontend/requirements-dev.txt
+
+# Copy environment variables file
 cp .env.example .env
+
+# Edit .env file and add your OpenRouter API key and configure other settings
+nano .env
 ```
 
-### Running the backend
+### Running the application locally
+
+#### Backend (FastAPI + Uvicorn)
 
 ```bash
 cd backend
 uvicorn app.main:app --reload --port 12015
 ```
 
-### Running the frontend
+#### Frontend (Flask)
 
 ```bash
 cd frontend
-flask --app app.main run --port 12016
+flask --app app.main run --port 12016 --debug
 ```
 
 ### Running tests
 
 ```bash
+# Run all tests
 pytest
+
+# Run backend tests only
+pytest backend/tests/
+
+# Run frontend tests only
+pytest frontend/tests/
 ```
 
+### Available Environment Variables
+
+| Variable             | Description                 | Default             |
+| -------------------- | --------------------------- | ------------------- |
+| `OPENROUTER_API_KEY` | Your OpenRouter API key     | _Required_          |
+| `ADMIN_EMAIL`        | Default admin user email    | `ai@allucanget.biz` |
+| `ADMIN_PASSWORD`     | Default admin user password | `admin123`          |
+| `DATABASE_URL`       | DuckDB database path        | `../data/app.db`    |
+
 ## Default admin user
 
 On first startup a default admin account is created:
@@ -77,19 +111,27 @@ Deployed on [Coolify](https://coolify.io) using Nixpacks. See [docs/deployment/c
 ## Project Structure
 
 ```txt
-backend/          FastAPI backend
+backend/                  FastAPI backend
   app/
-    routers/      API route handlers
-    services/     Business logic
-    models/       Pydantic models
-  tests/
-frontend/         Flask frontend
+    __init__.py          Package initialization
+    db.py                Database connection and operations
+    dependencies.py      Dependency injection
+    main.py              FastAPI application entrypoint
+    models/              Pydantic and database models
+    routers/             API route handlers (auth, users, admin, generate, gallery)
+    services/            Business logic for AI generation, users, admin, etc.
+  tests/                  Backend test suite
+frontend/                 Flask frontend
   app/
-    templates/    Jinja2 HTML templates
-    static/       CSS, JS, images
-  tests/
-data/             DuckDB database files (gitignored)
-docs/             Architecture documentation
+    __init__.py          Package initialization
+    main.py              Flask application entrypoint
+    templates/           Jinja2 HTML templates
+    static/              CSS, JS, images
+  tests/                  Frontend test suite
+data/                     DuckDB database files, uploaded media, and generated content
+logs/                     Application logs
+docs/                     Architecture documentation (arc42 template)
+nginx/                    Nginx configuration for Coolify deployment
 ```
 
 ## Documentation
diff --git a/docs/2-constraints.md b/docs/2-constraints.md
index 11aba55..0cb5305 100644
--- a/docs/2-constraints.md
+++ b/docs/2-constraints.md
@@ -22,5 +22,5 @@ Any requirement that constrains software architects in their freedom of design a
 
 | Convention           | Background / Motivation                             |
 | -------------------- | --------------------------------------------------- |
-| Python 3.11+         | Modern language features, type hints                |
+| Python 3.12+         | Modern language features, type hints                |
 | pytest for all tests | Consistent test tooling across backend and frontend |
diff --git a/docs/deployment/coolify.md b/docs/deployment/coolify.md
index 76d9aba..ead9de4 100644
--- a/docs/deployment/coolify.md
+++ b/docs/deployment/coolify.md
@@ -29,7 +29,7 @@ Coolify's built-in reverse proxy routes traffic:
 3. Select the `ai.allucanget.biz` repository
 4. Choose the `main` branch
 5. Set **Build Pack** to `nixpacks`
-6. **CRITICAL: Set Base Directory to `/backend`** — this tells Nixpacks to look in the `backend/` subdirectory for `requirements.txt` and the Python application
+6. Set **Base Directory** to `/backend` - this tells Nixpacks to look in the `backend/` subdirectory for `requirements.txt` and the Python application
 7. Set **Ports Exposed** to `12015`
 8. Set **Start Command** to:
 
@@ -59,7 +59,7 @@ Add these as **Runtime** environment variables in Coolify:
 2. Select the same repository
 3. Choose the `main` branch
 4. Set **Build Pack** to `nixpacks`
-5. **CRITICAL: Set Base Directory to `/frontend`** — this tells Nixpacks to look in the `frontend/` subdirectory for `requirements.txt` and the Python application
+5. Set **Base Directory** to `/frontend` - this tells Nixpacks to look in the `frontend/` subdirectory for `requirements.txt` and the Python application
 6. Set **Ports Exposed** to `12016`
 7. Set **Start Command** to: