/ChuwuYo/Endfield-Pomodoro

Wiki directory

Browse AI-generated documentation for any repository.

Project Structure

Relevant source files

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

This document outlines the architecture and organization of the Endfield-Pomodoro project. The application is a modern web app built with React 19, Vite, and TypeScript, featuring a component-based architecture with a strong separation of concerns. The structure is designed to be modular and extensible, particularly for UI themes and internationalization.

The project follows a standard Vite project layout, with all source code located in the src/ directory, public assets in public/, and configuration files at the root level. Key architectural principles include centralized state management in the root App component, modular business logic components, a dynamic theming system using CSS Variables, and comprehensive internationalization support.

1. Directory Layout

The project's directory structure is organized to separate different aspects of the application, such as components, configuration, hooks, and utilities.

This diagram shows the high-level directory structure of the project.

Generating architecture diagram...

Sources: README.md:104-149

Key Directories

Path	Description
`public/`	Contains static assets that are served directly, such as favicons and PWA icons.
`src/`	The main application source code directory.
`src/assets/`	Stores static assets like images that are processed by Vite during the build.
`src/components/`	Contains all React components, organized into business logic (`Pomodoro.tsx`), UI primitives (`ui/`), and theme effects (`themes/`).
`src/config/`	Centralized configuration files for themes (`themes.ts`) and the music player (`musicConfig.ts`).
`src/hooks/`	Custom React hooks for reusable logic, such as device detection (`useIsMobile.ts`) and player logic.
`src/utils/`	Utility functions, notably the internationalization (i18n) setup in `i18n.ts`.

Sources: README.md:104-149

2. Build and Configuration

The project uses Vite for building and development, with configurations defined in vite.config.ts. TypeScript settings are managed via tsconfig.json and tsconfig.app.json.

2.1. Scripts and Dependencies

The package.json file defines the core scripts for development, building, and linting, along with the project's dependencies.

Script	Description
`dev`	Starts the Vite development server.
`build`	Compiles TypeScript and builds for production.
`lint`	Runs ESLint to analyze the code.
`preview`	Serves the production build locally.
Sources: package.json:6-11

Key Dependencies:

react: Core library for building the UI.
vite: Build tool and development server.
tailwindcss: Utility-first CSS framework for styling.
typescript: Language for static typing.
vite-plugin-pwa: Handles Progressive Web App (PWA) configuration and service worker generation.
babel-plugin-react-compiler: Enables the experimental React Compiler for automatic memoization.

Sources: package.json:13-39, vite.config.ts:11-14

2.2. Vite Configuration

vite.config.ts is central to the build process. It integrates several key plugins:

@vitejs/plugin-react: Enables React support, including the configuration for the React Compiler.
@tailwindcss/vite: Integrates Tailwind CSS v4 into the build pipeline.
vite-plugin-pwa: Configures the PWA manifest, service worker caching strategies, and offline support. The configuration specifies which assets to cache and defines network-only strategies for dynamic content like music streams.

// vite.config.ts
export default defineConfig({
  plugins: [
    react({
      babel: {
        plugins: ['babel-plugin-react-compiler'],
      },
    }),
    tailwindcss(),
    VitePWA({
      registerType: 'autoUpdate',
      // ... manifest and workbox config
    })
  ],
})

Sources: vite.config.ts:6-20

2.3. TypeScript Configuration

The project uses a multi-project setup for TypeScript, referenced in tsconfig.json. The main application configuration is in tsconfig.app.json, which sets the target to ES2022, enables strict mode, and configures JSX for React. It also enforces linting rules like noUnusedLocals and noUnusedParameters.

Sources: tsconfig.json:3-6, tsconfig.app.json:3-26

3. Application Architecture

The application is centered around the App.tsx component, which acts as the root controller. It manages global state, view routing, and passes data down to its children.

3.1. Component Hierarchy

The App component orchestrates the main layout and conditionally renders either the DASHBOARD view or the SETTINGS view. The dashboard itself is composed of the primary feature components.

This diagram shows the main component structure.

Generating architecture diagram...

Sources: src/App.tsx:265-373

3.2. State Management and Data Flow

Global state, such as settings, sessionCount, and totalSeconds, is managed within the App.tsx component using React's useState hook. This state is persisted to localStorage to maintain user preferences and statistics across sessions.

The flow of data is primarily top-down. The App component passes settings and callbacks to child components like Pomodoro and TaskManager.

This sequence diagram illustrates how settings are loaded, updated, and passed to the Pomodoro component.

Generating architecture diagram...

