refactor: migrate to src layout and add linting/type-checking configs

.dockerignore

@@ -0,0 +1,11 @@
+.venv/
+.git/
+__pycache__/
+.env
+*.egg-info/
+.DS_Store
+.ruff_cache/
+.mypy_cache/
+.pytest_cache/
+tests/
+.claude/

.env.example

@@ -1,2 +1,5 @@
 PYGEOAPI_CONFIG=pygeoapi-config.yml
-PYGEOAPI_OPENAPI=pygeoapi-openapi.yml
+PYGEOAPI_OPENAPI=pygeoapi-openapi.yml
+DHIS2_BASE_URL=https://play.im.dhis2.org/stable-2-42-4/api
+DHIS2_USERNAME=admin
+DHIS2_PASSWORD=district

.github/workflows/ci.yml

@@ -0,0 +1,38 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  lint-and-test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Create .env from example
+        run: cp .env.example .env
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+        with:
+          version: "latest"
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+
+      - name: Install dependencies
+        run: uv sync --group dev
+
+      - name: Run linting
+        run: make lint
+
+      - name: Generate OpenAPI spec
+        run: make openapi
+
+      - name: Run tests
+        run: make test

.github/workflows/docker.yml

@@ -0,0 +1,72 @@
+name: Build and push Docker image
+
+on:
+  push:
+    branches: [main]
+
+env:
+  REGISTRY: ghcr.io
+  IMAGE_NAME: dhis2/eo-api
+
+jobs:
+  build-and-push:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
+      attestations: write
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Create .env from example
+        run: cp .env.example .env
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+        with:
+          version: "latest"
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+
+      - name: Install dependencies
+        run: uv sync
+
+      - name: Generate OpenAPI spec
+        run: make openapi
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Log in to GHCR
+        uses: docker/login-action@v3
+        with:
+          registry: ${{ env.REGISTRY }}
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Extract metadata (tags, labels)
+        id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
+
+      - name: Build and push
+        id: push
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          push: true
+          platforms: linux/amd64
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+
+      - name: Generate artifact attestation
+        uses: actions/attest-build-provenance@v2
+        with:
+          subject-name: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
+          subject-digest: ${{ steps.push.outputs.digest }}
+          push-to-registry: true

.gitignore

@@ -3,3 +3,4 @@ __pycache__/
 .venv/
 .env
 eo_api.egg-info/
+pygeoapi-openapi.yml

.python-version

@@ -0,0 +1 @@
+3.13

CLAUDE.md

@@ -0,0 +1,7 @@
+# CLAUDE.md
+
+## Commit conventions
+
+- Use conventional commits (e.g. `feat:`, `fix:`, `docs:`, `chore:`, `refactor:`, `test:`)
+- No Co-Authored-By or other attribution lines
+- Never use emojis anywhere — not in commits, code, comments, or responses

Dockerfile

