docs: update README with Noema architecture and routing diagrams#12
docs: update README with Noema architecture and routing diagrams#12raskolnikoff merged 1 commit intomainfrom
Conversation
There was a problem hiding this comment.
Pull request overview
This PR is a documentation overhaul for the RAGfish project, replacing the previous architecture specification with a leaner, more focused description of the Noema Architecture. It removes the old simplified PlantUML diagram from docs/diagrams/, adds three new PlantUML source files under docs/architecture/, adds a new PNG asset (routing-policy-decision.png), and rewrites the README to explain the three-layer architecture, routing policy decisions, and execution runtime flow.
Changes:
- Rewrote
README.mdwith a clearer, concise description of the Noema Architecture, new diagram sections, and a simplified component/principles reference. - Added three new PlantUML diagrams (
architecture-standalone.puml,execution-sequence.puml,routing-decision.puml) and a new AWS-variant diagram (architecture.aws.puml) underdocs/architecture/. - Removed the old
docs/diagrams/architecture-standalone.pumlto avoid duplication and added a rendered PNG for the routing policy decision flow.
Reviewed changes
Copilot reviewed 5 out of 8 changed files in this pull request and generated 2 comments.
Show a summary per file
| File | Description |
|---|---|
README.md |
Rewritten to explain Noema Architecture layers, routing, execution sequence, and design principles |
docs/architecture/architecture-standalone.puml |
New detailed code-level architecture diagram replacing the removed one |
docs/architecture/execution-sequence.puml |
New sequence diagram for the execution runtime flow |
docs/architecture/routing-decision.puml |
New activity diagram for routing policy decision logic |
docs/architecture/architecture.aws.puml |
New AWS-specific variant of the architecture diagram |
docs/assets/routing-policy-decision.png |
New rendered PNG for the routing policy decision diagram |
docs/diagrams/architecture-standalone.puml |
Old simplified diagram removed |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
You can also share your feedback on Copilot code review. Take the survey.
| │ ├ diagrams/ | ||
| │ │ architecture-standalone.puml | ||
| │ │ architecture-standalone.png | ||
| │ │ routing-decision.puml | ||
| │ │ execution-sequence.puml | ||
| │ │ |
There was a problem hiding this comment.
The Repository Structure section in the README states that the .puml files (architecture-standalone.puml, routing-decision.puml, and execution-sequence.puml) are located in docs/diagrams/, but they were actually added to docs/architecture/ in this PR. The documented path does not match the actual file locations, which will mislead developers trying to find or edit the source diagrams.
| │ ├ diagrams/ | |
| │ │ architecture-standalone.puml | |
| │ │ architecture-standalone.png | |
| │ │ routing-decision.puml | |
| │ │ execution-sequence.puml | |
| │ │ | |
| │ ├ architecture/ | |
| │ │ architecture-standalone.puml | |
| │ │ routing-decision.puml | |
| │ │ execution-sequence.puml | |
| │ ├ diagrams/ | |
| │ │ architecture-standalone.png |
|
|
||
| User -> View : submit query | ||
| View -> Coordinator : execute(request) | ||
| Coordinator -> Policy : evaluate(request) |
There was a problem hiding this comment.
The execution-sequence.puml diagram has a logical inconsistency: Coordinator -> Policy : evaluate(request) is called on line 51 but there is no response arrow from Policy back to Coordinator. The PolicyEngine evaluates the request and presumably its result influences the routing decision passed to Router on line 52, but this return/response step is missing from the sequence. This makes the flow ambiguous about how the policy evaluation result is communicated back.
| Coordinator -> Policy : evaluate(request) | |
| Coordinator -> Policy : evaluate(request) | |
| Policy --> Coordinator : evaluation result |
This pull request significantly overhauls the architectural documentation for the RAGfish project, introducing a new, clearer explanation of the Noema Architecture and providing detailed, visual documentation of the system's structure and runtime behavior. The README has been rewritten to clarify the separation of decision, execution, and knowledge layers, and new PlantUML diagrams have been added to illustrate key architectural concepts and flows.
Major improvements and additions:
Documentation Rewrite and Clarification
README.mdhas been completely rewritten to provide a clearer, more structured overview of the Noema Architecture, emphasizing the strict separation of decision (client), execution (agent), and knowledge layers, and introducing new sections on system architecture, routing, execution flows, and design principles.Architecture and Sequence Diagrams
docs/architecture/architecture-standalone.puml,docs/architecture/execution-sequence.puml, anddocs/architecture/routing-decision.puml, offering visual representations of the system’s structure and runtime behavior. [1] [2] [3]Removal of Outdated Diagrams
docs/diagrams/architecture-standalone.pumlto avoid confusion and ensure the documentation reflects the current system design.These changes collectively make the architecture and operational model of RAGfish much more accessible and explicit, supporting both onboarding and future development.