# griv32/agentic-proposal-generator architecture

> Architecture diagram of the GitHub repository griv32/agentic-proposal-generator, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-10-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/griv32/agentic-proposal-generator
- Repository: https://github.com/griv32/agentic-proposal-generator

## Overview

##### Project Type and Purpose
- This is a Python-based, CLI-driven multi-agent AI orchestration tool (not a web app).
- Purpose: Ingest a discovery call transcript → run specialist AI agents in parallel → synthesize and self-correct → emit a business proposal.

##### File Structure
Top-level directories:
- .claude/agents: human-readable agent definitions (markdown)
- src/agentic_proposal_generator/
– agents/: Python implementations of each specialist agent
– mcp/: “MCP Tools” library (business heuristics & utilities)
– parallel_orchestrator.py: core engine for parallel execution
– events.py: pub/sub or event system for agent coordination
– output_parser.py: formatting & streaming CLI output
– cli.py: entry point / argument parsing
- example_usage.py: sample script for end-user
- sample_data/: demonstration transcript
- tests/: unit, integration, manual/live tests
- CI config, packaging (pyproject.toml), linting, security, docs

##### README for Additional Insights
- Three-phase workflow:
Phase 1: Solutions Engineer, Solution Architect, Commercial Analyst (parallel)
Phase 2: Proposal Writer (synthesis)
Phase 3: Quality Reviewer (self-correction loop & human review)
- MCP Tools (six utility functions available to all agents)
- Async/await patterns for concurrency
- Human-in-the-loop optional via CLI flag

##### Main Components & Their Interactions
a. Components
– CLI Interface (cli.py / example_usage.py)
– Orchestrator (parallel_orchestrator.py + events.py)
– Agent Workers (solutions_engineer, solution_architect, commercial_analyst, proposal_writer, quality_reviewer)
– MCP Tools Library (mcp/tools.py)
– Output Parser / Formatter (output_parser.py)
– External API: Anthropic Claude via Claude Agent SDK
– Optional Human Review (HUMAN_REVIEW.md flow)
– Data Store: local file system for .md/.json outputs
b. Relationships & Data Flow
1. User invokes CLI → loads transcript.
2. CLI calls Orchestrator → emits events to spin up three parallel agents.
3. Each Agent: receives transcript, optionally calls MCP Tools, returns structured output.
4. Orchestrator collects parallel outputs → fires Proposal Writer agent.
5. Proposal Writer calls MCP Tools, merges data → produces draft proposal.
6. Orchestrator invokes Quality Reviewer → scores draft.
7. If score < threshold → feedback loop → re-emit events to revise prior agents.
8. Once approved, orchestrator writes final proposal to disk/CLI stream.
9. If human review not skipped → pause for user approval before finalizing.
c. Architectural Patterns
– Event-driven, pub/sub coordination between orchestrator and agents
– Parallel execution using asyncio
– Self-correction loop (feedback cycle) as a control flow
– Modular “tool” library for separation of concerns (MCP Tools)
d. Key Technologies & Frameworks
– Python 3.10+ (asyncio, type hints)
– Claude Agent SDK (Anthropic)
– UV for dependency management
– pytest (unit, integration, live tests)
– GitHub Actions (CI/CD workflows)

