System-Diagramme - Nachbarschaftshilfe-App

1. Deployment-Architektur (AWS)

graph TB
    subgraph "Clients"
        iOS[iOS App<br/>React Native]
        Android[Android App<br/>React Native]
    end

    subgraph "AWS Cloud - eu-central-1"
        subgraph "Edge Layer"
            CF[CloudFront CDN<br/>Static Assets + Caching]
            ALB[Application Load Balancer<br/>HTTPS Termination]
        end

        subgraph "Compute Layer - Auto Scaling Group"
            API1[NestJS API<br/>Instance 1]
            API2[NestJS API<br/>Instance 2]
            API3[NestJS API<br/>Instance N]
        end

        subgraph "Data Layer"
            RDS[(PostgreSQL RDS<br/>Multi-AZ<br/>Primary + Standby)]
            Redis[(Redis ElastiCache<br/>Sessions + Cache)]
            S3[S3 Bucket<br/>Images + Assets]
        end

        subgraph "Monitoring"
            CW[CloudWatch<br/>Logs + Metrics]
            Sentry[Sentry<br/>Error Tracking]
        end
    end

    subgraph "External Services"
        GoogleOAuth[Google OAuth]
        AppleOAuth[Apple Sign In]
        PartnerAPIs[Partner APIs<br/>Redemptions]
    end

    iOS --> CF
    Android --> CF
    CF --> ALB
    ALB --> API1
    ALB --> API2
    ALB --> API3

    API1 --> RDS
    API1 --> Redis
    API1 --> S3
    API2 --> RDS
    API2 --> Redis
    API2 --> S3
    API3 --> RDS
    API3 --> Redis
    API3 --> S3

    API1 --> CW
    API2 --> CW
    API3 --> CW
    API1 --> Sentry
    API2 --> Sentry
    API3 --> Sentry

    API1 --> GoogleOAuth
    API1 --> AppleOAuth
    API1 --> PartnerAPIs
    API2 --> GoogleOAuth
    API2 --> AppleOAuth
    API2 --> PartnerAPIs

2. Backend Service-Architektur (NestJS)

graph LR
    subgraph "NestJS Application"
        subgraph "API Layer"
            AuthController[Auth Controller<br/>Login/Register]
            UserController[User Controller<br/>Profile/Points]
            TaskController[Task Controller<br/>CRUD/Search]
            PartnerController[Partner Controller<br/>Redemptions]
        end

        subgraph "Business Logic Layer"
            AuthService[Auth Service<br/>JWT/OAuth]
            UserService[User Service]
            TaskService[Task Service]
            PointService[Point Service<br/>Transactions]
            PartnerService[Partner Service]
            GeoService[Geo Service<br/>Location Search]
        end

        subgraph "Data Access Layer"
            TypeORM[TypeORM<br/>Database Entities]
            RedisClient[Redis Client<br/>Cache + Sessions]
            S3Client[S3 Client<br/>Image Uploads]
        end

        subgraph "Middleware & Guards"
            JWTGuard[JWT Auth Guard]
            RateLimiter[Rate Limiter]
            ValidationPipe[Validation Pipe]
            LoggingInterceptor[Logging Interceptor]
        end
    end

    AuthController --> AuthService
    UserController --> UserService
    TaskController --> TaskService
    PartnerController --> PartnerService

    AuthService --> TypeORM
    AuthService --> RedisClient
    UserService --> TypeORM
    UserService --> PointService
    TaskService --> TypeORM
    TaskService --> GeoService
    TaskService --> S3Client
    PointService --> TypeORM
    PartnerService --> TypeORM

    JWTGuard --> AuthService
    AuthController -.middleware.-> JWTGuard
    UserController -.middleware.-> JWTGuard
    TaskController -.middleware.-> JWTGuard
    PartnerController -.middleware.-> JWTGuard

    AuthController -.middleware.-> RateLimiter
    AuthController -.middleware.-> ValidationPipe

3. Datenbank-Schema (Entity Relationship)

