patsy/flask_template_codex
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
flask_template_codex/design.md
patsy 87d087b913 final
2026-08-08 05:37:41 +02:00

14 KiB
Raw Permalink Blame History

📋 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

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

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

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)

: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)

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

Phase 2: Task Management (Week 3-4)

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

Phase 3: ADHD-Specific Features (Week 5-6)

  • Focus Mode (One Primary Action) [1]
  • Countdown Timer per Task [1]
  • Task Chunking UI (Time-Blocks) [1]
  • Context-based Reminders Placeholder [1]
  • Positive Feedback Animation + Completion Chime [1]
  • 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 (automated contracts; manual matrix documented) [2]
  • Reduce Motion Respekt [1]
  • Accessibility Audit (WCAG structural audit; no formal certification) [1]
  • Performance Optimization [3]
  • Documentation & Deployment Guide [3]

7. API Placeholder (Future Integration)

# 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.