# logly/mureo architecture

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

- Interactive diagram: https://gitdiagram.com/logly/mureo
- Repository: https://github.com/logly/mureo

## Overview

mureo is a local-first control plane for AI-assisted advertising operations. An agent uses its MCP tools to inspect account data, analyze performance against strategy, and—when connected to live APIs—make safety-gated changes; outcomes and tool calls are recorded for review and rollback. Users can connect live platforms or analyze imported BYOD data, and can configure the local installation through a browser UI. The graph includes documented capabilities, but sampled excerpts are incomplete, so some subsystem connections are omitted where their implementation path is not evidenced.

Main entry points: [`mureo/mcp/server.py`](https://github.com/logly/mureo/blob/main/mureo/mcp/server.py) (MCP Server), [`mureo/client_factory.py`](https://github.com/logly/mureo/blob/main/mureo/client_factory.py) (Client Factory), [`mureo/analytics/registry.py`](https://github.com/logly/mureo/blob/main/mureo/analytics/registry.py) (Analytics), [`mureo/mcp/tools_google_ads.py`](https://github.com/logly/mureo/blob/main/mureo/mcp/tools_google_ads.py) (Platform Tools)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_access["Agent Access"]
  node_mcp["MCP Server<br/>[server.py]"]
  node_tool_surface["Platform Tools"]
end

subgraph group_platforms["Data Connections"]
  node_live_factory["Client Factory<br/>[client_factory.py]"]
  node_google["Google Ads<br/>[client.py]"]
  node_meta["Meta Ads<br/>[client.py]"]
  node_byod["BYOD Clients<br/>[clients.py]"]
  node_amazon["Amazon Ads Bridge<br/>[provider.py]"]
  node_search["Search Console<br/>[client.py]"]
  node_auth["Credentials<br/>[auth.py]"]
end

subgraph group_decision["Strategy and Analysis"]
  node_analytics["Analytics<br/>[registry.py]"]
  node_collapse["Delivery Analysis"]
  node_strategy[("Strategy and State<br/>[state.py]")]
  node_guardrails["Safety Policy<br/>[guardrails.py]"]
  node_learning["Account Learning<br/>[context_builder.py]"]
end

subgraph group_operations["Auditable Operations"]
  node_action_log[("Action Log")]
  node_journal[("Tool Journal<br/>[journal.py]")]
  node_rollback["Rollback<br/>[executor.py]"]
end

subgraph group_setup["Local Setup"]
  node_configure["Configure UI<br/>[server.py]"]
  node_routes["Setup Routes<br/>[handlers.py]"]
end

node_agent(("AI Agent"))

node_agent -->|"invokes tools"| node_mcp
node_mcp -->|"exposes tools"| node_tool_surface
node_tool_surface -->|"opens clients"| node_live_factory
node_live_factory -->|"creates client"| node_google
node_live_factory -->|"creates client"| node_meta
node_live_factory -->|"routes BYOD"| node_byod
node_agent -->|"requests analysis"| node_analytics
node_analytics -->|"opens live clients"| node_live_factory
node_analytics -->|"runs analysis"| node_collapse
node_collapse -->|"reads strategy"| node_strategy
node_mcp -->|"serves context"| node_strategy
node_agent -->|"follows safety gates"| node_guardrails
node_agent -->|"records actions"| node_action_log
node_mcp -->|"journals tool calls"| node_journal
node_agent -->|"requests rollback"| node_rollback
node_agent -->|"builds knowledge"| node_learning
node_configure -->|"dispatches routes"| node_routes
node_agent -->|"configures locally"| node_configure
node_routes -->|"sets up credentials"| node_auth
node_mcp -->|"bridges provider"| node_amazon
node_agent -->|"uses Search Console"| node_search

click node_mcp "https://github.com/logly/mureo/blob/main/mureo/mcp/server.py"
click node_tool_surface "https://github.com/logly/mureo/blob/main/mureo/mcp/tools_google_ads.py"
click node_live_factory "https://github.com/logly/mureo/blob/main/mureo/client_factory.py"
click node_google "https://github.com/logly/mureo/blob/main/mureo/google_ads/client.py"
click node_meta "https://github.com/logly/mureo/blob/main/mureo/meta_ads/client.py"
click node_byod "https://github.com/logly/mureo/blob/main/mureo/byod/clients.py"
click node_amazon "https://github.com/logly/mureo/blob/main/mureo/amazon_ads/provider.py"
click node_search "https://github.com/logly/mureo/blob/main/mureo/search_console/client.py"
click node_auth "https://github.com/logly/mureo/blob/main/mureo/auth.py"
click node_analytics "https://github.com/logly/mureo/blob/main/mureo/analytics/registry.py"
click node_collapse "https://github.com/logly/mureo/blob/main/mureo/analysis/delivery_collapse.py"
click node_strategy "https://github.com/logly/mureo/blob/main/mureo/context/state.py"
click node_guardrails "https://github.com/logly/mureo/blob/main/mureo/policy/guardrails.py"
click node_learning "https://github.com/logly/mureo/blob/main/mureo/learning/context_builder.py"
click node_action_log "https://github.com/logly/mureo/blob/main/mureo/context/action_log_store.py"
click node_journal "https://github.com/logly/mureo/blob/main/mureo/mcp/journal.py"
click node_rollback "https://github.com/logly/mureo/blob/main/mureo/rollback/executor.py"
click node_configure "https://github.com/logly/mureo/blob/main/mureo/web/server.py"
click node_routes "https://github.com/logly/mureo/blob/main/mureo/web/handlers.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_mcp,node_tool_surface toneBlue
class node_live_factory,node_google,node_meta,node_byod,node_amazon,node_search,node_auth toneAmber
class node_analytics,node_collapse,node_strategy,node_guardrails,node_learning toneMint
class node_action_log,node_journal,node_rollback toneRose
class node_configure,node_routes,node_agent toneIndigo
```

## Components

### Agent Access

- [MCP Server](https://github.com/logly/mureo/blob/main/mureo/mcp/server.py): `mureo/mcp/server.py`
- [Platform Tools](https://github.com/logly/mureo/blob/main/mureo/mcp/tools_google_ads.py): `mureo/mcp/tools_google_ads.py`

### Data Connections

- [Client Factory](https://github.com/logly/mureo/blob/main/mureo/client_factory.py): `mureo/client_factory.py`
- [Google Ads](https://github.com/logly/mureo/blob/main/mureo/google_ads/client.py): `mureo/google_ads/client.py`
- [Meta Ads](https://github.com/logly/mureo/blob/main/mureo/meta_ads/client.py): `mureo/meta_ads/client.py`
- [BYOD Clients](https://github.com/logly/mureo/blob/main/mureo/byod/clients.py): `mureo/byod/clients.py`
- [Amazon Ads Bridge](https://github.com/logly/mureo/blob/main/mureo/amazon_ads/provider.py): `mureo/amazon_ads/provider.py`
- [Search Console](https://github.com/logly/mureo/blob/main/mureo/search_console/client.py): `mureo/search_console/client.py`
- [Credentials](https://github.com/logly/mureo/blob/main/mureo/auth.py): `mureo/auth.py`

### Strategy and Analysis

- [Analytics](https://github.com/logly/mureo/blob/main/mureo/analytics/registry.py): `mureo/analytics/registry.py`
- [Delivery Analysis](https://github.com/logly/mureo/blob/main/mureo/analysis/delivery_collapse.py): `mureo/analysis/delivery_collapse.py`
- [Strategy and State](https://github.com/logly/mureo/blob/main/mureo/context/state.py): `mureo/context/state.py`
- [Safety Policy](https://github.com/logly/mureo/blob/main/mureo/policy/guardrails.py): `mureo/policy/guardrails.py`
- [Account Learning](https://github.com/logly/mureo/blob/main/mureo/learning/context_builder.py): `mureo/learning/context_builder.py`

### Auditable Operations

- [Action Log](https://github.com/logly/mureo/blob/main/mureo/context/action_log_store.py): `mureo/context/action_log_store.py`
- [Tool Journal](https://github.com/logly/mureo/blob/main/mureo/mcp/journal.py): `mureo/mcp/journal.py`
- [Rollback](https://github.com/logly/mureo/blob/main/mureo/rollback/executor.py): `mureo/rollback/executor.py`

### Local Setup

- [Configure UI](https://github.com/logly/mureo/blob/main/mureo/web/server.py): `mureo/web/server.py`
- [Setup Routes](https://github.com/logly/mureo/blob/main/mureo/web/handlers.py): `mureo/web/handlers.py`

### Other components

- **AI Agent**

## Connections

- AI Agent → MCP Server: invokes tools
- MCP Server → Platform Tools: exposes tools (evidence: `mureo/mcp/server.py`)
- Platform Tools → Client Factory: opens clients (evidence: `mureo/client_factory.py`)
- Client Factory → Google Ads: creates client (evidence: `mureo/client_factory.py`)
- Client Factory → Meta Ads: creates client (evidence: `mureo/client_factory.py`)
- Client Factory → BYOD Clients: routes BYOD (evidence: `mureo/client_factory.py`)
- AI Agent → Analytics: requests analysis
- Analytics → Client Factory: opens live clients
- Analytics → Delivery Analysis: runs analysis
- Delivery Analysis → Strategy and State: reads strategy (evidence: `mureo/analysis/delivery_collapse.py`)
- MCP Server → Strategy and State: serves context
- AI Agent → Safety Policy: follows safety gates
- AI Agent → Action Log: records actions
- MCP Server → Tool Journal: journals tool calls (evidence: `mureo/mcp/server.py`)
- AI Agent → Rollback: requests rollback
- AI Agent → Account Learning: builds knowledge
- Configure UI → Setup Routes: dispatches routes (evidence: `mureo/web/server.py`)
- AI Agent → Configure UI: configures locally
- Setup Routes → Credentials: sets up credentials (evidence: `mureo/web/handlers.py`)
- MCP Server → Amazon Ads Bridge: bridges provider (evidence: `mureo/mcp/server.py`)
- AI Agent → Search Console: uses Search Console