# 📋 Design Document: Steady – ADHD-Friendly Flask Task Manager

## 1. Projektübersicht

**Steady** ist eine Flask-basierte, ADHS-freundliche Task-Management-Anwendung, die wissenschaftliche Erkenntnisse über Executive Function Deficits in ein intuitives, beruhigendes UI übersetzt. Die App compensiert typische ADHS-Herausforderungen wie Time Blindness, Working Memory Limits und Entscheidungsparalyse durch strukturierte, visuell ruhige Interaktion.

---

## 2. Technische Architektur

### 2.1 Stack
- **Backend**: Flask 3.x mit Application-Factory- und Blueprint-Architektur
- **Database**: SQLite3 (Flask-SQLAlchemy ORM)
- **Authentifizierung**: Flask-Login (Passwort-Hashing via werkzeug.security)
- **Frontend**: Jinja2 Templates + Vanilla CSS (keine Frameworks, nur Reset) + Vanilla JS
- **Sicherung**: JSON Export/Import für User-Backups
- **Erweiterbarkeit**: Unabhängige Feature-Packages, Config-driven Feature Toggles, versionierbare API

### 2.2 Verbindliche Architekturprinzipien

- Die Flask-App **muss Raum für weitere Apps und Features lassen**. Jede fachliche Funktion wird als eigenständiges Feature-Package mit Blueprint, Routes, Models, Services und optionalen Templates angelegt.
- Die Application Factory (`create_app`) erstellt und konfiguriert App-Instanzen. Globale Erweiterungen werden ungebunden in `extensions.py` definiert und per `init_app()` verbunden.
- Features dürfen keine internen Routes, Models oder Templates anderer Features importieren. Gemeinsame, fachlich neutrale Bausteine gehören nach `app/core/`; notwendige fachübergreifende Abläufe nutzen dokumentierte Service-Schnittstellen.
- Neue Features müssen registriert oder über Konfiguration aktiviert werden können, ohne bestehende Feature-Packages umzubauen.
- Erweiterbarkeit darf Sicherheit, Tests, Barrierefreiheit oder Wartbarkeit nicht umgehen. Etablierte Flask- und Python-Best-Practices sind verpflichtend.

### 2.3 Verzeichnisstruktur
```
steady/
├── app/
│   ├── __init__.py           # create_app() und Blueprint-Registrierung
│   ├── extensions.py         # db, login_manager, csrf (ungebunden)
│   ├── core/                 # Gemeinsame Fehlerseiten und neutrale Services
│   ├── auth/                 # Eigenständiges Auth-Feature
│   │   ├── __init__.py
│   │   ├── routes.py
│   │   ├── models.py
│   │   └── services.py
│   ├── tasks/                # Eigenständiges Task-Feature
│   │   ├── __init__.py
│   │   ├── routes.py
│   │   ├── models.py
│   │   └── services.py
│   ├── settings/             # Eigenständiges Settings-Feature
│   ├── admin/                # Deaktivierbares zukünftiges Feature
│   ├── api/                  # Versionierte API-Blueprints (zukünftig)
│   │   └── v1/
│   ├── templates/
│   │   ├── base.html
│   │   ├── auth/
│   │   ├── dashboard/
│   │   ├── tasks/
│   │   ├── settings/
│   │   └── admin/
│   └── static/
│       ├── css/
│       │   └── style.css     # Pastel Design-System
│       └── js/
│           └── main.js
├── config.py                 # Umgebungsconfig und Feature Toggles
├── wsgi.py                   # Produktions-Entrypoint
├── requirements.txt
├── instance/
│   └── steady.db             # SQLite Database
└── tests/                    # Unit- und Feature-Integrationstests
    ├── conftest.py
    ├── auth/
    └── tasks/
```

Diese Struktur ist ein Vertrag: Neue Funktionen wie Kalender, Coaching oder Benachrichtigungen werden als zusätzliche Packages unter `app/` ergänzt. Nur tatsächlich gemeinsam genutzter, fachlich neutraler Code darf nach `app/core/` verschoben werden.

