merged readme

README.md

@@ -0,0 +1,256 @@
+# 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: ['localhost:8000']
+    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
+```