Skip to main content

​
Water Quality Backend API Documentation

Build powerful water quality monitoring applications with real-time data, AI-powered analysis, and comprehensive alerts

Get StartedExplore API

​
Quick Start

Get up and running with the Water Quality Backend API in minutes.
1

Clone the Repository

Clone the project and navigate to the source directory:
git clone <repository-url>
cd water-quality-backend
2

Install Dependencies

Create a virtual environment and install required packages:
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
pip install -r requirements.txt
3

Configure Environment

Copy the example environment file and configure your credentials:
cp .env.example .env
Edit .env with your Firebase, API keys, and other service credentials.
4

Start the Server

Launch the development server:
fastapi dev app
Your API will be available at http://localhost:8000

​
What You Can Build

The Water Quality Backend API provides everything you need to create comprehensive water monitoring solutions:

Real-time Monitoring

Track water quality metrics in real-time with WebSocket support and instant updates

Smart Alerts

Set up intelligent alerts based on water quality thresholds with multi-channel notifications

AI Analysis

Leverage AI-powered analysis for water quality predictions and insights

User Management

Complete authentication with email/password, OAuth (GitHub), and role-based access control

Workspace Collaboration

Organize meters and teams with multi-tenant workspace support

Performance Monitoring

Built-in Prometheus metrics for monitoring API health and performance

​
Core Features

​
Authentication & Authorization

Secure your application with multiple authentication methods:
  • Email/Password Authentication - Traditional signup and login with password reset
  • OAuth Integration - GitHub OAuth for seamless social login
  • JWT Tokens - Secure, stateless authentication with 30-day expiration
  • Role-based Access Control - Manage permissions with user roles

​
Water Quality Monitoring

Comprehensive tools for tracking water quality:
  • Meter Management - CRUD operations for water quality meters
  • Real-time Data - WebSocket connections for live sensor readings
  • Historical Data - Query and analyze historical water quality trends
  • Multi-parameter Support - Track pH, temperature, turbidity, and more

​
Intelligent Alerts

Stay informed with smart notification system:
  • Threshold-based Alerts - Automatic notifications when parameters exceed limits
  • Multi-channel Delivery - Email, push notifications (OneSignal), and in-app alerts
  • Custom Alert Rules - Define your own alert conditions and severity levels
  • Alert History - Track and audit all triggered alerts

​
AI-Powered Insights

Make better decisions with machine learning:
  • Predictive Analysis - Forecast water quality trends
  • Anomaly Detection - Identify unusual patterns in sensor data
  • PDF Reports - Generate comprehensive analysis reports
  • Custom AI Models - Integration with OpenRouter for flexible AI capabilities

​
Architecture

The API follows a Vertical Slice Architecture for maximum maintainability:
app/
├── features/              # Feature-based organization
│   ├── auth/             # Authentication
│   ├── meters/           # Meter management
│   ├── alerts/           # Alert system
│   ├── users/            # User management
│   ├── workspaces/       # Workspace management
│   ├── analysis/         # AI analysis
│   └── monitoring/       # Performance metrics
│
└── share/                # Shared utilities
    ├── firebase/         # Firebase integration
    ├── jwt/              # JWT token handling
    ├── email/            # Email service
    └── socketio/         # WebSocket support
Each feature module contains:
  • domain/ - Business logic, models, and interfaces
  • infrastructure/ - Database and external service implementations
  • presentation/ - API routes and dependencies
  • services/ - Application services and orchestration

​
Technology Stack

Core Framework

  • FastAPI - Modern, fast web framework
  • Python 3.9+ - Latest Python features
  • Uvicorn - Lightning-fast ASGI server
  • Pydantic - Data validation and serialization

Database & Storage

  • Firebase Realtime Database - Real-time data sync
  • Firebase Admin SDK - Server-side Firebase operations

AI & Data Science

  • Pandas & NumPy - Data manipulation
  • Scikit-learn - Machine learning models
  • PydanticAI - AI model integration
  • Matplotlib - Data visualization

Real-time & Notifications

  • Socket.IO - WebSocket connections
  • OneSignal - Push notifications
  • Resend - Email delivery

​
API Endpoints Overview

The API is organized into feature-based modules:
ModulePrefixDescription
Authentication/authUser registration, login, password reset, OAuth
Workspaces/workspacesWorkspace CRUD and management
Meters/metersWater quality meter operations
Alerts/alertsAlert configuration and history
Users/usersUser profile and management
Analysis/analysisAI-powered water quality analysis
Monitoring/metricsPrometheus performance metrics
All endpoints are documented with OpenAPI/Swagger. Access the interactive docs at /docs when running the server.

​
Next Steps

Quickstart Guide

Follow our step-by-step guide to make your first API call

Installation

Detailed installation instructions including Docker deployment

Authentication

Learn how to authenticate and secure your API requests

API Reference

Explore the complete API reference documentation
Need Help? Check out our examples in the /postman directory or explore the comprehensive test suite in /tests.

Build docs developers (and LLMs) love

Get started for freeTalk to us