---

## 3. Datenbank-Modell (SQLite/SQLAlchemy)

### 3.1 User Model
```python
class User(UserMixin, db.Model):
    id = db.Column(db.Integer, primary_key=True)
    username = db.Column(db.String(80), unique=True, nullable=False)
    email = db.Column(db.String(120), unique=True, nullable=False)
    password_hash = db.Column(db.String(256), nullable=False)
    role = db.Column(db.String(20), default='user')  # user, admin, viewer, coach
    created_at = db.Column(db.DateTime, default=datetime.utcnow)
    
    # Settings (JSON-serialized)
    theme = db.Column(db.String(20), default='auto')  # auto, light, dark
    completion_chime = db.Column(db.Boolean, default=True)
    dyslexia_font = db.Column(db.Boolean, default=False)
    notification_frequency = db.Column(db.String(20), default='quiet')  # quiet, moderate, alert
    
    tasks = db.relationship('Task', backref='owner', lazy=True)
```

### 3.2 Task Model
```python
class Task(db.Model):
    id = db.Column(db.Integer, primary_key=True)
    title = db.Column(db.String(200), nullable=False)
    description = db.Column(db.Text, nullable=True)
    status = db.Column(db.String(20), default='not_started')  # not_started, in_progress, done
    priority = db.Column(db.String(20), default='normal')     # urgent, important, normal
    created_at = db.Column(db.DateTime, default=datetime.utcnow)
    due_date = db.Column(db.DateTime, nullable=True)
    completed_at = db.Column(db.DateTime, nullable=True)
    user_id = db.Column(db.Integer, db.ForeignKey('user.id'), nullable=False)
    
    # ADHD Features
    subtasks = db.relationship('Subtask', backref='parent_task', lazy=True)
    timer_seconds = db.Column(db.Integer, default=0)  # Countdown Timer
    context = db.Column(db.String(100), nullable=True)  # Location/Context-based reminders
    chunk_sessions = db.Column(db.JSON, default=list)    # Time-block sessions ["5min", "5min"]
```

### 3.3 Subtask Model
```python
class Subtask(db.Model):
    id = db.Column(db.Integer, primary_key=True)
    title = db.Column(db.String(100), nullable=False)
    completed = db.Column(db.Boolean, default=False)
    task_id = db.Column(db.Integer, db.ForeignKey('task.id'), nullable=False)
```

---

## 4. ADHS-UX/UI Richtlinien (aus ADHD.md abgeleitet)

### 4.1 Feature 1: Radical Reduction of Visible Items [1]
- **Today View** zeigt maximal 7 Items (Working Memory Cap) [1][2]
- Future-dated Items werden automatisch versteckt (Deferr/Snooze) [1]
- **One Primary Action** surfaced at a time in Focus Mode [1]

### 4.2 Feature 2: Frictionless Capture [1]
- Voice Input / Quick Add (<3 Sekunden) [1]
- Unstructured Inbox First, dann Organization [1]
- Markdown/Text Bulk Import [1]

### 4.3 Feature 3: Concrete External Time Structures [1]
- Visual Countdown Timer pro Task [1]
- Progress Bars für Time Blindness Countermeasure [1]
- Task Chunking in Time-Blocks (z.B. "3 x 5-min") [1]
- Context-based Reminders (Location) statt Fixed-Clock Alerts [1]

### 4.4 Feature 4: Forgiving, Shame-Free Feedback [1]
- Keine roten Overdue-Warnungen [1]
- Streak Freeze (Flexible Goals) [1]
- Immediate Positive Feedback (Animation + Audio Chime) [1]

### 4.5 Feature 5: Task Decomposition [1]
- Subtask-System für Step-by-Step Scaffolding [1]
- Persistent Progress Indicators [1]
- Sequential Task Lists (nur nächster Schritt) [1]

