How vamsikrishna0101/vendoriq works
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: AppLayout.tsx App layout · debate_graph.py Debate graph · DebatePage.tsx Debate page · main.py API app
Components 31
Backend
FastAPI service for ingestion, orchestration, persistence, and streaming
- API app · Backend application bootstrap and router wiring
Backend/main.py - Auth API · Authentication and session access endpoints
Backend/routers/auth_router.py - Upload API · Document ingestion endpoints
Backend/routers/upload_router.py - Debate API · Debate session start and observation endpoints
Backend/routers/debate_router.py - Upload service · Coordinates file intake and initial processing
Backend/services/upload_service.py - Extract data · Converts vendor documents into structured intelligence
Backend/services/extract_data_service.py - Intelligence · Structured vendor facts consumed by the debate layer
Backend/models/Intelligence.py - Debate graph · Stateful debate workflow and phase routing
Backend/graph/debate_graph.py - Graph core · Shared graph composition and execution helpers
Backend/graph/graph.py - Debate state · Session state carried across rounds and agents
Backend/state/debate_state.py - Gemini service · Single integration point for model calls
Backend/services/gemini_service.py - Event bus · Publishes debate progress and session events
Backend/services/session_event_bus.py - Streaming · Pushes incremental debate output to clients
Backend/services/streaming_service.py - Debate session · Top-level container for a debate run
Backend/models/DebateSession.py - Debate event · Append-only history used for replay and audit
Backend/models/DebateEvent.py - PostgreSQL · Persistence connection and storage boundary
Backend/utils/db.py - Agent roles · Role definitions for analyst, decision, customer, adversarial, and moderator agents
Backend/Agents - Agent nodes · Execution logic for each agent family
Backend/nodes - Prompts · Role prompts and shared context construction
Backend/prompts
Frontend
React app for uploads, session browsing, and live debate viewing
- API client · Frontend boundary for backend calls
frontend/src/api.ts - Auth context · App-wide authentication state
frontend/src/contexts/AuthContext.tsx - App layout · Shared navigation and page chrome
frontend/src/components/layout/AppLayout.tsx - Upload zone · Document upload control for vendor files
frontend/src/components/upload/UploadZone.tsx - Debate view · Live debate cards, timelines, transitions, and insight panels
frontend/src/components/debate - Auth page · Login and access entry screen
frontend/src/pages/Auth/AuthPage.tsx - Generate page · Session creation and analysis trigger screen
frontend/src/pages/Generate/GeneratePage.tsx - Home page · Primary landing and workflow entry point
frontend/src/pages/Home/HomePage.tsx - Debate page · Live session viewer and control surface
frontend/src/pages/Debate/DebatePage.tsx - Verdict screen · Final synthesis and decision display
frontend/src/pages/Debate/VerdictScreen.tsx - Sessions page · Browse and replay prior debate sessions
frontend/src/pages/Sessions/SessionsPage.tsx - Settings page · User and application settings
frontend/src/pages/Settings/SettingsPage.tsx
Connections 33
- 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