# elkofix/bioethics-hook-game architecture

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

- Interactive diagram: https://gitdiagram.com/elkofix/bioethics-hook-game
- Repository: https://github.com/elkofix/bioethics-hook-game

## Overview

##### Project type and purpose
- This is a single-page, full-stack web application built with Next.js (using the new “app” router) that leverages Firebase as a backend-as-a-service.
- Purpose: an interactive bioethics game for live presentations. The presenter controls the game via an `/admin` panel, participants vote in real time, and results are displayed on a `/results` page.

##### File structure
- Top-level config: next.config.ts, tsconfig.json, postcss.config.mjs, eslint.config.mjs.
- src/app: Next.js routes—page.tsx at root, `/admin/page.tsx`, `/results/page.tsx`.
- src/app/components: UI building blocks grouped by feature (admin, simulation, results).
- src/core/simulation: pure-TypeScript simulation logic (Entity, constants).
- src/services/simulationService.ts: wraps Firebase read/write operations.
- src/lib/firebase.ts: initializes Firebase SDK.
- public & images: static assets for welcome screen and finals.

##### README
- Describes user flows: presenter activates/deactivates game, audience votes, real-time results.
- Calls out Firebase Hosting as one target, but could also be deployed on Vercel/Netlify/GitHub Pages.
- No custom backend code—data stored in Firestore (or Realtime Database) via the Firebase SDK.

##### Main components
a. Frontend (Next.js app)
- Routes:
- `/` (welcome & play screen)
- `/admin` (presenter controls)
- `/results` (aggregated stats)
- Components: simulation UI, results charts/cards, admin control cards.
- Core simulation module (entities, constants, drawingUtils).
- simulationService: API layer to Firebase.
b. BaaS (Firebase)
- Firestore (or Realtime DB) collections:
- session state (active/inactive)
- votes (per user choice)
- SDK initialized in src/lib/firebase.ts
c. Hosting & Deployment
- Firebase Hosting / Vercel / Netlify / GitHub Pages serving the built Next.js site.
d. Users
- Presenter (admin client)
- Audience (multiple browser clients)

##### Relationships & data flow
- All browser clients load the same Next.js bundle.
- simulationService subscribes to “session active” flag in Firebase.
- When presenter toggles “Activate Game”, admin UI writes to Firestore → all clients get update.
- Audience clients write their vote to a “votes” collection.
- On “Deactivate Game”, Firestore flag flips → clients switch to final modal.
- Results page queries Firestore for vote counts and displays charts/stats.

##### Architectural patterns & principles
- Feature-based component organization (admin, simulation, results).
- Separation of concerns:
- UI components (src/app/components)
- Domain logic (src/core/simulation)
- Data/service layer (src/services)
- Infrastructure code (src/lib/firebase)
- Event-driven, real-time updates via Firebase’s pub/sub model.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Clients"
        BrowserA["Audience Browser"]:::client
        BrowserP["Presenter Browser"]:::client
    end

    subgraph "Next.js App"
        subgraph "Pages"
            Home["Home / Play Screen"]:::frontend
            AdminPage["Admin Panel"]:::frontend
            ResultsPage["Results Page"]:::frontend
        end

        subgraph "UI Components"
            GameControlCard["GameControlCard"]:::frontend
            WorldSim["WorldBoxSimulation"]:::frontend
            DrawingUtils["drawingUtils"]:::frontend
            WelcomeModal["WelcomeModal"]:::frontend
            FinalModal["FinalModal"]:::frontend
            ResultsChart["ResultsChart"]:::frontend
            ResultsList["ResultsList"]:::frontend
            StatsCards["StatsCards"]:::frontend
        end

        subgraph "Core Simulation Module"
            Entity["Entity"]:::core
            Constants["constants"]:::core
        end

        subgraph "Service Layer"
            FirebaseInit["Firebase SDK Init"]:::infra
            SimulationService["SimulationService"]:::infra
        end
    end

    subgraph "Firebase (BaaS)"
        Firestore["Firestore DB"]:::infra
    end

    Hosting["Hosting (Firebase/Vercel/Netlify)"]:::infra

    BrowserA --> NextApp
    BrowserP --> NextApp

    NextApp --> Hosting

    Home -->|loads UI| WorldSim
    Home -->|loads UI| WelcomeModal
    AdminPage -->|loads UI| GameControlCard
    ResultsPage -->|loads UI| ResultsChart
    ResultsPage -->|loads UI| ResultsList
    ResultsPage -->|loads UI| StatsCards

    WorldSim -->|uses logic| Entity
    WorldSim -->|uses logic| Constants

    SimulationService -->|reads/writes session state & votes| Firestore
    FirebaseInit --> SimulationService

    Firestore -->|real-time updates| SimulationService
    SimulationService -->|provides data| WorldSim
    SimulationService -->|provides data| ResultsChart

    Home -->|subscribes session| SimulationService
    AdminPage -->|toggles session| SimulationService
    Home -->|submits vote| SimulationService
    ResultsPage -->|fetches results| SimulationService

    click Home "https://github.com/elkofix/bioethics-hook-game/blob/main/src/app/page.tsx"
    click AdminPage "https://github.com/elkofix/bioethics-hook-game/blob/main/src/app/admin/page.tsx"
    click ResultsPage "https://github.com/elkofix/bioethics-hook-game/blob/main/src/app/results/page.tsx"
    click GameControlCard "https://github.com/elkofix/bioethics-hook-game/blob/main/src/app/components/admin/GameControlCard.tsx"
    click WorldSim "https://github.com/elkofix/bioethics-hook-game/blob/main/src/app/components/simulation/WorldBoxSimulation.tsx"
    click DrawingUtils "https://github.com/elkofix/bioethics-hook-game/blob/main/src/app/components/simulation/drawingUtils.ts"
    click WelcomeModal "https://github.com/elkofix/bioethics-hook-game/blob/main/src/app/components/simulation/ui/WelcomeModal.tsx"
    click FinalModal "https://github.com/elkofix/bioethics-hook-game/blob/main/src/app/components/simulation/ui/FinalModal.tsx"
    click ResultsChart "https://github.com/elkofix/bioethics-hook-game/blob/main/src/app/components/results/ResultsChart.tsx"
    click ResultsList "https://github.com/elkofix/bioethics-hook-game/blob/main/src/app/components/results/ResultsList.tsx"
    click StatsCards "https://github.com/elkofix/bioethics-hook-game/blob/main/src/app/components/results/StatsCards.tsx"
    click Entity "https://github.com/elkofix/bioethics-hook-game/blob/main/src/core/simulation/Entity.ts"
    click Constants "https://github.com/elkofix/bioethics-hook-game/blob/main/src/core/simulation/constants.ts"
    click FirebaseInit "https://github.com/elkofix/bioethics-hook-game/blob/main/src/lib/firebase.ts"
    click SimulationService "https://github.com/elkofix/bioethics-hook-game/blob/main/src/services/simulationService.ts"

    classDef client fill:#cce5ff,stroke:#3399ff,color:#000;
    classDef frontend fill:#e6f7ff,stroke:#66b2ff,color:#000;
    classDef core fill:#ffe6cc,stroke:#ff9933,color:#000;
    classDef infra fill:#e6ffe6,stroke:#33cc33,color:#000;
```
