# jashwanth0725/snap-tune architecture

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

- Interactive diagram: https://gitdiagram.com/jashwanth0725/snap-tune
- Repository: https://github.com/jashwanth0725/snap-tune

## Overview

##### Project Type and Purpose
- This is a full-stack SaaS application (“AI Caption Generator”) that lets authenticated users upload an image and receive AI-generated captions. It includes a React + TypeScript client, a Node.js + Express backend, MongoDB for persistence, Firebase for authentication, Stripe for payments, Cloudinary for image storage, and an external AI integration (Gemini).

##### File Structure Analysis
- Top-Level Directories
- `/client` – Frontend (React, Vite, Tailwind CSS, TypeScript)
- `/server` – Backend (Express, Mongoose, AI API integrations)
- Backend Patterns
- `/server/src/routes` → REST endpoints
- `/server/src/controllers` → Business logic & orchestration
- `/server/src/models` → Mongoose schemas for users, history, captions, payments
- `/server/src/apis` → External AI service calls (caption.api.js, summary.api.js)
- `/server/src/middlewares` → Auth, file‐upload (Multer)
- Layered MVC + service integration pattern
- Frontend Patterns
- `/client/src/api` → wrappers for backend calls (caption, summary, stripe)
- `/client/src/auth` → Firebase auth + protected routes
- `/client/src/components` → UI & AI components
- `/client/src/db` → client-side caching/state
- `/client/src/layout`, `/client/src/pages` → routing & page structure

##### Key Insights from README
- Workflow: user signs up/logs in → uploads image → backend calls Gemini AI → caption returned → optional save (MongoDB) → payment checks (Stripe)
- Tech stack calls out all external services: Firebase Auth, Stripe, Cloudinary, Gemini AI
- Scalability & history tracking are core non-functional requirements

##### Main Components
- User Interface Layer
- React Client (Browser)
- Firebase Auth widget
- API Layer
- Express REST API (Routes → Controllers → Services)
- Business Logic Layer
- CaptionController invokes Gemini via CaptionAPI
- HistoryController reads/writes MongoDB
- StripeController handles payment workflows
- Data Layer
- MongoDB (hosted in the cloud)
- Cloudinary for image storage
- External Services
- Gemini AI service
- Firebase Auth service
- Stripe payment gateway

##### Relationships & Data Flows
- Express → Gemini AI API → response back to Controller → HTTP response back to UI
- Save/retrieve operations: Controller ↔ MongoDB
- Image upload flow: Browser → Cloudinary (via backend or direct signed upload) → stored URL → backend
- Auth flow: React ↔ Firebase Auth → JWT passed in header to Express → auth.middleware
- Payment flow: React ↔ Stripe SDK → backend StripeController → Stripe API

##### Architectural Patterns & Principles
- Layered MVC on the server (Routes → Controllers → Models)
- Separation of concerns: UI, API gateway, business logic, persistence, external integrations
- Stateless REST endpoints, token-based auth via Firebase
- Single Responsibility in controllers/services

