# kirniy/coinmania architecture

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

- Interactive diagram: https://gitdiagram.com/kirniy/coinmania
- Repository: https://github.com/kirniy/coinmania

## Overview

##### Project type and purpose
- This is a full-stack React/TypeScript web application built on Next.js (App Router).
- It serves both a browser-rendered UI (pages under src/app and components) and a backend API (Route Handlers under src/app/api).
- It uses Supabase as its database/auth service, Redux for client state, and custom contexts/hooks for UI logic.

##### File structure
- Top-level config: next.config.mjs, tsconfig.json, tailwind.config.ts, postcss.config.mjs
- Public assets in public/ (images, static files)
- App entry in src/app/: layout.tsx, page.tsx, nested routes (bonus, game, profile, stub)
- API routes in src/app/api/* (auth, user, tasks, slot, util, etc.), each with its own route.ts
- UI components in src/components/ (common widgets, modal, popup, screens subfolders)
- Styling: global SCSS (globals.scss), CSS Modules next to components
- State: Redux slices in src/store/, contexts in src/app/context/
- Data layer: supabase client in src/db/supabase.ts
- Helpers and utils under src/helpers/ and src/utils/
- Type definitions in src/types/ and global.d.ts

##### README
- Confirms Next.js App Router setup, next/font usage, Vercel deployment.
- No custom microservices or external APIs beyond Supabase.

##### Main components & interactions
A. Browser (Client)
- Renders pages via Next.js (SSR/SSG or client-side)
- Loads React components, CSS, JS bundles
- Interacts with Next.js API endpoints and the Redux store/context

B. Next.js Application (Server & Build)
1. App Router (UI Layer)
– src/app/layout.tsx, nested page.tsx files
– global providers (Redux <Provider>, custom contexts)
– dynamic/static rendering, ISR paths if any
2. API Layer (Backend)
– src/app/api/**/*/route.ts
– Organized by domain (auth, user, tasks, slot, util, etc.)
– Handles HTTP requests, validates, applies business logic
3. Data Access
– supabase client in src/db/supabase.ts
– Queries/Mutations to Supabase (Postgres)
4. Build & Dev Tooling
– next.config.mjs for routing, env vars, custom webpack
– tailwind.config.ts + postcss.config.mjs for styling
– Typescript config

C. External Services
- Supabase (Database + Auth)
- Vercel (Hosting & CDN)

##### Relationships & data flow
- Clients request pages → Next.js App Router serves pre-rendered or dynamically rendered pages with data fetched from Supabase.
- Client-side hydration kicks in → React takes over, uses Redux store or contexts to manage in-app state.
- Components invoke API Layer endpoints (fetch/axios) → Next.js Route Handlers process requests, read/write Supabase, return JSON.
- API responses update Redux store or local state, UI updates.

##### Architectural patterns & design principles
- Monolithic full-stack framework leveraging Next.js App Router (file-system routing).
- Domain-partitioned API routes (grouped by feature).
- Separation of concerns:
- UI components under src/components and screens
- State management in Redux slices & React contexts
- Data logic centralized in supabase client
- Type safety end-to-end with TypeScript

##### Essential architectural elements
- Do not overcomplicate with every small helper or util—group them under “Helpers/Utils” if needed.
- Split between frontend (App Router + Components) and backend (API routes).
- Middleware of Redux/context providers as part of the UI Layer.
- That Supabase is both DB and Auth provider.
- If desired, annotate that assets and static files are served from public/ via Vercel CDN.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Clients
    Browser["Browser (Client)"]:::external
    Browser -->|"HTTP GET/SSR & Hydration"| UI_Layer

    %% Next.js Application
    subgraph "Next.js App"
        direction TB

        %% UI Layer
        subgraph "UI Layer" 
            direction TB
            AppRouter["App Router (src/app/)"]:::ui
            Providers["Global Providers (src/app/providers/)"]:::ui
            Contexts["React Contexts (src/app/context/)"]:::ui
            ReduxStore["Redux Store (src/store/)"]:::ui
            Components["UI Components (src/components/)"]:::ui
            PublicAssets["Public Assets (public/)"]:::ui
        end

        %% API Layer
        subgraph "API Layer"
            direction TB
            APIRoutes["API Route Handlers (src/app/api/)"]:::api
        end

        %% Data Access
        subgraph "Data Access"
            direction TB
            SupabaseClient["Supabase Client (src/db/supabase.ts)"]:::data
        end
    end

    %% External Services
    Supabase["Supabase (Database & Auth)"]:::external
    Vercel["Vercel (Hosting & CDN)"]:::external

    %% Data Flows
    UI_Layer -->|"fetch('/api/*')"| APIRoutes
    APIRoutes -->|"SQL queries/auth calls"| SupabaseClient
    SupabaseClient -->|"SQL/REST"| Supabase
    Supabase -->|"JSON responses"| APIRoutes
    APIRoutes -->|"JSON responses"| UI_Layer
    Vercel -.-> PublicAssets

    %% Click Events
    click AppRouter "https://github.com/kirniy/coinmania/tree/main/src/app/"
    click Providers "https://github.com/kirniy/coinmania/tree/main/src/app/providers/"
    click Contexts "https://github.com/kirniy/coinmania/tree/main/src/app/context/"
    click ReduxStore "https://github.com/kirniy/coinmania/tree/main/src/store/"
    click Components "https://github.com/kirniy/coinmania/tree/main/src/components/"
    click PublicAssets "https://github.com/kirniy/coinmania/tree/main/public/"
    click APIRoutes "https://github.com/kirniy/coinmania/tree/main/src/app/api/"
    click SupabaseClient "https://github.com/kirniy/coinmania/blob/main/src/db/supabase.ts"

    %% Styles
    classDef ui fill:#D6EFFF,stroke:#0366d6,color:#0366d6;
    classDef api fill:#E6FFDD,stroke:#2C662D,color:#2C662D;
    classDef data fill:#FFF4D6,stroke:#A66E00,color:#A66E00;
    classDef external fill:#FFE6E6,stroke:#CC0000,color:#CC0000;
```
