# team-somehow/ticket architecture

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

- Interactive diagram: https://gitdiagram.com/team-somehow/ticket
- Repository: https://github.com/team-somehow/ticket

## Overview

##### Project type and purpose
- FanBase is a full-stack, blockchain-enabled ticketing platform combining:
- Multiple React-based frontends (fan-facing “client/frontend” and organizer “organizer”)
- Serverless backends (Firebase Functions in Python and Node)
- On-chain smart contracts (StarkNet/Cairo & ERC-2981 EVM)
- Off-chain attestation & proof services
- External integrations (Spotify OAuth, Worldcoin/Anonaadhar, Coinbase)

##### File structure
- Top-level workspaces:
- attestation/ — Node TS service using True Network schemas & proofs
- client/ & organizer/ & frontend/ — Three parallel React+Vite/TypeScript UIs
- client/functions & functions-zkfetch & functions/ — Serverless Python/JS for OAuth, storage, ZK-fetch
- starknet/ — Cairo contracts, deployment scripts, Docker compose
- web3-interactions/ — TypeScript library for on-chain calls (Ethers/wagmi)
- firebase.json & .firebaserc — Firebase hosting & functions config
- docs/ — VitePress site describing APIs & guides

##### README for additional insight
- Core features:
- Fan scoring via Spotify data → priority queue
- ERC-2981 royalties & capped resale prices
- NFT-based non-resalable tickets
- Loyalty discounts & emerging artist perks
- Multi-network deployment (Sepolia, BSC, StarkNet)

##### Components
- UI Tier
- Fan Web App (React/Vite)
- Organizer Web App (React/Vite)
- API & Business Logic
- Firebase Functions (Python/Node)
- ZK-fetch Functions (JS)
- Attestation Service (Node/True Network)
- Blockchain Tier
- StarkNet Contracts (Cairo)
- EVM Contracts (ERC-2981)
- Web3-interactions library
- Data Indexing & Storage
- Firebase Firestore or Realtime Database
- External Services
- Spotify API (OAuth)
- Worldcoin/Anonaadhar
- Coinbase/ETH wallet providers

- Frontends ←→ Firebase Functions (user auth, fan‐score retrieval)
- Frontends → Web3-interactions → Smart Contracts (apply/buy/sell tickets)
- Firebase Functions → Attestation Service → True Network proofs
- Serverless Functions ↔ Spotify API (OAuth & listening data)
- Frontends ↔ Wallet providers (MetaMask/Coinbase)

c. Architectural patterns & principles:
- Microfrontend: parallel consumer & organizer apps
- Serverless microservices: Firebase Functions & ZK-fetch
- Layered architecture: UI → API → Blockchain → Storage
- Security by design: OAuth & attestations for data integrity

d. Key technologies & frameworks:
- React, TypeScript, Vite, Tailwind CSS
- Firebase (hosting, functions, Firestore)
- Node.js & Python for serverless code
- Cairo/Scarb for StarkNet contracts
- Ethers.js/wagmi for Ethereum interactions
- GraphQL & The Graph for indexing

