# carterlasalle/staminatimer architecture

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

- Interactive diagram: https://gitdiagram.com/carterlasalle/staminatimer
- Repository: https://github.com/carterlasalle/staminatimer

## Overview

##### Project Type and Purpose
- The README and file tree confirm that this is a full-stack application implemented in Next.js with TypeScript, Tailwind CSS, and Supabase.
- The primary goal is to allow users to time their training intervals, view historical data, access detailed analytics, and enjoy a responsive UI with dark mode support.

##### File Structure
- Top-level files like next.config.js, package.json, and tailwind.config.ts indicate standard configurations for a Next.js project.
- The src directory is our source of truth:
◦ The “src/app” directory contains Next.js page routes (e.g., dashboard, auth, login, license, privacy, share, terms) which indicate a client-side UI divided into distinct functional sections.
◦ The “src/components” folder houses reusable UI components (e.g., Achievements, Analytics, Timer) and UI primitives under a ui subdirectory, likely implemented using ShadCn/UI.
◦ “src/contexts” (e.g., AuthContext, GlobalContext) handle client-side state, ensuring global access to user authentication and global settings.
◦ “src/hooks” provide custom hooks to encapsulate logic, such as for achievements, analytics, sessions, and timers.
◦ “src/lib” is dedicated to helper utilities, analytics, export functionalities (PDF, share), security (validation, rate limiting), Supabase integration (client, schema, types), data fetching (getData) and shared types.
◦ “src/services” host service modules for analytics, database interactions, and toast messages.
- Middleware, configuration files (.eslintrc.json, postcss.config.mjs), and the Supabase SQL schema indicate integration with backend and external database.

##### Key Components and Responsibilities
- Frontend/UI Layer:
◦ Next.js pages: Various pages in the “src/app” directory for authentication, dashboard display, settings, and public info (license, privacy, terms).
◦ Reusable UI Components: Found under “src/components”, these handle timers, charts, data visualization, achievements, session history, etc. UI primitives under “src/components/ui” ensure consistency across the app.
◦ Contexts & Hooks: Enable state management (auth, global settings) and encapsulate functionality via custom hooks (e.g., useSession, useTimer).
- Backend Integration & Services:
◦ Server logic is mainly provided through API routes and Next.js middleware (“src/middleware.ts”) to ensure secure routing and data fetching.
◦ Database: Supabase is used as the backend for storing endurance metrics and historical data, with integration codes and schema definitions provided in “src/lib/supabase” and the “supabase/schema.sql” file.
◦ Analytics and Export Systems: “src/lib/analytics” and “src/lib/export” manage user analytics and the ability to export or share session data.
- External Libraries/Technologies:
◦ Tailwind CSS and Next.js for UI and application rendering.
◦ Chart.js for data visualization.
◦ ShadCn/UI for prebuilt UI components.
◦ Supabase integrates the database layer.

##### Relationships and Data Flow
- The frontend interacts with the backend through Next.js API routes and direct calls to Supabase for data persistence.
- Contexts and hooks abstract state and logic, while components are responsible for presenting user data and collecting input.
- Middleware and service files secure data flow and enforce rate limiting/validation at the server layer.
- External services (e.g., Chart.js) are integrated into the UI components, visualizing analytics data.

## Diagram (Mermaid)

