# nikhil-doye/ai-memory architecture

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

- Interactive diagram: https://gitdiagram.com/nikhil-doye/ai-memory
- Repository: https://github.com/nikhil-doye/ai-memory

## Overview

##### Project Type and Purpose
- This is a full-stack semantic memory management platform.
- Frontend: React + Vite for interactive graph visualization and memory management UI.
- Backend: FastAPI (Python) exposing REST and SSE endpoints to handle memory CRUD, embedding generation, vector search, relationship inference.
- Data Stores: Neo4j (graph + native vector index) for memories & relationships, Redis for caching stats and hot data.
- External Service: Hugging Face Qwen3-Embedding model for vector embeddings.

##### File Structure
- Top-level:
- backend/ (main.py, requirements, tests, Dockerfile)
- frontend/ (App.jsx, index.html, Vite & Tailwind configs, Dockerfile, nginx.conf)
- docker-compose.yml orchestrates Neo4j, Redis, backend, frontend
- monitoring/ (prometheus.yml)
- Patterns & Config:
- MVC-style separation: frontend (view), backend (controller + business logic), database (model)
- “migrate.sh” for database migrations or schema initialization
- test_platform.py for integration smoke tests

##### README for Architectural Insights
- Describes key flows: memory creation, search, graph retrieval.
- Lists components: caching layer, SSE for real-time updates, PDF ingestion.

- Browser / Client UI (React + Vite)
- Web Server / API Layer (FastAPI container)
- Graph Database (Neo4j)
- Cache Layer (Redis)
- Embedding Service (Hugging Face model)
- Orchestration (Docker Compose network)
- Monitoring (Prometheus)

- User → React UI → HTTP(S) → FastAPI
- FastAPI → Bolt driver → Neo4j (graph operations + vector search)
- FastAPI ↔ Redis (GET/SET for statistics and SSE)
- FastAPI → Hugging Face Hub (embedding generation)
- FastAPI → SSE stream → React UI (real-time graph updates)
- Docker Compose connects all containers on a private network

c. Architectural Patterns & Principles:
- Layered architecture: presentation, application logic, data access.
- Cache-Aside pattern for Redis.
- Batch queries to Neo4j for performance.
- Event-driven updates (SSE) for live UI refresh.
- Separation of concerns: PDF ingestion, embedding, relationship inference isolated in backend modules.

d. Key Technologies & Frameworks:
- React + Vite + Tailwind CSS (+ nginx)
- FastAPI + Pydantic + uvicorn
- Neo4j 5.x with vector search
- Redis in-memory cache
- Docker & Docker Compose
- Prometheus for metrics

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "Infrastructure (Docker Compose)" 
        direction TB
        DockerCompose["docker-compose.yml"]:::infra

        subgraph "Frontend Layer"
            direction TB
            Browser["Browser (User)"]:::ui
            Nginx["nginx (Static Server)"]:::ui
            ReactApp["React + Vite App"]:::ui
            HTMLTemplate["index.html"]:::ui
        end

        subgraph "Backend Layer"
            direction TB
            FastAPI["FastAPI API Server"]:::service
            Redis["Redis Cache"]:::datastore
            Neo4j["Neo4j Graph DB"]:::datastore
            HuggingFace["Hugging Face Embedding"]:::external
        end

        Migrate["Database Migration Script"]:::infra
        SmokeTest["End-to-End Smoke Test"]:::infra
        Prometheus["Prometheus Monitoring"]:::infra
    end

    %% Connections
    Browser -->|"HTTP 80"| Nginx
    Nginx -->|"Serves Assets"| HTMLTemplate
    HTMLTemplate -->|"Loads App"| ReactApp
    ReactApp -->|"HTTP 5173 /api"| FastAPI
    ReactApp -.->|"SSE /api/stream"| FastAPI
    FastAPI -->|"Bolt 7687"| Neo4j
    FastAPI -->|"GET/SET 6379"| Redis
    Redis -->|"Cache Hits/Misses"| FastAPI
    FastAPI -->|"HTTP (REST) "| HuggingFace
    Migrate -->|"Initializes"| Neo4j
    SmokeTest -->|"Tests API"| FastAPI
    Prometheus -->|"Scrapes Metrics"| FastAPI
    Prometheus -->|"Scrapes Metrics"| Redis
    Prometheus -->|"Scrapes Metrics"| Neo4j

    %% Click Events
    click ReactApp "https://github.com/nikhil-doye/ai-memory/blob/main/frontend/src/App.jsx"
    click HTMLTemplate "https://github.com/nikhil-doye/ai-memory/blob/main/frontend/index.html"
    click Nginx "https://github.com/nikhil-doye/ai-memory/blob/main/frontend/nginx.conf"
    click FastAPI "https://github.com/nikhil-doye/ai-memory/blob/main/backend/main.py"
    click Redis "https://github.com/nikhil-doye/ai-memory/blob/main/docker-compose.yml"
    click Neo4j "https://github.com/nikhil-doye/ai-memory/blob/main/docker-compose.yml"
    click HuggingFace "https://github.com/nikhil-doye/ai-memory/blob/main/backend/requirements.txt"
    click Migrate "https://github.com/nikhil-doye/ai-memory/blob/main/migrate.sh"
    click SmokeTest "https://github.com/nikhil-doye/ai-memory/blob/main/test_platform.py"
    click Prometheus "https://github.com/nikhil-doye/ai-memory/blob/main/monitoring/prometheus.yml"
    click DockerCompose "https://github.com/nikhil-doye/ai-memory/blob/main/docker-compose.yml"

    %% Styles
    classDef ui fill:#D0E6FF,stroke:#000;
    classDef service fill:#D0FFD6,stroke:#000;
    classDef datastore fill:#FFE9C6,stroke:#000;
    classDef external fill:#E5E5E5,stroke:#000;
    classDef infra fill:#EAD4EA,stroke:#000,stroke-dasharray: 5 5;
```
