# brandon-carlisle/stadiumguessr architecture

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

- Interactive diagram: https://gitdiagram.com/brandon-carlisle/stadiumguessr
- Repository: https://github.com/brandon-carlisle/stadiumguessr

## Overview

##### Main Components

A. Frontend Layer:
- Next.js Application (React)
- Components Structure:
- Game Components (src/components/game/*)
- UI Components (src/components/ui/*)
- Pages Structure (src/pages/*)
- State Management:
- Redux Store (src/store/*)
- Sound Context (src/store/sound-context.tsx)

B. Backend Layer:
- tRPC API (src/server/api/*)
- Authentication System (NextAuth.js)
- Routers:
- Match Router
- Stadium Router

C. Database Layer:
- Prisma ORM
- Database Schema (defined in prisma/schema.prisma)

**[Client Layer] → [API Layer] → [Data Layer]**

##### Key Flows to Highlight

A. Game Flow:
- User Authentication Flow
- Game Session Management
- Stadium Data Retrieval
- Answer Validation
- Score Tracking

B. Data Flow:
- tRPC API Communications
- Database Interactions
- State Management Updates

##### Important Architectural Patterns

- Next.js Pages Router Architecture
- tRPC API Structure
- Redux State Management Flow
- Authentication Flow with NextAuth.js

##### Integration Points

- Integration with:
- NextAuth.js for authentication
- Prisma for database operations
- Leaflet for map functionality (src/components/game/leaflet-map.tsx)
- Sound system integration

##### Additional Elements

Specific features in separate sections:
- Game Logic Components
- User Management
- Match History
- Admin Functions (from admin.tsx)
- Sound Management System

##### Specific Implementation Details

Relationship between:
- Game state management (src/store/features/game)
- API routes (src/server/api/routers)
- Database schema
- Frontend components

Remember to emphasize the real-time nature of the game mechanics and how the frontend components interact with the backend services through tRPC, while maintaining a clean separation of concerns between the game logic, user interface, and data management layers.

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph Client
        NextApp["Next.js Application"]:::frontend
        click NextApp "https://github.com/brandon-carlisle/StadiumGuessr/tree/main/src/pages"
        
        subgraph GameComponents["Game Components"]
            GameInterface["Game Interface"]:::frontend
            click GameInterface "https://github.com/brandon-carlisle/StadiumGuessr/blob/main/src/components/game/game.tsx"
            LeafletMap["Map Component"]:::frontend
            click LeafletMap "https://github.com/brandon-carlisle/StadiumGuessr/blob/main/src/components/game/leaflet-map.tsx"
            AnswerInput["Answer Interface"]:::frontend
            click AnswerInput "https://github.com/brandon-carlisle/StadiumGuessr/blob/main/src/components/game/answer-input.tsx"
            GameControls["Game Controls"]:::frontend
            click GameControls "https://github.com/brandon-carlisle/StadiumGuessr/blob/main/src/components/game/game-controls.tsx"
        end

        subgraph UIComponents["UI Components"]
            AuthButton["Auth Button"]:::frontend
            click AuthButton "https://github.com/brandon-carlisle/StadiumGuessr/blob/main/src/components/ui/auth-button.tsx"
            Spinner["Loading States"]:::frontend
            click Spinner "https://github.com/brandon-carlisle/StadiumGuessr/blob/main/src/components/ui/spinner.tsx"
            SoundControls["Sound Controls"]:::frontend
            click SoundControls "https://github.com/brandon-carlisle/StadiumGuessr/blob/main/src/components/ui/toggle-sound.tsx"
        end

        subgraph StateManagement["State Management"]
            ReduxStore["Redux Store"]:::state
            click ReduxStore "https://github.com/brandon-carlisle/StadiumGuessr/blob/main/src/store/store.ts"
            GameState["Game State"]:::state
            click GameState "https://github.com/brandon-carlisle/StadiumGuessr/blob/main/src/store/features/game/game-slice.ts"
            SoundContext["Sound Context"]:::state
            click SoundContext "https://github.com/brandon-carlisle/StadiumGuessr/blob/main/src/store/sound-context.tsx"
        end

        subgraph Pages["Pages"]
            PlayPage["Play Page"]:::frontend
            click PlayPage "https://github.com/brandon-carlisle/StadiumGuessr/blob/main/src/pages/play.tsx"
            AdminPage["Admin Interface"]:::frontend
            click AdminPage "https://github.com/brandon-carlisle/StadiumGuessr/blob/main/src/pages/admin.tsx"
            MatchSummary["Match Summary"]:::frontend
            click MatchSummary "https://github.com/brandon-carlisle/StadiumGuessr/blob/main/src/pages/summary/[matchId]/index.tsx"
            UserProfile["User Profile"]:::frontend
            click UserProfile "https://github.com/brandon-carlisle/StadiumGuessr/blob/main/src/pages/user/[userId]/index.tsx"
        end
    end

    subgraph APILayer["API Layer"]
        TRPC["tRPC Setup"]:::api
        click TRPC "https://github.com/brandon-carlisle/StadiumGuessr/blob/main/src/server/api/trpc.ts"
        APIRoot["API Root"]:::api
        click APIRoot "https://github.com/brandon-carlisle/StadiumGuessr/blob/main/src/server/api/root.ts"
        
        subgraph Routers["API Routers"]
            MatchRouter["Match Router"]:::api
            click MatchRouter "https://github.com/brandon-carlisle/StadiumGuessr/blob/main/src/server/api/routers/match.ts"
            StadiumRouter["Stadium Router"]:::api
            click StadiumRouter "https://github.com/brandon-carlisle/StadiumGuessr/blob/main/src/server/api/routers/stadium.ts"
        end

        subgraph Auth["Authentication"]
            NextAuth["NextAuth.js"]:::auth
            click NextAuth "https://github.com/brandon-carlisle/StadiumGuessr/blob/main/src/pages/api/auth/[...nextauth].ts"
            AuthUtils["Auth Utilities"]:::auth
            click AuthUtils "https://github.com/brandon-carlisle/StadiumGuessr/blob/main/src/server/auth.ts"
        end

        subgraph GameLogic["Game Logic"]
            AnswerValidation["Answer Validation"]:::logic
            click AnswerValidation "https://github.com/brandon-carlisle/StadiumGuessr/blob/main/src/utils/validate-answer.ts"
            StadiumManagement["Stadium Management"]:::logic
            click StadiumManagement "https://github.com/brandon-carlisle/StadiumGuessr/blob/main/src/utils/shuffle-stadiums.ts"
            GameHook["Game Hook"]:::logic
            click GameHook "https://github.com/brandon-carlisle/StadiumGuessr/blob/main/src/hooks/useGame.ts"
        end
    end

    subgraph DataLayer["Data Layer"]
        PrismaORM["Prisma ORM"]:::database
        DBSchema["Database Schema"]:::database
        click DBSchema "https://github.com/brandon-carlisle/StadiumGuessr/blob/main/prisma/schema.prisma"
        DBConnection["Database Connection"]:::database
        click DBConnection "https://github.com/brandon-carlisle/StadiumGuessr/blob/main/src/server/db.ts"
    end

    %% Connections
    NextApp --> GameComponents
    NextApp --> UIComponents
    NextApp --> StateManagement
    NextApp --> Pages
    
    GameComponents --> StateManagement
    UIComponents --> StateManagement
    Pages --> StateManagement
    
    StateManagement --> TRPC
    TRPC --> APIRoot
    APIRoot --> Routers
    APIRoot --> Auth
    
    Routers --> GameLogic
    GameLogic --> PrismaORM
    PrismaORM --> DBSchema
    PrismaORM --> DBConnection

    %% Styles
    classDef frontend fill:#3498db,stroke:#2980b9,color:white
    classDef api fill:#2ecc71,stroke:#27ae60,color:white
    classDef auth fill:#f1c40f,stroke:#f39c12,color:black
    classDef database fill:#9b59b6,stroke:#8e44ad,color:white
    classDef state fill:#e74c3c,stroke:#c0392b,color:white
    classDef logic fill:#1abc9c,stroke:#16a085,color:white

    %% Legend
    subgraph Legend
        Frontend["Frontend Component"]:::frontend
        API["API Component"]:::api
        Auth["Auth Component"]:::auth
        Database["Database Component"]:::database
        State["State Management"]:::state
        Logic["Game Logic"]:::logic
    end
```
