How vitorsm8/brasfoot-2 works
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