# johntheo/brokeniceberg architecture

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

- Interactive diagram: https://gitdiagram.com/johntheo/brokeniceberg
- Repository: https://github.com/johntheo/brokeniceberg

## Overview

##### Project type and purpose
- This is a single‐page application (SPA) built with React and Vite, focused purely on frontend functionality.
- Purpose: display random icebreaker questions, support i18n (English, Spanish, Portuguese), allow copying/sharing via URL, and track user events via GA4. It is deployed as static assets on Firebase Hosting.

##### File structure
- Top level:
- index.html, public/ — static entry point and public assets
- src/ — all React/TS source code
- src/pages/Home.tsx — main page component
- src/components/… — UI components (InfoModal, QuestionDisplay, LanguageSelector)
- src/components/ui/… — low-level Shadcn UI primitives (button, card, dialog, etc.)
- src/assets/*.json — translation files
- src/lib/utils.ts — utility functions (e.g., random selection)
- main.tsx → mounts <App />
- App.tsx → wraps router, context, analytics init
- Config/deploy:
- vite.config.ts → build tool config
- tailwind.config.js, postcss.config.js → styling
- firebase.json → hosting deployment settings
- package.json → dependencies (React, react-ga4, Shadcn, Firebase CLI)

##### README for additional insights
- Confirms tech stack: React, TypeScript, Vite, Shadcn UI, Firebase Hosting, GA4 via react-ga4.
- Features section highlights user flows: language selection, URL-driven state, copy/share, analytics events.

a. Main components
1. User’s Browser (Client)
2. Firebase Hosting + CDN
3. Static Assets (index.html, JS/CSS bundles, translation JSON)
4. React SPA
- App shell (App.tsx → React Router if used)
- Core UI components (QuestionDisplay, LanguageSelector, InfoModal)
- Utility layer (utils.ts)
5. External Service: Google Analytics 4
b. Relationships and interactions
- Browser → Firebase Hosting (HTTP GET) → receives index.html + bundles + assets
- React SPA bootstraps in browser; loads translation JSON on demand
- User interactions (click “new question,” select language) trigger state updates in the SPA
- SPA writes to URL query string for shareable link
- SPA calls Clipboard API for “copy”
- SPA sends analytics events via GA4 HTTP calls
c. Architectural patterns and design principles
- SPA architecture (client-side routing, static hosting)
- Component-based design (atomic UI primitives in src/components/ui, composite components in src/components)
- Configuration-driven i18n (JSON files loaded per language)
- Separation of concerns: utilities separated from UI components
d. Relevant technologies/frameworks
- React + React Router
- Vite for build/dev
- TypeScript for typing
- Tailwind CSS + Shadcn UI components
- Firebase Hosting for static asset delivery
- Google Analytics 4 with react-ga4 integration

##### Essential details to capture
- Static asset delivery path via Firebase + CDN
- Runtime component hierarchy in the browser
- i18n asset loading flow
- URL-driven state and share logic
- Analytics integration flow

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client Layer
    Browser["User's Browser"]:::client

    %% Hosting Layer
    Hosting["Firebase Hosting + CDN"]:::hosting

    %% External Service
    GA4["Google Analytics 4"]:::external

    %% Static Assets
    index["index.html"]:::hosting
    vite["vite.config.ts"]:::hosting
    tailwind["tailwind.config.js"]:::hosting
    postcss["postcss.config.js"]:::hosting
    firebase["firebase.json"]:::hosting
    pkg["package.json"]:::hosting

    %% React SPA Layer
    subgraph "React SPA" 
        direction TB
        MainEntry["main.tsx\n(Mount React App)"]:::client
        AppShell["App.tsx\n(App Shell\n(Router, Context, Analytics Init))"]:::client
        HomePage["Home.tsx\n(Home Page Component)"]:::client
        Utils["utils.ts\n(Utility Functions)"]:::client

        subgraph "UI Components" 
            direction TB
            QDisp["QuestionDisplay.tsx"]:::client
            LangSel["LanguageSelector.tsx"]:::client
            InfoMod["InfoModal.tsx"]:::client
        end

        subgraph "Atomic UI Primitives" 
            direction TB
            uiDir["src/components/ui/"]:::client
            btn["button.tsx"]:::client
            card["card.tsx"]:::client
            dlg["dialog.tsx"]:::client
            sel["select.tsx"]:::client
            toast["toast.tsx"]:::client
            toaster["toaster.tsx"]:::client
            useToast["use-toast.ts"]:::client
        end

        subgraph "Translation Assets" 
            direction TB
            en["en.json"]:::client
            es["es.json"]:::client
            pt["pt_br.json"]:::client
        end
    end

    %% Flows
    Browser -->|"GET index.html & bundles"| Hosting
    Hosting --> Browser
    Browser -->|Bootstrap SPA| MainEntry
    MainEntry --> AppShell
    AppShell --> HomePage
    HomePage --> QDisp
    HomePage --> LangSel
    HomePage --> InfoMod
    HomePage --> UtilUtils{"utils.ts"} 
    UtilUtils --> Utils
    AppShell --> GA4
    HomePage -->|"Load translations"| en
    HomePage --> es
    HomePage --> pt

    %% Analytics calls
    AppShell -->|"Send events"| GA4

    %% Click Events
    click AppShell "https://github.com/johntheo/brokeniceberg/blob/main/src/App.tsx"
    click MainEntry "https://github.com/johntheo/brokeniceberg/blob/main/src/main.tsx"
    click HomePage "https://github.com/johntheo/brokeniceberg/blob/main/src/pages/Home.tsx"
    click QDisp "https://github.com/johntheo/brokeniceberg/blob/main/src/components/QuestionDisplay.tsx"
    click LangSel "https://github.com/johntheo/brokeniceberg/blob/main/src/components/LanguageSelector.tsx"
    click InfoMod "https://github.com/johntheo/brokeniceberg/blob/main/src/components/InfoModal.tsx"
    click uiDir "https://github.com/johntheo/brokeniceberg/tree/main/src/components/ui/"
    click btn "https://github.com/johntheo/brokeniceberg/blob/main/src/components/ui/button.tsx"
    click card "https://github.com/johntheo/brokeniceberg/blob/main/src/components/ui/card.tsx"
    click dlg "https://github.com/johntheo/brokeniceberg/blob/main/src/components/ui/dialog.tsx"
    click sel "https://github.com/johntheo/brokeniceberg/blob/main/src/components/ui/select.tsx"
    click toast "https://github.com/johntheo/brokeniceberg/blob/main/src/components/ui/toast.tsx"
    click toaster "https://github.com/johntheo/brokeniceberg/blob/main/src/components/ui/toaster.tsx"
    click useToast "https://github.com/johntheo/brokeniceberg/blob/main/src/components/ui/use-toast.ts"
    click Utils "https://github.com/johntheo/brokeniceberg/blob/main/src/lib/utils.ts"
    click en "https://github.com/johntheo/brokeniceberg/blob/main/src/assets/en.json"
    click es "https://github.com/johntheo/brokeniceberg/blob/main/src/assets/es.json"
    click pt "https://github.com/johntheo/brokeniceberg/blob/main/src/assets/pt_br.json"
    click index "https://github.com/johntheo/brokeniceberg/blob/main/index.html"
    click vite "https://github.com/johntheo/brokeniceberg/blob/main/vite.config.ts"
    click tailwind "https://github.com/johntheo/brokeniceberg/blob/main/tailwind.config.js"
    click postcss "https://github.com/johntheo/brokeniceberg/blob/main/postcss.config.js"
    click firebase "https://github.com/johntheo/brokeniceberg/blob/main/firebase.json"
    click pkg "https://github.com/johntheo/brokeniceberg/blob/main/package.json"

    %% Styles
    classDef client fill:#cce5ff,stroke:#333,stroke-width:1px
    classDef hosting fill:#d4edda,stroke:#333,stroke-width:1px
    classDef external fill:#ffe5b4,stroke:#333,stroke-width:1px
```