Sources: src/App.tsx:61-82, src/App.tsx:198-204, src/components/Pomodoro.tsx:16-19

3.3. View Management

The application has two main views: DASHBOARD and SETTINGS. The current view is controlled by the currentView state variable in App.tsx. Clicking the header buttons updates this state, causing a conditional render of the appropriate content.

Generating architecture diagram...

Sources: src/App.tsx:55-57, src/App.tsx:290-309, src/App.tsx:375-381

4. Theming and Styling

The project features a dynamic theming system built on CSS Custom Properties (Variables) and Tailwind CSS v4's @theme directive.

4.1. CSS Variables

Base theme colors are defined as CSS variables in :root within src/index.css. These variables are then mapped to Tailwind's theme system.

/* src/index.css */
@theme {
  /* ... */
  --color-theme-base: var(--color-base);
  --color-theme-primary: var(--color-primary);
  /* ... */
}

:root {
  --color-base: #e5e5e5;
  --color-primary: #f97316;
  /* ... other default theme colors */
}

Sources: src/index.css:6-29

The active theme's colors are applied at runtime by the App.tsx component, which iterates over a theme configuration object and sets the CSS variables on the document.documentElement.

Sources: src/App.tsx:210-216

4.2. Modular Theme Effects

Theme-specific visual effects are encapsulated in separate components within src/components/themes/.

BackgroundEffects.tsx: Contains components for background visuals like grids, particles, or animations (e.g., OriginGrid, MatrixRain).
ForegroundEffects.tsx: Contains components for foreground visuals that often track the mouse, such as cursors or scanlines (e.g., TacticalForeground).
MikuDecorations.tsx: A special component that provides unique decorative elements specifically for the "MIKU" theme, demonstrating the system's extensibility.

These components are conditionally rendered by BackgroundLayer and ForegroundLayer in App.tsx based on the currently selected theme.

Sources: src/App.tsx:268-274, src/components/themes/BackgroundEffects.tsx, src/components/themes/ForegroundEffects.tsx, src/components/MikuDecorations.tsx

5. Internationalization (i18n)

The application supports multiple languages (English and Chinese) through a simple and effective i18n system defined in src/utils/i18n.ts.

All UI strings are stored in a translations object, keyed by language. A custom hook, useTranslation, provides a function t(key) that retrieves the correct string for the currently selected language. The language preference is stored in the main settings state.

// src/utils/i18n.ts
export const translations = {
  [Language.EN]: {
    APP_TITLE: 'Endfield Protocol',
    // ... other strings
  },
  [Language.CN]: {
    APP_TITLE: '末端协议-番茄钟',
    // ... other strings
  }
};

export const useTranslation = (lang: Language) => {
  return (key: keyof typeof translations['EN']) => {
    return translations[lang][key] || key;
  };
};

Sources: src/utils/i18n.ts:3-195

This hook is used throughout the application, for example in App.tsx to translate titles and button labels.

Sources: src/App.tsx:90, src/App.tsx:167

Project Structure

Relevant source files

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

1. Directory Layout

The project's directory structure is organized to separate different aspects of the application, such as components, configuration, hooks, and utilities.

This diagram shows the high-level directory structure of the project.

Generating architecture diagram...

Sources: README.md:104-149

Key Directories

Path	Description
`public/`	Contains static assets that are served directly, such as favicons and PWA icons.
`src/`	The main application source code directory.
`src/assets/`	Stores static assets like images that are processed by Vite during the build.
`src/components/`	Contains all React components, organized into business logic (`Pomodoro.tsx`), UI primitives (`ui/`), and theme effects (`themes/`).
`src/config/`	Centralized configuration files for themes (`themes.ts`) and the music player (`musicConfig.ts`).
`src/hooks/`	Custom React hooks for reusable logic, such as device detection (`useIsMobile.ts`) and player logic.
`src/utils/`	Utility functions, notably the internationalization (i18n) setup in `i18n.ts`.

Sources: README.md:104-149

2. Build and Configuration

The project uses Vite for building and development, with configurations defined in vite.config.ts. TypeScript settings are managed via tsconfig.json and tsconfig.app.json.

2.1. Scripts and Dependencies

The package.json file defines the core scripts for development, building, and linting, along with the project's dependencies.

Script	Description
`dev`	Starts the Vite development server.
`build`	Compiles TypeScript and builds for production.
`lint`	Runs ESLint to analyze the code.
`preview`	Serves the production build locally.
Sources: package.json:6-11

Key Dependencies:

