langchain-ai/docs
1
0
Fork 0
mirror of https://github.com/langchain-ai/docs.git synced 2026-07-22 04:15:25 -04:00
Code Issues 490 Packages Projects Releases Wiki Activity

[GH-ISSUE #2915] [langgraph]: Add ARCHITECTURE.md for contributor onboarding #2696

New Issue
Closed
opened 2026-06-05 17:26:20 -04:00 by yindo · 0 comments
yindo commented 2026-06-05 17:26:20 -04:00
Owner
Copy Link
Copy Source

Originally created by @ajoyacharyya-kyndryl on GitHub (Mar 4, 2026).
Original GitHub issue: https://github.com/langchain-ai/docs/issues/2915

Type of issue

request for content

Language

N/A

Description

Problem

The repo has README.md (user-facing), AGENTS.md/CLAUDE.md (AI agents, monorepo logistics) — but nothing explaining how the engine works for human contributors. pregel/main.py alone is 3,345 LOC with no map.

What's missing

  • Pregel/BSP execution model (super-step lifecycle)
  • Key abstractions and how they connect (StateGraph → Pregel → PregelLoop → channels)
  • Compilation pipeline (schema → channels → validation → wiring)
  • Persistence contract (BaseCheckpointSaver, checkpoint format v4)
  • Extension points (new backends, channel types, serializers)
  • Dependency direction rules across layers

Why it matters

New contributors spend hours tracing stream() → PregelLoop → _algo.prepare_next_tasks() → apply_writes() before they can make a meaningful change. An ARCHITECTURE.md is standard practice in mature OSS projects (Rust, Chromium, VS Code all have one).

Proposal

Add a single ARCHITECTURE.md at the repo root — ~800 lines with Mermaid diagrams covering the execution model, key abstractions, compilation pipeline, persistence, and a contributor quick-start. I have a draft ready if useful.

Acceptance criteria

  • ARCHITECTURE.md at repo root, Mermaid diagrams render on GitHub
  • Factual claims verified against current main
  • AGENTS.md/CLAUDE.md updated to reference it
Originally created by @ajoyacharyya-kyndryl on GitHub (Mar 4, 2026). Original GitHub issue: https://github.com/langchain-ai/docs/issues/2915 ### Type of issue request for content ### Language N/A ### Description ### Problem The repo has `README.md` (user-facing), `AGENTS.md`/`CLAUDE.md` (AI agents, monorepo logistics) — but nothing explaining **how the engine works** for human contributors. `pregel/main.py` alone is 3,345 LOC with no map. ### What's missing - Pregel/BSP execution model (super-step lifecycle) - Key abstractions and how they connect (`StateGraph` → `Pregel` → `PregelLoop` → channels) - Compilation pipeline (schema → channels → validation → wiring) - Persistence contract (`BaseCheckpointSaver`, checkpoint format v4) - Extension points (new backends, channel types, serializers) - Dependency direction rules across layers ### Why it matters New contributors spend hours tracing `stream()` → `PregelLoop` → `_algo.prepare_next_tasks()` → `apply_writes()` before they can make a meaningful change. An `ARCHITECTURE.md` is standard practice in mature OSS projects (Rust, Chromium, VS Code all have one). ### Proposal Add a single `ARCHITECTURE.md` at the repo root — ~800 lines with Mermaid diagrams covering the execution model, key abstractions, compilation pipeline, persistence, and a contributor quick-start. I have a draft ready if useful. ### Acceptance criteria - [ ] `ARCHITECTURE.md` at repo root, Mermaid diagrams render on GitHub - [ ] Factual claims verified against current `main` - [ ] `AGENTS.md`/`CLAUDE.md` updated to reference it
yindo added the langgraphexternal labels 2026-06-05 17:26:20 -04:00
yindo closed this issue 2026-06-05 17:26:20 -04:00
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
bug
deepagents
docs-infra
external
external
help wanted
integration
internal
internal
javascript
js/ts
langchain
langgraph
langsmith
needs-title
pull-request
Mirrored from GitHub Pull Request
 python
reference
No Label external langgraph
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
yindo
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: langchain-ai/docs#2696
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?