graph TB
    subgraph "Client Layer"
        A[React Frontend<br/>Vite + TypeScript<br/>Port: 5173]
        B[Verychat Bot<br/>WebSocket Interface]
        C[Mobile App<br/>React Native]
    end
    
    subgraph "API Gateway Layer"
        D[Express Server<br/>REST API + WebSocket<br/>Port: 3001]
        E[Rate Limiter<br/>Redis-backed]
        F[CORS Middleware]
        G[Auth Middleware<br/>JWT + API Keys]
    end
    
    subgraph "Service Layer"
        H[TipService<br/>Orchestration]
        I[HuggingFaceService<br/>AI Moderation]
        J[BlockchainService<br/>Web3 Integration]
        K[VerychatService<br/>Social Platform]
        L[IpfsService<br/>Decentralized Storage]
        M[QueueService<br/>BullMQ]
        N[BadgeService<br/>Gamification]
        O[AnalyticsService<br/>Metrics & Insights]
    end
    
    subgraph "AI Infrastructure"
        P[HuggingFace API<br/>unitary/toxic-bert<br/>Inference Endpoint]
        Q[Redis Cache<br/>Moderation Results<br/>TTL: 3600s]
        R[OpenAI API<br/>GPT-4 Suggestions<br/>Optional]
    end
    
    subgraph "Blockchain Layer"
        S[Very Chain<br/>Smart Contracts<br/>Chain ID: 8888]
        T[Meta-Transaction Relayer<br/>EIP-712 Signing<br/>Port: 8080]
        U[Event Listener<br/>WebSocket Subscription]
    end
    
    subgraph "Data Layer"
        V[(PostgreSQL<br/>Prisma ORM<br/>Connection Pool: 10)]
        W[(Redis<br/>Cache + Queue<br/>Cluster Mode)]
        X[IPFS Network<br/>Pinata/Infura<br/>CID Storage]
    end
    
    subgraph "Monitoring & Observability"
        Y[Prometheus<br/>Metrics Collection]
        Z[Grafana<br/>Dashboards]
        AA[Winston<br/>Structured Logging]
    end
    
    A --> D
    B --> D
    C --> D
    D --> E
    E --> F
    F --> G
    G --> H
    
    H --> I
    H --> J
    H --> K
    H --> L
    H --> M
    H --> N
    H --> O
    
    I --> P
    I --> Q
    I --> R
    
    J --> S
    J --> T
    J --> U
    
    M --> W
    H --> V
    L --> X
    
    H --> Y
    Y --> Z
    D --> AA
    
    style I fill:#ff6b6b
    style P fill:#ff6b6b
    style Q fill:#ff9999
    style J fill:#4ecdc4
    style S fill:#4ecdc4
    style T fill:#ffe66d
    style V fill:#51cf66
    style W fill:#ff6b6b