erDiagram
    USERS ||--o{ TASKS : creates
    USERS ||--o{ TASKS : helps_with
    USERS ||--o{ POINT_TRANSACTIONS : has
    USERS ||--o{ REDEMPTIONS : redeems
    TASKS ||--o{ POINT_TRANSACTIONS : generates
    PARTNERS ||--o{ REDEMPTIONS : offers
    REDEMPTIONS ||--o| POINT_TRANSACTIONS : consumes

    USERS {
        uuid id PK
        string email UK
        string password_hash
        string name
        point location "PostGIS"
        int points_balance
        string oauth_provider
        string oauth_id
        timestamp created_at
    }

    TASKS {
        uuid id PK
        uuid creator_id FK
        string title
        text description
        point location "PostGIS"
        int points_reward
        string status "open|assigned|completed"
        uuid helper_id FK
        text[] image_urls
        string category
        timestamp created_at
        timestamp completed_at
    }

    POINT_TRANSACTIONS {
        uuid id PK
        uuid user_id FK
        int amount "positive=earn,negative=spend"
        string type
        uuid task_id FK
        uuid redemption_id FK
        timestamp created_at
    }

    PARTNERS {
        uuid id PK
        string name
        string logo_url
        text description
        boolean is_active
        timestamp created_at
    }

    REDEMPTIONS {
        uuid id PK
        uuid user_id FK
        uuid partner_id FK
        int points_spent
        string discount_code
        timestamp redeemed_at
        timestamp expires_at
    }

4. Task-Lifecycle (State Machine)

stateDiagram-v2
    [*] --> Open: Creator erstellt Task
    
    Open --> Assigned: Helper bewirbt sich,<br/>Creator akzeptiert
    Open --> Cancelled: Creator löscht Task
    
    Assigned --> InProgress: Helper startet Task
    Assigned --> Open: Helper sagt ab
    
    InProgress --> PendingConfirmation: Helper markiert<br/>als erledigt
    InProgress --> Open: Helper bricht ab
    
    PendingConfirmation --> Completed: Creator bestätigt<br/>+ Punkte übertragen
    PendingConfirmation --> InProgress: Creator lehnt ab,<br/>Nachbesserung nötig
    
    Completed --> [*]
    Cancelled --> [*]

5. Authentication-Flow (OAuth + JWT)

sequenceDiagram
    participant User
    participant App as Mobile App
    participant API as Backend API
    participant OAuth as OAuth Provider<br/>(Google/Apple)
    participant DB as Database

    User->>App: Tap "Sign in with Google"
    App->>OAuth: Redirect to OAuth Login
    OAuth->>User: Show Login Page
    User->>OAuth: Enter Credentials
    OAuth->>App: Authorization Code
    App->>API: POST /auth/oauth/google<br/>{code}
    API->>OAuth: Exchange Code for Token
    OAuth->>API: User Profile + OAuth Token
    API->>DB: Find or Create User
    DB->>API: User Record
    API->>API: Generate JWT Access Token<br/>+ Refresh Token
    API->>App: {accessToken, refreshToken}
    App->>App: Store Tokens in<br/>Secure Storage
    App->>User: Navigate to Home Screen

    Note over App,API: Subsequent Requests
    App->>API: GET /tasks<br/>Authorization: Bearer {accessToken}
    API->>API: Verify JWT Signature
    API->>DB: Fetch Tasks
    DB->>API: Task List
    API->>App: Task Response

    Note over App,API: Token Refresh (when expired)
    App->>API: POST /auth/refresh<br/>{refreshToken}
    API->>API: Verify Refresh Token
    API->>App: {newAccessToken, newRefreshToken}

6. Point-Transaction-Flow (Task Completion)

sequenceDiagram
    participant Helper
    participant Creator
    participant API
    participant DB
    participant Notification

    Helper->>API: POST /tasks/:id/complete
    API->>DB: Update Task status<br/>→ 'pending_confirmation'
    DB->>API: Task Updated
    API->>Notification: Push to Creator<br/>"Task completed,<br/>please confirm"
    API->>Helper: 200 OK

    Creator->>API: POST /tasks/:id/confirm
    API->>DB: BEGIN TRANSACTION
    API->>DB: Update Task status<br/>→ 'completed'
    API->>DB: INSERT point_transaction<br/>(helper, +points, 'task_completed')
    API->>DB: UPDATE users<br/>SET points_balance = <br/>points_balance + reward<br/>WHERE id = helper_id
    API->>DB: COMMIT TRANSACTION
    DB->>API: Transaction Success
    API->>Notification: Push to Helper<br/>"You earned X points!"
    API->>Creator: 200 OK

7. Geo-Search-Flow (Nearby Tasks)

sequenceDiagram
    participant User
    participant App
    participant API
    participant Redis
    participant DB

    User->>App: Open Task List
    App->>App: Get GPS Location<br/>(lat, lng)
    App->>API: GET /tasks?<br/>lat=52.52&lng=13.405<br/>radius=5000
    
    API->>Redis: Check Cache<br/>geo:52.52:13.405:5000
    
    alt Cache Hit
        Redis->>API: Cached Task List
        API->>App: Task Response
    else Cache Miss
        API->>DB: SELECT * FROM tasks<br/>WHERE status = 'open'<br/>AND ST_DWithin(<br/>  location,<br/>  ST_MakePoint(13.405, 52.52),<br/>  5000<br/>)<br/>ORDER BY created_at DESC
        DB->>API: Nearby Tasks
        API->>Redis: Store in Cache<br/>TTL = 60 seconds
        API->>App: Task Response
    end

    App->>User: Display Task Cards<br/>on Map + List

8. CI/CD-Pipeline (GitHub Actions → AWS)

graph TD
    A[Developer Push<br/>to main branch] --> B[GitHub Actions<br/>Trigger]
    
    B --> C1[Lint Code<br/>ESLint + Prettier]
    B --> C2[Type Check<br/>TypeScript]
    B --> C3[Unit Tests<br/>Jest]
    
    C1 --> D{All Checks<br/>Pass?}
    C2 --> D
    C3 --> D
    
    D -->|No| E[Fail Build<br/>Notify Developer]
    D -->|Yes| F[Build Docker Images<br/>Backend + Frontend]
    
    F --> G[Push to AWS ECR<br/>Container Registry]
    G --> H[Deploy to Staging<br/>ECS/Fargate]
    
    H --> I[Run E2E Tests<br/>Playwright on Staging]
    
    I --> J{E2E Pass?}
    J -->|No| K[Rollback Staging<br/>Alert Team]
    J -->|Yes| L[Manual Approval<br/>Deploy to Production?]
    
    L -->|Approved| M[Blue-Green Deploy<br/>to Production]
    M --> N[Health Check<br/>Smoke Tests]
    
    N --> O{Healthy?}
    O -->|No| P[Automatic Rollback<br/>to Previous Version]
    O -->|Yes| Q[Complete Deployment<br/>Notify Team]

9. Skalierungs-Evolution

graph LR
    subgraph "Phase 1: MVP<br/>0-1K Users"
        P1[2x t3.small<br/>No Auto-Scaling<br/>Single-AZ DB<br/>~€100/mo]
    end

    subgraph "Phase 2: Growth<br/>1K-10K Users"
        P2[2-6x t3.medium<br/>Auto-Scaling ON<br/>Multi-AZ DB<br/>CDN Enabled<br/>~€400/mo]
    end

    subgraph "Phase 3: Scale<br/>10K-100K Users"
        P3[4-20x c6i.large<br/>Redis Cluster<br/>Read Replicas<br/>~€2000/mo]
    end

    subgraph "Phase 4: Hypergrowth<br/>100K+ Users"
        P4[Multi-Region<br/>DB Sharding<br/>Microservices<br/>Message Queue<br/>~€10K+/mo]
    end

    P1 -->|Growth| P2
    P2 -->|Growth| P3
    P3 -->|Growth| P4

    style P1 fill:#90EE90
    style P2 fill:#FFD700
    style P3 fill:#FFA500
    style P4 fill:#FF6347

10. Monitoring Dashboard (Konzept)

graph TB
    subgraph "Monitoring Stack"
        subgraph "Metrics"
            M1[API Response Time<br/>p50, p95, p99]
            M2[Request Rate<br/>req/sec]
            M3[Error Rate<br/>%]
            M4[Database<br/>Connection Pool]
            M5[Cache Hit Ratio<br/>%]
        end

        subgraph "Business Metrics"
            B1[Active Users<br/>DAU/MAU]
            B2[Tasks Created/Day]
            B3[Tasks Completed/Day]
            B4[Point Transactions<br/>per Day]
            B5[Redemptions/Day]
        end

        subgraph "Alerts"
            A1[Error Rate > 1%<br/>→ PagerDuty]
            A2[API p95 > 500ms<br/>→ Slack]
            A3[DB CPU > 80%<br/>→ Auto-Scale]
        end
    end

    M1 --> CloudWatch
    M2 --> CloudWatch
    M3 --> CloudWatch
    M4 --> CloudWatch
    M5 --> CloudWatch

    B1 --> Analytics[Mixpanel/<br/>Amplitude]
    B2 --> Analytics
    B3 --> Analytics
    B4 --> Analytics
    B5 --> Analytics

    CloudWatch --> A1
    CloudWatch --> A2
    CloudWatch --> A3

    style M1 fill:#87CEEB
    style M2 fill:#87CEEB
    style M3 fill:#87CEEB
    style M4 fill:#87CEEB
    style M5 fill:#87CEEB
    style B1 fill:#98FB98
    style B2 fill:#98FB98
    style B3 fill:#98FB98
    style B4 fill:#98FB98
    style B5 fill:#98FB98
    style A1 fill:#FFB6C1
    style A2 fill:#FFB6C1
    style A3 fill:#FFB6C1

---

Hinweis: Diese Diagramme verwenden Mermaid-Syntax und können in GitHub, GitLab, Notion und vielen Markdown-Viewers direkt gerendert werden.