# stuv1983/aqualog architecture

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

- Interactive diagram: https://gitdiagram.com/stuv1983/aqualog
- Repository: https://github.com/stuv1983/aqualog

## Overview

AquaLog is a local Streamlit aquarium-management dashboard backed by SQLite. Users select or configure a tank in the sidebar, log water tests, then inspect overview, warnings, analytics, cycle status, inventory, maintenance, and calculator views. The main entry point initializes storage and dispatches these views. Repository excerpts establish several UI-to-data and utility relationships; README capability statements fill in unsampled feature areas. Weekly email delivery is documented, but its runtime sender is not shown in the sampled source.

Main entry points: [`main.py`](https://github.com/stuv1983/aqualog/blob/master/main.py) (Dashboard entry), [`aqualog_db/repositories/tank.py`](https://github.com/stuv1983/aqualog/blob/master/aqualog_db/repositories/tank.py) (Tank repository), [`aqualog_db/base.py`](https://github.com/stuv1983/aqualog/blob/master/aqualog_db/base.py) (Repository database layer), [`sidebar/sidebar.py`](https://github.com/stuv1983/aqualog/blob/master/sidebar/sidebar.py) (Sidebar controls)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["App and navigation"]
  node_main["Dashboard entry<br/>[main.py]"]
  node_sidebar["Sidebar controls<br/>[sidebar.py]"]
  node_localization["Localization and units<br/>[localization.py]"]
end

subgraph group_water["Water quality"]
  node_logging["Water-test form<br/>[water_test_form.py]"]
  node_overview["Overview dashboard<br/>[overview_tab.py]"]
  node_warnings["Warnings and advice<br/>[warnings_tab.py]"]
  node_alerts["Range alert banner<br/>[alerts.py]"]
  node_validation["Range validation<br/>[validation.py]"]
end

subgraph group_management["Tank management"]
  node_tankselect["Tank selector<br/>[tank_selector.py]"]
  node_settings["Tank and app settings<br/>[settings_panel.py]"]
  node_inventory["Fish and plant inventory"]
  node_equipment["Equipment inventory<br/>[equipment_tab.py]"]
  node_maintenance["Maintenance log<br/>[maintenance_tab.py]"]
  node_emailprefs["Weekly report preferences<br/>[email_settings.py]"]
end

subgraph group_analysis["Analysis and tools"]
  node_analytics["Data analytics"]
  node_cycle["Cycle tracker<br/>[cycle_tab.py]"]
  node_tools["Aquarium calculators<br/>[tools_tab.py]"]
  node_chemistry["Chemistry calculations<br/>[chemistry.py]"]
end

subgraph group_storage["SQLite persistence"]
  node_dbinit["Schema initialization<br/>[schema.py]"]
  node_tankrepo["Tank repository<br/>[tank.py]"]
  node_waterrepo["Water-test repository"]
  node_catalogrepos["Inventory repositories"]
  node_maintrepo["Maintenance repository<br/>[maintenance.py]"]
  node_customrepo["Custom-range repository<br/>[custom_range.py]"]
  node_dbbase["Repository database layer<br/>[base.py]"]
  node_connection["SQLite connection manager<br/>[connection.py]"]
  node_sqlite[("Local SQLite database")]
end

node_user(("Aquarium keeper"))
node_smtp["SMTP service"]

node_user -->|"opens dashboard"| node_main
node_main -->|"initializes schema"| node_dbinit
node_main -->|"renders sidebar"| node_sidebar
node_main -->|"dispatches view"| node_overview
node_main -->|"dispatches view"| node_warnings
node_main -->|"dispatches view"| node_analytics
node_main -->|"dispatches view"| node_cycle
node_main -->|"dispatches view"| node_tools
node_main -->|"dispatches views"| node_inventory
node_main -->|"dispatches view"| node_equipment
node_main -->|"dispatches view"| node_maintenance
node_sidebar -->|"renders selector"| node_tankselect
node_sidebar -->|"renders settings"| node_settings
node_sidebar -->|"renders form"| node_logging
node_settings -->|"manages tanks"| node_tankrepo
node_settings -->|"configures preferences"| node_emailprefs
node_logging -->|"records readings"| node_waterrepo
node_tankselect -->|"loads tanks"| node_tankrepo
node_overview -->|"reads tank details"| node_tankrepo
node_overview -->|"reads test history"| node_waterrepo
node_warnings -->|"checks readings"| node_validation
node_warnings -->|"reads stored data"| node_connection
node_alerts -->|"loads latest test"| node_waterrepo
node_alerts -->|"checks ranges"| node_validation
node_validation -->|"loads custom ranges"| node_customrepo
node_validation -->|"loads tank settings"| node_tankrepo
node_analytics -->|"queries test data"| node_connection
node_cycle -->|"uses water records"| node_waterrepo
node_tools -->|"calculates doses"| node_chemistry
node_tools -->|"uses tank volume"| node_tankrepo
node_inventory -->|"manages livestock"| node_catalogrepos
node_equipment -->|"manages equipment"| node_catalogrepos
node_maintenance -->|"records tasks"| node_maintrepo
node_logging -->|"translates form"| node_localization
node_dbinit -->|"creates schema"| node_sqlite
node_tankrepo -->|"uses repository layer"| node_dbbase
node_maintrepo -->|"uses repository layer"| node_dbbase
node_customrepo -->|"uses repository layer"| node_dbbase
node_emailprefs -->|"uses repository layer"| node_dbbase
node_dbbase -->|"reads and writes"| node_sqlite
node_connection -->|"opens database"| node_sqlite
node_settings -->|"sets safe ranges"| node_customrepo
node_emailprefs -.->|"weekly delivery"| node_smtp

click node_main "https://github.com/stuv1983/aqualog/blob/master/main.py"
click node_sidebar "https://github.com/stuv1983/aqualog/blob/master/sidebar/sidebar.py"
click node_tankselect "https://github.com/stuv1983/aqualog/blob/master/sidebar/tank_selector.py"
click node_settings "https://github.com/stuv1983/aqualog/blob/master/sidebar/settings_panel.py"
click node_logging "https://github.com/stuv1983/aqualog/blob/master/sidebar/water_test_form.py"
click node_overview "https://github.com/stuv1983/aqualog/blob/master/tabs/overview_tab.py"
click node_warnings "https://github.com/stuv1983/aqualog/blob/master/tabs/warnings_tab.py"
click node_alerts "https://github.com/stuv1983/aqualog/blob/master/utils/ui/alerts.py"
click node_validation "https://github.com/stuv1983/aqualog/blob/master/utils/validation.py"
click node_analytics "https://github.com/stuv1983/aqualog/blob/master/tabs/data_analytics_tab.py"
click node_cycle "https://github.com/stuv1983/aqualog/blob/master/tabs/cycle_tab.py"
click node_tools "https://github.com/stuv1983/aqualog/blob/master/tabs/tools_tab.py"
click node_chemistry "https://github.com/stuv1983/aqualog/blob/master/utils/chemistry.py"
click node_inventory "https://github.com/stuv1983/aqualog/tree/master/tabs"
click node_equipment "https://github.com/stuv1983/aqualog/blob/master/tabs/equipment_tab.py"
click node_maintenance "https://github.com/stuv1983/aqualog/blob/master/tabs/maintenance_tab.py"
click node_localization "https://github.com/stuv1983/aqualog/blob/master/utils/localization.py"
click node_emailprefs "https://github.com/stuv1983/aqualog/blob/master/aqualog_db/repositories/email_settings.py"
click node_dbinit "https://github.com/stuv1983/aqualog/blob/master/aqualog_db/schema.py"
click node_tankrepo "https://github.com/stuv1983/aqualog/blob/master/aqualog_db/repositories/tank.py"
click node_waterrepo "https://github.com/stuv1983/aqualog/tree/master/aqualog_db/repositories"
click node_catalogrepos "https://github.com/stuv1983/aqualog/tree/master/aqualog_db/repositories"
click node_maintrepo "https://github.com/stuv1983/aqualog/blob/master/aqualog_db/repositories/maintenance.py"
click node_customrepo "https://github.com/stuv1983/aqualog/blob/master/aqualog_db/repositories/custom_range.py"
click node_dbbase "https://github.com/stuv1983/aqualog/blob/master/aqualog_db/base.py"
click node_connection "https://github.com/stuv1983/aqualog/blob/master/aqualog_db/connection.py"

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_main,node_sidebar,node_localization toneBlue
class node_logging,node_overview,node_warnings,node_alerts,node_validation toneAmber
class node_tankselect,node_settings,node_inventory,node_equipment,node_maintenance,node_emailprefs toneMint
class node_analytics,node_cycle,node_tools,node_chemistry toneRose
class node_dbinit,node_tankrepo,node_waterrepo,node_catalogrepos,node_maintrepo,node_customrepo,node_dbbase,node_connection,node_sqlite,node_user,node_smtp toneIndigo
```

## Components

### App and navigation

- [Dashboard entry](https://github.com/stuv1983/aqualog/blob/master/main.py): `main.py`
- [Sidebar controls](https://github.com/stuv1983/aqualog/blob/master/sidebar/sidebar.py): `sidebar/sidebar.py`
- [Localization and units](https://github.com/stuv1983/aqualog/blob/master/utils/localization.py): `utils/localization.py`

### Water quality

- [Water-test form](https://github.com/stuv1983/aqualog/blob/master/sidebar/water_test_form.py): `sidebar/water_test_form.py`
- [Overview dashboard](https://github.com/stuv1983/aqualog/blob/master/tabs/overview_tab.py): `tabs/overview_tab.py`
- [Warnings and advice](https://github.com/stuv1983/aqualog/blob/master/tabs/warnings_tab.py): `tabs/warnings_tab.py`
- [Range alert banner](https://github.com/stuv1983/aqualog/blob/master/utils/ui/alerts.py): `utils/ui/alerts.py`
- [Range validation](https://github.com/stuv1983/aqualog/blob/master/utils/validation.py): `utils/validation.py`

### Tank management

- [Tank selector](https://github.com/stuv1983/aqualog/blob/master/sidebar/tank_selector.py): `sidebar/tank_selector.py`
- [Tank and app settings](https://github.com/stuv1983/aqualog/blob/master/sidebar/settings_panel.py): `sidebar/settings_panel.py`
- [Fish and plant inventory](https://github.com/stuv1983/aqualog/tree/master/tabs): `tabs`
- [Equipment inventory](https://github.com/stuv1983/aqualog/blob/master/tabs/equipment_tab.py): `tabs/equipment_tab.py`
- [Maintenance log](https://github.com/stuv1983/aqualog/blob/master/tabs/maintenance_tab.py): `tabs/maintenance_tab.py`
- [Weekly report preferences](https://github.com/stuv1983/aqualog/blob/master/aqualog_db/repositories/email_settings.py): `aqualog_db/repositories/email_settings.py`

### Analysis and tools

- [Data analytics](https://github.com/stuv1983/aqualog/blob/master/tabs/data_analytics_tab.py): `tabs/data_analytics_tab.py`
- [Cycle tracker](https://github.com/stuv1983/aqualog/blob/master/tabs/cycle_tab.py): `tabs/cycle_tab.py`
- [Aquarium calculators](https://github.com/stuv1983/aqualog/blob/master/tabs/tools_tab.py): `tabs/tools_tab.py`
- [Chemistry calculations](https://github.com/stuv1983/aqualog/blob/master/utils/chemistry.py): `utils/chemistry.py`

### SQLite persistence

- [Schema initialization](https://github.com/stuv1983/aqualog/blob/master/aqualog_db/schema.py): `aqualog_db/schema.py`
- [Tank repository](https://github.com/stuv1983/aqualog/blob/master/aqualog_db/repositories/tank.py): `aqualog_db/repositories/tank.py`
- [Water-test repository](https://github.com/stuv1983/aqualog/tree/master/aqualog_db/repositories): `aqualog_db/repositories`
- [Inventory repositories](https://github.com/stuv1983/aqualog/tree/master/aqualog_db/repositories): `aqualog_db/repositories`
- [Maintenance repository](https://github.com/stuv1983/aqualog/blob/master/aqualog_db/repositories/maintenance.py): `aqualog_db/repositories/maintenance.py`
- [Custom-range repository](https://github.com/stuv1983/aqualog/blob/master/aqualog_db/repositories/custom_range.py): `aqualog_db/repositories/custom_range.py`
- [Repository database layer](https://github.com/stuv1983/aqualog/blob/master/aqualog_db/base.py): `aqualog_db/base.py`
- [SQLite connection manager](https://github.com/stuv1983/aqualog/blob/master/aqualog_db/connection.py): `aqualog_db/connection.py`
- **Local SQLite database**

### Other components

- **Aquarium keeper**
- **SMTP service**

## Connections

- Aquarium keeper → Dashboard entry: opens dashboard
- Dashboard entry → Schema initialization: initializes schema (evidence: `main.py`)
- Dashboard entry → Sidebar controls: renders sidebar (evidence: `main.py`)
- Dashboard entry → Overview dashboard: dispatches view (evidence: `main.py`)
- Dashboard entry → Warnings and advice: dispatches view (evidence: `main.py`)
- Dashboard entry → Data analytics: dispatches view (evidence: `main.py`)
- Dashboard entry → Cycle tracker: dispatches view (evidence: `main.py`)
- Dashboard entry → Aquarium calculators: dispatches view (evidence: `main.py`)
- Dashboard entry → Fish and plant inventory: dispatches views (evidence: `main.py`)
- Dashboard entry → Equipment inventory: dispatches view (evidence: `main.py`)
- Dashboard entry → Maintenance log: dispatches view (evidence: `main.py`)
- Sidebar controls → Tank selector: renders selector (evidence: `sidebar/sidebar.py`)
- Sidebar controls → Tank and app settings: renders settings (evidence: `sidebar/sidebar.py`)
- Sidebar controls → Water-test form: renders form (evidence: `sidebar/sidebar.py`)
- Tank and app settings → Tank repository: manages tanks (evidence: `sidebar/settings_panel.py`)
- Tank and app settings → Weekly report preferences: configures preferences (evidence: `sidebar/settings_panel.py`)
- Water-test form → Water-test repository: records readings (evidence: `sidebar/water_test_form.py`)
- Tank selector → Tank repository: loads tanks (evidence: `sidebar/tank_selector.py`)
- Overview dashboard → Tank repository: reads tank details (evidence: `tabs/overview_tab.py`)
- Overview dashboard → Water-test repository: reads test history (evidence: `tabs/overview_tab.py`)
- Warnings and advice → Range validation: checks readings (evidence: `tabs/warnings_tab.py`)
- Warnings and advice → SQLite connection manager: reads stored data (evidence: `tabs/warnings_tab.py`)
- Range alert banner → Water-test repository: loads latest test (evidence: `utils/ui/alerts.py`)
- Range alert banner → Range validation: checks ranges (evidence: `utils/ui/alerts.py`)
- Range validation → Custom-range repository: loads custom ranges (evidence: `utils/validation.py`)
- Range validation → Tank repository: loads tank settings (evidence: `utils/validation.py`)
- Data analytics → SQLite connection manager: queries test data (evidence: `tabs/data_analytics_tab.py`)
- Cycle tracker → Water-test repository: uses water records (evidence: `tabs/cycle_tab.py`)
- Aquarium calculators → Chemistry calculations: calculates doses (evidence: `tabs/tools_tab.py`)
- Aquarium calculators → Tank repository: uses tank volume (evidence: `tabs/tools_tab.py`)
- Fish and plant inventory → Inventory repositories: manages livestock (evidence: `tabs/fish_inventory_tab.py`)
- Equipment inventory → Inventory repositories: manages equipment (evidence: `tabs/equipment_tab.py`)
- Maintenance log → Maintenance repository: records tasks (evidence: `tabs/maintenance_tab.py`)
- Water-test form → Localization and units: translates form (evidence: `sidebar/water_test_form.py`)
- Schema initialization → Local SQLite database: creates schema
- Tank repository → Repository database layer: uses repository layer (evidence: `aqualog_db/repositories/tank.py`)
- Maintenance repository → Repository database layer: uses repository layer (evidence: `aqualog_db/repositories/maintenance.py`)
- Custom-range repository → Repository database layer: uses repository layer (evidence: `aqualog_db/repositories/custom_range.py`)
- Weekly report preferences → Repository database layer: uses repository layer (evidence: `aqualog_db/repositories/email_settings.py`)
- Repository database layer → Local SQLite database: reads and writes (evidence: `aqualog_db/base.py`)
- SQLite connection manager → Local SQLite database: opens database (evidence: `aqualog_db/connection.py`)
- Tank and app settings → Custom-range repository: sets safe ranges (evidence: `sidebar/settings_panel.py`)
- Weekly report preferences → SMTP service: weekly delivery
