[AISOS-2160] docs: add architecture diagram#152
Closed
ekuris-redhat wants to merge 7 commits into
Closed
Conversation
…ation Detailed description: - Created the initial docs/architecture.md document structure. - Drafted the Overview, Scope, and introduction to the global system architecture. - Documented the three major workflows (Feature, Bug RCA/Fix, Task Takeover). - Added system component architecture diagram and state checkpointing / resumability information. - Ensured formatting adheres to standard Markdown guides in the repository. Closes: AISOS-2165
…ment Lifecycle Detailed description: - Updated docs/architecture.md to add comprehensive documentation on the Isolated Podman Container and Execution Environment Lifecycle. - Outlined host-to-container 1:1 relationship and mapping mechanics. - Described image construction layout under Podman with deepagents and Upstash Context7 MCP. - Detailed volume mounts, workspace isolation (:Z flag), resource constraints (memory/cpu), and network configuration (slirp4netns). - Explained environment variable credential security and Google Application Default Credentials mounting. - Traced task execution lifecycle managed by entrypoint.py from bootstrap to commit generation. - Explained teardown and preservation rules (FORGE_CONTAINER_KEEP). Closes: AISOS-2167
… Edges Detailed description: - Analyzed LangGraph Feature Workflow in src/forge/workflow/feature/graph.py. - Traced all 31 state machine nodes, gates, conditional edge routing functions, feedback loops, and error recovery routes. - Created and integrated a 1:1 code-aligned Mermaid.js state machine flow diagram into docs/architecture.md. - Included full descriptions detailing the state transitions, entry routing, planning, execution, validation, human review, and termination phases. Closes: AISOS-2168
…on Mechanics Detailed description: - Added comprehensive text summaries and ASCII architectural transition diagrams to docs/architecture.md explaining the detailed execution stages of the Feature workflow. - Detailed the Planning Phase: initial Jira inputs triggering PRD, design spec, epic plan, and task generation, alongside the revision feedback mechanism triggered via comment commands. - Detailed the Execution Phase: repository fan-out parallel routing mechanics utilizing LangGraph Send API to orchestrate concurrent Podman execution environments, alongside workspace setups and agent implementation routines. - Detailed the CI/CD Validation & Review Phase: explained autonomous self-healing loops with a rigid 5-attempt retry limit for remote CI failures, transition gates, and PR merge and completion logic. Closes: AISOS-2169
Detailed description: - Analyzed and to extract all workflow nodes, conditional routes, loops, and terminal transitions. - Created featuring a 1:1 code-aligned Mermaid.js state machine diagram of the complete Bug Workflow. - Formatted with visual CSS styling and classes for clarity across the five primary phases (Triage, Analysis/Reflection, RCA Option Gate, Fix Planning, and Validation/Review/Post-Merge). - Explicitly documented the analysis-reflection self-correction loop and transition constraints. Closes: AISOS-2171
…imits Detailed description: - Updated docs/bug-workflow-graph.md with comprehensive, phase-by-phase state transition summaries for the Bug Workflow. - Detailed the transition logic, inputs, outputs, human-in-the-loop gates, and error handling for the Triage, RCA Analysis, Plan Bug Fix, Execution, and Verification phases. - Explicitly documented the RCA analysis/reflection self-correction loop mechanics, including the loop trigger criteria and the hard limit of exactly 3 attempts (_MAX_REFLECTION_COUNT = 3). - Ensured 1:1 code alignment of all state names, labels, and transition routing logic with src/forge/workflow/bug/graph.py. Closes: AISOS-2172
…architecture.md Detailed description: - Appended the 1:1 code-aligned Bug Workflow Mermaid.js state diagram under a new section in docs/architecture.md. - Added comprehensive phase-by-phase detailed summaries covering Triage, Analysis & Reflection, Bug Planning, Execution & Backward-Compatibility, and Validation, Review & Post-Merge Phases based on src/forge/workflow/bug/graph.py. - Validated formatting and Markdown syntax compliance, ensuring all original sections remain intact. Closes: AISOS-2173
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
This pull request establishes a comprehensive, centralized global system architecture documentation foundation (
docs/architecture.md) that maps the entire entry-to-merge trajectory of tickets in the Forge SDLC system. It documents the core components, the isolated containerization execution model under Podman, and provides detailed 1:1 code-aligned Mermaid.js state machine diagrams and technical summaries for both the Feature and Bug Workflows. This documentation serves as the single source of truth for developers to understand workflow orchestration, self-healing loops, parallelization mechanics, and execution environments.Changes
Architecture Documentation Foundation & Infrastructure
docs/architecture.mdoutlining the Overview, Scope, global component architecture, and webhook event-driven ingestion flow.:Zflags), credential mounting (Google Application Default Credentials), resource constraints, execution bootstrap viaentrypoint.py, and teardown/cleanup preservation rules (FORGE_CONTAINER_KEEP).Feature Workflow Mapping & Summaries
src/forge/workflow/feature/graph.pyinto a 1:1 code-aligned Mermaid.js state machine flow diagram.Bug Workflow Mapping & Summaries
src/forge/workflow/bug/graph.pyandsrc/forge/workflow/nodes/rca_analysis.pyto draft a syntax-valid Mermaid.js state machine diagram mapping Triage, Analysis, Reflection, Bug Planning, Execution, and Verification states._MAX_REFLECTION_COUNT = 3).docs/architecture.mdto ensure zero duplication and maintain formatting consistency.Implementation Notes
src/forge/workflow/feature/graph.pyandsrc/forge/workflow/bug/graph.py) exactly to ensure documentation does not become decoupled from behavior.docs/bug-workflow-graph.mdwere unified directly intodocs/architecture.mdto keep all primary workflow orchestration documentation in a single, highly readable file, reducing maintenance overhead.Testing
docs/architecture.mdto verify that all Markdown formatting and Mermaid.js syntax parse perfectly without errors in standard Markdown and Mermaid processors.pytest tests/unit/ -v) to confirm that documentation changes introduced no regressions or runtime errors, resulting in 100% passing test suites.Related Tickets
Generated by Forge SDLC Orchestrator