83 lines
3.2 KiB
Markdown
83 lines
3.2 KiB
Markdown
# 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.
|