How fabian416/sami works
Project type and purpose
• This is a full-stack, containerized Web3 game (“SAMI”) where players chat to uncover an AI agent hiding as a human. It combines:
• A Next.js frontend (React + Wagmi/Viem + RainbowKit for on-chain interactions)
• An Express/TypeScript backend (REST/API + Supabase persistence + blockchain event listener)
• An AI microservice (“Eliza”) that drives the chatbot via OpenAI or custom logic
• Solidity smart contracts managed by Foundry (game tokens, ticket system, etc.)
• Supabase (Postgres) as the primary database
• Docker Compose for local and production deployment
High-level file/dir analysis
• Top level: docker-compose.yml + docker-compose.production.yml, two Dockerfiles (frontend/backend), Caddyfile for reverse proxy
• packages/backend: Express API, controllers, services (game, player, eventListener), models, Supabase client, contract config
• packages/eliza: standalone AI microservice (chat, cache, DB), OpenAI client, its own Dockerfile/docker-compose
• packages/foundry: smart contracts, deployments, scripts, tests, Forge config
• packages/nextjs: Next.js 13 app folder, React components, scaffold-eth helpers, Wagmi/Viem config, socketContext, Tailwind CSS, web3 service layer
Key system components
A. Next.js Frontend (UI Layer)
• Hosts React pages (game lobby, block explorer, debug, leaderboard)
• Connects to:
• Express backend via REST (fetch game state, player actions) and WebSockets (real-time updates)
• Smart contracts directly via Wagmi/Viem for on-chain reads/writes (ticket minting, voting)
B. Express Backend (API Layer)
• Exposes REST endpoints (/game, /player, /sami)
• Uses Supabase client to persist Game and Player models
• Runs an eventListener service that connects to Ethereum node providers to catch contract events
• Forwards player chat to the Eliza service and returns AI responses
C. Eliza AI Microservice
• Receives chat messages (HTTP RPC) from backend
• Implements conversation logic: either rule-based or via OpenAI API
• Caches state, persists transcripts in its own store, and streams responses back
D. Smart Contracts (Blockchain Layer)
• Deployed Solidity contracts (MantleERC20, SimpleSAMI, TicketSystem) on configured networks
• Foundry scripts handle deployment and ABI generation (for frontend + backend)
E. Database & External Services
• Supabase (Postgres) for game state, player records
• OpenAI API for advanced AI chats
• Ethereum RPC providers (Infura/Alchemy or self-hosted)
Relationships & Data Flows
• Player (browser) → Next.js UI →
• REST/WS → Express API → Supabase / Eliza
• Direct on-chain calls → Smart Contracts → Ethereum
• Express API listens to on-chain events → updates Supabase → pushes to frontend via WS
• Express API calls Eliza microservice → Eliza calls OpenAI → returns chat token stream → API → frontend
• Docker Compose connects all containers (frontend, backend, eliza, supabase) behind a reverse proxy (Caddy)
Architectural patterns & principles
• Monorepo with clear package boundaries
• Microservices: AI is an isolated service
• MVC-inspired backend (controllers → services → models)
• Event-driven backchannel for blockchain event listening
• API Gateway (Express) centralizing business logic
• Container-first deployment for reproducibility
Detail reminders
• Use arrowheads and data-flow notes (e.g., “mintToken()”, “POST /api/game”)
• By Docker containers or Kubernetes pods if desired
• Essential services without over-fragmenting; keep layers distinct but comprehensive