# vishwanathbalasubramanian/aiflowcraft-project architecture

> Architecture diagram of the GitHub repository vishwanathbalasubramanian/aiflowcraft-project, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/vishwanathbalasubramanian/aiflowcraft-project
- Repository: https://github.com/vishwanathbalasubramanian/aiflowcraft-project

## Overview

##### Main Components
- Orchestrator: (src/orchestrator/orchestrator.py) acts as the core controller that manages the LangGraph-based node execution, handling transitions (pause/resume, rejection rerouting) among workflow stages.
- Agents: Located in src/agents, these are modular components for each stage:
- user_input_agent: For generating user stories.
- design_agent: For creating design documents.
- code_agent: For code generation.
- review_agent: For code review.
- qa_agent: For QA assessments.
- Utility Modules: (src/utils) encapsulate the logic for GitHub integration (github_helper), SQLite DB referencing (db_reference), and review logic (review_utils).
- External Integrations: Include external services like:
- GitHub REST API for committing and uploading code post-QA.
- Groq API integration as indicated for API key configuration.
- SQLite for evidence-based generation via a reference database.
- Experimental Modules: (src/experimental) that may be useful for backup/legacy flows or test runs.

##### Interactions and Data Flow
- UI → Orchestrator: The Streamlit app sends workflow inputs and receives status updates while providing interactive configuration (e.g., review modes, API keys, file uploads).
- Orchestrator → Agents: The orchestrator directs each agent sequentially according to the workflow: starting with user story generation, then design, code generation, review, and finally QA.
- Util Modules: These modules are invoked as dependencies by both the orchestrator and agents (e.g., GitHub helper for uploads, database reference for grounding content, review logic for LLM-based evaluation).

##### Architectural Patterns & Design Principles
- Modular Design: Each agent and utility is a decoupled component, making testing and extension (e.g., adding a new stage) easier.
- Stateful & Reactive UI: The Streamlit front end maintains session state and continuous log streaming.
- Extensibility and Configurable Pipeline: Emphasize how workflow configurations (different modes, conditional transitions) are managed within the orchestrator.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Nodes
    Start("Start"):::startend
    UI["Streamlit UI"]:::ui
    Orch["Workflow Engine"]:::orchestrator

    subgraph "Core Workflow"
        USG["User Story Generation"]:::agent
        USR["User Story Review"]:::agent
        DG["Design Generation"]:::agent
        DR["Design Review"]:::agent
        CG["Code Generation"]:::agent
        CR["Code Review"]:::agent
        QAG["QA Generation"]:::agent
        QAR["QA Review"]:::agent
    end

    End("End"):::startend

    %% Utility and External Modules
    subgraph "Utilities"
        GitHubUtil["GitHub Integration Utility"]:::utility
        SQLiteUtil["SQLite DB Reference Utility"]:::utility
        ReviewUtil["Review Logic Utility"]:::utility
    end

    subgraph "External Services"
        GitHubAPI["GitHub API"]:::external
        GroqAPI["Groq API"]:::external
        SQLiteDB["SQLite DB"]:::external
    end

    Exp["Experimental Modules"]:::utility

    %% Main Flow Connections
    Start -->|"ProjectInput"| UI
    UI -->|"InitWorkflow"| Orch

    Orch -->|"Trigger"| USG
    USG -->|"Output"| USR
    USR -- "Rejected" --> USG
    USR -- "Approved" --> DG

    DG -->|"Output"| DR
    DR -- "Rejected" --> DG
    DR -- "Approved" --> CG

    CG -->|"Output"| CR
    CR -- "Rejected" --> CG
    CR -- "Approved" --> QAG

    QAG -->|"Output"| QAR
    QAR -- "Rejected" --> QAG
    QAR -- "Approved" --> End

    %% Connections to Utilities and External Services
    Orch -->|"UploadCode"| GitHubUtil
    GitHubUtil -->|"API call"| GitHubAPI

    Orch -->|"DBReference"| SQLiteUtil
    SQLiteUtil -->|"Query"| SQLiteDB

    Orch -->|"LLMReview"| ReviewUtil

    QAG -->|"AIProcess"| GroqAPI

    Orch -.->|"Legacy/Test"| Exp

    %% Styling - Classes Definitions
    classDef startend fill:#cccccc,stroke:#000000,stroke-width:2px;
    classDef ui fill:#ff9,stroke:#333,stroke-width:2px;
    classDef orchestrator fill:#bbf,stroke:#333,stroke-width:2px;
    classDef agent fill:#cfc,stroke:#333,stroke-width:2px;
    classDef utility fill:#ffd,stroke:#333,stroke-width:2px;
    classDef external fill:#fdd,stroke:#333,stroke-width:2px;

    %% Click Events
    click UI "https://github.com/vishwanathbalasubramanian/aiflowcraft-project/blob/main/src/main.py"
    click Orch "https://github.com/vishwanathbalasubramanian/aiflowcraft-project/blob/main/src/orchestrator/orchestrator.py"
    click USG "https://github.com/vishwanathbalasubramanian/aiflowcraft-project/blob/main/src/agents/user_input_agent.py"
    click DG "https://github.com/vishwanathbalasubramanian/aiflowcraft-project/blob/main/src/agents/design_agent.py"
    click CG "https://github.com/vishwanathbalasubramanian/aiflowcraft-project/blob/main/src/agents/code_agent.py"
    click USR "https://github.com/vishwanathbalasubramanian/aiflowcraft-project/blob/main/src/agents/review_agent.py"
    click DR "https://github.com/vishwanathbalasubramanian/aiflowcraft-project/blob/main/src/agents/review_agent.py"
    click CR "https://github.com/vishwanathbalasubramanian/aiflowcraft-project/blob/main/src/agents/review_agent.py"
    click QAG "https://github.com/vishwanathbalasubramanian/aiflowcraft-project/blob/main/src/agents/qa_agent.py"
    click QAR "https://github.com/vishwanathbalasubramanian/aiflowcraft-project/blob/main/src/agents/qa_agent.py"
    click GitHubUtil "https://github.com/vishwanathbalasubramanian/aiflowcraft-project/blob/main/src/utils/github_helper.py"
    click SQLiteUtil "https://github.com/vishwanathbalasubramanian/aiflowcraft-project/blob/main/src/utils/db_reference.py"
    click ReviewUtil "https://github.com/vishwanathbalasubramanian/aiflowcraft-project/blob/main/src/utils/review_utils.py"
    click Exp "https://github.com/vishwanathbalasubramanian/aiflowcraft-project/tree/main/src/experimental"
```