##### Detail is critical
- Every major component—even if internal libraries (web3-interactions)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% UI Layer
    subgraph "UI Layer"
        FanWebApp["Fan Web App"]:::ui
        OrganizerWebApp["Organizer Web App"]:::ui
        AltFanWebApp["Alternative Fan Web App"]:::ui
    end

    %% API & Business Logic Layer
    subgraph "API & Business Logic" 
        FirebaseClientFuncs["Firebase Functions (Client)"]:::api
        FirebaseSharedFuncs["Firebase Functions (Shared)"]:::api
        ZKFetchFuncs["ZK-fetch Functions"]:::api
        Attestation["Attestation Service"]:::api
    end

    %% Blockchain Layer
    subgraph "Blockchain Tier"
        StarknetContracts["StarkNet Contracts"]:::blockchain
        EVMContracts["EVM Contracts"]:::blockchain
        Web3Lib["Web3-interactions Library"]:::blockchain
    end

    %% Indexing & Storage
    subgraph "Indexing & Storage"
        Subgraph["The Graph Subgraph"]:::storage
        Firestore["Firebase Firestore/Realtime DB"]:::storage
    end

    %% External Services
    subgraph "External Services"
        SpotifyAPI["Spotify API (OAuth)"]:::ext
        Worldcoin["Worldcoin/Anonaadhar"]:::ext
        CoinbaseWallet["Coinbase/ETH Wallet Providers"]:::ext
        TrueNetwork["True Network Proofs"]:::ext
        DockerCompose["Docker Compose (StarkNet & Subgraph)"]:::ext
    end

    %% Relationships
    FanWebApp <--> FirebaseClientFuncs
    OrganizerWebApp <--> FirebaseSharedFuncs
    AltFanWebApp <--> FirebaseClientFuncs

    FanWebApp -->|uses| Web3Lib
    OrganizerWebApp -->|uses| Web3Lib
    AltFanWebApp -->|uses| Web3Lib

    Web3Lib -->|"calls apply/buy/sell"| StarknetContracts
    Web3Lib -->|"calls apply/buy/sell"| EVMContracts

    FirebaseClientFuncs --> Attestation
    FirebaseSharedFuncs --> Attestation
    Attestation --> TrueNetwork

    FirebaseClientFuncs <--> SpotifyAPI
    FirebaseSharedFuncs <--> SpotifyAPI

    StarknetContracts -->|"emit events"| Subgraph
    EVMContracts -->|"emit events"| Subgraph
    Subgraph -->|GraphQL queries| FanWebApp
    Subgraph -->|GraphQL queries| OrganizerWebApp
    Subgraph -->|GraphQL queries| AltFanWebApp

    FirebaseClientFuncs -->|reads/writes| Firestore
    FirebaseSharedFuncs -->|reads/writes| Firestore

    FanWebApp <--> CoinbaseWallet
    OrganizerWebApp <--> CoinbaseWallet
    AltFanWebApp <--> CoinbaseWallet

    DockerCompose -.-> StarknetContracts
    DockerCompose -.-> Subgraph

    %% Click Events
    click FanWebApp "https://github.com/team-somehow/ticket/tree/main/client/frontend/"
    click OrganizerWebApp "https://github.com/team-somehow/ticket/tree/main/organizer/"
    click AltFanWebApp "https://github.com/team-somehow/ticket/tree/main/frontend/"
    click FirebaseClientFuncs "https://github.com/team-somehow/ticket/blob/main/client/functions/main.py"
    click FirebaseClientFuncs "https://github.com/team-somehow/ticket/tree/main/client/functions/spotify/"
    click FirebaseClientFuncs "https://github.com/team-somehow/ticket/tree/main/client/functions/storage/"
    click FirebaseSharedFuncs "https://github.com/team-somehow/ticket/blob/main/functions/main.py"
    click FirebaseSharedFuncs "https://github.com/team-somehow/ticket/tree/main/functions/spotify/"
    click FirebaseSharedFuncs "https://github.com/team-somehow/ticket/tree/main/functions/storage/"
    click ZKFetchFuncs "https://github.com/team-somehow/ticket/tree/main/functions-zkfetch/src/"
    click Attestation "https://github.com/team-somehow/ticket/blob/main/attestation/index.ts"
    click Attestation "https://github.com/team-somehow/ticket/tree/main/attestation/true-network/"
    click StarknetContracts "https://github.com/team-somehow/ticket/tree/main/starknet/src/"
    click StarknetContracts "https://github.com/team-somehow/ticket/tree/main/starknet/scripts/"
    click EVMContracts "https://github.com/team-somehow/ticket/tree/main/contracts/protocol/"
    click EVMContracts "https://github.com/team-somehow/ticket/blob/main/contracts/artifacts/gpt_contract.json"
    click Web3Lib "https://github.com/team-somehow/ticket/tree/main/web3-interactions/src/"
    click Web3Lib "https://github.com/team-somehow/ticket/tree/main/client/web3-interactions/src/"
    click Subgraph "https://github.com/team-somehow/ticket/tree/main/ticketsubgraph/src/"
    click Subgraph "https://github.com/team-somehow/ticket/blob/main/ticketsubgraph/subgraph.yaml"
    click FirebaseConfig "https://github.com/team-somehow/ticket/blob/main/firebase.json"
    click FirebaseConfig "https://github.com/team-somehow/ticket/blob/main/.firebaserc"
    click SpotifyAPI "https://github.com/team-somehow/ticket/blob/main/client/functions/spotify/auth.py"
    click SpotifyAPI "https://github.com/team-somehow/ticket/blob/main/functions/spotify/auth.py"
    click CoinbaseWallet "https://github.com/team-somehow/ticket/blob/main/web3-interactions/src/coinbaseFunctions.ts"
    click DockerCompose "https://github.com/team-somehow/ticket/blob/main/starknet/docker-compose.yml"
    click DockerCompose "https://github.com/team-somehow/ticket/blob/main/ticketsubgraph/docker-compose.yml"

    %% Styles
    classDef ui fill:#D0E8FF,stroke:#0366D6,color:#0366D6;
    classDef api fill:#DFFFE0,stroke:#228B22,color:#228B22;
    classDef blockchain fill:#ECD0FF,stroke:#7D3C98,color:#7D3C98;
    classDef storage fill:#FFE8C0,stroke:#FF8C00,color:#FF8C00;
    classDef ext fill:#F0F0F0,stroke:#606060,color:#606060;
    class FirebaseConfig ext
```
