77 lines
3.3 KiB
Markdown
77 lines
3.3 KiB
Markdown
# 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
|
|
```
|