# tensho1026/gitrpg architecture

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

- Interactive diagram: https://gitdiagram.com/tensho1026/gitrpg
- Repository: https://github.com/tensho1026/gitrpg

## Overview

##### Project type and purpose
- Git-RPG is a full-stack Next.js application that gamifies GitHub commit activity.
- Frontend and backend live in the same Next.js “app” directory, using Server Actions for data mutations and queries.
- External services: GitHub GraphQL API for commit data, Supabase for persistence, NextAuth for authentication.

##### File structure
- Top‐level “src/app” holds Next.js routes and React UI components for pages (home, avatar, item, grass, battle, auth).
- “src/actions” contains business‐logic modules (server actions) grouped by domain: github, user, item.
- “src/lib” holds utility code (session store, leveling, common helpers).
- “src/supabase/supabase.config.ts” configures the Supabase client.
- “src/types” defines TypeScript types.
- Presence of NextAuth config, API routes under “src/app/api/auth/[...nextauth]” indicates a built‐in auth layer.

##### Main components
- Browser (React/Next.js client)
- Next.js server (Server Actions + API routes)
- Authentication service (NextAuth + session store)
- Supabase database
- GitHub GraphQL API
- CDN/public assets

##### Relationships and interactions
- The Browser sends page requests to Next.js.
- Next.js renders pages (SSR/SSG) and invokes Server Actions or API routes for data.
- Server Actions call:
- GitHub GraphQL API to fetch commit counts and history
- Supabase to read/write user profiles, coins, XP, avatars, items
- NextAuth manages OAuth handshakes with GitHub, stores sessions in Supabase (or in-memory store).
- The Browser fetches JSON via built-in fetch wrappers or React hooks (useHomeData, useAvatarData, etc.).

