# mwasifanwar/oceanmind architecture

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

- Interactive diagram: https://gitdiagram.com/mwasifanwar/oceanmind
- Repository: https://github.com/mwasifanwar/oceanmind

## Overview

##### Project Type and Purpose
- oceanmind is a domain-specific AI system (full-stack machine learning application) that processes underwater imagery and video to:
- Track marine life (fish_detector)
- Monitor coral reef health (coral_reef_detector)
- Detect illegal fishing (illegal_fishing_detector)
- It provides both a training pipeline (train.py) and an inference/service pipeline (main.py + api/app.py).

##### File-Structure Analysis
- Top-level directories:
- api/             → REST API service (app.py)
- config/          → application configuration (settings.py)
- data/            → data ingestion & loaders (dataloader.py)
- models/          → model definitions & inference wrappers
- processing/      → video/image processing pipeline
- utils/           → shared utilities (image processing, visualization)
- tests/           → unit tests
- Root scripts:
- main.py          → orchestrates end-to-end inference pipeline
- train.py         → orchestrates model training
- Requirements.txt pins dependencies.

##### Key Components
a. Data Sources
- Raw underwater imagery/videos (on-disk or cloud storage)
b. Data Ingestion Layer
- data/dataloader.py
c. Preprocessing Layer
- utils/image_processing.py
- processing/video_processor.py
d. Inference Engine
- models/*.py (fish, coral reef, illegal fishing detectors)
e. Post-processing & Visualization
- utils/visualization.py
f. API Layer
- api/app.py (Flask/FastAPI service)
g. Orchestration & CLI
- main.py (invokes ingestion → preprocessing → inference → output)
h. Configuration
- config/settings.py
i. Training Pipeline
- train.py (uses data loader, processing, models to train new weights)
j. Testing
- tests/test_models.py

##### Interactions & Data Flow
- (1) Ingestion: Raw data → Data Loader
- (2) Preprocessing: Video Processor + Image Processing
- (3) Inference: Preprocessed frames → Detector Models
- (4) Post-processing: Inference results → Visualization outputs
- (5) API: External clients → API Layer → calls main.py logic → returns detection results/visuals
- (6) Training: Raw data → train.py → model definitions → new model artifact
- (7) Configuration: settings injected at startup (both for API and training)

##### Architectural Patterns & Principles
- Layered architecture separating data, processing, inference, API
- Modular, plug-and-play detectors (each model in its own module)
- Single responsibility for each script/module
- Configuration-driven behavior (via config/settings.py)
- Reusable utilities for image processing and visualization

##### Inclusion Checklist
- Clear labels for every component (module name + file path)
- Distinction between training and inference pipelines
- Configuration source (config/settings.py) pointed to by all runtime components

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Data
    RawData["Raw Underwater Imagery/Videos"]:::external

    %% Layers
    subgraph "Data Ingestion Layer"
        DataLoader["DataLoader (data/dataloader.py)"]:::data
    end

    subgraph "Preprocessing Layer"
        VidProc["VideoProcessor (processing/video_processor.py)"]:::processing
        ImgProc["ImageProcessing (utils/image_processing.py)"]:::util
    end

    subgraph "Inference Engine"
        Fish["FishDetector (models/fish_detector.py)"]:::inference
        Coral["CoralReefDetector (models/coral_reef_detector.py)"]:::inference
        Illegal["IllegalFishingDetector (models/illegal_fishing_detector.py)"]:::inference
    end

    PostProc["Visualization (utils/visualization.py)"]:::util

    subgraph "API & Orchestration"
        API["API Service (api/app.py)"]:::api
        Main["Orchestration CLI (main.py)"]:::orchestration
    end

    Train["Training Pipeline (train.py)"]:::orchestration
    Config["Settings (config/settings.py)"]:::config
    Test["Test Suite (tests/test_models.py)"]:::testing

    %% Data Flow
    RawData --> DataLoader
    DataLoader --> VidProc
    DataLoader --> ImgProc
    VidProc --> ImgProc
    ImgProc --> Fish
    ImgProc --> Coral
    ImgProc --> Illegal
    Fish --> PostProc
    Coral --> PostProc
    Illegal --> PostProc
    PostProc --> Main
    API --> Main
    Main --> API

    RawData --> Train
    Train --> Fish
    Train --> Coral
    Train --> Illegal

    Config --> API
    Config --> Main
    Config --> Train

    Test --> Fish
    Test --> Coral
    Test --> Illegal

    %% Click Events
    click DataLoader "https://github.com/mwasifanwar/oceanmind/blob/main/data/dataloader.py"
    click ImgProc "https://github.com/mwasifanwar/oceanmind/blob/main/utils/image_processing.py"
    click VidProc "https://github.com/mwasifanwar/oceanmind/blob/main/processing/video_processor.py"
    click Fish "https://github.com/mwasifanwar/oceanmind/blob/main/models/fish_detector.py"
    click Coral "https://github.com/mwasifanwar/oceanmind/blob/main/models/coral_reef_detector.py"
    click Illegal "https://github.com/mwasifanwar/oceanmind/blob/main/models/illegal_fishing_detector.py"
    click PostProc "https://github.com/mwasifanwar/oceanmind/blob/main/utils/visualization.py"
    click API "https://github.com/mwasifanwar/oceanmind/blob/main/api/app.py"
    click Main "https://github.com/mwasifanwar/oceanmind/blob/main/main.py"
    click Train "https://github.com/mwasifanwar/oceanmind/blob/main/train.py"
    click Config "https://github.com/mwasifanwar/oceanmind/blob/main/config/settings.py"
    click Test "https://github.com/mwasifanwar/oceanmind/blob/main/tests/test_models.py"

    %% Styles
    classDef external fill:#bbdefb,stroke:#333,stroke-dasharray:5 5
    classDef data fill:#bbdefb,stroke:#333
    classDef processing fill:#c8e6c9,stroke:#333
    classDef util fill:#e0e0e0,stroke:#333
    classDef inference fill:#ffe0b2,stroke:#333
    classDef api fill:#d1c4e9,stroke:#333
    classDef orchestration fill:#ce93d8,stroke:#333
    classDef config fill:#bdbdbd,stroke:#333
    classDef testing fill:#ffccbc,stroke:#333,stroke-dasharray:5 5
```
