# tythran/wagebait architecture

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

- Interactive diagram: https://gitdiagram.com/tythran/wagebait
- Repository: https://github.com/tythran/wagebait

## Overview

##### Project Type and Purpose
- This project is a full-stack web application built using Next.js (as seen from the "next.config.ts", directory structure under src/app with page components, and use of TypeScript/JSX files).
- Given the structure, wagebait appears to be an interactive platform—likely a game or real-time interactive session system—that includes authentication, session hosting (with dynamic session codes), joining sessions, and editing game content.

##### Analyzing the File Structure
- Top-Level Organization:
- The root contains a README and a directory called wagebait.
- The wagebait directory houses configuration files (.gitignore, package.json, tsconfig.json, etc.), public assets, and primarily the src/ folder.
- src/app Folder:
- This directory is organized into multiple subdirectories that represent distinct pages or sections: auth (for authentication and callback flows), avatar, edit (for content/game editing), host (for hosting sessions), join, login, play (with dynamic routes using [session_code]), and a global layout.
- Components and Shared Utilities:
- Under src/components there are shared UI components, for example, components to render game elements (e.g., categoryTab, game, question components) and utility components such as a loading component or bootstrap client code.
- The src/utils folder (especially src/utils/supabase) shows that Supabase is used for backend database interactions or authentication middleware, with distinct client and server utilities.
- External Backend Integration:
- The presence of a separate wagebait/supabase directory (with its own config.toml) suggests dedicated configuration for the Supabase instance, which implies that the application relies on Supabase for its database and possibly authentication/real-time features.

##### Overview of Architectural Components
a. User Interface (Frontend):
- Next.js Application: The bulk of the UI is built with Next.js using the app directory structure.
- Pages: Identify separate pages for login, authentication callback, avatar selection, and game functions (host, join, play, edit).
- Components: Include the common UI components that are used across different pages (e.g., question display, game controls, bootstrap components).
- CSS/Styling: CSS modules and global CSS (globals.css, page.module.css) reflect styling boundaries.

b. Backend / Server-Side Logic:
- Next.js API and Middleware: The app includes server-side code (e.g., in auth/callback/route.ts and middleware.ts) and integration logic for session management.

c. Database and External Services:
- Supabase Integration: Illustrate how the application communicates with the Supabase backend (authentication, database queries, and real-time data) using the utils/supabase/* code as well as configuration files in the wagebait/supabase directory.

d. Game and Session Management Components:
- Host & Play Components: Dynamic routes (e.g., host/[session_code] and play/[session_code]) that manage active gaming sessions, client-server interactions for game updates, and state management (with files like page.util.ts and various button components).
- Edit Functionality: Components for game editing (like categoryTab, game, question pages) that likely interface with the same backend to store or edit content.

##### Relationships and Interactions
- Authentication flows: Show a connection from the auth pages (login, callback) to Supabase for verifying user credentials.
- Session Management: For game sessions (host and play pages), emphasize a two-way interaction between the UI and the server logic while relaying game session data to and from Supabase.
- External Database/Storage: Represent Supabase as a central datastore that both the front-end logic (through utils/supabase) and server-side middleware interact with.

##### Architectural Patterns and Design Principles
- Next.js File-based Routing: Emphasize how dynamic routing (e.g., [session_code] directories) drives the flow for hosting and playing game sessions.
- Separation of Concerns: Distinguish between components, pages, utilities, and configuration. This separation is evident in how authentication, game play, and editing are in separate directories.
- Client-Server Collaboration: The application demonstrates how client-side components call or defer to server-side endpoints for secure operations (e.g., state mutation, database access).
- Use of Middleware: Note the inclusion of middleware.ts for handling aspects such as authentication or logging across requests.

## Diagram (Mermaid)

```mermaid
graph TD
    %% Frontend Subgraph
    subgraph "Next.js Frontend (src/app)"
        A["Frontend: Next.js (src/app)"] 
        A1["Authentication (Auth & Callback)"]
        A2["Login Page"]
        B["Avatar Selection"]
        C["Game Hosting (host/[session_code])"]
        D["Game Playing (play/[session_code])"]
        E["Game Editing Page (edit/page.tsx)"]
        F["Shared Components & UI (components)"]
        H["Global Styling (globals.css & page.module.css)"]
    end

    %% Backend & External Services Subgraph
    subgraph "Backend & Integration"
        I["Middleware & Server-Side Utils"]
        J["Supabase Service"]
    end

    %% User Interaction
    U["User"] 

    %% Connections from User to Frontend
    U -->|"Access via Browser"| A

    %% Frontend internal flow
    A --> A1
    A --> A2
    A --> B
    A --> C
    A --> D
    A --> E
    A --> F
    A --> H

    %% API calls from Frontend to Backend
    A -->|"API_Calls"| I

    %% Direct Authentication Flow
    A1 -->|"auth_check"| J

    %% Backend to External Data
    I -->|"Data_Queries"| J

    %% Styles
    %% (Global styling supports frontend, implied)

    %% Click Events
    click A "https://github.com/tythran/wagebait/tree/main/wagebait/src/app"
    click A1 "https://github.com/tythran/wagebait/tree/main/wagebait/src/app/auth"
    click A2 "https://github.com/tythran/wagebait/blob/main/wagebait/src/app/login/page.tsx"
    click B "https://github.com/tythran/wagebait/blob/main/wagebait/src/app/avatar/page.jsx"
    click C "https://github.com/tythran/wagebait/tree/main/wagebait/src/app/host/[session_code]"
    click D "https://github.com/tythran/wagebait/tree/main/wagebait/src/app/play/[session_code]"
    click E "https://github.com/tythran/wagebait/blob/main/wagebait/src/app/edit/page.tsx"
    click F "https://github.com/tythran/wagebait/tree/main/wagebait/src/components"
    click H "https://github.com/tythran/wagebait/blob/main/wagebait/src/app/globals.css"
    click I "https://github.com/tythran/wagebait/blob/main/wagebait/src/middleware.ts"
    click J "https://github.com/tythran/wagebait/tree/main/wagebait/supabase"

    %% Styles
    classDef frontend fill:#A1CEF1,stroke:#333,stroke-width:2px;
    classDef backend fill:#F8B195,stroke:#333,stroke-width:2px;
    classDef external fill:#CFF09E,stroke:#333,stroke-width:2px;

    class A,A1,A2,B,C,D,E,F,H frontend;
    class I backend;
    class J external;
```
