# scoutingscherpenzeel/jotihunt-tracker-client architecture

> Architecture diagram of the GitHub repository scoutingscherpenzeel/jotihunt-tracker-client, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/scoutingscherpenzeel/jotihunt-tracker-client
- Repository: https://github.com/scoutingscherpenzeel/jotihunt-tracker-client

## Overview

##### Project Type and Purpose
- This is a single-page front-end application (“Jotihunt Tracker (client)”) built with React (TSX), Vite, Tailwind, Zustand for state, SWR for data fetching, and Docker for containerization.
- It visualizes and manages “hunts” on a map (Google Maps API), letting users authenticate, view teams, markers, areas, devices, articles, hints, etc., by calling an external REST API.

##### Main Architectural Components
a. Browser / Client Runtime
- Serves index.html → boots React via main.tsx.
- Loads the Vite‐built JS/CSS bundle.
b. React Application
- Entry: src/main.tsx → Layout.tsx → Routes.tsx (React Router)
- Pages: src/pages/App.tsx, Login.tsx, Users.tsx
- UI Components: src/components/ui/* (buttons, dialogs, cards…)
- Feature Components: Map, Layers, Cards under src/components (e.g., MapMarker, NextHintTimeCard)
- Hooks layer: src/hooks/* (auth.hook.ts, hunts.hook.ts, teams.hook.ts, etc.) wraps API calls
- Data caching: src/lib/swr.ts used by hooks
- State management: src/stores/* (Zustand stores like counterhunt.store.ts, layers.store.ts)
- Utilities/types: src/lib/utils.ts, src/types/* for domain models
- Assets: src/assets (audio, images)
c. External Services
- REST API (Auth, Hunts, Teams, Markers, Devices, Areas, Articles endpoints)
- Google Maps JavaScript API for map rendering
d. Build & Deployment Pipeline
- Vite config (vite.config.ts, tsconfig.json) for bundling
- Dockerfile & .dockerignore for container image
- GitHub Actions (deploy-image.yml) to build & push image
- Environment variables (.env.example)

##### Relationships and Data Flows
- User → Browser UI → React Components
- UI events call custom hooks → fetch data from REST API → SWR caches → Zustand stores → triggers re-renders of components
- Components → Google Maps API (external script & REST if needed)
- CI/CD: Git push → GitHub Actions → Vite build → Docker image → registry → hosting

##### Key Architectural Patterns & Principles
- Layered separation:
- Presentational (UI) vs. container logic (hooks & stores)
- Data fetching & caching (SWR) separated from state (Zustand)
- Feature-based grouping: components, hooks, stores grouped by domain concept (hunts, teams, markers…)
- API‐first design: all domain data interacts via REST, enabling easy mock/testing
- Single Page Application (SPA) with client‐side routing

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Browser / Client Runtime
    subgraph "Browser / Client Runtime"
        direction TB
        HTML["index.html"]:::frontend
        MainEntry["src/main.tsx"]:::frontend
        Styles["src/index.css"]:::frontend
        HTML -->|boots React| MainEntry
        MainEntry -->|imports CSS| Styles
    end

    %% React SPA
    subgraph "React SPA"
        direction TB
        subgraph "Presentation Layer"
            direction TB
            Layout["src/Layout.tsx"]:::frontend
            Routes["src/Routes.tsx"]:::frontend
            AppPage["src/pages/App.tsx"]:::frontend
            LoginPage["src/pages/Login.tsx"]:::frontend
            UsersPage["src/pages/Users.tsx"]:::frontend
            UIComponents["src/components/ui (Presentation)"]:::frontend
            FeatureMap["src/components/Map.tsx"]:::frontend
            MapSubs["src/components/map/*"]:::frontend
            LayerComps["src/components/layers/*"]:::frontend
            CardComps["src/components/cards/*"]:::frontend
            Layout --> Routes
            Routes --> AppPage
            Routes --> LoginPage
            Routes --> UsersPage
            AppPage --> UIComponents
            AppPage --> FeatureMap
            FeatureMap --> MapSubs
            AppPage --> LayerComps
            AppPage --> CardComps
        end

        subgraph "Hooks & API Services"
            direction TB
            DomainHooks["src/hooks/*"]:::data
            UtilHooks["src/hooks/utils/*"]:::data
            SWRConfig["src/lib/swr.ts"]:::data
            DomainHooks --> SWRConfig
            UtilHooks --> DomainHooks
        end

        subgraph "State Management"
            direction TB
            Stores["src/stores/*"]:::data
            SWRConfig --> Stores
        end

        subgraph "Utilities & Types"
            direction TB
            Utils["src/lib/utils.ts"]:::data
            Types["src/types/*"]:::data
            Utils --> AppPage
            Types --> DomainHooks
        end

        subgraph "Assets"
            direction TB
            Audio["src/assets/audio/hint-alert.mp3"]:::frontassets
            Images["src/assets/images/*"]:::frontassets
            PublicAssets["public/robots.txt"]:::frontassets
        end
    end

    %% External Services
    subgraph "External Services"
        direction TB
        REST["REST API"]:::external
        GoogleMaps["Google Maps API"]:::external
    end

    %% CI/CD Pipeline
    subgraph "Build & Deployment Pipeline"
        direction TB
        ViteConfig["vite.config.ts / tsconfig*.json"]:::pipeline
        DockerCfg["Dockerfile /.dockerignore"]:::pipeline
        EnvExample[".env.example"]:::pipeline
        CIWorkflow[".github/workflows/deploy-image.yml"]:::pipeline
        CIWorkflow -->|build| ViteConfig
        ViteConfig -->|bundle| DockerCfg
        DockerCfg -->|docker build & push| EnvExample
    end

    %% Data Flows
    User["User"]:::external
    User -->|interacts with| HTML
    MainEntry -->|"renders"| Layout
    UIComponents -->|"UI events"| DomainHooks
    DomainHooks -->|"HTTP/HTTPS JSON"| REST
    REST -->|"JSON response"| DomainHooks
    DomainHooks -->|"updates"| Stores
    Stores -->|"triggers re-render"| UIComponents
    FeatureMap -->|"JS SDK"| GoogleMaps

    CIWorkflow -->|"deploys image"| User

    %% Click Events
    click HTML "https://github.com/scoutingscherpenzeel/jotihunt-tracker-client/blob/main//index.html"
    click MainEntry "https://github.com/scoutingscherpenzeel/jotihunt-tracker-client/blob/main//src/main.tsx"
    click Styles "https://github.com/scoutingscherpenzeel/jotihunt-tracker-client/blob/main//src/index.css"
    click Layout "https://github.com/scoutingscherpenzeel/jotihunt-tracker-client/blob/main//src/Layout.tsx"
    click Routes "https://github.com/scoutingscherpenzeel/jotihunt-tracker-client/blob/main//src/Routes.tsx"
    click AppPage "https://github.com/scoutingscherpenzeel/jotihunt-tracker-client/blob/main//src/pages/App.tsx"
    click LoginPage "https://github.com/scoutingscherpenzeel/jotihunt-tracker-client/blob/main//src/pages/Login.tsx"
    click UsersPage "https://github.com/scoutingscherpenzeel/jotihunt-tracker-client/blob/main//src/pages/Users.tsx"
    click UIComponents "https://github.com/scoutingscherpenzeel/jotihunt-tracker-client/tree/main//src/components/ui"
    click FeatureMap "https://github.com/scoutingscherpenzeel/jotihunt-tracker-client/blob/main//src/components/Map.tsx"
    click MapSubs "https://github.com/scoutingscherpenzeel/jotihunt-tracker-client/tree/main//src/components/map"
    click LayerComps "https://github.com/scoutingscherpenzeel/jotihunt-tracker-client/tree/main//src/components/layers"
    click CardComps "https://github.com/scoutingscherpenzeel/jotihunt-tracker-client/tree/main//src/components/cards"
    click DomainHooks "https://github.com/scoutingscherpenzeel/jotihunt-tracker-client/tree/main//src/hooks"
    click UtilHooks "https://github.com/scoutingscherpenzeel/jotihunt-tracker-client/tree/main//src/hooks/utils"
    click SWRConfig "https://github.com/scoutingscherpenzeel/jotihunt-tracker-client/blob/main//src/lib/swr.ts"
    click Stores "https://github.com/scoutingscherpenzeel/jotihunt-tracker-client/tree/main//src/stores"
    click Utils "https://github.com/scoutingscherpenzeel/jotihunt-tracker-client/blob/main//src/lib/utils.ts"
    click Types "https://github.com/scoutingscherpenzeel/jotihunt-tracker-client/tree/main//src/types"
    click Audio "https://github.com/scoutingscherpenzeel/jotihunt-tracker-client/blob/main//src/assets/audio/hint-alert.mp3"
    click Images "https://github.com/scoutingscherpenzeel/jotihunt-tracker-client/tree/main//src/assets/images"
    click PublicAssets "https://github.com/scoutingscherpenzeel/jotihunt-tracker-client/blob/main//public/robots.txt"
    click ViteConfig "https://github.com/scoutingscherpenzeel/jotihunt-tracker-client/blob/main//vite.config.ts"
    click DockerCfg "https://github.com/scoutingscherpenzeel/jotihunt-tracker-client/tree/main//Dockerfile"
    click EnvExample "https://github.com/scoutingscherpenzeel/jotihunt-tracker-client/blob/main//.env.example"
    click CIWorkflow "https://github.com/scoutingscherpenzeel/jotihunt-tracker-client/blob/main//.github/workflows/deploy-image.yml"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#0066CC,color:#003366
    classDef data fill:#E6F9E6,stroke:#33AA33,color:#006600
    classDef external fill:#FFE5CC,stroke:#FF6600,color:#994C00
    classDef pipeline fill:#F2F2F2,stroke:#999999,color:#666666
    classDef frontassets fill:#FFF5CC,stroke:#CCAA00,color:#665500
```
