GW2 Suggest API

GW2 Suggest is a companion web application for Guild Wars 2 that helps groups of players find achievements to tackle together.

Tech Stack

• FastAPI: Web framework.
• SQLAlchemy 2.0: ORM (using async support).
• Alembic: Database migrations.
• Pydantic v2: Data validation and settings.
• Celery: Background tasks.
• sqladmin: Admin interface.
• SQLite: Default development database.

Getting Started

Prerequisites

• Python 3.13+
• uv (recommended)

Installation

1. Clone the repository:

   git clone <repository-url>
   cd gw2suggest-api
   

2. Install dependencies:

   uv sync
   

Running the Application

1. Start the development server:

   uv run uvicorn gw2suggest.main:app --reload
   

2. Start the Celery worker (requires Redis):

   # In a new terminal
   $env:PYTHONPATH="src"
   uv run celery -A gw2suggest.celery_app worker --loglevel=info
   

The API will be available at http://127.0.0.1:8000. Swagger documentation: http://127.0.0.1:8000/docs.

Database Migrations

Apply migrations to your local SQLite database:

uv run alembic upgrade head

Running Tests

uv run pytest

Manual Testing with .http file

You can use tests/test_main.http for quick manual testing of the endpoints. This file is compatible with:

• PyCharm: Built-in HTTP Client. Open the file and click the green "Run" arrow next to requests.
• VS Code: Install the REST Client extension to execute requests directly from the editor.
• JetBrains IDEs: Any JetBrains IDE (IntelliJ, WebStorm, etc.) supports this format out of the box.

Documentation

See AGENTS.md for detailed development guidelines and best practices.