Skip to content

Technische Architektur - Nachbarschaftshilfe-App

Version: 1.0
Datum: 2026-06-05
Autor: CTO
Status: Initial

Executive Summary

Diese Dokumentation definiert die technische Architektur für unsere Nachbarschaftshilfe-App, die Menschen bei kleinen Aufgaben verbindet und mit einem Punktesystem Rabatte bei Werbepartnern ermöglicht.

1. Tech-Stack-Entscheidungen

1.1 Backend

Gewählt: Node.js mit TypeScript & Express/NestJS

Begründung:

  • JavaScript-Ökosystem: Ermöglicht Code-Sharing zwischen Frontend und Backend (z.B. Validierungslogik, DTOs)
  • TypeScript: Type Safety reduziert Fehler und verbessert Developer Experience
  • Performance: Node.js Event-Loop ist ideal für I/O-intensive Operationen (API-Calls, DB-Queries)
  • Entwicklungsgeschwindigkeit: Große Community, viele Libraries, schnelle Iteration
  • NestJS Framework: Enterprise-grade Struktur mit DI, Modulen, Guards für Authentifizierung
  • Skalierbarkeit: Horizontal skalierbar durch Stateless-Design

Alternativen geprüft:

  • Python/Django: Langsamer bei hoher Concurrency, aber gut für ML falls später benötigt
  • Go: Bessere Performance, aber kleineres Ökosystem und längere Entwicklungszeit

Tech-Stack Details:

  • Runtime: Node.js 20 LTS
  • Framework: NestJS 10.x (für Struktur) oder Express (für Einfachheit)
  • Sprache: TypeScript 5.x
  • API-Style: RESTful JSON APIs
  • Validation: class-validator + class-transformer
  • Testing: Jest + Supertest

1.2 Datenbank

Gewählt: PostgreSQL 16

Begründung:

  • Relationale Struktur: User → Tasks → Points → Redemptions haben klare Beziehungen
  • ACID-Garantien: Wichtig für Punktetransaktionen und Konsistenz
  • Performance: Exzellente Performance mit Indexes für Geo-Queries (Nachbarschaftssuche)
  • JSON-Support: Flexible Speicherung von Metadaten ohne Schema-Migration
  • PostGIS Extension: Geo-Spatial Queries für Nachbarschaftsfilter (z.B. "Aufgaben im 5km Radius")
  • Reife Technologie: Stabil, gut dokumentiert, große Community

Datenmodell (Kernentitäten):

Users (id, email, name, location, points_balance, created_at)
Tasks (id, creator_id, title, description, location, status, points_reward, created_at)
TaskAssignments (id, task_id, helper_id, status, completed_at)
PointTransactions (id, user_id, task_id, amount, type, created_at)
Partners (id, name, logo_url, description)
Redemptions (id, user_id, partner_id, points_spent, discount_code, redeemed_at)

Cache-Layer:

  • Redis 7.x für Session-Storage, Leaderboards, Hot-Data Caching

1.3 Frontend

Gewählt: React Native mit Expo

Begründung:

  • Cross-Platform: Eine Codebase für iOS & Android = 50% weniger Entwicklungszeit
  • JavaScript/TypeScript: Gleicher Tech-Stack wie Backend = Team-Effizienz
  • Expo Framework: Schnellerer Start, OTA-Updates, Managed Workflow
  • Community: Größte Cross-Platform Community, viele Libraries
  • Performance: Ausreichend für unseren Use-Case (keine Gaming-Performance nötig)
  • Hot-Reload: Schnelle Entwicklungszyklen

UI-Framework:

  • React Native Paper oder NativeBase für Material Design Komponenten
  • React Navigation für Routing
  • React Query für API State Management

Alternativen geprüft:

  • Native iOS/Swift + Android/Kotlin: Beste Performance, aber 2x Entwicklungsaufwand
  • Flutter: Gute Alternative, aber kleineres Ökosystem als React Native