```mermaid
flowchart TD

    %% Frontend Layer
    subgraph "Frontend Layer"
        %% Pages Subgraph
        subgraph "Pages"
            D["Dashboard Page"]:::pages
            L["Login Page"]:::pages
            A["Auth Routes"]:::pages
            Li["License Page"]:::pages
            P["Privacy Page"]:::pages
            S["Settings Page"]:::pages
            Sh["Share Page"]:::pages
            T["Terms Page"]:::pages
        end

        %% UI Components Subgraph
        subgraph "UI Components"
            TC["Timer Component"]:::components
            AC["Achievements Component"]:::components
            AN["Analytics Component"]:::components
            CH["Charts Component"]:::components
            SHI["Session History"]:::components
            SD["Session Details"]:::components
            EB["Export Button"]:::components
            UIP["UI Primitives"]:::components
            TUI["Toast UI Component"]:::components
        end

        %% Contexts & Hooks Subgraph
        subgraph "Contexts & Hooks"
            ACtx["Auth Context"]:::contexts
            GCtx["Global Context"]:::contexts
            THook["useTimer Hook"]:::contexts
            AHHook["useAnalytics Hook"]:::contexts
            ACHook["useAchievements Hook"]:::contexts
            SHook["useSession Hook"]:::contexts
            GHHook["useGlobalStats Hook"]:::contexts
        end
    end

    %% Backend & Services Layer
    subgraph "Backend & Services"
        %% API & Middleware Subgraph
        subgraph "API & Middleware"
            ADF["API/Data Fetching"]:::backend
            MW["Middleware"]:::backend
        end

        %% Supabase Integration Subgraph
        subgraph "Supabase Integration"
            SC["Supabase Client & Utils"]:::supabase
            SS["Supabase Schema"]:::supabase
            ST["Supabase Types"]:::supabase
            SSQL["Supabase SQL Schema"]:::supabase
            DB["Supabase Database"]:::supabase
        end

        %% Analytics & Export Subgraph
        subgraph "Analytics & Export"
            AA["Analytics Utilities"]:::services
            PE["PDF Export"]:::services
            SE["Share Export"]:::services
            AS["Analytics Service"]:::services
        end

        %% Security & Other Services Subgraph
        subgraph "Security & Other Services"
            RL["Rate Limiter"]:::security
            VAL["Validation"]:::security
            DS["Database Service"]:::security
            TS["Toast Service"]:::security
        end
    end

    %% Connections between Frontend groups
    D -->|"renders"| TC
    D -->|"renders"| AN
    L -->|"renders"| TC
    A -->|"renders"| TC
    Li -->|"renders"| TC
    P -->|"renders"| AN
    S -->|"renders"| TC
    Sh -->|"renders"| EB
    T -->|"renders"| TC

    %% UI Components using Hooks
    TC -->|"uses"| THook
    AN -->|"uses"| AHHook
    AC -->|"uses"| ACHook
    SHI -->|"monitors"| SHook
    CH -->|"uses"| AHHook
    EB -->|"triggers"| PE
    EB -->|"triggers"| SE
    TUI -->|"displays"| TS

    %% Contexts triggering API calls
    ACtx -->|"calls"| ADF
    GCtx -->|"calls"| ADF

    %% API & Middleware flows
    MW -->|"handles"| ADF
    RL --> MW
    VAL --> MW
    ADF -->|"fetches"| DS
    DS -->|"queries"| DB
    ADF -->|"utilizes"| SC
    SC --> DB

    %% Analytics & Export flows
    AN -->|"feeds"| AA
    CH -->|"feeds"| AA
    AA -->|"processes"| AS

    %% Click Events for Pages
    click D "https://github.com/carterlasalle/staminatimer/blob/main/src/app/dashboard/page.tsx"
    click L "https://github.com/carterlasalle/staminatimer/blob/main/src/app/login/page.tsx"
    click A "https://github.com/carterlasalle/staminatimer/tree/main/src/app/auth"
    click Li "https://github.com/carterlasalle/staminatimer/blob/main/src/app/license/page.tsx"
    click P "https://github.com/carterlasalle/staminatimer/blob/main/src/app/privacy/page.tsx"
    click S "https://github.com/carterlasalle/staminatimer/blob/main/src/app/settings/page.tsx"
    click Sh "https://github.com/carterlasalle/staminatimer/blob/main/src/app/share/[id]/page.tsx"
    click T "https://github.com/carterlasalle/staminatimer/blob/main/src/app/terms/page.tsx"

    %% Click Events for UI Components
    click TC "https://github.com/carterlasalle/staminatimer/blob/main/src/components/Timer.tsx"
    click AC "https://github.com/carterlasalle/staminatimer/blob/main/src/components/Achievements.tsx"
    click AN "https://github.com/carterlasalle/staminatimer/blob/main/src/components/Analytics.tsx"
    click CH "https://github.com/carterlasalle/staminatimer/blob/main/src/components/Charts.tsx"
    click SHI "https://github.com/carterlasalle/staminatimer/blob/main/src/components/SessionHistory.tsx"
    click SD "https://github.com/carterlasalle/staminatimer/blob/main/src/components/SessionDetails.tsx"
    click EB "https://github.com/carterlasalle/staminatimer/blob/main/src/components/ExportButton.tsx"
    click UIP "https://github.com/carterlasalle/staminatimer/tree/main/src/components/ui"
    click TUI "https://github.com/carterlasalle/staminatimer/blob/main/src/components/ui/toast.tsx"

    %% Click Events for Contexts & Hooks
    click ACtx "https://github.com/carterlasalle/staminatimer/blob/main/src/contexts/AuthContext.tsx"
    click GCtx "https://github.com/carterlasalle/staminatimer/blob/main/src/contexts/GlobalContext.tsx"
    click THook "https://github.com/carterlasalle/staminatimer/blob/main/src/hooks/useTimer.ts"
    click AHHook "https://github.com/carterlasalle/staminatimer/blob/main/src/hooks/useAnalytics.ts"
    click ACHook "https://github.com/carterlasalle/staminatimer/blob/main/src/hooks/useAchievements.ts"
    click SHook "https://github.com/carterlasalle/staminatimer/blob/main/src/hooks/useSession.ts"
    click GHHook "https://github.com/carterlasalle/staminatimer/blob/main/src/hooks/useGlobalStats.ts"

    %% Click Events for API & Middleware
    click ADF "https://github.com/carterlasalle/staminatimer/blob/main/src/lib/server/getData.ts"
    click MW "https://github.com/carterlasalle/staminatimer/blob/main/src/middleware.ts"

    %% Click Events for Supabase Integration
    click SC "https://github.com/carterlasalle/staminatimer/blob/main/src/lib/supabase/client.ts"
    click SS "https://github.com/carterlasalle/staminatimer/blob/main/src/lib/supabase/schema.ts"
    click ST "https://github.com/carterlasalle/staminatimer/blob/main/src/lib/supabase/types.ts"
    click SSQL "https://github.com/carterlasalle/staminatimer/blob/main/supabase/schema.sql"

    %% Click Events for Analytics & Export
    click AA "https://github.com/carterlasalle/staminatimer/blob/main/src/lib/analytics.ts"
    click PE "https://github.com/carterlasalle/staminatimer/blob/main/src/lib/export/pdf.ts"
    click SE "https://github.com/carterlasalle/staminatimer/blob/main/src/lib/export/share.ts"
    click AS "https://github.com/carterlasalle/staminatimer/blob/main/src/services/analytics.ts"

    %% Click Events for Security & Other Services
    click RL "https://github.com/carterlasalle/staminatimer/blob/main/src/lib/security/rateLimiter.ts"
    click VAL "https://github.com/carterlasalle/staminatimer/blob/main/src/lib/security/validation.ts"
    click DS "https://github.com/carterlasalle/staminatimer/blob/main/src/services/database.ts"
    click TS "https://github.com/carterlasalle/staminatimer/blob/main/src/services/toast.ts"

    %% Styles
    classDef pages fill:#AED6F1,stroke:#1F618D,stroke-width:2px,color:#000;
    classDef components fill:#F9E79F,stroke:#B9770E,stroke-width:2px,color:#000;
    classDef contexts fill:#D2B4DE,stroke:#6C3483,stroke-width:2px,color:#000;
    classDef backend fill:#ABEBC6,stroke:#27AE60,stroke-width:2px,color:#000;
    classDef supabase fill:#F5B7B1,stroke:#CB4335,stroke-width:2px,color:#000;
    classDef services fill:#D4EFDF,stroke:#229954,stroke-width:2px,color:#000;
    classDef security fill:#FAD7A0,stroke:#D35400,stroke-width:2px,color:#000;
```
