# mahakagarwal7/saraa architecture

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

- Interactive diagram: https://gitdiagram.com/mahakagarwal7/saraa
- Repository: https://github.com/mahakagarwal7/saraa

## Overview

#### 1. Purpose and Runtime Shape
SARAA is an executive-assistant system: a React SPA submits requests to a FastAPI backend, which coordinates specialist AutoGen-style agents for research, scheduling, email, knowledge retrieval, writing, and executive briefings. The principal entry points are `executive-assistant-swarm/frontend/src/main.tsx`, `executive-assistant-swarm/frontend/src/App.tsx`, and `executive-assistant-swarm/backend/api/main.py`.

#### 2. Client Interaction Layer
The Vite/React TypeScript client owns the conversational UI, browser-side interactions, and API invocation. `App.tsx` is the primary screen and workflow host; `services/api.ts` is the client/backend boundary. Styling and browser-print presentation are centralized in `frontend/src/App.css`, supporting client-side briefing export behavior.
- `executive-assistant-swarm/frontend/src/App.tsx`
- `executive-assistant-swarm/frontend/src/services/api.ts`
- `executive-assistant-swarm/frontend/src/App.css`

#### 3. API and Request Boundary
FastAPI is the backend ingress and process boundary. `api/main.py` accepts client operations and connects them to the swarm. It is the natural location for HTTP concerns, authentication handoff, request validation, response/stream handling, and CORS/client integration.
- `executive-assistant-swarm/backend/api/main.py`
- `executive-assistant-swarm/backend/api/__init__.py`

#### 4. Swarm Orchestration
The orchestrator is the central control plane: it interprets a user task, delegates work to specialist agents, and combines outputs into a result. The common base agent provides shared agent behavior and document-context extraction, keeping individual agents task-specific.
- `executive-assistant-swarm/backend/agents/orchestrator_agent.py`
- `executive-assistant-swarm/backend/agents/base_agent.py`
- `executive-assistant-swarm/backend/agents/__init__.py`

#### 5. Specialist Execution Stages
Specialists form the operational pipeline: research gathers external facts; knowledge handles retrieved/local context; scheduler handles calendar work; email supports communications; writer turns results into prose; briefing packages executive-facing output. The orchestrator selects and sequences these capabilities rather than exposing them as independent client workflows.
- `executive-assistant-swarm/backend/agents/research_agent.py`
- `executive-assistant-swarm/backend/agents/knowledge_agent.py`
- `executive-assistant-swarm/backend/agents/scheduler_agent.py`
- `executive-assistant-swarm/backend/agents/email_agent.py`
- `executive-assistant-swarm/backend/agents/writer_agent.py`
- `executive-assistant-swarm/backend/agents/briefing_agent.py`

#### 6. Information Acquisition, Documents, and Persistence
Web search and scraping are explicit external-data boundaries used by research agents. Uploaded or supplied PDF/Word material is parsed through the base-agent path; knowledge and memory stores preserve reusable context across agent actions. Generated briefing PDFs are written under backend outputs.
- `executive-assistant-swarm/backend/tools/web_search.py`
- `executive-assistant-swarm/backend/tools/web_scraper.py`
- `executive-assistant-swarm/backend/utils/knowledge_db.py`
- `executive-assistant-swarm/backend/utils/memory_db.py`
- `executive-assistant-swarm/backend/utils/pdf_export.py`
- `executive-assistant-swarm/backend/outputs`

#### 7. External Services and Deployment Dependencies
The backend depends on Azure OpenAI for LLM execution and AutoGen for multi-agent coordination. Microsoft Graph/MSAL supports identity plus calendar and mail operations; Tavily and optionally Bing provide search. The frontend runs on Node/Vite, while the backend runs on Python/FastAPI. Configuration is environment-driven through `utils/config.py`; deployment hints include Vercel configuration for the frontend.
- `executive-assistant-swarm/backend/requirements.txt`
- `executive-assistant-swarm/backend/utils/config.py`
- `executive-assistant-swarm/backend/tools/autogen_tools.py`
- `executive-assistant-swarm/frontend/vercel.json`

