How davincidreams/ai-notes works
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