# zzwtsy/wakatime-dashboard architecture

> Architecture diagram of the GitHub repository zzwtsy/wakatime-dashboard, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/zzwtsy/wakatime-dashboard
- Repository: https://github.com/zzwtsy/wakatime-dashboard

## Overview

##### Main Components
- Entry Point & Bootstrapping:
- index.html serves as the basic HTML shell.
- src/main.tsx is the starting point where React is bootstrapped, and the root of the component tree is rendered.
- Application Component:
- src/App.tsx is the central container wrapping overall functionality, which may include routing or state management.
- UI Components:
- Dashboard (src/components/Dashboard.tsx) which likely serves as the main view for displaying visualized data.
- ThemeProvider and ThemeToggle (src/components/ThemeProvider.tsx & src/components/ThemeToggle.tsx) managing and enabling theme switching.
- Chart components (Chart.tsx, DoughnutChart.tsx, StackedHorizontalBar.tsx under src/components/charts) that encapsulate different visualization types.
- Data and API Layer:
- src/api directory (with index.ts) manages API calls or data fetching logic related to Wakatime statistics.
- Domain Models and Types:
- src/entity contains “models” like GistRawUrl, StackedHorizontalBarData, and Wakatime representing the core data structures.
- src/enum and src/types provide typed constants and interfaces that support data consistency across the app.
- Assets:
- src/assets contains theming details for charts (JSON files for ECharts themes) and other static assets.
- Utilities:
- src/utils.ts and src/localStorage.ts support miscellaneous functions (including persisting theme preference or other state).

##### Out the Relationships and Data Flow
- The web page (index.html) loads the bundled JavaScript which is produced using Vite (notable from vite.config.ts, tsconfig related files).
- main.tsx initializes the React app by rendering App.tsx.
- App.tsx composes the page by including the Dashboard component as well as wrapping the content with ThemeProvider so that components down the tree can access theme state.
- Data is fetched from external sources using the API module (src/api/index.ts), which processes and transforms the data into model objects defined in src/entity.
- The visual representations in the charts use the style themes provided in src/assets/echarts (for light and dark modes).
- LocalStorage utilities help maintain state between sessions (like a chosen theme) and possibly cache data.

##### Architectural Patterns and Design Principles
- Component-Based Architecture: The project leverages React’s composable component system.
- Separation of Concerns: There’s a clear split between UI (in components), data access (in api), and domain data representation (in entity and types).
- Theming/Configuration Management: Dedicated components (ThemeProvider and ThemeToggle) encapsulate global UI state (theme) and configuration.
- Declarative Data Flow: Data flows from the API layer through model transformation into UI components for rendering interactive charts.

##### Detail Specific Technologies and Tools
- That the application uses:
- React for component-based UI,
- TypeScript for type safety,
- Vite as the build tool,
- ECharts (through assets JSON themes) for data visualization.
- External integration such as “wakatime-action-sync” for data feeding.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Data and Data Layer
    External["Wakatime Data"]:::external
    ApiLayer["API Layer"]:::business
    DomainModels["Domain Models"]:::business
    External -->|"fetch"| ApiLayer
    ApiLayer -->|"process"| DomainModels

    %% Entry & Bootstrapping Subgraph
    subgraph "Entry & Bootstrapping"
        EntryHTML["index.html"]:::ui
        MainTSX["main.tsx"]:::ui
        EntryHTML -->|"loads"| MainTSX
    end

    %% Application Container
    App["App Container"]:::ui
    MainTSX -->|"bootstraps"| App

    %% UI Layer and Dashboard
    Dashboard["Dashboard"]:::ui
    App -->|"renders"| Dashboard
    DomainModels -->|"provides data"| Dashboard

    %% Chart Components Subgraph
    subgraph "Chart Components"
        Chart["Base Chart"]:::ui
        Doughnut["Doughnut Chart"]:::ui
        Stacked["Stacked Horizontal Bar Chart"]:::ui
        Dashboard -->|"displays"| Chart
        Dashboard -->|"displays"| Doughnut
        Dashboard -->|"displays"| Stacked
    end

    %% Assets utilized by Chart Components
    Assets["Assets (ECharts Themes)"]:::util
    Assets -->|"styles"| Doughnut
    Assets -->|"styles"| Stacked

    %% Theme Management Subgraph
    subgraph "Theme Management"
        ThemeProvider["ThemeProvider"]:::ui
        ThemeToggle["ThemeToggle"]:::ui
        App -->|"applies"| ThemeProvider
        ThemeToggle -->|"toggles"| ThemeProvider
        ThemeProvider -->|"themes"| Dashboard
    end

    %% Icon Component
    GithubIcon["Github Icon"]:::ui
    Dashboard -->|"includes"| GithubIcon

    %% Utilities
    Utils["Utilities"]:::util
    Utils -->|"supports"| ThemeToggle

    %% Click Events
    click EntryHTML "https://github.com/zzwtsy/wakatime-dashboard/blob/react/index.html"
    click MainTSX "https://github.com/zzwtsy/wakatime-dashboard/blob/react/src/main.tsx"
    click App "https://github.com/zzwtsy/wakatime-dashboard/blob/react/src/App.tsx"
    click Dashboard "https://github.com/zzwtsy/wakatime-dashboard/blob/react/src/components/Dashboard.tsx"
    click ThemeProvider "https://github.com/zzwtsy/wakatime-dashboard/blob/react/src/components/ThemeProvider.tsx"
    click ThemeToggle "https://github.com/zzwtsy/wakatime-dashboard/blob/react/src/components/ThemeToggle.tsx"
    click Chart "https://github.com/zzwtsy/wakatime-dashboard/blob/react/src/components/charts/Chart.tsx"
    click Doughnut "https://github.com/zzwtsy/wakatime-dashboard/blob/react/src/components/charts/DoughnutChart.tsx"
    click Stacked "https://github.com/zzwtsy/wakatime-dashboard/blob/react/src/components/charts/StackedHorizontalBar.tsx"
    click GithubIcon "https://github.com/zzwtsy/wakatime-dashboard/blob/react/src/components/icon/GithubIcon.tsx"
    click ApiLayer "https://github.com/zzwtsy/wakatime-dashboard/blob/react/src/api/index.ts"
    click DomainModels "https://github.com/zzwtsy/wakatime-dashboard/tree/react/src/entity"
    click DomainModels "https://github.com/zzwtsy/wakatime-dashboard/blob/react/src/enum/localStorageKeyEnum.ts"
    click DomainModels "https://github.com/zzwtsy/wakatime-dashboard/blob/react/src/types.ts"
    click Assets "https://github.com/zzwtsy/wakatime-dashboard/tree/react/src/assets/echarts"
    click Utils "https://github.com/zzwtsy/wakatime-dashboard/blob/react/src/utils.ts"
    click Utils "https://github.com/zzwtsy/wakatime-dashboard/blob/react/src/localStorage.ts"

    %% Styling
    classDef external fill:#ffcccc,stroke:#990000,stroke-width:2px;
    classDef business fill:#cce5ff,stroke:#004085,stroke-width:2px;
    classDef ui fill:#d4edda,stroke:#155724,stroke-width:2px;
    classDef util fill:#fff3cd,stroke:#856404,stroke-width:2px;
```
