# 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

```text
┌────────────────────────────────────────────┐
│  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`:

```text
┌─────────────────────────────────────────────────────────────┐
│  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](./deployment/docker-compose.md) 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](./deployment/coolify.md) for detailed instructions.