TJWaterServerBinary/.github/copilot-instructions.md

Copilot Instructions for TJWater Server

This repository contains the backend code for the TJWater Server, a water distribution network management system built with FastAPI.

High-Level Architecture

The application follows a layered architecture:

• Entry Point: app/main.py initializes the FastAPI application, database connections (PostgreSQL & TimescaleDB), and middleware.
• API Layer: app/api/v1 contains the route handlers.
• Service Layer: app/services contains business logic and orchestration.
• Infrastructure Layer: app/infra handles database connections (db), audit logging (audit), and external integrations.
• Domain Layer: app/domain likely contains core domain models.
• Native/Algorithms: app/native and app/algorithms handle specialized water network calculations (possibly using EPANET/WNTR).

Build, Test, and Run Commands

Environment Setup

• Dependencies are listed in requirements.txt.
• Configuration is managed via environment variables (see .env.example if available, or app/core/config.py).
• Important: Ensure .env is configured with correct database credentials for both PostgreSQL and TimescaleDB.

If first time setting up, you may want to create a Conda environment:

conda create -n server python=3.12
conda activate server
pip install uv
uv pip install -r requirements.txt
conda install -c conda-forge pymetis

Running the Server

The preferred way to run the server locally is using the helper script which sets up the Python path correctly:

conda activate server
python scripts/run_server.py

Alternatively, you can run directly with uvicorn (ensure PYTHONPATH includes the root):

conda activate server
uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload

Running Tests

Use pytest to run tests. The tests/conftest.py handles path setup.

# Run all tests
pytest

# Run a specific test file
pytest tests/unit/test_specific_file.py

# Run a specific test case
pytest tests/unit/test_specific_file.py::test_function_name

Building (Optional)

The project includes scripts to compile Python modules to .pyd files using Cython (see scripts/build_pyd.py). This is likely for distribution/performance but not required for standard development.

Key Conventions

• Async/Await: The codebase heavily uses async and await for I/O operations, especially database interactions.
• Database Management:
  • Connections are managed globally in app.infra.db and initialized in lifespan (app/main.py).
  • Use app.infra.db.dynamic_manager for project-specific database connections (multi-tenancy/dynamic projects).
• Pydantic: extensively used for data validation and settings management.
• Scripts: The scripts/ directory contains many utility scripts for maintenance, data processing, and server management. Check there before writing new operational scripts.
• Water Network Modeling: Interactions with water network models often involve epanet or wntr libraries. Be aware of domain-specific terminology (nodes, links, junctions, tanks).

Code Style

• Follow standard PEP 8 guidelines.
• No specific linter configuration was found, so default to standard Python formatting.