##### Architectural patterns and design principles
- Layered architecture: Presentation (React pages) → Application logic (Server Actions) → Data access (Supabase, GitHub API).
- Domain separation in “src/actions” by feature (user, item, github) follows a Clean Architecture approach.
- File-system-based routing in Next.js organizes UI and API side by side.
- Hooks in “src/app/*/hooks” encapsulate data fetching logic for components.

##### Detail but keep clarity
- Key components: individual pages (home, avatar, item, grass, battle), shared UI libs, feature‐specific actions, Supabase, GitHub API, NextAuth.
- How data flows end-to-end: from user action in UI through business logic to persistence and back.
- Architectural principles: separation of concerns, domain grouping, external integrations.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Frontend Layer
    subgraph "Browser (React/Next.js Client UI)"
        direction TB
        Page["page.tsx"]:::frontend
        Layout["layout.tsx"]:::frontend
        HomePage["Home Page (src/app/home/page.tsx)"]:::frontend
        HomeComponents["Home Components"]:::frontend
        HomeHooks["Home Hooks"]:::frontend
        AvatarPage["Avatar Page (src/app/avatar/page.tsx)"]:::frontend
        AvatarComponents["Avatar Components"]:::frontend
        AvatarHooks["Avatar Hooks"]:::frontend
        ItemPage["Item Page (src/app/item/page.tsx)"]:::frontend
        ItemComponents["Item Components"]:::frontend
        ItemHooks["Item Hooks"]:::frontend
        GrassPage["Grass Page (src/app/grass/page.tsx)"]:::frontend
        GrassComponents["Grass Components"]:::frontend
        GrassHooks["Grass Hooks"]:::frontend
        BattlePage["Battle Page (src/app/battle/page.tsx)"]:::frontend
        BattleComponents["Battle Components"]:::frontend
        BattleHooks["Battle Hooks"]:::frontend
        AuthPage["Auth Page (src/app/auth/page.tsx)"]:::frontend
        AuthUIComponents["Auth UI Components"]:::frontend
        SharedUI["Shared UI"]:::frontend
    end

    %% Server Layer
    subgraph "Next.js Server (Server Actions & API Routes)"
        direction TB
        subgraph "Server Actions"
            direction TB
            GitHubActions["GitHub Actions"]:::backend
            UserActions["User Actions"]:::backend
            ItemActions["Item Actions"]:::backend
        end
        subgraph "API Routes"
            direction TB
            NextAuthRoute["NextAuth API Route"]:::backend
            ReadmeRoute["Readme API Route"]:::backend
        end
    end

    %% Authentication Service
    subgraph "Authentication Service (NextAuth & Session Store)"
        direction TB
        AuthOptions["Auth Options"]:::backend
        SessionStore["Session Store"]:::backend
        SessionHook["useSessionStatus Hook"]:::backend
        NextAuthTypes["NextAuth Types"]:::backend
    end

    %% Utilities & Types
    subgraph "Utilities & Types"
        direction TB
        UtilsFile["utils.ts"]:::backend
        LevelingFile["leveling.ts"]:::backend
        TypesAvatar["Avatar Types"]:::backend
        TypesEquipment["Equipment Types"]:::backend
        TypesUser["User Types"]:::backend
    end

    %% Data Layer
    subgraph "Persistence Layer"
        direction TB
        SupabaseConfig["Supabase Config"]:::database
        SupabaseDB["Supabase Database"]:::database
    end

    subgraph "External Services"
        direction TB
        GitHubAPI["GitHub GraphQL API"]:::external
        CDN["Public Assets (CDN)"]:::external
    end

    %% Connections: Frontend to Server
    Page -->|"SSR/SSG"| GitHubActions
    HomePage -->|"useHomeData()"| UserActions
    HomeHooks -->|"hooks invoke"| UserActions
    HomeComponents -->|"UI renders"| UserActions
    AvatarPage -->|"useAvatarData()"| UserActions
    AvatarHooks -->|"hooks invoke"| UserActions
    AvatarComponents -->|"UI renders"| UserActions
    ItemPage -->|"useItemData()"| ItemActions
    ItemHooks -->|"hooks invoke"| ItemActions
    ItemComponents -->|"UI renders"| ItemActions
    GrassPage -->|"useGrassData()"| GitHubActions
    GrassHooks -->|"hooks invoke"| GitHubActions
    GrassComponents -->|"UI renders"| GitHubActions
    BattlePage -->|"useBattleData()"| GitHubActions
    BattleHooks -->|"hooks invoke"| GitHubActions
    BattleComponents -->|"UI renders"| GitHubActions
    AuthPage -->|"login/logout"| NextAuthRoute
    AuthUIComponents -->|"UI renders"| NextAuthRoute
    SharedUI -->|"common UI libs"| GitHubActions

    %% Server Actions to Data
    UserActions -->|"READ/WRITE user_status"| SupabaseDB
    ItemActions -->|"READ/WRITE items"| SupabaseDB
    GitHubActions -->|"fetchCommits()"| GitHubAPI
    GitHubActions -->|"UPDATE commit_records"| SupabaseDB

    %% Auth flows
    NextAuthRoute -->|"issue session"| SessionStore
    SessionStore -->|"store session"| SupabaseDB
    AuthOptions -->|"configures"| NextAuthRoute
    SessionHook -->|"reads status"| SessionStore
    NextAuthTypes -->|"type defs"| NextAuthRoute

    %% Utility usage
    GitHubActions -->|"use helpers"| UtilsFile
    GitHubActions -->|"use leveling"| LevelingFile
    UserActions -->|"use utils"| UtilsFile
    ItemActions -->|"use utils"| UtilsFile

    %% Type usage
    UserActions -->|"types"| TypesUser
    ItemActions -->|"types"| TypesEquipment
    AvatarPage -->|"types"| TypesAvatar

    %% Legend
    subgraph Legend
        direction TB
        F["Frontend (Blue)"]:::frontend
        B["Backend (Green)"]:::backend
        D["Database (Orange)"]:::database
        E["External (Purple)"]:::external
    end

    %% Click Events
    click Page "https://github.com/tensho1026/gitrpg/blob/main/src/app/page.tsx"
    click Layout "https://github.com/tensho1026/gitrpg/blob/main/src/app/layout.tsx"
    click HomePage "https://github.com/tensho1026/gitrpg/blob/main/src/app/home/page.tsx"
    click HomeComponents "https://github.com/tensho1026/gitrpg/tree/main/src/app/home/components"
    click HomeHooks "https://github.com/tensho1026/gitrpg/tree/main/src/app/home/hooks"
    click AvatarPage "https://github.com/tensho1026/gitrpg/blob/main/src/app/avatar/page.tsx"
    click AvatarComponents "https://github.com/tensho1026/gitrpg/tree/main/src/app/avatar/components"
    click AvatarHooks "https://github.com/tensho1026/gitrpg/tree/main/src/app/avatar/hooks"
    click ItemPage "https://github.com/tensho1026/gitrpg/blob/main/src/app/item/page.tsx"
    click ItemComponents "https://github.com/tensho1026/gitrpg/tree/main/src/app/item/components"
    click ItemHooks "https://github.com/tensho1026/gitrpg/tree/main/src/app/item/hooks"
    click GrassPage "https://github.com/tensho1026/gitrpg/blob/main/src/app/grass/page.tsx"
    click GrassComponents "https://github.com/tensho1026/gitrpg/tree/main/src/app/grass/components"
    click GrassHooks "https://github.com/tensho1026/gitrpg/tree/main/src/app/grass/hooks"
    click BattlePage "https://github.com/tensho1026/gitrpg/blob/main/src/app/battle/page.tsx"
    click BattleComponents "https://github.com/tensho1026/gitrpg/tree/main/src/app/battle/components"
    click BattleHooks "https://github.com/tensho1026/gitrpg/tree/main/src/app/battle/hooks"
    click AuthPage "https://github.com/tensho1026/gitrpg/blob/main/src/app/auth/page.tsx"
    click AuthUIComponents "https://github.com/tensho1026/gitrpg/tree/main/src/app/auth/components"
    click SharedUI "https://github.com/tensho1026/gitrpg/tree/main/src/app/components"
    click GitHubActions "https://github.com/tensho1026/gitrpg/tree/main/src/actions/github"
    click UserActions "https://github.com/tensho1026/gitrpg/tree/main/src/actions/user"
    click ItemActions "https://github.com/tensho1026/gitrpg/tree/main/src/actions/item"
    click NextAuthRoute "https://github.com/tensho1026/gitrpg/blob/main/src/app/api/auth/[...nextauth]/route.ts"
    click ReadmeRoute "https://github.com/tensho1026/gitrpg/blob/main/src/app/api/readme/[name]/route.ts"
    click AuthOptions "https://github.com/tensho1026/gitrpg/blob/main/src/app/utils/authOptions.ts"
    click SessionStore "https://github.com/tensho1026/gitrpg/blob/main/src/lib/sessionStore.ts"
    click SessionHook "https://github.com/tensho1026/gitrpg/blob/main/src/lib/useSessionStatus.ts"
    click NextAuthTypes "https://github.com/tensho1026/gitrpg/blob/main/src/types/next-auth.d.ts"
    click UtilsFile "https://github.com/tensho1026/gitrpg/blob/main/src/lib/utils.ts"
    click LevelingFile "https://github.com/tensho1026/gitrpg/blob/main/src/lib/leveling.ts"
    click TypesAvatar "https://github.com/tensho1026/gitrpg/tree/main/src/types/avatar"
    click TypesEquipment "https://github.com/tensho1026/gitrpg/tree/main/src/types/equipment"
    click TypesUser "https://github.com/tensho1026/gitrpg/tree/main/src/types/user"
    click SupabaseConfig "https://github.com/tensho1026/gitrpg/blob/main/src/supabase/supabase.config.ts"
    click CDN "https://github.com/tensho1026/gitrpg/tree/main/public/"
    click GitHubAPI "https://github.com/tensho1026/gitrpg/blob/main/src/actions/github/fetchCommits.ts"

    %% Styles
    classDef frontend fill:#e0f7fa,stroke:#006064,color:#004d40
    classDef backend fill:#e8f5e9,stroke:#1b5e20,color:#1b5e20
    classDef database fill:#fff3e0,stroke:#e65100,color:#bf360c
    classDef external fill:#f3e5f5,stroke:#4a148c,color:#4a148c
```
