# mjanbandhu/multi-agent-productivity-assistant architecture

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

- Interactive diagram: https://gitdiagram.com/mjanbandhu/multi-agent-productivity-assistant
- Repository: https://github.com/mjanbandhu/multi-agent-productivity-assistant

## Overview

1. This repository is a Python 3.12 backend for a multi-agent productivity assistant. The runtime is FastAPI, packaged for Docker and deployed on Google Cloud Run. The app is centered on a single HTTP API that accepts natural-language productivity requests.

2. The main entrypoint is `app/main.py`, which wires the FastAPI application and mounts the API routes from `app/api/routes.py`. That file is the external boundary of the system: users send a `POST /query` request and receive a normalized response payload.

3. Request handling follows a clear pipeline: API route → primary orchestration agent → specialized agent(s) → tool layer → database. The `PrimaryAgent` in `app/agents/primary_agent.py` is the central router that decides whether the query should go to the task, notes, calendar, or multiple agents in sequence.

4. The specialized agents are split by domain in `app/agents/task_agent.py`, `app/agents/notes_agent.py`, and `app/agents/calendar_agent.py`. Each agent is responsible for interpreting user intent in its domain and coordinating the corresponding operation, rather than letting the API layer talk directly to storage.

5. The tool layer in `app/tools/` is the execution boundary between agent logic and persistence. `task_tool.py`, `notes_tool.py`, and `calendar_tool.py` encapsulate the actual CRUD-style operations for tasks, notes, and events, keeping business operations separated from routing logic.

6. Database access is isolated in `app/db/connection.py` and `app/db/queries.py`. The README indicates PostgreSQL/AlloyDB with `psycopg2`, so the architecture is a synchronous relational backend: tools call query helpers, which use the shared DB connection layer to execute SQL against PostgreSQL.

7. The system supports multi-step instructions, so a single query can fan out to more than one agent. Example: “create task … and add note … and schedule meeting …” is expected to be decomposed by the primary agent into multiple domain actions, each handled by its own specialized agent/tool path.

8. The `app/mcp/` directory suggests an internal Model Context Protocol-style tool exposure layer. `server.py` and `tool_registry.py` likely provide a registry and server boundary for exposing the assistant’s tools to an MCP-compatible client or internal agent runtime, separating tool registration from the FastAPI request surface.

9. `app/utils/helpers.py` is the shared utility boundary for reusable parsing or formatting logic that is not specific to one domain. In an architecture diagram, this sits as a supporting cross-cutting layer used by agents or tools rather than as a primary subsystem.

10. The deployment model is cloud-native and stateless at the application layer. Environment variables provide database credentials, while the container image is started via Docker/Cloud Run or the `Procfile`/Uvicorn command shown in the README. Persistent state lives in PostgreSQL, not in the API process.

11. The important external dependencies are FastAPI for HTTP, PostgreSQL for persistence, `psycopg2` for DB connectivity, Docker for packaging, and Google Cloud Run for hosting. No frontend is present in the repository; this is a backend API service only.

12. For an architecture diagram, the key boundaries are: client/API ingress, primary orchestration, domain agents, tool execution, database access, and the optional MCP/tool registry layer. The system is intentionally modular so each product area can be extended independently without changing the external API contract.

