Merge pull request #418 from timbornemann/codex/evaluate-and-migrate-store-structure

refactor: centralize state management with Zustand

Author: timbornemann

docs/frontend.md

@@ -13,9 +13,10 @@ The frontend lives in the `src` directory and is built with React 18, TypeScript
 - [`src/pages`](../src/pages) – route components; each page represents a top-level feature like tasks, notes or the pomodoro timer.
 - [`src/hooks`](../src/hooks) – custom React hooks for shared logic.
 - [`src/providers`](../src/providers) – context providers for state like themes or query clients.
+- [`src/stores`](../src/stores) – Zustand stores for global state.
 - [`src/locales`](../src/locales) – translation files in German and English consumed by `react-i18next`.
 - [`src/utils`](../src/utils) and [`src/lib`](../src/lib) – helper functions and abstractions.
-- [`src/shared`](../src/shared) – Zustand stores and shared types.
+- [`src/shared`](../src/shared) – shared utilities and types.
 
 ## Routing
 
@@ -25,9 +26,9 @@ defined in [`src/components/Navbar.tsx`](../src/components/Navbar.tsx).
 
 ## State Management
 
-Local state is handled with Zustand stores and React hooks. For example,
-[`useTimers`](../src/hooks/useTimers.tsx) persists timer state to local storage
-and syncs it to the server.
+Local state is handled with Zustand stores. For example,
+the [timers store](../src/stores/timers.ts) persists timer state to local storage
+and syncs it to the server via the [TimersProvider](../src/providers/TimersProvider.tsx).
 Server state and caching are provided by `@tanstack/react-query` via context
 providers in [`src/providers`](../src/providers).
 

docs/state-management.md

@@ -0,0 +1,11 @@
+# State Management
+
+This project evaluated different libraries for global state handling. Redux Toolkit offers powerful tooling but introduces boilerplate. Zustand provides a minimal API, shallow learning curve and works well with React's hooks.
+
+We standardize on **Zustand** for client-side state:
+
+- Stores live in [`src/stores`](../src/stores).
+- Context providers that persist or sync data reside in [`src/providers`](../src/providers).
+- Components and hooks import stores directly, e.g. `import { useTimers } from "@/stores/timers"`.
+
+Existing local stores were migrated into this structure. New global state should follow the same pattern.

src/components/Dashboard.tsx

@@ -53,7 +53,7 @@ import {
 } from "@dnd-kit/sortable";
 import { CSS } from "@dnd-kit/utilities";
 import Navbar from "./Navbar";
