mahakagarwal7/saraa

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