Getting Started with AquaGen API

This guide will help you set up your development environment and get the AquaGen API running on your local machine.

📋 Prerequisites

Before you begin, ensure you have the following installed:

• Python 3.8+ (Python 3.10+ recommended)
• pip (Python package manager)
• Git (for cloning the repository)
• Azure Account (for cloud services)
• Virtual Environment (recommended)

System Requirements

• OS: macOS, Linux, or Windows with WSL2
• RAM: Minimum 4GB (8GB recommended)
• Disk Space: At least 2GB free space

🔧 Installation

Step 1: Clone the Repository

git clone https://github.com/Fluxgentech/aquagenapi.git
cd aquagenapi

Step 2: Create a Virtual Environment

It's recommended to use a Python virtual environment to isolate dependencies:

# Create virtual environment
python -m venv .venv

# Activate virtual environment
# On macOS/Linux:
source .venv/bin/activate

# On Windows:
.venv\Scripts\activate

Virtual Environment Benefits

Using a virtual environment prevents package conflicts and keeps your global Python installation clean.

Step 3: Install Dependencies

pip install -r requirements.txt

macOS Users

If you encounter errors with PDF generation libraries, install these specific versions:

pip install xhtml2pdf==0.2.13
pip install reportlab==4.0.7

Step 4: Configure Azure Services

AquaGen API requires several Azure services. Create a .env file or set environment variables:

# Azure Cosmos DB
COSMOSDBENDPOINT=https://your-cosmos-account.documents.azure.com:443/
COSMOSDBKEY=your-cosmos-key

# Azure Key Vault
AZURE_CLIENT_ID=your-client-id
AZURE_TENANT_ID=your-tenant-id
AZURE_CLIENT_SECRET=your-client-secret

# Application Insights
APPLICATIONINSIGHTS_CONNECTION_STRING=your-insights-connection-string

# Environment
ENVIRONMENT=development

Security Warning

Never commit secrets or API keys to version control. Always use Azure Key Vault in production.

Step 5: Run the Application

python app.py

The application will start on port 5001:

 * Running on http://127.0.0.1:5001
 * Debug mode: on

🧪 Verify Installation

Test that the API is running correctly:

# Health check (if available)
curl http://localhost:5001/health

# Or test a public endpoint
curl http://localhost:5001/api/docs

🔑 Authentication Setup

Getting Your First JWT Token

1. Admin Login (for testing):

POST http://localhost:5001/api/admin/login
Content-Type: application/json

{
  "username": "admin@example.com",
  "password": "your-password"
}

2. Response:

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "user": {
    "userId": "user-123",
    "industryId": "industry-456",
    "role": "admin"
  }
}

3. Use the Token:

Include the token in subsequent requests:

GET http://localhost:5001/api/user/report?reportType=daily&reportFormat=html
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Token Expiration

Access tokens expire after 4 hours. Refresh tokens last for 14 days.

📊 Generate Your First Report

Let's generate a simple daily water consumption report:

curl -X GET "http://localhost:5001/api/user/report?\
reportType=daily&\
reportFormat=html&\
service=water&\
startDate=09/11/2024&\
jwt=YOUR_JWT_TOKEN"

Query Parameters Explained

Parameter	Description	Example
reportType	Type of report	daily, monthly, hourly
reportFormat	Output format	html, pdf, xlsx, csv
service	Service type	water, energy, level, quality
startDate	Report start date	09/11/2024 (DD/MM/YYYY)
jwt	Authentication token	Your JWT token

🎨 API Documentation

Once the application is running, you can access the interactive API documentation:

• Swagger UI: http://localhost:5001/api/docs
• User API: http://localhost:5001/api/user/
• Admin API: http://localhost:5001/api/admin/

🗂️ Project Structure Overview

aquagenapi/
├── app/
│   ├── __init__.py          # Flask app initialization
│   ├── config.py            # Configuration with Azure Key Vault
│   ├── apis/                # API blueprints
│   │   ├── user.py          # User API (31 namespaces)
│   │   ├── admin.py         # Admin API (13 namespaces)
│   │   └── external.py      # External integrations
│   ├── routes/              # Route handlers (33 files)
│   │   ├── report.py        # Report generation
│   │   ├── device_data.py   # Device data endpoints
│   │   └── alerts_routes.py # Alert management
│   ├── services/            # Business logic (40+ services)
│   │   ├── report/          # Report services
│   │   ├── alerts/          # Alert processing
│   │   └── admin/           # Admin services
│   ├── formatters/          # Data formatters (52 files)
│   │   ├── report/          # Report formatters
│   │   └── device_data_v2/  # Device data formatters
│   ├── database/            # Database layer
│   │   ├── database_config.py
│   │   └── database_supporter.py
│   ├── models/              # Data models (30 files)
│   ├── templates/           # Jinja2 HTML templates (55 files)
│   └── util/                # Utility functions
├── scripts/
│   └── auto_reports.sh      # Automated report generation
├── docs/                    # Documentation
├── requirements.txt         # Python dependencies
└── app.py                   # Application entry point

🔍 Key Components

1. Routes Layer

Handles HTTP requests and validation:

• User Routes: Report generation, device data, alerts
• Admin Routes: Industry management, user management, automated reports
• External Routes: Third-party integrations

2. Services Layer

Contains business logic:

• Report Services: 18 different report types
• Device Data Services: IoT data processing
• Alert Services: Alert rule evaluation and triggering

3. Formatters Layer

Transforms data for output:

• Report Formatters: HTML, PDF, XLSX, CSV generation
• Device Data Formatters: Polymorphic formatters for different device types

4. Database Layer

Manages data persistence:

• Azure Cosmos DB: NoSQL database with 15+ containers
• Database Supporter: 200+ query methods

🚦 Next Steps

Now that you have AquaGen API running, explore these topics:

1. Architecture Overview - Understand the system design
2. Report Generation Guide - Learn to generate reports
3. API Reference - Explore all available endpoints
4. Device Data Guide - Work with IoT device data
5. Alert System - Set up notifications and alerts

🐛 Troubleshooting

Port Already in Use

If port 5001 is already in use:

# Find and kill the process using port 5001
lsof -ti:5001 | xargs kill -9

# Or run on a different port
flask run --port 5002

Azure Connection Issues

If you can't connect to Azure services:

1. Verify your Azure credentials are correct
2. Check network connectivity
3. Ensure your IP is allowed in Azure Firewall rules
4. Verify the service principal has proper permissions

Package Installation Errors

If you encounter errors during pip install:

# Upgrade pip
pip install --upgrade pip

# Install packages one by one to identify the problematic package
pip install -r requirements.txt --verbose

ImportError or ModuleNotFoundError

Ensure your virtual environment is activated:

# Check which Python is being used
which python

# Should point to .venv/bin/python

📚 Additional Resources

• CLAUDE.md - Project guidelines and best practices
• Requirements - Complete list of dependencies
• Azure Documentation - Azure services documentation
• Flask Documentation - Flask framework documentation

---

You're All Set!

Your AquaGen API is now running. Head to the Architecture section to learn more about how it works!