docs: README in remaining component bricks (final sweep) (#925)

## Summary
Tier 1 README sweep, **batch 4 of 4** — closes out the goal of "every
directory that has at least a file or two has a README". Adds 26 short
READMEs across the remaining component bricks and a few subdirectories.

## Coverage
- **Auth + middleware:** api_key_auth, auth
- **Data plumbing:** composer, datatypes, exceptions, logging,
mongodb_connection, string_utils
- **Schema + config:** lif_schema_config, openapi_schema_parser,
openapi_to_graphql, schema_state_manager
- **Source-adapter framework:** data_source_adapters + two adapter
subdirs (lif_to_lif_adapter,
example_data_source_rest_api_to_lif_adapter)
- **Identity mapper trio:** identity_mapper_service,
identity_mapper_storage, identity_mapper_storage_sql
- **Service-specific bricks:** example_data_source_service,
graphql_client, langchain_agent (+ prompts/), semantic_search_service,
translator
- **Tenant routing pure helpers:** tenant_routing
- **Subdirs:** langchain_agent/prompts (5 prompt templates),
mdr_client/resources (bundled OpenAPI snapshot)

## Wrapping up the sweep

| Batch | PR | Scope |
|---|---|---|
| 1 | #922 | 11 bases |
| 2 | #923 | 5 MDR components |
| 3 | #924 | 7 query/orchestration components |
| 4 | **this PR** | 26 remaining components + subdirs |

After this merges, the only missing README under `bases/lif/` is
`learner_data_export_api/` — which will land with cbeach's open PR #920.

## Test plan
- [x] `uv run pre-commit run cspell --files <new READMEs>` passes
- [ ] Spot-check the "Used by" lists after merge
- [ ] Render check on GitHub: tables, cross-links between READMEs

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Author: bjagg

components/lif/api_key_auth/README.md

@@ -0,0 +1,20 @@
+# `api_key_auth` — Component
+
+Simple API-key authentication middleware for FastAPI. Validates `X-API-Key` headers against a configurable map of `key:client-name` pairs, and exposes the matched client name on `request.state.principal`.
+
+Used by services that want bare API-key auth (no Cognito, no HS256 JWT) — the GraphQL API in particular. For the richer MDR-side middleware that handles three principal types, see [`mdr_auth`](../mdr_auth/).
+
+## Public surface
+
+```python
+from lif.api_key_auth import ApiKeyAuthMiddleware, ApiKeyConfig
+
+config = ApiKeyConfig.from_environment(prefix="GRAPHQL_AUTH")
+if config.is_enabled:
+    app.add_middleware(ApiKeyAuthMiddleware, config=config)
+```
+
+The middleware no-ops when `<PREFIX>__API_KEYS` is unset, making local dev simple.
+
+## Used by
+- `bases/lif/api_graphql` — the GraphQL service's only auth path

components/lif/auth/README.md

@@ -0,0 +1,20 @@
+# `auth` — Component
+
+Lightweight HS256 JWT auth used by the Advisor and Example Data Source bases. Not the same as [`mdr_auth`](../mdr_auth/) — this one is older and simpler, with no Cognito or middleware-managed tenant routing. Demo-grade.
+
+## Public surface
+
+```python
+from lif.auth.core import (
+    create_access_token, create_refresh_token, decode_jwt,
+    verify_token, get_current_user,
+)
+```
+
+`create_access_token` / `create_refresh_token` mint short-lived access tokens and longer-lived refresh tokens. `verify_token` is a sync validator suitable for use as a FastAPI dependency. `get_current_user` is the FastAPI `Depends(...)` callable that extracts the authenticated username from a bearer token.
+
+## Used by
+- `bases/lif/advisor_restapi` — login + per-endpoint user resolution
+- `bases/lif/example_data_source_rest_api` — `verify_token` behind `x-key` header auth
+
+New services should default to `mdr_auth` instead unless they specifically don't want Cognito support.

components/lif/composer/README.md

@@ -0,0 +1,19 @@
+# `composer` — Component
+
+Merges LIF fragments back into a `LIFRecord`. Used by the cache to assemble the final record returned to callers from many small fragment writes (one per data source, one per orchestration job).
+
+## Public surface
+
+```python
+from lif.composer import compose_with_single_fragment, compose_with_fragment_list
+```
+
+| Function | Purpose |
+|---|---|
+| `compose_with_single_fragment` | Apply one `LIFFragment` to a base record |
+| `compose_with_fragment_list` | Apply many fragments at once; order matters when they overlap |
+
+Composition is path-driven: a fragment with `fragment_path = "person.Name"` is merged at that location. Path syntax follows the PascalCase/camelCase rules documented in [`docs/specs/data-model-rules.md`](../../../docs/specs/data-model-rules.md).
+
+## Used by
+- `components/lif/query_cache_service` — fragments arrive piecemeal; the composer stitches them into a complete record

components/lif/data_source_adapters/README.md

@@ -0,0 +1,25 @@
+# `data_source_adapters` — Component
+
+Adapter framework for pulling LIF data from heterogeneous source systems. The orchestrator picks an adapter by id, the adapter handles the source-specific API contract (auth scheme, pagination, response shape), and returns LIF fragments that the orchestrator merges into a record.
+
+## Public surface
+
+```python
+from lif.data_source_adapters import LIFDataSourceAdapter, ADAPTER_REGISTRY, register_adapter
+```
+
+`LIFDataSourceAdapter` is the abstract base class. Subclasses live in sibling directories (one per adapter):
+
+| Adapter id | Directory | Notes |
+|---|---|---|
+| `lif-to-lif` | [`lif_to_lif_adapter/`](lif_to_lif_adapter/) | Reads from another LIF GraphQL API |
+| `example-data-source-rest-api-to-lif` | [`example_data_source_rest_api_to_lif_adapter/`](example_data_source_rest_api_to_lif_adapter/) | Reference impl that pulls from the bundled example data source |
+
+External adapters can be registered via `register_adapter(adapter_id, adapter_class)`.
+
+## Adding a new adapter
+
+See [`docs/operations/guides/creating-a-data-source-adapter.md`](../../../docs/operations/guides/creating-a-data-source-adapter.md) for the class contract and design guidelines, or [`docs/operations/guides/add-data-source.md`](../../../docs/operations/guides/add-data-source.md) for the end-to-end tutorial.
+
+## Used by
+Pulled in by the orchestrator via configuration — the registry is consulted at adapter-dispatch time rather than by direct import from other components.

components/lif/data_source_adapters/example_data_source_rest_api_to_lif_adapter/README.md

@@ -0,0 +1,15 @@
+# `example_data_source_rest_api_to_lif_adapter` — Adapter
+
+Reference adapter that pulls from the bundled [`example_data_source_rest_api`](../../../../bases/lif/example_data_source_rest_api/) base. Treat as a worked example for how to write a custom adapter against a real source API — copy this directory, rename, swap in your auth + URL conventions.
+
+## Files
+
+| File | What it does |
+|---|---|
+| `adapter.py` | `ExampleDataSourceRestAPIToLIFAdapter` — implements the `LIFDataSourceAdapter` contract |
+
+## Registered as
+`example-data-source-rest-api-to-lif` (see [`../README.md`](../README.md) for the registry).
+
+## See also
+[`docs/operations/guides/add-data-source.md`](../../../../docs/operations/guides/add-data-source.md) walks through cloning this adapter as the starting point for a custom data source.

components/lif/data_source_adapters/lif_to_lif_adapter/README.md

@@ -0,0 +1,16 @@
+# `lif_to_lif_adapter` — Adapter
+
+Reads from another LIF GraphQL API. Used when one LIF deployment needs to pull learner data from a peer LIF deployment — typically in multi-org demos where org1's orchestrator fetches data hosted by org2 or org3.
+
+## Files
+
+| File | What it does |
+|---|---|
+| `adapter.py` | `LIFToLIFAdapter` — implements the `LIFDataSourceAdapter` contract |
+| `graphql_query_all_fields_org2.graphql` | Pre-baked query template for org2 |
+| `graphql_query_all_fields_org3.graphql` | Pre-baked query template for org3 |
+
+The per-org `.graphql` files exist because schema field selection is hard to template dynamically against an evolving LIF data model; keeping the queries as text files makes them easy to inspect and edit. Generic adapters that target arbitrary LIF deployments will need to generate selections at runtime — that work isn't done here.
+
+## Registered as
+`lif-to-lif` (see [`../README.md`](../README.md) for the registry).

components/lif/datatypes/README.md

@@ -0,0 +1,19 @@
+# `datatypes` — Component
+
+Core Pydantic models that flow through the LIF data plane. Every service that handles LIF records, queries, or jobs imports from here. Single source of truth for the wire shapes — bases don't define their own.
+
+## Layout
+
+| File | Contents |
+|---|---|
+| `core.py` | `LIFRecord`, `LIFPerson`, `LIFFragment`, `LIFQuery`, `LIFQueryFilter`, `LIFUpdate`, `LIFQueryPlan*`, `LIFPersonIdentifier(s)`, `LIFQueryStatusResponse`, `LIFQueryPlanPartTranslation`, `HealthCheckResponse`, `TargetTransformationDataModel(s)DTO` |
+| `identity_mapping.py` | `IdentityMapping` |
+| `mdr_sql_model.py` | SQLModel-style classes used by MDR persistence |
+| `orchestration.py` | `OrchestratorJob`, `OrchestratorJobDefinition`, `OrchestratorJobRequest`, request/response wrappers |
+
+## Naming convention
+
+Models follow the PascalCase/camelCase split documented in [`docs/specs/data-model-rules.md`](../../../docs/specs/data-model-rules.md): entities (containers) are PascalCase, scalars are camelCase. Many models use `populate_by_name=True` with `alias="EntityName"` so they accept either case on input but normalize internally.
+
+## Used by
+Practically everything: every REST base, the cache and planner services, the orchestrator, the translator, and the MDR services. Changes here ripple widely; treat additions as a stable-API extension.

components/lif/example_data_source_service/README.md

@@ -0,0 +1,21 @@
+# `example_data_source_service` — Component
+
+Sample data + business logic backing the [`example_data_source_rest_api`](../../../bases/lif/example_data_source_rest_api/) base. Provides a small fake person/course dataset that adapters can exercise locally without standing up a real SIS or LMS.
+
+## Public surface
+
+```python
+from lif.example_data_source_service.core import (
+    user_info, users_info, users_info_filtered, courses_info,
+)
+```
+
+| Function | Returns |
+|---|---|
+| `user_info(user_id)` | One sample person |
+| `users_info()` | All sample persons |
+| `users_info_filtered(filter)` | Subset matching the filter |
+| `courses_info()` | Sample courses dataset |
+
+## Used by
+- `bases/lif/example_data_source_rest_api` — only consumer; this component exists to keep that base small and stub-able.

components/lif/exceptions/README.md

@@ -0,0 +1,24 @@
+# `exceptions` — Component
+
+LIF-wide exception types. Services raise these instead of bare `Exception` so HTTP bases can centralize translation to status codes via `@app.exception_handler` registrations.
+
+## Public surface
+
+```python
+from lif.exceptions.core import (
+    LIFException,
+    ResourceNotFoundException,
+    DataNotFoundException,
+    # ...
+)
+```
+
+`LIFException` is the catch-all base. Sub-types convey common semantics (not-found, data-not-found, validation failure, etc.) so handlers can map them to 404 / 422 / 500 without `isinstance` chains in business code.
+
+## Convention
+
+When you add a new exception type, also wire its handler in any base that should respond differently to it. The translator base is a good template — see its `@app.exception_handler` cascade in `bases/lif/translator_restapi/core.py`.
+
+## Used by
+- Every REST base — handlers convert these to HTTP responses
+- Service components — raise these from business logic

components/lif/graphql_client/README.md

@@ -0,0 +1,20 @@
+# `graphql_client` — Component
+
+Authenticated HTTP client for calling the LIF GraphQL API. Wraps the boilerplate (auth header, error mapping, JSON shaping) into two functions so callers don't need to learn `httpx` semantics.
+
+## Public surface
+
+```python
+from lif.graphql_client import graphql_query, graphql_mutation, GraphQLClientException
+```
+
+Both functions send `X-API-Key` from `LIF_GRAPHQL_API_KEY` (when set) as the auth header — see CLAUDE.md § "GraphQL API Key Authentication" for the server-side configuration.
+
+| Function | Purpose |
+|---|---|
+| `graphql_query(...)` | Read-side query, returns parsed data |
+| `graphql_mutation(...)` | Write-side mutation, returns parsed data |
+| `GraphQLClientException` | Raised on transport or GraphQL-error response |
+
+## Used by
+- `components/lif/semantic_search_service` — calls GraphQL to fulfill MCP queries