# ayonpaul8906/zencue architecture

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

- Interactive diagram: https://gitdiagram.com/ayonpaul8906/zencue
- Repository: https://github.com/ayonpaul8906/zencue

## Overview

##### Project Type & Purpose
- This is a full-stack web application (“ZenCue”) that combines a React/Vite/Tailwind frontend, a Flask backend, AI multimodal processing (via Groq APIs), Firebase for auth & datastore, and OnchainKit (Base) for subscription payments.
- Purpose: Provide neurodivergent children with smart text/image/audio summarization, voice/chat AI, focus tools, plus secure on-chain subscription management.

##### File Structure Highlights
- Top-level:
- backend/ – Flask service (app.py, requirements.txt, Procfile)
- frontend/ – React/Vite SPA (TypeScript, Tailwind, Radix UI, many UI components)
- frontend/src/lib & hooks: wrappers for Firebase auth, Groq API calls, subscription logic
- Config files: Vite, Tailwind, eslint, tsconfig, vercel.json (frontend deploy), Procfile (backend deploy)
- No monorepo tooling; frontend and backend are separate deployables.

##### README Insights
- AI features: text/image understanding, chat with TTS via Groq
- Auth & data via Firebase (Firestore + Auth)
- On-chain payments & subscription via Base (SepholiaETH)
- Frontend hosted on Vercel; backend likely on Heroku or similar (Procfile present)

a. Frontend (Browser/Client)
- React App (Vite)
- UI Layer (Radix UI components)
- Auth Context & Routing
- Groq API wrappers / subscription hooks / Firebase SDK
- OnchainKit wallet integration
b. Backend (Flask API)
- REST endpoints: /summarize, /vision-explain, /chat, /tts
- Groq API clients (text, vision, audio)
- Firebase Admin (optional) for any server-side DB ops
c. Database & Auth
- Firebase Authentication
- Firestore (user profiles, subscription status, usage logs)
d. External Services
- Groq Multimodal AI APIs
- OnchainKit (Base) & Ethereum Sepolia
e. Hosting/Deployment
- Frontend → Vercel
- Backend → Heroku/AWS/GCP (Procfile implies Heroku)

##### Relationships & Data Flow
- User → Frontend (UI interactions, NFT wallet popups via OnchainKit)
- Frontend → Firebase Auth (login/signup)
- Frontend → Flask API over HTTPS
- For text/image summarization and voice chat
- Flask API → Groq APIs (multimodal calls)
- Frontend ↔ Firestore (fetch/save profile, subscription data)
- Frontend → OnchainKit → Base blockchain (manage subscriptions)
- All traffic secured over TLS

