# iloncka-ds/culicidaelab architecture

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

- Interactive diagram: https://gitdiagram.com/iloncka-ds/culicidaelab
- Repository: https://github.com/iloncka-ds/culicidaelab

## Overview

##### Project Type and Purpose
- CulicidaeLab is an open-source, configuration-driven Python library for mosquito image analysis (classification, detection, segmentation).
- It’s not a monolithic web app or full-stack system; it’s a core inference engine with pluggable providers, datasets, and model backends, consumed by CLI, notebooks, and external applications (e.g., culicidaelab-server, mobile clients).

##### High-Level Architectural Layers
a. Configuration & Settings Layer
b. Core Services & Managers Layer
c. Predictor & Backend Layer
d. External Systems & Data Providers Layer

##### Main Components
a. Configuration Layer
- config_manager.py / config_models.py: loads YAML configs (app_settings, datasets, predictors, providers, species)
- settings.py: central Settings object
b. Core Services & Managers
- ResourceManager: handles caching/downloading model weights and datasets
- ProviderService: orchestrates data/weight retrieval via BaseProvider interfaces
- DatasetsManager: loads datasets based on config
- BasePredictor / BaseInferenceBackend: shared predictor interface
c. Predictor & Backend Layer
- Predictor Factory (backend_factory.py): maps Predictor classes to specific backends
- Predictor modules (classifier.py, detector.py, segmenter.py): user-facing classes
- Backends:
- classifier/_fastai.py, _onnx.py
- detector/_yolo.py
- segmenter/_sam.py
- ModelWeightsManager: versioning & retrieval of pretrained weights
d. Serve Module
- serve.py: CLI or programmatic entrypoint for serving predictions
e. External Systems
- HuggingFace, Kaggle, Roboflow (providers)
- Local filesystem / cache (for downloaded artifacts)
- Upstream datasets repositories

##### Relationships & Data Flow
1. User code or serve.py → get_settings()
2. Settings → config_manager → parse YAML → Settings object
3. Settings passed to Predictor constructor → ResourceManager & ProviderService invoked
4. ProviderService uses BaseProvider implementations to fetch models/datasets from external sources
5. ResourceManager caches artifacts on local disk
6. Predictor calls backend_factory → instantiates appropriate InferenceBackend
7. InferenceBackend loads model weights (via ModelWeightsManager) and ML framework (FastAI/ONNX/YOLO/SAM)
8. Predictor.predict(image) → backend.infer(image) → returns predictions

##### Architectural Patterns & Principles
- Dependency Injection: Settings object passed through constructors
- Factory Pattern: backend_factory selects the correct backend
- Strategy Pattern: interchangeable backends implementing the same inference interface
- Configuration-Driven: behavior entirely controlled via YAML, no hard-coded parameters
- Single Responsibility: each manager/service focuses on one concern (config, resources, providers, datasets, inference)

##### Technologies & Frameworks to Annotate
- Core: Python 3.11, Pydantic for config models
- ML frameworks: PyTorch/FastAI, ONNX Runtime, Ultralytics YOLO, SAM
- Providers: HuggingFace Hub SDK, Kaggle API, Roboflow API
- CLI & packaging: uv (uvicorn?), pytest for tests, mkdocs for docs

