simbarag/.planning/codebase/ARCHITECTURE.md

Architecture

Analysis Date: 2026-02-04

Pattern Overview

Overall: RAG (Retrieval-Augmented Generation) system with multi-agent conversational AI architecture

Key Characteristics:

• RAG pattern with vector database for document retrieval
• LangChain agent-based orchestration with tool calling
• Blueprint-based API organization (Quart framework)
• Asynchronous request handling throughout
• OIDC authentication with RBAC via LDAP groups
• Streaming SSE responses for real-time chat

Layers

API Layer (Quart Blueprints):

• Purpose: HTTP request handling and route organization
• Location: blueprints/*/
• Contains: Blueprint definitions, route handlers, request/response serialization
• Depends on: Logic layer, models, JWT middleware
• Used by: Frontend (React SPA), external clients

Logic Layer:

• Purpose: Business logic and domain operations
• Location: blueprints/*/logic.py, blueprints/*/agents.py, main.py
• Contains: Conversation management, RAG indexing, agent orchestration, tool execution
• Depends on: Models, external services, LLM clients
• Used by: API layer

Model Layer (Tortoise ORM):

• Purpose: Database schema and data access
• Location: blueprints/*/models.py
• Contains: ORM model definitions, Pydantic serializers, database relationships
• Depends on: PostgreSQL database
• Used by: Logic layer, API layer

Integration Layer:

• Purpose: External service communication
• Location: utils/, config/
• Contains: Service clients (YNAB, Mealie, Paperless-NGX, OIDC)
• Depends on: External APIs
• Used by: Logic layer, tools

Tool Layer (LangChain Tools):

• Purpose: Agent-callable functions for extended capabilities
• Location: blueprints/conversation/agents.py
• Contains: @tool decorated functions for document search, web search, YNAB, Mealie
• Depends on: Integration layer, RAG logic
• Used by: LangChain agent

Frontend (React SPA):

• Purpose: User interface
• Location: raggr-frontend/
• Contains: React components, API service clients, authentication context
• Depends on: Backend API endpoints
• Used by: End users

Data Flow

Chat Query Flow:

1. User submits query in frontend (raggr-frontend/src/components/ChatScreen.tsx)
2. Frontend calls /api/conversation/query with SSE streaming (raggr-frontend/src/api/conversationService.ts)
3. API endpoint validates JWT, fetches user and conversation (blueprints/conversation/__init__.py)
4. User message saved to database via Tortoise ORM (blueprints/conversation/models.py)
5. Recent conversation history (last 10 messages) loaded and formatted
6. LangChain agent invoked with messages payload (blueprints/conversation/agents.py)
7. Agent decides which tools to call based on query (simba_search, ynab_, mealie_, web_search)
8. Tools execute: RAG query (blueprints/rag/logic.py), API calls (utils/*.py)
9. LLM generates response using tool results
10. Response streamed back via SSE events (status updates, content chunks)
11. Complete response saved to database
12. Frontend renders streaming response in real-time

RAG Document Flow:

1. Admin triggers indexing via /api/rag/index or /api/rag/reindex
2. RAG logic fetches documents from Paperless-NGX (blueprints/rag/fetchers.py)
3. Documents chunked using LangChain text splitter (1000 chars, 200 overlap)
4. Embeddings generated using OpenAI embedding model (text-embedding-3-small)
5. Vectors stored in ChromaDB persistent collection (chroma_db/)
6. Query time: embeddings generated for query, similarity search retrieves top 2 docs
7. Documents serialized and passed to LLM as context

State Management:

• Conversation state: PostgreSQL via Tortoise ORM
• Vector embeddings: ChromaDB persistent storage
• User sessions: JWT tokens in frontend localStorage
• Authentication: OIDC state in-memory (production should use Redis)

Key Abstractions

Conversation:

• Purpose: Represents a chat thread with message history
• Examples: blueprints/conversation/models.py
• Pattern: Aggregate root with message collection, foreign key to User

ConversationMessage:

• Purpose: Individual message in conversation (user or assistant)
• Examples: blueprints/conversation/models.py
• Pattern: Entity with enum speaker type, foreign key to Conversation

User:

• Purpose: Authenticated user with OIDC or local credentials
• Examples: blueprints/users/models.py
• Pattern: Entity with bcrypt password hashing, LDAP group membership, admin check method

LangChain Agent:

• Purpose: Orchestrates LLM calls with tool selection
• Examples: blueprints/conversation/agents.py (main_agent)
• Pattern: ReAct agent pattern with function calling via OpenAI-compatible API

Tool Functions:

• Purpose: Discrete capabilities callable by the agent
• Examples: simba_search, ynab_budget_summary, mealie_shopping_list in blueprints/conversation/agents.py
• Pattern: Decorated functions with docstrings that become tool descriptions

LLMClient:

• Purpose: Abstraction over LLM providers with fallback
• Examples: llm.py, blueprints/conversation/agents.py
• Pattern: Primary llama-server with OpenAI fallback, OpenAI-compatible interface

Service Clients:

• Purpose: External API integration wrappers
• Examples: utils/ynab_service.py, utils/mealie_service.py, utils/request.py
• Pattern: Class-based clients with async methods, relative date parsing

Entry Points

Web Application:

• Location: app.py
• Triggers: python app.py or Docker container startup
• Responsibilities: Initialize Quart app, register blueprints, configure Tortoise ORM, serve React frontend

CLI Indexing:

• Location: main.py (when run as script)
• Triggers: python main.py --reindex or --query <text>
• Responsibilities: Document indexing, direct RAG queries without API

Database Migrations:

• Location: aerich_config.py
• Triggers: aerich migrate, aerich upgrade
• Responsibilities: Schema migration generation and application

Admin Scripts:

• Location: scripts/add_user.py, scripts/user_message_stats.py, scripts/manage_vectorstore.py
• Triggers: Manual execution
• Responsibilities: User management, analytics, vector store inspection

React Frontend:

• Location: raggr-frontend/src/index.tsx
• Triggers: Bundle served at / by backend
• Responsibilities: Initialize React app, authentication context, routing

Error Handling

Strategy: Try-catch with logging at service boundaries, HTTP status codes for client errors

Patterns:

• API routes: Return JSON error responses with appropriate HTTP status codes (400, 401, 403, 500)
• Example: blueprints/rag/__init__.py line 26-27
• Async operations: Try-except blocks with logger.error for traceability
• Example: blueprints/conversation/agents.py line 142-145 (YNAB tool error handling)
• JWT validation: Decorator-based authentication with 401 response on failure
• Example: @jwt_refresh_token_required in all protected routes
• Frontend: Error callbacks in streaming service, redirect to login on session expiry
• Example: raggr-frontend/src/components/ChatScreen.tsx line 234-237
• Agent tool failures: Return error string to agent for recovery or user messaging
• Example: blueprints/conversation/agents.py line 384-385

Cross-Cutting Concerns

Logging: Python logging module with INFO level, structured with logger names by module (utils.ynab_service, blueprints.conversation.agents)

Validation: Pydantic models for serialization, Tortoise ORM field constraints, JWT token validation via quart-jwt-extended

Authentication: OIDC (Authelia) with PKCE flow → JWT tokens → RBAC via LDAP groups. Decorators: @jwt_refresh_token_required for auth, @admin_required for admin-only endpoints (blueprints/users/decorators.py)

---

Architecture analysis: 2026-02-04