# sayandeep-coder/mads architecture

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

- Interactive diagram: https://gitdiagram.com/sayandeep-coder/mads
- Repository: https://github.com/sayandeep-coder/mads
- Video tour (about a minute): https://gitdiagram.com/sayandeep-coder/mads/video

## Overview

Mads is a personal AI Chief of Staff: users chat through CLI, web, browser-extension, and Excel surfaces; a shared agent lets Gemini select tools, then returns a response. Advanced Planner and Adaptive Intelligence enrich the agent without replacing its tool interface. The graph preserves the documented tool families, skills, memory, and distinct planning and learning workflows. Several tool families are represented at their enclosing directory because their individual provider wiring was not sampled; those links follow the README rather than inferred source calls.

Main entry points: [`skills/registry.py`](https://github.com/sayandeep-coder/mads/blob/main/skills/registry.py) (On-demand skills), [`agent/session.py`](https://github.com/sayandeep-coder/mads/blob/main/agent/session.py) (Session builder), [`agent/agent.py`](https://github.com/sayandeep-coder/mads/blob/main/agent/agent.py) (Gemini agent), [`mcp_servers/manager.py`](https://github.com/sayandeep-coder/mads/blob/main/mcp_servers/manager.py) (Tool manager)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_surfaces["User surfaces"]
  node_cli["CLI REPL<br/>[main.py]"]
  node_web["Web chat<br/>[useChat.ts]"]
  node_extension["Browser extension<br/>[sidepanel.js]"]
  node_exceladdin["Excel add-in<br/>[taskpane.js]"]
  node_backend["Chat API<br/>[app.py]"]
end

subgraph group_runtime["Agent runtime"]
  node_session["Session builder<br/>[session.py]"]
  node_agent["Gemini agent<br/>[agent.py]"]
  node_manager["Tool manager<br/>[manager.py]"]
end

subgraph group_capabilities["Tools and skills"]
  node_providers["Tool providers"]
  node_skills["On-demand skills<br/>[registry.py]"]
  node_memory[("Memory engine<br/>[provider.py]")]
  node_research["Research tools<br/>[research_prompt.py]"]
  node_oauth["OAuth integrations<br/>[oauth_manager.py]"]
  node_skillsdocs["Document skills<br/>[docs.py]"]
  node_skillspdf["PDF skill<br/>[pdf.py]"]
  node_skillsexcel["Excel skill<br/>[excel.py]"]
  node_skillspptx["PPTX skill<br/>[pptx.py]"]
end

subgraph group_planning["Advanced Planner"]
  node_planner["Planner tools<br/>[planner.py]"]
  node_planningengine["Plan generation<br/>[planning_engine.py]"]
  node_projectmanager["Project management<br/>[project_manager.py]"]
  node_taskmanager["Task management<br/>[task_manager.py]"]
  node_promptlibrary["Prompt library<br/>[prompt_library.py]"]
  node_planstorage[("Project storage<br/>[storage.py]")]
end

subgraph group_adaptive["Adaptive Intelligence"]
  node_adaptivepipeline["History import<br/>[pipeline.py]"]
  node_adaptiveprofile["Approved profile<br/>[profile.py]"]
  node_adaptivestorage[("Adaptive storage<br/>[storage.py]")]
end

node_user(("User"))
node_gemini{{"Gemini"}}

node_user -->|"uses"| node_cli
node_user -->|"uses"| node_web
node_user -->|"uses"| node_extension
node_user -->|"uses"| node_exceladdin
node_cli -->|"builds"| node_session
node_web -->|"streams chat"| node_backend
node_extension -->|"sends browser chat"| node_backend
node_exceladdin -->|"sends workbook chat"| node_backend
node_backend -->|"routes chat"| node_session
node_session -->|"builds"| node_agent
node_agent -->|"sends turns"| node_gemini
node_gemini -->|"requests functions"| node_agent
node_agent -->|"dispatches tools"| node_manager
node_manager -->|"calls provider"| node_providers
node_agent -->|"invokes skills"| node_skills
node_session -->|"starts planner context"| node_planner
node_session -->|"loads profile"| node_adaptiveprofile
node_planner -->|"builds plans"| node_planningengine
node_planner -->|"manages projects"| node_projectmanager
node_planningengine -->|"reads tasks"| node_taskmanager
node_planningengine -->|"suggests prompts"| node_promptlibrary
node_projectmanager -->|"reads and writes"| node_planstorage
node_taskmanager -->|"reads and writes"| node_planstorage
node_cli -->|"imports history"| node_adaptivepipeline
node_adaptivepipeline -->|"queues candidates"| node_adaptiveprofile
node_adaptiveprofile -->|"persists profile"| node_adaptivestorage
node_manager -->|"dispatches memory tools"| node_memory
node_manager -->|"dispatches research tools"| node_research
node_skills -->|"loads document skill"| node_skillsdocs
node_skills -->|"loads PDF skill"| node_skillspdf
node_skills -->|"loads Excel skill"| node_skillsexcel
node_skills -->|"loads PPTX skill"| node_skillspptx
node_providers -.->|"uses OAuth"| node_oauth

click node_cli "https://github.com/sayandeep-coder/mads/blob/main/cli/main.py"
click node_web "https://github.com/sayandeep-coder/mads/blob/main/web/src/lib/useChat.ts"
click node_extension "https://github.com/sayandeep-coder/mads/blob/main/extension/sidepanel.js"
click node_exceladdin "https://github.com/sayandeep-coder/mads/blob/main/excel-addin/taskpane.js"
click node_backend "https://github.com/sayandeep-coder/mads/blob/main/server/app.py"
click node_session "https://github.com/sayandeep-coder/mads/blob/main/agent/session.py"
click node_agent "https://github.com/sayandeep-coder/mads/blob/main/agent/agent.py"
click node_manager "https://github.com/sayandeep-coder/mads/blob/main/mcp_servers/manager.py"
click node_providers "https://github.com/sayandeep-coder/mads/tree/main/mcp_servers/servers"
click node_skills "https://github.com/sayandeep-coder/mads/blob/main/skills/registry.py"
click node_memory "https://github.com/sayandeep-coder/mads/blob/main/memory/provider.py"
click node_planner "https://github.com/sayandeep-coder/mads/blob/main/planner/planner.py"
click node_planningengine "https://github.com/sayandeep-coder/mads/blob/main/planner/planning_engine.py"
click node_projectmanager "https://github.com/sayandeep-coder/mads/blob/main/planner/project_manager.py"
click node_taskmanager "https://github.com/sayandeep-coder/mads/blob/main/planner/task_manager.py"
click node_promptlibrary "https://github.com/sayandeep-coder/mads/blob/main/planner/prompt_library.py"
click node_planstorage "https://github.com/sayandeep-coder/mads/blob/main/planner/storage.py"
click node_adaptivepipeline "https://github.com/sayandeep-coder/mads/blob/main/adaptive/pipeline.py"
click node_adaptiveprofile "https://github.com/sayandeep-coder/mads/blob/main/adaptive/profile.py"
click node_adaptivestorage "https://github.com/sayandeep-coder/mads/blob/main/adaptive/storage.py"
click node_research "https://github.com/sayandeep-coder/mads/blob/main/agent/research_prompt.py"
click node_oauth "https://github.com/sayandeep-coder/mads/blob/main/auth/oauth_manager.py"
click node_skillsdocs "https://github.com/sayandeep-coder/mads/blob/main/skills/docs.py"
click node_skillspdf "https://github.com/sayandeep-coder/mads/blob/main/skills/pdf.py"
click node_skillsexcel "https://github.com/sayandeep-coder/mads/blob/main/skills/excel.py"
click node_skillspptx "https://github.com/sayandeep-coder/mads/blob/main/skills/pptx.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_cli,node_web,node_extension,node_exceladdin,node_backend,node_user toneBlue
class node_session,node_agent,node_manager toneAmber
class node_providers,node_skills,node_memory,node_research,node_oauth,node_skillsdocs,node_skillspdf,node_skillsexcel,node_skillspptx toneMint
class node_planner,node_planningengine,node_projectmanager,node_taskmanager,node_promptlibrary,node_planstorage toneRose
class node_adaptivepipeline,node_adaptiveprofile,node_adaptivestorage,node_gemini toneIndigo
```

## Components

### User surfaces

- [CLI REPL](https://github.com/sayandeep-coder/mads/blob/main/cli/main.py): `cli/main.py`
- [Web chat](https://github.com/sayandeep-coder/mads/blob/main/web/src/lib/useChat.ts): `web/src/lib/useChat.ts`
- [Browser extension](https://github.com/sayandeep-coder/mads/blob/main/extension/sidepanel.js): `extension/sidepanel.js`
- [Excel add-in](https://github.com/sayandeep-coder/mads/blob/main/excel-addin/taskpane.js): `excel-addin/taskpane.js`
- [Chat API](https://github.com/sayandeep-coder/mads/blob/main/server/app.py): `server/app.py`

### Agent runtime

- [Session builder](https://github.com/sayandeep-coder/mads/blob/main/agent/session.py): `agent/session.py`
- [Gemini agent](https://github.com/sayandeep-coder/mads/blob/main/agent/agent.py): `agent/agent.py`
- [Tool manager](https://github.com/sayandeep-coder/mads/blob/main/mcp_servers/manager.py): `mcp_servers/manager.py`

### Tools and skills

- [Tool providers](https://github.com/sayandeep-coder/mads/tree/main/mcp_servers/servers): `mcp_servers/servers`
- [On-demand skills](https://github.com/sayandeep-coder/mads/blob/main/skills/registry.py): `skills/registry.py`
- [Memory engine](https://github.com/sayandeep-coder/mads/blob/main/memory/provider.py): `memory/provider.py`
- [Research tools](https://github.com/sayandeep-coder/mads/blob/main/agent/research_prompt.py): `agent/research_prompt.py`
- [OAuth integrations](https://github.com/sayandeep-coder/mads/blob/main/auth/oauth_manager.py): `auth/oauth_manager.py`
- [Document skills](https://github.com/sayandeep-coder/mads/blob/main/skills/docs.py): `skills/docs.py`
- [PDF skill](https://github.com/sayandeep-coder/mads/blob/main/skills/pdf.py): `skills/pdf.py`
- [Excel skill](https://github.com/sayandeep-coder/mads/blob/main/skills/excel.py): `skills/excel.py`
- [PPTX skill](https://github.com/sayandeep-coder/mads/blob/main/skills/pptx.py): `skills/pptx.py`

### Advanced Planner

- [Planner tools](https://github.com/sayandeep-coder/mads/blob/main/planner/planner.py): `planner/planner.py`
- [Plan generation](https://github.com/sayandeep-coder/mads/blob/main/planner/planning_engine.py): `planner/planning_engine.py`
- [Project management](https://github.com/sayandeep-coder/mads/blob/main/planner/project_manager.py): `planner/project_manager.py`
- [Task management](https://github.com/sayandeep-coder/mads/blob/main/planner/task_manager.py): `planner/task_manager.py`
- [Prompt library](https://github.com/sayandeep-coder/mads/blob/main/planner/prompt_library.py): `planner/prompt_library.py`
- [Project storage](https://github.com/sayandeep-coder/mads/blob/main/planner/storage.py): `planner/storage.py`

### Adaptive Intelligence

- [History import](https://github.com/sayandeep-coder/mads/blob/main/adaptive/pipeline.py): `adaptive/pipeline.py`
- [Approved profile](https://github.com/sayandeep-coder/mads/blob/main/adaptive/profile.py): `adaptive/profile.py`
- [Adaptive storage](https://github.com/sayandeep-coder/mads/blob/main/adaptive/storage.py): `adaptive/storage.py`

### Other components

- **User**
- **Gemini**

## Connections

- User → CLI REPL: uses
- User → Web chat: uses
- User → Browser extension: uses
- User → Excel add-in: uses
- CLI REPL → Session builder: builds (evidence: `agent/session.py`)
- Web chat → Chat API: streams chat
- Browser extension → Chat API: sends browser chat
- Excel add-in → Chat API: sends workbook chat
- Chat API → Session builder: routes chat (evidence: `server/app.py`)
- Session builder → Gemini agent: builds (evidence: `agent/session.py`)
- Gemini agent → Gemini: sends turns
- Gemini → Gemini agent: requests functions
- Gemini agent → Tool manager: dispatches tools (evidence: `agent/agent.py`)
- Tool manager → Tool providers: calls provider (evidence: `mcp_servers/servers/search.py`)
- Gemini agent → On-demand skills: invokes skills (evidence: `agent/agent.py`)
- Session builder → Planner tools: starts planner context (evidence: `agent/session.py`)
- Session builder → Approved profile: loads profile (evidence: `agent/session.py`)
- Planner tools → Plan generation: builds plans (evidence: `planner/planner.py`)
- Planner tools → Project management: manages projects (evidence: `planner/planner.py`)
- Plan generation → Task management: reads tasks (evidence: `planner/planning_engine.py`)
- Plan generation → Prompt library: suggests prompts (evidence: `planner/planning_engine.py`)
- Project management → Project storage: reads and writes (evidence: `planner/project_manager.py`)
- Task management → Project storage: reads and writes (evidence: `planner/task_manager.py`)
- CLI REPL → History import: imports history (evidence: `cli/main.py`)
- History import → Approved profile: queues candidates (evidence: `adaptive/pipeline.py`)
- Approved profile → Adaptive storage: persists profile (evidence: `adaptive/profile.py`)
- Tool manager → Memory engine: dispatches memory tools
- Tool manager → Research tools: dispatches research tools
- On-demand skills → Document skills: loads document skill
- On-demand skills → PDF skill: loads PDF skill
- On-demand skills → Excel skill: loads Excel skill
- On-demand skills → PPTX skill: loads PPTX skill
- Tool providers → OAuth integrations: uses OAuth