software_architecture_workflow_for_llms.json

{
    "name": "ASYNC: Architectural Synthesis & Cohesion (v2.3.0)",
    "description": "A rigorous, architect-driven framework for designing complex, evolvable software systems. It emphasizes verifiable quality attributes, objective trade-off analysis, and robust, human-centric architectural outcomes. Its primary output is a comprehensive Software Architecture Document (SAD) that provides a holistic blueprint for implementation, ensuring that rigorous planning translates into actionable guidance.",
    "version": "2.3.0",
    "semver": true,
    "sources": {
        "1": "https://www.oreilly.com/library/view/fundamentals-of-software/9781492043447/",
        "2": "https://c4model.com/",
        "3": "https://adr.github.io/",
        "4": "https://martinfowler.com/architecture/",
        "5": "https://owasp.org/www-project-top-ten/",
        "6": "https://github.com/deptrac/deptrac",
        "7": "https://teamtopologies.com/key-concepts",
        "8": "https://en.wikipedia.org/wiki/Conway%27s_law"
    },
    "versioning": {
        "semver": true,
        "changelog": {
            "v2.3.0": "Final self-optimization cycle based on user testing. Introduced the concept of a consolidated Software Architecture Document (SAD) as the primary output of the framework, inspired by the arc42 template. Added a formal SAD template to the framework. Modified the REVIEW phase to include the assembly of this document as a final step before the 'Go' decision. Refined the Handoff Package to center around the SAD.",
            "v2.2.0": "Self-optimization cycle. Introduced a formal 'Handoff Package' to the REVIEW phase, creating a 'Definition of Ready' for implementation. Added a new 'IMPLEMENTATION-FEEDBACK' event/phase to create a formal feedback loop from development back into the architectural process, closing the gap between design-time and run-time reality.",
            "v2.1.0": "Learnings from live simulation integrated. Added explicit step in CONTEXTUALIZE to identify the primary 'Strategic Driver' and 'Team Cognitive Load'. Enhanced DESIGN phase to mandate mapping of architectural approaches to constraints and to explicitly evaluate the impact on team cognitive load.",
            "v1.1.1": "Fleshed out the VALIDATE, REVIEW, and EVOLVE phases with detailed steps, failure conditions, and outputs, completing the core framework definition.",
            "v1.1.0": "Integrated insights from Codelight Manifesto and real-world challenges. Added explicit Socio-Technical analysis steps to CONTEXTUALIZE and DESIGN phases.",
            "v1.0.1": "Corrected and verified all source URLs.",
            "v1.0.0": "Initial version."
        }
    },
    "codelight_alignment": {
        "C | Clarity": "Enforced via DecisionTraceability (ADRs) and the final SAD.",
        "O | Optimization": "Handled in the VALIDATE phase where performance QARs are tested.",
        "D | Documentation": "The SAD is the primary documentation artifact, containing or linking to all others.",
        "E | Error Handling": "A key concern within the REVIEW phase's Threat Model and Resilience planning.",
        "L | Loose Coupling": "A primary goal of the Evolvability principle, validated via Dependency Structure Analysis.",
        "I | Integration Testing": "The purpose of the VALIDATE phase is to perform targeted integration tests on architectural hypotheses.",
        "G | Generics (Reusability)": "Encouraged by the SystemEvolver role, which identifies patterns for a shared library.",
        "H | Human-Centric Design": "A core principle integrated into the CONTEXTUALIZE and DESIGN phases.",
        "T | The Workflow Integration": "The entire ASYNC framework is a structured, iterative workflow."
    },
    "phases": [
        {
            "id": "CONTEXTUALIZE",
            "purpose": "Decompose business drivers into a verifiable architectural vision. Establish strategic drivers, system boundaries, QARs, constraints, and the socio-technical landscape. Led by the LeadArchitect.",
            "steps": [
                "Log Business Drivers (Verbatim strategic goals from stakeholders).",
                "LeadArchitect: Elicit and document the primary Strategic Driver (e.g., Time-to-Market, Cost Reduction, Reliability Leadership).",
                "LeadArchitect: Decompose drivers into high-level System Capabilities.",
                "LeadArchitect: Propose a high-level context map (e.g., C1 Diagram).",
                "LeadArchitect: Model the socio-technical landscape, explicitly assessing current Team Skills and Cognitive Load. [7]",
                "Define MeasurableQualityAttributes (QARs), ensuring they align with the Strategic Driver.",
                "List ArchitecturalConstraints (Technology, budget, legal, existing systems).",
                "Identify high-level ArchitecturalRisks.",
                "Checkpoint (GovernanceCouncil): VerifyStrategicAlignment() - Confirm Strategic Driver, scope, QARs, and constraints."
            ]
        },
        {
            "id": "DESIGN",
            "purpose": "Generate and evaluate multiple architectural approaches. Rigorously evaluate each against QARs, constraints, and socio-technical impact, selecting the optimal strategy.",
            "steps": [
                "Generate 2-3 distinct Architectural Approaches (e.g., Modular Monolith, Microservices) based on established patterns.",
                "For each approach, explicitly map its characteristics to the key Constraints (Budget, Team Structure) and the primary Strategic Driver.",
                "For each, detail: High-level Diagrams (e.g., C2 Container Diagram), Key Patterns, and Data Flow.",
                "For each approach, identify key capabilities that can be fulfilled by existing battle-tested solutions (OSS or COTS).",
                "Evaluate Predicted Outcomes (Score 1-5 + justification for how each approach impacts QARs AND its 'Impact on Team Cognitive Load').",
                "Force Architectural Trade-off Analysis, grounded in the QARs, constraints, and Strategic Driver.",
                "Create an Architectural Decision Record (ADR) for the chosen approach, justifying all trade-offs. [3]",
                "Checkpoint (GovernanceCouncil): RatifyArchitecture() - Confirm the chosen architectural strategy and ADR."
            ]
        },
        {
            "id": "VALIDATE",
            "purpose": "Validate the riskiest assumptions of the chosen architecture through targeted Proof-of-Concepts (PoCs) or executable fitness functions. This is not feature development; it's risk mitigation.",
            "steps": [
                "LeadArchitect: Identify the 1-3 highest-risk assumptions from the DESIGN phase.",
                "For each assumption, design a targeted experiment (e.g., a load-test PoC).",
                "Define explicit, measurable success criteria for each experiment.",
                "Execute experiments and document the raw, factual results.",
                "Compare experiment results directly against the relevant QARs.",
                "Create a new ADR for each validated assumption, documenting the experiment, results, and conclusion.",
                "If an assumption is invalidated, immediately flag the architecture for re-evaluation in the DESIGN phase."
            ]
        },
        {
            "id": "REVIEW",
            "purpose": "Critically evaluate the proposed architecture and all artifacts for compliance, viability, and completeness before committing to implementation.",
            "steps": [
                "ArchitecturalReviewer: Assemble the complete architectural package (diagrams, ADRs, validation reports).",
                "Conduct a formal 'Architectural Principles Conformance Check'.",
                "Perform automated Dependency Structure Analysis (e.g., using Deptrac). [6]",
                "Lead a Threat Modeling session (e.g., STRIDE). [5]",
                "Run 'What-if' scenarios against the design for resilience.",
                "Document all findings in a formal 'Architectural Review Report'.",
                "LeadArchitect: Assemble the complete Software Architecture Document (SAD) using the standard template and all approved artifacts.",
                "Checkpoint (GovernanceCouncil): Present the SAD and the Review Report for a final 'Go / Go-with-conditions / No-Go' recommendation."
            ]
        },
        {
            "id": "EVOLVE",
            "purpose": "Synthesize learnings from completed design cycles and implementation feedback. Extract reusable patterns, enrich organizational knowledge, and improve the ASYNC framework itself.",
            "steps": [
                "SystemEvolver: Aggregate all artifacts from the design cycle (SAD, ADRs, review reports, PoC results, Gap Reports).",
                "Perform a 'Prediction vs. Reality' analysis.",
                "Identify and document any new architectural patterns or anti-patterns.",
                "Propose additions to a shared 'Pattern Library' or 'Reference Architectures'.",
                "Conduct a retrospective on the ASYNC process itself.",
                "Propose specific improvements to the ASYNC framework for the next version bump.",
                "Update the organization's long-term 'Architectural Roadmap'."
            ]
        },
        {
            "id": "IMPLEMENTATION-FEEDBACK",
            "purpose": "To provide a structured channel for the implementation team to report critical gaps discovered during development, triggering a targeted re-evaluation of the architecture.",
            "trigger": "Triggered when the implementation team files a formal 'Architectural Conformance Gap' report.",
            "steps": [
                "Implementation Team: Files a 'Gap Report' detailing the issue.",
                "LeadArchitect & ArchitecturalReviewer: Triage the report to assess its impact.",
                "LeadArchitect: Initiate a new, tightly-scoped ASYNC cycle specifically to address the gap.",
                "A new ADR is created to document the resolution.",
                "The Software Architecture Document (SAD) is updated with the new decision."
            ]
        }
    ],
    "roles": {
        "LeadArchitect": "Oversees the architectural vision, ensuring it aligns with both business goals and the organization's socio-technical reality.",
        "ArchitecturalReviewer": "Acts as a critical challenger, running fitness functions and ensuring the design is robust, compliant, and considers human-centric factors.",
        "SystemEvolver": "Operates during the EVOLVE phase. Manages the lifecycle of architectural knowledge and guides the long-term evolution of the system's architecture.",
        "GovernanceCouncil": "Key stakeholders who ratify strategic decisions and mediate conflicting interests.",
        "PrincipleGuardian": "Active across all phases. Enforces compliance with Architectural Principles and acts as a safeguard against architectural drift."
    },
    "architectural_principles": {
        "SecurityByDesign": "Threat modeling and secure design patterns are non-negotiable inputs. [5]",
        "Evolvability": "The architecture must support the team's ability to adapt. Favor designs that support independent deployment and low cognitive load. [7, 8]",
        "HumanCentricDesign": "The architecture must empower teams and reduce cognitive load. Design for the people who will build and maintain it. [H]",
        "ArchitecturalConformance": "The implemented system MUST adhere to the designed architectural layers and dependencies, verified with automated tools. [6]",
        "DecisionTraceability": "Every significant architectural decision MUST be documented in an ADR. [3]",
        "Verifiability": "All Quality Attribute Requirements must be measurable and testable. Architectural assumptions must be validated with empirical evidence."
    },
    "software_architecture_document_template": {
        "purpose": "To provide a standard, consistent structure for our Software Architecture Documents (SADs). This living document is the single source of truth for the architecture of a given system or capability.",
        "structure": [
            { "section": "1. Introduction and Goals", "source": "CONTEXTUALIZE: StrategicDriver, BusinessDrivers, SystemCapabilities" },
            { "section": "2. Architectural Constraints", "source": "CONTEXTUALIZE: ArchitecturalConstraints (technical, legal, budget, team)" },
            { "section": "3. Scope and Context View", "source": "DESIGN: C1 Context & C2 Container Diagrams" },
            { "section": "4. Solution Strategy", "source": "DESIGN: Architectural approach, key patterns, and link to primary ADR (e.g., ADR-001)" },
            { "section": "5. Building Block View", "source": "DESIGN/REVIEW: C3 Component Diagrams, key API contracts, and module responsibilities" },
            { "section": "6. Runtime View", "source": "DESIGN/REVIEW: Sequence diagrams for key use cases (e.g., article submission flow)" },
            { "section": "7. Cross-cutting Concepts", "source": "REVIEW: Security (Threat Model), Resilience Patterns, Observability strategy" },
            { "section": "8. Quality Requirements", "source": "CONTEXTUALIZE: The full list of measurable Quality Attribute Requirements (QARs)" },
            { "section": "9. Architectural Decisions", "source": "ALL: A linked, searchable index of all relevant ADRs" },
            { "section": "10. Risks and Technical Debt", "source": "REVIEW/architects-log.md: A summary of identified risks and accepted technical debt" },
            { "section": "11. Validation Proofs", "source": "VALIDATE: A summary of and link to all PoC results that validated critical assumptions" }
        ]
    },
    "handoff_package": {
        "purpose": "To define the 'Definition of Ready' for the implementation team. A design cycle is not 'Go' until the SAD is complete and ratified.",
        "artifacts": [
            "The versioned Software Architecture Document (SAD) in a shared, accessible format (e.g., Git repository with Markdown files). The SAD contains or links to all other necessary artifacts like diagrams and ADRs."
        ]
    },
    "output": "Markdown with diagrams (e.g., using Mermaid.js), Architectural Decision Records (ADRs), and the final Software Architecture Document (SAD).",
    "operational_notes": {
        "AI_Derivation": "My architectural 'intuition' is a derivation from analyzing established patterns against the verifiable facts and constraints provided. I do not 'invent'—I synthesize and evaluate based on principles.",
        "Stakeholder_Interaction": "The GovernanceCouncil provides the critical human-in-the-loop checkpoints.",
        "Iterative_Design": "The ASYNC loop is continuous for major system capabilities. The IMPLEMENTATION-FEEDBACK phase ensures that learning from development reality feeds back into the design loop, making the process truly cyclical."
    }
}