docs/architecture/current-system-design.md

Current System Architecture

Request Flow Diagram

┌─────────────────┐
│   User Request  │
└─────────┬───────┘
          │
          ▼
┌─────────────────┐
│  FastAPI        │
│  Chat Endpoint  │
└─────────┬───────┘
          │
          ▼
┌─────────────────┐
│ Extract Search  │
│ Terms (NLP)     │
└─────────┬───────┘
          │
          ▼
┌─────────────────┐    ┌─────────────────┐
│ Phase 1:        │◄──►│ Phase 2:        │
│ Rule-Based      │    │ AI-Enhanced     │
│ Decision        │    │ Decision        │
└─────────┬───────┘    └─────────────────┘
          │
          ▼
    ┌─────────┐
    │Search?  │──────────── No ────────────┐
    └─────────┘                            │
          │ Yes                            │
          ▼                                │
┌─────────────────┐                       │
│ Phase 3:        │                       │
│ Universal Cache │                       │
│ Check           │                       │
└─────────┬───────┘                       │
          │                                │
          ▼                                │
    ┌─────────┐                           │
    │Cache    │──── Hit ──┐               │
    │Hit?     │           │               │
    └─────────┘           │               │
          │ Miss          │               │
          ▼               │               │
┌─────────────────┐       │               │
│ Web Search      │       │               │
│ Combined        │       │               │
│ (Brave+DDG)     │       │               │
└─────────┬───────┘       │               │
          │               │               │
          ▼               │               │
┌─────────────────┐       │               │
│ Store in Cache  │       │               │
└─────────┬───────┘       │               │
          │               │               │
          ▼               │               │
┌─────────────────┐       │               │
│ Format Results  │◄──────┘               │
└─────────┬───────┘                       │
          │                                │
          ▼                                │
┌─────────────────┐◄──────────────────────┘
│ AI Response     │
│ Generation      │
│ (Gemini)        │
└─────────┬───────┘
          │
          ▼
┌─────────────────┐
│ Analytics       │
│ Tracking        │
└─────────┬───────┘
          │
          ▼
┌─────────────────┐
│ JSON Response   │
│ to Client       │
└─────────────────┘

Current Cache Implementation

┌─────────────────────────────────────────────────────────────┐
│                    Universal Search Cache                   │
│                                                             │
│  ┌─────────────────┐    ┌─────────────────────────────────┐ │
│  │   Hash Table    │    │         Cache Entry             │ │
│  │   (OrderedDict) │    │                                 │ │
│  │                 │    │  • search_results: List[Dict]   │ │
│  │  MD5(terms) ──► │────┤  • search_query: str           │ │
│  │                 │    │  • search_terms: List[str]     │ │
│  │                 │    │  • timestamp: float            │ │
│  │                 │    │  • ttl: int                    │ │
│  │                 │    │  • hit_count: int              │ │
│  │                 │    │  • last_accessed: float        │ │
│  └─────────────────┘    └─────────────────────────────────┘ │
│                                                             │
│  Lookup Strategy:                                           │
│  1. Exact Match: O(1) hash lookup                          │
│  2. Semantic Search: O(n) spaCy similarity                 │
│                                                             │
│  Max Size: 1000 entries                                    │
│  Default TTL: 3600 seconds                                 │
│  Memory: ~2-10MB per entry                                 │
└─────────────────────────────────────────────────────────────┘

Performance Characteristics

Operation	Time Complexity	Typical Duration	Resource Usage
Exact Cache Hit	O(1)	1-5μs	RAM only
Semantic Cache Search	O(n)	10-500ms	CPU + RAM
Rule-Based Decision	O(1)	50-200ms	CPU intensive
AI-Based Decision	O(1)	200-500ms	Network + GPU
Web Search	O(1)	2-5s	Network + APIs

Current Limitations

1. Decision-First Approach: Always runs search decision logic before cache check
2. Dual Lookup Complexity: Two different cache lookup strategies
3. Poor Semantic Scaling: O(n) performance degrades with cache size
4. Memory-Only: Cache lost on server restart
5. Session Complexity: Removed but left complex patterns in codebase