# griv32/proposal-generator architecture

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

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

## Overview

##### Project Type and Purpose
- This is an open-source, Python-based CLI tool (“Proposal Generator”) that ingests discovery-call transcript files, invokes the OpenAI API to generate structured business proposals, and outputs markdown/JSON files. It’s a command-line workflow engine, not a multi-tier web app.

##### High-Level File-Structure Analysis
- Top-level:
- `src/proposal_generator/` – core modules (CLI, workflow, processors, models, formatter)
- `run_*` and `example_*.py` scripts – sample entry points
- `sample_data/` – example transcripts
- `docs/` – API and developer docs
- CI/CD configs and linting/security tools in `.github/`, `.bandit`, `.pre-commit-config.yaml`, etc.
- Tests mirror the core modules under `tests/`, verifying each component.

##### Key Modules & Responsibilities
- CLI (`cli.py`): Parses command-line args (Click), loads env, dispatches to `ProposalWorkflow`.
- Workflow (`workflow.py`): Orchestrates the end-to-end pipeline:
a. Load transcript (file or text)
b. `TranscriptionProcessor` – cleans/splits the text
c. `ProposalGenerator` – assembles prompts, calls OpenAI API (via LangChain or direct HTTP)
d. `OutputFormatter` – builds Markdown/JSON, writes to disk
- Models (`models.py`): Pydantic schemas for inputs/outputs and validation.

##### External Dependencies & Storage
- Environment/config: `.env` or env vars for OpenAI API Key, model, log level
- External Service: OpenAI GPT API (via LangChain or direct REST)
- Local FS:
- Input transcripts (`--input`, `sample_data/`)
- Output folder (`--output` for `.md` and `.json`)

a. **CLI Layer**
- proposal-generator executable (Click)
- Example runners (`run_example.py`, `run_proposal_generator.py`)
b. **Core Pipeline**
- ProposalWorkflow (orchestrator)
- TranscriptionProcessor
- ProposalGenerator
- OutputFormatter
- Models (validation)
c. **External Services**
- OpenAI GPT API
d. **Persistence**
- Local File System for inputs/outputs
e. **Configuration**
- Env Vars / .env loader

##### Relationships & Data Flow
1. User invokes CLI →
2. CLI parses args & reads transcript file →
3. Workflow calls TranscriptionProcessor → cleans/splits text →
4. Workflow calls ProposalGenerator → sends prompt/data to OpenAI →
5. OpenAI returns generated content →
6. Workflow calls OutputFormatter → writes `.md` and `.json` →
7. CLI reports success/failure

