# manojmadduri/ai-memory-clone architecture

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

- Interactive diagram: https://gitdiagram.com/manojmadduri/ai-memory-clone
- Repository: https://github.com/manojmadduri/ai-memory-clone

## Overview

##### Project Overview
- This is a full-stack application that builds a personal AI capable of memory recall, semantic search, and image processing.
- The system is split between a React-based frontend styled with Tailwind CSS and a FastAPI-based backend written in Python.
- Additional functionalities include integration with face recognition, image ingestion, and memory processing powered by GPT and semantic embeddings.
- The project leverages Supabase (PostgreSQL and Storage) as its database and storage solution.

##### Main Components
a. Frontend:
- A “Frontend (React + Tailwind)” component.
- Elements inside include pages such as Chat, Home, MemoryView, People, Timeline, and Upload.
- Connects to the backend via HTTP API calls (using Axios/CORS as mentioned in the README).

b. Backend:
- A “Backend (FastAPI)” component.
- Detail modular sub-components:
- main.py – the API entry point.
- Memory Manager (memory_manager.py) – handles storing and retrieving memory embeddings.
- GPT Response (gpt_response.py) – responsible for chat responses and context generation.
- Image Ingestion (image_ingestion.py) – processes images, applies face recognition (utilizing face_recognition/dlib) and caption generation.
- Additional utilities (face_utils.py, cluster_utils.py, timeline_utils.py) – manage specialized tasks such as face recognition and memory clustering based on timeline or person.
- Bulk Memory Import (bulk_memory_import.py) – for importing large numbers of memories from a text file.
- Supabase Integration (supabase_client.py) – for interaction with Supabase storage and database.
- Personal memories file (personal_memories.txt) acting as a local store for bulk import scenarios.

c. Database and External Services:
- A “Database” (Supabase with PostgreSQL) component.
- Links from the backend to Supabase for memory storage.
- Optionally, note integration with external AI services such as GPT (via OpenAI API or a local model) and sentence-transformers for text embedding.
- Image-related storage (Supabase Storage) for processed images.

##### Relationships and Data Flow
- Data flow from the Frontend (user actions and API requests) → Backend endpoints.
- Backend interactions with the Database for memory retrieval, storage of embeddings, and image metadata.
- Functional flow within the backend that calls specialized modules (e.g., image_ingestion processing images and then invoking Supabase).
- Cycle between the GPT module and memory manager – input user query triggers memory retrieval, which then informs GPT’s response.

##### Architectural Patterns & Technologies
- Separation of concerns between frontend and backend.
- Integration points: APIs for chat and memory APIs, image processing endpoints, and potential callbacks to external AI models.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend
    subgraph "Frontend Layer"
        FE["Frontend (React + Tailwind)"]:::frontend
        FE1["Chat Page"]:::frontend
        FE2["Home Page"]:::frontend
        FE3["MemoryView Page"]:::frontend
        FE4["People Page"]:::frontend
        FE5["Timeline Page"]:::frontend
        FE6["Upload Page"]:::frontend
    end

    %% Backend
    subgraph "Backend Layer (FastAPI)"
        API["API Entry (main.py)"]:::backend
        MM["Memory Manager"]:::backend
        GPT["GPT Response"]:::backend
        II["Image Ingestion"]:::backend
        BM["Bulk Memory Import"]:::backend
        SI["Supabase Integration"]:::backend
        LS["Local Memory Store"]:::backend
        subgraph "Utilities Modules"
            FU["Face Utils"]:::backend
            CU["Cluster Utils"]:::backend
            TU["Timeline Utils"]:::backend
        end
    end

    %% Database & External Services
    DB["Database (Supabase)"]:::database

    %% Connections from Frontend to Backend
    FE -->|"HTTP_API"| API
    FE1 -->|"Routes"| FE
    FE2 -->|"Routes"| FE
    FE3 -->|"Routes"| FE
    FE4 -->|"Routes"| FE
    FE5 -->|"Routes"| FE
    FE6 -->|"Routes"| FE

    %% Backend internal connections
    API -->|"handles"| MM
    API -->|"handles"| GPT
    API -->|"handles"| II
    MM <-->|"cycle"| GPT
    II -->|"processes"| SI
    BM --> LS
    BM -->|"updates"| DB

    %% Backend to Database connections
    MM -->|"reads/writes"| DB
    GPT -->|"accesses memories"| DB
    SI -->|"stores data"| DB

    %% Click Events for Frontend
    click FE "https://github.com/manojmadduri/ai-memory-clone/tree/main/frontend/"
    click FE1 "https://github.com/manojmadduri/ai-memory-clone/blob/main/frontend/src/pages/Chat.js"
    click FE2 "https://github.com/manojmadduri/ai-memory-clone/blob/main/frontend/src/pages/Home.js"
    click FE3 "https://github.com/manojmadduri/ai-memory-clone/blob/main/frontend/src/pages/MemoryView.js"
    click FE4 "https://github.com/manojmadduri/ai-memory-clone/blob/main/frontend/src/pages/People.js"
    click FE5 "https://github.com/manojmadduri/ai-memory-clone/blob/main/frontend/src/pages/Timeline.js"
    click FE6 "https://github.com/manojmadduri/ai-memory-clone/blob/main/frontend/src/pages/Upload.js"

    %% Click Events for Backend
    click API "https://github.com/manojmadduri/ai-memory-clone/blob/main/backend/main.py"
    click MM "https://github.com/manojmadduri/ai-memory-clone/blob/main/backend/memory_manager.py"
    click GPT "https://github.com/manojmadduri/ai-memory-clone/blob/main/backend/gpt_response.py"
    click II "https://github.com/manojmadduri/ai-memory-clone/blob/main/backend/image_ingestion.py"
    click BM "https://github.com/manojmadduri/ai-memory-clone/blob/main/backend/bulk_memory_import.py"
    click SI "https://github.com/manojmadduri/ai-memory-clone/blob/main/backend/supabase_client.py"
    click FU "https://github.com/manojmadduri/ai-memory-clone/blob/main/backend/face_utils.py"
    click CU "https://github.com/manojmadduri/ai-memory-clone/blob/main/backend/cluster_utils.py"
    click TU "https://github.com/manojmadduri/ai-memory-clone/blob/main/backend/timeline_utils.py"
    click LS "https://github.com/manojmadduri/ai-memory-clone/blob/main/backend/personal_memories.txt"

    %% Styles
    classDef frontend fill:#cce5ff,stroke:#333,stroke-width:2px;
    classDef backend fill:#d4edda,stroke:#333,stroke-width:2px;
    classDef database fill:#fff3cd,stroke:#333,stroke-width:2px;
```