### 4.6 Feature 6: Visual Simplicity [1]
- Minimalist Layout mit Generous White Space [1]
- Consistent Navigation [1]
- User-Controlled Notifications (Default: Quiet) [1]
- System "Reduce Motion" Respekt [1]

### 4.7 Feature 7: Personalization [1]
- Theme Toggle (Light/Dark/Auto) [1]
- Dyslexia-Friendly Font Toggle [1]
- Customizable Notification Frequency [1]

---

## 5. Design-System (CSS Variables)

```css
:root {
    /* Pastel Palette */
    --lavender: #B8A9C9;  /* Primary Actions, Important Tasks */
    --blue: #A8D8EA;      /* Completed Tasks */
    --yellow: #FFEAA7;    /* Urgent Tasks */
    --purple: #D4A5FF;    /* Not Started Tasks */
    --orange: #FFB4A2;    /* In Progress Tasks */
    --beige: #F5F0E8;     /* Background Light */
    --dark-bg: #1E1E24;   /* Background Dark */
    --text-primary: #2D2D3A;
    --text-secondary: #6B6B7B;
    --success: #A8D8EA;
    --warning: #FFEAA7;
    --error: #FFB4A2;     /* Nur für positive Feedback, nie für Overdue */
}

/* ADHD Guidelines: ruhige, gezielte Übergänge statt transition: all */
button,
a,
.task-card {
    transition: color 0.2s ease, background-color 0.2s ease,
                border-color 0.2s ease, transform 0.2s ease;
}

/* Generous White Space */
.task-card {
    padding: 1.5rem;
    margin-bottom: 1rem;
}

/* Accessibility-Best-Practice: Systemeinstellung respektieren */
@media (prefers-reduced-motion: reduce) {
    *, *::before, *::after {
        scroll-behavior: auto !important;
        transition-duration: 0.01ms !important;
        animation-duration: 0.01ms !important;
        animation-iteration-count: 1 !important;
    }
}
```

---

## 6. Feature-Phasen & Task-Liste

### Phase 1: Core Infrastruktur (Week 1-2)
- [x] Flask Application Factory mit unabhängiger Blueprint-Registrierung [3]
- [x] Zentrale, ungebundene Extensions mit `init_app()` [3]
- [x] Config-Klassen für Development, Testing und Production sowie Feature Toggles [3]
- [x] SQLite Database Setup mit SQLAlchemy [3]
- [x] User Model & Registration/Login Routes [3]
- [x] Password Hashing mit werkzeug.security [3]
- [x] Session Cookie Security (HttpOnly, SameSite=Lax) [3]
- [x] Jinja2 Base Template mit Pastel CSS [2]

### Phase 2: Task Management (Week 3-4)
- [x] Task CRUD Operations (Create, Read, Update, Delete) [3]
- [x] Task List View mit Today View (Max 7 Items) [1]
- [x] Status Filter (All, Not Started, In Progress, Done) [2]
- [x] Priority Badge System (Urgent, Important, Normal) [2]
- [x] Subtask Decomposition UI [1]
- [x] Progress Bar Component [1]

### Phase 3: ADHD-Specific Features (Week 5-6)
- [x] Focus Mode (One Primary Action) [1]
- [x] Countdown Timer per Task [1]
- [x] Task Chunking UI (Time-Blocks) [1]
- [x] Context-based Reminders Placeholder [1]
- [x] Positive Feedback Animation + Completion Chime [1]
- [x] Forgiving Streak System (No Guilt) [1]

### Phase 4: Import/Export & Backup (Week 7)
- [x] Markdown File Upload & Bulk Task Import [2]
- [x] JSON Export (Backup) [2]
- [x] JSON Import (Restore) [2]
- [x] Clear Completed Tasks (Undoable) [2]

