Architecture Overview

+---------------------------------------------------------------+
|                     FRONTEND LAYER                            |
|                                                               |
|  React 19 + TypeScript + Zustand                              |
|  Runtime: WebView2 (Windows) / WebKit (macOS/Linux)           |
|                                                               |
|  Features:                                                    |
|  * Real-time SSE streaming with 60fps token buffering         |
|  * Performance-optimized rendering (React.memo)               |
|  * Document management with drag-drop upload                  |
|  * Live performance metrics dashboard                         |
|  * Settings panel with model hot-swap UI                      |
|  * Dark mode with localStorage persistence                    |
|                                                               |
+----------------+----------------------------------------------+
                 |
                 |  +---------------------------------------+
                 +--| Tauri IPC (JSON-RPC)                  |
                 |  | * Native features                     |
                 |  | * Health monitoring                   |
                 |  | * System notifications                |
                 |  +---------------------------------------+
                 |
                 |  +---------------------------------------+
                 +--| Direct HTTP (Fetch API)               |
                    | * Query endpoints                     |
                    | * Document upload                     |
                    | * SSE streaming                       |
                    +---------------------------------------+
                    |
+-------------------v---------------------------------------+
|                DESKTOP BRIDGE LAYER                       |
|                                                           |
|  Tauri 2.9 (Rust Native Binary)                           |
|  Runtime: Native system process                           |
|                                                           |
|  Responsibilities:                                        |
|  * IPC command handlers (type-safe bidirectional)         |
|  * Backend health monitoring (background task)            |
|  * HTTP proxy to FastAPI backend                          |
|  * Native OS integration (file dialogs, notifications)    |
|  * WebView management and security policies               |
|  * Application lifecycle management                       |
|                                                           |
+----------------+------------------------------------------+
                 |
                 | HTTP/REST (reqwest crate)
                 | Target: http://localhost:8000
                 |
+----------------v------------------------------------------+
|                   BACKEND LAYER                           |
|                                                           |
|  FastAPI + Python 3.11                                    |
|  Runtime: Docker containers with CUDA support             |
|                                                           |
|  Core Components:                                         |
|  * RAG orchestration engine (parallel initialization)     |
|  * llama.cpp GPU inference (80-100 tokens/sec)            |
|  * Vector database - Qdrant (dense + sparse search)       |
|  * Multi-tier caching - Redis (L1-L5 ATLAS protocol)      |
|  * Document processing pipeline (PDF/DOCX/TXT)            |
|  * Adaptive retrieval strategies (simple/hybrid/advanced) |
|  * Model management (hot-swappable LLMs)                  |
|  * Confidence scoring and source citation                 |
|                                                           |
|  Infrastructure:                                          |
|  * Qdrant: Vector storage and similarity search           |
|  * Redis: Multi-level caching and session management      |
|  * CUDA Toolkit: GPU acceleration for inference           |
|                                                           |
+-----------------------------------------------------------+

src/
├── App.tsx                    // Main application entry with error boundary
├── hooks/
│   ├── useChat.ts            // Chat orchestration with token batching
│   └── useStreamingChat.ts   // SSE streaming implementation
├── store/
│   ├── useStore.ts           // Main Zustand store with persistence
│   └── performanceStore.ts   // Memoized performance calculations
├── services/
│   └── api.ts                // API client with retry logic
└── components/
    ├── Chat/
    │   ├── ChatWindow.tsx    // Main chat interface
    │   └── ChatMessage.tsx   // Optimized message rendering (React.memo)
    └── ErrorBoundary/
        └── ErrorBoundary.tsx // Production error recovery

// Command allowlisting prevents arbitrary Rust execution
#[tauri::command]
async fn check_atlas_health(
    state: State<'_, Arc<tokio::sync::Mutex<AppState>>>
) -> Result<HealthStatus, String> {
    // Type-safe, validated, allowlisted command
}

Startup Time: 20-30 seconds (optimized from 78s via parallel init)
 
Query Latency:
  Cache Hit: less than 1ms (98% reduction from 50-100ms)
  Simple Mode: 8-15 seconds
  Adaptive Mode: 10-25 seconds
 
Inference Speed: 80-100 tokens/sec (RTX 5080, Q5_K_M quantization)
 
Cache Hit Rate: 60-80% in production workloads
 
Resource Usage:
  RAM: 8GB idle, 12GB active, 20GB during reindexing
  VRAM: 6GB loaded model, 10GB with reranker
  CPU: less than 5% idle, 100% single-core during generation

# Groups independent components for concurrent loading
# Speedup: 3.4x (78s → 23s)
async def initialize():
    # GROUP 1: Fully independent
    await asyncio.gather(
        init_embedding_cache(),
        init_embeddings(),
        load_bm25_data(),
        init_llm()
    )
 
    # GROUP 2: Depends on GROUP 1
    await asyncio.gather(
        init_cache_manager(),
        init_vectorstore(),
        init_bm25_retriever(),
        llm_warmup()
    )
 
    # GROUP 3: Final components
    await asyncio.gather(
        load_metadata(),
        init_conversation_memory(),
        init_confidence_scorer()
    )

# Trade-off: Minor context bleed for 40-60% speedup
# Does NOT clear cache between requests
def generate(self, prompt, **kwargs):
    response = self.llm(prompt, max_tokens=kwargs.get('max_tokens', 512))
    return response['choices'][0]['text']

// Frontend: Type-safe Tauri invoke
import { invoke } from '@tauri-apps/api/core';
 
interface HealthStatus {
  status: 'healthy' | 'unhealthy' | 'degraded';
  components: {
    vectorstore: 'ready' | 'error';
    llm: 'ready' | 'error';
    cache: 'ready' | 'error';
  };
}
 
export const checkHealth = async (): Promise<HealthStatus> => {
  return await invoke<HealthStatus>('check_atlas_health');
};

// Backend: Rust command handler
#[tauri::command]
async fn check_atlas_health(
    state: State<'_, Arc<tokio::sync::Mutex<AppState>>>
) -> Result<HealthStatus, String> {
    let app_state = state.lock().await;
 
    let response = app_state.http_client
        .get(format!("{}/api/health", app_state.backend_url))
        .timeout(Duration::from_secs(5))
        .send()
        .await
        .map_err(|e| format!("Health check failed: {}", e))?;
 
    response.json().await.map_err(|e| format!("Parse error: {}", e))
}

User Query --> Frontend Validation --> Cache Lookup (L1-L2)
    |
    +--> [Cache Hit] --> Return cached result (<1ms)
    |
    +--> [Cache Miss] --> Continue to retrieval
                |
                v
        Security Checks (rate limit, injection detection)
                |
                v
        Query Classification (simple/moderate/complex)
                |
                v
        Document Retrieval (mode-specific strategy)
                |
                v
        Answer Generation (llama.cpp GPU)
                |
                v
        Confidence Scoring (parallel)
                |
                v
        Response Formatting
                |
                v
        Background Tasks (cache update, prefetch)

File Selection --> Frontend Validation (size, type)
    |
    v
POST multipart/form-data --> Backend /api/documents/upload
    |
    v
Filename sanitization --> SHA256 hash --> Duplicate check
    |
    v
Save to documents/ directory
    |
    v
User triggers reindexing
    |
    v
Acquire mutex lock (prevent concurrent reindex)
    |
    v
Text extraction --> Semantic chunking (1024/128)
    |
    v
Generate embeddings (BGE-large on CPU)
    |
    v
Index in Qdrant (dense + sparse BM25)
    |
    v
Atomic swap (temp --> production)
    |
    v
Release lock --> Return stats