tschunkorder/README.md

# TschunkOrder

A modern web application for managing drink orders, specifically designed for Tschunk beverages. The application provides a real-time ordering system with a Vue.js frontend and FastAPI backend, featuring WebSocket support for live updates and Prometheus metrics for monitoring.

## Purpose

TschunkOrder is a full-stack application that allows users to:
- Create and manage drink orders in real-time
- Choose from various Tschunk variants (Tschunk, Tschunk Hannover-Mische, Tschunk alkoholfreier Rum, Virgin Tschunk)
- Select between Flora Mate and Club Mate
- Add custom notes and special requests
- View order statistics and metrics
- Receive live updates via WebSocket connections

## Quick Start with Docker

The easiest way to run the application is using the provided Docker Compose setup:

```bash
# Clone the repository (if not already done)
git clone ssh://gogs@git.hannover.ccc.de:3071/clarity/tschunkorder.git
cd tschunkorder

# Start all services
docker-compose up -d

# Access the application
# Frontend: http://[url]
# API Documentation: http://[url]/api/docs
# Prometheus Metrics: http://[url]/metrics
```

The Docker setup includes:
- **Frontend**: Vue.js application served on port 80
- **Backend**: FastAPI server with WebSocket support
- **Nginx**: Reverse proxy with rate limiting and security headers

## Development Environment Setup

### Backend Development

**Prerequisites:**
- Python 3.8+
- pip

**Setup:**
```bash
cd backend

# Create virtual environment
python -m venv venv

# Activate virtual environment
# Linux/macOS:
source venv/bin/activate
# Windows:
# venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Run the development server
python main.py
# or
uvicorn main:app --reload
```

The backend will be available at `http://localhost:8000`

### Frontend Development

**Prerequisites:**
- Node.js 18+
- npm

**Setup:**
```bash
cd frontend

# Install dependencies
npm install

# Start development server
npm run dev
```

The frontend will be available at `http://localhost:5173`

**Available Scripts:**
- `npm run dev` - Start development server
- `npm run build` - Build for production
- `npm run preview` - Preview production build
- `npm run lint` - Run ESLint
- `npm run type-check` - Check TypeScript types

## API Description

The backend provides a RESTful API with WebSocket support for real-time updates.

### Base URL
- Development: `http://[url]:8000`
- Production: `http://[url]/api` (when setup via docker)

### REST Endpoints

#### Create Order
```http
POST /api/orders
Content-Type: application/json

{
  "drinks": [
    {
      "drink_type": "Tschunk",
      "mate_type": "Club Mate",
      "quantity": 2,
      "notes": "Extra cold please"
    }
  ]
}
```

#### Get All Orders
```http
GET /api/orders
```

#### Delete Order
```http
DELETE /api/orders/{order_id}
```

#### Get Available Drinks
```http
GET /api/drinks
```

#### Get Drink Statistics
```http
GET /api/stats/drinks
```

### WebSocket Endpoint

**Connection:** `ws://[url]:8000/api/ws` (development) or `ws://[url]/api/ws` (production)

**Message Types:**

1. **Create Order:**
```json
{
  "type": "create_order",
  "drinks": [...]
}
```

2. **Get All Orders:**
```json
{
  "type": "get_all_orders"
}
```

3. **Delete Order:**
```json
{
  "type": "delete_order",
  "order_id": "uuid"
}
```

4. **Ping/Pong:**
```json
{
  "type": "ping"
}
```

**Received Messages:**

- `order_created` - New order created
- `order_deleted` - Order deleted
- `all_orders` - All current orders
- `pong` - Response to ping

### Available Drink Types
- Tschunk
- Tschunk Hannover-Mische
- Tschunk alkoholfreier Rum
- Virgin Tschunk

### Available Mate Types
- Flora Mate
- Club Mate

## Prometheus Metrics

The application exposes Prometheus metrics at `/metrics` endpoint for monitoring drink sales and application performance.

### Available Metrics

#### `tschunk_drinks_sold_total`
- **Type:** Counter
- **Labels:** `drink_type`, `mate_type`
- **Description:** Total number of drinks sold by type and mate variety

**Example:**
```
# HELP tschunk_drinks_sold_total Total number of drinks sold
# TYPE tschunk_drinks_sold_total counter
tschunk_drinks_sold_total{drink_type="Tschunk",mate_type="Club Mate"} 15
tschunk_drinks_sold_total{drink_type="Virgin Tschunk",mate_type="Flora Mate"} 8
```

### Metrics Persistence

- Metrics are persisted to `drink_stats.json` in the backend directory
- Counters are restored on application restart
- Data survives container restarts when using Docker volumes

### Monitoring Integration

The metrics endpoint can be scraped by:
- Prometheus server
- Grafana dashboards
- Other monitoring tools

**Example Prometheus configuration:**
```yaml
scrape_configs:
  - job_name: 'tschunkorder'
    static_configs:
      - targets: ['http://url']
    metrics_path: '/metrics'
```

## Project Structure

```
tschunkorder/
├── backend/                 # FastAPI backend
│   ├── main.py             # Main application entry point
│   ├── models.py           # Pydantic models
│   ├── database.py         # In-memory database
│   ├── websocket_manager.py # WebSocket connection management
│   ├── prometheus_metrics.py # Prometheus metrics
│   └── requirements.txt    # Python dependencies
├── frontend/               # Vue.js frontend
│   ├── src/               # Source code
│   ├── package.json       # Node.js dependencies
│   └── vite.config.ts     # Vite configuration
├── nginx/                 # Nginx configuration
│   ├── nginx.conf         # Main nginx config
│   └── conf.d/            # Server configurations
└── docker-compose.yml     # Docker orchestration
```