sequenceDiagram
    participant User as User Wallet<br/>(MetaMask/Web3)
    participant Frontend as React Frontend<br/>(Ethers.js)
    participant Relayer as Meta-Tx Relayer<br/>(Express + Ethers)
    participant Contract as TipRouter.sol<br/>(Very Chain)
    participant Blockchain as Very Chain<br/>(RPC Node)

    Note over User,Blockchain: Phase 1: Message Hash Construction
    
    User->>Frontend: Initiate Tip<br/>{from, to, amount, cid, nonce}
    Frontend->>Frontend: Build Message Hash<br/>keccak256(abi.encodePacked(...))
    Frontend->>Frontend: Build CID Hash<br/>keccak256(cid)
    
    Note over User,Blockchain: Phase 2: User Signature (EIP-191)
    
    Frontend->>User: Request Signature<br/>signMessage(messageHash)
    User->>User: Sign with Private Key<br/>EIP-191 Personal Sign
    User->>Frontend: Return Signature<br/>{v, r, s}
    
    Note over User,Blockchain: Phase 3: Relayer Verification & Submission
    
    Frontend->>Relayer: POST /submit-meta<br/>{from, to, amount, cidHash, nonce, v, r, s}
    Relayer->>Relayer: Verify User Signature<br/>recoverAddress(ethSignedHash, {v, r, s})
    Relayer->>Relayer: Validate Nonce<br/>Check Replay Protection
    Relayer->>Relayer: Sign with Relayer Key<br/>signMessage(messageHash)
    Relayer->>Relayer: Extract Relayer Sig<br/>{relayerV, relayerR, relayerS}
    
    Note over User,Blockchain: Phase 4: Contract Execution
    
    Relayer->>Contract: submitTip(...)<br/>with relayer signature
    Contract->>Contract: Verify Relayer Signature<br/>onlyRelayer modifier
    Contract->>Contract: Check Replay Protection<br/>nonceUsed mapping
    Contract->>Contract: Mark Nonce as Used<br/>nonceUsed[messageHash] = true
    Contract->>Contract: Emit TipSubmitted Event
    Contract->>Blockchain: Transaction Confirmed
    Blockchain->>Relayer: Transaction Receipt<br/>{txHash, blockNumber, status}
    Relayer->>Frontend: Response<br/>{ok: true, txHash, status}
    Frontend->>User: Display Success<br/>Tip Confirmed

graph TB
    subgraph "Input Processing"
        A[Tip Message<br/>User Input<br/>Max Length: 500 chars]
        B[Input Sanitization<br/>HTML Escaping<br/>Unicode Normalization]
    end
    
    subgraph "Stage 1: Fast Pre-Filter"
        C[Keyword Filter<br/>Pattern Matching<br/>Regex Engine]
        D[Blacklist Check<br/>Redis Lookup<br/>O(1) Complexity]
        E{Match Found?}
    end
    
    subgraph "Stage 2: Cache Layer"
        F[Cache Key Generation<br/>Base64(message[0:50])]
        G[Redis Cache Lookup<br/>TTL: 3600s]
        H{Cache Hit?}
    end
    
    subgraph "Stage 3: AI Classification"
        I[HuggingFace API<br/>unitary/toxic-bert<br/>Inference Endpoint]
        J[Text Classification<br/>6 Toxicity Categories]
        K[Score Extraction<br/>Max Score Calculation]
    end
    
    subgraph "Stage 4: Decision Engine"
        L[Threshold Evaluation<br/>Configurable Limits]
        M{Score < 0.5?}
        N{0.5 ≤ Score ≤ 0.8?}
        O{Score > 0.8?}
        P[SAFE<br/>✅ Approved]
        Q[MANUAL REVIEW<br/>⚠️ Queue for Human]
        R[FLAGGED<br/>❌ Rejected]
    end
    
    subgraph "Stage 5: Result Storage"
        S[Cache Result<br/>Redis SET<br/>TTL: 3600s]
        T[Log for Analytics<br/>PostgreSQL<br/>SentimentAnalysis]
        U[Return ModerationResult<br/>JSON Response]
    end
    
    A --> B
    B --> C
    C --> D
    D --> E
    E -->|Yes| R
    E -->|No| F
    F --> G
    G --> H
    H -->|Yes| U
    H -->|No| I
    I --> J
    J --> K
    K --> L
    L --> M
    M -->|Yes| P
    M -->|No| N
    N -->|Yes| Q
    N -->|No| O
    O -->|Yes| R
    P --> S
    Q --> S
    R --> S
    S --> T
    T --> U
    
    style I fill:#4ecdc4
    style J fill:#4ecdc4
    style K fill:#ffe66d
    style R fill:#ff6b6b
    style Q fill:#ffa94d
    style P fill:#51cf66
    style G fill:#ff9999

