feat: update documentation with project details, deployment instructions, and database concurrency management

Co-authored-by: Copilot <copilot@github.com>
2026-04-29 18:25:53 +02:00
parent 615b842b03
commit d5a94947de
6 changed files with 154 additions and 132 deletions
@@ -5,71 +5,79 @@ Describes:
 1. Technical infrastructure used to execute your system, with infrastructure elements like geographical locations, environments, computers, processors, channels and net topologies.
 2. Mapping of (software) building blocks to that infrastructure elements.

+**See**: [Coolify Deployment Guide](./deployment/coolify.md) for detailed instructions.
+
 ## Infrastructure Level 1

-```text
-┌────────────────────────────────────────────┐
-│  Host / VM                                 │
-│  ┌─────────────┐  ┌────────────────────┐   │
-│  │  frontend   │  │      backend       │   │
-│  │  (Flask)    │  │    (FastAPI)       │   │
-│  │  :12016     │  │    :12015          │   │
-│  └──────┬──────┘  └─────────┬──────────┘   │
-│         │                   │              │
-│         └────────┬──────────┘              │
-│                  │                         │
-│          ┌───────▼────────┐                │
-│          │  db (DuckDB)   │                │
-│          │  data/app.db   │                │
-│          └────────────────┘                │
-└────────────────────────────────────────────┘
+Hosted on a single VM running docker containers, deployed via Coolify with Nixpacks to 192.168.88.18 for production.
+
+Containers run behind nginx at 192.168.88.11 which handles TLS termination and reverse proxying to the frontend on port 12016 and backend on port 12015. The database is a file on the host filesystem at `data/app.db` accessed by the backend service.
+
+```mermaid
+graph TD
+      Users[Users / Internet]
+      Nginx[nginx reverse proxy\nTLS termination]
+      Users -->|HTTPS| Nginx
+
+      subgraph Coolify Server
+         direction TB
+         subgraph AI Frontend
+            AI_Frontend[AI Frontend\nFlask\nServes HTML/CSS/JS UI]
+         end
+         subgraph AI Backend
+            AI_Backend[AI Backend\nFastAPI\nCommunicates with openrouter.ai API]
+            db[(DuckDB Database\nFile: data/app.db)]
+            AI_Backend --> db
+         end
+         AI_Frontend -->|BACKEND_URL:12015| AI_Backend
+      end
+      Nginx -->|12016| AI_Frontend
 ```

-**Motivation:** All three components run on a single VM (or as Docker containers) for simplicity and low operational overhead.
+**Motivation:** All three components run as Docker containers for simplicity and low operational overhead.

 **Quality and/or Performance Features:** The frontend and backend are stateless; DuckDB persists data on the host filesystem.

 **Mapping of Building Blocks to Infrastructure:**

-| Building Block  | Container / Process          | Port  |
-| --------------- | ---------------------------- | ----- |
-| Flask frontend  | `frontend`                   | 12016 |
-| FastAPI backend | `backend`                    | 12015 |
-| DuckDB          | File on host (`data/app.db`) | —     |
+| Building Block  | Container / Process          | Port            |
+| --------------- | ---------------------------- | --------------- |
+| Nginx           | `nginx`                      | 80/443 (public) |
+| Coolify Server  | `coolify`                    | —               |
+| Flask frontend  | `frontend`                   | 12016           |
+| FastAPI backend | `backend`                    | 12015           |
+| DuckDB          | File on host (`data/app.db`) | —               |

 ## Infrastructure Level 2

 ### Coolify with Nixpacks (Production)

-Both services are deployed as separate Nixpacks resources in Coolify:
+Both services are deployed as separate Nixpacks resources in Coolify, which results in two separate containers running on the same host. The database is a file on the host filesystem, mounted as a volume in the backend container.

-```text
-┌──────────────────────────────────────────────────────────┐
-│  Coolify Server                                          │
-│  ┌────────────────────────────┐                          │
-│  │ Backend Service (FastAPI)  │                          │
-│  │ - Base Dir: /backend       │                          │
-│  │ - Port: 12015              │                          │
-│  │ - Volume: /app/data        │                          │
-│  ├────────────────────────────┤                          │
-│  │ Frontend Service (Flask)   │                          │
-│  │ - Base Dir: /frontend      │                          │
-│  │ - Port: 12016 (public)     │                          │
-│  │ - BACKEND_URL: :12015      │                          │
-│  └────────────────────────────┘                          │
-│                   ▲                                      │
-│         Coolify reverse proxy (TLS termination)          │
-└──────────────────────────────────────────────────────────┘
-                    │
-                 Users / Internet
+#### Frontend
+
+```mermaid
+graph TD
+   subgraph Coolify Server
+      direction TB
+      subgraph AI Frontend
+         AI_Frontend[AI Frontend\nNixpacks\nBase Dir: /frontend]
+      end
+   end
+   Users[Users / Internet] -->|HTTPS| AI_Frontend
 ```

-**Deployment Steps:**
+#### Backend

-1. Create backend Nixpacks service in Coolify with Base Directory `/backend`
-2. Create frontend Nixpacks service with Base Directory `/frontend`
-3. Set environment variables per service
-4. Attach domain to frontend on port `12016`
-5. Enable Auto HTTPS in Coolify
-
-**See**: [Coolify Deployment Guide](./deployment/coolify.md) for detailed instructions.
+```mermaid
+graph TD
+   subgraph Coolify Server
+      direction TB
+      subgraph AI Backend
+         AI_Backend[AI Backend\nNixpacks\nBase Dir: /backend]
+         db[(DuckDB Database\nVolume: /app/data)]
+         AI_Backend --> db
+      end
+   end
+   Frontend[Frontend Container] -->|BACKEND_URL:12015| AI_Backend
+```