1

Access Layer

Open WebUI Complete
Web Interface • PostgreSQL • v0.7.2
Primary web chat interface with persistent user profiles, settings, and conversation history. Multi-user support with authentication and real-time streaming responses.
OpenClaw Gateway Active
Messaging Gateway • Docker
Multi-channel messaging gateway normalizing inbound/outbound messages. Supports WhatsApp, Telegram, Discord, Slack. Configured with SN-Assist as model provider.
↓
2

Application Layer

FastAPI Core Complete
Python • OpenAI-Compatible API
Core API with OpenAI-compatible /v1/chat/completions endpoint. Handles request routing, authentication, streaming responses, and progress indicators.
LangGraph Swarm Complete
LangGraph • 6 Domain Agents
Multi-agent orchestration with main orchestrator delegating to domain specialists: ServiceNow, ITIL, SAFe, Audit, BPM, Six Sigma. Handoff mechanisms and response synthesis.
GraphRAG Engine Complete
Hybrid Search • Vector + Graph
Hybrid retrieval merging vector similarity (Qdrant) with graph traversal (Neo4j). Query routing for user-scoped vs knowledge questions. Source citations.
Query Pipeline Complete
Prompt Enhancement • Clarification
Pre-processing pipeline with query clarity scoring. Automatic prompt enhancement for salvageable queries and conversational clarification for vague inputs.
Context Manager Complete
Multi-Tier • Token Budgeting
Multi-tier context window management for long conversations (200+ messages). Tier 1 (hot): verbatim, Tier 2 (warm): summaries, Tier 3 (cold): compressed.
Self-Evolution Complete
5-Layer Pipeline • Evidence-Gated
Feedback-first self-improvement: Harvester (15min), Accumulator (1hr), Proposer, A/B Gatekeeper (p<0.05), KB Expander. Circuit breaker protected.
Project Companion In Progress
Kanban • Risk Management • Phased
Universal project management: cert prep, implementations, Six Sigma initiatives. Phases, tasks, milestones, risks, collaborators, real-time board.
Learning Workflows Complete
CSA Prep • Quizzes • Progress
Guided learning with 20-day CSA exam prep curriculum. Adaptive quizzing, progress tracking, weak area identification, multi-session persistence.
↓
3

Knowledge & Data Layer

Neo4j Complete
Knowledge Graph • 176 Docs • 3221 Chunks
Graph database storing entities and relationships. Document-chunk relationships enable graph traversal for multi-hop reasoning and context expansion.
Qdrant Complete
Vector DB • 1536-dim • Cosine
Vector database for semantic similarity search. Stores embeddings with metadata and source links. HNSW indexing for fast retrieval.
PostgreSQL Complete
System of Record • Users • Conversations
Primary database for users, profiles, conversations, messages, learning plans, projects, and evolution metrics. Separate snassist and openwebui databases.
Redis Complete
Queue • Cache • Pub/Sub
Per-conversation queuing for sequential processing. Caching for user context and learning data. Pub/sub for real-time board updates.
↓
4

External Services

OpenAI Primary
GPT-5 • GPT-4o-mini • Embeddings
Primary LLM provider. GPT-5 for orchestrator (400K context), GPT-4o-mini for domain agents and summarization. text-embedding-3-small for vectors.
OpenRouter Fallback
Free Tier • Cheap Models
Fallback LLM provider for cost optimization. Free tier (google/gemma-2-9b-it:free) and cheap models as secondary fallbacks.
Google Gemini Fallback
2.5 Flash • 1M Context • Web Search
Tertiary fallback and web retrieval. 2.5 Flash for JIT web retrieval when KB confidence is low. 1M token context for large documents.

Animated Data Flows

ACCESS GATEWAY APP LAYER KNOWLEDGE Open WebUI Web Chat WhatsApp Messaging Nginx Reverse Proxy FastAPI /v1/chat Query Pipeline Enhance/Clarify Orchestrator Route to Agents Domain Agents 6 Specialists Context Builder 3-Tier Window GraphRAG Hybrid Search Qdrant Vectors (3.2K) Neo4j Graph (176 docs) PostgreSQL Conversations Redis Queue/Cache User Memory Cross-Session OpenAI GPT-5 / 4o-mini

Chat Query Flow

  • 1
    User sends message via Open WebUI or messaging platform
  • 2
    Nginx routes to FastAPI /v1/chat/completions endpoint
  • 3
    Query Pipeline scores clarity - enhances or clarifies as needed
  • 4
    Identity Bridge resolves user ID for cross-session memory
  • 5
    Context Builder assembles 3-tier window with summaries
  • 6
    GraphRAG retrieves from Qdrant (vectors) + Neo4j (graph)
  • 7
    Orchestrator classifies domains and delegates to specialists
  • 8
    Domain agents (ServiceNow, ITIL, etc.) process with RAG context
  • 9
    Responses synthesized, scored, formatted with citations
  • 10
    Streaming response with stage indicators (searching → analyzing → formulating)

Feature Manifest

28
Complete
4
In Progress
5
Planned
3
Backlog
Core Platform 7 features ▼

FastAPI Core

OpenAI-compatible API with streaming support, JWT auth, and health checks

📁 api/snassist/main.py ✅ 242 tests
View Code →

