# harmonydata/harmonyapi architecture

> Architecture diagram of the GitHub repository harmonydata/harmonyapi, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2024-12-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/harmonydata/harmonyapi
- Repository: https://github.com/harmonydata/harmonyapi

## Overview

##### Main Components

a. Client Layer:
- External clients (Web browsers, API consumers)
- Docker containers for local deployment
- React frontend (referenced but not in this repository)

b. API Layer:
- FastAPI application
- Main routers (/text, /health-check, /info endpoints)
- Request/response handling

c. Core Services:
- Text parsing service
- Matching service
- Embedding services (OpenAI, Azure, Google, HuggingFace)
- Caching system
- Instrument processing

d. External Dependencies:
- Apache Tika server for PDF parsing
- Azure Functions for spaCy
- Azure Blob Storage
- Sentence transformers
- Various ML models

##### Architecture Patterns to Highlight

- Microservices architecture (main API + Tika server + Azure Functions)
- Dependency injection pattern (visible in the services structure)
- Caching strategy (vectors_cache and instruments_cache)
- Multiple deployment options (Docker, AWS Lambda, Azure)

**┌─ Client Layer ─────────────────────┐**

- ┘
**┌─ API Layer ──────────────────────┐**

- ┘
**┌─ Services Layer ─────────────────┐**

- ┘
**┌─ External Services ──────────────┐**

- ┘

##### Key Relationships

- Client requests flowing through FastAPI endpoints
- Text processing pipeline (PDF/Excel → Tika → Parser → Matcher)
- Multiple embedding service options (OpenAI, Azure, Google, HuggingFace)
- Caching system interaction with core services
- Data persistence and storage interactions

##### Important Details

- API endpoints (/text/parse, /text/match, etc.)
- Supported file formats (PDF, XLSX, TXT)
- Language support (multilingual capabilities)
- Caching mechanisms
- Authentication/authorization flow (if implemented)

##### Deployment Options

Alternative deployment paths:
- Docker container deployment
- AWS Lambda serverless deployment
- Azure deployment with Functions

##### Technical Details to Highlight

- FastAPI framework
- Python-based services
- Docker containerization
- ML model integration
- PDF processing capabilities
- Excel file handling
- Multilingual support
- Vector-based matching

## Diagram (Mermaid)

```mermaid
graph TB
    %% Client Layer
    subgraph CL["Client Layer"]
        WC[Web Clients]
        AC[API Consumers]
        RF[React Frontend]
    end

    %% API Layer
    subgraph AL["API Layer"]
        FA["FastAPI Application"]:::api
        click FA "https://github.com/harmonydata/harmonyapi/blob/main/main.py"
        
        subgraph Routers["API Routers"]
            HC["Health Check Router"]:::router
            click HC "https://github.com/harmonydata/harmonyapi/blob/main/harmony_api/routers/health_check_router.py"
            IR["Info Router"]:::router
            click IR "https://github.com/harmonydata/harmonyapi/blob/main/harmony_api/routers/info_router.py"
            TR["Text Router"]:::router
            click TR "https://github.com/harmonydata/harmonyapi/blob/main/harmony_api/routers/text_router.py"
        end
        
        DP["Dependencies"]:::core
        click DP "https://github.com/harmonydata/harmonyapi/blob/main/harmony_api/dependencies.py"
    end

    %% Core Services Layer
    subgraph SL["Services Layer"]
        subgraph ES["Embedding Services"]
            OAI["OpenAI Service"]:::embedding
            click OAI "https://github.com/harmonydata/harmonyapi/blob/main/harmony_api/services/openai_embeddings.py"
            AZ["Azure OpenAI Service"]:::embedding
            click AZ "https://github.com/harmonydata/harmonyapi/blob/main/harmony_api/services/azure_openai_embeddings.py"
            GE["Google Service"]:::embedding
            click GE "https://github.com/harmonydata/harmonyapi/blob/main/harmony_api/services/google_embeddings.py"
            HF["HuggingFace Service"]:::embedding
            click HF "https://github.com/harmonydata/harmonyapi/blob/main/harmony_api/services/hugging_face_embeddings.py"
        end

        subgraph CS["Caching System"]
            VC["Vectors Cache"]:::cache
            click VC "https://github.com/harmonydata/harmonyapi/blob/main/harmony_api/services/vectors_cache.py"
            IC["Instruments Cache"]:::cache
            click IC "https://github.com/harmonydata/harmonyapi/blob/main/harmony_api/services/instruments_cache.py"
        end

        subgraph Core["Core Components"]
            SET["Settings"]:::core
            click SET "https://github.com/harmonydata/harmonyapi/blob/main/harmony_api/core/settings.py"
            LOG["Logger"]:::core
            click LOG "https://github.com/harmonydata/harmonyapi/blob/main/harmony_api/core/logger.py"
            CON["Constants"]:::core
            click CON "https://github.com/harmonydata/harmonyapi/blob/main/harmony_api/constants.py"
            HLP["Helpers"]:::core
            click HLP "https://github.com/harmonydata/harmonyapi/blob/main/harmony_api/helpers.py"
        end
    end

    %% External Services Layer
    subgraph EX["External Services"]
        TS["Apache Tika Server"]:::external
        AF["Azure Functions"]:::external
        ABS["Azure Blob Storage"]:::external
        ST["Sentence Transformers"]:::external
    end

    %% Deployment Options
    subgraph DO["Deployment Options"]
        DC["Docker Container"]:::deployment
        click DC "https://github.com/harmonydata/harmonyapi/tree/main/Dockerfile"
        DCP["Docker Compose"]:::deployment
        click DCP "https://github.com/harmonydata/harmonyapi/blob/main/docker_compose.yaml"
        AD["Azure Deployment"]:::deployment
        click AD "https://github.com/harmonydata/harmonyapi/blob/main/build_push_harmony_azure.sh"
        AWS["AWS Lambda"]:::deployment
    end

    %% Testing Infrastructure
    subgraph TI["Testing Infrastructure"]
        LT["Local Tests"]:::test
        click LT "https://github.com/harmonydata/harmonyapi/tree/main/tests/local_tests/"
        RT["Remote Tests"]:::test
        click RT "https://github.com/harmonydata/harmonyapi/tree/main/tests/remote_tests/"
        ST["Staging Tests"]:::test
        click ST "https://github.com/harmonydata/harmonyapi/tree/main/tests/staging_tests/"
    end

    %% Relationships
    CL --> FA
    FA --> Routers
    FA --> DP
    TR --> ES
    TR --> CS
    TR --> TS
    ES --> ABS
    ES --> AF
    CS --> ABS

    %% Styles
    classDef api fill:#2374ab
    classDef router fill:#2374ab,stroke:#164b69
    classDef embedding fill:#48a9a6
    classDef cache fill:#e4cc37
    classDef core fill:#407899
    classDef external fill:#89a894
    classDef deployment fill:#9b6b6c
    classDef test fill:#7d7d7d

    %% Legend
    subgraph Legend
        L1["API Components"]:::api
        L2["Embedding Services"]:::embedding
        L3["Caching System"]:::cache
        L4["Core Components"]:::core
        L5["External Services"]:::external
        L6["Deployment Options"]:::deployment
        L7["Testing Infrastructure"]:::test
    end
```