##### Essential Elements to Capture
- Config layer feeding all downstream components
- Core services/managers that abstract resource handling and data loading
- Predictor classes vs. backend implementations
- ModelWeightsManager as the nexus for weight versioning/download
- External providers and local cache boundary
- Entry points (Python API, CLI, notebooks)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Entry Points
    Serve["serve.py"]:::entry
    Notebook["Notebooks / Scripts"]:::entry

    %% Configuration & Settings Layer
    subgraph "Configuration & Settings Layer"
        direction TB
        ConfigFiles["YAML Configs\n(culicidaelab/conf/)"]:::config
        ConfigManager["config_manager.py"]:::config
        ConfigModels["config_models.py"]:::config
        Settings["settings.py"]:::config
    end

    %% Core Services & Managers Layer
    subgraph "Core Services & Managers Layer"
        direction TB
        ResourceManager["ResourceManager"]:::core
        ProviderService["ProviderService"]:::core
        DatasetsManager["DatasetsManager"]:::core
        BasePredictor["BasePredictor"]:::core
        BaseInferenceBackend["BaseInferenceBackend"]:::core
        BaseProvider["BaseProvider"]:::core
    end

    %% Predictor & Backend Layer
    subgraph "Predictor & Backend Layer"
        direction TB
        BackendFactory["backend_factory.py"]:::predictor
        ClassifierPred["classifier.py"]:::predictor
        DetectorPred["detector.py"]:::predictor
        SegmenterPred["segmenter.py"]:::predictor
        ModelWeightsMgr["ModelWeightsManager"]:::predictor

        subgraph "Classifier Backends"
            direction TB
            FastAI["_fastai.py"]:::predictor
            ONNX["_onnx.py"]:::predictor
        end

        subgraph "Detector Backend"
            direction TB
            YOLO["_yolo.py"]:::predictor
        end

        subgraph "Segmenter Backend"
            direction TB
            SAM["_sam.py"]:::predictor
        end
    end

    %% External Systems & Data Providers Layer
    subgraph "External Systems & Data Providers Layer"
        direction TB
        HFCloud["HuggingFace"]:::external
        KaggleCloud["Kaggle"]:::external
        RoboflowCloud["Roboflow"]:::external
        HFProvider["huggingface_provider.py"]:::external
        ProviderConfigs["Provider YAML\n(culicidaelab/conf/providers/)"]:::external
        LocalCache["Local Cache"]:::data
    end

    %% Relationships
    Serve -->|"load settings"| ConfigManager
    Notebook -->|"load settings"| ConfigManager
    ConfigFiles --> ConfigManager
    ConfigManager -->|"parse YAML"| Settings
    ConfigModels --> Settings

    Settings --> ResourceManager
    Settings --> ProviderService
    Settings --> DatasetsManager
    Settings --> BasePredictor

    ProviderService --> HFProvider
    ProviderService --> ProviderConfigs
    HFProvider --> HFCloud
    ProviderService --> LocalCache
    ResourceManager --> LocalCache
    DatasetsManager --> LocalCache

    BasePredictor --> BackendFactory
    BackendFactory --> ClassifierPred
    BackendFactory --> DetectorPred
    BackendFactory --> SegmenterPred

    ClassifierPred --> FastAI
    ClassifierPred --> ONNX
    DetectorPred --> YOLO
    SegmenterPred --> SAM

    FastAI --> ModelWeightsMgr
    ONNX --> ModelWeightsMgr
    YOLO --> ModelWeightsMgr
    SAM --> ModelWeightsMgr

    ModelWeightsMgr --> LocalCache

    %% Click Events
    click ConfigManager "https://github.com/iloncka-ds/culicidaelab/blob/main/culicidaelab/core/config_manager.py"
    click ConfigModels "https://github.com/iloncka-ds/culicidaelab/blob/main/culicidaelab/core/config_models.py"
    click Settings "https://github.com/iloncka-ds/culicidaelab/blob/main/culicidaelab/core/settings.py"
    click ConfigFiles "https://github.com/iloncka-ds/culicidaelab/tree/main/culicidaelab/conf/"
    click ResourceManager "https://github.com/iloncka-ds/culicidaelab/blob/main/culicidaelab/core/resource_manager.py"
    click ProviderService "https://github.com/iloncka-ds/culicidaelab/blob/main/culicidaelab/core/provider_service.py"
    click DatasetsManager "https://github.com/iloncka-ds/culicidaelab/blob/main/culicidaelab/datasets/datasets_manager.py"
    click BasePredictor "https://github.com/iloncka-ds/culicidaelab/blob/main/culicidaelab/core/base_predictor.py"
    click BaseInferenceBackend "https://github.com/iloncka-ds/culicidaelab/blob/main/culicidaelab/core/base_inference_backend.py"
    click BaseProvider "https://github.com/iloncka-ds/culicidaelab/blob/main/culicidaelab/core/base_provider.py"
    click BackendFactory "https://github.com/iloncka-ds/culicidaelab/blob/main/culicidaelab/predictors/backend_factory.py"
    click ClassifierPred "https://github.com/iloncka-ds/culicidaelab/blob/main/culicidaelab/predictors/classifier.py"
    click DetectorPred "https://github.com/iloncka-ds/culicidaelab/blob/main/culicidaelab/predictors/detector.py"
    click SegmenterPred "https://github.com/iloncka-ds/culicidaelab/blob/main/culicidaelab/predictors/segmenter.py"
    click ModelWeightsMgr "https://github.com/iloncka-ds/culicidaelab/blob/main/culicidaelab/predictors/model_weights_manager.py"
    click FastAI "https://github.com/iloncka-ds/culicidaelab/blob/main/culicidaelab/predictors/backends/classifier/_fastai.py"
    click ONNX "https://github.com/iloncka-ds/culicidaelab/blob/main/culicidaelab/predictors/backends/classifier/_onnx.py"
    click YOLO "https://github.com/iloncka-ds/culicidaelab/blob/main/culicidaelab/predictors/backends/detector/_yolo.py"
    click SAM "https://github.com/iloncka-ds/culicidaelab/blob/main/culicidaelab/predictors/backends/segmenter/_sam.py"
    click Serve "https://github.com/iloncka-ds/culicidaelab/blob/main/culicidaelab/serve.py"
    click HFProvider "https://github.com/iloncka-ds/culicidaelab/blob/main/culicidaelab/providers/huggingface_provider.py"
    click ProviderConfigs "https://github.com/iloncka-ds/culicidaelab/tree/main/culicidaelab/conf/providers/"

    %% Styles
    classDef entry fill:#f9f,stroke:#333,stroke-width:1px
    classDef config fill:#afa,stroke:#333,stroke-width:1px
    classDef core fill:#afe,stroke:#333,stroke-width:1px
    classDef predictor fill:#da0,stroke:#333,stroke-width:1px
    classDef external fill:#fca,stroke:#333,stroke-width:1px
    classDef data fill:#ccf,stroke:#333,stroke-width:1px
```
