# nerveband/image_sense architecture

> Architecture diagram of the GitHub repository nerveband/image_sense, 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/nerveband/image_sense
- Repository: https://github.com/nerveband/image_sense

## Overview

##### Main Components

a) Client Layer:
- CLI Interface (src/cli)
- Configuration Management (src/core/config.py)
- Input Validation & Processing

b) Core Processing Layer:
- Image Processing Module (src/core/image_processor.py)
- LLM Handler (src/core/llm_handler.py)
- Metadata Handler (src/core/metadata_handler.py)
- Output Handler (src/core/output_handler.py)

c) External Services:
- Google Gemini Vision API
- Anthropic Claude API
- ExifTool Integration

d) Storage & Output:
- File System Storage
- Multiple Output Formats (CSV/XML)
- Metadata Storage

##### Flow Representation

Following key flows:
**User Input → CLI Interface → Image Processing → LLM Analysis → Metadata Generation → Output Generation**

##### Detailed Component Breakdown

Image Processing Pipeline:
**Input Image → Compression/Optimization → Vision API Processing → Metadata Extraction → Output Generation**

##### Key Relationships to Highlight

- CLI to Core Services interaction
- Image Processing to External APIs
- Metadata Handler to Storage
- Configuration Management across all components

##### Technical Details

- Environment configuration flow
- API integration points
- File format conversions
- Backup mechanisms

##### Architectural Patterns

Highlight:
- Modular design
- Service-oriented architecture
- Pipeline processing
- Event-driven components

**[User Interface Layer]**
- ↓
**[Configuration Layer]**
- ↓
**[Core Processing Layer]**
- ↓
**[External Services Layer]**
- ↓
**[Storage Layer]**

Remember to:
- Keep components aligned with the actual codebase structure
- Clear separation of concerns
- Scalability points
- Configuration touchpoints
- Version/model selection flows

- AI-powered analysis
- Batch processing capabilities
- Multiple output formats
- Metadata management
- Error handling and backup systems

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Styles
    classDef client fill:#a8d1f0,stroke:#000
    classDef core fill:#90EE90,stroke:#000
    classDef external fill:#DDA0DD,stroke:#000
    classDef storage fill:#FFA07A,stroke:#000
    classDef config fill:#FFE4B5,stroke:#000

    %% Client Layer
    subgraph ClientLayer
        CLI["CLI Interface"]
        ASCII["ASCII Art Interface"]
        InputVal["Input Validation"]
    end

    %% Configuration Layer
    subgraph ConfigLayer
        Config["Configuration Management"]
        EnvConfig["Environment Settings"]
    end

    %% Core Processing Layer
    subgraph CoreLayer
        ImgProc["Image Processing Module"]
        ImgUtils["Image Utilities"]
        LLMHandler["LLM Handler"]
        MetaHandler["Metadata Handler"]
        OutHandler["Output Handler"]
    end

    %% External Services Layer
    subgraph ExternalLayer
        GeminiAPI["Gemini Vision API"]
        ClaudeAPI["Anthropic Claude API"]
        ExifTool["ExifTool"]
    end

    %% Storage Layer
    subgraph StorageLayer
        FileSystem[("File System")]
        MetaStorage[("Metadata Storage")]
        OutputFormats[("Output Formats")]
    end

    %% Relationships
    CLI --> Config
    CLI --> InputVal
    ASCII --> CLI
    Config --> CoreLayer
    InputVal --> ImgProc
    ImgProc --> ImgUtils
    ImgProc --> LLMHandler
    ImgProc --> MetaHandler
    LLMHandler --> GeminiAPI
    LLMHandler --> ClaudeAPI
    MetaHandler --> ExifTool
    MetaHandler --> MetaStorage
    OutHandler --> OutputFormats
    OutputFormats --> FileSystem
    MetaStorage --> FileSystem

    %% Click Events
    click CLI "https://github.com/nerveband/image_sense/blob/main/src/cli/main.py"
    click Config "https://github.com/nerveband/image_sense/blob/main/src/core/config.py"
    click ImgProc "https://github.com/nerveband/image_sense/blob/main/src/core/image_processor.py"
    click ImgUtils "https://github.com/nerveband/image_sense/blob/main/src/core/image_utils.py"
    click LLMHandler "https://github.com/nerveband/image_sense/blob/main/src/core/llm_handler.py"
    click MetaHandler "https://github.com/nerveband/image_sense/blob/main/src/core/metadata_handler.py"
    click OutHandler "https://github.com/nerveband/image_sense/blob/main/src/core/output_handler.py"
    click GeminiAPI "https://github.com/nerveband/image_sense/tree/main/docs/gemini-docs/"
    click OutputFormats "https://github.com/nerveband/image_sense/tree/main/tests/test_images/bulk_images_5/metadata/"
    click ASCII "https://github.com/nerveband/image_sense/blob/main/src/core/ascii_art.py"

    %% Legend
    subgraph Legend
        L1["Client Components"]:::client
        L2["Core Components"]:::core
        L3["External Services"]:::external
        L4["Storage Components"]:::storage
        L5["Configuration"]:::config
    end

    %% Apply styles
    class CLI,ASCII,InputVal client
    class ImgProc,ImgUtils,LLMHandler,MetaHandler,OutHandler core
    class GeminiAPI,ClaudeAPI,ExifTool external
    class FileSystem,MetaStorage,OutputFormats storage
    class Config,EnvConfig config
```
