# rounaksenskr/proposalflow-ai architecture

> Architecture diagram of the GitHub repository rounaksenskr/proposalflow-ai, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/rounaksenskr/proposalflow-ai
- Repository: https://github.com/rounaksenskr/proposalflow-ai

## Overview

ProposalFlow AI turns a freelancer’s client lead into a researched, tailored proposal, then pauses for human approval before recording the result. FastAPI accepts leads and exposes status and review endpoints; the LangGraph workflow coordinates validation, research, portfolio retrieval, proposal drafting, critique, retry routing, review, and persistence. Retrieval combines BM25 and vector search with reciprocal-rank fusion over the Markdown knowledge base. Research uses Tavily and Groq. The graph, routes, research, and retrieval implementations were sampled; generator and persistence details are inferred only from the README and source tree, so their internal wiring is not expanded.

Main entry points: [`src/proposal_bot/graph.py`](https://github.com/rounaksenskr/proposalflow-ai/blob/main/src/proposal_bot/graph.py) (Workflow Graph), [`src/proposal_bot/api/routes.py`](https://github.com/rounaksenskr/proposalflow-ai/blob/main/src/proposal_bot/api/routes.py) (Lead and Review Routes), [`src/proposal_bot/nodes/research.py`](https://github.com/rounaksenskr/proposalflow-ai/blob/main/src/proposal_bot/nodes/research.py) (Client Research), [`src/proposal_bot/api/app.py`](https://github.com/rounaksenskr/proposalflow-ai/blob/main/src/proposal_bot/api/app.py) (FastAPI App)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["API and Entry"]
  node_fastapi["FastAPI App<br/>[app.py]"]
  node_routes["Lead and Review Routes<br/>[routes.py]"]
end

subgraph group_workflow["Proposal Workflow"]
  node_graph["Workflow Graph<br/>[graph.py]"]
  node_ingestion["Lead Ingestion<br/>[ingestion.py]"]
  node_generator["Proposal Generator<br/>[generator.py]"]
  node_critic["Proposal Critic<br/>[critic.py]"]
  node_review["Human Review<br/>[graph.py]"]
  node_persist["Proposal Persistence<br/>[persist.py]"]
end

subgraph group_knowledge["Research and Retrieval"]
  node_research["Client Research<br/>[research.py]"]
  node_retrieval["Case Retrieval<br/>[retrieval.py]"]
  node_hybrid["Hybrid Retriever"]
  node_knowledgebase["Portfolio Knowledge Base"]
end

subgraph group_storage["State and Records"]
  node_records[("Proposal Records<br/>[models.py]")]
  node_dbsession["Database Session<br/>[session.py]"]
  node_checkpoint[("Graph Checkpoints<br/>[routes.py]")]
end

node_freelancer(("Freelancer"))
node_tavily["Tavily Search"]
node_groq["Groq LLM"]
node_reviewer(("Freelancer Reviewer"))

node_freelancer -->|"submits lead"| node_fastapi
node_fastapi -->|"dispatches requests"| node_routes
node_routes -->|"invokes workflow"| node_graph
node_graph -->|"dispatches"| node_ingestion
node_graph -->|"dispatches"| node_research
node_graph -->|"dispatches"| node_retrieval
node_graph -->|"dispatches"| node_generator
node_graph -->|"dispatches"| node_critic
node_graph -->|"dispatches"| node_review
node_graph -->|"dispatches"| node_persist
node_research -->|"searches"| node_tavily
node_research -->|"extracts intelligence"| node_groq
node_retrieval -->|"queries"| node_hybrid
node_hybrid -->|"loads documents"| node_knowledgebase
node_review -->|"requests decision"| node_reviewer
node_reviewer -->|"submits decision"| node_routes
node_routes -->|"reads and resumes"| node_checkpoint
node_routes -->|"reads status"| node_graph
node_persist -->|"uses session"| node_dbsession
node_dbsession -->|"creates tables"| node_records

click node_fastapi "https://github.com/rounaksenskr/proposalflow-ai/blob/main/src/proposal_bot/api/app.py"
click node_routes "https://github.com/rounaksenskr/proposalflow-ai/blob/main/src/proposal_bot/api/routes.py"
click node_graph "https://github.com/rounaksenskr/proposalflow-ai/blob/main/src/proposal_bot/graph.py"
click node_ingestion "https://github.com/rounaksenskr/proposalflow-ai/blob/main/src/proposal_bot/nodes/ingestion.py"
click node_research "https://github.com/rounaksenskr/proposalflow-ai/blob/main/src/proposal_bot/nodes/research.py"
click node_retrieval "https://github.com/rounaksenskr/proposalflow-ai/blob/main/src/proposal_bot/nodes/retrieval.py"
click node_hybrid "https://github.com/rounaksenskr/proposalflow-ai/blob/main/src/proposal_bot/rag/hybrid_retriever.py"
click node_knowledgebase "https://github.com/rounaksenskr/proposalflow-ai/tree/main/data/knowledge_base"
click node_generator "https://github.com/rounaksenskr/proposalflow-ai/blob/main/src/proposal_bot/nodes/generator.py"
click node_critic "https://github.com/rounaksenskr/proposalflow-ai/blob/main/src/proposal_bot/nodes/critic.py"
click node_review "https://github.com/rounaksenskr/proposalflow-ai/blob/main/src/proposal_bot/graph.py"
click node_persist "https://github.com/rounaksenskr/proposalflow-ai/blob/main/src/proposal_bot/nodes/persist.py"
click node_records "https://github.com/rounaksenskr/proposalflow-ai/blob/main/src/proposal_bot/db/models.py"
click node_dbsession "https://github.com/rounaksenskr/proposalflow-ai/blob/main/src/proposal_bot/db/session.py"
click node_checkpoint "https://github.com/rounaksenskr/proposalflow-ai/blob/main/src/proposal_bot/api/routes.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_fastapi,node_routes,node_reviewer toneBlue
class node_graph,node_ingestion,node_generator,node_critic,node_review,node_persist toneAmber
class node_research,node_retrieval,node_hybrid,node_knowledgebase toneMint
class node_records,node_dbsession,node_checkpoint toneRose
class node_freelancer,node_tavily,node_groq toneIndigo
```

## Components

### API and Entry

- [FastAPI App](https://github.com/rounaksenskr/proposalflow-ai/blob/main/src/proposal_bot/api/app.py): `src/proposal_bot/api/app.py`
- [Lead and Review Routes](https://github.com/rounaksenskr/proposalflow-ai/blob/main/src/proposal_bot/api/routes.py): `src/proposal_bot/api/routes.py`

### Proposal Workflow

- [Workflow Graph](https://github.com/rounaksenskr/proposalflow-ai/blob/main/src/proposal_bot/graph.py): `src/proposal_bot/graph.py`
- [Lead Ingestion](https://github.com/rounaksenskr/proposalflow-ai/blob/main/src/proposal_bot/nodes/ingestion.py): `src/proposal_bot/nodes/ingestion.py`
- [Proposal Generator](https://github.com/rounaksenskr/proposalflow-ai/blob/main/src/proposal_bot/nodes/generator.py): `src/proposal_bot/nodes/generator.py`
- [Proposal Critic](https://github.com/rounaksenskr/proposalflow-ai/blob/main/src/proposal_bot/nodes/critic.py): `src/proposal_bot/nodes/critic.py`
- [Human Review](https://github.com/rounaksenskr/proposalflow-ai/blob/main/src/proposal_bot/graph.py): `src/proposal_bot/graph.py`
- [Proposal Persistence](https://github.com/rounaksenskr/proposalflow-ai/blob/main/src/proposal_bot/nodes/persist.py): `src/proposal_bot/nodes/persist.py`

### Research and Retrieval

- [Client Research](https://github.com/rounaksenskr/proposalflow-ai/blob/main/src/proposal_bot/nodes/research.py): `src/proposal_bot/nodes/research.py`
- [Case Retrieval](https://github.com/rounaksenskr/proposalflow-ai/blob/main/src/proposal_bot/nodes/retrieval.py): `src/proposal_bot/nodes/retrieval.py`
- [Hybrid Retriever](https://github.com/rounaksenskr/proposalflow-ai/blob/main/src/proposal_bot/rag/hybrid_retriever.py): `src/proposal_bot/rag/hybrid_retriever.py`
- [Portfolio Knowledge Base](https://github.com/rounaksenskr/proposalflow-ai/tree/main/data/knowledge_base): `data/knowledge_base`

### State and Records

- [Proposal Records](https://github.com/rounaksenskr/proposalflow-ai/blob/main/src/proposal_bot/db/models.py): `src/proposal_bot/db/models.py`
- [Database Session](https://github.com/rounaksenskr/proposalflow-ai/blob/main/src/proposal_bot/db/session.py): `src/proposal_bot/db/session.py`
- [Graph Checkpoints](https://github.com/rounaksenskr/proposalflow-ai/blob/main/src/proposal_bot/api/routes.py): `src/proposal_bot/api/routes.py`

### Other components

- **Freelancer**
- **Tavily Search**
- **Groq LLM**
- **Freelancer Reviewer**

## Connections

- Freelancer → FastAPI App: submits lead
- FastAPI App → Lead and Review Routes: dispatches requests
- Lead and Review Routes → Workflow Graph: invokes workflow
- Workflow Graph → Lead Ingestion: dispatches
- Workflow Graph → Client Research: dispatches
- Workflow Graph → Case Retrieval: dispatches
- Workflow Graph → Proposal Generator: dispatches
- Workflow Graph → Proposal Critic: dispatches
- Workflow Graph → Human Review: dispatches
- Workflow Graph → Proposal Persistence: dispatches
- Client Research → Tavily Search: searches
- Client Research → Groq LLM: extracts intelligence
- Case Retrieval → Hybrid Retriever: queries
- Hybrid Retriever → Portfolio Knowledge Base: loads documents
- Human Review → Freelancer Reviewer: requests decision
- Freelancer Reviewer → Lead and Review Routes: submits decision
- Lead and Review Routes → Graph Checkpoints: reads and resumes
- Lead and Review Routes → Workflow Graph: reads status
- Proposal Persistence → Database Session: uses session
- Database Session → Proposal Records: creates tables