Skip to content

LNA AI System - High-Level Design Document

Executive Summary

The LNA (African Digital Library) AI System is a comprehensive full-stack application that provides an intelligent chat interface for African book content. The system combines a Python FastAPI backend with AI agent capabilities, a Next.js React frontend with internationalization support, and a PostgreSQL database with vector search functionality using Supabase.

System Architecture Overview

Architecture Pattern

  • Pattern: Three-tier architecture with microservices principles
  • Frontend: Next.js 15 with React 19 (Client-side rendering with SSR support)
  • Backend: FastAPI with async/await patterns
  • Database: PostgreSQL with pgvector extension via Supabase
  • AI/ML: Ollama integration with Pydantic AI framework
  • Authentication: Supabase Auth
  • Deployment: Containerizable with Docker support

Component Architecture

1. Frontend Layer (Next.js + React)

Diagram

LNA AGENT PIPELINE

Technology Stack

  • Framework: Next.js 15.5.0 with App Router
  • UI Library: React 19.1.0 with TypeScript
  • Styling: Tailwind CSS 4.0
  • Component Library: Radix UI components
  • Internationalization: next-intl for multi-language support (English/French)
  • State Management: React Context API + useState/useEffect hooks
  • Authentication: Supabase Auth helpers

Key Components

Core Components
  1. Chat Component (/src/components/Chat.tsx)
  2. Main chat interface with real-time streaming
  3. Message history management
  4. Book selection integration

  5. Error handling and loading states

  6. Header Component (/src/components/Header.tsx)

  7. Navigation and branding
  8. Language switcher
  9. User authentication menu

  10. Welcome message display

  11. BookSelector Component (/src/components/BookSelector.tsx)

  12. Dynamic book loading from backend API
  13. Dropdown selection interface
  14. Error handling for book loading failures
Authentication System
  • AuthProvider (/src/components/AuthProvider.tsx)
  • Context-based authentication state management
  • Session persistence and refresh handling
  • Sign-out functionality
Internationalization
  • Supported Languages: English (en), French (fr)
  • Configuration: /src/i18n/config.ts
  • Message Files: /messages/en.json, /messages/fr.json
  • Implementation: next-intl with locale-based routing

API Integration Layer

  • Base API Client (/src/lib/api.ts)
  • HTTP client for backend communication
  • Streaming response handling for real-time chat
  • Error handling and retry logic
  • Environment-based URL configuration

2. Backend Layer (FastAPI + Python)

Technology Stack

  • Framework: FastAPI with Uvicorn ASGI server
  • AI Framework: Pydantic AI for agent orchestration
  • LLM Integration: Ollama client for local LLM inference
  • Database Client: Supabase Python SDK
  • Async Support: Native async/await throughout
  • Environment: Python-dotenv for configuration

Core Services

1. Main API Service (/backend/main.py)

Endpoints: - GET /books - Retrieve available books from vector database - POST /answer - Synchronous question answering - POST /answer/stream - Server-sent events streaming for real-time responses - POST /stream - Alternative streaming endpoint using run_stream - GET /test - CORS and connectivity testing

Features: - CORS middleware for cross-origin requests - Request/response validation with Pydantic models - Comprehensive error handling and logging - Dynamic source configuration per request

2. AI Agent Service (/backend/lna_ai_agent.py)

Architecture: - Agent Pattern: Pydantic AI Agent with tool-based architecture - LLM Provider: OpenAI-compatible API via Ollama - Model: Configurable (default: qwen3:8b) - Context Management: Dependency injection pattern

AI Tools: 1. retrieve_relevant_documentation - Vector similarity search using embeddings - RAG (Retrieval Augmented Generation) implementation - Top-K document retrieval (default: 5) - Source filtering by book/document

  1. list_book_pages
  2. Dynamic page discovery
  3. Source-specific content listing

  4. Sorted and deduplicated results

  5. get_book_pages_content

  6. Full page content reconstruction
  7. Chunk ordering and assembly
  8. Source-specific content retrieval

Embedding System: - Model: nomic-embed-text:latest via Ollama - Dimensionality: 768-dimensional vectors - Fallback: Zero vector on embedding failures

Configuration Management

  • Config Class: Mutable configuration for dynamic source switching
  • Environment Variables: Ollama host, model selection, API keys
  • Dependency Injection: PydanticAIDeps for service composition

3. Database Layer (PostgreSQL + pgvector)

Database Schema

Primary Table: book_vector_pages
CREATE TABLE public.book_vector_pages (
  id BIGSERIAL PRIMARY KEY,
  url CHARACTER VARYING NOT NULL,
  chunk_number INTEGER NOT NULL,
  title CHARACTER VARYING NOT NULL,
  summary CHARACTER VARYING NOT NULL,
  content TEXT NOT NULL,
  metadata JSONB NOT NULL DEFAULT '{}'::jsonb,
  embedding public.vector NULL,
  created_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT timezone('utc'::text, now()),
  CONSTRAINT book_vector_pages_url_chunk_number_key UNIQUE (url, chunk_number)
);

Indexing Strategy

  1. GIN Index on Metadata: idx_book_vector_pages_metadata
  2. Enables fast JSON queries for filtering

  3. Supports source-based filtering

  4. IVFFlat Vector Index: book_vector_pages_embedding_idx

  5. Optimized for cosine similarity searches
  6. Enables fast vector similarity queries

Vector Search Function

