# remvze/moodist architecture

> Architecture diagram of the GitHub repository remvze/moodist, 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/remvze/moodist
- Repository: https://github.com/remvze/moodist

## Overview

##### Main Components
- Frontend Application: Represented by the Astro project that generates static HTML and hydrates dynamic React components.
- UI Components: A large set of reusable components (buttons, modals, toolbars, sliders, notepad, pomodoro timer, etc.) found under src/components.
- State Management & Contexts: Using Zustand stores (in src/stores) and React contexts (e.g., snackbar, stories) that coordinate application state (sound selections, modal states, timers, etc.).
- Data & Assets: Ambient sound assets (located in public/sounds and src/data/sounds) and other static media (public/assets, fonts, images).
- Utilities and Helpers: Various helper functions under src/helpers and libraries (e.g., for sound handling, browser detection, randomization).
- Deployment & Infrastructure Components: Dockerfiles, docker-compose.yml, and Nginx configuration (in docker/nginx) which illustrate the containerization and web server used in production.

##### Relationships and Interactions
- The Client Browser (User) interacts with the Frontend Application, which is rendered initially by Astro and enhanced with React.
- UI components communicate with individual stores (via Zustand) and contexts to fetch, update, and synchronize the state (for example, handling the persistent sound selection, timers, and notepad elements).
- User interactions trigger events (keyboard shortcuts, modal displays, media controls) that flow from individual components into the common state and UI feedback loops.
- The build and deployment pipeline is maintained by Docker, where the application is built and served via an Nginx container, using docker-compose to orchestrate containers and related services.
- External static resources like ambient sound files, images, and fonts come from the public folder and are served directly to the client.

##### Architectural Patterns and Design Principles
- Component-Based Architecture: A large, modular set of UI components grouped by functionality (buttons, modals, toolboxes, toolbars, etc.) that follow a clear separation of concerns.
- State Management Abstraction: Use of centralized state stores (Zustand) and contexts to encapsulate UI state, ensuring that data flows in one direction and minimizing side effects.
- Static Site Generation with Client Hydration: Astro is used to generate static pages, which are then hydrated by React, ensuring fast initial load times alongside dynamic interactivity.
- Containerization for Deployment: The Dockerfile and docker-compose configuration indicate that the project is designed to be self-hostable, isolating the production server (Nginx) from the underlying application logic.

##### Relevant Technologies Specified
- Frameworks & Languages: Astro, React, TypeScript.
- Styling & Animation: CSS Modules, Framer Motion.
- State & Data: Zustand for state management; local sound data (from src/data).
- CI/CD and Quality Tools: ESLint, Prettier, Stylelint, Husky, Commitizen, etc.
- Docker and Nginx: For containerized build and production deployment.
- Testing Tools (upcoming): Vitest for unit tests and Playwright for end-to-end testing.

- Client Browser / User Interface
- Astro Static Site Generator (SSR & SSG layer)
- React Components (grouped by functional area: modals, toolbar, sound controls, etc.)
- Zustand Stores / React Contexts
- Static Assets and Data Sources (sounds, images, fonts)
- Docker / Nginx Containerized Deployment Environment
- Data flow between the UI components and the state management (e.g., user actions → store updates → UI refresh)
- Pipeline of build and deployment from code (Astro/React) → Docker build → Nginx serving to client.
- Differentiate between presentation (UI components), state (stores/contexts), configuration/infrastructure (Docker, Nginx), and static assets.
- Provide callouts or annotations for key technologies (e.g., “Astro for Static Generation”, “Zustand for centralized state management”) to clarify their role within the system.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Global Entities
    A["Client Browser (User)"]:::external

    %% Frontend Application Layer
    subgraph "Frontend Application"
        B["Astro Static Site Generator"]:::frontend
        C["React Components"]:::frontend
    end

    %% UI and State Layer
    subgraph "UI and State Layer"
        D["UI Components"]:::ui
        E["Zustand Stores"]:::state
        F["React Contexts"]:::state
    end

    %% Assets & Helpers Layer
    subgraph "Assets & Helpers"
        G["Ambient Sound Assets"]:::assets
        H["Sound Data"]:::assets
        I["Utilities & Helpers"]:::helper
    end

    %% Deployment & Infrastructure Layer
    subgraph "Deployment & Infrastructure"
        J["Docker (Containerization)"]:::infra
        K["Nginx (Production Server)"]:::infra
    end

    %% Connections
    A -->|"initialLoad"| B
    B -->|"hydrates"| C
    C -->|"renders"| D
    D -->|"triggersUpdates"| E
    D -->|"triggersUpdates"| F
    E -->|"stateChanges"| C
    F -->|"stateUpdates"| C
    G -->|"providesMedia"| C
    H -->|"suppliesData"| C
    I -->|"assists"| C
    C -->|"buildAndDeploy"| J
    J -->|"orchestrates"| K
    K -->|"servesAssets"| A

    %% Click Events for Component Mapping
    click B "https://github.com/remvze/moodist/blob/main/astro.config.mjs"
    click B "https://github.com/remvze/moodist/blob/main/src/pages/index.astro"
    click D "https://github.com/remvze/moodist/tree/main/src/components"
    click E "https://github.com/remvze/moodist/tree/main/src/stores"
    click F "https://github.com/remvze/moodist/tree/main/src/contexts"
    click G "https://github.com/remvze/moodist/tree/main/public/sounds"
    click H "https://github.com/remvze/moodist/tree/main/src/data/sounds"
    click I "https://github.com/remvze/moodist/tree/main/src/helpers"
    click J "https://github.com/remvze/moodist/tree/main/Dockerfile"
    click J "https://github.com/remvze/moodist/blob/main/docker-compose.yml"
    click K "https://github.com/remvze/moodist/blob/main/docker/nginx/nginx.conf"

    %% Styles
    classDef external fill:#ffcccc,stroke:#333,stroke-width:2px;
    classDef frontend fill:#cce5ff,stroke:#333,stroke-width:2px;
    classDef ui fill:#d4edda,stroke:#333,stroke-width:2px;
    classDef state fill:#fff3cd,stroke:#333,stroke-width:2px;
    classDef assets fill:#e6ccff,stroke:#333,stroke-width:2px;
    classDef helper fill:#ffe6cc,stroke:#333,stroke-width:2px;
    classDef infra fill:#f8d7da,stroke:#333,stroke-width:2px;
```
