# kr3t3n/crosscribb architecture

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

- Interactive diagram: https://gitdiagram.com/kr3t3n/crosscribb
- Repository: https://github.com/kr3t3n/crosscribb

## Overview

##### Project type and purpose
- This is a client-side, single-page Progressive Web App (PWA) built in React + TypeScript.
- Its purpose is to provide an offline-capable scoring companion for Cribbage and Cross-Crib games, with real-time score tracking, history, stats, and theming.

##### File structure
- Top level:
- src/ – application code
- src/components/ – small, reusable UI pieces (Header, Footer, ScoreBoard, RoundHistory, etc.)
- src/pages/ – route-level views (Landing, GamePage, Contact, Privacy, Terms)
- src/contexts/ – React Context providers (ThemeContext for dark/light, plus potentially a GameContext)
- src/utils/ – pure business-logic functions (scoring.ts, stats.ts)
- src/types/ – TypeScript type definitions for game models
- Config/build: Vite (vite.config.ts), Tailwind (tailwind.config.js), ESLint, TS configs, Netlify deployment via static export

##### README for architectural insights
- State management via React Context + Local Storage
- PWA capabilities (service-worker, manifest) for offline support
- The build & deployment pipeline: Vite → optimized static assets → Netlify CDN

1. User & Browser (client)
2. PWA Shell (service-worker, manifest)
3. React SPA (App.tsx / React Router)
4. Pages (LandingPage, GamePage, etc.)
5. UI Components (Header, ScoreBoard, RoundScoring, GameStats, ThemeToggle…)
6. Context Layer (ThemeContext, GameContext)
7. Business Logic / Utils (scoring.ts, stats.ts)
8. Local Storage (persistent game state)
9. Build & Deployment (Vite bundler, Tailwind processing, Netlify hosting)

- User → Browser → PWA Shell
- PWA Shell → React SPA root
- React Router → Page components
- Pages & Components ↔ Context (read/write state)
- Components → Utils (compute scores, stats)
- Context & Utils ↔ Local Storage (persist, rehydrate)
- Source code → Vite → Bundled assets → Netlify (CI/CD)

c. Architectural patterns & principles:
- Single-Page Application (SPA) with client-side routing
- Component composition & separation of concerns (small UI units vs page-level containers)
- Context API for global cross-cutting concerns (theme, game state)
- Clear boundary between UI, state management, business logic, and storage
- PWA pattern for offline first

