Architecture Overview

Relevant source files

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

• src/App.tsx
• vite.config.ts
• src/components/TerminalUI.tsx
• src/utils/i18n.ts
• package.json
• src/index.css
• README.md

This document provides a technical overview of the Endfield-Pomodoro application's architecture. It is a single-page application (SPA) built with React 19, Vite, and TypeScript, designed as an immersive, cyber-themed Pomodoro timer. The architecture emphasizes a component-based structure, centralized state management, a dynamic theming system, and PWA capabilities for offline use.

The core of the application is the App.tsx component, which orchestrates state, views, and data persistence. The visual identity is driven by a sophisticated Theming System that leverages CSS Variables and modular effect components. The build process is optimized for performance using Vite and the React Compiler.

Project Setup and Tooling

The project is built upon a modern frontend stack, configured for high performance and developer efficiency. The build tool, dependencies, and compiler settings are central to its architecture.

Sources: vite.config.ts, package.json

Tech Stack

The primary technologies used in this project are defined in package.json.

Technology	Version	Role
React	19.2.0	Core UI library.
Vite	7.2.4	Build tool and development server.
TypeScript	~5.9.3	Language for static typing.
TailwindCSS	4.1.17	Utility-first CSS framework for styling.
React Compiler	1.0.0	Babel plugin for automatic memoization.
VitePWA	1.2.0	Plugin for Progressive Web App features.

Sources: package.json:11-20, 24-32

Build Process

The application uses Vite for its build process. The configuration in vite.config.ts specifies the use of several key plugins that define the compilation and bundling pipeline. The React Compiler is enabled via a Babel plugin to automatically optimize components, eliminating the need for manual useMemo or useCallback in most cases.

The diagram below illustrates the build pipeline.

This diagram shows how Vite processes the source code, applying React, TailwindCSS, and PWA plugins to generate the optimized production build.

Sources: vite.config.ts:6-12

Application Structure

The application follows a standard component-based architecture. The main entry point is src/main.tsx, which renders the root App component into the DOM.

Component Hierarchy

The App component serves as the orchestrator, managing global state, view switching (Dashboard vs. Settings), and the overall layout, which includes a fixed header, a main content area, and a fixed footer.

This diagram shows the main component hierarchy, with App.tsx at the root controlling layout, UI layers, and conditionally rendering either the Dashboard or Settings view.

Sources: src/App.tsx:280-701, README.md:83-122

Directory Structure

The project structure is organized to separate concerns, as detailed in the README.md.

Directory	Purpose
src/assets/	Static assets like images and fonts.
src/components/	Reusable React components. Contains subdirectories for UI primitives (ui/) and themes (themes/).
src/config/	Application-wide configuration, such as themes and default music settings.
src/hooks/	Custom React hooks for reusable logic.
src/utils/	Utility functions, including internationalization (i18n.ts).
src/	Root source files like App.tsx, main.tsx, and global styles.

Sources: README.md:83-122

State Management

State is managed locally within components using React Hooks (useState, useEffect, useRef). The App.tsx component acts as the primary state container for global settings and session data, passing state down to child components via props.

Global State in App.tsx

The App component initializes and manages the following key pieces of state:

• settings: An object containing all user-configurable options, such as timer durations, theme, and language. It is loaded from localStorage on startup.
• sessionCount: The number of completed Pomodoro sessions.
• totalSeconds: The total accumulated study time.
• currentView: Toggles between the 'DASHBOARD' and 'SETTINGS' views.

Sources: src/App.tsx:63-100

Data Persistence

User settings and progress are persisted in the browser's localStorage to ensure data is retained across sessions.

localStorage Key	Description	Managed In
origin_terminal_settings	Stores the user's Settings object.	src/App.tsx
origin_terminal_sessions	Stores the count of completed Pomodoro sessions.	src/App.tsx
origin_terminal_total_seconds	Stores the total focused time in seconds.	src/App.tsx
origin_terminal_tasks	Stores the list of tasks for the Task Manager.	src/components/TaskManager.tsx
origin_terminal_audio_source	Stores the selected audio mode ('local' or 'online').	src/components/AudioPlayer.tsx

