# TaskFlow Architektur

**Stand:** 2026-02-03

---

## Stack

| Schicht | Technologie |
|---|---|
| **Frontend** | React 18, TypeScript, Tailwind CSS, shadcn/ui, Vite |
| **Backend** | Express.js, TypeScript, Node.js |
| **Datenbank** | PostgreSQL 15, Drizzle ORM |
| **State** | TanStack Query (Client), Express Session (Server) |
| **Auth** | Passport.js (Local Strategy), API Key, 2FA (Email OTP) |
| **Build** | Vite (Frontend), ESBuild (Server Bundle) |
| **Deployment** | Docker, Docker Compose |

---

## Verzeichnisstruktur

```
/opt/task-manager/
├── client/                     # React Frontend
│   └── src/
│       ├── components/         # UI-Komponenten
│       │   ├── adhd/           # ADHD-Mode Features
│       │   ├── admin/          # Admin-Panel
│       │   └── gamification/   # Gamification UI
│       ├── pages/              # Seitenkomponenten
│       ├── hooks/              # Custom React Hooks
│       └── lib/                # Utilities, API Client
├── server/                     # Express Backend
│   ├── index.ts               # Server Entry Point
│   ├── routes.ts              # API Routes (~2400 Zeilen)
│   ├── storage.ts             # Storage Interface + Implementierungen
│   ├── auth.ts                # Passport Auth + Session
│   ├── api-key-auth.ts        # API Key Middleware [NEU]
│   ├── mcp.ts                 # MCP Server (JSON-RPC)
│   ├── ai.ts                  # AI Service (Chat, Scheduling)
│   ├── gamification.ts        # XP, Levels, Streaks
│   ├── email.ts               # SMTP Email Service
│   ├── push.ts                # Web Push Notifications
│   ├── db.ts                  # Database Connection
│   └── services/
│       └── recurrence.ts      # Recurring Tasks
├── shared/                     # Shared Types
│   ├── schema.ts              # Drizzle DB Schema + Zod
│   └── gamification.ts        # XP/Level Constants
├── docs/                       # Dokumentation
│   ├── ARCHITECTURE.md        # Diese Datei
│   ├── API-REFERENCE.md       # API Dokumentation
│   └── REFACTORING-REVIEW.md  # Code Review
├── docker-compose.yml
├── Dockerfile
└── package.json
```

---

## Features

### Core
- Task CRUD mit Labels, Prioritäten, Due-Dates
- Kalender-Ansicht (Drag & Drop)
- Kanban Board (Traditional, Weekly, Monthly)
- Subtasks / Parent-Child Beziehungen
- Time Tracking mit Timer
- Task Sharing (User-to-User, Label Sharing)

### Gamification
- XP-System mit Levels
- Tägliche Streaks
- Rewards Shop
- Leaderboard
- Daily Challenges

### ADHD Mode
- Quick Win List (kurze Tasks zuerst)
- Single Task View (Fokus-Modus)
- Energy Check-In (Low/Medium/High)
- Break Reminders
- Hyperfocus Guard
- Visual Timer
- Body Doubling Sessions

### AI Integration
- Chat mit Kontext (Tasks, User-Profil)
- Auto-Scheduling (AI plant Task-Termine)
- Task Completion Analysis
- Task Breakdown (AI teilt große Tasks auf)
- Configurable Provider (OpenAI, Ollama, etc.)

### Communication
- Email (Passwort-Reset, 2FA, Routinen)
- Web Push Notifications
- MCP Server (für AI-Tools)

### Admin
- User Management (erstellen, deaktivieren, löschen)
- System Settings (SMTP, AI, Registration)
- Audit Logs
- XP Reset

---

## Datenmodell (Wichtigste Tabellen)

```
users ──┬── tasks ──── labels
        │       └── sharedTasks
        ├── conversations ── messages
        ├── xpEvents
        ├── userRewards ── rewards
        ├── focusSessions
        ├── dailyChallenges
        ├── breakLogs
        ├── energyLogs
        └── auditLogs
```

---

## Auth-Flow

```
Browser Request
  │
  ├── Hat Session Cookie? → Passport Session Auth → req.user
  │
  ├── Hat X-API-Key / Bearer? → API Key Middleware → req.user
  │
  └── Keins von beiden → 401 Unauthorized
```

---

## Deployment

### Lokal (Development)
```bash
cd /opt/task-manager
npm run dev  # Vite + Express auf Port 5001
```

### Docker (Production)
```bash
docker-compose up -d  # PostgreSQL + App auf Port 5000
```

### Live
- **URL:** https://task.nothaft.cloud
- Reverse Proxy davor (vermutlich Caddy/Nginx)

---

*Letzte Aktualisierung: 2026-02-03*
