Maintenance PR (#311)

* Add CLAUDE.md for Claude Code guidance

Provides essential commands, architecture overview, and development
patterns to help Claude Code instances work effectively in this repo.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* Add .claudeignore file

Excludes IDE files, caches, build artifacts, and lock files from
Claude Code indexing to reduce noise and improve context relevance.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* Misc PyCharm changes

* Update README.md

* Update dependencies in `uv.lock`

Upgrade multiple packages to newer versions, adjust `requires-python` specification, and apply other dependency updates for maintenance.

* Test only latest python version

* Simplify Python test workflow by removing matrix strategy

* Update remaining python 3.13 leftovers

* Remove QLTY and duplicate typing

* Bump up dependencies and force test engine disposal

* Fix some warnings and deprecations

* Format

---------

Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>

Author: febus982

.claudeignore

@@ -0,0 +1,60 @@
+# IDE and editor files
+.idea/
+.vscode/
+*.iws
+*.iml
+
+# Python cache and bytecode
+__pycache__/
+*.py[cod]
+*$py.class
+.mypy_cache/
+.dmypy.json
+.pytest_cache/
+.hypothesis/
+
+# Virtual environments
+.venv/
+venv/
+env/
+ENV/
+
+# Build and distribution
+build/
+dist/
+*.egg-info/
+*.egg
+.eggs/
+
+# Coverage reports
+htmlcov/
+.coverage
+.coverage.*
+coverage.xml
+
+# Documentation build
+docs/_build/
+/site
+
+# Database files
+*.db
+db.sqlite3
+
+# Credentials and secrets
+credentials.env
+.env
+
+# Docker volumes
+volumes/
+
+# OS files
+.DS_Store
+Thumbs.db
+
+# Lock files (large, not useful for code understanding)
+uv.lock
+
+# Quality tools cache
+.qlty
+.tox/
+.nox/

.github/workflows/github-pages.yml

@@ -27,7 +27,7 @@ jobs:
       - name: Checkout
         uses: actions/checkout@v6
 
-      - name: Set up Python 3.13
+      - name: Set up Python 3.14
         uses: actions/setup-python@v6
         with:
           python-version: "3.14"

.github/workflows/python-code-style.yml

@@ -17,7 +17,7 @@ jobs:
 
     steps:
     - uses: actions/checkout@v6
-    - name: Set up Python 3.13
+    - name: Set up Python 3.14
       uses: actions/setup-python@v6
       with:
         python-version: "3.14"

.github/workflows/python-lint.yml

@@ -17,7 +17,7 @@ jobs:
 
     steps:
     - uses: actions/checkout@v6
-    - name: Set up Python 3.13
+    - name: Set up Python 3.14
       uses: actions/setup-python@v6
       with:
         python-version: "3.14"

.github/workflows/python-quality.yml

@@ -17,7 +17,7 @@ jobs:
 
     steps:
     - uses: actions/checkout@v6
-    - name: Set up Python 3.13
+    - name: Set up Python 3.14
       uses: actions/setup-python@v6
       with:
         python-version: "3.14"
@@ -29,7 +29,3 @@ jobs:
       run: make dev-dependencies
     - name: Run coverage
       run: make ci-coverage
-    - uses: qltysh/qlty-action/coverage@v2
-      with:
-        token: ${{secrets.QLTY_COVERAGE_TOKEN}}
-        files: ${{github.workspace}}/coverage.lcov

.github/workflows/python-tests.yml

@@ -13,24 +13,17 @@ on:
 
 jobs:
   test:
-    strategy:
-      matrix:
-        version: ["3.10", "3.11", "3.12", "3.13"]
-        os: [ubuntu-latest]
-    runs-on: ${{ matrix.os }}
+    runs-on: ubuntu-latest
     steps:
     - uses: actions/checkout@v6
-    - name: Set up Python ${{ matrix.version }}
+    - name: Set up Python 3.14
       uses: actions/setup-python@v6
       with:
-        python-version: "${{ matrix.version }}"
+        python-version: "3.14"
     - name: Install uv
       uses: astral-sh/setup-uv@v7
     - name: Install dependencies
       run: make dev-dependencies
     - name: Test with pytest
       run: |
         make ci-test
-    - name: Check typing
-      run: |
-        make typing

.github/workflows/python-typing.yml

@@ -17,7 +17,7 @@ jobs:
 
     steps:
     - uses: actions/checkout@v6
-    - name: Set up Python 3.13
+    - name: Set up Python 3.14
       uses: actions/setup-python@v6
       with:
         python-version: "3.14"

.idea/bootstrap-python-fastapi.iml

@@ -0,0 +1,105 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Build and Development Commands
+
+**Package Management (uv):**
+- `make dev-dependencies` - Install all dependencies including dev
+- `make install-dependencies` - Install production dependencies only
+- `make update-dependencies` - Update and sync dependencies
+
+**Running Applications:**
+- `make dev-http` - Run HTTP application with hot reload (Docker)
+- `make dev-socketio` - Run Socket.io application with hot reload (Docker)
+- `docker compose up dramatiq-worker` - Run Dramatiq worker
+
+**Testing:**
+- `make test` - Run full test suite with coverage (parallel execution)
+- `uv run pytest tests/path/to/test_file.py` - Run a single test file
+- `uv run pytest tests/path/to/test_file.py::test_function` - Run a specific test
+- `uv run pytest -k "pattern"` - Run tests matching pattern
+
+**Code Quality:**
+- `make check` - Run all checks (lint, format, typing, test)
+- `make fix` - Auto-fix linting and formatting issues
+- `make typing` - Run mypy type checking
+- `make lint` - Run ruff linter
+- `make format` - Check code formatting
+
+**Database:**
+- `make migrate` - Run database migrations
+- `make autogenerate-migration` - Generate new migration file
+
+**Documentation:**
+- `make docs` - Serve documentation locally
+
+## Architecture Overview
+
+This is a Clean Architecture Python application with multiple entry points (HTTP/FastAPI, WebSocket/Socket.io, async tasks/Dramatiq).
+
+### Layer Structure (`src/`)
+
+```
+domains/       → Business logic (services, models, DTOs, events)
+gateways/      → External system interfaces (event gateways)
+http_app/      → FastAPI application and routes
+socketio_app/  → Socket.io application and namespaces
+dramatiq_worker/ → Async task worker
+common/        → Shared infrastructure (config, DI, storage, telemetry)
+migrations/    → Alembic database migrations
+```
+
+### Dependency Injection Pattern
+
+Uses `dependency-injector` library. Interface mappings are defined in `src/common/di_container.py`:
+
+```python
+# Container maps interfaces to implementations
+BookRepositoryInterface: Factory[BookRepositoryInterface] = Factory(
+    SQLAlchemyAsyncRepository,
+    bind=SQLAlchemyBindManager.provided.get_bind.call(),
+    model_class=BookModel,
+)
+```
+
+Services use `@inject` decorator with `Provide[]`:
+
+```python
+@inject
+def __init__(
+    self,
+    book_repository: BookRepositoryInterface = Provide[BookRepositoryInterface.__name__],
+)
+```
+
+### Application Bootstrap
+
+All applications share common initialization via `application_init()` in `src/common/bootstrap.py`:
+- Configures DI container
+- Initializes logging (structlog)
+- Sets up SQLAlchemy storage
+- Configures Dramatiq
+- Instruments OpenTelemetry
+
+### Domain Structure (example: `domains/books/`)
+
+- `_models.py` - SQLAlchemy models (imperative mapping)
+- `_service.py` - Business logic services
+- `_gateway_interfaces.py` - Repository/gateway protocols
+- `_tasks.py` - Dramatiq async tasks
+- `dto.py` - Pydantic DTOs for API layer
+- `events.py` - CloudEvents definitions
+- `interfaces.py` - Public domain interfaces
+
+### Testing
+
+Tests mirror source structure in `src/tests/`. Key patterns:
+- Integration tests use `TestClient` with in-memory SQLite
+- Unit tests mock dependencies via `AsyncMock`/`MagicMock`
+- 100% coverage required (`fail_under = 100` in pyproject.toml)
+- Storage tests in `tests/storage/` use isolated database fixtures
+
+### Configuration
+
+Environment-based configuration via Pydantic Settings in `src/common/config.py`. Nested configs use `__` delimiter (e.g., `DRAMATIQ__BROKER_URL`).