# bradcstevens/az-image-description-ai-matching architecture

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

- Interactive diagram: https://gitdiagram.com/bradcstevens/az-image-description-ai-matching
- Repository: https://github.com/bradcstevens/az-image-description-ai-matching

## Overview

##### Project Type and Purpose
- This is a command-line image-processing tool (an open-source utility) written in Python.
- It uses Azure OpenAI and Azure Computer Vision to analyze food images, match them against a menu list, then rename and store results with confidence scores.

##### File Structure Analysis
- Top-level:
- run.py – application entry point (CLI orchestrator)
- app/ – modular source code
- images/ – input JPEG images
- results/ – timestamped output folders with renamed images and JSON reports
- requirements.txt, .env.example – dependencies and environment variables
- app/config (Pydantic settings), app/core (service integrations & business logic), app/utils (file operations), app/tests (pytest unit tests)

##### Key Insights from README
- Modular design with clear separation of concerns
- Two Azure services (Vision AI and OpenAI) used in “dual-model” fashion
- CLI supports flags for input folder, output folder, description file, service toggles
- Results include both renamed images and a JSON report per run

##### Components
a. Main Components
- CLI Runner (run.py)
- Configuration Loader (app/config/settings.py)
- File Utils (app/utils/file_utils.py)
- Image Analyzer (app/core/image_analyzer.py)
- Azure Vision Service Wrapper (app/core/azure_vision.py)
- Azure OpenAI Service Wrapper (app/core/azure_openai.py)
- Description Loader (food-descriptions.txt parser)
- Results Store (timestamped folder + results.json)
- External Services: Azure Computer Vision API, Azure OpenAI API
b. Relationships & Interactions
1. CLI Runner reads CLI args → loads settings
2. CLI triggers Description Loader → builds in-memory list of menu items
3. CLI scans images directory → for each image:
– calls Image Analyzer
- Image Analyzer invokes Azure Vision wrapper → receives tags, OCR text
- Image Analyzer invokes Azure OpenAI wrapper → receives semantic description & confidence
- Combines results → computes final confidence score
– calls File Utils to rename/move image into results folder
4. After all images processed, CLI writes results.json via File Utils
c. Architectural Patterns & Principles
- Modular service wrappers (single responsibility for each Azure API)
- Dependency injection: Image Analyzer takes service instances as parameters for testability
- Configuration abstraction through Pydantic models
- Utility layer for file operations, isolating side-effects
- Timestamped output for idempotent runs
d. Technologies & Frameworks
- Python 3.8+
- Pydantic (settings model)
- Azure SDKs for Vision and OpenAI
- pytest for unit testing
- dotenv for environment variables

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Configuration"
        Settings["Configuration Loader\napp/config/settings.py"]:::config
    end

    subgraph "Core Logic"
        CLI["CLI Runner\nrun.py"]:::core
        Desc["Description Loader\nfood-descriptions.txt"]:::core
        Analyzer["Image Analyzer\napp/core/image_analyzer.py"]:::core
        Vision["Azure Vision Service Wrapper\napp/core/azure_vision.py"]:::service
        OpenAI["Azure OpenAI Service Wrapper\napp/core/azure_openai.py"]:::service
    end

    subgraph "Utilities"
        FileUtils["File Utils\napp/utils/file_utils.py"]:::util
    end

    subgraph "External Services"
        AZVision["Azure Computer Vision API"]:::external
        AZOpenAI["Azure OpenAI API"]:::external
    end

    subgraph "Persistence"
        FSImages["Input Images\nimages/"]:::persistence
        Results["Results Store\nresults/<timestamp>/results.json"]:::persistence
    end

    subgraph "Tests"
        Tests["Unit Tests\napp/tests"]:::test
    end

    FSImages -->|"image file list"| CLI
    CLI -->|"loads settings"| Settings
    CLI -->|"loads descriptions"| Desc
    CLI -->|"iterates images"| Analyzer
    Analyzer -->|"tags + OCR text"| Vision
    Vision --> AZVision
    Analyzer -->|"semantic description + score"| OpenAI
    OpenAI --> AZOpenAI
    Analyzer -->|"final confidence"| CLI
    Analyzer --> FileUtils
    FileUtils --> Results
    CLI -->|"write results.json"| FileUtils
    Tests --> Analyzer
    Tests --> Vision
    Tests --> OpenAI
    Tests --> FileUtils

    click CLI "https://github.com/bradcstevens/az-image-description-ai-matching/blob/main/run.py"
    click Settings "https://github.com/bradcstevens/az-image-description-ai-matching/blob/main/app/config/settings.py"
    click FileUtils "https://github.com/bradcstevens/az-image-description-ai-matching/blob/main/app/utils/file_utils.py"
    click Analyzer "https://github.com/bradcstevens/az-image-description-ai-matching/blob/main/app/core/image_analyzer.py"
    click Vision "https://github.com/bradcstevens/az-image-description-ai-matching/blob/main/app/core/azure_vision.py"
    click OpenAI "https://github.com/bradcstevens/az-image-description-ai-matching/blob/main/app/core/azure_openai.py"
    click Desc "https://github.com/bradcstevens/az-image-description-ai-matching/blob/main/food-descriptions.txt"
    click Results "https://github.com/bradcstevens/az-image-description-ai-matching/blob/main/results/<timestamp>/results.json"

    classDef config fill:#ADD8E6,stroke:#000;
    classDef core fill:#90EE90,stroke:#000;
    classDef service fill:#98FB98,stroke:#000;
    classDef util fill:#D3D3D3,stroke:#000;
    classDef external fill:#FFA500,stroke:#000;
    classDef persistence fill:#FFFFE0,stroke:#000;
    classDef test fill:#FFB6C1,stroke:#000;
```
