# osamaashraf01/al-baheth architecture

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

- Interactive diagram: https://gitdiagram.com/osamaashraf01/al-baheth
- Repository: https://github.com/osamaashraf01/al-baheth

## Overview

##### Project type and purpose
- This is a full-stack search engine (“Al-baheth”) that lets users upload local files, index their contents using multiple indexing/NLP services, and run queries against those indexes.
- The README confirms a FastAPI backend (Python 3.8+), a React/Vite/TypeScript frontend, MongoDB as the primary database, and Elasticsearch (plus PyTerrier, NLTK, LangChain) for indexing & retrieval.

##### High-level component breakdown
a. Frontend
- A Vite-powered React/TypeScript single-page app (src/…).
- Components: file uploader, search bar, results panel, theme toggle.
- Calls backend REST endpoints.
b. Backend (FastAPI)
- API layer: routes (files, indexing, query) → controllers.
- Business logic layer: services (DirectoryService, IndexingService, ElasticSearchService, PyTerrierService, NLP services, ParsingService).
- Data layer: repositories + MongoDB documents/models.
- Environment: runs on Uvicorn, configured via .env.
c. External systems
- MongoDB (via Docker Compose).
- Elasticsearch (possibly spun up in Docker).
- NLP libs (NLTK) and retrieval frameworks (PyTerrier, LangChain) as internal/external service stubs.
d. File system
- Local directory scanning for ingestion.

##### Relationships & data flow
- User ↔ Frontend: HTTP/HTTPS.
- Frontend ↔ Backend: REST calls to /files (upload/index), /index (trigger index), /query (search).
- Backend → DirectoryService: reads files from disk.
- Backend → Repositories → MongoDB: store document metadata & full text.
- Backend → IndexingService → Elasticsearch & PyTerrier: push and retrieve indexed data.
- Backend → NLP & Parsing services: preprocess text, chain prompts.
- Query path: user query → QueryController → NLP/Parsing → search engines → repository fetch → response → frontend.