##### Detail Level & Scope
– Capture each agent as its own component even if they live in the same directory
– Include the event bus or orchestration mechanism explicitly
– Show both programmatic (API calls to Claude) and human (CLI prompt) interactions
– Don’t forget the Output Parser/Formatter step before writing the final file

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Layers and components
    subgraph "CLI Layer"
        CLI["CLI Interface"]:::core
        Example["Example Usage Script"]:::core
    end

    subgraph "Pre-processing"
        TS["Transcript Summarizer"]:::agent
    end

    subgraph "Core Engine"
        Orchestrator["Orchestrator\n(parallel_orchestrator.py)"]:::core
        Events["Event Bus\n(events.py)"]:::core
    end

    subgraph "Phase 1: Parallel Agents"
        SE["Solutions Engineer"]:::agent
        SA["Solution Architect"]:::agent
        CA["Commercial Analyst"]:::agent
    end

    subgraph "Phase 2: Synthesis"
        PW["Proposal Writer"]:::agent
    end

    subgraph "Phase 3: Quality Review"
        QR["Quality Reviewer"]:::agent
        Human["Human Review (CLI)"]:::human
    end

    subgraph "Utilities & Integration"
        Tools["MCP Tools Library"]:::util
        Claude["Anthropic Claude API"]:::external
    end

    Parser["Output Parser\n(output_parser.py)"]:::util
    Storage[(Local File Storage)]:::storage

    %% Data flow
    CLI -->|"invoke"| Orchestrator
    CLI -->|"load transcript"| TS
    TS -->|"summary"| Orchestrator
    Orchestrator -->|"emit events"| Events
    Events -->|"start"| SE
    Events -->|"start"| SA
    Events -->|"start"| CA

    SE -->|"structured output"| Orchestrator
    SA -->|"structured output"| Orchestrator
    CA -->|"structured output"| Orchestrator

    SE -->|uses| Tools
    SA -->|uses| Tools
    CA -->|uses| Tools
    SE -->|calls| Claude
    SA -->|calls| Claude
    CA -->|calls| Claude

    Orchestrator -->|"aggregate outputs"| PW
    PW -->|"draft proposal"| Orchestrator
    PW -->|uses| Tools
    PW -->|calls| Claude

    Orchestrator -->|"invoke review"| QR
    QR -->|"score draft"| Orchestrator
    QR -->|uses| Tools
    QR -->|calls| Claude

    Orchestrator -- "if score<threshold" --> SE
    Orchestrator -- "if score<threshold" --> SA
    Orchestrator -- "if score<threshold" --> CA

    Orchestrator -->|"approved"| Human
    Human -->|"user approval"| Orchestrator

    Orchestrator -->|"finalize"| Parser
    Parser -->|"write"| Storage
    Parser -->|"stream"| CLI

    %% Click events
    click CLI "https://github.com/griv32/agentic-proposal-generator/blob/main/src/agentic_proposal_generator/cli.py"
    click Example "https://github.com/griv32/agentic-proposal-generator/blob/main/example_usage.py"
    click TS "https://github.com/griv32/agentic-proposal-generator/blob/main/src/agentic_proposal_generator/agents/transcript_summarizer.py"
    click Orchestrator "https://github.com/griv32/agentic-proposal-generator/blob/main/src/agentic_proposal_generator/parallel_orchestrator.py"
    click Events "https://github.com/griv32/agentic-proposal-generator/blob/main/src/agentic_proposal_generator/events.py"
    click SE "https://github.com/griv32/agentic-proposal-generator/blob/main/src/agentic_proposal_generator/agents/solutions_engineer.py"
    click SA "https://github.com/griv32/agentic-proposal-generator/blob/main/src/agentic_proposal_generator/agents/solution_architect.py"
    click CA "https://github.com/griv32/agentic-proposal-generator/blob/main/src/agentic_proposal_generator/agents/commercial_analyst.py"
    click PW "https://github.com/griv32/agentic-proposal-generator/blob/main/src/agentic_proposal_generator/agents/proposal_writer.py"
    click QR "https://github.com/griv32/agentic-proposal-generator/blob/main/src/agentic_proposal_generator/agents/quality_reviewer.py"
    click Tools "https://github.com/griv32/agentic-proposal-generator/blob/main/src/agentic_proposal_generator/mcp/tools.py"
    click Parser "https://github.com/griv32/agentic-proposal-generator/blob/main/src/agentic_proposal_generator/output_parser.py"
    click Human "https://github.com/griv32/agentic-proposal-generator/blob/main/HUMAN_REVIEW.md"

    %% Styles
    classDef core fill:#AED6F1,stroke:#2E86C1,color:#1B4F72;
    classDef agent fill:#ABEBC6,stroke:#28B463,color:#145A32;
    classDef util fill:#F9E79F,stroke:#B7950B,color:#7D6608;
    classDef external fill:#D5D8DC,stroke:#566573,color:#1B2631;
    classDef human fill:#F5B041,stroke:#B9770E,color:#784212;
    classDef storage fill:#D7BDE2,stroke:#6C3483,color:#4A235A;
```
