# vitorsm8/brasfoot-2 architecture

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

- Interactive diagram: https://gitdiagram.com/vitorsm8/brasfoot-2
- Repository: https://github.com/vitorsm8/brasfoot-2

## Overview

##### Project type + purpose (from README + tree)
This is a **pure frontend** (no server folder) **React + TypeScript** app built with **Vite**. It’s an “AI Studio app” template that runs locally with Node tooling and requires a **`GEMINI_API_KEY`** in `.env.local`, implying the app makes calls to the **Gemini API** (Google AI) directly from the client (or via whatever AI Studio deployment runtime provides).

So the architecture is primarily:
- **Browser SPA (React/Vite)** hosting UI + domain logic
- **External LLM service (Gemini API)** called over HTTPS
- **Static build/deploy** (Vite output) rather than a traditional backend

Top-level:
- `index.html` + `vite.config.ts` + `tsconfig.json` + `package.json`: build/runtime scaffolding (Vite/TS).
- `.env.example`: environment variable contract (Gemini key).
- `metadata.json`: AI Studio/app metadata (deployment descriptor; include it as “platform config” if relevant to your audience).

`src/` indicates a single “frontend container” with internal modules:
- `main.tsx`: React entrypoint (mounts app).
- `App.tsx`: root component / app shell.
- `LiveMatchDay.tsx`: a major feature UI surface (looks like the main screen).
- `gameReducer.ts`: state management (reducer pattern).
- `engine.ts`: core “simulation/engine” logic (domain layer).
- `rng.ts`: deterministic randomness abstraction (domain utility).
- `data.ts`: static data / fixtures / seed data.
- `types.ts`: shared type contracts (domain types).
- `index.css`: styling.

- **UI layer** (React components)
- **State layer** (reducer)
- **Domain/engine layer** (engine + rng + data + types)

Goal: show “what it is” and “who/what it talks to”.
Include:
- **User** (web browser)
- **This Web App (AI Studio React SPA)**
- **Gemini API (External service)**

- User ↔ Web App (UI interactions)
- Web App → Gemini API (HTTPS requests; include “API key via env at build/runtime”)

Goal: show deployable/runtime units.
For this repo, containers are basically:
- **Browser (React SPA runtime)** — the app executes here
- **Static hosting / AI Studio hosting** (where the built assets live; optional but useful)
- **Gemini API** (external)

- Browser downloads static assets from Hosting (HTML/JS/CSS)
- Browser calls Gemini API directly (HTTPS)
Notes to label clearly:
- “No dedicated backend service in repo”
- “Secrets handling: `GEMINI_API_KEY` provided via `.env.local` / platform env injection”