##### Architectural Patterns & Principles
- Separation of concerns: UI vs client-side logic vs backend services
- Component-driven UI (Radix + Tailwind + custom components)
- Hook-based logic for data & side-effects (React Hooks)
- Externalizing secrets/config via .env, aligning with 12-factor app
- Micro-service style: small Flask API for AI features, distinct from client

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    subgraph "Client (Browser)" 
        direction TB
        ReactApp["React + Vite SPA"]:::frontend
        UIComponents["UI Components (Radix + Tailwind)"]:::frontend
        AuthRouting["AuthContext & Routing"]:::frontend
        FirebaseSDK["Firebase SDK & Firestore Services"]:::frontend
        AIHooks["AI & Groq API Hooks"]:::frontend
        OnchainKit["OnchainKit Subscription Logic"]:::frontend
        ConfigDeploy["Global Config & Deployment"]:::frontend
    end

    %% API Layer
    subgraph "API Layer (Flask)" 
        direction TB
        FlaskAPI["Flask API Service"]:::backend
        TextService["TextService (/summarize)"]:::backend
        VisionService["VisionService (/vision-explain)"]:::backend
        ChatService["ChatService (/chat)"]:::backend
        TTSService["TTSService (/tts)"]:::backend
    end

    %% Services Layer
    subgraph "External Services" 
        direction TB
        Firestore[(Firestore DB)]:::db
        Auth[(Firebase Auth)]:::db
        GroqAPI["Groq Multimodal API"]:::external
        BaseChain["Base Blockchain (SepholiaETH)"]:::external
    end

    %% Hosting
    Vercel["Vercel Hosting"]:::external
    Heroku["Heroku/AWS Hosting"]:::external

    %% Connections
    ReactApp -->|"uses"/src components| UIComponents
    ReactApp -->|"uses"/src hooks| AuthRouting
    ReactApp -->|"uses"/src lib| FirebaseSDK
    ReactApp -->|"uses"/src hooks| AIHooks
    ReactApp -->|"uses"/src hooks| OnchainKit
    ReactApp -->|"config via"/frontend/tailwind.config.js| ConfigDeploy

    ReactApp -->|POST /summarize<br/>POST /vision-explain| FlaskAPI
    FlaskAPI -->|calls| TextService
    FlaskAPI -->|calls| VisionService
    FlaskAPI -->|calls| ChatService
    FlaskAPI -->|calls| TTSService
    TextService -->|HTTPS| GroqAPI
    VisionService -->|HTTPS| GroqAPI
    ChatService -->|HTTPS| GroqAPI
    TTSService -->|HTTPS| GroqAPI

    ReactApp -->|onAuthStateChanged| Auth
    ReactApp -->|read/write| Firestore
    FlaskAPI -->|admin ops| Firestore

    ReactApp -->|eth_signTx / subscribe| BaseChain

    Vercel -->|deploys| ReactApp
    Heroku -->|deploys| FlaskAPI

    %% Click Events - Frontend
    click ReactApp "https://github.com/ayonpaul8906/zencue/blob/master/frontend/src/main.tsx"
    click ReactApp "https://github.com/ayonpaul8906/zencue/blob/master/frontend/src/App.tsx"
    click UIComponents "https://github.com/ayonpaul8906/zencue/tree/master/frontend/src/components/ui/"
    click AuthRouting "https://github.com/ayonpaul8906/zencue/blob/master/frontend/src/hooks/AuthContext.tsx"
    click AuthRouting "https://github.com/ayonpaul8906/zencue/blob/master/frontend/src/components/ProtectedRoute.tsx"
    click FirebaseSDK "https://github.com/ayonpaul8906/zencue/blob/master/frontend/src/lib/firebase.ts"
    click FirebaseSDK "https://github.com/ayonpaul8906/zencue/blob/master/frontend/src/lib/usageService.ts"
    click FirebaseSDK "https://github.com/ayonpaul8906/zencue/blob/master/frontend/src/lib/subscriptions.ts"
    click AIHooks "https://github.com/ayonpaul8906/zencue/blob/master/frontend/src/hooks/importantWords.ts"
    click AIHooks "https://github.com/ayonpaul8906/zencue/blob/master/frontend/src/hooks/subscriptionService.ts"
    click OnchainKit "https://github.com/ayonpaul8906/zencue/blob/master/frontend/src/hooks/useSubscriptionPayment.ts"
    click OnchainKit "https://github.com/ayonpaul8906/zencue/blob/master/frontend/src/hooks/use-mobile.tsx"
    click ConfigDeploy "https://github.com/ayonpaul8906/zencue/blob/master/frontend/tailwind.config.js"
    click ConfigDeploy "https://github.com/ayonpaul8906/zencue/blob/master/frontend/vite.config.ts"
    click ConfigDeploy "https://github.com/ayonpaul8906/zencue/blob/master/frontend/src/globals.css"
    click ConfigDeploy "https://github.com/ayonpaul8906/zencue/blob/master/frontend/src/styles/globals.css"
    click ConfigDeploy "https://github.com/ayonpaul8906/zencue/blob/master/frontend/vercel.json"
    click ConfigDeploy "https://github.com/ayonpaul8906/zencue/blob/master/frontend/package.json"

    %% Click Events - Backend
    click FlaskAPI "https://github.com/ayonpaul8906/zencue/blob/master/backend/app.py"
    click FlaskAPI "https://github.com/ayonpaul8906/zencue/blob/master/backend/requirements.txt"
    click FlaskAPI "https://github.com/ayonpaul8906/zencue/tree/master/backend/Procfile"

    %% Styles
    classDef frontend fill:#cce5ff,stroke:#333,stroke-width:1px
    classDef backend fill:#d4edda,stroke:#333,stroke-width:1px
    classDef external fill:#fff3cd,stroke:#333,stroke-width:1px
    classDef db fill:#d1ecf1,stroke:#333,stroke-width:1px
```
