# davincidreams/ai-notes architecture

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

- Interactive diagram: https://gitdiagram.com/davincidreams/ai-notes
- Repository: https://github.com/davincidreams/ai-notes

## Overview

##### Project type and purpose
- This is a full-stack, self-hosted collaborative knowledge management web application (“AI Notes”) combining real-time rich text editing, drawing, voice integration, AI-powered search, and a knowledge graph.
- Key goals: collaborative editing (Yjs/Hocuspocus), AI services (local LLMs via Ollama, Whisper), document management, visualization (knowledge graph), semantic search.

##### File structure highlights
- Top level:
- Dockerfiles (backend, frontend, collaboration) + docker-compose.yml/databases → containerized microservices.
- server/ → Node.js/Express API, routes/, services/, middleware/, database.ts, WebSocket collaboration entrypoints.
- src/ → React 18 + TypeScript frontend, components/, hooks/, contexts/, services/, Vite config.
- Public/ + index.html + nginx.conf → static assets and reverse proxy config.
- Test scripts (test-*.js/.ps1) for voice, transcription, API.

##### README-driven architecture
- Frontend: React + Vite + Tailwind + React Query + React Router.
- Backend: Node.js/Express (REST API), FastAPI (Python) for heavy AI workloads, WebSocket server (Yjs + Hocuspocus).
- Datastores: PostgreSQL, Neo4j, Elasticsearch, Redis, MinIO.
- AI/ML: Ollama (Llama models), Whisper (speech-to-text), browser TTS.
- Infrastructure: Docker Compose to orchestrate all containers.

##### Main components and interactions
a. Frontend SPA (React/Vite)
- Communicates via REST/HTTP to API Server (port 3001)
- Opens WebSocket to Collaboration Server (port 1234) for real-time editing
- Invokes voice APIs (Whisper) via backend or direct browser TTS
b. API Server (Node.js/Express)
- Routes: auth, documents, ingestion, enhanced ingestion, knowledgeGraph, search, upload
- Services layer: aiService, authService, dataIngestionService, enhancedIngestionService, knowledgeGraphService, searchService
- Persists to PostgreSQL (documents, users), writes to Neo4j (graph), indexes to Elasticsearch, caches/sessions in Redis, stores files/attachments in MinIO
- Proxies AI calls to FastAPI service or directly to Ollama (LLM inference) and Whisper for transcription
c. Collaboration Server (TypeScript)
- Yjs/Hocuspocus WebSocket server for CRDT-based real-time collaborative editing
- Persists document updates or syncs via API Server endpoints or directly to MongoDB/Redis (depending on implementation)
d. AI Microservice (FastAPI/Python)
- Exposes endpoints for LLM inference (Ollama), speech-to-text (Whisper)
- Returns embeddings, entity extraction, suggestions to API Server
e. External/Infrastructure
- Ollama endpoint (localhost:11434)
- Whisper models (local)
- MinIO for object storage
- Docker network connecting all services
f. Databases
- PostgreSQL (primary relational store)
- Neo4j (graph data)
- Elasticsearch (full-text & semantic search)
- Redis (cache, sessions)

##### Architectural patterns & principles
- Microservices: separate containers for frontend, backend REST API, WebSocket collaboration, AI service.
- Layered architecture: controllers/routes → services → data layer.
- Eventual consistency: ingestion → indexing → graph extraction pipelines.
- CRDT for conflict-free real-time collaboration (Yjs).
- Container-first DevOps with Docker Compose.

