# akash5467/meeting-agent architecture

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

- Interactive diagram: https://gitdiagram.com/akash5467/meeting-agent
- Repository: https://github.com/akash5467/meeting-agent

## Overview

1. **Repository shape**
   - This is a two-tier system: a Python backend in `backend/` and a React/TypeScript frontend in `frontend/`.
   - The backend owns ingestion, research, persistence, and live update fan-out. The frontend is a read-only dashboard for authenticated users.

2. **Primary backend boundary**
   - The backend is a FastAPI service (`backend/app/main.py`) with supporting modules for database access, calendar polling, parsing, websocket broadcasting, and AI orchestration.
   - It is not just an API server; it also runs a background monitoring loop that continuously processes upcoming meetings.

3. **Calendar ingestion pipeline**
   - `calendar_listener.py` polls Google Calendar on a fixed interval, described in the README as every 60 seconds.
   - The listener is the entry point for meeting data. It pulls upcoming events, then hands them to the parser and downstream workflow.
   - This makes the system event-driven at the application level even though the source is polled rather than webhook-based.

4. **Company identification and gating**
   - `parser.py` extracts the company associated with a meeting using a priority order: title first, then attendee emails, then description.
   - This module defines a major architectural boundary: meetings with an identifiable company enter the research pipeline; meetings without one are stored with a fallback “no_company” state and still shown gracefully.

5. **Research subsystem**
   - `backend/agent/` is the intelligence engine. It is split into specialist agents and a synthesis layer.
   - The sub-agents are:
     - `news_agent.py` for recent company/news context
     - `tech_agent.py` for technology stack or technical signals
     - `pain_point_agent.py` for likely business pain points
   - `synthesis_agent.py` combines those outputs into the final structured brief.

6. **Tooling and external research APIs**
   - The agent layer uses explicit tools in `backend/agent/tools/`.
   - `web_search.py` and `tech_lookup.py` wrap external research providers, specifically Serper for search/news-style lookup and Exa for semantic company research.
   - The agent boundary is important: sub-agents do not appear to access the internet directly; they operate through these tool abstractions.

7. **Orchestration model**
   - `orchestrator.py` coordinates the end-to-end research flow.
   - The README indicates the three specialist agents run in parallel and then feed a synthesis step, which is the key execution pattern for the architecture diagram.
   - This is the main “brains” layer: calendar event in, structured brief out.

8. **Persistence layer**
   - `database.py` and `models.py` define the storage boundary, backed by PostgreSQL/Cloud SQL.
   - The database stores meetings, research outputs, and status needed for the dashboard.
   - The app uses persistence not only for final briefs but also for lifecycle states such as pending, done, and no_company.

9. **Live update delivery**
   - `websocket_manager.py` handles push updates from the backend to connected clients.
   - The README calls out a WebSocket broadcast model so the dashboard updates immediately when research completes, rather than polling the API.
   - This is the key UI synchronization mechanism and an important diagram boundary between backend state changes and frontend rendering.

10. **Frontend structure**
   - The frontend is a Vite React app with TypeScript and Tailwind CSS.
   - `App.tsx` and the components under `src/components/` render the login screen, meeting list cards, skeleton/loading states, and the full brief detail view.
   - The UI is organized around meeting cards and a detail page, reflecting the backend’s meeting-centric data model.

11. **Frontend data access and auth**
   - `useLiveMeetings.ts` is the live data hook, likely consuming the backend’s WebSocket updates and current meeting state.
   - `useAuth.ts` gates access via Google Sign-In and an email allowlist, so the dashboard is restricted to approved accounts.
   - This makes the frontend both an auth boundary and a presentation layer, but not a source of business logic.

12. **Deployment/runtime considerations**
   - The backend is containerized with Docker and designed for Cloud Run, with Cloud SQL for PostgreSQL.
   - The README explicitly notes `min-instances 1` on Cloud Run to keep the polling loop alive, which is an important operational constraint.
   - The frontend is intended for static hosting on Vercel.

13. **External service dependencies**
   - Google Calendar API supplies meeting data.
   - Google OAuth provides both Calendar access on the backend and Sign-In on the frontend.
   - Gemini 2.5 Flash powers synthesis and AI-agent reasoning; Serper and Exa provide the research substrate.
   - These external services are central to the architecture, not incidental integrations.

14. **End-to-end data flow**
   - The simplest way to draw the system: Google Calendar → polling listener → company parser → parallel research agents → synthesis agent → PostgreSQL → WebSocket broadcast → React dashboard.
   - The major branching point is company identification: identifiable meetings are researched; unidentifiable ones are stored and surfaced as a graceful fallback.

