319 lines
13 KiB
Markdown
319 lines
13 KiB
Markdown
# 📋 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)
|
||
- [ ] Markdown File Upload & Bulk Task Import [2]
|
||
- [ ] JSON Export (Backup) [2]
|
||
- [ ] JSON Import (Restore) [2]
|
||
- [ ] 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.*
|