1.4 Authentifizierung

Gewählt: JWT + OAuth 2.0

Implementierung:

  • JWT Tokens: Stateless Authentication mit Access (15min) + Refresh Tokens (7 Tage)
  • OAuth 2.0 Provider:
    • Google Sign-In (höchste Adoption)
    • Apple Sign-In (iOS App Store Requirement)
    • Email/Password als Fallback
  • Library: Passport.js (Backend) + React Native AppAuth (Frontend)
  • Security:
    • Tokens in Secure Storage (iOS Keychain, Android Keystore)
    • HTTPS-only
    • CSRF Protection
    • Rate Limiting auf Login-Endpoints

1.5 Hosting & Cloud-Provider

Gewählt: AWS (Amazon Web Services)

Begründung:

  • Marktführer: Größte Auswahl an Services, beste Dokumentation
  • Skalierbarkeit: Von MVP bis Millionen User ohne Platform-Wechsel
  • Geo-Distribution: CloudFront CDN, Multi-Region Deployment möglich
  • Managed Services: RDS (PostgreSQL), ElastiCache (Redis), S3 (Bilder)
  • Kosteneffizienz: Free Tier für Start, Pay-as-you-grow

Alternative für Early Stage:

  • Vercel/Railway für schnelleres MVP-Deployment
  • Migration zu AWS wenn Skalierung nötig wird

2. System-Architektur

2.1 High-Level Architektur

┌─────────────────────────────────────────────────────────────┐
│                        Clients                               │
│  ┌──────────────┐              ┌──────────────┐             │
│  │  iOS App     │              │ Android App  │             │
│  │ React Native │              │React Native  │             │
│  └──────────────┘              └──────────────┘             │
└─────────────────────────────────────────────────────────────┘

                          │ HTTPS/TLS

┌─────────────────────────────────────────────────────────────┐
│                    API Gateway / CDN                         │
│              AWS CloudFront + Application Load Balancer      │
└─────────────────────────────────────────────────────────────┘


┌─────────────────────────────────────────────────────────────┐
│                    Backend API Layer                         │
│  ┌────────────────────────────────────────────────────────┐ │
│  │         NestJS Application Servers                     │ │
│  │  ┌──────────┐ ┌──────────┐ ┌──────────┐              │ │
│  │  │ Auth API │ │ Task API │ │Points API│              │ │
│  │  └──────────┘ └──────────┘ └──────────┘              │ │
│  │  ┌──────────┐ ┌──────────┐                            │ │
│  │  │Partner API│ │User API  │                           │ │
│  │  └──────────┘ └──────────┘                            │ │
│  └────────────────────────────────────────────────────────┘ │
│                    (Auto-Scaling Group)                      │
└─────────────────────────────────────────────────────────────┘


┌─────────────────────────────────────────────────────────────┐
│                    Data Layer                                │
│  ┌──────────────┐         ┌──────────────┐                  │
│  │ PostgreSQL   │         │    Redis     │                  │
│  │   RDS        │         │ ElastiCache  │                  │
│  │              │         │              │                  │
│  │ - Users      │         │ - Sessions   │                  │
│  │ - Tasks      │         │ - Cache      │                  │
│  │ - Points     │         │ - Leaderboard│                  │
│  └──────────────┘         └──────────────┘                  │
│                                                              │
│  ┌──────────────┐                                           │
│  │   AWS S3     │                                           │
│  │              │                                           │
│  │ - User Photos│                                           │
│  │ - Task Images│                                           │
│  └──────────────┘                                           │
└─────────────────────────────────────────────────────────────┘


┌─────────────────────────────────────────────────────────────┐
│                External Services                             │
│  ┌──────────────┐ ┌──────────────┐ ┌──────────────┐        │
│  │   Google     │ │    Apple     │ │   Partner    │        │
│  │   OAuth      │ │    OAuth     │ │     APIs     │        │
│  └──────────────┘ └──────────────┘ └──────────────┘        │
└─────────────────────────────────────────────────────────────┘