react: Core library for building the UI.
vite: Build tool and development server.
tailwindcss: Utility-first CSS framework for styling.
typescript: Language for static typing.
vite-plugin-pwa: Handles Progressive Web App (PWA) configuration and service worker generation.
babel-plugin-react-compiler: Enables the experimental React Compiler for automatic memoization.

Sources: package.json:13-39, vite.config.ts:11-14

2.2. Vite Configuration

vite.config.ts is central to the build process. It integrates several key plugins:

@vitejs/plugin-react: Enables React support, including the configuration for the React Compiler.
@tailwindcss/vite: Integrates Tailwind CSS v4 into the build pipeline.
vite-plugin-pwa: Configures the PWA manifest, service worker caching strategies, and offline support. The configuration specifies which assets to cache and defines network-only strategies for dynamic content like music streams.

// vite.config.ts
export default defineConfig({
  plugins: [
    react({
      babel: {
        plugins: ['babel-plugin-react-compiler'],
      },
    }),
    tailwindcss(),
    VitePWA({
      registerType: 'autoUpdate',
      // ... manifest and workbox config
    })
  ],
})

Sources: vite.config.ts:6-20

2.3. TypeScript Configuration

Sources: tsconfig.json:3-6, tsconfig.app.json:3-26

3. Application Architecture

The application is centered around the App.tsx component, which acts as the root controller. It manages global state, view routing, and passes data down to its children.

3.1. Component Hierarchy

The App component orchestrates the main layout and conditionally renders either the DASHBOARD view or the SETTINGS view. The dashboard itself is composed of the primary feature components.

This diagram shows the main component structure.

Generating architecture diagram...

Sources: src/App.tsx:265-373

3.2. State Management and Data Flow

The flow of data is primarily top-down. The App component passes settings and callbacks to child components like Pomodoro and TaskManager.

This sequence diagram illustrates how settings are loaded, updated, and passed to the Pomodoro component.

Generating architecture diagram...

Sources: src/App.tsx:61-82, src/App.tsx:198-204, src/components/Pomodoro.tsx:16-19

3.3. View Management

Generating architecture diagram...

Sources: src/App.tsx:55-57, src/App.tsx:290-309, src/App.tsx:375-381

4. Theming and Styling

The project features a dynamic theming system built on CSS Custom Properties (Variables) and Tailwind CSS v4's @theme directive.

4.1. CSS Variables

Base theme colors are defined as CSS variables in :root within src/index.css. These variables are then mapped to Tailwind's theme system.

/* src/index.css */
@theme {
  /* ... */
  --color-theme-base: var(--color-base);
  --color-theme-primary: var(--color-primary);
  /* ... */
}

:root {
  --color-base: #e5e5e5;
  --color-primary: #f97316;
  /* ... other default theme colors */
}

Sources: src/index.css:6-29

The active theme's colors are applied at runtime by the App.tsx component, which iterates over a theme configuration object and sets the CSS variables on the document.documentElement.

Sources: src/App.tsx:210-216

4.2. Modular Theme Effects

Theme-specific visual effects are encapsulated in separate components within src/components/themes/.

BackgroundEffects.tsx: Contains components for background visuals like grids, particles, or animations (e.g., OriginGrid, MatrixRain).
ForegroundEffects.tsx: Contains components for foreground visuals that often track the mouse, such as cursors or scanlines (e.g., TacticalForeground).
MikuDecorations.tsx: A special component that provides unique decorative elements specifically for the "MIKU" theme, demonstrating the system's extensibility.

These components are conditionally rendered by BackgroundLayer and ForegroundLayer in App.tsx based on the currently selected theme.

Sources: src/App.tsx:268-274, src/components/themes/BackgroundEffects.tsx, src/components/themes/ForegroundEffects.tsx, src/components/MikuDecorations.tsx

5. Internationalization (i18n)

The application supports multiple languages (English and Chinese) through a simple and effective i18n system defined in src/utils/i18n.ts.

// src/utils/i18n.ts
export const translations = {
  [Language.EN]: {
    APP_TITLE: 'Endfield Protocol',
    // ... other strings
  },
  [Language.CN]: {
    APP_TITLE: '末端协议-番茄钟',
    // ... other strings
  }
};

export const useTranslation = (lang: Language) => {
  return (key: keyof typeof translations['EN']) => {
    return translations[lang][key] || key;
  };
};

Sources: src/utils/i18n.ts:3-195

This hook is used throughout the application, for example in App.tsx to translate titles and button labels.

Sources: src/App.tsx:90, src/App.tsx:167