##### Architectural patterns & tech
- Layered (Controller → Service → Repository).
- Hexagonal/infrastructure-driven: core logic is framework-agnostic, injected via dependencies.py.
- Micro-libraries for indexing/NLP aggregated behind a unified service interface.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Title
    subgraph "Al-baheth System Architecture"

    %% User and Frontend
    User["User"]:::external
    subgraph "Frontend (React/Vite)" 
        direction TB
        FrontendApp["Frontend Application"]:::frontend
        FileUploader["File Uploader"]:::frontend
        SearchBar["Search Bar"]:::frontend
        ResultsPanel["Results Panel"]:::frontend
        ResultItem["Result Item"]:::frontend
        ThemeToggle["Theme Toggle"]:::frontend
        ThemeContext["Theme Context"]:::frontend
        APIUtils["API Utilities"]:::frontend
    end

    %% Backend Layer
    subgraph "Backend (FastAPI)" 
        direction TB
        MainEntry["Main Entry (main.py)"]:::backend
        EnvConfig["Env Config (.env)"]:::backend

        subgraph "API / Controllers"
            direction TB
            FileController["FileController"]:::backend
            IndexingController["IndexingController"]:::backend
            QueryController["QueryController"]:::backend
            BaseController["BaseController"]:::backend
        end

        subgraph "Services"
            direction TB
            DirectoryService["DirectoryService"]:::backend
            IndexingService["IndexingService"]:::backend
            ElasticSearchService["ElasticSearchService"]:::backend
            PyTerrierService["PyTerrierService"]:::backend
            LanguageProcessingService["LanguageProcessingService"]:::backend
            NLTKService["NLTKService"]:::backend
            ParsingService["ParsingService"]:::backend
            LangChainService["LangChainService"]:::backend
            Dependencies["dependencies.py"]:::backend
        end

        subgraph "Data Layer"
            direction TB
            DocumentRepo["Document Repository"]:::backend
            Models["MongoDB Models"]:::backend
        end

        subgraph "Helpers & Config"
            direction TB
            Lifespan["Lifespan Helper"]:::backend
            ConfigHelper["Config Helper"]:::backend
        end
    end

    %% Data Stores and External
    subgraph "Data Stores"
        direction TB
        MongoDB[(MongoDB)]:::datastore
        Elasticsearch[(Elasticsearch)]:::datastore
        FileSystem["File System"]:::datastore
    end

    subgraph "External Libraries"
        direction TB
        PyTerrierExt["PyTerrier"]:::external
        NLTKExt["NLTK"]:::external
        LangChainExt["LangChain"]:::external
    end

    end

    %% Connections: User to Frontend
    User -->|"interacts via UI"| FrontendApp

    %% Frontend internal
    FrontendApp --> FileUploader
    FrontendApp --> SearchBar
    FrontendApp --> ResultsPanel
    ResultsPanel --> ResultItem
    FrontendApp --> ThemeToggle
    FrontendApp --> ThemeContext
    FrontendApp --> APIUtils

    %% Frontend to Backend
    APIUtils -->|POST /files| FileController
    APIUtils -->|POST /index| IndexingController
    APIUtils -->|GET /query| QueryController

    %% Controllers to Services
    FileController -->|reads disk| DirectoryService
    FileController -->|save metadata| DocumentRepo
    IndexingController -->|invoke| IndexingService
    QueryController -->|process| LanguageProcessingService
    QueryController -->|process| ParsingService

    %% Services to external libs
    DirectoryService --> FileSystem
    IndexingService --> ElasticSearchService
    IndexingService --> PyTerrierService
    ElasticSearchService --> Elasticsearch
    PyTerrierService --> PyTerrierExt
    LanguageProcessingService --> NLTKExt
    ParsingService --> LangChainService
    LangChainService --> LangChainExt

    %% Services to Data Layer
    DocumentRepo --> MongoDB
    QueryController -->|fetch| DocumentRepo

    %% Dependencies injection
    Dependencies --> DirectoryService
    Dependencies --> IndexingService
    Dependencies --> LanguageProcessingService
    Dependencies --> ParsingService

    %% Helpers
    MainEntry --> Lifespan
    MainEntry --> ConfigHelper
    MainEntry -->|includes| EnvConfig
    MainEntry --> FileController
    MainEntry --> IndexingController
    MainEntry --> QueryController

    %% Click events
    click FrontendApp "https://github.com/osamaashraf01/al-baheth/tree/main/frontend/"
    click FileUploader "https://github.com/osamaashraf01/al-baheth/blob/main/frontend/src/components/FileUploader.tsx"
    click SearchBar "https://github.com/osamaashraf01/al-baheth/blob/main/frontend/src/components/SearchBar.tsx"
    click ResultsPanel "https://github.com/osamaashraf01/al-baheth/blob/main/frontend/src/components/ResultsPanel.tsx"
    click ResultItem "https://github.com/osamaashraf01/al-baheth/blob/main/frontend/src/components/ResultItem.tsx"
    click ThemeToggle "https://github.com/osamaashraf01/al-baheth/blob/main/frontend/src/components/ThemeToggle.tsx"
    click ThemeContext "https://github.com/osamaashraf01/al-baheth/blob/main/frontend/src/context/ThemeContext.tsx"
    click APIUtils "https://github.com/osamaashraf01/al-baheth/blob/main/frontend/src/utils/api.ts"
    click MainEntry "https://github.com/osamaashraf01/al-baheth/blob/main/backend/core/main.py"
    click EnvConfig "https://github.com/osamaashraf01/al-baheth/blob/main/backend/core/.env.example"
    click FileController "https://github.com/osamaashraf01/al-baheth/blob/main/backend/core/controllers/FileController.py"
    click IndexingController "https://github.com/osamaashraf01/al-baheth/blob/main/backend/core/controllers/IndexingController.py"
    click QueryController "https://github.com/osamaashraf01/al-baheth/blob/main/backend/core/controllers/QueryController.py"
    click BaseController "https://github.com/osamaashraf01/al-baheth/blob/main/backend/core/controllers/BaseController.py"
    click DirectoryService "https://github.com/osamaashraf01/al-baheth/blob/main/backend/core/services/Directory/DirectoryService.py"
    click IndexingService "https://github.com/osamaashraf01/al-baheth/blob/main/backend/core/services/Indexing/IndexingService.py"
    click ElasticSearchService "https://github.com/osamaashraf01/al-baheth/blob/main/backend/core/services/Indexing/ElasticSearchService.py"
    click PyTerrierService "https://github.com/osamaashraf01/al-baheth/blob/main/backend/core/services/Indexing/PyTerrierService.py"
    click LanguageProcessingService "https://github.com/osamaashraf01/al-baheth/blob/main/backend/core/services/NLP/LanguageProcessingService.py"
    click NLTKService "https://github.com/osamaashraf01/al-baheth/blob/main/backend/core/services/NLP/NLTKService.py"
    click ParsingService "https://github.com/osamaashraf01/al-baheth/blob/main/backend/core/services/Parsing/ParsingService.py"
    click LangChainService "https://github.com/osamaashraf01/al-baheth/blob/main/backend/core/services/Parsing/LangChainService.py"
    click Dependencies "https://github.com/osamaashraf01/al-baheth/blob/main/backend/core/services/dependencies.py"
    click DocumentRepo "https://github.com/osamaashraf01/al-baheth/blob/main/backend/core/repositories/document_repository.py"
    click Models "https://github.com/osamaashraf01/al-baheth/blob/main/backend/core/models/document.py"
    click Models "https://github.com/osamaashraf01/al-baheth/blob/main/backend/core/models/file.py"
    click Lifespan "https://github.com/osamaashraf01/al-baheth/blob/main/backend/core/helpers/Lifespan.py"
    click ConfigHelper "https://github.com/osamaashraf01/al-baheth/blob/main/backend/core/helpers/config.py"
    click MongoDB "https://github.com/osamaashraf01/al-baheth/blob/main/docker/docker-compose.yml"
    click Elasticsearch "https://github.com/osamaashraf01/al-baheth/blob/main/docker/docker-compose.yml"

    %% Styles
    classDef frontend fill:#D6EFFF,stroke:#0284C7,color:#000
    classDef backend fill:#E8D7FF,stroke:#7C3AED,color:#000
    classDef datastore fill:#D1FAE5,stroke:#059669,color:#000
    classDef external fill:#FEF3C7,stroke:#D97706,color:#000
    classDef backendNodes fill:#F3F4F6,stroke:#9CA3AF,color:#000
    class FileController,IndexingController,QueryController,BaseController,DirectoryService,IndexingService,ElasticSearchService,PyTerrierService,LanguageProcessingService,NLTKService,ParsingService,LangChainService,Dependencies,DocumentRepo,Models,Lifespan,ConfigHelper mainEndpoints
    class mainEndpoints backendNodes
```
