# fabian416/sami architecture

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

- Interactive diagram: https://gitdiagram.com/fabian416/sami
- Repository: https://github.com/fabian416/sami

## Overview

##### 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

## Diagram (Mermaid)

```mermaid
graph TB
  classDef ui fill:#ADD8E6,stroke:#000,stroke-width:1px
  classDef api fill:#90EE90,stroke:#000,stroke-width:1px
  classDef ai fill:#FFA500,stroke:#000,stroke-width:1px
  classDef blockchain fill:#DDA0DD,stroke:#000,stroke-width:1px
  classDef db fill:#D3D3D3,stroke:#000,stroke-width:1px
  classDef external fill:#F08080,stroke:#000,stroke-width:1px
  classDef infra fill:#F5F5F5,stroke:#000,stroke-width:1px

  %% User and External Services
  User["Player (Browser)"]:::external
  OpenAI["OpenAI API"]:::external
  EthereumRPC["Ethereum RPC\n(Infura/Alchemy)"]:::external

  %% Reverse Proxy & Orchestration
  subgraph "Caddy & Docker Compose" 
    direction TB
    Caddy["Caddy\n(Reverse Proxy)"]:::infra
    DCLocal["docker-compose.yml"]:::infra
    DCProd["docker-compose.production.yml"]:::infra
    Caddy --> DCLocal
    Caddy --> DCProd
  end

  %% Frontend Container
  subgraph "Next.js Frontend" 
    direction TB
    Frontend["Next.js Frontend\n(React, Tailwind)"]:::ui
    subgraph "Frontend Code"
      direction TB
      AppFolder["App Folder"]:::ui
      ComponentsNode["Components"]:::ui
      Web3["Web3 Service\n(wagmiConfig)"]:::ui
      WagmiConn["wagmiConnectors"]:::ui
      Socket["SocketContext"]:::ui
    end
  end

  %% Backend Container
  subgraph "Express Backend" 
    direction TB
    Backend["Express API\n(TypeScript, REST, WS)"]:::api
    subgraph "Backend Code"
      direction TB
      CTR["Controllers"]:::api
      GS["gameService.ts"]:::api
      PS["playerService.ts"]:::api
      EL["eventListener.ts"]:::api
      GM["Game.ts"]:::api
      PM["Player.ts"]:::api
      GRoutes["gameRoutes.ts"]:::api
      PRoutes["playerRoutes.ts"]:::api
      SRoutes["samiRoutes.ts"]:::api
      SC["supabaseClient.ts"]:::api
      CC["contractConfig.ts"]:::api
    end
  end

  %% AI Microservice Container
  subgraph "Eliza AI Service" 
    direction TB
    Eliza["Eliza AI Service"]:::ai
    subgraph "Eliza Code"
      direction TB
      ChatLogic["chat/index.ts"]:::ai
      Clients["clients/index.ts"]:::ai
      Cache["cache/index.ts"]:::ai
      DBEliza["database/index.ts"]:::ai
    end
    ElizaDocker["Dockerfile"]:::infra
    ElizaCompose["docker-compose.yaml"]:::infra
  end

  %% Smart Contracts Container
  subgraph "Foundry Smart Contracts" 
    direction TB
    Contracts["contracts"]:::blockchain
    Deployments["deployments"]:::blockchain
    GenTs["generateTsAbis.js"]:::blockchain
    FoundryConfig["foundry.toml"]:::blockchain
  end

  %% Database Container
  Supabase["Supabase\n(Postgres)"]:::db

  %% Container Builds
  DockerFE["Dockerfile.frontend"]:::infra
  DockerBE["Dockerfile.backend"]:::infra
  Caddyfile["Caddyfile"]:::infra

  %% Connections
  User --> Frontend
  Frontend -->|"REST/WS POST /api/*"| Backend
  Frontend -->|"on-chain calls mintToken()"| EthereumRPC
  Backend -->|"persist/read"| Supabase
  Backend -->|"RPC events"| EthereumRPC
  Backend -->|"chat RPC"| Eliza
  Eliza -->|"OpenAI API calls"| OpenAI
  EthereumRPC -->|"event stream"| Backend
  Caddy --> Frontend
  Caddy --> Backend
  Caddy --> Eliza
  Caddy --> Supabase

  %% Click Events
  click AppFolder "https://github.com/fabian416/sami/tree/main/packages/nextjs/app"
  click ComponentsNode "https://github.com/fabian416/sami/tree/main/packages/nextjs/components"
  click Web3 "https://github.com/fabian416/sami/blob/main/packages/nextjs/services/web3/wagmiConfig.tsx"
  click WagmiConn "https://github.com/fabian416/sami/blob/main/packages/nextjs/services/web3/wagmiConnectors.tsx"
  click Socket "https://github.com/fabian416/sami/blob/main/packages/nextjs/app/socketContext.tsx"
  click Backend "https://github.com/fabian416/sami/tree/main/packages/backend/src"
  click CTR "https://github.com/fabian416/sami/tree/main/packages/backend/src/controllers"
  click GS "https://github.com/fabian416/sami/blob/main/packages/backend/src/services/gameService.ts"
  click PS "https://github.com/fabian416/sami/blob/main/packages/backend/src/services/playerService.ts"
  click EL "https://github.com/fabian416/sami/blob/main/packages/backend/src/services/eventListener.ts"
  click GM "https://github.com/fabian416/sami/blob/main/packages/backend/src/models/Game.ts"
  click PM "https://github.com/fabian416/sami/blob/main/packages/backend/src/models/Player.ts"
  click GRoutes "https://github.com/fabian416/sami/blob/main/packages/backend/src/routes/gameRoutes.ts"
  click PRoutes "https://github.com/fabian416/sami/blob/main/packages/backend/src/routes/playerRoutes.ts"
  click SRoutes "https://github.com/fabian416/sami/blob/main/packages/backend/src/routes/samiRoutes.ts"
  click SC "https://github.com/fabian416/sami/blob/main/packages/backend/src/config/supabaseClient.ts"
  click CC "https://github.com/fabian416/sami/blob/main/packages/backend/src/config/contractConfig.ts"
  click ChatLogic "https://github.com/fabian416/sami/blob/main/packages/eliza/src/chat/index.ts"
  click Clients "https://github.com/fabian416/sami/blob/main/packages/eliza/src/clients/index.ts"
  click Cache "https://github.com/fabian416/sami/blob/main/packages/eliza/src/cache/index.ts"
  click DBEliza "https://github.com/fabian416/sami/blob/main/packages/eliza/src/database/index.ts"
  click ElizaDocker "https://github.com/fabian416/sami/tree/main/packages/eliza/Dockerfile"
  click ElizaCompose "https://github.com/fabian416/sami/blob/main/packages/eliza/docker-compose.yaml"
  click Contracts "https://github.com/fabian416/sami/tree/main/packages/foundry/contracts"
  click Deployments "https://github.com/fabian416/sami/tree/main/packages/foundry/deployments"
  click GenTs "https://github.com/fabian416/sami/blob/main/packages/foundry/scripts-js/generateTsAbis.js"
  click FoundryConfig "https://github.com/fabian416/sami/blob/main/packages/foundry/foundry.toml"
  click DCLocal "https://github.com/fabian416/sami/blob/main/docker-compose.yml"
  click DCProd "https://github.com/fabian416/sami/blob/main/docker-compose.production.yml"
  click DockerFE "https://github.com/fabian416/sami/blob/main/Dockerfile.frontend"
  click DockerBE "https://github.com/fabian416/sami/blob/main/Dockerfile.backend"
  click Caddyfile "https://github.com/fabian416/sami/tree/main/Caddyfile"
```
