Skip to main content

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.11
  • 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​

# Create virtual environment
python -m venv .venv

# Activate on macOS/Linux:
source .venv/bin/activate

# Activate on Windows:
.venv\Scripts\activate

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: Run the Application​

export FLASK_DEBUG=1 && export FLASK_ENV=dev && flask run --host localhost --port 5001

The application will start on http://localhost:5001.

API Documentation​

Once the application is running, access the interactive Swagger docs:

tip

The Swagger UI at each of these URLs lets you explore and test all available endpoints interactively without writing any code.

Authentication​

Getting Your First JWT Token​

Use Swagger UI

The easiest way to get a token is via the Swagger UI at http://localhost:5001/ — enter your username and password in the /api/user/login endpoint's header fields and execute directly.

If calling manually, pass credentials as HTTP headers:

curl -X GET http://localhost:5001/api/user/login \
  -H "username: your-username" \
  -H "password: your-password"

The response includes:

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "industryId": "your-industry-id",
  "userId": "your-user-id",
  "permissions": ["REPORTS", "ALERTS", "..."],
  "status": "Success"
}
Token Expiration

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

Project Structure Overview​

aquagenapi/
├── app/
│   ├── __init__.py              # Flask app initialization
│   ├── config.py                # Configuration with Azure Key Vault
│   ├── apis/                    # API blueprints
│   │   ├── user.py              # User API (35 namespaces)
│   │   ├── admin.py             # Admin API (24 namespaces)
│   │   ├── external.py          # External integrations
│   │   └── qa.py                # QA API
│   ├── routes/                  # Route handlers (61 files)
│   ├── services/                # Business logic
│   ├── formatters/              # Data formatters
│   ├── database/                # Database abstraction layer
│   │   ├── database_config.py   # Cosmos DB client and container setup
│   │   ├── database_supporter.py# Query methods (~200 methods)
│   │   └── queires_list.py      # Centralized query strings
│   ├── models/                  # Data models (35 files)
│   ├── data_class/              # Data classes & DTOs
│   ├── templates/               # HTML report templates (63 files)
│   └── util/                    # Utility functions
├── scripts/
│   └── auto_reports.sh          # Automated report generation script
├── requirements.txt             # Python dependencies
└── app.py                       # Application entry point

Troubleshooting​

Port Already in Use​

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

Package Installation Errors​

# Upgrade pip first
pip install --upgrade pip
pip install -r requirements.txt
tip

Always upgrade pip before installing dependencies to avoid resolver issues with older pip versions.

Next Steps​

  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