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/mineAPI Versioning: URL-based (v1, v2, ...) für Breaking Changes
2.3 Security Layer
Implementierte Maßnahmen:
Transport Security
- HTTPS/TLS 1.3 everywhere
- Certificate Pinning in Mobile Apps
Authentication & Authorization
- JWT mit short-lived Access Tokens
- Refresh Token Rotation
- Role-Based Access Control (RBAC)
Input Validation
- class-validator für alle Inputs
- SQL Injection Prevention (Parameterized Queries)
- XSS Prevention (Output Encoding)
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
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-AZ3.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 + MonitoringDeployment 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:
Database Writes
- Problem: PostgreSQL Single-Writer
- Lösung: Write-Through Cache (Redis), Batch Inserts, Connection Pooling
Geo-Queries
- Problem: Nachbarschaftssuche ist CPU-intensiv
- Lösung: PostGIS Indexes, Cache häufige Searches, Pre-compute Popular Areas
Point Transactions
- Problem: Race Conditions bei gleichzeitigen Point-Updates
- Lösung: Database Transactions mit SELECT FOR UPDATE, Optimistic Locking
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)
-- 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 ConfigMonorepo-Tool: Turborepo
- Shared Dependencies
- Parallel Builds
- Smart Caching
6.2 Development Environment
Docker Compose Setup:
# 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
| Risiko | Impact | Wahrscheinlichkeit | Mitigation |
|---|---|---|---|
| Datenschutz-Verletzung | Hoch | Niedrig | GDPR-Compliance, Security Audits, Verschlüsselung |
| Datenbank-Ausfall | Hoch | Niedrig | Multi-AZ RDS, Automated Backups, Disaster Recovery Plan |
| Punktebetrug | Mittel | Mittel | Task-Confirmation Flow, Fraud Detection, Rate Limiting |
| Zu langsame Geo-Queries | Mittel | Mittel | PostGIS Indexes, Caching, Query Optimization |
| API-Überlastung | Mittel | Niedrig | Auto-Scaling, Rate Limiting, CDN |
| Vendor Lock-in AWS | Niedrig | Hoch | Abstraction 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
| Kriterium | Node.js/TS | Python | Go | Gewicht | Gewinner |
|---|---|---|---|---|---|
| Dev Speed | 9/10 | 7/10 | 6/10 | 30% | Node.js |
| Performance | 7/10 | 5/10 | 10/10 | 20% | Go |
| Ecosystem | 9/10 | 8/10 | 6/10 | 25% | Node.js |
| Code Sharing | 10/10 | 5/10 | 5/10 | 15% | Node.js |
| Team Skills | 8/10 | 7/10 | 6/10 | 10% | Node.js |
| Total | 8.45 | 6.7 | 6.95 | Node.js |
| Kriterium | React Native | Native | Flutter | Gewicht | Gewinner |
|---|---|---|---|---|---|
| Dev Speed | 9/10 | 4/10 | 8/10 | 35% | React Native |
| Performance | 7/10 | 10/10 | 8/10 | 20% | Native |
| Code Reuse | 10/10 | 0/10 | 10/10 | 25% | RN/Flutter |
| Ecosystem | 9/10 | 8/10 | 7/10 | 15% | React Native |
| Hiring | 8/10 | 6/10 | 6/10 | 5% | React Native |
| Total | 8.6 | 5.9 | 8.15 | React Native |
10. Nächste Schritte
- ✅ Architektur-Dokument erstellt
- ⏭️ Projekt-Repository Setup (GitHub)
- ⏭️ Monorepo-Struktur initialisieren
- ⏭️ Docker Development Environment aufsetzen
- ⏭️ AWS Account & CDK Infrastructure Setup
- ⏭️ Backend Scaffold (NestJS)
- ⏭️ Frontend Scaffold (React Native + Expo)
- ⏭️ Database Schema implementieren
- ⏭️ Authentication Flow implementieren
- ⏭️ MVP Feature Development starten
Review & Approval: Dieses Dokument sollte vom Team reviewed werden bevor mit der Implementierung begonnen wird.
