# yad4o/map architecture

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

- Interactive diagram: https://gitdiagram.com/yad4o/map
- Repository: https://github.com/yad4o/map

## Overview

MAP is a multi-agent task automation platform with a React dashboard and FastAPI backend. A user submits a task; the API queues it, a Celery worker runs the agent controller, and the result is persisted and exposed to the dashboard through polling or an event stream. The documented agent stages are planning, execution, analysis, and memory retrieval. The README also describes authentication, provider fallback, administration, logs, and task observability. Several backend modules are indexed but unsampled, so those branches and their links are shown only where the README documents the relationship.

Main entry points: [`backend/agents/controller/agent_controller.py`](https://github.com/yad4o/map/blob/main/backend/agents/controller/agent_controller.py) (Agent controller), [`backend/app/routes/tasks.py`](https://github.com/yad4o/map/blob/main/backend/app/routes/tasks.py) (Task routes), [`backend/app/worker/tasks.py`](https://github.com/yad4o/map/blob/main/backend/app/worker/tasks.py) (Celery task worker), [`backend/app/core/fallback_engine.py`](https://github.com/yad4o/map/blob/main/backend/app/core/fallback_engine.py) (Fallback engine)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Dashboard"]
  node_dashboard["React dashboard<br/>[App.tsx]"]
  node_task_ui["Task views<br/>[TaskDetailPage.tsx]"]
  node_task_api["Task API client<br/>[tasks.ts]"]
  node_stream_hook["Live stream hook<br/>[useTaskStream.ts]"]
end

subgraph group_gateway["API and identity"]
  node_api_app["FastAPI app<br/>[main.py]"]
  node_task_routes["Task routes<br/>[tasks.py]"]
  node_auth["Auth service<br/>[auth_service.py]"]
  node_oauth["OAuth exchange<br/>[oauth_service.py]"]
  node_task_service["Task service<br/>[task_service.py]"]
end

subgraph group_runtime["Task runtime"]
  node_worker["Celery task worker<br/>[tasks.py]"]
  node_runner["Agent runner<br/>[agent_runner.py]"]
end

subgraph group_agents["Agent pipeline"]
  node_controller["Agent controller"]
  node_planner["Planner<br/>[planner_agent.py]"]
  node_executor["Executor and tools<br/>[executor_agent.py]"]
  node_analyzer["Analyzer<br/>[analyzer_agent.py]"]
  node_memory_agent["Memory agent<br/>[memory_agent.py]"]
end

subgraph group_state["State and providers"]
  node_vector_store[("Vector store<br/>[vector_store.py]")]
  node_task_store[("Task and user data<br/>[task.py]")]
  node_redis[("Redis queue and streams<br/>[redis_client.py]")]
  node_fallback["Fallback engine<br/>[fallback_engine.py]"]
  node_llm_provider["LLM provider selection<br/>[llm_provider.py]"]
end

node_user(("User"))
node_llm_service{{"LLM providers"}}
node_bentoml{{"BentoML fallback"}}

node_user -->|"submits task"| node_dashboard
node_dashboard -->|"opens task views"| node_task_ui
node_task_ui -.->|"requests task data"| node_task_api
node_task_api -.->|"calls task endpoints"| node_task_routes
node_task_routes -->|"delegates task operations"| node_task_service
node_api_app -->|"registers routes"| node_task_routes
node_api_app -.->|"registers auth routes"| node_auth
node_oauth -->|"returns verified profile"| node_auth
node_task_service -.->|"persists task data"| node_task_store
node_task_routes -->|"queues task"| node_worker
node_worker -->|"runs task"| node_runner
node_runner -.->|"starts agent workflow"| node_controller
node_controller -->|"plans task"| node_planner
node_controller -->|"executes plan"| node_executor
node_controller -->|"validates results"| node_analyzer
node_controller -.->|"retrieves context"| node_memory_agent
node_memory_agent -.->|"retrieves memories"| node_vector_store
node_controller -->|"records agent steps"| node_task_store
node_worker -->|"saves results and status"| node_task_store
node_worker -.->|"uses distributed queue"| node_redis
node_task_routes -->|"streams task events"| node_redis
node_task_routes -.->|"serves event stream"| node_stream_hook
node_stream_hook -.->|"updates live answer"| node_task_ui
node_controller -.->|"requests inference"| node_fallback
node_fallback -.->|"selects provider"| node_llm_provider
node_llm_provider -.->|"calls configured model"| node_llm_service
node_fallback -.->|"uses local fallback"| node_bentoml

click node_dashboard "https://github.com/yad4o/map/blob/main/frontend/src/App.tsx"
click node_task_ui "https://github.com/yad4o/map/blob/main/frontend/src/pages/TaskDetailPage.tsx"
click node_task_api "https://github.com/yad4o/map/blob/main/frontend/src/api/tasks.ts"
click node_stream_hook "https://github.com/yad4o/map/blob/main/frontend/src/hooks/useTaskStream.ts"
click node_api_app "https://github.com/yad4o/map/blob/main/backend/app/main.py"
click node_task_routes "https://github.com/yad4o/map/blob/main/backend/app/routes/tasks.py"
click node_auth "https://github.com/yad4o/map/blob/main/backend/app/services/auth_service.py"
click node_oauth "https://github.com/yad4o/map/blob/main/backend/app/services/oauth_service.py"
click node_task_service "https://github.com/yad4o/map/blob/main/backend/app/services/task_service.py"
click node_worker "https://github.com/yad4o/map/blob/main/backend/app/worker/tasks.py"
click node_runner "https://github.com/yad4o/map/blob/main/backend/app/worker/agent_runner.py"
click node_controller "https://github.com/yad4o/map/blob/main/backend/agents/controller/agent_controller.py"
click node_planner "https://github.com/yad4o/map/blob/main/backend/agents/planner/planner_agent.py"
click node_executor "https://github.com/yad4o/map/blob/main/backend/agents/executor/executor_agent.py"
click node_analyzer "https://github.com/yad4o/map/blob/main/backend/agents/analyzer/analyzer_agent.py"
click node_memory_agent "https://github.com/yad4o/map/blob/main/backend/agents/memory/memory_agent.py"
click node_vector_store "https://github.com/yad4o/map/blob/main/backend/agents/memory/vector_store.py"
click node_task_store "https://github.com/yad4o/map/blob/main/backend/app/db/models/task.py"
click node_redis "https://github.com/yad4o/map/blob/main/backend/app/core/redis_client.py"
click node_fallback "https://github.com/yad4o/map/blob/main/backend/app/core/fallback_engine.py"
click node_llm_provider "https://github.com/yad4o/map/blob/main/app/core/llm_provider.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_dashboard,node_task_ui,node_task_api,node_stream_hook,node_user toneBlue
class node_api_app,node_task_routes,node_auth,node_oauth,node_task_service toneAmber
class node_worker,node_runner toneMint
class node_controller,node_planner,node_executor,node_analyzer,node_memory_agent toneRose
class node_vector_store,node_task_store,node_redis,node_fallback,node_llm_provider,node_llm_service,node_bentoml toneIndigo
```

## Components

### Dashboard

- [React dashboard](https://github.com/yad4o/map/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Task views](https://github.com/yad4o/map/blob/main/frontend/src/pages/TaskDetailPage.tsx): `frontend/src/pages/TaskDetailPage.tsx`
- [Task API client](https://github.com/yad4o/map/blob/main/frontend/src/api/tasks.ts): `frontend/src/api/tasks.ts`
- [Live stream hook](https://github.com/yad4o/map/blob/main/frontend/src/hooks/useTaskStream.ts): `frontend/src/hooks/useTaskStream.ts`

### API and identity

- [FastAPI app](https://github.com/yad4o/map/blob/main/backend/app/main.py): `backend/app/main.py`
- [Task routes](https://github.com/yad4o/map/blob/main/backend/app/routes/tasks.py): `backend/app/routes/tasks.py`
- [Auth service](https://github.com/yad4o/map/blob/main/backend/app/services/auth_service.py): `backend/app/services/auth_service.py`
- [OAuth exchange](https://github.com/yad4o/map/blob/main/backend/app/services/oauth_service.py): `backend/app/services/oauth_service.py`
- [Task service](https://github.com/yad4o/map/blob/main/backend/app/services/task_service.py): `backend/app/services/task_service.py`

### Task runtime

- [Celery task worker](https://github.com/yad4o/map/blob/main/backend/app/worker/tasks.py): `backend/app/worker/tasks.py`
- [Agent runner](https://github.com/yad4o/map/blob/main/backend/app/worker/agent_runner.py): `backend/app/worker/agent_runner.py`

### Agent pipeline

- [Agent controller](https://github.com/yad4o/map/blob/main/backend/agents/controller/agent_controller.py): `backend/agents/controller/agent_controller.py`
- [Planner](https://github.com/yad4o/map/blob/main/backend/agents/planner/planner_agent.py): `backend/agents/planner/planner_agent.py`
- [Executor and tools](https://github.com/yad4o/map/blob/main/backend/agents/executor/executor_agent.py): `backend/agents/executor/executor_agent.py`
- [Analyzer](https://github.com/yad4o/map/blob/main/backend/agents/analyzer/analyzer_agent.py): `backend/agents/analyzer/analyzer_agent.py`
- [Memory agent](https://github.com/yad4o/map/blob/main/backend/agents/memory/memory_agent.py): `backend/agents/memory/memory_agent.py`

### State and providers

- [Vector store](https://github.com/yad4o/map/blob/main/backend/agents/memory/vector_store.py): `backend/agents/memory/vector_store.py`
- [Task and user data](https://github.com/yad4o/map/blob/main/backend/app/db/models/task.py): `backend/app/db/models/task.py`
- [Redis queue and streams](https://github.com/yad4o/map/blob/main/backend/app/core/redis_client.py): `backend/app/core/redis_client.py`
- [Fallback engine](https://github.com/yad4o/map/blob/main/backend/app/core/fallback_engine.py): `backend/app/core/fallback_engine.py`
- [LLM provider selection](https://github.com/yad4o/map/blob/main/app/core/llm_provider.py): `app/core/llm_provider.py`

### Other components

- **User**
- **LLM providers**
- **BentoML fallback**

## Connections

- User → React dashboard: submits task
- React dashboard → Task views: opens task views (evidence: `frontend/src/App.tsx`)
- Task views → Task API client: requests task data
- Task API client → Task routes: calls task endpoints
- Task routes → Task service: delegates task operations (evidence: `backend/app/routes/tasks.py`)
- FastAPI app → Task routes: registers routes (evidence: `backend/app/main.py`)
- FastAPI app → Auth service: registers auth routes (evidence: `backend/app/main.py`)
- OAuth exchange → Auth service: returns verified profile (evidence: `backend/app/services/oauth_service.py`)
- Task service → Task and user data: persists task data
- Task routes → Celery task worker: queues task (evidence: `backend/app/routes/tasks.py`)
- Celery task worker → Agent runner: runs task (evidence: `backend/app/worker/tasks.py`)
- Agent runner → Agent controller: starts agent workflow
- Agent controller → Planner: plans task (evidence: `backend/agents/controller/agent_controller.py`)
- Agent controller → Executor and tools: executes plan (evidence: `backend/agents/controller/agent_controller.py`)
- Agent controller → Analyzer: validates results (evidence: `backend/agents/controller/agent_controller.py`)
- Agent controller → Memory agent: retrieves context (evidence: `backend/agents/controller/agent_controller.py`)
- Memory agent → Vector store: retrieves memories
- Agent controller → Task and user data: records agent steps (evidence: `backend/agents/controller/agent_controller.py`)
- Celery task worker → Task and user data: saves results and status (evidence: `backend/app/worker/tasks.py`)
- Celery task worker → Redis queue and streams: uses distributed queue
- Task routes → Redis queue and streams: streams task events (evidence: `backend/app/routes/tasks.py`)
- Task routes → Live stream hook: serves event stream
- Live stream hook → Task views: updates live answer (evidence: `frontend/src/hooks/useTaskStream.ts`)
- Agent controller → Fallback engine: requests inference
- Fallback engine → LLM provider selection: selects provider
- LLM provider selection → LLM providers: calls configured model (evidence: `app/core/llm_provider.py`)
- Fallback engine → BentoML fallback: uses local fallback