2.2 API-Struktur

RESTful Endpoints:

Authentication:
POST   /api/v1/auth/register
POST   /api/v1/auth/login
POST   /api/v1/auth/refresh
POST   /api/v1/auth/oauth/google
POST   /api/v1/auth/oauth/apple

Users:
GET    /api/v1/users/me
PATCH  /api/v1/users/me
GET    /api/v1/users/:id/profile
GET    /api/v1/users/me/points

Tasks:
GET    /api/v1/tasks                    # List nearby tasks
POST   /api/v1/tasks                    # Create task
GET    /api/v1/tasks/:id
PATCH  /api/v1/tasks/:id
DELETE /api/v1/tasks/:id
POST   /api/v1/tasks/:id/apply          # Helper applies
POST   /api/v1/tasks/:id/complete       # Mark complete
POST   /api/v1/tasks/:id/confirm        # Creator confirms

Points:
GET    /api/v1/points/history
GET    /api/v1/points/leaderboard

Partners:
GET    /api/v1/partners
GET    /api/v1/partners/:id
POST   /api/v1/redemptions              # Redeem points
GET    /api/v1/redemptions/mine

API Versioning: URL-based (v1, v2, ...) für Breaking Changes

2.3 Security Layer

Implementierte Maßnahmen:

  1. Transport Security

    • HTTPS/TLS 1.3 everywhere
    • Certificate Pinning in Mobile Apps
  2. Authentication & Authorization

    • JWT mit short-lived Access Tokens
    • Refresh Token Rotation
    • Role-Based Access Control (RBAC)
  3. Input Validation

    • class-validator für alle Inputs
    • SQL Injection Prevention (Parameterized Queries)
    • XSS Prevention (Output Encoding)
  4. Rate Limiting

    • IP-based: 100 req/min für öffentliche Endpoints
    • User-based: 1000 req/hour für authenticated Endpoints
    • Sensitive Endpoints: 5 login attempts/15min
  5. Data Protection

    • Passwords: bcrypt (cost 12)
    • PII Encryption at Rest (AWS KMS)
    • GDPR Compliance: Data Export/Deletion

3. Deployment-Strategie

3.1 Environments

Development  → Lokale Docker-Container
Staging      → AWS (eu-central-1), kleinere Instances
Production   → AWS (eu-central-1), Multi-AZ

3.2 Infrastructure as Code

Tool: AWS CDK (TypeScript)

Vorteile:

  • Infrastructure in TypeScript = Same Language wie App
  • Type-Safe Infrastructure
  • Wiederverwendbare Constructs
  • CloudFormation Integration

3.3 CI/CD Pipeline

Tool: GitHub Actions

Pipeline Stages:

1. Code Push to GitHub

2. CI: Lint, Type-Check, Unit Tests

3. Build: Docker Images (Backend + Frontend)

4. Push to AWS ECR (Container Registry)

5. Deploy to Staging

6. E2E Tests auf Staging

7. Manual Approval

8. Deploy to Production (Blue-Green)

9. Smoke Tests

10. Health Check + Monitoring

Deployment Strategy: Blue-Green

  • Zero-Downtime Deployments
  • Instant Rollback möglich
  • Database Migrations vor Deployment

3.4 Monitoring & Observability

Tools:

  • Logging: AWS CloudWatch Logs
  • Metrics: CloudWatch Metrics + Custom Metrics
  • Tracing: AWS X-Ray für Distributed Tracing
  • Uptime: UptimeRobot oder AWS CloudWatch Alarms
  • Error Tracking: Sentry (Client + Server)
  • Analytics: Mixpanel oder Amplitude (User Behavior)

Key Metrics:

  • API Response Time (p50, p95, p99)
  • Error Rate
  • Database Connection Pool
  • Cache Hit Ratio
  • User Sign-ups per Day
  • Task Completion Rate

