How existence-master/sentient works
Project Type & Purpose
• This is a self-hostable, full-stack Electron desktop application (“Sentient”) that embeds a Next.js/React UI (renderer & preload in Electron) talking to a Python FastAPI backend.
• It provides a proactive AI companion with long-term (Neo4j knowledge graph) and short-term (relational/SQLite) memory, voice interactions (WebRTC/STT/TTS), and integrations with external services (Google Workspace, web search, social-media scrapers, Ollama).
File Structure Analysis
• Top-level:
• .github (CI, issue/PR templates)
• src/client (Electron + Next.js UI, components, pages, main/preload, scripts, public assets, styles)
• src/server (Python/FastAPI app split into sub-modules: agents, chat, context, memory, voice, common utilities, tests)
• utils, startserv.sh (helper scripts)
• Architectural hints:
• src/client/main (Electron main process & IPC)
• src/client/app (Next.js pages) + components, hooks, utils → MVC/MVVM-style UI
• src/client/scripts (local servers like authServer, appServer, setupServer)
• src/server/app/app.py (FastAPI entry point)
• Modular Python packages for “agents”, “context”, “memory” → logical micro-layers
• Persistence: Neo4j (bolt config) + relational DB/SQLite (short-term memory)
• Voice: llama-cpp-python + Orpheus TTS, FasterWhisper for STT
• Async/task queues implied by “Memory and Task Queues” roadmap
Key README Insights
• Frontend tech: ElectronJS, Next.js, TailwindCSS
• Backend tech: FastAPI, Ollama, Neo4j, various Python scrapers/integrations
• Feature calls out dual-memory, autonomous agents, voice mode, web search, proactive context streams.
a. Main Components
• Electron Desktop Client
• Renderer (Next.js UI)
• Preload + IPC Bridge
• Main Process (manages windows, local servers)
• Client-side Local Servers
• appServer.js (serves UI or proxies to backend)
• authServer.js (Auth0 flow)
• WebRTC/WebSocket audio client
• FastAPI Backend
• API Facade (endpoints for chat, memory, agents)
• Business Logic Modules (agents, context, memory, chat)
• AI Model Servers
• Ollama HTTP API
• llama-cpp-python for voice
• Data Stores
• Neo4j Graph DB (long-term memory)
• SQLite / relational DB (short-term memory)
• External Services
• Google Workspace APIs (Gmail, Calendar, Drive, etc.)
• Brave Search API, Social-media scrapers (Reddit, LinkedIn, X)
• Internet Search
b. Relationships & Data Flow
• UI ↔ (IPC) ↔ Electron Main ↔ Client-side servers
• UI ↔ (HTTP/WebSocket) ↔ FastAPI Backend
• Backend ↔ (Bolt) ↔ Neo4j
• Backend ↔ (SQL) ↔ SQLite
• Backend ↔ (HTTP) ↔ Ollama / llama-cpp-python
• Backend ↔ (OAuth/REST) ↔ Google & other external APIs
• Voice stream: UI captures mic → WebRTC → Backend STT/TTS → UI audio output
c. Architectural Patterns & Principles
• Layered Architecture: UI Layer, API Layer, Domain Logic Layer (agents/context/memory), Persistence Layer.
• Modular “agent” pattern: isolated services with own prompts, runnables, helpers.
• Dual-memory pattern: graph vs. relational storage.
• Asynchronous processing: task queues for memory and agent operations.
• IPC boundary: clear separation between Electron processes and HTTP services.
d. Key Technologies/Frameworks
• Frontend: ElectronJS, Next.js, React, TailwindCSS
• Backend: FastAPI, Python 3.11, asyncio
• AI: Ollama, llama-cpp-python, FasterWhisper
• Databases: Neo4j, SQLite
• Integrations: Auth0, Google OAuth, PRAW, linkedin-scraper, nitter
• DevOps: GitHub Actions (CI), Docker (optional), shell scripts