From 6f04cc654f7e7343945e8679b75c21963b870476 Mon Sep 17 00:00:00 2001
From: Stefan Koelle <stefan.koelle@gmail.com>
Date: Sat, 1 Aug 2026 16:45:04 +0200
Subject: [PATCH] docs: add API and Web-UI documentation to README and AGENTS

---
 AGENTS.md | 19 +++++++++++++++++--
 README.md | 49 +++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 66 insertions(+), 2 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index 5b8bc7e..2f89565 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -10,14 +10,20 @@ Python-basierter Google Calendar → MariaDB Synchronizer. Läuft als Docker Con
 
 - **Sprache**: Python 3.12
 - **Datenbank**: MariaDB (mysql-connector-python)
+- **API**: FastAPI + Uvicorn + Jinja2
 - **Docker**: Multi-Stage Build nicht verwendet, simples Slim-Image
-- **Dependencies**: requests, icalendar, recurring-ical-events, mysql-connector-python
+- **Dependencies**: requests, icalendar, recurring-ical-events, mysql-connector-python, fastapi, uvicorn, jinja2
 
 ## Projektstruktur
 
 ```
 .
 ├── sync.py              # Hauptskript (alles in einer Datei)
+├── api/
+│   ├── main.py          # FastAPI App (REST API + HTML UI)
+│   ├── database.py      # DB-Verbindung für die API
+│   └── templates/
+│       └── index.html   # Jinja2 Template für Web-UI
 ├── requirements.txt     # Python Dependencies
 ├── Dockerfile           # Docker Image Definition
 ├── docker-compose.yml   # Docker Compose Konfiguration
@@ -29,7 +35,16 @@ Python-basierter Google Calendar → MariaDB Synchronizer. Läuft als Docker Con
 ## Wichtige Hinweise
 
 ### Kein Framework
-Das Projekt verwendet kein Web-Framework. `sync.py` ist ein eigenständiges Python-Skript mit einer Endlosschleife (`main()` → `time.sleep()`).
+Das Projekt verwendet kein Web-Framework für den Sync-Teil. `sync.py` ist ein eigenständiges Python-Skript mit einer Endlosschleife (`main()` → `time.sleep()`).
+
+### FastAPI Applikation
+Die API (`api/main.py`) ist eine separarte FastAPI-App die als eigenständiger Container läuft:
+- **Web-UI**: `GET /` - Jinja2 Template mit anstehenden Termine und Suchfunktion
+- **REST API**: `GET /api/events` - JSON-Liste zukünftiger Events
+- **Einzeln-Event**: `GET /api/events/{id}` - Einzelnes Event als JSON
+- **Health Check**: `GET /api/health` - Gibt `{"status": "ok"}` zurück
+- Läuft über Uvicorn auf Port 8000
+- Teilt sich die Datenbank mit `sync.py`, verwendet aber eigene DB-Verbindung (`api/database.py`)
 
 ### Datenbank-Schema
 Schema wird in `ensure_schema()` per `CREATE TABLE IF NOT EXISTS` erstellt. Bei Schema-Änderungen:
diff --git a/README.md b/README.md
index 1e3e90d..190e0bb 100644
--- a/README.md
+++ b/README.md
@@ -11,6 +11,8 @@ Läuft als Docker Container, pollt periodisch einen privaten Google Calendar ICS
 - Soft-Delete: Entfernte Events werden als `deleted=1` markiert, nicht gelöscht
 - Optionales Database-Bootstrap: Erstellt DB und User automatisch bei `DB_BOOTSTRAP=true`
 - Zeitfenster-konfiguration für Vergangenheit/Future (standardmäßig -90 Tage / +365 Tage)
+- Web-UI zur Anzeige anstehender Termine mit Suchfunktion
+- REST API für programmsprachigen Zugriff auf Kalenderdaten
 
 ## Voraussetzungen
 
@@ -92,6 +94,53 @@ Tabelle `calendar_events`:
 | `created_at` | DATETIME | Erstellungszeitpunkt |
 | `updated_at` | DATETIME | Letzte Änderung |
 
+## Web-UI & API
+
+Das Projekt enthält eine FastAPI-basierte Webanwendung die als separater Container (`calendar-api`) läuft und auf Port `8000` erreichbar ist.
+
+### Endpoints
+
+| Endpoint | Beschreibung |
+|----------|--------------|
+| `GET /` | HTML-Seite mit anstehenden Terminen und Suchfunktion |
+| `GET /api/health` | Health Check (gibt `{"status": "ok"}` zurück) |
+| `GET /api/events?limit=10&search=...` | JSON-Liste zukünftiger Events (nicht gelöscht) |
+| `GET /api/events/{event_id}` | Einzelnes Event als JSON |
+
+### API Beispiel
+
+```bash
+# Alle anstehenden Events (max. 10)
+curl http://localhost:8000/api/events
+
+# Suche nach Titel
+curl "http://localhost:8000/api/events?search=Meeting&limit=5"
+
+# Einzelnes Event
+curl http://localhost:8000/api/events/42
+```
+
+### JSON Response Format
+
+```json
+{
+  "events": [
+    {
+      "id": 1,
+      "summary": "Teammeeting",
+      "description": "Wöchentliches Teammeeting",
+      "location": "Konferenzraum 1",
+      "start_at": "2025-01-15T10:00:00",
+      "end_at": "2025-01-15T11:00:00",
+      "all_day": false,
+      "status": "CONFIRMED"
+    }
+  ],
+  "count": 1,
+  "query_time": "2025-01-15T09:30:00Z"
+}
+```
+
 ## CI/CD
 
 GitHub Actions Workflow (`docker-publish.yml`) baut und published das Docker Image automatisch nach GitHub Container Registry: