# azure-samples/ai-knowledge architecture

> Architecture diagram of the GitHub repository azure-samples/ai-knowledge, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/azure-samples/ai-knowledge
- Repository: https://github.com/azure-samples/ai-knowledge

## Overview

##### Project type and purpose
- This is a full-stack, desktop-style application (user runs it locally via Streamlit) with a Python/FastAPI backend.
- Purpose: provide an interface to deploy and orchestrate disconnected Azure AI service containers (OCR, summarization), integrate with Ollama LLMs and embeddings, perform RAG workflows (vectorize documents, query, summarize), all on the user’s machine.

##### File structure
- Top level:
- backend/ – FastAPI service entry point (main.py) and helper modules for interacting with Ollama, Azure Document Intelligence, language services.
- frontend/ – Streamlit app (app.py), AI provider abstractions (aiproviders/), UI components (ui/components/), state/UI coordination services (ui/services/), styling.
- tests/ – unit tests for Ollama service.
- requirements.txt, README.md, Docker setup expected externally (docker-compose described in README).

##### README for technical stack and architecture clues
- Built With: Python 3.12+, FastAPI, Streamlit, Docker containerized Azure Cognitive Services, Ollama, ChromaDB (vector store).
- Usage:
- Spin up two Azure containers (form-recognizer & textanalytics summarization).
- Pull Ollama models (LLM + embedding).
- Run FastAPI on port 8000 to expose endpoints for model listing, document processing, Q&A, summarization.
- Run Streamlit on port 8501 to render UI and call backend endpoints.
- .env holds container endpoints & keys.
- Core workflow:
User uploads document → chunk & embed → store in vector DB → process query via LLM + vector retrieval → display results.

##### Main components and interactions
a. Frontend (Streamlit)
- UI Components (chat_interface, document_viewer, header, question_suggestions)
- State Manager & UI Coordinator services for event flow
- Calls backend REST API (FastAPI) for:
- /get_models, /process_document, /ask_question, /summarize endpoints
b. Backend (FastAPI)
- Controllers (main.py) route incoming requests
- Helpers in backend/helpers:
- ollama_helper.py – calls local Ollama daemon for embeddings & completion
- doc_helper.py – splits PDFs/text into chunks
- language_helper.py – wraps Azure Text Analytics container calls for summarization
- Vector Store (ChromaDB) abstraction under frontend/aiproviders/vector_store.py (persist and query embeddings)
- Ollama Service abstraction under frontend/aiproviders/ollama_service.py
- Other provider abstractions in frontend/aiproviders/…
c. External Services / Containers
- Azure Form Recognizer container (OCR/document parsing)
- Azure Text Analytics Summarization container
- Ollama LLM daemon (running locally, exposes HTTP gRPC)
d. Data stores
- Local folder for storing models (C:/ExtractiveModel)
- ChromaDB (file-based) for vector embeddings
e. User’s machine hosts all components; Docker network “ocrvnet” for inter-container communication.

##### Architectural patterns and principles
- Separation of concerns: UI / orchestration (Streamlit) vs. business logic & service integration (FastAPI) vs. AI providers (helper layers) vs. persistence (vector store).
- Adapter pattern: aiproviders/ modules abstract away different AI backends (Azure containers, Ollama).
- Pipeline pattern: document ingestion → chunking → embedding → storage → retrieval → summarization/Q&A.

- User (actor)
- AI Provider Adapters (cluster): Ollama Service, Azure OCR, Azure Summarization
1. User → Streamlit UI → emits HTTP requests to FastAPI
2. FastAPI → Doc Helper → Azure OCR container (HTTP) → parsed text
3. FastAPI → Doc Helper → chunking → Ollama embedding adapter → ChromaDB (write)
4. FastAPI → Query endpoint → ChromaDB (read) → retrieved chunks → Ollama LLM adapter (completion)
5. FastAPI → Azure Summarization container → returns summary
6. Responses flow back to Streamlit → UI renders results to User
c. External container network: group OCR & Text Analytics under a “Docker Bridge Network (ocrvnet)” boundary.
d. Ports: 5000 (OCR), 5001 (Summarization), 11434 (Ollama default), 8000 (FastAPI), 8501 (Streamlit).

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Actors
    User(("User")):::external
    User -->|"Interacts"| UI

    %% Local Machine Boundary
    subgraph "Local Machine"
        %% Frontend Layer
        subgraph "Frontend (Streamlit UI)" 
            UI["Streamlit UI\n(port 8501)"]:::frontend
            CI["Chat Interface"]:::frontend
            DV["Document Viewer"]:::frontend
            HD["Header"]:::frontend
            QS["Question Suggestions"]:::frontend
            SM["State Manager"]:::frontend
            UC["UI Coordinator"]:::frontend
        end

        %% Backend Layer
        subgraph "Backend (FastAPI)" 
            API["FastAPI Service\n(port 8000)"]:::backend
            DH["Doc Helper"]:::backend
            LH["Language Helper"]:::backend
            OH["Ollama Helper"]:::backend
        end

        %% AI Provider Adapters
        subgraph "AI Provider Adapters"
            OS["Ollama Service Adapter"]:::ai
            VS["Vector Store Adapter"]:::ai
            DP["Document Provider Abstraction"]:::ai
            MP["Message Provider Abstraction"]:::ai
            CFG["AI Providers Config"]:::ai
        end

        %% Storage
        subgraph "Storage"
            FS["Model Storage\n(folder)"]:::storage
            DB["ChromaDB\n(vector store)"]:::storage
        end
    end

    %% Docker Network Boundary
    subgraph "Docker Network (ocrvnet)"
        OCR["Azure Form Recognizer\nHTTP :5000"]:::external
        SUM["Azure Text Analytics\nHTTP :5001"]:::external
        OLL["Ollama Daemon\ngRPC :11434"]:::external
    end

    %% Data Flows
    UI -->|"HTTP/REST"| API
    API -->|"call OCR\nHTTP"| DH
    DH -->|"/analyze"| OCR
    API -->|"chunking"| DH
    DH -->|"text chunks"| OS
    OS -->|"embeddings"| DB
    API -->|"query"| DB
    DB -->|"retrieved chunks"| OS
    OS -->|"completion"| API
    API -->|"summarization"| LH
    LH -->|"HTTP/REST"| SUM
    API -->|"respond"| UI

    %% Adapter to External Services
    OS -->|"gRPC/HTTP"| OLL
    VS -->|"reads/writes"| DB

    %% Component Click Events
    click UI "https://github.com/azure-samples/ai-knowledge/blob/main/frontend/app.py"
    click CI "https://github.com/azure-samples/ai-knowledge/blob/main/frontend/ui/components/chat_interface.py"
    click DV "https://github.com/azure-samples/ai-knowledge/blob/main/frontend/ui/components/document_viewer.py"
    click HD "https://github.com/azure-samples/ai-knowledge/blob/main/frontend/ui/components/header.py"
    click QS "https://github.com/azure-samples/ai-knowledge/blob/main/frontend/ui/components/question_suggestions.py"
    click SM "https://github.com/azure-samples/ai-knowledge/blob/main/frontend/ui/services/state_manager.py"
    click UC "https://github.com/azure-samples/ai-knowledge/blob/main/frontend/ui/services/ui_coordinator.py"
    click OS "https://github.com/azure-samples/ai-knowledge/blob/main/frontend/aiproviders/ollama_service.py"
    click VS "https://github.com/azure-samples/ai-knowledge/blob/main/frontend/aiproviders/vector_store.py"
    click DP "https://github.com/azure-samples/ai-knowledge/blob/main/frontend/aiproviders/document.py"
    click MP "https://github.com/azure-samples/ai-knowledge/blob/main/frontend/aiproviders/message.py"
    click CFG "https://github.com/azure-samples/ai-knowledge/blob/main/frontend/aiproviders/config.py"
    click API "https://github.com/azure-samples/ai-knowledge/blob/main/backend/main.py"
    click DH "https://github.com/azure-samples/ai-knowledge/blob/main/backend/helpers/doc_helper.py"
    click LH "https://github.com/azure-samples/ai-knowledge/blob/main/backend/helpers/language_helper.py"
    click OH "https://github.com/azure-samples/ai-knowledge/blob/main/backend/helpers/ollama_helper.py"
    click OCR "https://github.com/azure-samples/ai-knowledge/blob/main/README.md"
    click FS "https://github.com/azure-samples/ai-knowledge/blob/main/README.md"
    click DB "https://github.com/azure-samples/ai-knowledge/blob/main/requirements.txt"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#0366D6,color:#0366D6
    classDef backend fill:#E6FFEA,stroke:#028A0F,color:#028A0F
    classDef ai fill:#FFF5D7,stroke:#C69000,color:#C69000
    classDef storage fill:#F0F0F0,stroke:#6E6E6E,color:#6E6E6E
    classDef external fill:#FFE8E6,stroke:#D22B2B,color:#D22B2B
```