##### Final checklist
- All major components (Frontend, API, Collaboration, AI, Datastores, External) present
- Architectural patterns noted (microservices, CRDT, pipelines)
- Deployment context (Docker Compose) indicated

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Docker host boundary
    subgraph "Docker Host"
        direction TB

        %% Frontend Container
        subgraph "Frontend Container"
            direction TB
            FE["Frontend SPA<br>(React/Vite)<br>Port 5173"]:::ui

            subgraph "Editor"
                ED["Document Editor"]:::ui
            end
            subgraph "Knowledge Graph"
                KG["KnowledgeGraph.tsx"]:::ui
            end
            subgraph "Semantic Search"
                SS["SmartSearch.tsx"]:::ui
            end
            subgraph "Voice Integration"
                VI["VoiceControls.tsx"]:::ui
            end
        end

        %% API Container
        subgraph "API Container"
            direction TB
            API["API Server<br>(Node.js/Express)<br>Port 3001"]:::backend
        end

        %% Collaboration Container
        subgraph "Collaboration Container"
            direction TB
            COL["Collaboration Server<br>(Yjs/Hocuspocus)<br>Port 1234"]:::collab
        end

        %% AI Container
        subgraph "AI Container"
            direction TB
            AI["AI Microservice<br>(FastAPI)"]:::ai
        end

        %% Datastores
        subgraph "Datastores"
            direction TB
            PG["PostgreSQL"]:::db
            NG["Neo4j"]:::db
            ES["Elasticsearch"]:::db
            RD["Redis"]:::db
            MI["MinIO"]:::db
        end
    end

    %% External Infra
    Oll["Ollama Endpoint"]:::ext
    Whi["Whisper Models"]:::ext

    %% Connections
    FE -->|"REST (HTTP)"| API
    FE -->|"WS" | COL
    API -->|"Reads/Writes"| PG
    API -->|"Graph writes/reads"| NG
    API -->|"Indexing"| ES
    API -->|"Cache/Sessions"| RD
    API -->|"Uploads/Downloads"| MI
    API -->|"HTTP RPC"| AI
    AI -->|"LLM Inference"| Oll
    AI -->|"Speech-to-Text"| Whi
    COL -->|"Sync ops"| API
    COL -->|"Persistence"| RD

    %% Frontend subcomponent connections
    FE --> ED
    FE --> KG
    FE --> SS
    FE --> VI

    %% Click events - Frontend
    click FE "https://github.com/davincidreams/ai-notes/tree/main/src/"
    click FE "https://github.com/davincidreams/ai-notes/blob/main/src/main.tsx"
    click FE "https://github.com/davincidreams/ai-notes/blob/main/src/App.tsx"
    click FE "https://github.com/davincidreams/ai-notes/blob/main/vite.config.ts"
    click FE "https://github.com/davincidreams/ai-notes/blob/main/Dockerfile.frontend"
    click ED "https://github.com/davincidreams/ai-notes/blob/main/src/components/Editor/CollaborativeEditor.tsx"
    click KG "https://github.com/davincidreams/ai-notes/blob/main/src/components/Graph/KnowledgeGraph.tsx"
    click SS "https://github.com/davincidreams/ai-notes/blob/main/src/components/Search/SmartSearch.tsx"
    click VI "https://github.com/davincidreams/ai-notes/blob/main/src/components/Voice/VoiceControls.tsx"
    click VI "https://github.com/davincidreams/ai-notes/blob/main/src/services/VoiceService.ts"

    %% Click events - API
    click API "https://github.com/davincidreams/ai-notes/tree/main/server/"
    click API "https://github.com/davincidreams/ai-notes/blob/main/server/index.ts"
    click API "https://github.com/davincidreams/ai-notes/blob/main/server/database.ts"
    click API "https://github.com/davincidreams/ai-notes/blob/main/server/routes/auth.ts"
    click API "https://github.com/davincidreams/ai-notes/blob/main/server/routes/documents.ts"
    click API "https://github.com/davincidreams/ai-notes/blob/main/server/routes/ingestion.ts"
    click API "https://github.com/davincidreams/ai-notes/blob/main/server/routes/enhancedIngestion.ts"
    click API "https://github.com/davincidreams/ai-notes/blob/main/server/routes/knowledgeGraph.ts"
    click API "https://github.com/davincidreams/ai-notes/blob/main/server/routes/search.ts"
    click API "https://github.com/davincidreams/ai-notes/blob/main/server/routes/upload.ts"
    click API "https://github.com/davincidreams/ai-notes/blob/main/server/routes/ai.ts"
    click API "https://github.com/davincidreams/ai-notes/blob/main/server/services/authService.ts"
    click API "https://github.com/davincidreams/ai-notes/blob/main/server/services/dataIngestionService.ts"
    click API "https://github.com/davincidreams/ai-notes/blob/main/server/services/enhancedIngestionService.ts"
    click API "https://github.com/davincidreams/ai-notes/blob/main/server/services/knowledgeGraphService.ts"
    click API "https://github.com/davincidreams/ai-notes/blob/main/server/services/searchService.ts"
    click API "https://github.com/davincidreams/ai-notes/blob/main/server/services/aiService.ts"
    click API "https://github.com/davincidreams/ai-notes/blob/main/server/middleware/auth.ts"
    click API "https://github.com/davincidreams/ai-notes/blob/main/Dockerfile.backend"

    %% Click events - Collab
    click COL "https://github.com/davincidreams/ai-notes/blob/main/server/collaboration.ts"
    click COL "https://github.com/davincidreams/ai-notes/blob/main/server/collaboration-simple.ts"
    click COL "https://github.com/davincidreams/ai-notes/blob/main/server/collaboration-minimal.ts"
    click COL "https://github.com/davincidreams/ai-notes/blob/main/Dockerfile.collaboration"

    %% Click events - Docker Compose & infra
    click Oll "https://github.com/davincidreams/ai-notes/blob/main/docker-compose.yml"
    click Oll "https://github.com/davincidreams/ai-notes/blob/main/docker-compose.databases.yml"
    click Oll "https://github.com/davincidreams/ai-notes/blob/main/nginx.conf"

    %% Styles
    classDef ui fill:#AEDFFF,stroke:#333,stroke-width:1px
    classDef backend fill:#A2F5A2,stroke:#333,stroke-width:1px
    classDef collab fill:#80FFD4,stroke:#333,stroke-width:1px
    classDef ai fill:#FFCC80,stroke:#333,stroke-width:1px
    classDef db fill:#D0B3FF,stroke:#333,stroke-width:1px
    classDef ext fill:#CCCCCC,stroke:#333,stroke-width:1px
```