d. Key technologies & frameworks:
- React 18 + TypeScript
- React Context API
- Vite (ESM build tool)
- Tailwind CSS for utility-first styling
- Local Storage Web API
- Netlify static hosting & CDN

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Browser & PWA Shell
    subgraph "Browser / PWA Shell"
        direction TB
        User["User"]:::external
        Browser["Browser"]:::external
        PWA_Shell["PWA Shell"]:::infra
        Manifest["site.webmanifest"]:::infra
        IndexHTML["index.html"]:::infra
        Images["public/images/"]:::infra
    end

    %% React App Bootstrapping
    subgraph "React Application"
        direction TB
        Main["main.tsx"]:::infra
        App["App.tsx"]:::infra

        subgraph "Pages (Routing)"
            direction TB
            Landing["LandingPage"]:::ui
            GamePg["GamePage"]:::ui
            Contact["ContactPage"]:::ui
            Privacy["PrivacyPage"]:::ui
            Terms["TermsPage"]:::ui
        end

        subgraph "UI Components"
            direction TB
            Header["Header"]:::ui
            Footer["Footer"]:::ui
            ScoreBoard["ScoreBoard"]:::ui
            RoundScoring["RoundScoring"]:::ui
            RoundHistory["RoundHistory"]:::ui
            GameStats["GameStats"]:::ui
            GameSetup["GameSetup"]:::ui
            ThemeToggle["ThemeToggle"]:::ui
        end

        subgraph "Context Layer"
            direction TB
            ThemeCtx["ThemeContext"]:::state
        end

        subgraph "Business Logic / Utils"
            direction TB
            Scoring["scoring.ts"]:::logic
            StatsUtil["stats.ts"]:::logic
        end

        subgraph "Type Definitions"
            direction TB
            GameTypes["game.ts"]:::infra
        end

        Styling["src/index.css"]:::infra
    end

    %% Build & Deployment
    subgraph "Build & Deployment Pipeline"
        direction TB
        Vite["vite.config.ts"]:::infra
        TailwindCfg["tailwind.config.js"]:::infra
        TSConfig1["tsconfig.json"]:::infra
        TSConfigApp["tsconfig.app.json"]:::infra
        TSConfigNode["tsconfig.node.json"]:::infra
        ESLintCfg["eslint.config.js"]:::infra
        Netlify["Netlify/CDN"]:::infra
    end

    %% Connections
    User --> Browser
    Browser --> PWA_Shell
    PWA_Shell --> Manifest
    PWA_Shell --> IndexHTML
    PWA_Shell --> Images
    IndexHTML --> Main
    Main --> App
    App --> Landing
    App --> GamePg
    App --> Contact
    App --> Privacy
    App --> Terms
    Landing --> Header
    Landing --> Footer
    GamePg --> ScoreBoard
    GamePg --> RoundScoring
    GamePg --> RoundHistory
    GamePg --> GameSetup
    GamePg --> GameStats
    Header --> ThemeToggle
    ThemeToggle --> ThemeCtx
    ScoreBoard --> Scoring
    RoundScoring --> Scoring
    RoundHistory --> StatsUtil
    GameStats --> StatsUtil
    ThemeCtx --> Styling
    ThemeCtx --> GameTypes
    Scoring --> GameTypes
    StatsUtil --> GameTypes
    ThemeCtx -->|"persist/rehydrate"| Styling
    ThemeCtx -->|"persist/rehydrate"| GameTypes
    Scoring -->|"persist/rehydrate"| GameTypes
    App --> ThemeCtx
    App --> Scoring
    App --> StatsUtil

    %% Build pipeline connections
    Main --> Vite
    App --> Vite
    Styling --> TailwindCfg
    Vite --> Netlify
    TailwindCfg --> Netlify
    TSConfig1 --> Vite
    TSConfigApp --> Vite
    TSConfigNode --> Vite
    ESLintCfg --> Vite

    %% Click Events
    click Manifest "https://github.com/kr3t3n/crosscribb/blob/main/public/site.webmanifest"
    click IndexHTML "https://github.com/kr3t3n/crosscribb/blob/main/index.html"
    click Images "https://github.com/kr3t3n/crosscribb/tree/main/public/images/"
    click Main "https://github.com/kr3t3n/crosscribb/blob/main/src/main.tsx"
    click App "https://github.com/kr3t3n/crosscribb/blob/main/src/App.tsx"
    click Landing "https://github.com/kr3t3n/crosscribb/blob/main/src/pages/LandingPage.tsx"
    click GamePg "https://github.com/kr3t3n/crosscribb/blob/main/src/pages/GamePage.tsx"
    click Contact "https://github.com/kr3t3n/crosscribb/blob/main/src/pages/ContactPage.tsx"
    click Privacy "https://github.com/kr3t3n/crosscribb/blob/main/src/pages/PrivacyPage.tsx"
    click Terms "https://github.com/kr3t3n/crosscribb/blob/main/src/pages/TermsPage.tsx"
    click Header "https://github.com/kr3t3n/crosscribb/blob/main/src/components/Header.tsx"
    click Footer "https://github.com/kr3t3n/crosscribb/blob/main/src/components/Footer.tsx"
    click ScoreBoard "https://github.com/kr3t3n/crosscribb/blob/main/src/components/ScoreBoard.tsx"
    click RoundScoring "https://github.com/kr3t3n/crosscribb/blob/main/src/components/RoundScoring.tsx"
    click RoundHistory "https://github.com/kr3t3n/crosscribb/blob/main/src/components/RoundHistory.tsx"
    click GameStats "https://github.com/kr3t3n/crosscribb/blob/main/src/components/GameStats.tsx"
    click GameSetup "https://github.com/kr3t3n/crosscribb/blob/main/src/components/GameSetup.tsx"
    click ThemeToggle "https://github.com/kr3t3n/crosscribb/blob/main/src/components/ThemeToggle.tsx"
    click ThemeCtx "https://github.com/kr3t3n/crosscribb/blob/main/src/contexts/ThemeContext.tsx"
    click Scoring "https://github.com/kr3t3n/crosscribb/blob/main/src/utils/scoring.ts"
    click StatsUtil "https://github.com/kr3t3n/crosscribb/blob/main/src/utils/stats.ts"
    click GameTypes "https://github.com/kr3t3n/crosscribb/blob/main/src/types/game.ts"
    click Styling "https://github.com/kr3t3n/crosscribb/blob/main/src/index.css"
    click Vite "https://github.com/kr3t3n/crosscribb/blob/main/vite.config.ts"
    click TailwindCfg "https://github.com/kr3t3n/crosscribb/blob/main/tailwind.config.js"
    click TSConfig1 "https://github.com/kr3t3n/crosscribb/blob/main/tsconfig.json"
    click TSConfigApp "https://github.com/kr3t3n/crosscribb/blob/main/tsconfig.app.json"
    click TSConfigNode "https://github.com/kr3t3n/crosscribb/blob/main/tsconfig.node.json"
    click ESLintCfg "https://github.com/kr3t3n/crosscribb/blob/main/eslint.config.js"

    %% Styles
    classDef ui fill:#cce5ff,stroke:#000,stroke-width:1px
    classDef state fill:#d4edda,stroke:#000,stroke-width:1px
    classDef logic fill:#fff3cd,stroke:#000,stroke-width:1px
    classDef infra fill:#e2e3e5,stroke:#000,stroke-width:1px
    classDef external fill:#f8d7da,stroke:#000,stroke-width:1px
```
