How arttribute/mosaics works
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).