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)       │   │
│  │  :12016     │  │    :12015          │   │
│  └──────┬──────┘  └─────────┬──────────┘   │
│         │                   │              │
│         └────────┬──────────┘              │
│                  │                         │
│          ┌───────▼────────┐                │
│          │  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	12016
FastAPI backend	backend	12015
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: 12015                                │    │   │
│  │  │ - Service Name: backend                      │    │   │
│  │  │ - Volume Mount: /app/data ← host/data/       │    │   │
│  │  ├──────────────────────────────────────────────┤    │   │
│  │  │ Frontend Container (Flask)                   │    │   │
│  │  │ - Port: 12016                                │    │   │
│  │  │ - 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:12015             │    │   │
│  │  │           / → frontend:12016                 │    │   │
│  │  └──────────────────────────────────────────────┘    │   │
│  └──────────────────────────────────────────────────────┘   │
│                         ▲                                   │
│                  Host Port Bindings                         │
│         80:80, 443:443, 12015:12015, 12016:12016            │
└─────────────────────────────────────────────────────────────┘
                         │
                      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:12016 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:12015, frontend:12016)
• 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. Recommended Path: Deploy docker-compose.coolify.yml as one Coolify Docker Compose resource
2. Public Entry Point: Route domain to nginx service on port 80; backend and frontend stay internal
3. Data Persistence: Named volume keeps DuckDB data at /app/data
4. Fallback Path: Use separate Nixpacks services only when one-stack Compose deploy is not suitable

Note: In Compose-based Coolify deployment, frontend reaches backend through Docker DNS at http://backend:12015. In Nixpacks-based deployment, use Coolify internal networking or colocate both services.

See: Coolify Deployment Guide for detailed instructions.