# AGENTS.md — Grabengasse 7 Home Portal (`grabengasse`)

> [!NOTE]
> **Domain**: Local climate, environment, and smart home portal for Grabengasse 7.  
> **Live Production URL**: `https://grabengasse7.de`  
> **Kubernetes Manifests**: `k8s/grabengasse/` (Namespace: `grabengasse`)  
> **Images**:  
> - Frontend: `registry.haumdaucher.de/website/grabengasse_frontend:latest`  
> - Backend: `registry.haumdaucher.de/website/grabengasse_backend:latest`  
> **Source Location**: `projects/grabengasse/`

---

## 🏛️ Architecture & Tech Stack

1. **Frontend (`frontend/`)**:
   - **Framework**: Vue 3 (Composition API) + Vite + TypeScript.
   - **Styling**: Retro-chic aesthetic with pixel art accents, glassmorphic cards, and an optional CRT scanline toggle.
   - **Data Visualization**: Chart.js / Vue-Chartjs / Apexcharts for 24h temperature, humidity, wind, solar, and rain telemetry.
   - **Serving Runtime**: Nginx (`nginx:alpine`) in Docker.

2. **Backend (`backend/`)**:
   - **Framework**: FastAPI (Python 3.11).
   - **Telemetry Source**: Direct HTTP queries to cluster Prometheus (`http://prometheus-operator-kube-p-prometheus.monitoring.svc.cluster.local:9090`) aggregating metrics from the Shelly WS90 weather station.
   - **Endpoints**:
     - `GET /healthz`: Liveness and readiness probe.
     - `GET /api/v1/weather/current`: Live weather telemetry (temperature, humidity, wind speed, solar radiation, rain).
     - `GET /api/v1/weather/history`: Historical timeseries for 24h graphing.

3. **Kubernetes Ingress & Routing (`k8s/grabengasse/`)**:
   - Ingress Host: `grabengasse7.de` with Traefik ingress controller and `cert-manager` TLS.
   - `/` → `grabengasse-frontend` (Port 80)
   - `/api` → `grabengasse-backend` (Port 8000)

---

## 🛠️ Build & Deployment Commands

```bash
cd projects/grabengasse
make compile          # Build frontend static assets (npm run build)
make build            # Build both frontend and backend Docker images (linux/amd64)
make push             # Push images to registry.haumdaucher.de
make deploy           # Apply k8s manifests and rollout restart pods
```

---

## 📁 Repository Structure

```
projects/grabengasse/
├── Makefile                    # Coordinated multi-service build and deploy
├── AGENTS.md                   # This handbook
├── README.md                   # Project overview
├── frontend/                   # Vue 3 SPA
│   ├── Dockerfile
│   ├── Makefile
│   ├── nginx.conf
│   ├── package.json
│   ├── src/
│   │   ├── App.vue             # Weather dashboard layout & state
│   │   ├── components/         # Weather gauges, telemetry cards & retro CRT overlay
│   │   └── scripts/            # generate_icons.py (Pixel art icon generator)
│   └── public/                 # Static icons, manifest, and service worker
└── backend/                    # FastAPI microservice
    ├── Dockerfile
    ├── Makefile
    ├── requirements.txt
    ├── main.py                 # FastAPI application entrypoint
    ├── config.py               # CORS & environment configuration
    ├── routers/
    │   └── weather.py          # /api/v1/weather routes
    └── services/
        └── prometheus.py       # Prometheus query client
```