How roystondalmeida/multi-agent-research-assistant works
1. Overall shape
- This is a two-tier product: a React/Vite frontend in the repo root and a FastAPI Python backend under backend/.
- The product is a research assistant that accepts a topic, runs an AI-driven workflow, stores results, and shows progress/results back to the user.
2. Frontend boundary
- The frontend is a single-page app built with React + TypeScript + Vite.
- Routing appears page-based (src/pages) with views for auth, dashboard, progress, results, history, settings, password reset, and a not-found fallback.
- src/main.tsx and src/App.tsx likely set up global providers and route layout.
3. Frontend state and integration layer
- src/contexts/AuthContext.tsx manages user/session state.
- src/contexts/ResearchContext.tsx holds research-query state and likely coordinates results/progress across pages.
- src/hooks/useResearch.ts and src/hooks/useRealtimeProgress.ts indicate the frontend subscribes to backend/database updates rather than polling only.
- src/integrations/supabase/client.ts shows Supabase is the browser-side auth/data integration point.
4. Frontend UI composition
- The UI is broken into focused components for each research lifecycle step: query submission, progress, previews, results, sources, perspectives, export, rating, and feedback.
- src/components/ui/* is a large reusable design-system layer, likely shadcn/ui primitives used across the app.
- The visual stack is Tailwind CSS plus component primitives, making the frontend mostly presentation + orchestration over shared UI building blocks.
5. User-facing workflow
- A user signs in, submits a research query, watches real-time progress, and then navigates to a results page with report content, sources, perspectives, export actions, and feedback.
- Dashboard, History, and Settings suggest persisted account-specific research history and user preferences.
6. Backend boundary
- The backend is a FastAPI service that exposes the research API and acts as the orchestration layer for the AI workflow.
- backend/main.py is the entry point, likely defining health and research endpoints described in the README.
- The backend is not a generic CRUD API; its primary job is to authenticate requests, run the workflow, and persist/update research state.
7. Backend workflow orchestration
- backend/services/research_workflow.py is the central orchestration module and is the best place to diagram the multi-step pipeline.
- The README’s agent pipeline maps to backend responsibilities such as browser/search, outline generation, section research, review, writing, and publishing.
- The workflow is likely stateful and iterative, with intermediate progress updates emitted as each stage completes.
8. Backend service boundaries
- auth_service.py handles Supabase-backed request authentication and user context.
- database_service.py centralizes persistence and retrieval of research records, statuses, and history.
- web_search_service.py handles external web discovery/source gathering.
- gemini_service.py encapsulates LLM calls for generation, synthesis, and review.
- content_service.py likely assembles and formats the final report content from workflow outputs.
9. Data model layer
- backend/models/research_models.py defines the backend’s research-related schemas, which are probably used by FastAPI request/response validation and internal workflow state.
- This is an important boundary for diagramming because it separates API payloads from internal workflow data and persisted records.
10. External systems
- Supabase is the key external platform: authentication, database/storage, and real-time updates for the frontend.
- Gemini is the LLM provider used for content generation and analysis.
- Web search is an additional external dependency used by the research workflow to collect sources.
11. Real-time update path
- The architecture suggests the backend writes status/progress to Supabase or a database layer, while the frontend subscribes or refreshes through its realtime hook.
- This creates a clear separation: the frontend does not manage the workflow directly; it observes workflow state updates.
12. Deployment/runtime boundaries
- The repo is designed for a static frontend deployment on Vercel or similar and a separately hosted Python backend.
- vercel.json indicates frontend deployment configuration, while backend/requirements.txt and uvicorn setup indicate a standalone API service runtime.
- Environment variables tie the pieces together: frontend needs Supabase and backend URLs; backend needs Supabase, Gemini, and frontend origin settings.
13. What to emphasize in an architecture diagram
- Draw three main zones: browser UI, FastAPI orchestration backend, and external services (Supabase, Gemini, web search).
- Show the frontend submitting research requests and rendering realtime progress/results.
- Show the backend as the orchestrator between auth, persistence, search, AI generation, and final content publication.
- Show Supabase as both identity and state/history backbone, not just login.
Main entry points: App.tsx App shell · Results.tsx Results page · main.py API entry · research_workflow.py Workflow engine
Components 34
Frontend
React/Vite single-page app, UI, state, and realtime observation layer.
- Entry · Bootstraps the browser app and global providers.
src/main.tsx - App shell · Top-level layout and route composition.
src/App.tsx - Auth state · Manages signed-in user and session state.
src/contexts/AuthContext.tsx - Research state · Coordinates research query, progress, and result state across pages.
src/contexts/ResearchContext.tsx - Research hook · Frontend integration for starting and observing research work.
src/hooks/useResearch.ts - Realtime hook · Subscribes to live progress updates for active research jobs.
src/hooks/useRealtimeProgress.ts - Auth page · Sign-in and account access flows.
src/pages/Auth.tsx - Dashboard · Primary landing view for starting and resuming research.
src/pages/Dashboard.tsx - Progress page · Shows workflow status while research is running.
src/pages/Progress.tsx - Results page · Displays the generated report and supporting material.
src/pages/Results.tsx - History page · Lists prior research runs and saved output.
src/pages/History.tsx - Settings page · Account and app preferences.
src/pages/Settings.tsx - Reset page · Password reset flow.
src/pages/ResetPassword.tsx - Fallback · Route fallback for unknown paths.
src/pages/NotFound.tsx - Research form · Captures the topic and starts the workflow.
src/components/ResearchForm.tsx - Progress tracker · Visualizes the current research stage and completion state.
src/components/ProgressTracker.tsx - Results view · Renders the final report content.
src/components/ResultsDisplay.tsx - Sources view · Shows research sources and citations.
src/components/SourcesDisplay.tsx - Preview view · Surfaces intermediate or draft output.
src/components/PreviewContent.tsx - Perspectives view · Displays alternative viewpoints and analysis angles.
src/components/PerspectivesDisplay.tsx - Export actions · Provides export and sharing actions for finished output.
src/components/ExportActions.tsx - Feedback form · Collects user feedback on the generated research.
src/components/FeedbackForm.tsx - Header · Top-level navigation and account chrome.
src/components/Header.tsx - UI kit · Reusable component primitives used across the interface.
src/components/ui
Backend
FastAPI orchestration service for auth, workflow execution, and persistence.
- API entry · FastAPI application and HTTP endpoint surface.
backend/main.py - Research model · Request, response, and workflow state schemas.
backend/models/research_models.py - Workflow engine · Coordinates the multi-step research pipeline.
backend/services/research_workflow.py - Auth service · Validates Supabase-backed identity and user context.
backend/services/auth_service.py - Database service · Reads and writes research records, status, and history.
backend/services/database_service.py - Search service · Finds external sources and web evidence.
backend/services/web_search_service.py - Gemini service · Wraps LLM calls for synthesis, review, and writing.
backend/services/gemini_service.py - Content service · Assembles and formats the final report payload.
backend/services/content_service.py
External systems
Third-party services used for identity, state, realtime updates, search, and generation.
- Supabase · Identity, persistent state, and realtime backbone.
- Gemini · External model provider for generation and analysis.
Connections 42
- Entry → App shell: boot · Initializes the app shell and providers.
- App shell → Auth state: session · Provides authentication state to the route tree.
- App shell → Research state: research state · Provides research state to pages and widgets.
- App shell → Auth page: routes · Maps route entry points to page views.
- App shell → Dashboard: routes · Maps route entry points to page views.
- App shell → Progress page: routes · Maps route entry points to page views.
- App shell → Results page: routes · Maps route entry points to page views.
- App shell → History page: routes · Maps route entry points to page views.
- App shell → Settings page: routes · Maps route entry points to page views.
- App shell → Reset page: routes · Maps route entry points to page views.
- App shell → Fallback: fallback · Handles unknown routes.
- Dashboard → Research form: start · Lets the user submit a research topic.
- Progress page → Progress tracker: status · Shows live workflow progress.
- Results page → Results view: report · Renders the final answer and sections.
- Results page → Sources view: sources · Shows citations and evidence.
- Results page → Preview view: draft · Surfaces intermediate or partial output.
- Results page → Perspectives view: analysis · Displays alternate viewpoints.
- Results page → Export actions: actions · Exports or shares the finished report.
- Results page → Feedback form: feedback · Collects post-result feedback.
- Dashboard → Header: chrome · Uses shared navigation and account header.
- History page → Header: chrome · Uses shared navigation and account header.
- Settings page → Header: chrome · Uses shared navigation and account header.
- Auth page → Header: chrome · Uses shared navigation and account header.
- Auth state → Supabase: auth · Reads and manages session state through Supabase.
- Research hook → API entry: API · Starts research jobs and fetches workflow state.
- Realtime hook → Supabase: realtime · Consumes live updates for running research.
- Realtime hook → API entry: status · Aligns UI progress with backend-managed job state.
- Research state → Research hook: orchestrate · Coordinates query submission and result lifecycle.
- Research state → Realtime hook: observe · Tracks live completion and stage changes.
- API entry → Research model: validate · Uses schemas for API and workflow payloads.
- API entry → Auth service: protect · Authenticates incoming requests.
- API entry → Workflow engine: run · Delegates research execution to the workflow engine.
- API entry → Database service: persist · Stores and retrieves research records.
- Workflow engine → Search service: discover · Collects web sources and evidence.
- Workflow engine → Gemini service: generate · Uses the LLM for synthesis and writing.
- Workflow engine → Content service: assemble · Builds the final report payload.
- Workflow engine → Database service: update · Emits progress and persists stage results.
- Auth service → Supabase: verify · Validates user identity through Supabase.
- Database service → Supabase: store · Persists research state, history, and updates.
- Search service → Supabase: optional state · May record source-related metadata or job state.
- Gemini service → Gemini: invoke · Calls the external model provider.
- Content service → Research model: shape · Formats output according to research schemas.