### Phase 5: Settings & Personalization (Week 8)
- [ ] Theme Toggle (Light/Dark/Auto) [2]
- [ ] Dyslexia-Friendly Font Toggle [2]
- [ ] Notification Frequency Settings [1]
- [ ] Browser Reminders (Web Push API Placeholder) [2]

### Phase 6: Admin Dashboard (Placeholder - Future) [3]
- [ ] Admin Route Placeholder [3]
- [ ] User Management UI (Future) [3]
- [ ] Analytics Dashboard (Future) [3]
- [ ] Role-based Access Control (Admin, User, Viewer, Coach) [3]

### Phase 7: Polish & Testing (Week 9-10)
- [ ] Responsive Design Testing [2]
- [ ] Reduce Motion Respekt [1]
- [ ] Accessibility Audit (WCAG) [1]
- [ ] Performance Optimization [3]
- [ ] Documentation & Deployment Guide [3]

---

## 7. API Placeholder (Future Integration)

```python
# app/api/v1/
# Separater, versionierter Blueprint für stabile Integrationen
# - /api/v1/tasks (JSON CRUD)
# - /api/v1/users (Admin)
# - /api/v1/analytics (Admin Dashboard)
```

Web-Routes und API-Routes verwenden dieselbe Service-Schicht, damit Geschäftslogik nicht dupliziert wird. Öffentliche Schnittstellen müssen versioniert, validiert, autorisiert und durch Vertragstests abgesichert sein.

---

## 8. Sicherheit & Best Practices

- **Password Hashing**: werkzeug.security.generate_password_hash [3]
- **Session Security**: HttpOnly, SameSite=Lax Cookies [3]
- **CSRF Protection**: Flask-WTF Token [3]
- **Input Validation**: Form-/Schema-Validierung an jeder Systemgrenze; SQLAlchemy schützt Datenbankabfragen zusätzlich durch parametrisierte Queries [3]
- **Role-Based Access**: Flask-Login @login_required + Role Check [3]
- **Best Practices (verpflichtend)**: PEP 8, Type Hints für öffentliche Funktionen, kleine Module, klare Verantwortlichkeiten und keine Geschäftslogik in Routes oder Templates
- **Dependency Management**: Versionen reproduzierbar festhalten, Updates prüfen und bekannte Schwachstellen vermeiden
- **Tests**: Jedes Feature erhält isolierte Unit-Tests und Integrationstests mit einer eigenen Test-App und temporärer Datenbank
- **Migrationen**: Schemaänderungen ausschließlich nachvollziehbar über Flask-Migrate/Alembic; keine manuellen Produktionsänderungen
- **Observability**: Strukturiertes Logging und zentrale Fehlerbehandlung ohne Secrets oder personenbezogene Daten in Logs
- **Feature Contract**: Jedes neue Feature dokumentiert Blueprint, Konfiguration, Berechtigungen, Datenmodell und öffentliche Service-Schnittstellen

---

## 9. Zukünftige Erweiterungen

Alle Erweiterungen werden als deaktivierbare Feature-Packages umgesetzt und über die Application Factory registriert. Sie dürfen bestehende Features nur über dokumentierte Schnittstellen verwenden und müssen unabhängig testbar bleiben.

- **Multi-User Collaboration**: Shared Tasks, Coach-User Mapping [3]
- **Push Notifications**: WebSockets/Celery Background Tasks [3]
- **AI Task Summarization**: LLM Integration for Auto-Subtasking [3]
- **Calendar Integration**: Google/Outlook Sync [3]
- **Mobile App**: React Native Wrapper [3]

---

## 10. Referenzen

[1] ADHD.md – Wissenschaftliche Grundlagen für ADHS-UX/UI  
[2] index.html –现有 HTML Mockup Features  
[3] Codex Prompt.md – Flask App Architektur

---

*Diese Design-Dokument dient als BluePrint für die Entwicklung der Flask-App. Alle ADHS-UX-Richtlinien sind evidenzbasiert aus peer-reviewed Meta-Analysen und UX-Research für neurodivergente Nutzer.*