Main entry points: [`backend/agent/orchestrator.py`](https://github.com/akash5467/meeting-agent/blob/main/backend/agent/orchestrator.py) (Orchestrator), [`backend/app/main.py`](https://github.com/akash5467/meeting-agent/blob/main/backend/app/main.py) (FastAPI app), [`backend/agent/agents/synthesis_agent.py`](https://github.com/akash5467/meeting-agent/blob/main/backend/agent/agents/synthesis_agent.py) (Synthesis agent), [`backend/app/database.py`](https://github.com/akash5467/meeting-agent/blob/main/backend/app/database.py) (Database)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_backend["Backend"]
  node_backend_main["FastAPI app<br/>api/runtime<br/>[main.py]"]
  node_calendar_listener["Calendar listener<br/>polling ingest"]
  node_parser["Company parser<br/>meeting classifier<br/>[parser.py]"]
  node_orchestrator["Orchestrator<br/>workflow engine<br/>[orchestrator.py]"]
  node_news_agent["News agent<br/>research agent<br/>[news_agent.py]"]
  node_tech_agent["Tech agent<br/>research agent<br/>[tech_agent.py]"]
  node_pain_point_agent["Pain agent<br/>research agent"]
  node_synthesis_agent["Synthesis agent<br/>brief builder<br/>[synthesis_agent.py]"]
  node_web_search["Web search<br/>research tool<br/>[web_search.py]"]
  node_tech_lookup["Tech lookup<br/>research tool<br/>[tech_lookup.py]"]
  node_database[("Database<br/>persistence<br/>[database.py]")]
  node_models["Data models<br/>schema<br/>[models.py]"]
  node_websocket_manager["WebSocket hub<br/>realtime fan-out"]
end

subgraph group_frontend["Frontend"]
  node_frontend_app["React app<br/>ui shell<br/>[App.tsx]"]
  node_use_auth["Auth hook<br/>access control<br/>[useAuth.ts]"]
  node_use_live_meetings["Live meetings<br/>data hook<br/>[useLiveMeetings.ts]"]
  node_meeting_ui["Meeting UI<br/>presentation"]
end

subgraph group_external["External services"]
  node_google_calendar(("Google Calendar<br/>calendar api"))
  node_google_oauth(("Google OAuth<br/>identity"))
  node_gemini(("Gemini<br/>llm"))
  node_serper_exa(("Serper + Exa<br/>research providers"))
  node_postgres[("PostgreSQL<br/>database service")]
end

node_backend_main -->|"start loop"| node_calendar_listener
node_backend_main -->|"serve state"| node_database
node_backend_main -->|"broadcast"| node_websocket_manager
node_calendar_listener -->|"poll"| node_google_calendar
node_calendar_listener -->|"new meeting"| node_parser
node_parser -->|"identify company"| node_orchestrator
node_parser -->|"no_company"| node_database
node_orchestrator -->|"parallel run"| node_news_agent
node_orchestrator -->|"parallel run"| node_tech_agent
node_orchestrator -->|"parallel run"| node_pain_point_agent
node_news_agent -->|"tool use"| node_web_search
node_tech_agent -->|"tool use"| node_tech_lookup
node_pain_point_agent -->|"tool use"| node_web_search
node_web_search -->|"query"| node_serper_exa
node_tech_lookup -->|"research"| node_serper_exa
node_news_agent -->|"reason"| node_gemini
node_tech_agent -->|"reason"| node_gemini
node_pain_point_agent -->|"reason"| node_gemini
node_orchestrator -->|"merge"| node_synthesis_agent
node_synthesis_agent -->|"compose"| node_gemini
node_synthesis_agent -->|"persist brief"| node_database
node_database -->|"store"| node_postgres
node_synthesis_agent -->|"notify"| node_websocket_manager
node_websocket_manager -->|"push updates"| node_use_live_meetings
node_frontend_app -->|"gate access"| node_use_auth
node_frontend_app -->|"load live state"| node_use_live_meetings
node_frontend_app -->|"render"| node_meeting_ui
node_use_auth -->|"sign in"| node_google_oauth
node_backend_main -->|"calendar auth"| node_google_oauth

click node_backend_main "https://github.com/akash5467/meeting-agent/blob/main/backend/app/main.py"
click node_calendar_listener "https://github.com/akash5467/meeting-agent/blob/main/backend/app/calendar_listener.py"
click node_parser "https://github.com/akash5467/meeting-agent/blob/main/backend/app/parser.py"
click node_orchestrator "https://github.com/akash5467/meeting-agent/blob/main/backend/agent/orchestrator.py"
click node_news_agent "https://github.com/akash5467/meeting-agent/blob/main/backend/agent/agents/news_agent.py"
click node_tech_agent "https://github.com/akash5467/meeting-agent/blob/main/backend/agent/agents/tech_agent.py"
click node_pain_point_agent "https://github.com/akash5467/meeting-agent/blob/main/backend/agent/agents/pain_point_agent.py"
click node_synthesis_agent "https://github.com/akash5467/meeting-agent/blob/main/backend/agent/agents/synthesis_agent.py"
click node_web_search "https://github.com/akash5467/meeting-agent/blob/main/backend/agent/tools/web_search.py"
click node_tech_lookup "https://github.com/akash5467/meeting-agent/blob/main/backend/agent/tools/tech_lookup.py"
click node_database "https://github.com/akash5467/meeting-agent/blob/main/backend/app/database.py"
click node_models "https://github.com/akash5467/meeting-agent/blob/main/backend/app/models.py"
click node_websocket_manager "https://github.com/akash5467/meeting-agent/blob/main/backend/app/websocket_manager.py"
click node_frontend_app "https://github.com/akash5467/meeting-agent/blob/main/frontend/src/App.tsx"
click node_use_auth "https://github.com/akash5467/meeting-agent/blob/main/frontend/src/hooks/useAuth.ts"
click node_use_live_meetings "https://github.com/akash5467/meeting-agent/blob/main/frontend/src/hooks/useLiveMeetings.ts"
click node_meeting_ui "https://github.com/akash5467/meeting-agent/blob/main/frontend/src/components/MeetingDetailPage.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_backend_main,node_calendar_listener,node_parser,node_orchestrator,node_news_agent,node_tech_agent,node_pain_point_agent,node_synthesis_agent,node_web_search,node_tech_lookup,node_database,node_models,node_websocket_manager toneBlue
class node_frontend_app,node_use_auth,node_use_live_meetings,node_meeting_ui toneAmber
class node_google_calendar,node_google_oauth,node_gemini,node_serper_exa,node_postgres toneMint
```

## Components

### Backend

FastAPI service, background polling, research orchestration, persistence, and realtime fan-out.

- [FastAPI app](https://github.com/akash5467/meeting-agent/blob/main/backend/app/main.py): api/runtime · HTTP entrypoint that also starts the background monitoring loop. · `backend/app/main.py`
- [Calendar listener](https://github.com/akash5467/meeting-agent/blob/main/backend/app/calendar_listener.py): polling ingest · Polls Google Calendar on an interval and hands meetings into the processing flow. · `backend/app/calendar_listener.py`
- [Company parser](https://github.com/akash5467/meeting-agent/blob/main/backend/app/parser.py): meeting classifier · Extracts the company from meeting title, attendees, or description and routes no-company fallbacks. · `backend/app/parser.py`
- [Orchestrator](https://github.com/akash5467/meeting-agent/blob/main/backend/agent/orchestrator.py): workflow engine · Coordinates the parallel research agents and synthesis step for each meeting. · `backend/agent/orchestrator.py`
- [News agent](https://github.com/akash5467/meeting-agent/blob/main/backend/agent/agents/news_agent.py): research agent · Finds recent company and market context. · `backend/agent/agents/news_agent.py`
- [Tech agent](https://github.com/akash5467/meeting-agent/blob/main/backend/agent/agents/tech_agent.py): research agent · Looks for technology stack and technical signals. · `backend/agent/agents/tech_agent.py`
- [Pain agent](https://github.com/akash5467/meeting-agent/blob/main/backend/agent/agents/pain_point_agent.py): research agent · Infers likely business pain points and priorities. · `backend/agent/agents/pain_point_agent.py`
- [Synthesis agent](https://github.com/akash5467/meeting-agent/blob/main/backend/agent/agents/synthesis_agent.py): brief builder · Combines specialist outputs into the final structured brief. · `backend/agent/agents/synthesis_agent.py`
- [Web search](https://github.com/akash5467/meeting-agent/blob/main/backend/agent/tools/web_search.py): research tool · Search/news wrapper used by agents for public web lookup. · `backend/agent/tools/web_search.py`
- [Tech lookup](https://github.com/akash5467/meeting-agent/blob/main/backend/agent/tools/tech_lookup.py): research tool · Semantic company research wrapper used by agents. · `backend/agent/tools/tech_lookup.py`
- [Database](https://github.com/akash5467/meeting-agent/blob/main/backend/app/database.py): persistence · Stores meetings, research results, and lifecycle state. · `backend/app/database.py`
- [Data models](https://github.com/akash5467/meeting-agent/blob/main/backend/app/models.py): schema · Defines meeting and brief records plus status fields. · `backend/app/models.py`
- [WebSocket hub](https://github.com/akash5467/meeting-agent/blob/main/backend/app/websocket_manager.py): realtime fan-out · Broadcasts updated meeting state to connected clients. · `backend/app/websocket_manager.py`

### Frontend

Vite React dashboard for authenticated users.

- [React app](https://github.com/akash5467/meeting-agent/blob/main/frontend/src/App.tsx): ui shell · Top-level dashboard shell and route composition. · `frontend/src/App.tsx`
- [Auth hook](https://github.com/akash5467/meeting-agent/blob/main/frontend/src/hooks/useAuth.ts): access control · Handles Google Sign-In and allowlist gating. · `frontend/src/hooks/useAuth.ts`
- [Live meetings](https://github.com/akash5467/meeting-agent/blob/main/frontend/src/hooks/useLiveMeetings.ts): data hook · Consumes live meeting state from the backend. · `frontend/src/hooks/useLiveMeetings.ts`
- [Meeting UI](https://github.com/akash5467/meeting-agent/blob/main/frontend/src/components/MeetingDetailPage.tsx): presentation · Login, list, skeleton, detail, and brief rendering components. · `frontend/src/components/MeetingDetailPage.tsx`

### External services

Calendar, identity, LLM, research, and database dependencies.

- **Google Calendar**: calendar api · Source of meeting data for the polling listener.
- **Google OAuth**: identity · Authentication and calendar access provider.
- **Gemini**: llm · Model used for agent reasoning and synthesis.
- **Serper + Exa**: research providers · External research and search substrate behind the agent tools.
- **PostgreSQL**: database service · Cloud SQL-backed storage for persisted meeting state.

## Connections

- FastAPI app → Calendar listener: start loop · Boots the polling monitor alongside the API.
- FastAPI app → Database: serve state · Reads and writes meeting data for API responses.
- FastAPI app → WebSocket hub: broadcast · Pushes live updates to connected clients.
- Calendar listener → Google Calendar: poll · Fetches upcoming meetings on a fixed interval.
- Calendar listener → Company parser: new meeting · Hands each fetched meeting to company extraction.
- Company parser → Orchestrator: identify company · Routes identifiable meetings into the research pipeline.
- Company parser → Database: no_company · Persists fallback state for meetings without a company.
- Orchestrator → News agent: parallel run · Runs specialist research in parallel.
- Orchestrator → Tech agent: parallel run · Runs specialist research in parallel.
- Orchestrator → Pain agent: parallel run · Runs specialist research in parallel.
- News agent → Web search: tool use · Uses search/news abstraction rather than direct internet access.
- Tech agent → Tech lookup: tool use · Uses semantic company lookup abstraction.
- Pain agent → Web search: tool use · Uses external research through tool wrapper.
- Web search → Serper + Exa: query · Delegates searches to external providers.
- Tech lookup → Serper + Exa: research · Delegates technical/company lookup to external providers.
- News agent → Gemini: reason · Uses the model for interpretation and extraction.
- Tech agent → Gemini: reason · Uses the model for interpretation and extraction.
- Pain agent → Gemini: reason · Uses the model for interpretation and extraction.
- Orchestrator → Synthesis agent: merge · Feeds specialist outputs into final brief synthesis.
- Synthesis agent → Gemini: compose · Uses the model to produce the structured brief.
- Synthesis agent → Database: persist brief · Stores the completed research output and status.
- Database → PostgreSQL: store · Persists meeting and brief records in PostgreSQL.
- Synthesis agent → WebSocket hub: notify · Triggers realtime fan-out when research completes.
- WebSocket hub → Live meetings: push updates · Delivers live meeting changes to the frontend.
- React app → Auth hook: gate access · Controls whether the dashboard is shown to the user.
- React app → Live meetings: load live state · Displays meetings and brief updates from the backend.
- React app → Meeting UI: render · Composes login, list, detail, and loading views.
- Auth hook → Google OAuth: sign in · Uses Google identity for user access control.
- FastAPI app → Google OAuth: calendar auth · Uses Google credentials to access Calendar.