-import { usePomodoroStore } from "./PomodoroTimer";
+import { usePomodoroStore } from "@/stores/pomodoro";
 
 interface SortableCategoryProps {
   category: Category;

src/components/PomodoroTicker.tsx

@@ -1,5 +1,5 @@
 import { useEffect, useRef } from "react";
-import { usePomodoroStore } from "./PomodoroTimer";
+import { usePomodoroStore } from "@/stores/pomodoro";
 import { usePomodoroHistory } from "@/hooks/usePomodoroHistory.tsx";
 
 const PomodoroTicker = () => {

src/components/PomodoroTimer.tsx

@@ -2,8 +2,7 @@ import React, { useEffect, useRef, useState } from "react";
 import { useTranslation } from "react-i18next";
 import ReactDOM from "react-dom/client";
 import { Button } from "@/components/ui/button";
-import { create } from "zustand";
-import { persist } from "zustand/middleware";
+import { usePomodoroStore } from "@/stores/pomodoro";
 import { useSettings, SettingsProvider } from "@/hooks/useSettings";
 import { hslToHex, hexToHsl, complementaryColor } from "@/utils/color";
 import { playSound } from "@/utils/sounds";
@@ -12,118 +11,6 @@ import {
   PomodoroHistoryProvider,
 } from "@/hooks/usePomodoroHistory.tsx";
 
-interface PomodoroState {
-  isRunning: boolean;
-  isPaused: boolean;
-  remainingTime: number;
-  mode: "work" | "break";
-  currentTaskId?: string;
-  workDuration: number;
-  breakDuration: number;
-  startTime?: number;
-  lastTick?: number;
-  pauseStart?: number;
-  start: (taskId?: string) => void;
-  pause: () => void;
-  resume: () => void;
-  reset: () => void;
-  startBreak: () => void;
-  skipBreak: () => void;
-  tick: () => void;
-  setStartTime: (time?: number) => void;
-  setLastTick: (time: number) => void;
-  setDurations: (work: number, brk: number) => void;
-}
-
-const WORK_DURATION = 25 * 60; // 25 Minuten
-const BREAK_DURATION = 5 * 60; // 5 Minuten
-
-export const usePomodoroStore = create<PomodoroState>()(
-  persist(
-    (set) => ({
-      isRunning: false,
-      isPaused: false,
-      pauseStart: undefined,
-      remainingTime: WORK_DURATION,
-      mode: "work",
-      currentTaskId: undefined,
-      workDuration: WORK_DURATION,
-      breakDuration: BREAK_DURATION,
-      startTime: undefined,
-      lastTick: undefined,
-      start: (taskId?: string) =>
-        set((state) => ({
-          isRunning: true,
-          isPaused: false,
-          pauseStart: undefined,
-          remainingTime: state.workDuration,
-          mode: "work",
-          currentTaskId: taskId,
-          startTime: Date.now(),
-          lastTick: Date.now(),
-        })),
-      pause: () => set({ isPaused: true, pauseStart: Date.now() }),
-      resume: () =>
-        set({ isPaused: false, lastTick: Date.now(), pauseStart: undefined }),
-      reset: () =>
-        set((state) => ({
-          isRunning: false,
-          isPaused: false,
-          remainingTime: state.workDuration,
-          mode: "work",
-          currentTaskId: undefined,
-          startTime: undefined,
-          lastTick: undefined,
-          pauseStart: undefined,
-        })),
-      startBreak: () =>
-        set((state) => ({
-          isRunning: true,
-          isPaused: false,
-          pauseStart: undefined,
-          mode: "break",
-          remainingTime: state.breakDuration,
-          lastTick: Date.now(),
-        })),
-      skipBreak: () =>
-        set((state) => ({
-          isRunning: true,
-          isPaused: false,
-          pauseStart: undefined,
-          mode: "work",
-          remainingTime: state.workDuration,
-          lastTick: Date.now(),
-        })),
-      tick: () =>
-        set((state) => {
-          if (!state.isRunning || state.isPaused) return state;
-          if (state.remainingTime > 0) {
-            return {
-              remainingTime: state.remainingTime - 1,
-              lastTick: Date.now(),
-            };
-          }
-          const nextMode = state.mode === "work" ? "break" : "work";
-          return {
-            mode: nextMode,
-            remainingTime:
-              nextMode === "work" ? state.workDuration : state.breakDuration,
-            lastTick: Date.now(),
-          } as PomodoroState;
-        }),
-      setStartTime: (time) => set({ startTime: time }),
-      setLastTick: (time) => set({ lastTick: time }),
-      setDurations: (work, brk) =>
-        set((state) => ({
-          workDuration: work,
-          breakDuration: brk,
-          remainingTime: !state.isRunning ? work : state.remainingTime,
-        })),
-    }),
-    { name: "pomodoro" },
-  ),
-);
-
 const formatTime = (sec: number) => {
   const m = Math.floor(sec / 60)
     .toString()

src/components/TimerCard.tsx

@@ -10,7 +10,7 @@ import {
   Settings,
 } from "lucide-react";
 import TimerCircle from "./TimerCircle";
-import { useTimers } from "@/hooks/useTimers.tsx";
+import { useTimers } from "@/stores/timers";
 import { useSettings } from "@/hooks/useSettings";
 import { isColorDark, complementarySameHue, adjustColor } from "@/utils/color";
 import { Button } from "@/components/ui/button";

src/components/TimerTicker.tsx

@@ -1,5 +1,5 @@
 import { useEffect } from "react";
-import { useTimers } from "@/hooks/useTimers.tsx";
+import { useTimers } from "@/stores/timers";
 
 const TimerTicker = () => {
   const tick = useTimers((state) => state.tick);

src/pages/Kanban.tsx

@@ -4,7 +4,7 @@ import TaskCard from "@/components/TaskCard";
 import Navbar from "@/components/Navbar";
 import TaskModal from "@/components/TaskModal";
 import { useNavigate } from "react-router-dom";
-import { usePomodoroStore } from "@/components/PomodoroTimer";
+import { usePomodoroStore } from "@/stores/pomodoro";
 import { useToast } from "@/hooks/use-toast";
 import { Task, TaskFormData } from "@/types";
 import { flattenTasks, FlattenedTask } from "@/utils/taskUtils";

src/pages/TimerDetail.tsx

@@ -4,7 +4,7 @@ import { useTranslation } from "react-i18next";
 import Navbar from "@/components/Navbar";
 import TimerCircle from "@/components/TimerCircle";
 import { Button } from "@/components/ui/button";
-import { useTimers } from "@/hooks/useTimers.tsx";
+import { useTimers } from "@/stores/timers";
 import { Play, Pause, RotateCcw, Plus, Edit } from "lucide-react";
 import { useSettings } from "@/hooks/useSettings";
 import { isColorDark, complementaryColor } from "@/utils/color";

src/pages/Timers.tsx

@@ -3,7 +3,7 @@ import Navbar from "@/components/Navbar";
 import TimerCard from "@/components/TimerCard";
 import TimerModal from "@/components/TimerModal";
 import { Button } from "@/components/ui/button";
-import { useTimers } from "@/hooks/useTimers.tsx";
+import { useTimers } from "@/stores/timers";
 import { useTranslation } from "react-i18next";
 import {
   DndContext,