ReefMind Cloud 🌊

Cloud-based multi-tenant SaaS platform for Neptune Apex aquarium controllers.

Collect telemetry from your Apex controller, visualize real-time probe readings and outlet states, browse tank notes with month/week filtering, and get AI-powered reef-keeping advice — all without running a local database or Grafana instance. While the Apex APIs allow you to control the Apex just like you can on Fusion, this is read-only at the moment. The intent at this stage is not to replace the Apex Fusion as a controller, but to allow an AI layer and take back your data for backup purposes.

Version: v0.1.4 — Notes History & Nemo Insights
Status: Working prototype (Docker-based deployment)
Previous project: ReefMind (local on-premise version)

---

Architecture

Stack

Layer	Technology	Purpose
Backend API	FastAPI (Python)	Auth, ingest, telemetry, settings, Nemo AI
Frontend	React + TypeScript + Vite + ECharts	Dashboard, tank notes, settings
Relational DB	PostgreSQL 16	Users, tenants, config
Time-Series DB	InfluxDB 2.7	Telemetry, outlet states, power, water tests, notes
Cache/Queue	Redis 7	Session cache
Proxy	Nginx	Static assets, API reverse proxy

Data Flow

Fusion Cloud API
    │
    ├── ilog/mlog/logs sync ──HTTPS──▶ Collector (5min poll)
    │                                         │
    │                                    ┌────▼────┐
    │                                    │ FastAPI  │
    │                                    │ Backend  │
    │                                    └┬──┬──┬──┘
    │                                     │  │  │
    │                         ┌───────────┘  │  └───────────┐
    │                         ▼              ▼              ▼
    │                    ┌─────────┐  ┌──────────┐  ┌──────────┐
    │                    │Postgres │  │ InfluxDB │  │  Redis   │
    │                    │(users,  │  │(per-     │  │ (cache)  │
    │                    │ config) │  │ tenant)  │  │          │
    │                    └─────────┘  └──────────┘  └──────────┘
    │                                        │
    │                                        ▼
    │                                ┌──────────────┐
    │                                │  React Web   │
    │                                │  Dashboard   │
    │                                │  + Nemo AI   │
    │                                └──────────────┘

All data collection is server-side via the Fusion API — no on-prem agent required. The collector polls every 5 minutes for probes, outlets, power, water tests, and tank notes.

---

Quick Start

Prerequisites

• Docker & Docker Compose v2
• A Neptune Apex Fusion account with API credentials

Setup

git clone https://github.com/niveknow/ReefMind-Cloud.git
cd ReefMind-Cloud

# Configure environment
cp .env.example .env
# Edit .env with your settings

# Start the stack
docker compose up -d

# Access the web app
open http://localhost:8080

Environment Variables

Variable	Default	Description
DATABASE_URL	postgresql+asyncpg://reefmind:reefmind@postgres:5432/reefmind	PostgreSQL connection
INFLUX_URL	http://influxdb:8086	InfluxDB connection
INFLUX_TOKEN	reefmind-admin-token	InfluxDB admin token
INFLUX_ORG	reefmind	InfluxDB organization
REDIS_URL	redis://redis:6379/0	Redis connection
JWT_SECRET	(auto-generated by FastAPI)	JWT signing key

---

Project Structure

ReefMind-Cloud/
├── api/                          # FastAPI backend
│   ├── app/
│   │   ├── main.py              # App entry point, lifespan, CORS
│   │   ├── config.py            # pydantic-settings config
│   │   ├── database.py          # SQLAlchemy async engine
│   │   ├── middleware/auth.py   # JWT + API key auth middleware
│   │   ├── models/              # SQLAlchemy models
│   │   │   ├── user.py          # User accounts
│   │   │   └── tenant.py        # Tenant config (Fusion creds, Nemo API key)
│   │   ├── routers/
│   │   │   ├── auth.py          # Register, login, JWT refresh
│   │   │   ├── telemetry.py     # Probe data, notes, water tests, outlets
│   │   │   ├── ingest.py        # Agent data ingestion
│   │   │   ├── fusion.py        # Fusion discovery & live data
│   │   │   ├── tenant_config.py # Settings management
│   │   │   └── nemo.py          # AI reef assistant (2yr notes context)
│   │   ├── schemas/             # Pydantic request/response models
│   │   └── services/
│   │       ├── influx.py        # InfluxDB read/write (telemetry, notes, outlets, power, water tests)
│   │       ├── collector.py     # 5-min Fusion poll loop (probes, outlets, power, water tests, notes)
│   │       ├── fusion_live.py   # Fusion API live data client
│   │       └── fusion_discovery.py  # Fusion onboarding discovery
│   ├── requirements.txt
│   └── Dockerfile
│
├── web/                          # React frontend
│   ├── src/
│   │   ├── App.tsx              # Routing + auth context
│   │   ├── main.tsx             # Entry point
│   │   ├── pages/
│   │   │   ├── LoginPage.tsx
│   │   │   ├── RegisterPage.tsx
│   │   │   ├── DashboardPage.tsx      # Probe charts, outlet grid
│   │   │   ├── NotesPage.tsx          # Tank Notes w/ month/week filter
│   │   │   ├── SettingsPage.tsx       # Fusion config, AI settings
│   │   │   ├── WaterTestPage.tsx      # Water test history & charts
│   │   │   └── CsvImportPage.tsx
│   │   ├── components/
│   │   │   ├── charts/
│   │   │   │   ├── TimeSeriesChart.tsx
│   │   │   │   └── OutletGrid.tsx
│   │   │   └── layout/DashboardLayout.tsx
│   ├── Dockerfile
│   ├── nginx.conf
│   └── package.json
│
├── docs/
│   ├── saas-architecture-review.md     # Archie's full design
│   ├── saas-implementation-plan.md     # Cody's build plan
│   ├── saas-project-structure.md       # Original project layout
│   └── ANALYSIS-BACKLOG.md             # 15-item backlog (with v0.1.4 updates)
│
├── docker-compose.yml                  # Full stack (Postgres, InfluxDB, Redis, API, Web, Nginx)
├── nginx.conf                          # Reverse proxy config
├── CHANGELOG.md                        # Release history (v0.1.0 → v0.1.4)
└── .env.example                        # Environment template

