docs: add architecture guide, developer guide, and roadmap - #13
Open
wilsonhj wants to merge 1 commit into
Open
Conversation
Adds three contributor-facing guides under docs/:
- ARCHITECTURE.md: layered architecture, session/model flow, upstream
risk surface, and a bug-history appendix.
- DEVELOPER_GUIDE.md: setup, configuration schema, and debugging tips.
- ROADMAP.md: non-committal backlog of potential improvements.
These guides document the post-fix state of the codebase. They reference
modules, symbols, and behavior (e.g. get_valid_llm, thread-safe SessionMap
singleton, LCEL error re-raising, and the langchain<0.4.0 / mcp-adapters
<0.2.0 dependency pins) that only exist after the bug-fix and dependency-pin
PRs. This PR should therefore be merged AFTER those fix PRs, at which point
the forward references become accurate.
Includes one correction to the environment-variable table: HTTPS_PROXY is
not read anywhere in the codebase (example.env defines REQUESTS_CA_BUNDLE
only, and outbound proxying is configured via the config.yml proxy {host,
port} block). The row now lists REQUESTS_CA_BUNDLE alone and points to the
config.yml proxy block for proxying.
Co-authored-by: Claude <noreply@anthropic.com>
This was referenced Jul 8, 2026
Merged
Contributor
Author
Verification note — SKIP (no runtime surface)Docs-only change, so there's nothing to execute. In lieu of runtime verification: all technical claims in the three guides were fact-checked against the source at this branch (module/class names, env vars incl. the |
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.
What this adds
Three contributor-facing guides, absent today:
docs/ARCHITECTURE.md— module map, EAS auth flow, LCEL integration, MCP design, upstream-dependency risk table, and a "bug history" appendix explaining why several modules look the way they do.docs/DEVELOPER_GUIDE.md— setup (CONFIG_PATH,example.env, config.yml schema), test/lint/type tooling (uv, make targets), debugging tips, contribution conventions.docs/ROADMAP.md— proposed feature direction, explicitly separated from bug tracking.All technical claims were fact-checked against the source (module/class names, env vars, config schema, deprecation timelines, lint limits). One correction made relative to earlier drafts: the env-var table no longer lists
HTTPS_PROXY(nothing in the codebase reads it — outbound proxying is configured via config.yml'sproxy: {host, port}block).These guides document the codebase after the accompanying fix PRs (deps pin, sanitizer/orchestrator, model/session/config, MCP). ~16 statements reference post-fix state — e.g.
SessionMap.get_valid_llm(), the double-checked-locking singleton, the orchestrator's.invoke()/.ainvoke()migration, and thelangchain<0.4.0pins. Merging this PR before those would make the docs describe code that isn't onmainyet. Happy to hold/rebase this until the rest of the series lands.Co-authored-by: Claude noreply@anthropic.com