4. Skalierungs-Strategie

4.1 Skalierungs-Phasen

Phase 1: MVP (0-1.000 User)

  • Single Region (eu-central-1)
  • Backend: 2x t3.small Instances
  • Database: RDS db.t3.micro (Single-AZ)
  • Redis: ElastiCache t3.micro
  • Kosten: ~€100-150/Monat

Phase 2: Growth (1.000-10.000 User)

  • Auto-Scaling: 2-6 Instances (t3.medium)
  • Database: RDS db.t3.small (Multi-AZ)
  • Redis: ElastiCache r6g.large
  • CDN aktiviert (CloudFront)
  • Kosten: ~€300-500/Monat

Phase 3: Scale (10.000-100.000 User)

  • Auto-Scaling: 4-20 Instances (c6i.large)
  • Database: RDS db.r6g.xlarge (Multi-AZ, Read Replicas)
  • Redis Cluster: 3 Nodes
  • S3 + CloudFront Caching aggressive
  • Database Sharding vorbereiten
  • Kosten: ~€1.500-3.000/Monat

Phase 4: Hypergrowth (100.000+ User)

  • Multi-Region Deployment (eu-central-1 + eu-west-1)
  • Database Sharding (by Region/User-ID)
  • Microservices Split (Auth, Tasks, Points als separate Services)
  • Message Queue (AWS SQS) für Async Processing
  • Kosten: €10.000+/Monat

4.2 Skalierungs-Trigger

Backend Auto-Scaling Rules:

  • Scale OUT: CPU > 70% für 5 Minuten
  • Scale IN: CPU < 30% für 15 Minuten

Database Scaling:

  • Vertical: CPU > 80% sustained → größere Instance
  • Horizontal: Read Load > 60% → Add Read Replica

4.3 Bottleneck-Vermeidung

Potenzielle Bottlenecks:

  1. Database Writes

    • Problem: PostgreSQL Single-Writer
    • Lösung: Write-Through Cache (Redis), Batch Inserts, Connection Pooling
  2. Geo-Queries

    • Problem: Nachbarschaftssuche ist CPU-intensiv
    • Lösung: PostGIS Indexes, Cache häufige Searches, Pre-compute Popular Areas
  3. Point Transactions

    • Problem: Race Conditions bei gleichzeitigen Point-Updates
    • Lösung: Database Transactions mit SELECT FOR UPDATE, Optimistic Locking
  4. Image Uploads

    • Problem: Backend-Throughput für Uploads
    • Lösung: Direct S3 Upload mit Pre-Signed URLs (Backend generiert nur URL)

4.4 Cost Optimization

Strategien:

  • Reserved Instances für Baseline-Capacity (30-50% Ersparnis)
  • Spot Instances für Non-Critical Workloads
  • S3 Lifecycle Policies (alte Bilder nach 1 Jahr in Glacier)
  • CloudFront Caching (reduziert Backend-Load)
  • Database Query Optimization (Slow Query Log → Indexes)

5. Datenbank-Schema (Detail)

sql
-- Users Table
CREATE TABLE users (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  email VARCHAR(255) UNIQUE NOT NULL,
  password_hash VARCHAR(255),  -- NULL für OAuth-only Users
  name VARCHAR(255) NOT NULL,
  avatar_url VARCHAR(500),
  bio TEXT,
  location GEOGRAPHY(POINT),    -- PostGIS für Geo-Queries
  points_balance INTEGER DEFAULT 0 CHECK (points_balance >= 0),
  oauth_provider VARCHAR(50),   -- 'google', 'apple', NULL
  oauth_id VARCHAR(255),
  email_verified BOOLEAN DEFAULT FALSE,
  created_at TIMESTAMP DEFAULT NOW(),
  updated_at TIMESTAMP DEFAULT NOW()
);

