ai.allucanget.biz/docs/7-deployment-view.md

7. Deployment View

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.

Infrastructure Level 1

┌────────────────────────────────────────────┐
│  Host / VM                                 │
│  ┌─────────────┐  ┌────────────────────┐   │
│  │  frontend   │  │      backend       │   │
│  │  (Flask)    │  │    (FastAPI)       │   │
│  │  :12001     │  │    :12000          │   │
│  └──────┬──────┘  └─────────┬──────────┘   │
│         │                   │              │
│         └────────┬──────────┘              │
│                  │                         │
│          ┌───────▼────────┐                │
│          │  db (DuckDB)   │                │
│          │  data/app.db   │                │
│          └────────────────┘                │
└────────────────────────────────────────────┘

Motivation: All three components run on a single VM (or 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	12001
FastAPI backend	backend	12000
DuckDB	File on host (data/app.db)	—

Infrastructure Level 2

Docker Compose (Recommended for Development & Production)

All services are containerized and orchestrated with docker compose:

┌─────────────────────────────────────────────────────────────┐
│  Docker Host / VM                                           │
│  ┌──────────────────────────────────────────────────────┐   │
│  │  Docker Network: app-network (bridge)                │   │
│  │  ┌──────────────────────────────────────────────┐    │   │
│  │  │ Backend Container (FastAPI)                  │    │   │
│  │  │ - Port: 12000                                │    │   │
│  │  │ - Service Name: backend                      │    │   │
│  │  │ - Volume Mount: /app/data ← host/data/       │    │   │
│  │  ├──────────────────────────────────────────────┤    │   │
│  │  │ Frontend Container (Flask)                   │    │   │
│  │  │ - Port: 12001                                │    │   │
│  │  │ - Service Name: frontend                     │    │   │
│  │  │ - Depends on: backend (health check)         │    │   │
│  │  ├──────────────────────────────────────────────┤    │   │
│  │  │ Nginx Container (Reverse Proxy)              │    │   │
│  │  │ - Port: 80 (HTTP), 443 (HTTPS)               │    │   │
│  │  │ - Config: nginx/docker-compose.conf          │    │   │
│  │  │ - Routes: /api/* → backend:12000             │    │   │
│  │  │           / → frontend:12001                 │    │   │
│  │  └──────────────────────────────────────────────┘    │   │
│  └──────────────────────────────────────────────────────┘   │
│                         ▲                                   │
│                  Host Port Bindings                         │
│         80:80, 443:443, 12000:12000, 12001:12001            │
└─────────────────────────────────────────────────────────────┘
                         │
                      Users / Internet

Deployment Steps:

1. Ensure Docker and Docker Compose are installed
2. Create .env with required environment variables
3. Run: docker compose up --build
4. Access via browser at http://localhost:12001 or through Nginx at http://localhost:80

Benefits:

• Consistency: Same containerized environment across development, testing, and production
• Simplicity: Single command to start entire stack
• Portability: Run on any system with Docker installed
• Persistence: DuckDB data survives container restarts via volume mounts
• Networking: Service names enable automatic DNS resolution (backend:12000, frontend:12001)
• Observability: Easy logging with docker compose logs

See: Docker Compose Deployment Guide for detailed instructions.

Coolify (Alternative for Existing Deployments)

If using Coolify instead of Docker Compose:

1. Backend Service: Nixpacks build with base directory /backend, port 12000
2. Frontend Service: Nixpacks build with base directory /frontend, port 12001
3. Reverse Proxy: Coolify's built-in proxy or custom Nginx config
4. Data Persistence: Volume mount at /app/data for DuckDB

Note: Both services must be on the same Coolify server or cluster for service-to-service communication via http://localhost:12000 or service DNS names (depending on Coolify's networking setup).

See: Coolify Deployment Guide for detailed instructions.