# lucabn/canegattostivali architecture

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

- Interactive diagram: https://gitdiagram.com/lucabn/canegattostivali
- Repository: https://github.com/lucabn/canegattostivali

## Overview

##### Project type and purpose
- This is a client-side, single-page web application (a word-chain game) built with React and TypeScript. It’s hosted as a static site on Cloudflare Pages and uses Vite for build and development. There is no separate backend service—everything runs in the user’s browser and communicates only with local storage or embedded JSON data.

##### High-level components
a. User’s Browser (Client)
b. React Application
- Entry point (main.tsx)
- UI Layer (Atomic → Molecules → Organisms → Templates)
- State & Context Providers (ThemeProvider, KeyboardStatusProvider, ReactRouterProvider)
- Utilities (game logic, storage, encoding, etc.)
- Assets & Data (static JSON word lists, images, styles)
c. Build & Deployment Pipeline
- Vite (dev server, bundling, HMR)
- GitHub (source repo) → Cloudflare Pages (CDN‐backed static host)

##### Relationships & Data Flows
- Browser requests index.html from Cloudflare CDN → retrieves bundled JS/CSS/assets.
- React app boots, wraps `<App>` with Providers.
- UI components render based on internal state or static JSON data (wordList, newsData).
- User interactions (typing guesses, clicking buttons) → events propagate through React components → update Context or call utility functions (game-logic, local-storage).
- Local storage (via utils/local-storage.ts) persists user preferences or progress.
- Static assets (images, manifest.json) served by the same CDN.

##### Architectural Patterns & Design Principles
- Component-driven UI using Atomic Design (Atoms → Molecules → Organisms → Templates).
- Context providers for theme and keyboard status, enabling global state without prop drilling.
- Separation of concerns:
- UI (components)
- Business logic (utils/game-logic.ts)
- Data layer (static JSON in src/assets/data)
- Styling (SCSS modules, global overrides)
- Build-time bundling and optimization via Vite, TypeScript ensures type safety.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Entities
    User(("User")):::external
    Browser(["Browser"]):::external

    %% CDN and Hosting
    CloudflareCDN((Cloudflare CDN)):::infra
    IndexHTML(["index.html"]):::infra

    %% React Application Container
    subgraph "React Application"
        %% Entry & Routing
        subgraph "Entry & Routing"
            Main["main.tsx"]:::frontend
            AppCore["App Component"]:::frontend
        end

        %% Providers
        subgraph "Providers"
            ThemeProv["ThemeProvider"]:::providers
            KeyProv["KeyboardStatusProvider"]:::providers
            RouterProv["ReactRouterProvider"]:::providers
        end

        %% UI Component Layers
        subgraph "UI Components"
            subgraph "Atoms"
                Atoms["Atoms"]:::frontend
            end
            subgraph "Molecules"
                Molecules["Molecules"]:::frontend
            end
            subgraph "Organisms"
                Organisms["Organisms"]:::frontend
            end
            subgraph "Templates"
                Templates["Templates"]:::frontend
            end
        end

        %% Utilities
        subgraph "Utilities"
            GameLogic["game-logic.ts"]:::utils
            LocalStorageUtil["local-storage.ts"]:::utils
            Encoding["encoding.ts"]:::utils
        end

        %% Assets & Data
        subgraph "Assets & Data"
            WordList["wordList.json"]:::data
            NewsData["newsData.json"]:::data
            Images["Image Assets"]:::data
            Styles["Styles (SCSS)"]:::data
            Constants["Constants"]:::data
        end
    end

    %% Persistent Storage
    LocalStorage[(Local Storage)]:::data

    %% Build & Deployment
    GitHub[(GitHub Repo)]:::build
    Vite["Vite Build Server"]:::build
    CloudflarePages((Cloudflare Pages)):::infra

    %% Relationships & Flows
    User --> Browser
    Browser --> CloudflareCDN
    CloudflareCDN --> IndexHTML
    IndexHTML --> Main
    Main --> AppCore
    AppCore --> ThemeProv
    ThemeProv --> KeyProv
    KeyProv --> RouterProv
    RouterProv --> Atoms
    Atoms --> Molecules
    Molecules --> Organisms
    Organisms --> Templates

    %% UI interactions with utilities and data
    Templates --> GameLogic
    Templates --> LocalStorageUtil
    Templates --> Encoding
    Templates --> WordList
    Templates --> NewsData

    %% Utilities to storage
    LocalStorageUtil --> LocalStorage

    %% Build & deploy flow
    GitHub --> Vite
    Vite --> CloudflarePages
    CloudflarePages --> CloudflareCDN

    %% Click Events
    click Main "https://github.com/lucabn/canegattostivali/blob/main/src/main.tsx"
    click AppCore "https://github.com/lucabn/canegattostivali/blob/main/src/components/App/App.tsx"
    click Atoms "https://github.com/lucabn/canegattostivali/tree/main/src/components/UI/Atoms"
    click Molecules "https://github.com/lucabn/canegattostivali/tree/main/src/components/UI/Molecules"
    click Organisms "https://github.com/lucabn/canegattostivali/tree/main/src/components/UI/Organisms"
    click Templates "https://github.com/lucabn/canegattostivali/tree/main/src/components/UI/Templates"
    click ThemeProv "https://github.com/lucabn/canegattostivali/blob/main/src/components/providers/ThemeProvider/ThemeProvider.tsx"
    click KeyProv "https://github.com/lucabn/canegattostivali/blob/main/src/components/providers/KeyboardStatusProvider/KeyboardStatusProvider.tsx"
    click RouterProv "https://github.com/lucabn/canegattostivali/blob/main/src/components/providers/ReactRouterProvider/ReactRouterProvider.tsx"
    click GameLogic "https://github.com/lucabn/canegattostivali/blob/main/src/utils/game-logic.ts"
    click LocalStorageUtil "https://github.com/lucabn/canegattostivali/blob/main/src/utils/local-storage.ts"
    click Encoding "https://github.com/lucabn/canegattostivali/blob/main/src/utils/encoding.ts"
    click WordList "https://github.com/lucabn/canegattostivali/blob/main/src/assets/data/wordList.json"
    click NewsData "https://github.com/lucabn/canegattostivali/blob/main/src/assets/data/newsData.json"
    click Images "https://github.com/lucabn/canegattostivali/tree/main/public/assets/img"
    click Styles "https://github.com/lucabn/canegattostivali/blob/main/src/styles/index.scss"
    click GitHub "https://github.com/lucabn/canegattostivali/blob/main/vite.config.ts"
    click CloudflarePages "https://github.com/lucabn/canegattostivali/blob/main/public/manifest.json"
    click CloudflarePages "https://github.com/lucabn/canegattostivali/tree/main/public/_redirects"

    %% Styles
    classDef external fill:#a2d2ff,stroke:#1d3557,color:#1d3557
    classDef infra fill:#dee2e6,stroke:#495057,color:#495057
    classDef frontend fill:#caf0f8,stroke:#0077b6,color:#0077b6
    classDef providers fill:#b7e4c7,stroke:#2d6a4f,color:#2d6a4f
    classDef utils fill:#ffd8a8,stroke:#e76f51,color:#e76f51
    classDef data fill:#ffe5d9,stroke:#fc5a03,color:#fc5a03
    classDef build fill:#ced4da,stroke:#495057,color:#495057
```