-- match_book_vector_pages function
RETURNS TABLE (
  id BIGINT,
  url CHARACTER VARYING,
  chunk_number INTEGER,
  title CHARACTER VARYING,
  summary CHARACTER VARYING,
  content TEXT,
  metadata JSONB,
  similarity FLOAT
)

Functionality: - Cosine similarity calculation: 1 - (embedding <=> query_embedding) - Metadata filtering with JSONB operators - Configurable result limits - Ordered by similarity score

Data Flow Architecture

1. User Query Flow

User Input → Frontend Chat → API Request → Backend FastAPI → AI Agent
    ↓
AI Agent → Vector Search → Database → Relevant Chunks → LLM Processing
    ↓
Generated Response → Streaming API → Frontend → Real-time Display

2. Book Selection Flow

Frontend → GET /books → Backend → Supabase Query → book_vector_pages
    ↓
Unique Books Extraction → Response → Frontend BookSelector → User Selection

3. Authentication Flow

User → Supabase Auth → JWT Token → Frontend Context → Protected Routes

AI/ML Architecture

Large Language Model Integration

  • Provider: Ollama (local inference)
  • Model: qwen3:8b (configurable)
  • API Compatibility: OpenAI-compatible interface
  • Reasoning: Configurable reasoning inclusion

Retrieval Augmented Generation (RAG)

  1. Query Processing: User query → embedding generation
  2. Similarity Search: Vector database query with metadata filtering
  3. Context Assembly: Top-K relevant chunks formatting
  4. Generation: LLM response with retrieved context
  5. Streaming: Real-time response delivery

Vector Embeddings

  • Model: nomic-embed-text:latest
  • Dimensions: 768
  • Similarity Metric: Cosine similarity
  • Storage: PostgreSQL pgvector extension

Security Architecture

Authentication & Authorization

  • Provider: Supabase Auth
  • Method: JWT-based authentication
  • Session Management: Client-side session persistence
  • Protected Routes: Context-based route protection

API Security

  • CORS: Configured for cross-origin requests
  • Environment Variables: Sensitive configuration externalized
  • Error Handling: Sanitized error responses

Database Security

  • Row Level Security: Supabase RLS policies
  • Connection Security: Environment-based credentials
  • Query Parameterization: SQL injection prevention

Performance Architecture

Frontend Performance

  • Next.js Optimizations: App Router with static generation
  • Code Splitting: Automatic route-based splitting
  • Image Optimization: Next.js Image component
  • Caching: Browser and CDN caching strategies

Backend Performance

  • Async Architecture: Non-blocking I/O throughout
  • Connection Pooling: Supabase connection management
  • Streaming Responses: Real-time data delivery
  • Vector Indexing: Optimized similarity searches

Database Performance

  • Vector Indexing: IVFFlat for fast similarity searches
  • JSON Indexing: GIN indexes for metadata queries
  • Query Optimization: Parameterized queries with proper indexing

Scalability Architecture

Horizontal Scaling

  • Frontend: CDN distribution via Vercel/Netlify
  • Backend: Multiple FastAPI instances behind load balancer
  • Database: Supabase managed scaling

Vertical Scaling

  • LLM Inference: GPU acceleration for Ollama
  • Vector Operations: Optimized vector libraries
  • Database: Supabase automatic scaling

Deployment Architecture

Development Environment

  • Frontend: Next.js dev server (localhost:3000)
  • Backend: Uvicorn dev server (localhost:8000)
  • Database: Supabase cloud instance
  • LLM: Local Ollama instance (localhost:11434)

Production Considerations

  • Containerization: Docker support for all services
  • Environment Configuration: .env file management
  • Health Checks: API endpoint monitoring
  • Logging: Structured logging throughout stack

Integration Points

External Services

  1. Supabase
  2. Authentication service
  3. PostgreSQL database with pgvector

  4. Real-time subscriptions capability

  5. Ollama

  6. Local LLM inference
  7. Embedding generation
  8. Model management

Internal APIs

  • Frontend ↔ Backend: RESTful API with streaming support
  • Backend ↔ Database: Supabase SDK integration
  • Backend ↔ AI: Pydantic AI framework

Error Handling & Monitoring

Frontend Error Handling

  • API Errors: User-friendly error messages
  • Network Failures: Retry mechanisms
  • Loading States: Comprehensive loading indicators

Backend Error Handling

  • Exception Handling: Try-catch blocks with logging
  • HTTP Status Codes: Proper status code usage
  • Error Responses: Structured error information

Monitoring Considerations

  • API Metrics: Response times, error rates
  • Database Metrics: Query performance, connection health
  • AI Metrics: Model response times, embedding quality

Future Architecture Considerations

Scalability Enhancements

  • Microservices: Service decomposition for independent scaling
  • Caching Layer: Redis for frequently accessed data
  • CDN Integration: Static asset optimization

AI/ML Enhancements

  • Model Optimization: Fine-tuned models for African content
  • Multi-modal Support: Image and document processing
  • Advanced RAG: Hybrid search with keyword + semantic

Feature Expansions

  • Multi-tenant Architecture: Organization-based data isolation
  • Advanced Analytics: User interaction tracking
  • Real-time Collaboration: Multi-user chat sessions

Conclusion

The LNA AI System represents a modern, scalable architecture that combines cutting-edge AI capabilities with robust web technologies. The system is designed for high performance, maintainability, and extensibility, making it suitable for serving African digital library content to a global audience.

The architecture supports real-time interactions, multi-language content, and intelligent document retrieval, providing users with an intuitive interface for exploring African literary heritage through AI-powered conversations.