docs: README in every bases/lif/ directory#922
Merged
Conversation
Adds a short README to each base brick so GitHub navigators can tell what each service does without opening core.py. Each README follows the same shape: purpose, endpoints, auth (where relevant), components composed, and the project that deploys it. Covers: api_graphql, advisor_restapi, query_cache_restapi, example_data_source_rest_api, semantic_search_mcp_server, orchestrator_restapi, translator_restapi, identity_mapper_restapi, query_planner_restapi, mdr_restapi (with an endpoint-group table for its 16 endpoint modules), and the empty query_cache_module stub. Skipping learner_data_export_api — that base only exists on the open PR LIF-Initiative#920 branch; its README will land with that PR. cspell: add Starlette.
github-project-automation
Bot
moved this from Backlog
to Done
in Current Community Efforts
2 tasks
bjagg
added a commit
that referenced
this pull request
May 16, 2026
## Summary Adds short READMEs to the five MDR-side components: `mdr_auth`, `mdr_client`, `mdr_dto`, `mdr_services`, `mdr_utils`. Each follows the same shape: purpose, public surface, file layout (where the brick has many sub-modules), and the list of consumers. `mdr_services` and `mdr_dto` each get an at-a-glance table of files → endpoint groups so readers don't have to open 20 modules to find the right one. ## Why Tier 1 README sweep, batch 2 of ~4 (after PR #922's bases). Reviewer-free docs PR. ## Test plan - [x] `uv run pre-commit run cspell --files components/lif/mdr_*/README.md` passes - [ ] Spot-check the "Used by" lists after merge 🤖 Generated with [Claude Code](https://claude.com/claude-code)
2 tasks
bjagg
added a commit
that referenced
this pull request
May 16, 2026
## Summary Tier 1 README sweep, batch 3 of 4. Adds short READMEs to seven query- and orchestration-side components, following the same template as PRs #922 (bases) and #923 (MDR components). | Component | Notes | |---|---| | `query_cache_service` | The actual cache logic; documents the four operations + MongoDB coupling | | `query_cache_read` | **Stub** (empty `core.py`) — placeholder for future read interface | | `query_cache_read_store_in_memory` | **Stub** — future in-memory implementation | | `query_cache_read_store_mongodb` | **Stub** — future MongoDB implementation | | `query_planner_service` | `LIFQueryPlannerService` + async job store | | `orchestrator_service` | `OrchestratorService` entrypoint | | `orchestrator_clients` | Factory pattern; Dagster is the only backend today | The three empty stub bricks now each have a README explaining what they're scaffolding for, so a reader doesn't have to guess why an empty `core.py` is registered as a brick. ## Test plan - [x] `uv run pre-commit run cspell --files <new READMEs>` passes — no new dictionary words needed - [ ] Spot-check the "Used by" lists after merge 🤖 Generated with [Claude Code](https://claude.com/claude-code)
3 tasks
bjagg
added a commit
that referenced
this pull request
May 16, 2026
## 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)
2 tasks
bjagg
added a commit
that referenced
this pull request
May 16, 2026
## Summary Three small, mechanical wrap-up tasks following the docs sweep: 1. **`docs/INDEX.md` sync.** Adds entries for the two docs landed in #921 — `docs/design/cross-cutting/self-serve-tenant-auth.md` and `docs/operations/guides/adding-a-new-microservice.md`. The cross-cutting section's placeholder ("Currently no docs in this layer…") is replaced with a real entry while preserving the "other planned topics" note. 2. **`CLAUDE.md` companion-doc pointers.** New short section between *Project Overview* and *Commands* listing the human-readable docs that complement CLAUDE.md (`ARCHITECTURE.md`, `docs/INDEX.md`, services overview, self-serve auth narrative, data-model rules, microservice runbook). AI agents will now discover them on first read instead of re-deriving the content. 3. **Programmatic link audit.** Walked every relative link in the 4 docs landed in #921, all 49 bases/components/projects READMEs from #922–#926, and `INDEX.md` itself. **Zero broken links** across the set. ## Why Closes out the recommendation set from the post-#926 doc-tier review: Tier 3a (INDEX sync), Tier 5 (CLAUDE grooming), Tier 6 (link audit). Quick, mechanical, no review needed. ## Test plan - [x] `uv run pre-commit run cspell` passes (added `pipefail`, `dataclass` to dictionary for pre-existing CLAUDE.md content the cspell hook hadn't re-checked since the recent doc activity) - [x] Link audit script: zero broken relative links 🤖 Generated with [Claude Code](https://claude.com/claude-code)
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds a short README to each base brick so people navigating the repo on GitHub can tell what each service does without opening
core.py. Each follows the same shape: purpose, endpoints, auth (where relevant), components composed, and the deploying project.Coverage
11 new READMEs:
api_graphql,advisor_restapi,query_cache_restapi,example_data_source_rest_api,semantic_search_mcp_server,orchestrator_restapi,translator_restapi,identity_mapper_restapi,query_planner_restapimdr_restapi— with an endpoint-group table summarizing its 16 endpoint modules under their URL prefixesquery_cache_module— a note that this is an empty stub for a future non-HTTP cache interfaceSkipped:
learner_data_export_api(only on the open #920 branch; its README will land with that PR).Why
Reviewer bandwidth constraint means we're chipping away at docs that don't need review. Tier 1 of the README sweep — bases first because they're well-bounded; components batch will follow.
Test plan
uv run pre-commit run cspell --files bases/lif/*/README.mdpassescore.pyafter merge🤖 Generated with Claude Code