# arttribute/mosaics architecture

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

- Interactive diagram: https://gitdiagram.com/arttribute/mosaics
- Repository: https://github.com/arttribute/mosaics

## Overview

##### Project type and purpose
- Mosaics is a full-stack, server‐rendered Next.js 13 application that combines AI‐powered puzzle generation, real‐time multiplayer, on‐chain staking/NFTs, and off-chain user data.
- Key use cases: single‐player puzzles, Play-to-Earn staking, multiplayer collaboration, ENS integration.

##### File structure
- Frontend/UI:
- app/… pages and layouts (React server & client components)
- components/… reusable UI & feature components
- styles (globals.css, tailwind config)
- API layer (Next.js serverless routes under app/api):
- /api/galadriel → prompt generation agent
- /api/generation → Astria image generation
- /api/huddle → Huddle SDK real-time signaling
- /api/generation/[id], etc.
- Business logic & hooks:
- hooks/useGameLogic.ts, useMultiplayer.ts, useRoomsLogic.ts
- lib/abi & lib/utils for contract interactions
- Blockchain & contracts:
- contracts/ + hardhat.config.js + scripts/deploy.ts
- ignition/modules for low-level chain utilities
- Off-chain data & auth:
- utils/supabase/client.ts, middleware.ts, server.ts
- Tests: test/… for smart contracts & game logic
- Configuration: .env.example, next.config.mjs, tsconfig.json, package.json

##### README for additional insights
- Tech stack: Next.js, Tailwind, Supabase, Huddle SDK (Ably), Astria Stability Diffusion API, Galadriel AI agent, ENS, Filecoin testnet
- Architectural notes: Three external “domains” – AI generation, blockchain contracts, real-time comms – woven together by Next.js APIs.

- Client (Browser/React UI)
- Next.js Server (Server Components + API routes)
- Supabase Database (Postgres)
- AI Services
– Galadriel agent (Devnet RPC)
– Astria Stability Diffusion API
- Real-time Multiplayer Service (Huddle SDK/Ably)
- Blockchain Network (Filecoin Calibration Testnet)
- ENS Service (Ethereum Mainnet/Testnet for name resolution)
1. User ↔ React UI (HTTP/WebSocket)
2. React UI → Next.js Page/API (HTTP)
3. API “/galadriel” → Galadriel RPC → returns prompts
4. API “/generation” → Astria API → returns images
5. API “/huddle” ↔ Huddle SDK/Ably (WebSocket)
6. API & Hooks → Supabase (CRUD, auth)
7. API & Client → Blockchain via Ethers.js/ABI → Filecoin network
8. Client & API → ENS (name lookup)
c. Architectural patterns & design principles:
- Separation of concerns: UI vs API vs external services
- Serverless micro-endpoints (Next.js App Router)
- Hook-based business logic for reusability
- Layered integration: AI layer, real-time layer, blockchain layer, data layer
d. Key technologies per component:
- Frontend: Next.js 13 App Router, React 18, TailwindCSS
- Backend/APIs: Next.js Server Components, Route Handlers (route.ts/route.tsx)
- State/Logic: React hooks + Zustand (if used)
- DB: Supabase (Postgres + Auth)
- Smart Contracts: Hardhat, Ethers.js, Filecoin devnet
- AI: Galadriel, Astria Stability Diffusion API
- Realtime: Huddle SDK (Ably)
- ENS: @ensdomains libraries
- Deployment: Vercel (or similar), Hardhat scripts

##### Detail without over-complication
- Similar components (all lib/abi and utils under “Blockchain Client SDK”).
- Data flows for typical user journeys (single-player, staking flow, multiplayer session).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    subgraph "Client Layer"
        direction TB
        ClientUI["React UI (Next.js app/)"]:::client
    end

    %% API Layer
    subgraph "Next.js API Layer"
        direction TB
        API["Next.js Server & API Routes (app/api/)"]:::api
        subgraph "AI Endpoints"
            direction TB
            GaladrielAPI["/api/galadriel"]:::external
            AstriaAPI["/api/generation"]:::external
        end
        subgraph "Realtime Endpoint"
            direction TB
            HuddleAPI["/api/huddle"]:::external
        end
    end

    %% External Services Layer
    subgraph "External Services"
        direction TB
        GaladrielService["Galadriel AI Agent"]:::external
        AstriaService["Astria Stability Diffusion API"]:::external
        HuddleService["Huddle SDK (Ably)"]:::external
        ENSService["ENS Name Resolution"]:::external
        BlockchainNetwork["Filecoin Calibration Testnet"]:::blockchain
    end

    %% Persistence Layer
    subgraph "Persistence Layer"
        direction TB
        SupabaseDB["Supabase (Postgres + Auth)"]:::persistence
    end

    %% Business Logic & SDKs
    subgraph "Client & API SDKs"
        direction TB
        Hooks["Game & Multiplayer Hooks\n(hooks/)"]:::api
        BlockchainSDK["Blockchain Client SDK\n(lib/abi + lib/utils)"]:::blockchain
    end

    %% Smart Contracts
    subgraph "Smart Contracts"
        direction TB
        Contracts["Contracts & Hardhat\n(contracts/, hardhat.config.js)"]:::blockchain
    end

    %% Interactions
    ClientUI -->|"HTTP/WebSocket"| API
    API -->|"RPC"| GaladrielService
    API -->|"HTTP"| AstriaService
    API -->|"WebSocket"| HuddleService
    API -->|"CRUD/Auth"| SupabaseDB
    API -->|"Ethers.js/ABI"| BlockchainNetwork
    ClientUI -->|"Ethers.js/ABI"| BlockchainNetwork
    ClientUI -->|"Name lookup"| ENSService
    API -->|"Name lookup"| ENSService
    ClientUI --> Hooks
    API --> Hooks
    API --> BlockchainSDK
    ClientUI --> BlockchainSDK
    BlockchainSDK --> BlockchainNetwork
    Contracts --> BlockchainNetwork

    %% Click Events
    click ClientUI "https://github.com/arttribute/mosaics/tree/main/app/"
    click API "https://github.com/arttribute/mosaics/tree/main/app/api/"
    click GaladrielAPI "https://github.com/arttribute/mosaics/blob/main/app/api/galadriel/route.ts"
    click AstriaAPI "https://github.com/arttribute/mosaics/blob/main/app/api/generation/route.ts"
    click HuddleAPI "https://github.com/arttribute/mosaics/blob/main/app/api/huddle/rooms/route.tsx"
    click Hooks "https://github.com/arttribute/mosaics/blob/main/hooks/useGameLogic.ts"
    click BlockchainSDK "https://github.com/arttribute/mosaics/blob/main/lib/abi/MosaicsGameAgentABI.ts"
    click Contracts "https://github.com/arttribute/mosaics/tree/main/contracts/"
    click SupabaseDB "https://github.com/arttribute/mosaics/blob/main/utils/supabase/client.ts"

    %% Styles
    classDef client fill:#DDEEFF,stroke:#3399FF
    classDef api fill:#CCFFCC,stroke:#33AA33
    classDef persistence fill:#FFFFAA,stroke:#DDDD00
    classDef external fill:#FFDDAA,stroke:#FF8800
    classDef blockchain fill:#E0CCFF,stroke:#9966CC
```
