# vamsikrishna0101/vendoriq architecture

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

- Interactive diagram: https://gitdiagram.com/vamsikrishna0101/vendoriq
- Repository: https://github.com/vamsikrishna0101/vendoriq

## Overview

1. **Overall shape**
   VendorIQ is split into a **React frontend** and a **FastAPI/Python backend**. The backend is the system of record and orchestration layer; the frontend is a live debate viewer and control surface for uploads, session browsing, and verdict inspection.

2. **Primary user flow**
   The main pipeline is: **upload vendor PDFs → extract structured intelligence → run a multi-round agent debate → stream progress to the UI → persist the full session and events in PostgreSQL**. The architecture is built around replayability, so debate outputs are stored as events rather than only as a final summary.

3. **API boundary**
   `Backend/main.py` is the backend entrypoint, with routers split by responsibility:
   - `auth_router.py` for user/session authentication
   - `upload_router.py` for document ingestion
   - `debate_router.py` for starting and observing debate sessions  
   This keeps transport/API concerns separate from the debate logic itself.

4. **Document ingestion and intelligence extraction**
   Uploads are handled by `services/upload_service.py`, then processed by `services/extract_data_service.py`. The extracted output is stored as structured **Intelligence** records rather than raw PDFs being passed into the debate layer. This is an important boundary: the debate agents consume curated domain data, not original documents.

5. **LLM integration**
   `services/gemini_service.py` wraps the Gemini model calls. It is the single integration point to the external LLM provider, which makes model access reusable across analysts, decision agents, customer agents, and the moderator.

6. **Debate orchestration**
   The core reasoning engine lives in `graph/debate_graph.py`, `graph/graph.py`, and `state/debate_state.py`. This is where LangGraph-style stateful orchestration likely routes the session through phases/rounds, carries agent outputs forward, and coordinates the final synthesis. The graph is the central backbone of the system.

7. **Agent layer**
   The repo separates agent definitions from execution:
   - `Backend/Agents/*_agents.py` define the roles/personas
   - `Backend/nodes/*_node.py` implement the runtime behavior for each agent group
   - `Backend/prompts/*_prompt.py` and `context_builder.py` define what each agent is allowed to see and how it responds  
   The architecture uses specialized agent families: analyst, decision, customer, adversarial, and moderator. This role-based split is key to the product’s “boardroom debate” model.

8. **Streaming and live debate UI**
   `services/streaming_service.py` and `services/session_event_bus.py` indicate an event-driven streaming path from backend to frontend. The UI is designed to receive incremental debate output, not just final responses, which matches the live-agent cards, timelines, and transition components under `frontend/src/components/debate`.

9. **Persistence and replay**
   Database models in `Backend/models/` include `User`, `DebateSession`, `DebateEvent`, and `Intelligence`. This suggests a normalized storage model:
   - users/auth identity
   - uploaded/intelligence artifacts
   - debate sessions as top-level containers
   - event history for replay and audit  
   `utils/db.py` provides the DB connection layer, and the README indicates PostgreSQL is used to enable full session replay without rerunning Gemini.

10. **Frontend structure**
    The frontend is organized by workflow pages: `Auth`, `Home`, `Generate`, `Debate`, `Sessions`, and `Settings`. Shared layout lives in `components/layout`, upload handling in `components/upload`, and debate visualization in `components/debate`. `contexts/AuthContext.tsx` suggests app-wide auth state, while `api.ts` is the single client boundary to the backend.

11. **Cross-cutting concerns**
    Authentication is isolated in `Backend/utils/auth.py`, and the app appears to be designed around session-based access to debates. The presence of `Procfile`, `Dockerfile`, `runtime.txt`, and `requirements.txt` indicates a deployable backend service, while the frontend is a standard Vite/React app.

12. **Validation and support artifacts**
    `Backend/tests/` contains extraction and Gemini tests plus sample documents, showing the most important backend contract is the quality of document parsing and model behavior. `demo_files/` and `local_backup.sql` support local demos and seeded data, reinforcing that the app is centered on reproducible vendor-debate sessions.

Main entry points: [`frontend/src/components/layout/AppLayout.tsx`](https://github.com/vamsikrishna0101/vendoriq/blob/main/frontend/src/components/layout/AppLayout.tsx) (App layout), [`Backend/graph/debate_graph.py`](https://github.com/vamsikrishna0101/vendoriq/blob/main/Backend/graph/debate_graph.py) (Debate graph), [`frontend/src/pages/Debate/DebatePage.tsx`](https://github.com/vamsikrishna0101/vendoriq/blob/main/frontend/src/pages/Debate/DebatePage.tsx) (Debate page), [`Backend/main.py`](https://github.com/vamsikrishna0101/vendoriq/blob/main/Backend/main.py) (API app)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_backend["Backend"]
  node_main["API app<br/>FastAPI entrypoint<br/>[main.py]"]
  node_auth_router["Auth API<br/>route layer<br/>[auth_router.py]"]
  node_upload_router["Upload API<br/>route layer<br/>[upload_router.py]"]
  node_debate_router["Debate API<br/>route layer<br/>[debate_router.py]"]
  node_upload_service["Upload service<br/>ingestion service<br/>[upload_service.py]"]
  node_extract_service["Extract data<br/>parsing service"]
  node_intelligence[("Intelligence<br/>domain model<br/>[Intelligence.py]")]
  node_debate_graph["Debate graph<br/>orchestrator<br/>[debate_graph.py]"]
  node_graph_core["Graph core<br/>workflow engine<br/>[graph.py]"]
  node_debate_state["Debate state<br/>state schema<br/>[debate_state.py]"]
  node_gemini_service["Gemini service<br/>llm adapter<br/>[gemini_service.py]"]
  node_session_bus["Event bus<br/>streaming bus"]
  node_streaming_service["Streaming"]
  node_session_model[("Debate session<br/>session model<br/>[DebateSession.py]")]
  node_event_model[("Debate event<br/>event model<br/>[DebateEvent.py]")]
  node_db[("PostgreSQL<br/>db layer<br/>[db.py]")]
  node_agents["Agent roles<br/>persona layer"]
  node_nodes["Agent nodes<br/>runtime nodes"]
  node_prompts["Prompts<br/>prompt layer"]
end

subgraph group_frontend["Frontend"]
  node_api_client["API client<br/>frontend api<br/>[api.ts]"]
  node_auth_context["Auth context<br/>react state<br/>[AuthContext.tsx]"]
  node_app_layout["App layout<br/>ui shell<br/>[AppLayout.tsx]"]
  node_upload_zone["Upload zone<br/>ui component<br/>[UploadZone.tsx]"]
  node_debate_ui["Debate view<br/>ui components"]
  node_auth_page["Auth page<br/>screen<br/>[AuthPage.tsx]"]
  node_generate_page["Generate page<br/>screen<br/>[GeneratePage.tsx]"]
  node_home_page["Home page<br/>screen<br/>[HomePage.tsx]"]
  node_debate_page["Debate page<br/>screen<br/>[DebatePage.tsx]"]
  node_verdict_screen["Verdict screen<br/>[VerdictScreen.tsx]"]
  node_sessions_page["Sessions page<br/>screen<br/>[SessionsPage.tsx]"]
  node_settings_page["Settings page<br/>screen<br/>[SettingsPage.tsx]"]
end

node_main -->|"mounts"| node_auth_router
node_main -->|"mounts"| node_upload_router
node_main -->|"mounts"| node_debate_router
node_upload_router -->|"calls"| node_upload_service
node_upload_service -->|"parses"| node_extract_service
node_extract_service -->|"produces"| node_intelligence
node_debate_router -->|"starts"| node_debate_graph
node_debate_graph -->|"builds on"| node_graph_core
node_debate_graph -->|"updates"| node_debate_state
node_debate_graph -->|"coordinates"| node_agents
node_agents -->|"executes via"| node_nodes
node_nodes -->|"uses"| node_prompts
node_nodes -->|"calls"| node_gemini_service
node_prompts -->|"consumes"| node_intelligence
node_gemini_service -->|"emits"| node_session_bus
node_session_bus -->|"feeds"| node_streaming_service
node_streaming_service -->|"persists"| node_event_model
node_streaming_service -->|"updates"| node_session_model
node_event_model -->|"stored in"| node_db
node_session_model -->|"stored in"| node_db
node_auth_router -->|"reads/writes"| node_db
node_api_client -->|"drives"| node_auth_page
node_api_client -->|"drives"| node_upload_zone
node_api_client -->|"drives"| node_debate_page
node_auth_context -->|"wraps"| node_app_layout
node_app_layout -->|"hosts"| node_home_page
node_app_layout -->|"hosts"| node_generate_page
node_app_layout -->|"hosts"| node_debate_page
node_app_layout -->|"hosts"| node_sessions_page
node_debate_page -->|"renders"| node_debate_ui
node_debate_page -->|"shows"| node_verdict_screen
node_home_page -->|"launches"| node_upload_zone
node_settings_page -->|"uses"| node_auth_context

click node_main "https://github.com/vamsikrishna0101/vendoriq/blob/main/Backend/main.py"
click node_auth_router "https://github.com/vamsikrishna0101/vendoriq/blob/main/Backend/routers/auth_router.py"
click node_upload_router "https://github.com/vamsikrishna0101/vendoriq/blob/main/Backend/routers/upload_router.py"
click node_debate_router "https://github.com/vamsikrishna0101/vendoriq/blob/main/Backend/routers/debate_router.py"
click node_upload_service "https://github.com/vamsikrishna0101/vendoriq/blob/main/Backend/services/upload_service.py"
click node_extract_service "https://github.com/vamsikrishna0101/vendoriq/blob/main/Backend/services/extract_data_service.py"
click node_intelligence "https://github.com/vamsikrishna0101/vendoriq/blob/main/Backend/models/Intelligence.py"
click node_debate_graph "https://github.com/vamsikrishna0101/vendoriq/blob/main/Backend/graph/debate_graph.py"
click node_graph_core "https://github.com/vamsikrishna0101/vendoriq/blob/main/Backend/graph/graph.py"
click node_debate_state "https://github.com/vamsikrishna0101/vendoriq/blob/main/Backend/state/debate_state.py"
click node_gemini_service "https://github.com/vamsikrishna0101/vendoriq/blob/main/Backend/services/gemini_service.py"
click node_session_bus "https://github.com/vamsikrishna0101/vendoriq/blob/main/Backend/services/session_event_bus.py"
click node_streaming_service "https://github.com/vamsikrishna0101/vendoriq/blob/main/Backend/services/streaming_service.py"
click node_session_model "https://github.com/vamsikrishna0101/vendoriq/blob/main/Backend/models/DebateSession.py"
click node_event_model "https://github.com/vamsikrishna0101/vendoriq/blob/main/Backend/models/DebateEvent.py"
click node_db "https://github.com/vamsikrishna0101/vendoriq/blob/main/Backend/utils/db.py"
click node_agents "https://github.com/vamsikrishna0101/vendoriq/tree/main/Backend/Agents"
click node_nodes "https://github.com/vamsikrishna0101/vendoriq/tree/main/Backend/nodes"
click node_prompts "https://github.com/vamsikrishna0101/vendoriq/tree/main/Backend/prompts"
click node_api_client "https://github.com/vamsikrishna0101/vendoriq/blob/main/frontend/src/api.ts"
click node_auth_context "https://github.com/vamsikrishna0101/vendoriq/blob/main/frontend/src/contexts/AuthContext.tsx"
click node_app_layout "https://github.com/vamsikrishna0101/vendoriq/blob/main/frontend/src/components/layout/AppLayout.tsx"
click node_upload_zone "https://github.com/vamsikrishna0101/vendoriq/blob/main/frontend/src/components/upload/UploadZone.tsx"
click node_debate_ui "https://github.com/vamsikrishna0101/vendoriq/tree/main/frontend/src/components/debate"
click node_auth_page "https://github.com/vamsikrishna0101/vendoriq/blob/main/frontend/src/pages/Auth/AuthPage.tsx"
click node_generate_page "https://github.com/vamsikrishna0101/vendoriq/blob/main/frontend/src/pages/Generate/GeneratePage.tsx"
click node_home_page "https://github.com/vamsikrishna0101/vendoriq/blob/main/frontend/src/pages/Home/HomePage.tsx"
click node_debate_page "https://github.com/vamsikrishna0101/vendoriq/blob/main/frontend/src/pages/Debate/DebatePage.tsx"
click node_verdict_screen "https://github.com/vamsikrishna0101/vendoriq/blob/main/frontend/src/pages/Debate/VerdictScreen.tsx"
click node_sessions_page "https://github.com/vamsikrishna0101/vendoriq/blob/main/frontend/src/pages/Sessions/SessionsPage.tsx"
click node_settings_page "https://github.com/vamsikrishna0101/vendoriq/blob/main/frontend/src/pages/Settings/SettingsPage.tsx"

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_main,node_auth_router,node_upload_router,node_debate_router,node_upload_service,node_extract_service,node_intelligence,node_debate_graph,node_graph_core,node_debate_state,node_gemini_service,node_session_bus,node_streaming_service,node_session_model,node_event_model,node_db,node_agents,node_nodes,node_prompts toneBlue
class node_api_client,node_auth_context,node_app_layout,node_upload_zone,node_debate_ui,node_auth_page,node_generate_page,node_home_page,node_debate_page,node_verdict_screen,node_sessions_page,node_settings_page toneAmber
```

## Components

### Backend

FastAPI service for ingestion, orchestration, persistence, and streaming

- [API app](https://github.com/vamsikrishna0101/vendoriq/blob/main/Backend/main.py): FastAPI entrypoint · Backend application bootstrap and router wiring · `Backend/main.py`
- [Auth API](https://github.com/vamsikrishna0101/vendoriq/blob/main/Backend/routers/auth_router.py): route layer · Authentication and session access endpoints · `Backend/routers/auth_router.py`
- [Upload API](https://github.com/vamsikrishna0101/vendoriq/blob/main/Backend/routers/upload_router.py): route layer · Document ingestion endpoints · `Backend/routers/upload_router.py`
- [Debate API](https://github.com/vamsikrishna0101/vendoriq/blob/main/Backend/routers/debate_router.py): route layer · Debate session start and observation endpoints · `Backend/routers/debate_router.py`
- [Upload service](https://github.com/vamsikrishna0101/vendoriq/blob/main/Backend/services/upload_service.py): ingestion service · Coordinates file intake and initial processing · `Backend/services/upload_service.py`
- [Extract data](https://github.com/vamsikrishna0101/vendoriq/blob/main/Backend/services/extract_data_service.py): parsing service · Converts vendor documents into structured intelligence · `Backend/services/extract_data_service.py`
- [Intelligence](https://github.com/vamsikrishna0101/vendoriq/blob/main/Backend/models/Intelligence.py): domain model · Structured vendor facts consumed by the debate layer · `Backend/models/Intelligence.py`
- [Debate graph](https://github.com/vamsikrishna0101/vendoriq/blob/main/Backend/graph/debate_graph.py): orchestrator · Stateful debate workflow and phase routing · `Backend/graph/debate_graph.py`
- [Graph core](https://github.com/vamsikrishna0101/vendoriq/blob/main/Backend/graph/graph.py): workflow engine · Shared graph composition and execution helpers · `Backend/graph/graph.py`
- [Debate state](https://github.com/vamsikrishna0101/vendoriq/blob/main/Backend/state/debate_state.py): state schema · Session state carried across rounds and agents · `Backend/state/debate_state.py`
- [Gemini service](https://github.com/vamsikrishna0101/vendoriq/blob/main/Backend/services/gemini_service.py): llm adapter · Single integration point for model calls · `Backend/services/gemini_service.py`
- [Event bus](https://github.com/vamsikrishna0101/vendoriq/blob/main/Backend/services/session_event_bus.py): streaming bus · Publishes debate progress and session events · `Backend/services/session_event_bus.py`
- [Streaming](https://github.com/vamsikrishna0101/vendoriq/blob/main/Backend/services/streaming_service.py): streaming service · Pushes incremental debate output to clients · `Backend/services/streaming_service.py`
- [Debate session](https://github.com/vamsikrishna0101/vendoriq/blob/main/Backend/models/DebateSession.py): session model · Top-level container for a debate run · `Backend/models/DebateSession.py`
- [Debate event](https://github.com/vamsikrishna0101/vendoriq/blob/main/Backend/models/DebateEvent.py): event model · Append-only history used for replay and audit · `Backend/models/DebateEvent.py`
- [PostgreSQL](https://github.com/vamsikrishna0101/vendoriq/blob/main/Backend/utils/db.py): db layer · Persistence connection and storage boundary · `Backend/utils/db.py`
- [Agent roles](https://github.com/vamsikrishna0101/vendoriq/tree/main/Backend/Agents): persona layer · Role definitions for analyst, decision, customer, adversarial, and moderator agents · `Backend/Agents`
- [Agent nodes](https://github.com/vamsikrishna0101/vendoriq/tree/main/Backend/nodes): runtime nodes · Execution logic for each agent family · `Backend/nodes`
- [Prompts](https://github.com/vamsikrishna0101/vendoriq/tree/main/Backend/prompts): prompt layer · Role prompts and shared context construction · `Backend/prompts`

### Frontend

React app for uploads, session browsing, and live debate viewing

- [API client](https://github.com/vamsikrishna0101/vendoriq/blob/main/frontend/src/api.ts): frontend api · Frontend boundary for backend calls · `frontend/src/api.ts`
- [Auth context](https://github.com/vamsikrishna0101/vendoriq/blob/main/frontend/src/contexts/AuthContext.tsx): react state · App-wide authentication state · `frontend/src/contexts/AuthContext.tsx`
- [App layout](https://github.com/vamsikrishna0101/vendoriq/blob/main/frontend/src/components/layout/AppLayout.tsx): ui shell · Shared navigation and page chrome · `frontend/src/components/layout/AppLayout.tsx`
- [Upload zone](https://github.com/vamsikrishna0101/vendoriq/blob/main/frontend/src/components/upload/UploadZone.tsx): ui component · Document upload control for vendor files · `frontend/src/components/upload/UploadZone.tsx`
- [Debate view](https://github.com/vamsikrishna0101/vendoriq/tree/main/frontend/src/components/debate): ui components · Live debate cards, timelines, transitions, and insight panels · `frontend/src/components/debate`
- [Auth page](https://github.com/vamsikrishna0101/vendoriq/blob/main/frontend/src/pages/Auth/AuthPage.tsx): screen · Login and access entry screen · `frontend/src/pages/Auth/AuthPage.tsx`
- [Generate page](https://github.com/vamsikrishna0101/vendoriq/blob/main/frontend/src/pages/Generate/GeneratePage.tsx): screen · Session creation and analysis trigger screen · `frontend/src/pages/Generate/GeneratePage.tsx`
- [Home page](https://github.com/vamsikrishna0101/vendoriq/blob/main/frontend/src/pages/Home/HomePage.tsx): screen · Primary landing and workflow entry point · `frontend/src/pages/Home/HomePage.tsx`
- [Debate page](https://github.com/vamsikrishna0101/vendoriq/blob/main/frontend/src/pages/Debate/DebatePage.tsx): screen · Live session viewer and control surface · `frontend/src/pages/Debate/DebatePage.tsx`
- [Verdict screen](https://github.com/vamsikrishna0101/vendoriq/blob/main/frontend/src/pages/Debate/VerdictScreen.tsx): screen · Final synthesis and decision display · `frontend/src/pages/Debate/VerdictScreen.tsx`
- [Sessions page](https://github.com/vamsikrishna0101/vendoriq/blob/main/frontend/src/pages/Sessions/SessionsPage.tsx): screen · Browse and replay prior debate sessions · `frontend/src/pages/Sessions/SessionsPage.tsx`
- [Settings page](https://github.com/vamsikrishna0101/vendoriq/blob/main/frontend/src/pages/Settings/SettingsPage.tsx): screen · User and application settings · `frontend/src/pages/Settings/SettingsPage.tsx`

## Connections

- API app → Auth API: mounts · Registers authentication routes
- API app → Upload API: mounts · Registers upload routes
- API app → Debate API: mounts · Registers debate routes
- Upload API → Upload service: calls · Hands off file ingestion work
- Upload service → Extract data: parses · Extracts structured data from documents
- Extract data → Intelligence: produces · Creates curated intelligence records
- Debate API → Debate graph: starts · Triggers debate sessions and observation
- Debate graph → Graph core: builds on · Uses shared orchestration helpers
- Debate graph → Debate state: updates · Carries phase and round state forward
- Debate graph → Agent roles: coordinates · Routes work across role personas
- Agent roles → Agent nodes: executes via · Agent personas are implemented by runtime nodes
- Agent nodes → Prompts: uses · Nodes prepare role-specific context and instructions
- Agent nodes → Gemini service: calls · Runtime node behavior invokes the LLM adapter
- Prompts → Intelligence: consumes · Prompts are grounded in structured vendor intelligence
- Gemini service → Event bus: emits · Model progress and results are published as events
- Event bus → Streaming: feeds · Streaming layer relays event updates to clients
- Streaming → Debate event: persists · Debate activity is stored as replayable events
- Streaming → Debate session: updates · Maintains the current session container
- Debate event → PostgreSQL: stored in · Append-only event history lives in PostgreSQL
- Debate session → PostgreSQL: stored in · Session records live in PostgreSQL
- Auth API → PostgreSQL: reads/writes · Authentication state and user records use the database
- API client → Auth page: drives · Frontend auth flows use the API boundary
- API client → Upload zone: drives · Uploads are sent through the backend API
- API client → Debate page: drives · Live debate views subscribe through the API boundary
- Auth context → App layout: wraps · Auth state supports application shell behavior
- App layout → Home page: hosts · Shared shell frames the main workflow screens
- App layout → Generate page: hosts · Shared shell frames the main workflow screens
- App layout → Debate page: hosts · Shared shell frames the live debate experience
- App layout → Sessions page: hosts · Shared shell frames session browsing
- Debate page → Debate view: renders · Live debate screen is built from specialized components
- Debate page → Verdict screen: shows · Final outcome is displayed after the debate concludes
- Home page → Upload zone: launches · Home workflow exposes document upload
- Settings page → Auth context: uses · Settings depend on authenticated user state