CREATE INDEX idx_users_location ON users USING GIST(location);
CREATE INDEX idx_users_email ON users(email);

-- Tasks Table
CREATE TABLE tasks (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  creator_id UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,
  title VARCHAR(255) NOT NULL,
  description TEXT NOT NULL,
  location GEOGRAPHY(POINT) NOT NULL,
  address VARCHAR(500),
  points_reward INTEGER NOT NULL CHECK (points_reward > 0),
  status VARCHAR(50) NOT NULL DEFAULT 'open',  
    -- 'open', 'assigned', 'in_progress', 'completed', 'cancelled'
  helper_id UUID REFERENCES users(id) ON DELETE SET NULL,
  image_urls TEXT[],            -- Array of S3 URLs
  category VARCHAR(100),        -- 'handwerk', 'garten', 'technik', etc.
  created_at TIMESTAMP DEFAULT NOW(),
  completed_at TIMESTAMP,
  expires_at TIMESTAMP
);

CREATE INDEX idx_tasks_location ON tasks USING GIST(location);
CREATE INDEX idx_tasks_status ON tasks(status);
CREATE INDEX idx_tasks_creator ON tasks(creator_id);
CREATE INDEX idx_tasks_helper ON tasks(helper_id);

-- Point Transactions Table
CREATE TABLE point_transactions (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  user_id UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,
  amount INTEGER NOT NULL,       -- Positive = earned, Negative = spent
  type VARCHAR(50) NOT NULL,     -- 'task_completed', 'redemption', 'bonus', 'refund'
  task_id UUID REFERENCES tasks(id) ON DELETE SET NULL,
  redemption_id UUID REFERENCES redemptions(id) ON DELETE SET NULL,
  description TEXT,
  created_at TIMESTAMP DEFAULT NOW()
);

CREATE INDEX idx_point_transactions_user ON point_transactions(user_id, created_at DESC);

-- Partners Table
CREATE TABLE partners (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  name VARCHAR(255) NOT NULL,
  logo_url VARCHAR(500),
  description TEXT,
  website_url VARCHAR(500),
  is_active BOOLEAN DEFAULT TRUE,
  created_at TIMESTAMP DEFAULT NOW()
);

-- Redemptions Table
CREATE TABLE redemptions (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  user_id UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,
  partner_id UUID NOT NULL REFERENCES partners(id) ON DELETE RESTRICT,
  points_spent INTEGER NOT NULL CHECK (points_spent > 0),
  discount_code VARCHAR(100),
  discount_description TEXT,
  redeemed_at TIMESTAMP DEFAULT NOW(),
  expires_at TIMESTAMP
);

CREATE INDEX idx_redemptions_user ON redemptions(user_id, redeemed_at DESC);
CREATE INDEX idx_redemptions_partner ON redemptions(partner_id);

6. Entwicklungs-Workflow

6.1 Monorepo-Struktur

project-root/
├── apps/
│   ├── mobile/              # React Native App
│   │   ├── src/
│   │   ├── app.json
│   │   └── package.json
│   └── backend/             # NestJS API
│       ├── src/
│       ├── test/
│       └── package.json
├── packages/
│   └── shared/              # Shared TypeScript Code
│       ├── types/
│       └── validators/
├── infrastructure/          # AWS CDK Code
│   └── lib/
├── docker-compose.yml       # Lokale Dev-Environment
├── package.json
└── turbo.json               # Turborepo Config

Monorepo-Tool: Turborepo

  • Shared Dependencies
  • Parallel Builds
  • Smart Caching

6.2 Development Environment

Docker Compose Setup:

