# jesika-23/hackcult_aquashield architecture

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

- Interactive diagram: https://gitdiagram.com/jesika-23/hackcult_aquashield
- Repository: https://github.com/jesika-23/hackcult_aquashield

## Overview

AquaShield is a Streamlit prototype for AI-assisted underwater and sonar-style image review. Users upload an image, configure a confidence threshold, and receive YOLO detections with visual annotations and supporting quality, shadow, anomaly, and priority analysis. The app also supports optional preprocessing, reports, manually entered location visualization, session history, and human feedback logging. The graph reflects documented capabilities; unsampled app wiring is linked only where the README or source index supports it. Priority and shadow analysis are prototype heuristics, not validated risk or sonar-physics models.

Main entry points: [`app.py`](https://github.com/jesika-23/hackcult_aquashield/blob/main/app.py) (Streamlit application), [`utils/inference.py`](https://github.com/jesika-23/hackcult_aquashield/blob/main/utils/inference.py) (YOLO detection), [`utils/feedback.py`](https://github.com/jesika-23/hackcult_aquashield/blob/main/utils/feedback.py) (Feedback logging), [`utils/preprocess.py`](https://github.com/jesika-23/hackcult_aquashield/blob/main/utils/preprocess.py) (Image preprocessing)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["Review interface"]
  node_app["Streamlit application<br/>[app.py]"]
end

subgraph group_analysis["Image analysis"]
  node_preprocess["Image preprocessing<br/>[preprocess.py]"]
  node_detector["YOLO detection<br/>[inference.py]"]
  node_weights["YOLO weights<br/>[best.pt]"]
  node_quality["Image quality<br/>[quality.py]"]
  node_shadow["Shadow heuristics<br/>[shadow.py]"]
  node_anomaly["Visual anomalies<br/>[inference.py]"]
end

subgraph group_results["Review results"]
  node_priority["Priority scoring<br/>[priority.py]"]
  node_report["Analysis report<br/>[report.py]"]
  node_map["Location map<br/>[map_view.py]"]
end

subgraph group_state["History and feedback"]
  node_history["Session history<br/>[history.py]"]
  node_feedback["Feedback logging<br/>[feedback.py]"]
  node_feedbackcsv[("Feedback CSV<br/>[feedback_log.csv]")]
end

node_reviewer(("Human reviewer"))

node_reviewer -->|"uploads and reviews"| node_app
node_app -.->|"optionally enhances"| node_preprocess
node_app -->|"runs detection"| node_detector
node_detector -->|"uses weights"| node_weights
node_app -->|"assesses quality"| node_quality
node_app -->|"analyzes shadows"| node_shadow
node_app -->|"checks image differences"| node_anomaly
node_app -->|"scores detections"| node_priority
node_app -->|"generates report"| node_report
node_app -->|"shows locations"| node_map
node_app -->|"records session history"| node_history
node_app -->|"saves reviewer feedback"| node_feedback
node_feedback -->|"appends rows"| node_feedbackcsv

click node_app "https://github.com/jesika-23/hackcult_aquashield/blob/main/app.py"
click node_preprocess "https://github.com/jesika-23/hackcult_aquashield/blob/main/utils/preprocess.py"
click node_detector "https://github.com/jesika-23/hackcult_aquashield/blob/main/utils/inference.py"
click node_weights "https://github.com/jesika-23/hackcult_aquashield/blob/main/model/best.pt"
click node_quality "https://github.com/jesika-23/hackcult_aquashield/blob/main/utils/quality.py"
click node_shadow "https://github.com/jesika-23/hackcult_aquashield/blob/main/utils/shadow.py"
click node_anomaly "https://github.com/jesika-23/hackcult_aquashield/blob/main/utils/inference.py"
click node_priority "https://github.com/jesika-23/hackcult_aquashield/blob/main/utils/priority.py"
click node_report "https://github.com/jesika-23/hackcult_aquashield/blob/main/utils/report.py"
click node_map "https://github.com/jesika-23/hackcult_aquashield/blob/main/utils/map_view.py"
click node_history "https://github.com/jesika-23/hackcult_aquashield/blob/main/utils/history.py"
click node_feedback "https://github.com/jesika-23/hackcult_aquashield/blob/main/utils/feedback.py"
click node_feedbackcsv "https://github.com/jesika-23/hackcult_aquashield/blob/main/feedback_log.csv"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_app,node_reviewer toneBlue
class node_preprocess,node_detector,node_weights,node_quality,node_shadow,node_anomaly toneAmber
class node_priority,node_report,node_map toneMint
class node_history,node_feedback,node_feedbackcsv toneRose
```

## Components

### Review interface

- [Streamlit application](https://github.com/jesika-23/hackcult_aquashield/blob/main/app.py): `app.py`

### Image analysis

- [Image preprocessing](https://github.com/jesika-23/hackcult_aquashield/blob/main/utils/preprocess.py): `utils/preprocess.py`
- [YOLO detection](https://github.com/jesika-23/hackcult_aquashield/blob/main/utils/inference.py): `utils/inference.py`
- [YOLO weights](https://github.com/jesika-23/hackcult_aquashield/blob/main/model/best.pt): `model/best.pt`
- [Image quality](https://github.com/jesika-23/hackcult_aquashield/blob/main/utils/quality.py): `utils/quality.py`
- [Shadow heuristics](https://github.com/jesika-23/hackcult_aquashield/blob/main/utils/shadow.py): `utils/shadow.py`
- [Visual anomalies](https://github.com/jesika-23/hackcult_aquashield/blob/main/utils/inference.py): `utils/inference.py`

### Review results

- [Priority scoring](https://github.com/jesika-23/hackcult_aquashield/blob/main/utils/priority.py): `utils/priority.py`
- [Analysis report](https://github.com/jesika-23/hackcult_aquashield/blob/main/utils/report.py): `utils/report.py`
- [Location map](https://github.com/jesika-23/hackcult_aquashield/blob/main/utils/map_view.py): `utils/map_view.py`

### History and feedback

- [Session history](https://github.com/jesika-23/hackcult_aquashield/blob/main/utils/history.py): `utils/history.py`
- [Feedback logging](https://github.com/jesika-23/hackcult_aquashield/blob/main/utils/feedback.py): `utils/feedback.py`
- [Feedback CSV](https://github.com/jesika-23/hackcult_aquashield/blob/main/feedback_log.csv): `feedback_log.csv`

### Other components

- **Human reviewer**

## Connections

- Human reviewer → Streamlit application: uploads and reviews (evidence: `README.md`)
- Streamlit application → Image preprocessing: optionally enhances (evidence: `README.md`)
- Streamlit application → YOLO detection: runs detection (evidence: `README.md`)
- YOLO detection → YOLO weights: uses weights (evidence: `utils/inference.py`)
- Streamlit application → Image quality: assesses quality (evidence: `README.md`)
- Streamlit application → Shadow heuristics: analyzes shadows (evidence: `README.md`)
- Streamlit application → Visual anomalies: checks image differences (evidence: `utils/inference.py`)
- Streamlit application → Priority scoring: scores detections (evidence: `app.py`)
- Streamlit application → Analysis report: generates report (evidence: `README.md`)
- Streamlit application → Location map: shows locations (evidence: `README.md`)
- Streamlit application → Session history: records session history (evidence: `README.md`)
- Streamlit application → Feedback logging: saves reviewer feedback (evidence: `app.py`)
- Feedback logging → Feedback CSV: appends rows (evidence: `utils/feedback.py`)