Main entry points: [`executive-assistant-swarm/backend/agents/orchestrator_agent.py`](https://github.com/mahakagarwal7/saraa/blob/main/executive-assistant-swarm/backend/agents/orchestrator_agent.py) (Swarm orchestrator), [`executive-assistant-swarm/frontend/src/App.tsx`](https://github.com/mahakagarwal7/saraa/blob/main/executive-assistant-swarm/frontend/src/App.tsx) (Conversation UI), [`executive-assistant-swarm/frontend/src/services/api.ts`](https://github.com/mahakagarwal7/saraa/blob/main/executive-assistant-swarm/frontend/src/services/api.ts) (API client), [`executive-assistant-swarm/backend/api/main.py`](https://github.com/mahakagarwal7/saraa/blob/main/executive-assistant-swarm/backend/api/main.py) (FastAPI ingress)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["React Client"]
  node_client_main["Client entry<br/>Vite bootstrap<br/>[main.tsx]"]
  node_app["Conversation UI<br/>React workflow host<br/>[App.tsx]"]
  node_client_api["API client<br/>client boundary<br/>[api.ts]"]
  node_client_styles["Print styling<br/>CSS presentation<br/>[App.css]"]
end

subgraph group_backend["FastAPI &amp; Agent Swarm"]
  node_api["FastAPI ingress<br/>HTTP API<br/>[main.py]"]
  node_orchestrator{{"Swarm orchestrator<br/>agent control plane"}}
  node_base_agent["Base agent<br/>shared agent behavior<br/>[base_agent.py]"]
  node_research["Research agent<br/>specialist agent<br/>[research_agent.py]"]
  node_knowledge["Knowledge agent<br/>specialist agent<br/>[knowledge_agent.py]"]
  node_productivity["Calendar &amp; mail agents<br/>specialist agents<br/>[scheduler_agent.py]"]
  node_writing["Writer &amp; briefing agents<br/>output specialists<br/>[briefing_agent.py]"]
  node_web_tools["Web acquisition<br/>search and scraping<br/>[web_search.py]"]
  node_context_stores[("Knowledge &amp; memory<br/>persistent context<br/>[knowledge_db.py]")]
  node_pdf_export["Briefing PDF export<br/>document renderer<br/>[pdf_export.py]"]
  node_outputs["Generated outputs<br/>briefing artifacts"]
end

subgraph group_external["External Services"]
  node_azure_openai{{"Azure OpenAI<br/>LLM service"}}
  node_graph{{"Microsoft Graph / MSAL<br/>identity, calendar, mail"}}
  node_search_providers{{"Tavily / Bing<br/>search providers"}}
  node_autogen{{"AutoGen<br/>agent coordination runtime<br/>[autogen_tools.py]"}}
end

node_client_main -->|"mounts"| node_app
node_app -->|"submits requests"| node_client_api
node_app -->|"uses"| node_client_styles
node_client_api -->|"HTTP operations"| node_api
node_api -->|"dispatches task"| node_orchestrator
node_orchestrator -->|"shared behavior"| node_base_agent
node_orchestrator -->|"delegates research"| node_research
node_orchestrator -->|"delegates retrieval"| node_knowledge
node_orchestrator -->|"delegates scheduling and mail"| node_productivity
node_orchestrator -->|"delegates composition"| node_writing
node_research -->|"acquires facts"| node_web_tools
node_web_tools -->|"searches"| node_search_providers
node_knowledge -->|"retrieves and stores context"| node_context_stores
node_base_agent -->|"uses document context"| node_context_stores
node_productivity -->|"identity, calendar, mail"| node_graph
node_writing -->|"renders briefing"| node_pdf_export
node_pdf_export -->|"writes PDFs"| node_outputs
node_orchestrator -->|"coordinates through"| node_autogen
node_orchestrator -->|"LLM execution"| node_azure_openai

click node_client_main "https://github.com/mahakagarwal7/saraa/blob/main/executive-assistant-swarm/frontend/src/main.tsx"
click node_app "https://github.com/mahakagarwal7/saraa/blob/main/executive-assistant-swarm/frontend/src/App.tsx"
click node_client_api "https://github.com/mahakagarwal7/saraa/blob/main/executive-assistant-swarm/frontend/src/services/api.ts"
click node_client_styles "https://github.com/mahakagarwal7/saraa/blob/main/executive-assistant-swarm/frontend/src/App.css"
click node_api "https://github.com/mahakagarwal7/saraa/blob/main/executive-assistant-swarm/backend/api/main.py"
click node_orchestrator "https://github.com/mahakagarwal7/saraa/blob/main/executive-assistant-swarm/backend/agents/orchestrator_agent.py"
click node_base_agent "https://github.com/mahakagarwal7/saraa/blob/main/executive-assistant-swarm/backend/agents/base_agent.py"
click node_research "https://github.com/mahakagarwal7/saraa/blob/main/executive-assistant-swarm/backend/agents/research_agent.py"
click node_knowledge "https://github.com/mahakagarwal7/saraa/blob/main/executive-assistant-swarm/backend/agents/knowledge_agent.py"
click node_productivity "https://github.com/mahakagarwal7/saraa/blob/main/executive-assistant-swarm/backend/agents/scheduler_agent.py"
click node_writing "https://github.com/mahakagarwal7/saraa/blob/main/executive-assistant-swarm/backend/agents/briefing_agent.py"
click node_web_tools "https://github.com/mahakagarwal7/saraa/blob/main/executive-assistant-swarm/backend/tools/web_search.py"
click node_context_stores "https://github.com/mahakagarwal7/saraa/blob/main/executive-assistant-swarm/backend/utils/knowledge_db.py"
click node_pdf_export "https://github.com/mahakagarwal7/saraa/blob/main/executive-assistant-swarm/backend/utils/pdf_export.py"
click node_outputs "https://github.com/mahakagarwal7/saraa/tree/main/executive-assistant-swarm/backend/outputs"
click node_autogen "https://github.com/mahakagarwal7/saraa/blob/main/executive-assistant-swarm/backend/tools/autogen_tools.py"

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_client_main,node_app,node_client_api,node_client_styles toneBlue
class node_api,node_orchestrator,node_base_agent,node_research,node_knowledge,node_productivity,node_writing,node_web_tools,node_context_stores,node_pdf_export,node_outputs toneAmber
class node_azure_openai,node_graph,node_search_providers,node_autogen toneMint
```

## Components

### React Client

- [Client entry](https://github.com/mahakagarwal7/saraa/blob/main/executive-assistant-swarm/frontend/src/main.tsx): Vite bootstrap · `executive-assistant-swarm/frontend/src/main.tsx`
- [Conversation UI](https://github.com/mahakagarwal7/saraa/blob/main/executive-assistant-swarm/frontend/src/App.tsx): React workflow host · Hosts requests and client-side briefing export. · `executive-assistant-swarm/frontend/src/App.tsx`
- [API client](https://github.com/mahakagarwal7/saraa/blob/main/executive-assistant-swarm/frontend/src/services/api.ts): client boundary · `executive-assistant-swarm/frontend/src/services/api.ts`
- [Print styling](https://github.com/mahakagarwal7/saraa/blob/main/executive-assistant-swarm/frontend/src/App.css): CSS presentation · `executive-assistant-swarm/frontend/src/App.css`

### FastAPI & Agent Swarm

- [FastAPI ingress](https://github.com/mahakagarwal7/saraa/blob/main/executive-assistant-swarm/backend/api/main.py): HTTP API · Validates client operations and hands requests to the swarm. · `executive-assistant-swarm/backend/api/main.py`
- [Swarm orchestrator](https://github.com/mahakagarwal7/saraa/blob/main/executive-assistant-swarm/backend/agents/orchestrator_agent.py): agent control plane · Interprets tasks, delegates specialist work, and combines results. · `executive-assistant-swarm/backend/agents/orchestrator_agent.py`
- [Base agent](https://github.com/mahakagarwal7/saraa/blob/main/executive-assistant-swarm/backend/agents/base_agent.py): shared agent behavior · Provides common behavior and document-context extraction. · `executive-assistant-swarm/backend/agents/base_agent.py`
- [Research agent](https://github.com/mahakagarwal7/saraa/blob/main/executive-assistant-swarm/backend/agents/research_agent.py): specialist agent · `executive-assistant-swarm/backend/agents/research_agent.py`
- [Knowledge agent](https://github.com/mahakagarwal7/saraa/blob/main/executive-assistant-swarm/backend/agents/knowledge_agent.py): specialist agent · `executive-assistant-swarm/backend/agents/knowledge_agent.py`
- [Calendar & mail agents](https://github.com/mahakagarwal7/saraa/blob/main/executive-assistant-swarm/backend/agents/scheduler_agent.py): specialist agents · Schedules calendar work and supports communications. · `executive-assistant-swarm/backend/agents/scheduler_agent.py`
- [Writer & briefing agents](https://github.com/mahakagarwal7/saraa/blob/main/executive-assistant-swarm/backend/agents/briefing_agent.py): output specialists · Drafts prose and packages executive-facing briefings. · `executive-assistant-swarm/backend/agents/briefing_agent.py`
- [Web acquisition](https://github.com/mahakagarwal7/saraa/blob/main/executive-assistant-swarm/backend/tools/web_search.py): search and scraping · `executive-assistant-swarm/backend/tools/web_search.py`
- [Knowledge & memory](https://github.com/mahakagarwal7/saraa/blob/main/executive-assistant-swarm/backend/utils/knowledge_db.py): persistent context · Preserves reusable knowledge and agent memory. · `executive-assistant-swarm/backend/utils/knowledge_db.py`
- [Briefing PDF export](https://github.com/mahakagarwal7/saraa/blob/main/executive-assistant-swarm/backend/utils/pdf_export.py): document renderer · `executive-assistant-swarm/backend/utils/pdf_export.py`
- [Generated outputs](https://github.com/mahakagarwal7/saraa/tree/main/executive-assistant-swarm/backend/outputs): briefing artifacts · `executive-assistant-swarm/backend/outputs`

### External Services

- **Azure OpenAI**: LLM service
- **Microsoft Graph / MSAL**: identity, calendar, mail
- **Tavily / Bing**: search providers
- [AutoGen](https://github.com/mahakagarwal7/saraa/blob/main/executive-assistant-swarm/backend/tools/autogen_tools.py): agent coordination runtime · `executive-assistant-swarm/backend/tools/autogen_tools.py`

## Connections

- Client entry → Conversation UI: mounts
- Conversation UI → API client: submits requests
- Conversation UI → Print styling: uses
- API client → FastAPI ingress: HTTP operations
- FastAPI ingress → Swarm orchestrator: dispatches task
- Swarm orchestrator → Base agent: shared behavior
- Swarm orchestrator → Research agent: delegates research
- Swarm orchestrator → Knowledge agent: delegates retrieval
- Swarm orchestrator → Calendar & mail agents: delegates scheduling and mail
- Swarm orchestrator → Writer & briefing agents: delegates composition
- Research agent → Web acquisition: acquires facts
- Web acquisition → Tavily / Bing: searches
- Knowledge agent → Knowledge & memory: retrieves and stores context
- Base agent → Knowledge & memory: uses document context
- Calendar & mail agents → Microsoft Graph / MSAL: identity, calendar, mail
- Writer & briefing agents → Briefing PDF export: renders briefing
- Briefing PDF export → Generated outputs: writes PDFs
- Swarm orchestrator → AutoGen: coordinates through
- Swarm orchestrator → Azure OpenAI: LLM execution