Main entry points: [`app/agents/primary_agent.py`](https://github.com/mjanbandhu/multi-agent-productivity-assistant/blob/main/app/agents/primary_agent.py) (Primary agent), [`app/mcp/server.py`](https://github.com/mjanbandhu/multi-agent-productivity-assistant/blob/main/app/mcp/server.py) (MCP server), [`app/agents/task_agent.py`](https://github.com/mjanbandhu/multi-agent-productivity-assistant/blob/main/app/agents/task_agent.py) (Task agent), [`app/db/queries.py`](https://github.com/mjanbandhu/multi-agent-productivity-assistant/blob/main/app/db/queries.py) (SQL queries)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_g_entry["API ingress"]
  node_n_client(("Client"))
  node_n_main["App entry<br/>FastAPI bootstrap<br/>[main.py]"]
  node_n_routes["API routes<br/>HTTP boundary<br/>[routes.py]"]
end

subgraph group_g_orch["Orchestration"]
  node_n_primary["Primary agent<br/>router agent<br/>[primary_agent.py]"]
  node_n_task_agent["Task agent<br/>domain agent<br/>[task_agent.py]"]
  node_n_notes_agent["Notes agent<br/>domain agent<br/>[notes_agent.py]"]
  node_n_calendar_agent["Calendar agent<br/>domain agent<br/>[calendar_agent.py]"]
end

subgraph group_g_exec["Execution"]
  node_n_task_tool["Task tool<br/>task executor<br/>[task_tool.py]"]
  node_n_notes_tool["Notes tool<br/>notes executor<br/>[notes_tool.py]"]
  node_n_calendar_tool["Calendar tool<br/>calendar executor<br/>[calendar_tool.py]"]
  node_n_queries["SQL queries<br/>query layer<br/>[queries.py]"]
  node_n_conn[("DB connection<br/>psycopg2 connection<br/>[connection.py]")]
  node_n_pg[("PostgreSQL<br/>relational store")]
end

subgraph group_g_mcp["MCP layer"]
  node_n_mcp_server["MCP server<br/>tool server<br/>[server.py]"]
  node_n_registry["Tool registry<br/>[tool_registry.py]"]
end

subgraph group_g_support["Support"]
  node_n_helpers["Helpers<br/>shared utils<br/>[helpers.py]"]
  node_n_runtime(("Cloud runtime<br/>Docker/Cloud Run"))
end

node_n_client -->|"HTTP request"| node_n_main
node_n_main -->|"mounts"| node_n_routes
node_n_routes -->|"dispatch"| node_n_primary
node_n_primary -.->|"task"| node_n_task_agent
node_n_primary -.->|"notes"| node_n_notes_agent
node_n_primary -.->|"calendar"| node_n_calendar_agent
node_n_primary -.->|"multi-step"| node_n_task_agent
node_n_task_agent -->|"executes"| node_n_task_tool
node_n_notes_agent -->|"executes"| node_n_notes_tool
node_n_calendar_agent -->|"executes"| node_n_calendar_tool
node_n_task_agent -.->|"uses"| node_n_helpers
node_n_notes_agent -.->|"uses"| node_n_helpers
node_n_calendar_agent -.->|"uses"| node_n_helpers
node_n_task_tool -->|"sql"| node_n_queries
node_n_notes_tool -->|"sql"| node_n_queries
node_n_calendar_tool -->|"sql"| node_n_queries
node_n_queries -->|"uses"| node_n_conn
node_n_conn -->|"connects"| node_n_pg
node_n_registry -->|"registers"| node_n_mcp_server
node_n_mcp_server -.->|"exposes"| node_n_task_tool
node_n_mcp_server -.->|"exposes"| node_n_notes_tool
node_n_mcp_server -.->|"exposes"| node_n_calendar_tool
node_n_runtime -->|"runs"| node_n_main

click node_n_main "https://github.com/mjanbandhu/multi-agent-productivity-assistant/blob/main/app/main.py"
click node_n_routes "https://github.com/mjanbandhu/multi-agent-productivity-assistant/blob/main/app/api/routes.py"
click node_n_primary "https://github.com/mjanbandhu/multi-agent-productivity-assistant/blob/main/app/agents/primary_agent.py"
click node_n_task_agent "https://github.com/mjanbandhu/multi-agent-productivity-assistant/blob/main/app/agents/task_agent.py"
click node_n_notes_agent "https://github.com/mjanbandhu/multi-agent-productivity-assistant/blob/main/app/agents/notes_agent.py"
click node_n_calendar_agent "https://github.com/mjanbandhu/multi-agent-productivity-assistant/blob/main/app/agents/calendar_agent.py"
click node_n_helpers "https://github.com/mjanbandhu/multi-agent-productivity-assistant/blob/main/app/utils/helpers.py"
click node_n_task_tool "https://github.com/mjanbandhu/multi-agent-productivity-assistant/blob/main/app/tools/task_tool.py"
click node_n_notes_tool "https://github.com/mjanbandhu/multi-agent-productivity-assistant/blob/main/app/tools/notes_tool.py"
click node_n_calendar_tool "https://github.com/mjanbandhu/multi-agent-productivity-assistant/blob/main/app/tools/calendar_tool.py"
click node_n_queries "https://github.com/mjanbandhu/multi-agent-productivity-assistant/blob/main/app/db/queries.py"
click node_n_conn "https://github.com/mjanbandhu/multi-agent-productivity-assistant/blob/main/app/db/connection.py"
click node_n_mcp_server "https://github.com/mjanbandhu/multi-agent-productivity-assistant/blob/main/app/mcp/server.py"
click node_n_registry "https://github.com/mjanbandhu/multi-agent-productivity-assistant/blob/main/app/mcp/tool_registry.py"
click node_n_runtime "https://github.com/mjanbandhu/multi-agent-productivity-assistant/tree/main/Dockerfile"

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_n_client,node_n_main,node_n_routes toneBlue
class node_n_primary,node_n_task_agent,node_n_notes_agent,node_n_calendar_agent toneAmber
class node_n_task_tool,node_n_notes_tool,node_n_calendar_tool,node_n_queries,node_n_conn,node_n_pg toneMint
class node_n_mcp_server,node_n_registry toneRose
class node_n_helpers,node_n_runtime toneIndigo
```

## Components

### API ingress

HTTP entrypoint and external request surface

- **Client**: external client · Sends natural-language productivity requests
- [App entry](https://github.com/mjanbandhu/multi-agent-productivity-assistant/blob/main/app/main.py): FastAPI bootstrap · Builds and starts the FastAPI application · `app/main.py`
- [API routes](https://github.com/mjanbandhu/multi-agent-productivity-assistant/blob/main/app/api/routes.py): HTTP boundary · Exposes the POST /query request and normalizes responses · `app/api/routes.py`

### Orchestration

Primary routing and domain agents

- [Primary agent](https://github.com/mjanbandhu/multi-agent-productivity-assistant/blob/main/app/agents/primary_agent.py): router agent · Routes each request to one or more domain agents · `app/agents/primary_agent.py`
- [Task agent](https://github.com/mjanbandhu/multi-agent-productivity-assistant/blob/main/app/agents/task_agent.py): domain agent · Interprets task-related intent and coordinates task actions · `app/agents/task_agent.py`
- [Notes agent](https://github.com/mjanbandhu/multi-agent-productivity-assistant/blob/main/app/agents/notes_agent.py): domain agent · Interprets note-related intent and coordinates note actions · `app/agents/notes_agent.py`
- [Calendar agent](https://github.com/mjanbandhu/multi-agent-productivity-assistant/blob/main/app/agents/calendar_agent.py): domain agent · Interprets calendar intent and coordinates event actions · `app/agents/calendar_agent.py`

### Execution

Tool layer and database access

- [Task tool](https://github.com/mjanbandhu/multi-agent-productivity-assistant/blob/main/app/tools/task_tool.py): task executor · Executes task CRUD operations · `app/tools/task_tool.py`
- [Notes tool](https://github.com/mjanbandhu/multi-agent-productivity-assistant/blob/main/app/tools/notes_tool.py): notes executor · Executes note CRUD operations · `app/tools/notes_tool.py`
- [Calendar tool](https://github.com/mjanbandhu/multi-agent-productivity-assistant/blob/main/app/tools/calendar_tool.py): calendar executor · Executes calendar and event operations · `app/tools/calendar_tool.py`
- [SQL queries](https://github.com/mjanbandhu/multi-agent-productivity-assistant/blob/main/app/db/queries.py): query layer · Builds and runs domain SQL statements · `app/db/queries.py`
- [DB connection](https://github.com/mjanbandhu/multi-agent-productivity-assistant/blob/main/app/db/connection.py): psycopg2 connection · Shared PostgreSQL connection management · `app/db/connection.py`
- **PostgreSQL**: relational store · Persistent datastore for tasks, notes, and events

### MCP layer

Internal tool exposure boundary

- [MCP server](https://github.com/mjanbandhu/multi-agent-productivity-assistant/blob/main/app/mcp/server.py): tool server · Exposes assistant tools through an MCP-style boundary · `app/mcp/server.py`
- [Tool registry](https://github.com/mjanbandhu/multi-agent-productivity-assistant/blob/main/app/mcp/tool_registry.py): registry · Registers available tools for the MCP layer · `app/mcp/tool_registry.py`

### Support

Shared utilities and deployment/runtime boundary

- [Helpers](https://github.com/mjanbandhu/multi-agent-productivity-assistant/blob/main/app/utils/helpers.py): shared utils · Reusable parsing and formatting helpers · `app/utils/helpers.py`
- [Cloud runtime](https://github.com/mjanbandhu/multi-agent-productivity-assistant/tree/main/Dockerfile): Docker/Cloud Run · Containerized deployment environment for the stateless API · `Dockerfile`

## Connections

- Client → App entry: HTTP request · Client sends requests to the service entrypoint
- App entry → API routes: mounts · FastAPI app wires in the API routes
- API routes → Primary agent: dispatch · Route handler forwards queries into orchestration
- Primary agent → Task agent: task · Routes task intent to the task specialist
- Primary agent → Notes agent: notes · Routes note intent to the notes specialist
- Primary agent → Calendar agent: calendar · Routes calendar intent to the calendar specialist
- Primary agent → Task agent: multi-step · May fan out one request across multiple agents
- Task agent → Task tool: executes · Task agent delegates work to task tools
- Notes agent → Notes tool: executes · Notes agent delegates work to notes tools
- Calendar agent → Calendar tool: executes · Calendar agent delegates work to calendar tools
- Task agent → Helpers: uses · Shared parsing or formatting support
- Notes agent → Helpers: uses · Shared parsing or formatting support
- Calendar agent → Helpers: uses · Shared parsing or formatting support
- Task tool → SQL queries: sql · Tool layer calls query helpers for persistence
- Notes tool → SQL queries: sql · Tool layer calls query helpers for persistence
- Calendar tool → SQL queries: sql · Tool layer calls query helpers for persistence
- SQL queries → DB connection: uses · Query helpers execute through the shared DB connection
- DB connection → PostgreSQL: connects · Persistent state lives in PostgreSQL
- Tool registry → MCP server: registers · Registry provides the MCP server with available tools
- MCP server → Task tool: exposes · MCP boundary can expose task tools
- MCP server → Notes tool: exposes · MCP boundary can expose notes tools
- MCP server → Calendar tool: exposes · MCP boundary can expose calendar tools
- Cloud runtime → App entry: runs · Containerized deployment runs the API process
