Skip to content

Architektur

Die Architektur von TreeQuest ist in vier logische Schichten unterteilt und nutzt moderne, bewährte Technologien, um Skalierbarkeit, Wartbarkeit und eine reibungslose Entwicklung zu gewährleisten.

1. Systemüberblick

TreeQuest nutzt eine typische Client-Server-Architektur, bei der die mobile App über eine REST-API mit dem Backend kommuniziert.

graph TD
    subgraph Client
        App[React Native / Expo App]
    end

    subgraph Backend
        API[FastAPI Server]
        ML[ML Model - Species ID]
    end

    subgraph Database
        DB[(PostgreSQL + PostGIS)]
    end

    App -- "HTTP/REST & GeoJSON" --> API
    API -- "In-process inference" --> ML
    API -- "SQLAlchemy / GeoAlchemy2" --> DB

    style App fill:#61dafb,stroke:#333,stroke-width:2px,color:#000
    style API fill:#059669,stroke:#333,stroke-width:2px,color:#fff
    style ML fill:#10b981,stroke:#333,stroke-width:2px,color:#fff
    style DB fill:#336791,stroke:#333,stroke-width:2px,color:#fff

Kernkomponenten: - Mobile App: React Native + Expo (TypeScript) - Backend: FastAPI (Python 3.14) - Datenbank: PostgreSQL 18 + PostGIS 3.6 - Infrastruktur: Docker Compose, DigitalOcean Droplet, EAS Build für die App.

2. Mobile App (React Native + Expo)

Die mobile App ist mit React Native und dem Expo Managed Workflow gebaut. Dies ermöglicht eine schnelle Entwicklung ohne komplexe native Android/iOS-Konfigurationen.

Kerntechnologien

  • @maplibre/maplibre-react-native: Kartenrendering basierend auf OpenStreetMap (OGC-konform).
  • expo-camera / expo-image-picker: Für die Fotoaufnahme zur Baumerkennung.
  • zustand: Leichtgewichtiges State-Management mit dedizierten Stores (authStore, treeStore, etc.).
  • axios: HTTP-Client mit Interceptoren für nahtlose JWT-Authentifizierung.
  • @react-navigation/*: Tab- und Stack-Navigation.

Architekturkonzepte

Die App ist Online-First konzipiert, bietet aber durch gecachte Kartenelemente eine gewisse Offline-Fähigkeit. Alle permanenten Daten leben im Backend. Die Kommunikation mit dem Backend erfolgt über REST und standardisiertes GeoJSON für räumliche Daten.

3. Backend (FastAPI / Python 3.14)

FastAPI wurde als Backend-Framework gewählt, da das eingesetzte Machine-Learning-Modell für die Artenbestimmung Python-nativ (PyTorch) ist. Dies erspart einen separaten ML-Service.

Struktur (Layered Architecture)

Das Backend folgt einem sauberen Schichtenmodell, ähnlich dem Controller-Service-Repository Pattern:

  1. Router: Behandeln HTTP-Requests und rufen Services auf.
  2. Services: Enthalten die Business-Logik (z.B. Punktevergabe, Streak-Berechnung).
  3. Repositories: Kapseln Datenbankzugriffe (via SQLAlchemy).
  4. Models / Schemas: SQLAlchemy ORM Modelle und Pydantic v2 Schemas für Validierung.

Authentifizierung & Sicherheit

Die Anwendung nutzt zustandslose JWT-Tokens (Access & Refresh Tokens). Passwörter werden sicher mit bcrypt gehasht.

4. Machine Learning (Artenbestimmung)

Das Backend integriert ein Pre-Trained-Modell (z.B. aus dem iNaturalist-Ökosystem oder BioClip) direkt in den FastAPI-Prozess.

sequenceDiagram
    participant User
    participant App
    participant API
    participant ML as ML Model

    User->>App: Fotografiert Baum
    App->>API: POST /api/v1/identify (Bild)
    API->>ML: Bild normalisieren & auswerten
    ML-->>API: Top-5 Vorhersagen (Confidence)
    API-->>App: Gemappte Baumarten (JSON)
    App-->>User: Zeigt Vorschläge an
  • Das Modell wird beim Startup in den RAM geladen.
  • Bilder werden über die API empfangen, auf z.B. 224x224 normalisiert und durch das Modell geschickt.
  • Die Latenz liegt bei < 5 Sekunden auf einer Standard-CPU.

5. Datenbankschicht (PostgreSQL + PostGIS)

Die Kombination aus PostgreSQL und der Geodaten-Erweiterung PostGIS ist der Industrie-Standard für räumliche Daten.

Highlights

  • Geometrien: Baumstandorte werden als PostGIS Point (SRID 4326) gespeichert.
  • Zonen: "Discovery Zones" sind als Polygon gespeichert.
  • Räumliche Abfragen: Komplexe Queries wie ST_Contains (Befindet sich ein Punkt in einer Zone?) oder ST_MakeEnvelope (Bäume in einem Kartenausschnitt) werden effizient auf Datenbankebene ausgeführt.

6. Gamification System

Die Architektur beinhaltet ein durchdachtes Gamification-Modul im Backend:

  • Punkte: Werden automatisch für Aktionen wie das Markieren oder Verifizieren vergeben.
  • Badges: JSON-basierte Kriterien, die nach jedem Punktezuwachs evaluiert werden (z.B. "Erster Baum markiert").
  • Streaks: Tracking der täglichen Aktivität mit Feuer-Icons.
  • Discovery Zones: Verdeckte Zonen ("Fog of war" auf der Karte), die durch GPS-Fix oder Aktionen aufgedeckt werden und Extrapunkte geben.