# jhanink/poolmaster architecture

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

- Interactive diagram: https://gitdiagram.com/jhanink/poolmaster
- Repository: https://github.com/jhanink/poolmaster

## Overview

##### Main Components
a. Frontend/UI Layer:
- The React Application housed in the “app” directory.
- Organized routing (see app/routes, react-router.config.ts) that manages navigation.
- UI components (e.g., header, footer, main, guest form/list, drag-and-drop interfaces) within app/routes/components.
- Global state management aspects under app/appStateGlobal (jotai atoms) and local state via React hooks.
- Styling: Incorporates Tailwind CSS and CSS Modules (e.g., in headerStyles.module.css, etc.).

b. Configuration & Utilities:
- Configuration management in app/config that holds environment/runtime configurations (AppConfig.ts, AppRuntime.ts, etc.) and service interfaces.
- Utility helpers in app/util for managing themes, storage, general styling, etc.

c. Server/Backend Layer:
- Server-side logic under app/server covers domain-specific actions such as guest assignment, guest deletion, saving guest data, state synchronization, and file storage interactions.
- A websocket manager (app/server/websocketManager.ts) is responsible for real-time updates between clients.

d. Persistence/Storage Layer:
- Filesystem storage managed outside the main UI under fileStorage, which contains sample data (e.g., app_state_file.json) to serve as a central shared source of truth state.

##### Understanding the Relationships and Interactions
- The user interacts with the Frontend/UI layer which uses React Router to handle navigation through different views/pages.
- UI components send actions (e.g., form submissions, drag-and-drop interactions) that trigger client-side event handlers, invoking “Remix” style loaders and actions.
- These actions communicate with the Server Layer (via endpoints implemented in app/server) to handle CRUD operations and state synchronization.
- The websocket manager in the server sends real-time state updates back to the UI clients, ensuring consistency across sessions.
- Global state managed by jotai is updated based on server responses, and these changes may trigger UI re-rendering.
- The Server Layer interfaces with the filesystem (fileStorage) to persist data, creating a layered interaction between active state, persistent storage, and client views.

##### Architectural Patterns and Design Principles
- Componentized UI: Separation of concerns across distinct UI components (header, footer, main, etc.) ensuring modularity.
- Layered Architecture: Clear separation between the presentation (React components), business logic (server actions, websocket manager), and persistence (fileStorage).
- Real-Time Synchronization: The use of a dedicated websocketManager for maintaining real-time client-to-client state synchronization.
- Configuration as Code: Dedicated configuration files capture runtime and application settings, making the architecture flexible and maintainable.
- “Remix” style actions/loaders: This pattern simplifies data fetching and state updating by coupling UI events directly with backend actions.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend/UI Layer
    subgraph "Frontend/UI Layer"
        A["React UI"]:::frontend
        B["React Router Config"]:::frontend
        C["Routes"]:::frontend
        D["Root Component"]:::frontend
        E["UI Components"]:::frontend
        F["Global State Management"]:::frontend
        G["Local State"]:::frontend
        H["Styling"]:::frontend
    end

    %% Backend/Server Layer
    subgraph "Backend/Server Layer"
        I["Assign Guest Service"]:::backend
        J["Delete Guest Service"]:::backend
        K["Save Guest Service"]:::backend
        L["State Service"]:::backend
        M["Storage Service"]:::backend
        N["Websocket Manager"]:::backend
        O["Config & Util"]:::backend
    end

    %% Persistence Layer
    subgraph "Persistence Layer"
        P(("Filesystem Storage")):::persistence
        Q["Sample Data File"]:::persistence
    end

    %% Internal Frontend connections
    A -->|"includes"| B
    A -->|"includes"| C
    A -->|"includes"| D
    A -->|"organizes"| E
    A -->|"updates"| F
    A -->|"uses"| G
    A -->|"loads"| H

    %% Config linkage
    O -->|"configures"| A
    O -->|"assists"| E

    %% UI to Backend actions
    E -->|"action_submit"| I
    E -->|"action_submit"| J
    E -->|"action_submit"| K
    E -->|"action_submit"| L
    E -->|"action_submit"| M

    %% Backend persistence interactions
    I -->|"persist_data"| P
    M -->|"read_write"| P
    L -->|"sync_state"| P

    %% Real-time communication
    N <-->|"realtime_update"| A

    %% Class Definitions
    classDef frontend fill:#bbdefb,stroke:#0d47a1,stroke-width:2px;
    classDef backend fill:#c8e6c9,stroke:#1b5e20,stroke-width:2px;
    classDef persistence fill:#eeeeee,stroke:#424242,stroke-width:2px;

    %% Click Events
    click A "https://github.com/jhanink/poolmaster/tree/master/app"
    click B "https://github.com/jhanink/poolmaster/blob/master/react-router.config.ts"
    click C "https://github.com/jhanink/poolmaster/blob/master/app/routes.ts"
    click D "https://github.com/jhanink/poolmaster/blob/master/app/root.tsx"
    click E "https://github.com/jhanink/poolmaster/tree/master/app/routes/components"
    click F "https://github.com/jhanink/poolmaster/blob/master/app/appStateGlobal/atoms.ts"
    click G "https://github.com/jhanink/poolmaster/blob/master/app/routes/components/main/guestForm/guestForm.tsx"
    click H "https://github.com/jhanink/poolmaster/blob/master/app/app.css"
    click O "https://github.com/jhanink/poolmaster/tree/master/app/config"
    click I "https://github.com/jhanink/poolmaster/blob/master/app/server/assignGuestService.server.ts"
    click J "https://github.com/jhanink/poolmaster/blob/master/app/server/deleteGuestService.server.ts"
    click K "https://github.com/jhanink/poolmaster/blob/master/app/server/saveGuestService.server.ts"
    click L "https://github.com/jhanink/poolmaster/blob/master/app/server/stateService.server.ts"
    click M "https://github.com/jhanink/poolmaster/blob/master/app/server/storageService.server.ts"
    click N "https://github.com/jhanink/poolmaster/blob/master/app/server/websocketManager.ts"
    click P "https://github.com/jhanink/poolmaster/tree/master/fileStorage"
    click Q "https://github.com/jhanink/poolmaster/blob/master/fileStorage/samples/app_state_file.json"
```