---

API Endpoints

Auth

Method	Path	Description
POST	/api/auth/register	Create account + tenant
POST	/api/auth/login	Get JWT
POST	/api/auth/refresh	Refresh JWT

Telemetry (JWT required)

Method	Path	Description
GET	/api/telemetry/summary	Latest probe readings
GET	/api/telemetry/outlets	Current outlet states
GET	/api/telemetry/notes	Tank notes (730d history)
GET	/api/telemetry/water-tests	Water test history
GET	/api/telemetry/controller	Controller hardware info
GET	/api/telemetry/{probe}	Probe history (time range)

Settings

Method	Path	Description
GET	/api/tenant/config	Current tenant config
PUT	/api/tenant/config	Update config
POST	/api/tenant/regenerate-key	Rotate agent API key

Fusion

Method	Path	Description
POST	/api/fusion/discover	Discover Apex controllers from Fusion credentials
POST	/api/fusion/save	Save discovered Fusion config
GET	/api/fusion/status	Check Fusion connection status
GET	/api/fusion/readings	Live probe readings from Fusion
GET	/api/fusion/outlets	Live outlet states from Fusion

Nemo AI

Method	Path	Description
GET	/api/nemo/status	Check Nemo AI configuration status
POST	/api/nemo/ask	Ask the reef-keeping AI assistant (sees 2yr notes history)

---

Design Documents

This project was designed by Archie (SaaS Architect), built by Cody (Developer Agent), and QA'd by Trixie:

• Architecture Review — Complete system design, decisions, data model, API spec, and migration path (by Archie)
• Implementation Plan — Phase-by-phase build plan for Cody (by Archie)
• Project Structure — Original file layout reference
• Backlog — Feature backlog for future development (updated for v0.1.4)

---

Features Delivered

v0.1.1 — Water Tests & Power Monitoring

• Water test (mlog) collection and charting
• Per-outlet power monitoring (watts/amps)
• Device grouping by EB832, Vortech, etc.

v0.1.2 — Controller Health & Backfill

• Historical probe data backfill (7-day ilog)
• Controller system health (serial, firmware, timezone)
• Outlet type tagging (Variable, Switch, Pump)
• Route ordering fixes, duration button fixes
• Error handling for InfluxDB writes

v0.1.3 — Full Notes Backfill

• 18-month tank notes backfill from Fusion API
• Multi-tenant notes support
• InfluxDB HTTP API writes (bypassed stale Python client)

v0.1.4 — Notes History & Nemo Insights

• Tank Notes page — month/week filter bar, month-jump dropdown, month grouping
• Notes history — extended from 365d to 730d (24 months)
• Ask Nemo — receives 2 years / 50 notes with full comment text
• Fixed empty note titles causing InfluxDB 400 on backfill

Collected Data (by collector.py)

Measurement	Tags	Interval	History
apex_telemetry	tenant_id, apex_id, probe_name, probe_type, unit, did	5min	7-day ilog backfill on first poll
apex_outlet_states	tenant_id, apex_id, outlet_name, outlet_type, device_id, device_group	5min	Current state
apex_power	tenant_id, apex_id, outlet_name, channel	5min	Current readings
apex_water_tests	tenant_id, apex_id, parameter, unit	5min (atomic replace)	365 days
apex_logs (notes)	tenant_id, apex_id, note_id, type_code, type_name, title, reason_code, has_comment	5min (atomic replace)	730 days (backfilled)
apex_controller_info	tenant_id, apex_id, serial	5min (atomic replace)	Current state

---

Design Decisions (from Archie's Review)

Decision	Choice	Status
Data collection	Server-side Fusion API polling (no agent required)	Implemented
Tenant isolation	Per-tenant InfluxDB buckets	Implemented
Dashboard	Custom React + ECharts	Implemented
Auth	JWT + per-tenant API key	Implemented
Nemo role	General reef advisor with tank data context	Implemented (v0.1.4: 2yr notes)
Notes backfill	Monthly-chunked Fusion API with dedup	Implemented (v0.1.3)
Notes filtering	Client-side month/week filter with InfluxDB 730d query	Implemented (v0.1.4)
Deployment	Same Docker Compose for local + VPS	Deferred — env var switch ready
On-prem agent	Separate Docker container	Future — planned for NAT'd controllers
Background workers	ARQ (Redis-backed)	Deferred — inline asyncio for now

---

On-Prem Agent

The companion on-prem agent for remote Apex controllers behind NAT is planned but not yet built. For now, the cloud stack collects data directly from the Fusion API — no local agent needed.

---

License

MIT — see LICENSE

---

Authors

• Kevin Nguyen — Project owner, domain expert
• Archie — SaaS architecture & design
• Cody — Implementation & development
• Trixie — QA & validation