##### Detail-Level Recommendations
- Zoom into critical flows: Image upload → Caption generation → Save to history
- Rate limits or free-tier checks (20 free uses)
- Call out middleware steps: auth.middleware, multer.middleware

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend" 
        direction TB
        ReactApp["React App (Browser)"]:::frontend
        FirebaseWidget["Firebase Auth Widget"]:::frontend
        ProtectedRoute["ProtectedRoute (Auth)"]:::frontend
        StripeProvider["Stripe.js Provider"]:::frontend
        subgraph "API Wrappers"
            direction TB
            CaptionAPI["Caption API Wrapper"]:::frontend
            SummaryAPI["Summary API Wrapper"]:::frontend
            StripeAPI["Stripe API Wrapper"]:::frontend
        end
        subgraph "AI UI Components"
            direction TB
            CaptionComponent["Caption Component"]:::frontend
            SummaryComponent["Summary Component"]:::frontend
        end
        UILibrary["UI Library Components"]:::frontend
        Pages["React Pages & Routing"]:::frontend
    end

    %% Backend Layer
    subgraph "Backend"
        direction TB
        ExpressEntry["Express App (app.js)"]:::backend
        HTTPServer["HTTP Server (index.js)"]:::backend
        subgraph "Middlewares"
            direction TB
            AuthMiddleware["Firebase Auth Middleware"]:::backend
            MulterMiddleware["File Upload Middleware"]:::backend
        end
        subgraph "Routes"
            direction TB
            GenerateRoute["/generate Routes"]:::backend
            StripeRoute["/stripe Routes"]:::backend
            UserRoute["/user Routes"]:::backend
        end
        subgraph "Controllers"
            direction TB
            GenerateCtrl["Generate Controller"]:::backend
            HistoryCtrl["History Controller"]:::backend
            StripeCtrl["Stripe Controller"]:::backend
            UserCtrl["User Controller"]:::backend
            DBCtrl["Database Controller"]:::backend
        end
        subgraph "APIs"
            direction TB
            GeminiCaptionAPI["Gemini Caption API"]:::backend
            GeminiSummaryAPI["Gemini Summary API"]:::backend
        end
        subgraph "Models"
            direction TB
            UserModel["User Model"]:::backend
            CaptionModel["Caption Model"]:::backend
            SummaryModel["Summary Model"]:::backend
            HistoryModel["History Model"]:::backend
            PaymentModel["Payment Model"]:::backend
        end
        DBConnection["DB Connection Setup"]:::backend
        subgraph "Utils"
            direction TB
            CloudinaryUtil["Cloudinary Helper"]:::backend
            ApiError["API Error Formatter"]:::backend
            ApiResponse["API Response Formatter"]:::backend
            AsyncHandler["Async Handler"]:::backend
            Base64Util["ImageBase64 Helper"]:::backend
            TranscriptUtil["YouTube Transcript Helper"]:::backend
        end
    end

    %% Data Stores
    subgraph "Data Stores"
        direction TB
        MongoDB["MongoDB (Cloud)"]:::datastore
        Cloudinary["Cloudinary Storage"]:::datastore
    end

    %% External Services
    subgraph "External Services"
        direction TB
        GeminiAI["Gemini AI Service"]:::external
        FirebaseAuthService["Firebase Auth Service"]:::external
        StripeGateway["Stripe Payment Gateway"]:::external
    end

    %% Connections
    ReactApp -->|"POST /generate"| ExpressEntry
    ReactApp -->|"Authenticate"| FirebaseAuthService
    ReactApp -->|"Stripe SDK"| StripeGateway
    ReactApp --> CaptionAPI
    ReactApp --> SummaryAPI
    ReactApp --> StripeAPI
    ReactApp --> FirebaseWidget
    ReactApp --> ProtectedRoute
    ReactApp --> StripeProvider
    ReactApp --> CaptionComponent
    ReactApp --> SummaryComponent
    ReactApp --> UILibrary
    ReactApp --> Pages

    ExpressEntry --> HTTPServer
    ExpressEntry --> AuthMiddleware
    ExpressEntry --> MulterMiddleware
    ExpressEntry --> GenerateRoute
    ExpressEntry --> StripeRoute
    ExpressEntry --> UserRoute
    ExpressEntry --> DBConnection

    GenerateRoute --> GenerateCtrl
    StripeRoute --> StripeCtrl
    UserRoute --> UserCtrl

    GenerateCtrl --> GeminiCaptionAPI
    GenerateCtrl --> GeminiAI
    GenerateCtrl --> CaptionModel
    GenerateCtrl --> HistoryModel

    HistoryCtrl --> HistoryModel
    HistoryCtrl --> MongoDB

    StripeCtrl --> StripeGateway
    StripeCtrl --> PaymentModel

    UserCtrl --> UserModel
    UserCtrl --> MongoDB

    DBConnection --> MongoDB

    MulterMiddleware --> Cloudinary
    CloudinaryUtil --> Cloudinary

    GeminiCaptionAPI --> GeminiAI
    GeminiSummaryAPI --> GeminiAI

    ApiError --> GenerateCtrl
    ApiResponse --> GenerateCtrl
    AsyncHandler --> GenerateCtrl
    Base64Util --> GenerateCtrl
    TranscriptUtil --> GenerateCtrl

    %% Click Events - Frontend
    click ReactApp "https://github.com/jashwanth0725/snap-tune/blob/main/client/src/App.tsx"
    click FirebaseWidget "https://github.com/jashwanth0725/snap-tune/blob/main/client/src/auth/firebase.auth.tsx"
    click ProtectedRoute "https://github.com/jashwanth0725/snap-tune/blob/main/client/src/auth/protectedRoute.tsx"
    click StripeProvider "https://github.com/jashwanth0725/snap-tune/blob/main/client/src/lib/stripe.provider.tsx"
    click CaptionAPI "https://github.com/jashwanth0725/snap-tune/blob/main/client/src/api/caption.api.tsx"
    click SummaryAPI "https://github.com/jashwanth0725/snap-tune/blob/main/client/src/api/summary.api.tsx"
    click StripeAPI "https://github.com/jashwanth0725/snap-tune/blob/main/client/src/api/stripe.api.tsx"
    click CaptionComponent "https://github.com/jashwanth0725/snap-tune/blob/main/client/src/components/ai/caption.tsx"
    click SummaryComponent "https://github.com/jashwanth0725/snap-tune/blob/main/client/src/components/ai/summary.tsx"
    click UILibrary "https://github.com/jashwanth0725/snap-tune/tree/main/client/src/components/ui"
    click Pages "https://github.com/jashwanth0725/snap-tune/tree/main/client/src/pages"

    %% Click Events - Backend
    click ExpressEntry "https://github.com/jashwanth0725/snap-tune/blob/main/Server/src/app.js"
    click HTTPServer "https://github.com/jashwanth0725/snap-tune/blob/main/Server/src/index.js"
    click GenerateRoute "https://github.com/jashwanth0725/snap-tune/blob/main/Server/src/routes/generate.routes.js"
    click StripeRoute "https://github.com/jashwanth0725/snap-tune/blob/main/Server/src/routes/stripes.routes.js"
    click UserRoute "https://github.com/jashwanth0725/snap-tune/blob/main/Server/src/routes/user.routes.js"
    click GenerateCtrl "https://github.com/jashwanth0725/snap-tune/blob/main/Server/src/controllers/generate.controller.js"
    click HistoryCtrl "https://github.com/jashwanth0725/snap-tune/blob/main/Server/src/controllers/history.controller.js"
    click StripeCtrl "https://github.com/jashwanth0725/snap-tune/blob/main/Server/src/controllers/stripe.controller.js"
    click UserCtrl "https://github.com/jashwanth0725/snap-tune/blob/main/Server/src/controllers/user.controller.js"
    click DBCtrl "https://github.com/jashwanth0725/snap-tune/blob/main/Server/src/controllers/database.controller.js"
    click UserModel "https://github.com/jashwanth0725/snap-tune/blob/main/Server/src/models/user.model.js"
    click CaptionModel "https://github.com/jashwanth0725/snap-tune/blob/main/Server/src/models/caption.model.js"
    click SummaryModel "https://github.com/jashwanth0725/snap-tune/blob/main/Server/src/models/summary.model.js"
    click HistoryModel "https://github.com/jashwanth0725/snap-tune/blob/main/Server/src/models/history.model.js"
    click PaymentModel "https://github.com/jashwanth0725/snap-tune/blob/main/Server/src/models/payment.model.js"
    click GeminiCaptionAPI "https://github.com/jashwanth0725/snap-tune/blob/main/Server/src/apis/caption.api.js"
    click GeminiSummaryAPI "https://github.com/jashwanth0725/snap-tune/blob/main/Server/src/apis/summary.api.js"
    click AuthMiddleware "https://github.com/jashwanth0725/snap-tune/blob/main/Server/src/middlewares/auth.middleware.js"
    click MulterMiddleware "https://github.com/jashwanth0725/snap-tune/blob/main/Server/src/middlewares/multer.middleware.js"
    click DBConnection "https://github.com/jashwanth0725/snap-tune/blob/main/Server/src/db/index.js"
    click CloudinaryUtil "https://github.com/jashwanth0725/snap-tune/blob/main/Server/src/utils/cloudinary.js"
    click ApiError "https://github.com/jashwanth0725/snap-tune/blob/main/Server/src/utils/ApiError.js"
    click ApiResponse "https://github.com/jashwanth0725/snap-tune/blob/main/Server/src/utils/ApiResponse.js"
    click AsyncHandler "https://github.com/jashwanth0725/snap-tune/blob/main/Server/src/utils/asyncHandler.js"
    click Base64Util "https://github.com/jashwanth0725/snap-tune/blob/main/Server/src/utils/ImageBase64.js"
    click TranscriptUtil "https://github.com/jashwanth0725/snap-tune/blob/main/Server/src/utils/youtube.transcripts.js"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#333,stroke-width:1px
    classDef backend fill:#D0FFD0,stroke:#333,stroke-width:1px
    classDef datastore fill:#FFE0B2,stroke:#333,stroke-width:1px
    classDef external fill:#E1D5FF,stroke:#333,stroke-width:1px
```