Sources: src/App.tsx:18-19, 64, 84, 94, src/components/TaskManager.tsx:12, src/components/AudioPlayer.tsx:18

The flow of state updates and persistence is illustrated below.

This sequence shows how user actions in child components trigger state updates in App.tsx, which then persists the data and re-renders the UI.

Sources: src/App.tsx:190-196, 613-637

Theming System

The application features a dynamic theming system that allows users to change the visual appearance instantly. This system is built on CSS Variables, React state, and modular theme components.

Sources: src/App.tsx:201-207, src/components/TerminalUI.tsx, src/index.css:12-28

Mechanism

1. CSS Variables: A set of CSS variables for colors are defined in src/index.css and mapped to Tailwind's theme configuration. These variables (--color-primary, --color-base, etc.) are used throughout the application's styles.
2. Theme Configuration: The file src/config/themes.ts (not provided, but referenced) contains objects that map each theme preset (e.g., ThemePreset.INDUSTRIAL) to a specific set of color values for the CSS variables.
3. State-Driven Updates: The current theme is stored in the settings state within App.tsx. When the user selects a new theme, this state is updated.
4. Dynamic Application: A useLayoutEffect hook in App.tsx listens for changes to settings.theme. When it changes, the hook iterates over the new theme's color values and applies them directly to the :root element's style properties.

// src/App.tsx:201-207
useLayoutEffect(() => {
    const root = document.documentElement;
    const themeColors = THEMES[settings.theme];
    Object.entries(themeColors).forEach(([key, value]) => {
        root.style.setProperty(key, value as string);
    });
}, [settings.theme]);

Visual Effect Layers

To create immersive visual effects unique to each theme, the UI is structured into distinct layers managed by TerminalUI.tsx.

• BackgroundLayer (z-0): Renders static or animated background effects (e.g., grids, particles, digital rain). It uses a switch statement to select the correct effect component based on the current theme prop.
• ForegroundLayer (z-50): Renders interactive foreground effects that often respond to mouse movement (e.g., crosshairs, glows). It is disabled on mobile devices.
• MikuDecorations (z-5): A special component that adds unique decorative elements only when the MIKU theme is active.

Sources: src/components/TerminalUI.tsx, src/components/MikuDecorations.tsx:173-182, src/App.tsx:286-294

The following diagram shows the theme application flow.

Internationalization (i18n)

The application supports multiple languages (English and Chinese) through a simple and effective i18n system.

• Translations: All UI strings are stored in a translations object in src/utils/i18n.ts. This object is keyed by language codes (EN, CN).
• useTranslation Hook: A custom hook, useTranslation, takes the current language from the settings state and returns a translator function t.
• Usage: The t function is called with a translation key (e.g., t('DASHBOARD')) to retrieve the correct string for the active language. This enables instantaneous language switching without a page reload.

Sources: src/utils/i18n.ts, src/App.tsx:142, 353

PWA Configuration

The application is configured as a Progressive Web App (PWA) using the vite-plugin-pwa plugin, enabling offline functionality and a native-like app experience.

Sources: vite.config.ts:13-125

Service Worker and Caching

The PWA is configured to automatically update the service worker (registerType: 'autoUpdate'). The workbox configuration defines specific caching strategies for different types of resources to balance performance and freshness.

URL Pattern	Handler	Cache Name	Description
index.html	NetworkFirst	index-html	Ensures the user always gets the latest app shell, falling back to cache if offline.
/api/ & audio/video	NetworkOnly	-	All API calls and media streams are fetched directly from the network and not cached.
Google Fonts	CacheFirst	google-fonts-*	Caches fonts for up to a year to improve load times.
Other assets (js, css, etc.)	precache	-	Core application assets are precached during service worker installation.

Sources: vite.config.ts:51-124

This strategy ensures the app shell loads quickly from cache while dynamic content, like music streams, is always fetched live, preventing stale data issues.