stateDiagram-v2
    [*] --> PENDING: User Initiates Tip
    PENDING --> PROCESSING: Queue Worker Picks Up
    PROCESSING --> IPFS_UPLOAD: Message Encryption
    IPFS_UPLOAD --> BLOCKCHAIN_SUBMIT: CID Hash Generated
    BLOCKCHAIN_SUBMIT --> CONFIRMING: Transaction Sent
    CONFIRMING --> COMPLETED: Event Received
    CONFIRMING --> FAILED: Transaction Reverted
    FAILED --> RETRY: Retry Logic (3 attempts)
    RETRY --> PROCESSING: Retry Successful
    RETRY --> FAILED: Max Retries Exceeded
    COMPLETED --> BADGE_CHECK: Award Badges
    BADGE_CHECK --> NOTIFICATION: Send Alerts
    NOTIFICATION --> [*]
    FAILED --> [*]
    
    note right of PENDING
        Status: PENDING
        Database: Tip Record Created
        Queue: Job Added
    end note
    
    note right of PROCESSING
        Status: PROCESSING
        Database: Status Updated
        Worker: Active Processing
    end note
    
    note right of COMPLETED
        Status: COMPLETED
        Database: txHash Stored
        Blockchain: Event Emitted
    end note

graph TB
    subgraph "TipRouter.sol Contract"
        A[Constructor<br/>Initialize relayerSigner]
        B[submitTip Function<br/>Main Entry Point]
        C[onlyRelayer Modifier<br/>Signature Verification]
        D[Replay Protection<br/>nonceUsed Mapping]
        E[Event Emission<br/>TipSubmitted]
    end
    
    subgraph "State Variables"
        F[relayerSigner<br/>immutable address]
        G[nonceUsed<br/>mapping(bytes32 => bool)]
        H[totalTips<br/>uint256 counter]
    end
    
    subgraph "Security Features"
        I[ReentrancyGuard<br/>OpenZeppelin]
        J[Ownable<br/>Access Control]
        K[ECDSA<br/>Signature Recovery]
    end
    
    subgraph "External Interactions"
        L[Event Listener<br/>WebSocket Subscription]
        M[Indexer Service<br/>Blockchain Indexing]
        N[Analytics Service<br/>Metrics Collection]
    end
    
    A --> F
    B --> C
    C --> D
    D --> E
    B --> I
    B --> J
    C --> K
    E --> L
    L --> M
    M --> N
    
    style B fill:#4ecdc4
    style C fill:#ffe66d
    style D fill:#ff6b6b
    style E fill:#51cf66

erDiagram
    User ||--o{ Tip : "sends"
    User ||--o{ Tip : "receives"
    User ||--o{ UserBadge : "earns"
    User ||--o{ LeaderboardEntry : "ranks"
    User ||--|| GasSponsorship : "has"
    User ||--o{ AIConversation : "has"
    User ||--o{ VoiceCommand : "issues"
    
    Tip ||--o| SentimentAnalysis : "analyzed_by"
    Tip }o--o| Badge : "triggers"
    
    Badge ||--o{ UserBadge : "awarded_to"
    
    Leaderboard ||--o{ LeaderboardEntry : "contains"
    
    User {
        string id PK
        string verychatId UK
        string username UK
        string walletAddress UK
        string email UK
        enum kycStatus
        json kycMetadata
        bigint totalTipsSent
        bigint totalTipsReceived
        int uniqueUsersTipped
        int tipStreak
        datetime lastTipAt
        json tokenBalances
        datetime createdAt
        datetime updatedAt
    }
    
    Tip {
        string id PK
        string senderId FK
        string recipientId FK
        string tokenAddress
        string amount
        bigint amountInWei
        string messageHash
        string messageEncrypted
        string transactionHash UK
        int blockNumber
        int tipId
        string aiSuggestionId
        float aiConfidence
        json aiFeatures
        enum status
        string errorReason
        datetime createdAt
        datetime confirmedAt
    }
    
    SentimentAnalysis {
        string id PK
        string tipId FK
        string sentiment
        float score
        json categories
        string[] flags
        string model
        string version
        datetime processedAt
    }
    
    Badge {
        string id PK
        string name UK
        string description
        string imageUrl
        json requirements
        int contractBadgeId
        boolean onChain
        boolean isCommunityFunded
        string poolBalance
        int totalMinted
        datetime createdAt
        datetime updatedAt
    }
    
    UserBadge {
        string id PK
        string userId FK
        string badgeId FK
        string transactionHash
        string tokenId
        datetime earnedAt
        json context
    }
    
    Leaderboard {
        string id PK
        enum period
        enum category
        json rankings
        datetime periodStart
        datetime periodEnd
        datetime calculatedAt
    }
    
    LeaderboardEntry {
        string id PK
        string leaderboardId FK
        string userId FK
        int rank
        bigint score
        int change
        datetime createdAt
    }
    
    GasSponsorship {
        string id PK
        string userId FK
        int totalCredits
        int usedCredits
        int remainingCredits
        int dailyUsed
        int dailyLimit
        datetime lastResetAt
        datetime nextResetAt
        bigint totalSponsored
        datetime updatedAt
    }

graph TB
    subgraph "Queue Management"
        A[Tip Queue<br/>BullMQ Redis]
        B[Job Producer<br/>TipService]
        C[Job Consumer<br/>Queue Worker]
    end
    
    subgraph "Job Lifecycle"
        D[Job Created<br/>Status: waiting]
        E[Job Active<br/>Status: active]
        F[Job Completed<br/>Status: completed]
        G[Job Failed<br/>Status: failed]
        H[Job Retry<br/>Status: delayed]
    end
    
    subgraph "Worker Processing"
        I[Fetch Tip from DB]
        J[Update Status: PROCESSING]
        K[Encrypt Message]
        L[Upload to IPFS]
        M[Submit to Blockchain]
        N[Update Status: COMPLETED]
        O[Handle Errors]
    end
    
    subgraph "Retry Logic"
        P[Exponential Backoff<br/>Base: 1s, Max: 60s]
        Q[Max Retries: 3]
        R[Dead Letter Queue<br/>After Max Retries]
    end
    
    B --> A
    A --> C
    C --> D
    D --> E
    E --> I
    I --> J
    J --> K
    K --> L
    L --> M
    M --> N
    N --> F
    M --> O
    O --> G
    G --> H
    H --> P
    P --> Q
    Q -->|Retry| E
    Q -->|Max Exceeded| R
    
    style A fill:#ff6b6b
    style C fill:#4ecdc4
    style F fill:#51cf66
    style G fill:#ff6b6b
    style R fill:#ffa94d

graph TB
    subgraph "Network Layer"
        A[DDoS Protection<br/>Cloudflare/CloudFront]
        B[Rate Limiting<br/>Redis-backed]
        C[IP Whitelisting<br/>Optional]
    end
    
    subgraph "Application Layer"
        D[Input Validation<br/>Zod Schema]
        E[SQL Injection Prevention<br/>Prisma Parameterized Queries]
        F[XSS Protection<br/>Content Sanitization]
        G[CSRF Protection<br/>SameSite Cookies]
    end
    
    subgraph "Authentication & Authorization"
        H[JWT Tokens<br/>RS256 Algorithm]
        I[API Key Validation<br/>HMAC Signing]
        J[Role-Based Access Control<br/>RBAC]
        K[OAuth 2.0<br/>Verychat Integration]
    end
    
    subgraph "Blockchain Security"
        L[Signature Verification<br/>EIP-712]
        M[Replay Protection<br/>Nonce Management]
        N[Reentrancy Guards<br/>OpenZeppelin]
        O[Access Control<br/>Ownable Pattern]
    end
    
    subgraph "Data Security"
        P[Encryption at Rest<br/>AES-256]
        Q[Encryption in Transit<br/>TLS 1.3]
        R[Message Encryption<br/>Public Key Crypto]
        S[IPFS Privacy<br/>Encrypted CIDs]
    end
    
    subgraph "Monitoring & Detection"
        T[Security Logging<br/>Winston + ELK]
        U[Anomaly Detection<br/>ML-based]
        V[Intrusion Detection<br/>IDS/IPS]
        W[Audit Trails<br/>Immutable Logs]
    end
    
    A --> B
    B --> C
    C --> D
    D --> E
    E --> F
    F --> G
    G --> H
    H --> I
    I --> J
    J --> K
    K --> L
    L --> M
    M --> N
    N --> O
    O --> P
    P --> Q
    Q --> R
    R --> S
    S --> T
    T --> U
    U --> V
    V --> W
    
    style L fill:#4ecdc4
    style M fill:#ffe66d
    style N fill:#ff6b6b
    style R fill:#51cf66
    style T fill:#ffa94d

graph TB
    subgraph "Cache Layers"
        A[L1: In-Memory Cache<br/>Node.js Map<br/>TTL: 60s]
        B[L2: Redis Cache<br/>Distributed<br/>TTL: 3600s]
        C[L3: Database<br/>PostgreSQL<br/>Persistent]
    end
    
    subgraph "Cache Keys"
        D[Moderation Results<br/>hf:moderation:{hash}]
        E[User Data<br/>user:{userId}]
        F[Leaderboard<br/>leaderboard:{period}:{category}]
        G[Tip Status<br/>tip:{tipId}]
    end
    
    A -->|Cache Miss| B
    B -->|Cache Miss| C
    C -->|Populate| B
    B -->|Populate| A
    
    style A fill:#51cf66
    style B fill:#ff6b6b
    style C fill:#4ecdc4

graph TB
    subgraph "CDN & Load Balancer"
        A[Cloudflare CDN<br/>Static Assets]
        B[Application Load Balancer<br/>AWS ALB / GCP LB]
    end
    
    subgraph "Application Tier"
        C[API Server 1<br/>Node.js + Express<br/>Auto-scaling: 2-10]
        D[API Server 2<br/>Node.js + Express]
        E[API Server N<br/>Node.js + Express]
    end
    
    subgraph "Queue Workers"
        F[Worker 1<br/>BullMQ Consumer]
        G[Worker 2<br/>BullMQ Consumer]
        H[Worker N<br/>BullMQ Consumer]
    end
    
    subgraph "Data Tier"
        I[(PostgreSQL Primary<br/>AWS RDS / GCP Cloud SQL)]
        J[(PostgreSQL Replica<br/>Read Replica)]
        K[(Redis Cluster<br/>ElastiCache / Memorystore)]
    end
    
    subgraph "Blockchain Services"
        L[Meta-Transaction Relayer<br/>KMS-backed Signing]
        M[Event Listener<br/>WebSocket Subscription]
        N[Indexer Service<br/>Blockchain Indexing]
    end
    
    subgraph "External Services"
        O[HuggingFace API<br/>AI Moderation]
        P[IPFS Providers<br/>Pinata / Infura]
        Q[Very Chain<br/>RPC Nodes]
    end
    
    subgraph "Monitoring & Observability"
        R[Prometheus<br/>Metrics]
        S[Grafana<br/>Dashboards]
        T[ELK Stack<br/>Logging]
        U[Sentry<br/>Error Tracking]
    end
    
    A --> B
    B --> C
    B --> D
    B --> E
    C --> I
    D --> I
    E --> I
    I --> J
    C --> K
    D --> K
    E --> K
    F --> K
    G --> K
    H --> K
    F --> I
    G --> I
    H --> I
    L --> Q
    M --> Q
    N --> Q
    C --> O
    C --> P
    L --> Q
    C --> R
    D --> R
    E --> R
    R --> S
    C --> T
    C --> U
    
    style I fill:#51cf66
    style K fill:#ff6b6b
    style L fill:#ffe66d
    style O fill:#4ecdc4

graph TB
    A[E2E Tests<br/>10%<br/>Critical User Flows]
    B[Integration Tests<br/>30%<br/>Service Interactions]
    C[Unit Tests<br/>60%<br/>Individual Functions]
    
    A --> B
    B --> C
    
    style A fill:#ff6b6b
    style B fill:#ffe66d
    style C fill:#51cf66