##### Container: Hosting → Browser SPA → Gemini API
3. **Component (src)**: main/App/LiveMatchDay + reducer + engine + rng + data + types + Gemini integration

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% =========================
  %% Level 1 — System Context
  %% =========================
  subgraph "Level 1 — System Context"
    direction TB

    User["User"]:::external
    WebApp["AI Studio Web App (React + TypeScript SPA)"]:::container
    Gemini["Gemini API (External LLM Service)"]:::external
    EnvKey["GEMINI_API_KEY (Environment-provided secret)"]:::config

    User -->|"uses_UI_in_browser"| WebApp
    WebApp -->|"HTTPS_requests (prompt/completions)"| Gemini
    EnvKey -.->|"configures_API_access"| WebApp
  end

  %% =========================
  %% Level 2 — Container Diagram
  %% =========================
  subgraph "Level 2 — Containers (Deploy/Runtime Units)"
    direction TB

    Hosting["Static Hosting / AI Studio Runtime (serves built assets)"]:::hosting
    Browser["Browser Runtime (executes React SPA)"]:::container
    StaticAssets["Static Assets (HTML/JS/CSS from Vite build)"]:::artifact
    NoBackend["No dedicated backend service in this repo"]:::note

    Hosting -->|"serves"| StaticAssets
    StaticAssets -->|"downloaded_by"| Browser
    Browser -->|"HTTPS_calls (direct from client)"| Gemini
    NoBackend -.->|"architecture_note"| Browser
  end

  %% =========================
  %% Level 3 — Component Diagram (src/)
  %% =========================
  subgraph "Level 3 — Components (Frontend Application)"
    direction TB

    %% Tooling & configuration (build-time / platform)
    subgraph "Build / Platform Config"
      direction TB
      ViteCfg["Vite config (build + dev server)"]:::config
      TSCfg["TypeScript config"]:::config
      Pkg["Package scripts + dependencies"]:::config
      EnvExample["Environment contract (.env.example)"]:::config
      Meta["AI Studio metadata descriptor"]:::config
    end

    %% Runtime entry
    subgraph "Bootstrapping"
      direction TB
      IndexHtml["index.html (loads Vite bundle)"]:::artifact
      Main["main.tsx (mount React root)"]:::core
    end

    %% UI layer
    subgraph "UI Layer (React Components)"
      direction TB
      App["App.tsx (root app shell)"]:::ui
      Live["LiveMatchDay.tsx (primary feature screen)"]:::ui
      Css["index.css (global styling)"]:::styling
    end

    %% State layer
    subgraph "State Layer"
      direction TB
      Reducer["gameReducer.ts (state transitions/actions)"]:::state
    end

    %% Domain layer
    subgraph "Domain Layer"
      direction TB
      Engine["engine.ts (simulation / core domain logic)"]:::domain
      RNG["rng.ts (deterministic randomness)"]:::domain
      Data["data.ts (fixtures / seed data)"]:::domain
      Types["types.ts (shared type contracts)"]:::domainTypes
    end

    %% Integration layer (logical)
    subgraph "Integration Layer"
      direction TB
      GeminiClient["Gemini Client (logical module; async fetch/SDK)"]:::integration
    end

    %% Runtime flows
    IndexHtml -->|"loads_bundle"| Main
    Main -->|"renders"| App
    App -->|"composes"| Live

    Live -->|"dispatches_actions"| Reducer
    Reducer -->|"calls_domain_logic"| Engine
    Engine -->|"uses_randomness"| RNG
    Engine -->|"reads_fixtures"| Data
    Engine -->|"returns_new_state/events"| Reducer
    Reducer -->|"updates_state"| Live

    %% Async integration flow
    Live -->|"async_request"| GeminiClient
    GeminiClient -->|"HTTPS (Gemini REST/SDK)"| Gemini

    %% Styling
    Css -->|"styles"| App
    Css -->|"styles"| Live

    %% Build/config dependencies (conceptual)
    EnvExample -.->|"defines_env_contract"| GeminiClient
    ViteCfg -.->|"bundles"| IndexHtml
    TSCfg -.->|"typecheck"| Main
    Pkg -.->|"scripts/build/dev"| ViteCfg
    Meta -.->|"platform_descriptor"| Hosting

    %% Types are imported widely (conceptual)
    Types -.->|"types_imported_by"| Engine
    Types -.->|"types_imported_by"| Reducer
    Types -.->|"types_imported_by"| Live
  end

  %% =========================
  %% Click events (from component_mapping)
  %% =========================
  click IndexHtml "https://github.com/vitorsm8/brasfoot-2/blob/main/index.html"
  click Main "https://github.com/vitorsm8/brasfoot-2/blob/main/src/main.tsx"
  click App "https://github.com/vitorsm8/brasfoot-2/blob/main/src/App.tsx"
  click Live "https://github.com/vitorsm8/brasfoot-2/blob/main/src/LiveMatchDay.tsx"
  click Reducer "https://github.com/vitorsm8/brasfoot-2/blob/main/src/gameReducer.ts"
  click Engine "https://github.com/vitorsm8/brasfoot-2/blob/main/src/engine.ts"
  click RNG "https://github.com/vitorsm8/brasfoot-2/blob/main/src/rng.ts"
  click Data "https://github.com/vitorsm8/brasfoot-2/blob/main/src/data.ts"
  click Types "https://github.com/vitorsm8/brasfoot-2/blob/main/src/types.ts"
  click Css "https://github.com/vitorsm8/brasfoot-2/blob/main/src/index.css"
  click EnvExample "https://github.com/vitorsm8/brasfoot-2/blob/main/.env.example"
  click Meta "https://github.com/vitorsm8/brasfoot-2/blob/main/metadata.json"
  click ViteCfg "https://github.com/vitorsm8/brasfoot-2/blob/main/vite.config.ts"
  click TSCfg "https://github.com/vitorsm8/brasfoot-2/blob/main/tsconfig.json"
  click Pkg "https://github.com/vitorsm8/brasfoot-2/blob/main/package.json"

  %% =========================
  %% Styles
  %% =========================
  classDef external fill:#ffedd5,stroke:#c2410c,stroke-width:2px,color:#111827
  classDef container fill:#dbeafe,stroke:#1d4ed8,stroke-width:2px,color:#0b1220
  classDef hosting fill:#e0f2fe,stroke:#0369a1,stroke-width:2px,color:#0b1220
  classDef artifact fill:#f3f4f6,stroke:#6b7280,stroke-width:2px,color:#111827
  classDef config fill:#ede9fe,stroke:#6d28d9,stroke-width:2px,color:#111827
  classDef core fill:#cffafe,stroke:#0e7490,stroke-width:2px,color:#0b1220
  classDef ui fill:#bfdbfe,stroke:#1e40af,stroke-width:2px,color:#0b1220
  classDef state fill:#fce7f3,stroke:#be185d,stroke-width:2px,color:#111827
  classDef domain fill:#dcfce7,stroke:#15803d,stroke-width:2px,color:#0b1220
  classDef domainTypes fill:#ecfccb,stroke:#4d7c0f,stroke-width:2px,color:#0b1220
  classDef integration fill:#fef3c7,stroke:#b45309,stroke-width:2px,color:#111827
  classDef styling fill:#e5e7eb,stroke:#374151,stroke-width:2px,color:#111827
  classDef note fill:#fff7ed,stroke:#9a3412,stroke-width:1.5px,color:#111827,stroke-dasharray:4 3
```
