Add integration and development documentation

docs/integrations/feedapi.md

@@ -0,0 +1,138 @@
+# Feedapi Runtime Contract
+
+`weatherapi` uses feedapi as its generic HTTP runtime and configuration layer.
+This document describes the feedapi behavior that `weatherapi` relies on.
+
+## Version
+
+`go.mod` depends on:
+
+- `gitea.maximumdirect.net/ejr/feedapi v0.1.0`
+
+Only feedapi behavior used by `weatherapi` is documented here.
+
+## Packages Used
+
+Runtime composition imports:
+
+- `feedapi/app`
+- `feedapi/config`
+- `feedapi/db`
+
+The HTTP adapter imports:
+
+- `feedapi/bind`
+- `feedapi/endpoint`
+- `feedapi/errors`
+- `feedapi/render`
+- `feedapi/response`
+
+Tests also use:
+
+- `feedapi/templates`
+- `feedapi/transport/httpx`
+
+## Config Ownership
+
+Feedapi owns loading and validating the YAML config used by `weatherapi`.
+`weatherapi` adds one local runtime check: `databases` must contain at least
+one entry.
+
+The implemented config areas used by `weatherapi` are:
+
+- `server`: HTTP listen/default format/timeouts;
+- `databases`: named database handles opened into a registry;
+- `templates`: base directory for text templates.
+
+The canonical config reference is [`docs/config.md`](../config.md).
+
+## Database Registry
+
+`cmd/weatherapi` calls feedapi `db.OpenAll` with configured databases and passes
+the resulting registry into `feedapi/app.New`. It also selects the first
+configured database name from the registry as the primary weather store.
+
+Feedapi owns opening and closing database handles. `weatherapi` owns choosing
+which opened handle is used by the Postgres repository.
+
+## Endpoint Registry
+
+`weatherapi` builds endpoint definitions with `httpapi.Definitions` and passes
+them to feedapi through `feedapi/app.WithEndpoints`.
+
+Feedapi owns:
+
+- route adaptation;
+- HTTP method/path matching;
+- invoking endpoint binders;
+- invoking endpoint handlers;
+- rendering handler results.
+
+Endpoint definitions remain owned by `internal/adapters/inbound/httpapi`.
+
+## Renderers and Templates
+
+Each implemented endpoint declares JSON, XML, and text output through feedapi
+render formats. Text endpoints also name a template file.
+
+Feedapi owns:
+
+- renderer registration;
+- format negotiation;
+- template loading from `templates.base_dir`;
+- applying templates to response envelopes.
+
+`weatherapi` owns the template files under `templates/` and presenter output
+shapes consumed by those templates.
+
+## Content Negotiation
+
+`weatherapi` relies on feedapi's negotiation order:
+
+1. `format` query parameter;
+2. `Accept` header;
+3. configured default format.
+
+Unsupported formats are exposed as structured API errors. See
+[`docs/api.md`](../api.md) for the public HTTP contract.
+
+## Success and Error Envelopes
+
+Endpoint handlers return `response.Envelope{Data: ...}` for successful
+responses. Nil data is rendered as `data: null`.
+
+Feedapi error handling exposes structured error envelopes with:
+
+- `error.code`;
+- `error.message`.
+
+`weatherapi` relies on feedapi invalid-parameter and unsupported-format errors
+for request validation and negotiation failures.
+
+## Middleware and Shutdown
+
+Feedapi owns generic HTTP middleware and server lifecycle. The architecture
+policy records that recovery, request ID, and timing middleware are installed by
+default.
+
+`weatherapi` supplies a signal-cancelable context to feedapi startup. Feedapi
+owns graceful HTTP shutdown after that context is canceled.
+
+## Upgrade Checklist
+
+Before upgrading feedapi:
+
+- verify config field names and defaults still match [`docs/config.md`](../config.md);
+- verify database registry behavior still supports first configured database
+  selection;
+- verify endpoint definition APIs still support binders, handlers, formats,
+  and template names;
+- verify negotiation order remains `format`, then `Accept`, then default;
+- verify success and error envelopes still match [`docs/api.md`](../api.md);
+- run `go test ./...` with private module access configured.
+
+## Related Docs
+
+- [`docs/internal/runtime.md`](../internal/runtime.md)
+- [`docs/internal/http-adapter.md`](../internal/http-adapter.md)
+- [`docs/api.md`](../api.md)