# itzzgaurav7/sage-zingguru architecture

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

- Interactive diagram: https://gitdiagram.com/itzzgaurav7/sage-zingguru
- Repository: https://github.com/itzzgaurav7/sage-zingguru

## Overview

##### Project Type & Purpose
- Full-stack, AI-powered learning ecosystem
- Frontend: React & Vite (web app) + optional browser extension
- Backend/API Gateway: Node.js + Express
- AI/ML microservices: Python FastAPI (RAG pipelines) & ML-API (video summarizer)
- Data: PostgreSQL, Redis cache, AWS S3, Firebase

##### File Structure
Top-level directories
– Frontend/ : React-Vite app, components, Redux slices, Firebase config
– Backend/ : Node.js Express server, db.js, REST endpoints
– Fast-API/ : Python apps for Retrieval-Augmented Generation (RAG)
– ML-API/ : Python video summarizer service
– extension/ : Browser extension assets, background.js, popup.js
– data/ : Static JSON for career paths
Config & infra
– .env files in each service
– package.json at root for monorepo scripts
– Vercel config in Frontend/vercel.json

##### README Insights
- System Architecture snippet: “User ➝ Frontend ➝ API Gateway ➝ Backend ➝ DB ➝ AI Services ➝ Caching ➝ Storage”
- Tech stack table: React, Node/Express, GraphQL API, OpenAI, LangChain, PostgreSQL, Redis, AWS S3, Firebase

1. Presentation Layer
- Web App (React)
- Browser Extension
2. API Layer
- API Gateway / Node.js (Express + GraphQL)
3. Service Layer
- FastAPI RAG Service
- ML-API Video Summarizer
4. Data Layer
- PostgreSQL (persistent storage)
- Redis (caching)
- AWS S3 (blob storage)
- Firebase (Auth, Firestore/Realtime)
5. External AI Services
- OpenAI / LangChain
- Google Cloud ML
6. Hosting & CI/CD
- Vercel (frontend)
- Docker/Kubernetes (optional backend)

- User → React UI (HTTPS)
- React → API Gateway (REST/GraphQL)
- Extension → API Gateway (REST)
- API Gateway → PostgreSQL (queries)
- API Gateway ↔ Redis (get/set cache)
- API Gateway → AWS S3 (upload/download media)
- API Gateway → FastAPI RAG (HTTP/gRPC) → OpenAI/LangChain
- API Gateway → ML-API (HTTP) for video summarization
- API Gateway → Firebase Auth & Firestore
- Optional: FastAPI/ML-API also call external AI services directly

c. Architectural Patterns & Principles
- Layered Architecture: clear separation of Presentation, API, Services, Data
- Microservices: independent RAG & ML services
- Cache‐Aside: Redis for hot data
- Serverless/static hosting for frontend (Vercel), containerized backend/services
- State Management: Redux slices in frontend

d. Technologies & Frameworks to Call Out
- React.js + Vite + Tailwind (UI)
- Express.js + GraphQL (API Gateway)
- FastAPI (Python RAG), Streamlit (optional UI)
- Python video summarizer (ML-API)
- PostgreSQL, Redis, AWS S3
- Firebase (Auth, Firestore)
- OpenAI / LangChain

##### Final Checklist
✔ All layers & components represented
✔ Data flows & dependencies clearly arrowed
✔ Key technologies called out in component labels

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Presentation Layer
    subgraph "Presentation Layer"
        direction TB
        User((User)):::external
        WebApp["Web App (React & Vite)"]:::presentation
        BrowserExt["Browser Extension"]:::presentation
    end

    %% API Layer
    subgraph "API Layer"
        direction TB
        APIGateway["API Gateway\n(Node.js/Express, GraphQL)"]:::api
    end

    %% Service Layer
    subgraph "Service Layer"
        direction TB
        FastAPI["FastAPI RAG Service"]:::service
        MLAPI["ML-API Video Summarizer"]:::service
    end

    %% Data Layer
    subgraph "Data Layer"
        direction TB
        Postgres["PostgreSQL"]:::data
        Redis["Redis Cache"]:::data
        S3["AWS S3"]:::data
        Firebase["Firebase Auth & Firestore"]:::data
        StaticCareer["Static Career Paths JSON"]:::data
        PublicAssets["Public Static Assets"]:::data
        ExtBlocked["Extension Blocked Page"]:::data
    end

    %% External AI Services
    subgraph "External AI Services"
        direction TB
        OpenAI["OpenAI / LangChain"]:::external
        GCloud["Google Cloud ML"]:::external
    end

    %% Hosting & CI/CD
    subgraph "Hosting & CI/CD"
        direction TB
        Vercel["Vercel (Frontend)"]:::hosting
        Docker["Docker / Kubernetes"]:::hosting
    end

    %% Connections
    User -->|"HTTPS"| WebApp
    User -->|"HTTPS"| BrowserExt
    WebApp -->|"REST/GraphQL"| APIGateway
    BrowserExt -->|"REST"| APIGateway
    APIGateway -->|"SQL queries"| Postgres
    APIGateway -- "Cache get/set" --> Redis
    APIGateway -->|"Upload/download"| S3
    APIGateway -->|"HTTP/gRPC"| FastAPI
    APIGateway -->|"HTTP"| MLAPI
    APIGateway -->|"Auth & DB"| Firebase

    FastAPI -->|"calls"| OpenAI
    MLAPI -->|"calls"| GCloud

    WebApp --> Vercel
    APIGateway --> Docker
    FastAPI --> Docker
    MLAPI --> Docker

    %% Click Events
    click WebApp "https://github.com/itzzgaurav7/sage-zingguru/tree/main/Frontend/"
    click BrowserExt "https://github.com/itzzgaurav7/sage-zingguru/tree/main/extension/"
    click APIGateway "https://github.com/itzzgaurav7/sage-zingguru/tree/main/Backend/"
    click FastAPI "https://github.com/itzzgaurav7/sage-zingguru/blob/main/Fast-API/RAG/app.py"
    click MLAPI "https://github.com/itzzgaurav7/sage-zingguru/blob/main/ML-API/Video-summarizer/main.py"
    click StaticCareer "https://github.com/itzzgaurav7/sage-zingguru/blob/main/data/career_paths.json"
    click PublicAssets "https://github.com/itzzgaurav7/sage-zingguru/tree/main/Frontend/public/"
    click ExtBlocked "https://github.com/itzzgaurav7/sage-zingguru/blob/main/extension/blocked.html"

    %% Styles
    classDef presentation fill:#D0E8FF,stroke:#0366D6,color:#0366D6;
    classDef api fill:#E8D0FF,stroke:#7209B7,color:#7209B7;
    classDef service fill:#D0FFD8,stroke:#008000,color:#008000;
    classDef data fill:#FFE8D0,stroke:#FF8C00,color:#FF8C00;
    classDef external fill:#F0F0F0,stroke:#666666,color:#666666;
    classDef hosting fill:#FFF5BA,stroke:#E7A600,color:#E7A600;
```
