# 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)       │   │
│  │  :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`:

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