Data Persistence

Relevant source files

The following files were used as context for generating this wiki page:

• src/App.tsx
• src/components/Pomodoro.tsx
• src/components/TaskManager.tsx
• src/constants.ts
• README.md

Data persistence is a core feature of the Endfield-Pomodoro application, ensuring that user settings, session progress, and task lists are preserved between browser sessions. This is achieved by leveraging the browser's localStorage API to store key application state.

The system is designed to automatically save changes as they happen and restore the state when the application is reloaded. This provides a seamless experience, allowing users to close their browser and later return to their Pomodoro session, tasks, and personalized configuration exactly as they left them. The main persisted data includes Pomodoro timer status, user-defined settings, task lists, and cumulative statistics like completed sessions and total focus time.

Sources: README.md, src/App.tsx, src/components/Pomodoro.tsx, src/components/TaskManager.tsx

Core Mechanism: localStorage

The application exclusively uses the browser's localStorage to store data. All data is stored as JSON strings under specific keys. A central constants.ts file defines all storage keys to ensure consistency and prevent naming conflicts.

Sources: src/constants.ts:7-19

Storage Keys

The following table details the keys used for storing data in localStorage.

Key	Description	Managed In
origin_terminal_settings	Stores the user's application settings, including timer durations, theme, language, and audio preferences.	src/App.tsx
origin_terminal_sessions	Stores the number of completed Pomodoro work cycles.	src/App.tsx
origin_terminal_total_seconds	Stores the cumulative total of focused work time in seconds, aggregated from completed sessions.	src/App.tsx
origin_terminal_current_session_start	Stores the timestamp (in milliseconds) of when the current work session started. Used to calculate elapsed time after a page refresh.	src/App.tsx
origin_terminal_timer	Stores the real-time state of the Pomodoro timer, including the current mode, time left, and whether it's active. This allows the timer to be restored accurately.	src/components/Pomodoro.tsx
origin_terminal_tasks	Stores the user's list of tasks.	src/components/TaskManager.tsx
origin_terminal_audio_source	Stores the selected audio source mode (e.g., 'local' or 'online').	src/components/AudioPlayer.tsx

Sources: src/constants.ts:7-19

Persisted Data Modules

Application Settings

User settings are managed within the main App component. They are loaded on initial application start and saved automatically whenever a setting is changed.

Sources: src/App.tsx:66-83, 210-216

Loading and Saving Flow

On application load, the settings state is initialized by reading from localStorage. If no saved settings are found, DEFAULT_SETTINGS are used. Any subsequent change to the settings object triggers a useEffect hook that serializes the state to JSON and saves it back to localStorage.

The diagram below illustrates the settings persistence lifecycle.

Settings Data Structure

The Settings object contains all user-configurable options.

Field	Type	Description	Default Value
workDuration	number	Duration of a work cycle in minutes.	25
shortBreakDuration	number	Duration of a short break in minutes.	5
longBreakDuration	number	Duration of a long break in minutes.	15
autoStartBreaks	boolean	Automatically start breaks after a work cycle.	true
autoStartWork	boolean	Automatically start work after a break.	true
soundEnabled	boolean	Enable/disable audio feedback.	true
notificationsEnabled	boolean	Enable/disable desktop notifications.	false
language	Language	The selected UI language ('EN' or 'CN').	Browser-dependent
theme	ThemePreset	The selected UI theme.	INDUSTRIAL
musicConfig	MusicConfig	Configuration for the online music player.	defaultMusicConfig

Sources: src/App.tsx:25-39, src/types.ts

Pomodoro Timer State

The state of the Pomodoro timer is persisted to allow users to refresh the page without losing their place in a cycle. This is managed by the Pomodoro component.

Sources: src/components/Pomodoro.tsx:112-129, 52-95

Timer State Restoration

On component mount, Pomodoro.tsx attempts to load the timer state from localStorage. If the timer was active when the page was last closed, it calculates the time elapsed since then and adjusts the timeLeft accordingly. This ensures the timer continues accurately.

The following sequence diagram shows the restoration process.

TimerPayload Data Structure

The TimerPayload is saved to localStorage whenever the timer's state changes.

Field	Type	Description
mode	TimerMode	The current timer mode (WORK, SHORT_BREAK, LONG_BREAK).
timeLeft	number	The remaining time in seconds.
isActive	boolean	true if the timer is currently running.
startTs	number (optional)	The Date.now() timestamp when the timer was started or resumed. Only present if isActive is true.

Sources: src/components/Pomodoro.tsx:23-28, 112-129

Task Manager Data

The TaskManager component persists the user's list of tasks.

Sources: src/components/TaskManager.tsx:18-31

Loading and Saving Flow

Similar to settings, tasks are loaded from localStorage during the component's initial state setup. A useEffect hook is responsible for writing the entire task list back to localStorage whenever the tasks array is modified (e.g., a task is added, completed, or deleted).

Session & Study Statistics

The application tracks the number of completed sessions and the total study time, persisting these metrics in localStorage. This logic is handled in the main App component.

• Session Count: The sessionCount is loaded from origin_terminal_sessions on startup. When a work cycle completes, the count is incremented and saved back.
• Total Study Time: This is calculated from two sources: persistedTotalSeconds (from origin_terminal_total_seconds) and the elapsed time of the current work session. When a work session completes, its duration is added to persistedTotalSeconds and saved. The origin_terminal_current_session_start key is used to track the current session's progress across page reloads.

Sources: src/App.tsx:85-88, 93-97, 608-624

The flow for updating total study time is as follows: