# codeaid/woth-toolbox architecture

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

- Interactive diagram: https://gitdiagram.com/codeaid/woth-toolbox
- Repository: https://github.com/codeaid/woth-toolbox

## Overview

##### Frontend Application Layer (Next.js Client)
- Pages (located in src/app): These include individual pages like Animals, Firearms, Life Cycle, Maps (Nez Perce Valley, Transylvania, Aurora Shores, Tikamoon Plains) showing different aspects of game data.
- Components (located in src/components): A large number of reusable UI components (Animal lists, Weapon selectors, maps, context menus, modals, buttons, toolbars, etc.) which are used to build the user interface.
- Layout and Navigation Components: These include Sidebar, NavLink, SidePanel, and Layout components that provide structure, routing, and interactivity across pages.

##### State Management and Business Logic
- Context Providers (src/contexts): Include ApplicationProvider, FirebaseContext, SettingsContext, TutorialContext, and custom contexts to manage global application state such as user settings, Firebase integration, and tutorial flows.
- Custom Hooks (src/hooks): Contains logic for handling animal markers, settings, localization, storage, and Firebase operations. These hooks encapsulate business logic and facilitate communication between UI components and data/services.
- Libraries in src/lib: These utility libraries handle tasks such as data filtering, routing, persistence, tracking, and integration with business rules (for example, calculating the recommended hit energy values and ethical ranges).

##### Data and Configuration Layer
- Localization (src/locales): Provide internationalization support, enabling the application to display content in multiple languages.
- Scripts (src/scripts): Data processing scripts (e.g., for “companion” data) that may be used during development or data preparation.

##### External Services and Storage
- Firebase Integration: Although the application stores many user-made customizations locally (as noted in the README) via browser local storage, there are Firebase configuration files (e.g., firebase.json, firestore.rules) and a FirebaseContext that could handle aspects of authentication or remote data storage if needed.
- Browser Local Storage: Used for storing marker customizations and other transient application data, ensuring that changes are preserved per browser instance.

##### Development, CI/CD & Tooling
- GitHub Actions (under .github/workflows): Automated workflows for tasks such as building and testing the Next.js application.
- Code Quality and Formatting Tools: ESLint, Prettier, Husky (for pre-commit hooks), and associated configuration files that ensure code quality and consistency.
- Deployment Configurations: Files like next.config.js and firebase.json indicate that the project’s deployment pipelines are set up to deploy on hosting platforms supporting Next.js and/or Firebase.

- Begin at the highest level by separating the application into the “Frontend UI Layer,” “Business Logic/State Management,” “Data/Configuration Layer” and “External Services.”
– From configuration files and static data (src/config, src/locales) into the context hooks and components.
– From components to state management (contexts and hooks) which in turn interact with Firebase services and local storage.
- Annotations for key interactions:
– The UI layer’s pages (animals, firearms, maps, etc.) communicate with Context providers (e.g., FirebaseContext for Firebase interactions, SettingsContext for user preferences) using custom hooks.
– Utility libraries (src/lib) support both business logic and data presentation, handling tasks like filtering (for weapons and ethical hit energy calculations) and routing.
– Localization and configuration data drive dynamic content; show how the localization files connect to UI components.

- Separation between:
– The UI (Next.js pages and React components) and the business logic (contexts, hooks, libraries),
– And the data layer (configuration files, localization, static and external data sources).
- To explicitly include auxiliary services (Firebase/Firestore) for authentication or remote data if needed in the future.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Data and Configuration Layer
    subgraph "Data and Configuration Layer"
        N_config["Static Config Files"]:::config
        N_locales["Localization"]:::config
        N_scripts["Scripts (companion data)"]:::config
    end

    %% Business Logic & State Management
    subgraph "Business Logic & State Management"
        N_context["Context Providers"]:::biz
        N_hooks["Custom Hooks"]:::biz
        N_lib["Utility Libraries"]:::biz
    end

    %% Frontend UI Layer
    subgraph "Frontend UI Layer"
        N_pages["Pages"]:::ui
        N_components["UI Components"]:::ui
        subgraph "Layout and Navigation"
            N_layout["Layout"]:::ui
            N_sidebar["Sidebar"]:::ui
            N_navlink["NavLink"]:::ui
            N_sidepanel["SidePanel"]:::ui
        end
    end

    %% External Services
    subgraph "External Services"
        N_firebase["Firebase Integration"]:::ext
        N_localstorage["Browser Local Storage Integration"]:::ext
    end

    %% Development & Tooling
    subgraph "Development & Tooling"
        N_github["GitHub Actions"]:::dev
        N_deploy["Deployment Configs"]:::dev
    end

    %% Connections from Data & Configuration to Business Logic
    N_config -->|"feeds"| N_context
    N_locales -->|"drives"| N_components
    N_scripts -->|"supports"| N_hooks

    %% Connections from Business Logic to Frontend UI
    N_context -->|"influences"| N_pages
    N_hooks -->|"updates"| N_pages
    N_lib -->|"enhances"| N_pages

    %% Connections from Business Logic to External Services
    N_context -->|"integrates"| N_firebase
    N_context -->|"stores"| N_localstorage
    N_hooks -->|"reads"| N_localstorage

    %% Development Build Process
    N_github -->|"triggers"| N_deploy
    N_deploy -->|"builds"| N_pages

    %% Click Events
    click N_pages "https://github.com/codeaid/woth-toolbox/tree/main/src/app"
    click N_components "https://github.com/codeaid/woth-toolbox/tree/main/src/components"
    click N_layout "https://github.com/codeaid/woth-toolbox/tree/main/src/components/Layout"
    click N_sidebar "https://github.com/codeaid/woth-toolbox/tree/main/src/components/Sidebar"
    click N_navlink "https://github.com/codeaid/woth-toolbox/tree/main/src/components/NavLink"
    click N_sidepanel "https://github.com/codeaid/woth-toolbox/tree/main/src/components/SidePanel"
    click N_context "https://github.com/codeaid/woth-toolbox/tree/main/src/contexts"
    click N_hooks "https://github.com/codeaid/woth-toolbox/tree/main/src/hooks"
    click N_lib "https://github.com/codeaid/woth-toolbox/tree/main/src/lib"
    click N_config "https://github.com/codeaid/woth-toolbox/tree/main/src/config"
    click N_locales "https://github.com/codeaid/woth-toolbox/tree/main/src/locales"
    click N_scripts "https://github.com/codeaid/woth-toolbox/tree/main/src/scripts/companion"
    click N_firebase "https://github.com/codeaid/woth-toolbox/blob/main/firebase.json"
    click N_localstorage "https://github.com/codeaid/woth-toolbox/tree/main/src/lib/persistence"
    click N_github "https://github.com/codeaid/woth-toolbox/tree/main/.github/workflows"
    click N_deploy "https://github.com/codeaid/woth-toolbox/blob/main/next.config.js"

    %% Styling Definitions
    classDef config fill:#fff3cd,stroke:#000,stroke-width:1px;
    classDef biz fill:#d4edda,stroke:#000,stroke-width:1px;
    classDef ui fill:#cce5ff,stroke:#000,stroke-width:1px;
    classDef ext fill:#f8d7da,stroke:#000,stroke-width:1px;
    classDef dev fill:#e2e3e5,stroke:#000,stroke-width:1px;
```
