pdf/gateway/README.md

# Gateway (FastAPI)

Phase 0 task **"FastAPI service scaffolding"** (Dev 1). Skeleton only — every
PDF-touching route returns **501** until the pybind11 engine module in
[`bindings/python/`](../bindings/python/) lands at Gate G0b.

What the gateway eventually does (see `docs/phase0.md` and engine blueprint §8):

- Auth, metadata, storage (S3 / MinIO), async job queue.
- Bridges to the C++ engine via **pybind11** (`bindings/python/`).
- Hosts the API the React + TypeScript viewer in [`frontend/`](../frontend/) calls.

## Current state

```
gateway/
  pyproject.toml              # pinned FastAPI/uvicorn/pydantic + ruff/pytest
  app/
    __init__.py               # exports __version__
    main.py                   # FastAPI app factory
    config.py                 # pydantic-settings (PDFENGINE_* env vars)
    routers/                  # PEP 420 namespace pkg — no __init__.py needed
      health.py               # GET /health  → 200
      documents.py            # CRUD         → 501 (placeholder)
      render.py               # render/text  → 501 (placeholder)
      edits.py                # apply edits  → 501 (placeholder)
    services/                 # PEP 420 namespace pkg
      engine.py               # lazy pybind11 import wrapper (engine absent in Phase 0)
  tests/
    conftest.py
    test_health.py            # /health works without the engine
    test_placeholders.py      # every PDF route 501s until G0b lands
```

The gateway depends on **no C++** today — the `engine` service module probes
for `import pdfengine` lazily and reports `engine_available: false` via
`/health` while the pybind11 module does not exist.

## Local development

Requires Python 3.11+ (3.12 works). Build dirs are git-ignored.

```powershell
cd gateway
python -m venv .venv
.venv\Scripts\Activate.ps1
pip install -e ".[dev]"
```

```sh
# Linux/macOS
cd gateway
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
```

Run the service:

Using the startup script (Windows):
```powershell
# Default port (8765)
powershell -File scripts/start_gateway.ps1

# Custom port (e.g. 8080)
powershell -File scripts/start_gateway.ps1 -Port 8080
```

Or run directly via uvicorn (cross-platform):
```sh
# Default port (8765)
uvicorn app.main:app --reload

# Custom port (e.g. 8080)
uvicorn app.main:app --reload --port 8080
```
# → http://127.0.0.1:<port>/health
# → http://127.0.0.1:<port>/docs  (OpenAPI UI)


Lint, format, and test (the exact commands CI runs):

```sh
ruff check .
ruff format --check .
pytest
```

## Configuration

Environment variables are read by `app/config.py` with the prefix
`PDFENGINE_`:

| Var                          | Default | Meaning                                          |
|------------------------------|---------|--------------------------------------------------|
| `PDFENGINE_ENVIRONMENT`      | `dev`   | `dev` / `staging` / `prod` — echoed in `/health` |
| `PDFENGINE_ENGINE_AVAILABLE` | `false` | Forces the engine-availability flag for testing  |

Additionally, the gateway startup scripts and frontend configuration support:

| Var                | Default                 | Meaning                                          |
|--------------------|-------------------------|--------------------------------------------------|
| `PORT`             | `8765`                  | Gateway listening port (used by `start_gateway.ps1`). |
| `VITE_GATEWAY_URL` | `http://127.0.0.1:8765` | URL of the gateway API (used by the frontend).     |

A `.env` file in `gateway/` is auto-loaded if present (it is git-ignored
via the repo-wide `.venv/` and Python rules — add `.env` to your local
ignores if you keep secrets in it).

## CI

The `gateway` job in [`.github/workflows/ci.yml`](../.github/workflows/ci.yml)
runs on **ubuntu-latest only** — the gateway is pure Python with no
OS-specific surface, so a cross-platform matrix would burn runner minutes
catching nothing. The engine `build` matrix still covers Linux + macOS +
Windows; once the pybind11 wheel is built per-platform there, the gateway
job will install it and run integration tests against the real engine.

## What is **not** here yet (and why)

- **Real document/render/edit routes** — blocked on Gate G0b
  (`PdfDocument` / `PdfPage` interface contracts) and the pybind11 module.
  Stubbing them earlier would just lock us into a bad API.
- **Auth, storage, job queue** — Phase 1 / 2 work. Leaving these out of
  Phase 0 keeps the surface area small enough to keep CI green while the
  engine is still being scaffolded.
- **Containerization (Dockerfile, compose)** — added when there is
  something non-trivial to package. A FastAPI app with a `/health` route
  does not need an image yet.