How akash5467/meeting-agent works
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: orchestrator.py Orchestrator · main.py FastAPI app · synthesis_agent.py Synthesis agent · database.py Database
Components 22
Backend
FastAPI service, background polling, research orchestration, persistence, and realtime fan-out.
- FastAPI app · HTTP entrypoint that also starts the background monitoring loop.
backend/app/main.py - Calendar listener · Polls Google Calendar on an interval and hands meetings into the processing flow.
backend/app/calendar_listener.py - Company parser · Extracts the company from meeting title, attendees, or description and routes no-company fallbacks.
backend/app/parser.py - Orchestrator · Coordinates the parallel research agents and synthesis step for each meeting.
backend/agent/orchestrator.py - News agent · Finds recent company and market context.
backend/agent/agents/news_agent.py - Tech agent · Looks for technology stack and technical signals.
backend/agent/agents/tech_agent.py - Pain agent · Infers likely business pain points and priorities.
backend/agent/agents/pain_point_agent.py - Synthesis agent · Combines specialist outputs into the final structured brief.
backend/agent/agents/synthesis_agent.py - Web search · Search/news wrapper used by agents for public web lookup.
backend/agent/tools/web_search.py - Tech lookup · Semantic company research wrapper used by agents.
backend/agent/tools/tech_lookup.py - Database · Stores meetings, research results, and lifecycle state.
backend/app/database.py - Data models · Defines meeting and brief records plus status fields.
backend/app/models.py - WebSocket hub · Broadcasts updated meeting state to connected clients.
backend/app/websocket_manager.py
Frontend
Vite React dashboard for authenticated users.
- React app · Top-level dashboard shell and route composition.
frontend/src/App.tsx - Auth hook · Handles Google Sign-In and allowlist gating.
frontend/src/hooks/useAuth.ts - Live meetings · Consumes live meeting state from the backend.
frontend/src/hooks/useLiveMeetings.ts - Meeting UI · Login, list, skeleton, detail, and brief rendering components.
frontend/src/components/MeetingDetailPage.tsx
External services
Calendar, identity, LLM, research, and database dependencies.
- Google Calendar · Source of meeting data for the polling listener.
- Google OAuth · Authentication and calendar access provider.
- Gemini · Model used for agent reasoning and synthesis.
- Serper + Exa · External research and search substrate behind the agent tools.
- PostgreSQL · Cloud SQL-backed storage for persisted meeting state.
Connections 29
- 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.