# suryanshgupta9933/scene-sense architecture

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

- Interactive diagram: https://gitdiagram.com/suryanshgupta9933/scene-sense
- Repository: https://github.com/suryanshgupta9933/scene-sense

## Overview

##### Project Type and Purpose
- Scene Sense is a full-stack application that includes a web-based UI (via FastAPI endpoints) and backend processing for image search.
- Key functional areas include AI-powered search (using CLIP), user authentication (with JWT and MongoDB), image storage (on Google Cloud Platform), and embedding management (using Pinecone).

##### File Structure
- Top-Level Directories and Files:
- The “app” directory contains API endpoint definitions for various user interactions (e.g., home, gallery, login, signup, search, upload).
- The “API” directory holds API modules for core functionalities such as “clip.py” (for interfacing with the CLIP model) and “user_auth.py” (for authentication routines).
- The “cloud” directory handles cloud-related tasks, including storage, indexing, and upload operations (implying integration with Google Cloud Platform).
- The “connections” directory abstracts external service integrations, specifically with GCP, MongoDB, and Pinecone.
- Other files such as “routes.py”, “scene_sense_app.py”, and Docker-related files indicate how services are orchestrated and containerized.
- The “utils” directory contains helper functions such as embeddings calculations, image fetching, and other utilities.
- The “tests” directory is for unit/integration tests ensuring maintainability.

##### Identifying the Main Components and Their Interactions
a. UI/API Layer:
- Represented by the “app” folder, which houses endpoints (gallery, home, login, signup, search, upload) responsible for handling HTTP requests.
- “routes.py” likely aggregates these endpoints.

b. Core Services / Business Logic:
- The “API” folder is used to encapsulate core processing logic such as interacting with the CLIP model (clip.py) and performing user authentication (user_auth.py).
- These services are triggered by the API layer and in turn handle business logic for search and authentication.

c. Cloud Integration:
- The “cloud” module handles storage (cloud/storage.py), cloud indexing (cloud/index.py), and file uploads (cloud/upload.py). It’s key for image handling and persistent asset storage.

d. External Connections:
- The “connections” directory provides modules for:
- MongoDB for storing user credentials (connections/mongo_db.py)
- Google Cloud Platform integration (connections/gcp.py)
- Pinecone for managing vector embeddings (connections/pinecone.py)

e. Utilities & Testing:
- Utility functions (in “utils”) support image processing, embedding computation, and other helper operations.
- “tests” ensure that major functionalities perform correctly.

##### Architectural Patterns and Design Principles
- Separation of Concerns: UI routings, API core logic, cloud integrations, and external connection handling are segregated into different modules.
- Microservices/Modular Design: Although the project is a proof-of-concept, its modular file organization supports easier scalability and possible future microservices-like deployments.
- Containerization: The presence of Dockerfiles and docker-compose indicates the use of containerization to achieve consistent deployments.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% UI/API Layer
    subgraph "UI/API Layer"
        A1["Gallery Endpoint"]:::ui
        A2["Home Endpoint"]:::ui
        A3["Login Endpoint"]:::ui
        A4["Signup Endpoint"]:::ui
        A5["Search Endpoint"]:::ui
        A6["Upload Endpoint"]:::ui
        A7["Aggregated Routes"]:::ui
    end

    %% Core Services / Business Logic
    subgraph "Core Services / Business Logic"
        B1["CLIP Integration Module"]:::core
        B2["User Authentication Module"]:::core
    end

    %% Cloud Integration
    subgraph "Cloud Integration"
        C1["Cloud Storage & Upload Service"]:::cloud
        C2["Cloud Indexing Service"]:::cloud
    end

    %% External Connections
    subgraph "External Connections"
        D1["Google Cloud Integration"]:::external
        D2["MongoDB Connection"]:::external
        D3["Pinecone Integration"]:::external
    end

    %% Utilities & Testing
    subgraph "Utilities & Testing"
        E1["Utility Functions"]:::utility
        E2["Testing Suite"]:::testing
    end

    %% Data Flows
    A1 --> A7
    A2 --> A7
    A3 --> A7
    A4 --> A7
    A5 --> A7
    A6 --> A7

    A7 --> B1
    A7 --> B2

    B1 --> C2
    B1 --> C1
    B2 --> D2
    B2 --> D3

    C1 --> D1

    %% Supporting utilities
    E1 --- B1
    E1 --- C1
    E1 --- D2
    E2 --- B1
    E2 --- B2

    %% Styling
    classDef ui fill:#ffcc00,stroke:#333,stroke-width:2px;
    classDef core fill:#ff9999,stroke:#333,stroke-width:2px;
    classDef cloud fill:#99ccff,stroke:#333,stroke-width:2px;
    classDef external fill:#ccffcc,stroke:#333,stroke-width:2px;
    classDef utility fill:#cccccc,stroke:#333,stroke-width:2px;
    classDef testing fill:#ffccff,stroke:#333,stroke-width:2px;

    %% Click Events for UI/API Layer
    click A1 "https://github.com/suryanshgupta9933/scene-sense/blob/main/app/gallery.py"
    click A2 "https://github.com/suryanshgupta9933/scene-sense/blob/main/app/home.py"
    click A3 "https://github.com/suryanshgupta9933/scene-sense/blob/main/app/login.py"
    click A4 "https://github.com/suryanshgupta9933/scene-sense/blob/main/app/signup.py"
    click A5 "https://github.com/suryanshgupta9933/scene-sense/blob/main/app/search.py"
    click A6 "https://github.com/suryanshgupta9933/scene-sense/blob/main/app/upload.py"
    click A7 "https://github.com/suryanshgupta9933/scene-sense/blob/main/routes.py"

    %% Click Events for Core Services / Business Logic
    click B1 "https://github.com/suryanshgupta9933/scene-sense/blob/main/API/clip.py"
    click B2 "https://github.com/suryanshgupta9933/scene-sense/blob/main/API/user_auth.py"

    %% Click Events for Cloud Integration
    click C1 "https://github.com/suryanshgupta9933/scene-sense/blob/main/cloud/storage.py"
    click C2 "https://github.com/suryanshgupta9933/scene-sense/blob/main/cloud/index.py"

    %% Click Events for External Connections
    click D1 "https://github.com/suryanshgupta9933/scene-sense/blob/main/connections/gcp.py"
    click D2 "https://github.com/suryanshgupta9933/scene-sense/blob/main/connections/mongo_db.py"
    click D3 "https://github.com/suryanshgupta9933/scene-sense/blob/main/connections/pinecone.py"

    %% Click Events for Utilities & Testing
    click E1 "https://github.com/suryanshgupta9933/scene-sense/blob/main/utils/embeddings.py"
    click E2 "https://github.com/suryanshgupta9933/scene-sense/blob/main/tests/__init__.py"
```
