Skip to content

CLAUDE.md

Latest commit

 

History

History
222 lines (191 loc) · 9.48 KB

CLAUDE.md

File metadata and controls

222 lines (191 loc) · 9.48 KB

DevHabit - Projektrichtlinien

Projektbeschreibung

DevHabit ist ein lokaler Habit-Tracker für Softwareentwickler. Er hilft beim Aufbau konsistenter Engineering-Gewohnheiten durch Habit-Tracking, Streak-Berechnung, Fokuszeit-Messung und Git-Commit-Analyse. Die Anwendung läuft vollständig lokal ohne externe Infrastruktur oder Authentifizierung.

Tech-Stack

Backend

  • Framework: Spring Boot 3, Java 21
  • Build: Maven (./mvnw)
  • Web: Spring Web (REST API)
  • Persistence: Spring Data JPA, H2 (embedded)
  • Test: JUnit 5, Mockito, AssertJ, Spring Boot Test, ArchUnit

Frontend

  • Framework: React 18 mit TypeScript
  • Build: Vite
  • State/Data: React Query (TanStack Query)
  • Styling: TailwindCSS
  • Test: Vitest, React Testing Library
  • Paketmanager: npm

Projektstruktur

devhabits/
├── backend/                          # Spring Boot Anwendung
│   └── src/
│       ├── main/java/de/devhabits/
│       │   ├── DevHabitApplication.java
│       │   ├── habit/                # Feature-Modul: Habits
│       │   │   ├── domain/           # Entities, Value Objects, Domain Services
│       │   │   ├── application/      # Use Cases / Application Services
│       │   │   ├── adapter/
│       │   │   │   ├── in/web/       # REST Controller (Driving Adapter)
│       │   │   │   └── out/persistence/  # JPA Repository (Driven Adapter)
│       │   │   └── port/
│       │   │       ├── in/           # Input Ports (Use Case Interfaces)
│       │   │       └── out/          # Output Ports (Repository Interfaces)
│       │   ├── focus/                # Feature-Modul: Focus Sessions
│       │   │   ├── domain/
│       │   │   ├── application/
│       │   │   ├── adapter/
│       │   │   │   ├── in/web/
│       │   │   │   └── out/persistence/
│       │   │   └── port/
│       │   │       ├── in/
│       │   │       └── out/
│       │   ├── git/                  # Feature-Modul: Git Tracking
│       │   │   ├── domain/
│       │   │   ├── application/
│       │   │   ├── adapter/
│       │   │   │   ├── in/web/
│       │   │   │   └── out/git/      # Git CLI Adapter
│       │   │   └── port/
│       │   │       ├── in/
│       │   │       └── out/
│       │   └── stats/                # Feature-Modul: Statistiken
│       │       ├── domain/
│       │       ├── application/
│       │       ├── adapter/
│       │       │   └── in/web/
│       │       └── port/
│       │           └── in/
│       └── test/java/de/devhabits/  # Tests spiegeln src-Struktur
├── frontend/                         # React Anwendung
│   └── src/
│       ├── main.tsx
│       ├── App.tsx
│       ├── features/
│       │   ├── habits/               # Feature-Modul: Habits
│       │   │   ├── domain/           # Typen, Interfaces, Business-Logik
│       │   │   ├── application/      # Custom Hooks (Use Cases)
│       │   │   ├── infrastructure/   # API-Client, Adapter
│       │   │   └── ui/               # React-Komponenten
│       │   ├── focus/                # Feature-Modul: Focus Sessions
│       │   │   ├── domain/
│       │   │   ├── application/
│       │   │   ├── infrastructure/
│       │   │   └── ui/
│       │   ├── git/                  # Feature-Modul: Git Tracking
│       │   │   ├── domain/
│       │   │   ├── application/
│       │   │   ├── infrastructure/
│       │   │   └── ui/
│       │   └── stats/                # Feature-Modul: Statistiken
│       │       ├── domain/
│       │       ├── application/
│       │       ├── infrastructure/
│       │       └── ui/
│       └── shared/                   # Geteilte Komponenten, Utilities
│           ├── ui/
│           └── api/
└── PRD.md

Architektur: Hexagonal / Clean Architecture

Backend (Spring Boot)

Jedes Feature-Modul folgt der Hexagonal Architecture:

  • domain/: Entities, Value Objects, Domain Services. Keine Framework-Abhängigkeiten.
  • port/in/: Input Ports - Interfaces für Use Cases (z.B. CreateHabitUseCase).
  • port/out/: Output Ports - Interfaces für externe Systeme (z.B. HabitRepository).
  • application/: Implementierung der Input Ports. Orchestriert Domain-Logik und Output Ports.
  • adapter/in/web/: REST Controller. Ruft Input Ports auf, übersetzt HTTP zu/von DTOs.
  • adapter/out/persistence/: JPA-Implementierung der Output Ports.