##### Architectural Patterns & Principles
- Pipeline / Chain of Responsibility: each module has a single responsibility.
- Dependency Injection: CLI wires in Workflow and modules.
- Modular, testable components with Pydantic models.
- External-service abstraction (isolated call to OpenAI).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CLI Layer
    subgraph "CLI Layer"
        ExecNode["proposal-generator CLI"]:::cli
        RunExample["run_example.py"]:::cli
        RunProposal["run_proposal_generator.py"]:::cli
        ExampleUsage["example_usage.py"]:::cli
        ExampleFileUsage["example_file_usage.py"]:::cli
    end

    %% Core Pipeline
    subgraph "ProposalGenerator Pipeline"
        Workflow["ProposalWorkflow\n(src/proposal_generator/workflow.py)"]:::core
        TranscriptionProcessor["TranscriptionProcessor\n(src/proposal_generator/transcription_processor.py)"]:::core
        ProposalGenerator["ProposalGenerator\n(src/proposal_generator/proposal_generator.py)"]:::core
        OutputFormatter["OutputFormatter\n(src/proposal_generator/output_formatter.py)"]:::core
        Models["Pydantic Models\n(src/proposal_generator/models.py)"]:::core
    end

    %% External Services
    subgraph "External Services"
        OpenAI["OpenAI GPT API"]:::external
    end

    %% Persistence
    subgraph "Persistence"
        SampleData["discovery_call_transcript.txt\n(sample_data/)"]:::fs
        FileSystem["Local File System\n(inputs/outputs)"]:::fs
    end

    %% Docs & Config
    subgraph "Docs & Config"
        ApiDoc["API Documentation\n(docs/API.md)"]:::docs
        DevGuide["Developer Guide\n(docs/DEVELOPER_GUIDE.md)"]:::docs
        EnvExample[".env.example"]:::docs
    end

    %% CI/CD Workflows
    subgraph "CI/CD"
        CI1["ci.yml\n(.github/workflows/)"]:::ci
        CI2["release.yml\n(.github/workflows/)"]:::ci
    end

    %% Tests
    subgraph "Tests"
        TestCLI["test_cli.py"]:::test
        TestWorkflow["test_workflow.py"]:::test
        TestProc["test_transcription_processor.py"]:::test
        TestGen["test_proposal_generator.py"]:::test
        TestFmt["test_output_formatter.py"]:::test
        TestModels["test_models.py"]:::test
    end

    %% Data Flow
    ExecNode -->|"invoke"| Workflow
    ExecNode -->|"reads transcript"| SampleData
    SampleData -->|"raw transcript"| TranscriptionProcessor
    TranscriptionProcessor -->|"cleaned text"| ProposalGenerator
    ProposalGenerator -->|"API request/response"| OpenAI
    OpenAI -->|"LLM response"| ProposalGenerator
    ProposalGenerator -->|"data for formatting"| OutputFormatter
    OutputFormatter -->|"writes .md/.json"| FileSystem
    Workflow -->|"uses schemas"| Models

    %% Test Connections
    TestCLI --> ExecNode
    TestWorkflow --> Workflow
    TestProc --> TranscriptionProcessor
    TestGen --> ProposalGenerator
    TestFmt --> OutputFormatter
    TestModels --> Models

    %% Click Events
    click ExecNode "https://github.com/griv32/proposal-generator/blob/main/src/proposal_generator/cli.py"
    click RunExample "https://github.com/griv32/proposal-generator/blob/main/run_example.py"
    click RunProposal "https://github.com/griv32/proposal-generator/blob/main/run_proposal_generator.py"
    click ExampleUsage "https://github.com/griv32/proposal-generator/blob/main/example_usage.py"
    click ExampleFileUsage "https://github.com/griv32/proposal-generator/blob/main/example_file_usage.py"
    click Workflow "https://github.com/griv32/proposal-generator/blob/main/src/proposal_generator/workflow.py"
    click TranscriptionProcessor "https://github.com/griv32/proposal-generator/blob/main/src/proposal_generator/transcription_processor.py"
    click ProposalGenerator "https://github.com/griv32/proposal-generator/blob/main/src/proposal_generator/proposal_generator.py"
    click OutputFormatter "https://github.com/griv32/proposal-generator/blob/main/src/proposal_generator/output_formatter.py"
    click Models "https://github.com/griv32/proposal-generator/blob/main/src/proposal_generator/models.py"
    click SampleData "https://github.com/griv32/proposal-generator/blob/main/sample_data/discovery_call_transcript.txt"
    click ApiDoc "https://github.com/griv32/proposal-generator/blob/main/docs/API.md"
    click DevGuide "https://github.com/griv32/proposal-generator/blob/main/docs/DEVELOPER_GUIDE.md"
    click EnvExample "https://github.com/griv32/proposal-generator/blob/main/.env.example"
    click CI1 "https://github.com/griv32/proposal-generator/blob/main/.github/workflows/ci.yml"
    click CI2 "https://github.com/griv32/proposal-generator/blob/main/.github/workflows/release.yml"
    click TestCLI "https://github.com/griv32/proposal-generator/blob/main/tests/test_cli.py"
    click TestWorkflow "https://github.com/griv32/proposal-generator/blob/main/tests/test_workflow.py"
    click TestProc "https://github.com/griv32/proposal-generator/blob/main/tests/test_transcription_processor.py"
    click TestGen "https://github.com/griv32/proposal-generator/blob/main/tests/test_proposal_generator.py"
    click TestFmt "https://github.com/griv32/proposal-generator/blob/main/tests/test_output_formatter.py"
    click TestModels "https://github.com/griv32/proposal-generator/blob/main/tests/test_models.py"

    %% Styles
    classDef cli fill:#ADD8E6,stroke:#000
    classDef core fill:#6495ED,stroke:#000
    classDef external fill:#90EE90,stroke:#000
    classDef fs fill:#D3D3D3,stroke:#000
    classDef docs fill:#F0E68C,stroke:#000
    classDef ci fill:#FFE4B5,stroke:#000
    classDef test fill:#FFB6C1,stroke:#000
```
