# chimmykk/light-games architecture

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

- Interactive diagram: https://gitdiagram.com/chimmykk/light-games
- Repository: https://github.com/chimmykk/light-games

## Overview

##### Project type and purpose
- This is a full-stack, server-rendered Next.js application (“Light Game”) that lets end users generate, play, and share lightweight AI-powered games.
- It combines a React/Next.js frontend (app directory) with serverless API routes (app/api/*), a MongoDB database (Mongoose models), authentication (NextAuth.js), and external AI services for game generation.

##### File structure
- Top-level “app/” directory:
- page.tsx, layout.tsx, CSS, SessionProvider.tsx → React pages, global layout, session management
- app/api/*/route.ts → Next.js Serverless API endpoints (auth, game CRUD, generation, prompt-nicer, retry, etc.)
- app/explore, my-creations, p, play → feature pages
- “components/” directory:
- feature components (ExploreButton, project-generation)
- “ui/” subfolder: atomic, reusable UI primitives (buttons, dialogs, inputs, etc.)
- “lib/” for utilities and Zustand store
- “hooks/” for custom React hooks (mobile detection, toast)
- “models/” for Mongoose schemas and dbConnect
- Config files for Tailwind, Next.js, pnpm, TypeScript

##### README insights
- Confirms tech stack: Next.js, pnpm, MongoDB/Mongoose, Zustand, NextAuth.js, Tailwind, next-themes, lucide-react.
- Describes API endpoints and their responsibilities (game HTML generation, save, fetch, improve, retry).

a. Main components
- Client (Browser / Mobile)
– Next.js React UI (pages + components)
– Zustand store (lib/store.ts)
– ThemeProvider (next-themes)
– SessionProvider (NextAuth)
- Next.js Server (Serverless Functions)
– API layer (app/api/*)
– Server actions (app/actions.ts for saving to DB)
– Authentication (NextAuth.js handlers under api/auth)
- Business Logic
– Prompt enhancement (makeit-nicer, promptnicer)
- Database
– MongoDB Atlas (Mongoose models: GameData, Pets; dbConnect)
- External Services
– Optional: OAuth providers via NextAuth
- Static Assets & CDN
– public/ folder (images, placeholders)

b. Relationships and data flows
1. User requests page → Next.js SSR/SSG → HTML/CSS/JS returns to client
2. Client actions (e.g., “Generate Game”) → fetch(“/api/generate-game”)
3. API route handler calls AI service → receives game code/HTML
4. Client may call “/api/save-game” → server action writes to MongoDB
5. On “Play” pages: client fetches game data via “/api/games/[gameId]” → renders
6. Authentication flows: client uses SessionProvider → NextAuth API → issues session cookie/JWT → secure endpoints

c. Architectural patterns and design principles
- Monolithic serverless architecture (Next.js app + API in one codebase)
- Atomic component design (UI primitives under components/ui)
- Server Actions (Next.js 13 App Router) for direct server-side DB writes
- React hooks and global state (Zustand) to decouple UI from data-fetching logic
- Separation of concerns: UI / state / API / data models / external integrations

d. Key technologies to annotate
- Next.js 13 App Router
- React (TSX components)
- NextAuth.js (authentication)
- Tailwind CSS (styling)
- Zustand (state management)
- Mongoose + MongoDB

##### Capturing all critical elements
- Don’t forget the SessionProvider / NextAuth flow.
- Both “core” game-generation endpoints and “utility” endpoints (promptnicer, retry).
- Mongoose models and dbConnect as part of the data access layer.
- Component library (components/ui) as part of the frontend but note reusability.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Frontend Layer
    subgraph "Frontend (Browser)"
        direction TB
        UI["Next.js UI"]:::frontend
        SP["SessionProvider"]:::frontend
        TP["ThemeProvider"]:::frontend
        ZS["Zustand Store"]:::frontend
        UT["Utils (lib/utils.ts)"]:::frontend
        FC["Feature Components"]:::frontend
        UP["UI Primitives (components/ui)"]:::frontend
        HK["Custom Hooks"]:::frontend
        SA["Static Assets (public/)"]:::frontend
    end

    %% Backend Layer
    subgraph "Backend (Next.js Serverless)"
        direction TB
        subgraph "API Layer"
            direction TB
            AUTH["Auth API /api/auth/[...nextauth]"]:::server
            GEN["Generate Game /api/generate-game"]:::server
            NICER1["MakeItNicer /api/makeit-nicer"]:::server
            NICER2["PromptNicer /api/promptnicer"]:::server
            RETRY["Retry /api/retry"]:::server
            SAVE["Save Game /api/save-game"]:::server
            FETCHALL["FetchAllGames /api/fetchallgames"]:::server
            CRUDROOT["Games CRUD /api/games"]:::server
            CRUDID["Game CRUD /api/games/[gameId]"]:::server
            GETONE["GetGameData /api/getGameData"]:::server
            TEST["Test Simple /api/test-simple"]:::server
        end
        SACTIONS["Server Actions (app/actions.ts)"]:::server
        subgraph "Data Access Layer"
            direction TB
            DBCONN["dbConnect"]:::server
            MODEL1["GameData Model"]:::server
            MODEL2["Pets Model"]:::server
            DB["MongoDB Atlas"]:::db
        end
        EXTSVC["External AI/Shapes API"]:::external
    end

    %% Relationships
    UI -->|"fetch /api/generate-game"| GEN
    UI -->|"fetch /api/save-game"| SAVE
    UI -->|"fetch /api/fetchallgames"| FETCHALL
    UI -->|"fetch /api/games/[gameId] or /api/getGameData"| CRUDID
    UI -->|"uses"| ZS
    UI -->|"uses"| HK
    UI -->|"wraps with"| SP
    UI -->|"wraps with"| TP
    UI -->|"imports"| UP
    FC -->|"components in UI"| UI

    GEN -->|"calls"| EXTSVC
    NICER1 -->|"calls"| EXTSVC
    NICER2 -->|"calls"| EXTSVC
    RETRY -->|"calls"| EXTSVC

    SAVE -->|"calls"| SACTIONS
    SACTIONS -->|"writes using"| DBCONN
    SACTIONS -->|"uses models"| MODEL1
    SACTIONS -->|"uses models"| MODEL2
    CRUDROOT -->|"reads/writes"| DBCONN
    CRUDID -->|"reads/writes"| DBCONN
    GETONE -->|"reads"| DBCONN
    FETCHALL -->|"reads"| DBCONN

    DBCONN -->|"connects to"| DB
    MODEL1 -->|"schema in"| DB
    MODEL2 -->|"schema in"| DB

    UI -->|"auth flows"| AUTH
    AUTH -->|"issues session"| SP

    %% Click Events
    click UI "https://github.com/chimmykk/light-games/blob/main/app/layout.tsx"
    click UI "https://github.com/chimmykk/light-games/blob/main/app/page.tsx"
    click UI "https://github.com/chimmykk/light-games/blob/main/app/globals.css"
    click UI "https://github.com/chimmykk/light-games/blob/main/app/lightgame-interface.tsx"
    click UI "https://github.com/chimmykk/light-games/blob/main/app/explore/page.tsx"
    click UI "https://github.com/chimmykk/light-games/blob/main/app/my-creations/page.tsx"
    click UI "https://github.com/chimmykk/light-games/blob/main/app/p/[gameId]/page.tsx"
    click UI "https://github.com/chimmykk/light-games/blob/main/app/play/[gameid]/page.tsx"
    click SP "https://github.com/chimmykk/light-games/blob/main/app/SessionProvider.tsx"
    click TP "https://github.com/chimmykk/light-games/blob/main/components/theme-provider.tsx"
    click ZS "https://github.com/chimmykk/light-games/blob/main/lib/store.ts"
    click UT "https://github.com/chimmykk/light-games/blob/main/lib/utils.ts"
    click FC "https://github.com/chimmykk/light-games/blob/main/components/ExploreButton.tsx"
    click FC "https://github.com/chimmykk/light-games/blob/main/components/project-generation.tsx"
    click FC "https://github.com/chimmykk/light-games/blob/main/components/mycreation.tsx"
    click UP "https://github.com/chimmykk/light-games/tree/main/components/ui"
    click HK "https://github.com/chimmykk/light-games/blob/main/hooks/use-mobile.tsx"
    click HK "https://github.com/chimmykk/light-games/blob/main/hooks/use-toast.tsx"
    click SA "https://github.com/chimmykk/light-games/tree/main/public/"

    click SACTIONS "https://github.com/chimmykk/light-games/blob/main/app/actions.ts"
    click AUTH "https://github.com/chimmykk/light-games/blob/main/app/api/auth/[...nextauth]/route.ts"
    click GEN "https://github.com/chimmykk/light-games/blob/main/app/api/generate-game/route.ts"
    click NICER1 "https://github.com/chimmykk/light-games/blob/main/app/api/makeit-nicer/route.ts"
    click NICER2 "https://github.com/chimmykk/light-games/blob/main/app/api/promptnicer/route.ts"
    click RETRY "https://github.com/chimmykk/light-games/blob/main/app/api/retry/route.ts"
    click SAVE "https://github.com/chimmykk/light-games/blob/main/app/api/save-game/route.ts"
    click FETCHALL "https://github.com/chimmykk/light-games/blob/main/app/api/fetchallgames/route.ts"
    click CRUDROOT "https://github.com/chimmykk/light-games/blob/main/app/api/games/route.ts"
    click CRUDID "https://github.com/chimmykk/light-games/blob/main/app/api/games/[gameId]/route.ts"
    click GETONE "https://github.com/chimmykk/light-games/blob/main/app/api/getGameData/route.ts"
    click TEST "https://github.com/chimmykk/light-games/blob/main/app/api/test-simple/route.ts"
    click DBCONN "https://github.com/chimmykk/light-games/blob/main/models/dbConnect.ts"
    click MODEL1 "https://github.com/chimmykk/light-games/blob/main/models/GameData.ts"
    click MODEL2 "https://github.com/chimmykk/light-games/blob/main/models/Pets.ts"

    %% Styles
    classDef frontend fill:#bae1ff,stroke:#000,stroke-width:1px
    classDef server fill:#b7f0a6,stroke:#000,stroke-width:1px
    classDef db fill:#ffd699,stroke:#000,stroke-width:1px
    classDef external fill:#ffb3b3,stroke:#000,stroke-width:1px
```