yaml
# docker-compose.yml
services:
  postgres:
    image: postgis/postgis:16-3.4
    ports: ["5432:5432"]
    environment:
      POSTGRES_DB: neighbor_dev
      POSTGRES_USER: dev
      POSTGRES_PASSWORD: dev
    volumes:
      - postgres-data:/var/lib/postgresql/data

  redis:
    image: redis:7-alpine
    ports: ["6379:6379"]

  backend:
    build: ./apps/backend
    ports: ["3000:3000"]
    environment:
      DATABASE_URL: postgresql://dev:dev@postgres:5432/neighbor_dev
      REDIS_URL: redis://redis:6379
    volumes:
      - ./apps/backend:/app
    command: npm run start:dev

volumes:
  postgres-data:

6.3 Testing-Strategie

Test-Pyramide:

        /\
       /E2E\          5% - Playwright Tests (Critical User Flows)
      /------\
     /Integration\   15% - API Tests (Supertest + Test DB)
    /------------\
   / Unit Tests  \  80% - Jest Unit Tests (Business Logic)
  /--------------\

Test-Coverage Ziel: 80% für Backend, 60% für Frontend

7. Risiken & Mitigations

RisikoImpactWahrscheinlichkeitMitigation
Datenschutz-VerletzungHochNiedrigGDPR-Compliance, Security Audits, Verschlüsselung
Datenbank-AusfallHochNiedrigMulti-AZ RDS, Automated Backups, Disaster Recovery Plan
PunktebetrugMittelMittelTask-Confirmation Flow, Fraud Detection, Rate Limiting
Zu langsame Geo-QueriesMittelMittelPostGIS Indexes, Caching, Query Optimization
API-ÜberlastungMittelNiedrigAuto-Scaling, Rate Limiting, CDN
Vendor Lock-in AWSNiedrigHochAbstraction Layer für kritische Services, IaC

8. Migration & Rollout-Plan

8.1 MVP-Launch (Woche 1-8)

Scope:

  • User Registration & Login
  • Task Creation & Browsing
  • Basic Point System
  • 1-2 Partner-Integrationen

Infra:

  • Staging + Production Environment
  • Basic Monitoring
  • Manual Deployments

8.2 Beta-Phase (Woche 9-12)

Scope:

  • Push Notifications
  • Advanced Filters
  • User Ratings & Reviews
  • More Partners

Infra:

  • CI/CD Pipeline
  • Automated Testing
  • Error Tracking

8.3 Public Launch (Woche 13+)

Scope:

  • Marketing Landing Page
  • Referral Program
  • Analytics Dashboard
  • Admin Panel

Infra:

  • Auto-Scaling konfiguriert
  • Performance Optimizations
  • Cost Monitoring

9. Entscheidungsmatrix

KriteriumNode.js/TSPythonGoGewichtGewinner
Dev Speed9/107/106/1030%Node.js
Performance7/105/1010/1020%Go
Ecosystem9/108/106/1025%Node.js
Code Sharing10/105/105/1015%Node.js
Team Skills8/107/106/1010%Node.js
Total8.456.76.95Node.js
KriteriumReact NativeNativeFlutterGewichtGewinner
Dev Speed9/104/108/1035%React Native
Performance7/1010/108/1020%Native
Code Reuse10/100/1010/1025%RN/Flutter
Ecosystem9/108/107/1015%React Native
Hiring8/106/106/105%React Native
Total8.65.98.15React Native

10. Nächste Schritte

  1. ✅ Architektur-Dokument erstellt
  2. ⏭️ Projekt-Repository Setup (GitHub)
  3. ⏭️ Monorepo-Struktur initialisieren
  4. ⏭️ Docker Development Environment aufsetzen
  5. ⏭️ AWS Account & CDK Infrastructure Setup
  6. ⏭️ Backend Scaffold (NestJS)
  7. ⏭️ Frontend Scaffold (React Native + Expo)
  8. ⏭️ Database Schema implementieren
  9. ⏭️ Authentication Flow implementieren
  10. ⏭️ MVP Feature Development starten

Review & Approval: Dieses Dokument sollte vom Team reviewed werden bevor mit der Implementierung begonnen wird.

Good Deeds - Nachbarschaftshilfe-App