LangGraph Swarm

Multi-agent orchestration with 6 domain agents and handoff mechanisms

📁 api/snassist/agents/ ✅ Complete
View Code →

GraphRAG Hybrid Search

Vector similarity + graph traversal for contextual retrieval with citations

📁 api/snassist/retrieval/ ✅ 3,221 vectors
View Code →

Identity Bridge

Deterministic user ID mapping for cross-session persistence across channels

📁 api/snassist/auth.py ✅ Complete
View Code →

Role-Based Personalization

11 roles with profile inference, role-aware retrieval, and scoring

📁 api/snassist/roles.py ✅ 66 tests
View Code →

LLM Fallback Chain

OpenAI → OpenRouter → Gemini with circuit breaker protection

📁 api/snassist/llm.py ✅ Complete
View Code →

Web Retrieval (JIT)

Just-in-time web fetching for low-confidence KB queries with rate limiting

📁 api/snassist/tools/web_retrieval.py ✅ Complete
View Code →
Query & Context Management 3 features ▼

Query Pipeline

Query clarity scoring, prompt enhancement, and conversational clarification

📁 api/snassist/query_pipeline.py ✅ 24 tests
View Plan →

Multi-Tier Context

3-tier context window for 200+ message conversations with summarization

📁 api/snassist/context_builder.py ✅ 51 tests
View Plan →

Streaming Responses

SSE streaming with stage indicators (searching → analyzing → formulating)

📁 api/snassist/api/chat.py ✅ Complete
View Plan →
Self-Evolution Pipeline 5 features ▼

Feedback Harvester

Extract explicit, verbal, and behavioral feedback from conversations (15min cycle)

📁 api/snassist/evolution/harvester.py ✅ Complete
View Plan →

Evidence Accumulator

Bayesian scoring per agent/chunk with Thompson Sampling (1hr cycle)

📁 api/snassist/evolution/accumulator.py ✅ Complete
View Plan →

Change Proposer

Generate improvement proposals when metrics cross thresholds

📁 api/snassist/evolution/proposer.py ✅ Complete
View Plan →

A/B Gatekeeper

Statistical backtesting with Welch's t-test (p<0.05, Cohen's d>0.3)

📁 api/snassist/evolution/gatekeeper.py ✅ Complete
View Plan →

KB Expander

Autonomous knowledge gap detection and scraping from approved sources

📁 api/snassist/evolution/kb_expander.py ✅ Complete
View Plan →
Universal Project Companion 5 features ▼

Data Models

11 tables: projects, phases, tasks, milestones, risks, collaborators, dependencies

📁 api/snassist/projects/models.py ✅ 86 tests
View Plan →

Project Engine

CRUD operations, progress tracking, dependency management, optimistic locking

📁 api/snassist/projects/service.py 🔄 49 tests
View Plan →

Project API

REST endpoints with SSE streaming for real-time board updates

📁 api/snassist/api/projects.py 🔄 In Progress
View Plan →

Kanban Board UI

Preact SPA with drag-drop, real-time sync via SSE, risk matrix view

📁 board/ 📋 Planned
View Plan →

LangGraph Intake

Conversational project creation with multi-agent planning workflow

📁 api/snassist/projects/intake.py 📋 Planned
View Plan →
Guided Learning Workflows 3 features ▼

Learning Plans

20-day CSA exam prep with progress tracking and weak area identification

📁 api/snassist/learning/ ✅ 9 tests
View Plan →

Quiz Generation

Adaptive quizzing with KB + LLM generation, scoring, and remediation

📁 api/snassist/learning/quiz.py ✅ Complete
View Code →

Open WebUI Integration

Filter function for context injection, Tool functions for quiz/progress

📁 openwebui-functions/ ✅ Complete
View Code →
Infrastructure & Deployment 6 features ▼

Local Docker Stack

Split app/data plane with Docker Compose, 9 services running locally

📁 docker-compose.*.yml ✅ Complete
View Config →

Knowledge Base

176 documents across 12 domains, 3,221 chunks in Neo4j + Qdrant

📁 docs/knowledge-base/ ✅ Complete
View Docs →

VPS Deployment

Hostinger VPS with Tailscale VPN, UFW firewall, Let's Encrypt SSL

📁 docs/deployment/ 📋 Planned
View Plan →

Monitoring & Alerts

Prometheus metrics, Grafana dashboards, alerting rules

📁 docs/dashboards/ 📋 Planned
View Plan →

iMessage & Signal

Additional messaging channels via OpenClaw (deferred)

📝 Backlog ⏸️ Deferred
No docs yet

Enterprise SSO

SAML/LDAP integration for enterprise deployments (future phase)

📝 Backlog ⏸️ Future
No docs yet
Knowledge Base Expansion 2 features ▼

CSA Content Ingestion

130-150 additional documents for Data Administration, UI/Navigation domains

📁 scripts/ingest_csa_content.py 📋 Planned (~2,500 chunks)
View Plan →

KB 1000+ Target

Expand from 176 to 1000+ documents across all domains

📋 Planned 📊 17% complete
Planning phase
Complete (Built & Working)
In Progress (Built, integrating)
Planned (In design/docs)
Backlog (GitHub issues, not planned)