@@ -0,0 +1,30 @@
+FROM ghcr.io/astral-sh/uv:0.10-python3.13-trixie-slim
+
+RUN apt-get update && \
+    apt-get install -y --no-install-recommends \
+        git curl \
+        build-essential cython3 \
+        libgeos-dev libproj-dev && \
+    rm -rf /var/lib/apt/lists/*
+
+RUN groupadd --system eo && useradd --system --gid eo --create-home eo
+
+WORKDIR /app
+
+COPY pyproject.toml uv.lock .python-version ./
+COPY src/ src/
+
+RUN uv sync --frozen --no-dev
+
+COPY pygeoapi-config.yml pygeoapi-openapi.yml ./
+
+ENV PYGEOAPI_CONFIG=/app/pygeoapi-config.yml
+ENV PYGEOAPI_OPENAPI=/app/pygeoapi-openapi.yml
+ENV PORT=8000
+
+USER eo
+
+HEALTHCHECK --interval=30s --timeout=5s --start-period=10s --retries=3 \
+    CMD curl -f http://localhost:${PORT}/health || exit 1
+
+CMD /app/.venv/bin/uvicorn eo_api.main:app --host 0.0.0.0 --port ${PORT}

Makefile

@@ -1,8 +1,27 @@
-sync:
+.DEFAULT_GOAL := help
+
+help: ## Show this help
+	@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | awk 'BEGIN {FS = ":.*?## "}; {printf "  %-15s %s\n", $$1, $$2}'
+
+sync: ## Install dependencies with uv
 	uv sync
 
-run:
-	uv run uvicorn main:app --reload
+run: openapi ## Start the app with uvicorn
+	uv run uvicorn eo_api.main:app --reload
+
+lint: ## Run ruff linting and formatting (autofix)
+	uv run ruff check --fix .
+	uv run ruff format .
+
+test: ## Run tests with pytest
+	uv run pytest tests/
+
+openapi: ## Generate pygeoapi OpenAPI spec
+	@set -a && . ./.env && set +a && \
+		PYTHONPATH="$(PWD)/src" uv run pygeoapi openapi generate ./pygeoapi-config.yml > pygeoapi-openapi.yml
+
+start: openapi ## Start the Docker stack (builds images first)
+	docker compose up --build
 
-openapi:
-	PYTHONPATH="$(PWD)" uv run pygeoapi openapi generate ./pygeoapi-config.yml > pygeoapi-openapi.yml
+restart: openapi ## Tear down, rebuild, and start the Docker stack from scratch
+	docker compose down -v && docker compose build --no-cache && docker compose up

README.md

@@ -13,9 +13,15 @@ Install dependencies (requires [uv](https://docs.astral.sh/uv/)):
 Environment variables are loaded automatically from `.env` (via `python-dotenv`).
 Copy `.env.example` to `.env` and adjust values as needed.
 
+Key environment variables (used by the OGC API DHIS2 plugin):
+
+- `DHIS2_BASE_URL` -- DHIS2 API base URL (defaults to play server in `.env.example`)
+- `DHIS2_USERNAME` -- DHIS2 username
+- `DHIS2_PASSWORD` -- DHIS2 password
+
 Start the app:
 
-`uv run uvicorn main:app --reload`
+`uv run uvicorn eo_api.main:app --reload`
 
 ### Using pip (alternative)
 
@@ -25,7 +31,7 @@ If you can't use uv (e.g. mixed conda/forge environments):
 python -m venv .venv
 source .venv/bin/activate
 pip install -e .
-uvicorn main:app --reload
+uvicorn eo_api.main:app --reload
 ```
 
 ### Using conda
@@ -34,13 +40,18 @@ uvicorn main:app --reload
 conda create -n dhis2-eo-api python=3.13
 conda activate dhis2-eo-api
 pip install -e .
-uvicorn main:app --reload
+uvicorn eo_api.main:app --reload
 ```
 
 ### Makefile targets
 
-- `make sync` — install dependencies with uv
-- `make run` — start the app with uv
+- `make sync` -- install dependencies with uv
+- `make run` -- start the app with uvicorn
+- `make lint` -- run ruff linting and format checks
+- `make test` -- run tests with pytest
+- `make openapi` -- generate pygeoapi OpenAPI spec
+- `make start` -- start the Docker stack (builds images first)
+- `make restart` -- tear down, rebuild, and start the Docker stack from scratch
 
 ### pygeoapi instructions
 

compose.ghcr.yml

@@ -0,0 +1,8 @@
+services:
+  api:
+    image: ghcr.io/dhis2/eo-api:latest
+    env_file: .env
+    ports:
+      - "${PORT:-8000}:${PORT:-8000}"
+    init: true
+    restart: unless-stopped

compose.yml

@@ -0,0 +1,8 @@
+services:
+  api:
+    build: .
+    env_file: .env
+    ports:
+      - "${PORT:-8000}:${PORT:-8000}"
+    init: true
+    restart: unless-stopped