# 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:

```bash
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:

```bash
conda activate server
python scripts/run_server.py
```

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

```bash
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.

```bash
# 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.