Regeln:

  • Domain-Schicht hat KEINE Abhängigkeiten zu anderen Schichten oder Frameworks.
  • Application-Schicht kennt nur Domain und Ports, nicht Adapter.
  • Adapter hängen von Ports ab, nie umgekehrt.
  • Controller verwenden DTOs, nie Domain-Entities direkt.

Frontend (React)

Jedes Feature-Modul folgt derselben Schichtentrennung:

  • domain/: TypeScript-Interfaces, Typen, reine Business-Logik-Funktionen.
  • application/: Custom Hooks für Use Cases (z.B. useCreateHabit). Nutzt React Query.
  • infrastructure/: API-Client-Funktionen, Adapter zum Backend.
  • ui/: React-Komponenten. Nutzen nur Application-Hooks, nie Infrastructure direkt.

Regeln:

  • UI-Komponenten importieren nie aus infrastructure/.
  • Domain-Typen haben keine React- oder Framework-Abhängigkeiten.
  • API-Aufrufe nur in infrastructure/, nie in Komponenten.

Entwicklungsmethodik: Test-Driven Development (TDD)

Vorgehen

  1. Red: Test schreiben, der fehlschlägt.
  2. Green: Minimalen Code schreiben, damit der Test besteht.
  3. Refactor: Code verbessern, Tests müssen weiterhin bestehen.

Backend-Tests

  • Unit Tests (domain/, application/): JUnit 5 + Mockito + AssertJ. Keine Spring-Kontextabhängigkeit.
  • Integration Tests (adapter/): @SpringBootTest oder @DataJpaTest für Persistence, @WebMvcTest für Controller.
  • Architektur-Tests: ArchUnit zur Validierung der Hexagonal-Schichtregeln.

Frontend-Tests

  • Unit Tests (domain/): Vitest für reine Funktionen.
  • Hook Tests (application/): Vitest + React Testing Library renderHook.
  • Komponenten-Tests (ui/): Vitest + React Testing Library.

Testbefehle

# Backend Tests
cd backend && ./mvnw test

# Frontend Tests
cd frontend && npm test

REST API

Methode Pfad Beschreibung
GET /api/habits Alle Habits abrufen
POST /api/habits Habit erstellen
PUT /api/habits/{id} Habit aktualisieren
DELETE /api/habits/{id} Habit löschen
POST /api/habits/{id}/complete Habit als erledigt markieren
POST /api/focus/start Fokus-Session starten
POST /api/focus/stop Fokus-Session stoppen
GET /api/stats/weekly Wochenstatistiken
GET /api/git/activity Git-Aktivität abrufen

Datenmodell

  • Habit: id, name, description, frequency (DAILY/WEEKLY), startDate
  • HabitCompletion: id, habitId, date, completed
  • FocusSession: id, startTime, endTime, duration, habitId (optional)
  • RepositoryConfig: id, path, enabled
  • CommitActivity: id, date, count
  • LearningTopic: id, name, description, progress, notes

Implementierungsplan

Der detaillierte Implementierungsplan mit Checkboxen zum Abhaken befindet sich in Implementationplan.md.

Vorgehen

  • Implementierung erfolgt phasenweise gemaess dem Plan
  • Jeder abgeschlossene Schritt wird in Implementationplan.md abgehakt (- [x])
  • Vor Beginn einer neuen Phase wird der aktuelle Stand im Plan geprueft
  • Innerhalb jeder Phase wird TDD angewendet (Red-Green-Refactor)
  • Nach Abschluss einer Phase: Tests ausfuehren, Commit erstellen

Phasen-Uebersicht

  1. Project Setup (Backend + Frontend Grundgeruest + ArchUnit)
  2. Habit CRUD (Domain, Ports, Adapter, Tests, Frontend)
  3. Habit Completion (Abhaken-Logik, Kalender)
  4. Streak Calculation (currentStreak, longestStreak)
  5. Focus Sessions (Start/Stop, Dauer, Timer)
  6. Git Commit Tracking (lokales Repo lesen, Aktivitaet)
  7. Stats API & Dashboard (Wochenstatistiken, Routing)
  8. Heatmap Visualization (Bonus)

Konventionen

Code-Style

  • Backend: Standard Java-Konventionen, keine Lombok-Nutzung
  • Frontend: ESLint + Prettier, funktionale Komponenten, Named Exports
  • Sprache im Code: Englisch (Variablen, Klassen, Kommentare)

Git

  • Commit-Messages auf Englisch, konventionelle Commits: feat:, fix:, test:, refactor:, docs:, chore:
  • Ein Commit pro logische Änderung

Starten der Anwendung

# Backend
cd backend && ./mvnw spring-boot:run

# Frontend
cd frontend && npm run dev

Definition of Done

Ein Feature ist fertig, wenn:

  • Backend API implementiert und getestet (Unit + Integration)
  • Frontend UI implementiert und getestet
  • Integration zwischen Frontend und Backend funktioniert
  • Daten werden korrekt persistiert
  • Architektur-Regeln (Hexagonal) werden eingehalten (ArchUnit)