Developer Documentation

Architektur

Moderne PWA mit Flask-Backend, Service Worker und Analytics.

CLIENT (PWA)

app.js sw.js IndexedDB Cache API

↕

SERVER (Flask)

Routes Push API Analytics SQLite

┌─────────────────────────────────────────────────────────────┐
│                        CLIENT (PWA)                         │
├─────────────────────────────────────────────────────────────┤
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────────┐  │
│  │    app.js    │  │    sw.js     │  │   IndexedDB      │  │
│  │  (Main App)  │  │(ServiceWorker)│  │ (Offline Queue)  │  │
│  └──────┬───────┘  └──────┬───────┘  └────────┬─────────┘  │
│         └─────────────────┼────────────────────┘            │
│                    ┌──────┴──────┐                         │
│                    │  Cache API  │                         │
│                    └─────────────┘                         │
└─────────────────────────────────────────────────────────────┘
                            │
                     HTTPS / Push
                            │
┌─────────────────────────────────────────────────────────────┐
│                     SERVER (Flask)                          │
├─────────────────────────────────────────────────────────────┤
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────────┐  │
│  │   Routes     │  │   Push API   │  │   Analytics      │  │
│  │  (app.py)    │  │   (VAPID)    │  │   (Tracking)     │  │
│  └──────┬───────┘  └──────┬───────┘  └────────┬─────────┘  │
│         └─────────────────┼────────────────────┘            │
│                    ┌──────┴──────┐                         │
│                    │  SQLite DB  │                         │
│                    └─────────────┘                         │
└─────────────────────────────────────────────────────────────┘

Tech Stack

Layer	Tech	Purpose
Frontend	Vanilla JS	Zero deps, max perf
SW	Workbox-style	Cache, Push, Sync
Backend	Flask	API, Push, Analytics
Push	VAPID	iOS 16.4+, Android
DB	SQLite	Users, Events
Deploy	Coolify	CI/CD, Docker

Features

Push Notifications

Web Push mit VAPID. iOS 16.4+, Android, Desktop.

iOS 16.4+

Offline First

Service Worker mit intelligenten Caching-Strategien.

100% Offline

Analytics

Privacy-first. Core Web Vitals, Engagement, Properties.

DSGVO

Background Sync

Offline-Events automatisch synchronisieren.

Auto

App Shortcuts

Quick Actions vom Homescreen.

PWA

Update Banner

User-kontrollierte SW-Updates.

UX

Push Notifications

Ablauf

// 1. VAPID Key holen
const { publicKey } = await fetch('/api/push/vapid-public-key').json();

// 2. Subscriben
const sub = await reg.pushManager.subscribe({
  userVisibleOnly: true,
  applicationServerKey: publicKey
});

// 3. An Server senden
await fetch('/api/push/subscribe', {
  method: 'POST',
  body: JSON.stringify({ subscription: sub })
});

iOS Support

iOS	Support	Hinweis
16.4+	Voll	Web Push via PWA
16.0-16.3	Teil	Nur Notification API
<16.0	Nein	-

Wichtig: iOS Push nur im Standalone Mode (vom Homescreen).

Analytics

Tracking

// Event tracken
await pwaApp.trackEvent('button_click', {
  button_id: 'submit',
  page: '/checkout'
});

// Session End (via sendBeacon)
navigator.sendBeacon('/api/analytics/track', data);

Auto-Events

Kategorie	Events
Core	`app_open`, `app_installed`
Engagement	`scroll_depth`, `button_click`, `rage_click`
Session	`session_end`, `page_hidden`, `page_visible`
Network	`went_offline`, `went_online`
Perf	`web_vital_lcp`, `web_vital_inp`, `web_vital_cls`

Event Reference

Core Events

Event	Daten
`app_open`	`source`, `is_installed`, `referrer`
`session_end`	`duration_seconds`, `pages_viewed`
`scroll_depth`	`percent`, `page`

Engagement

Event	Daten
`button_click`	`button_id`, `button_text`
`rage_click`	`click_count`, `element_id`

User Properties

Property	Beispiel
`screen_width`	1920
`timezone`	Europe/Berlin
`connection_type`	4g
`is_standalone`	true
`color_scheme`	dark

API Endpoints

Push

GET /api/push/vapid-public-key

VAPID Public Key abrufen

POST /api/push/subscribe

Push-Subscription registrieren

POST /api/push/send-test

Test-Notification senden

Analytics

POST /api/analytics/track

Event tracken

GET /api/analytics/summary?days=7

Summary abrufen

System

GET /health

Health Check

Offline Support

Caching-Strategien

Asset	Strategie
HTML	Network-First
CSS, JS	Stale-While-Revalidate
Images	Cache-First
API	Network-Only

Background Sync

// Events in IndexedDB speichern
await store.add({ data, timestamp: Date.now() });

// Sync registrieren
await reg.sync.register('sync-analytics');

Security

Headers

Header	Wert
CSP	`default-src 'self'`
X-Content-Type	`nosniff`
X-Frame	`DENY`
Referrer	`strict-origin`

Rate Limiting

200 Requests/Tag
50 Requests/Stunde
Broadcast: Admin-Key

DSGVO

Keine persönlichen Daten
Anonymous User ID
Daten löschen Button
Kein Tracking ohne Consent