# existence-master/sentient architecture

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

- Interactive diagram: https://gitdiagram.com/existence-master/sentient
- Repository: https://github.com/existence-master/sentient

## Overview

##### 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

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Desktop Client Layer
    subgraph "Desktop Client (Electron)"
        direction TB
        Main["Electron Main Process"]:::ui
        Preload["Electron Preload (IPC Bridge)"]:::ui
        AuthMgr["Electron Auth Manager"]:::ui
        Renderer["Next.js Renderer (UI pages)"]:::ui
        Components["UI Components Library"]:::ui
        Hooks["Client Hooks"]:::ui
        UtilsAPI["API Client"]:::ui
        WebRTCClient["WebRTC Client"]:::ui
        WebSocketAudio["WebSocket Audio Client"]:::ui
        subgraph "Local Servers"
            direction TB
            AppServer["App Server"]:::ui
            AuthServer["Auth Server"]:::ui
            SetupServer["Setup Server"]:::ui
            Neo4jHelperServer["Neo4j Helper Server"]:::ui
            UtilsServer["Utilities Server"]:::ui
        end
    end

    %% Backend Layer
    subgraph "FastAPI Backend"
        direction TB
        AppPy["FastAPI Entry Point"]:::backend
        Agents["Agents Module"]:::backend
        Chat["Chat Module"]:::backend
        Context["Context Module"]:::backend
        MemoryMod["Memory Module"]:::backend
        Scraper["Scraper Module"]:::backend
        Voice["Voice Module"]:::backend
        Common["Common Utilities"]:::backend
        AuthHelpers["Server-side Auth Helpers"]:::backend
        UtilsSV["Server Utilities"]:::backend
        BaseHelpers["FastAPI Base & Helpers"]:::backend
        Requirements["Backend Requirements"]:::backend
        Tests["Server Tests"]:::backend
    end

    %% AI Models Layer
    subgraph "AI Model Servers"
        direction TB
        Ollama["Ollama HTTP API"]:::ai
        LlamaCPP["llama-cpp-python"]:::ai
    end

    %% Datastores Layer
    subgraph "Datastores"
        direction TB
        Neo4j["Neo4j Graph DB"]:::db
        SQLite["SQLite DB"]:::db
    end

    %% External Services Layer
    subgraph "External Services"
        direction TB
        Google["Google Workspace APIs"]:::ext
        Brave["Brave Search API"]:::ext
        Social["Social Media Scrapers"]:::ext
        Internet["Internet Search"]:::ext
    end

    %% Relationships
    Renderer -->|IPC| Preload
    Preload -->|IPC| Main
    Main -->|manages| AppServer
    Main -->|manages| AuthServer
    Main -->|manages| SetupServer
    Main -->|manages| Neo4jHelperServer
    Main -->|manages| UtilsServer

    Renderer -->|HTTP/WebSocket| AppPy
    AppPy -->|invokes| Agents
    AppPy -->|invokes| Chat
    AppPy -->|invokes| Context
    AppPy -->|invokes| MemoryMod
    AppPy -->|invokes| Scraper
    AppPy -->|invokes| Voice
    AppPy -->|uses| AuthHelpers
    AppPy -->|uses| BaseHelpers
    Agents -->|async tasks| Common

    Chat -->|inference| Ollama
    Voice -->|STT/TTS| LlamaCPP

    MemoryMod -->|bolt| Neo4j
    MemoryMod -->|sql| SQLite

    Context -->|OAuth/REST| Google
    Context -->|HTTP| Brave
    Context -->|HTTP| Social
    Context -->|HTTP| Internet

    %% Click Events
    click Main "https://github.com/existence-master/sentient/blob/master/src/client/main/index.js"
    click Preload "https://github.com/existence-master/sentient/blob/master/src/client/main/preload.js"
    click AuthMgr "https://github.com/existence-master/sentient/blob/master/src/client/main/auth.js"
    click Renderer "https://github.com/existence-master/sentient/blob/master/src/client/app/page.js"
    click Components "https://github.com/existence-master/sentient/tree/master/src/client/components"
    click Hooks "https://github.com/existence-master/sentient/tree/master/src/client/hooks"
    click UtilsAPI "https://github.com/existence-master/sentient/blob/master/src/client/utils/api.js"
    click WebRTCClient "https://github.com/existence-master/sentient/blob/master/src/client/utils/WebRTCClient.js"
    click WebSocketAudio "https://github.com/existence-master/sentient/blob/master/src/client/utils/WebSocketAudioClient.js"
    click AppServer "https://github.com/existence-master/sentient/blob/master/src/client/scripts/appServer.js"
    click AuthServer "https://github.com/existence-master/sentient/blob/master/src/client/scripts/authServer.js"
    click SetupServer "https://github.com/existence-master/sentient/blob/master/src/client/scripts/setupServer.js"
    click Neo4jHelperServer "https://github.com/existence-master/sentient/blob/master/src/client/scripts/neo4j.js"
    click UtilsServer "https://github.com/existence-master/sentient/blob/master/src/client/scripts/utilsServer.js"
    click AppPy "https://github.com/existence-master/sentient/blob/master/src/server/app/app.py"
    click Agents "https://github.com/existence-master/sentient/tree/master/src/server/agents"
    click Chat "https://github.com/existence-master/sentient/tree/master/src/server/chat"
    click Context "https://github.com/existence-master/sentient/tree/master/src/server/context"
    click MemoryMod "https://github.com/existence-master/sentient/tree/master/src/server/memory"
    click Scraper "https://github.com/existence-master/sentient/tree/master/src/server/scraper"
    click Voice "https://github.com/existence-master/sentient/tree/master/src/server/voice"
    click Common "https://github.com/existence-master/sentient/tree/master/src/server/common"
    click AuthHelpers "https://github.com/existence-master/sentient/blob/master/src/server/auth/helpers.py"
    click UtilsSV "https://github.com/existence-master/sentient/blob/master/src/server/utils/helpers.py"
    click BaseHelpers "https://github.com/existence-master/sentient/blob/master/src/server/app/base.py"
    click Requirements "https://github.com/existence-master/sentient/blob/master/src/server/requirements.txt"
    click Tests "https://github.com/existence-master/sentient/tree/master/src/server/tests"

    %% Styles
    classDef ui fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef backend fill:#90EE90,stroke:#000,stroke-width:1px
    classDef ai fill:#DDA0DD,stroke:#000,stroke-width:1px
    classDef db fill:#FFA500,stroke:#000,stroke-width:1px
    classDef ext fill:#D3D3D3,stroke:#000,stroke-width:1px
```
