# ruvnet/marketing architecture

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

- Interactive diagram: https://gitdiagram.com/ruvnet/marketing
- Repository: https://github.com/ruvnet/marketing

## Overview

1. **Repo shape**
   - This is a TypeScript/Node.js package for an AI “swarm” that optimizes marketing campaigns.
   - The codebase is split between the product runtime under `src/` and a large Claude-Flow/Claude Code automation layer under `.claude/` and `.claude-flow/`.

2. **Primary runtime boundary**
   - The executable application lives in `src/index.ts` and is exposed as a library/CLI hybrid.
   - The main runtime entry points are the swarm orchestration APIs plus CLI commands in `src/cli/` for starting and checking swarm status.

3. **Orchestration layer**
   - `src/swarm/swarm-coordinator.ts` is the central control plane.
   - It coordinates task routing, lifecycle, and agent participation across the system, matching the “hierarchical mesh” described in the README.
   - This is the most important architectural node for diagramming: most domain work flows through it.

4. **Agent hierarchy**
   - Agents are organized into five tiers under `src/agents/`.
   - Tier 1 handles coordination/quality/memory, Tier 2 handles analytical intelligence, Tier 3 handles creative generation and fatigue prediction, Tier 4 handles attribution/causal analysis, and Tier 5 handles account health and cross-platform operations.
   - `src/agents/base-agent.ts` provides the shared abstraction, while `src/agents/index.ts` is the aggregation point.

5. **Shared core services**
   - `src/core/` contains the event bus, logging, and state management.
   - `event-bus.ts` is the main internal communication backbone between agents and services.
   - `state-manager.ts` represents shared swarm state, likely used for coordination, health, and persistence of operational context.

6. **Domain services**
   - `src/services/` contains business-facing workflow services: analytics, attribution, campaign, and creative.
   - These services are the main domain boundary between agent decisions and external systems/data sources.
   - In a diagram, they sit between the agent layer and platform/data integrations.

7. **External integrations**
   - `src/integrations/gcp/` is the concrete infrastructure adapter layer.
   - It includes BigQuery, Pub/Sub, Cloud Storage, and Vertex AI clients, which suggests the system can read analytics data, exchange events, store artifacts, and call ML inference services on GCP.
   - `src/integrations/index.ts` and `src/integrations/gcp/index.ts` act as integration facades.

8. **Cross-cutting platform concerns**
   - `src/security/` contains input validation, secrets handling, and audit logging.
   - `src/performance/` contains batching, caching, and connection pooling, which indicates the system is designed for sustained high-throughput processing rather than simple request/response usage.
   - These are shared infrastructure layers used by services, agents, and integrations.

9. **Control and observability flow**
   - The README’s runtime model is: user/automation submits a campaign task, the swarm coordinator routes it to the right agent tier, agents exchange signals through the event bus and shared state, then services perform domain actions and integration calls.
   - Health/status surfaces exist through the CLI and the tiered agent health/quality roles.
   - The `.claude-flow/metrics/` and `.swarm/state.json` files show that operational state and metrics are persisted outside the TypeScript app code as part of the swarm runtime.

10. **Claude automation layer**
   - `.claude/agents/`, `.claude/commands/`, `.claude/helpers/`, and `.claude/skills/` are not product runtime code; they are orchestration, prompting, and automation assets for Claude Code / Claude-Flow.
   - These files define agent behaviors, command shortcuts, hooks, and workflow utilities used to operate the repo and swarm.
   - For architecture diagrams, this should be shown as an operator/tooling plane rather than part of the core application data path.

11. **Planning and design artifacts**
   - `plans/` contains ADRs and domain-driven design documents for architecture, Google Cloud, API security, and specific marketing domains.
   - These are specification and decision records, not runtime components, but they explain intended boundaries such as event-driven design, Rust/WASM strategy, and Firestore/GCP choices.

12. **Testing and validation**
   - `tests/` mirrors the runtime layers: agents, core, integrations, services, and swarm coordinator.
   - This suggests the main architectural seams are stable and intended to be tested independently, especially around orchestration and integration boundaries.
   - `vitest.config.ts` confirms Vitest as the test runner.

13. **Likely deployment/runtime model**
   - The repo is built as a Node.js 20+ TypeScript service/CLI package, not a browser app.
   - The documented startup flow uses `npm` plus Claude-Flow daemon/swarm initialization, implying long-running swarm processes and stateful coordination rather than short-lived scripts.

14. **Most important diagram boundaries**
   - Show three major zones: operator/tooling (`.claude`, `.claude-flow`), application runtime (`src/`), and external infrastructure (GCP services and ad platform APIs implied by the domain).
   - Inside runtime, the key flow is: CLI/API entry → swarm coordinator → tiered agents → core event/state/logging → domain services → GCP/platform integrations.

Main entry points: [`src/agents/index.ts`](https://github.com/ruvnet/marketing/blob/main/src/agents/index.ts) (Agent registry), [`src/swarm/swarm-coordinator.ts`](https://github.com/ruvnet/marketing/blob/main/src/swarm/swarm-coordinator.ts) (Swarm coordinator), [`src/services/index.ts`](https://github.com/ruvnet/marketing/blob/main/src/services/index.ts) (Domain services), [`src/integrations/gcp/index.ts`](https://github.com/ruvnet/marketing/blob/main/src/integrations/gcp/index.ts) (GCP adapter)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_tooling["Operator / tooling plane"]
  node_claude["Claude assets<br/>automation assets<br/>[.claude]"]
  node_claude_flow[("Flow runtime<br/>daemon/runtime state<br/>[.claude-flow]")]
  node_swarm_state[("Swarm state<br/>persisted runtime state<br/>[state.json]")]
  node_plans["Plans<br/>architecture docs"]
end

subgraph group_runtime["Application runtime"]
  node_app_entry["App entry<br/>library / CLI entry<br/>[index.ts]"]
  node_cli_start["Start CLI<br/>command<br/>[swarm-start.ts]"]
  node_cli_status["Status CLI<br/>command<br/>[swarm-status.ts]"]
  node_coordinator{{"Swarm coordinator<br/>control plane"}}
  node_agent_index["Agent registry<br/>agent facade<br/>[index.ts]"]
  node_base_agent["Base agent<br/>agent base<br/>[base-agent.ts]"]
  node_tier1(("Tier 1<br/>coordination tier"))
  node_tier2(("Tier 2<br/>analysis tier"))
  node_tier3(("Tier 3<br/>creative tier"))
  node_tier4(("Tier 4<br/>causal tier"))
  node_tier5(("Tier 5<br/>ops tier"))
  node_core["Core services<br/>shared core<br/>[index.ts]"]
  node_event_bus(("Event bus<br/>messaging backbone<br/>[event-bus.ts]"))
  node_state_manager[("State manager<br/>shared state<br/>[state-manager.ts]")]
  node_services["Domain services<br/>workflow services<br/>[index.ts]"]
  node_security["Security<br/>cross-cutting<br/>[index.ts]"]
  node_performance["Performance<br/>cross-cutting<br/>[index.ts]"]
end

subgraph group_infra["External infrastructure"]
  node_integrations["Integrations<br/>adapter facade<br/>[index.ts]"]
  node_gcp["GCP adapter<br/>cloud adapter<br/>[index.ts]"]
  node_gcp_bigquery[("BigQuery<br/>analytics client<br/>[bigquery-client.ts]")]
  node_gcp_pubsub["Pub/Sub<br/>event client<br/>[pubsub-client.ts]"]
  node_gcp_storage[("Storage<br/>artifact client<br/>[storage-client.ts]")]
  node_gcp_vertex["Vertex AI<br/>ml client"]
end

node_app_entry -->|"bootstraps"| node_coordinator
node_cli_start -->|"starts"| node_coordinator
node_cli_status -->|"reads status"| node_state_manager
node_coordinator -->|"dispatches"| node_agent_index
node_coordinator -->|"publishes"| node_event_bus
node_coordinator -->|"updates"| node_state_manager
node_agent_index -->|"extends"| node_base_agent
node_agent_index -->|"organizes"| node_tier1
node_agent_index -->|"organizes"| node_tier2
node_agent_index -->|"organizes"| node_tier3
node_agent_index -->|"organizes"| node_tier4
node_agent_index -->|"organizes"| node_tier5
node_tier1 -->|"signals"| node_event_bus
node_tier2 -->|"analyzes"| node_services
node_tier3 -->|"creates"| node_services
node_tier4 -->|"attributes"| node_services
node_tier5 -->|"operates"| node_services
node_services -->|"calls"| node_integrations
node_services -.->|"validates"| node_security
node_services -.->|"optimizes"| node_performance
node_integrations -->|"routes"| node_gcp
node_gcp -->|"reads"| node_gcp_bigquery
node_gcp -->|"publishes"| node_gcp_pubsub
node_gcp -->|"stores"| node_gcp_storage
node_gcp -->|"inferences"| node_gcp_vertex
node_event_bus -->|"syncs"| node_state_manager
node_claude -.->|"operates"| node_coordinator
node_claude_flow -.->|"persists"| node_swarm_state
node_plans -.->|"informs"| node_coordinator

click node_claude "https://github.com/ruvnet/marketing/blob/main/.claude"
click node_claude_flow "https://github.com/ruvnet/marketing/blob/main/.claude-flow"
click node_swarm_state "https://github.com/ruvnet/marketing/blob/main/.swarm/state.json"
click node_plans "https://github.com/ruvnet/marketing/tree/main/plans"
click node_app_entry "https://github.com/ruvnet/marketing/blob/main/src/index.ts"
click node_cli_start "https://github.com/ruvnet/marketing/blob/main/src/cli/swarm-start.ts"
click node_cli_status "https://github.com/ruvnet/marketing/blob/main/src/cli/swarm-status.ts"
click node_coordinator "https://github.com/ruvnet/marketing/blob/main/src/swarm/swarm-coordinator.ts"
click node_agent_index "https://github.com/ruvnet/marketing/blob/main/src/agents/index.ts"
click node_base_agent "https://github.com/ruvnet/marketing/blob/main/src/agents/base-agent.ts"
click node_tier1 "https://github.com/ruvnet/marketing/tree/main/src/agents/tier1"
click node_tier2 "https://github.com/ruvnet/marketing/tree/main/src/agents/tier2"
click node_tier3 "https://github.com/ruvnet/marketing/tree/main/src/agents/tier3"
click node_tier4 "https://github.com/ruvnet/marketing/tree/main/src/agents/tier4"
click node_tier5 "https://github.com/ruvnet/marketing/tree/main/src/agents/tier5"
click node_core "https://github.com/ruvnet/marketing/blob/main/src/core/index.ts"
click node_event_bus "https://github.com/ruvnet/marketing/blob/main/src/core/event-bus.ts"
click node_state_manager "https://github.com/ruvnet/marketing/blob/main/src/core/state-manager.ts"
click node_services "https://github.com/ruvnet/marketing/blob/main/src/services/index.ts"
click node_security "https://github.com/ruvnet/marketing/blob/main/src/security/index.ts"
click node_performance "https://github.com/ruvnet/marketing/blob/main/src/performance/index.ts"
click node_integrations "https://github.com/ruvnet/marketing/blob/main/src/integrations/index.ts"
click node_gcp "https://github.com/ruvnet/marketing/blob/main/src/integrations/gcp/index.ts"
click node_gcp_bigquery "https://github.com/ruvnet/marketing/blob/main/src/integrations/gcp/bigquery-client.ts"
click node_gcp_pubsub "https://github.com/ruvnet/marketing/blob/main/src/integrations/gcp/pubsub-client.ts"
click node_gcp_storage "https://github.com/ruvnet/marketing/blob/main/src/integrations/gcp/storage-client.ts"
click node_gcp_vertex "https://github.com/ruvnet/marketing/blob/main/src/integrations/gcp/vertex-ai-client.ts"

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_claude,node_claude_flow,node_swarm_state,node_plans toneBlue
class node_app_entry,node_cli_start,node_cli_status,node_coordinator,node_agent_index,node_base_agent,node_tier1,node_tier2,node_tier3,node_tier4,node_tier5,node_core,node_event_bus,node_state_manager,node_services,node_security,node_performance toneAmber
class node_integrations,node_gcp,node_gcp_bigquery,node_gcp_pubsub,node_gcp_storage,node_gcp_vertex toneMint
```

## Components

### Operator / tooling plane

Claude automation assets, workflows, and persisted swarm state used to run and manage the repo.

- [Claude assets](https://github.com/ruvnet/marketing/blob/main/.claude): automation assets · Prompting, commands, helpers, and skills for Claude Code / Claude-Flow operations. · `.claude`
- [Flow runtime](https://github.com/ruvnet/marketing/blob/main/.claude-flow): daemon/runtime state · Claude-Flow daemon config and metrics used by the automation plane. · `.claude-flow`
- [Swarm state](https://github.com/ruvnet/marketing/blob/main/.swarm/state.json): persisted runtime state · External swarm state persisted outside the TypeScript app code. · `.swarm/state.json`
- [Plans](https://github.com/ruvnet/marketing/tree/main/plans): architecture docs · ADRs and domain design documents that define intended boundaries and implementation direction. · `plans`

### Application runtime

The TypeScript/Node.js product runtime: CLI entrypoints, swarm control plane, agents, core services, and domain workflows.

- [App entry](https://github.com/ruvnet/marketing/blob/main/src/index.ts): library / CLI entry · Top-level TypeScript entrypoint for the package. · `src/index.ts`
- [Start CLI](https://github.com/ruvnet/marketing/blob/main/src/cli/swarm-start.ts): command · CLI command for starting the swarm runtime. · `src/cli/swarm-start.ts`
- [Status CLI](https://github.com/ruvnet/marketing/blob/main/src/cli/swarm-status.ts): command · CLI command for checking swarm health and status. · `src/cli/swarm-status.ts`
- [Swarm coordinator](https://github.com/ruvnet/marketing/blob/main/src/swarm/swarm-coordinator.ts): control plane · Central orchestration layer that routes tasks, manages lifecycle, and coordinates agent participation. · `src/swarm/swarm-coordinator.ts`
- [Agent registry](https://github.com/ruvnet/marketing/blob/main/src/agents/index.ts): agent facade · Aggregation point for the tiered agent hierarchy. · `src/agents/index.ts`
- [Base agent](https://github.com/ruvnet/marketing/blob/main/src/agents/base-agent.ts): agent base · Shared abstraction for all agents in the swarm. · `src/agents/base-agent.ts`
- [Tier 1](https://github.com/ruvnet/marketing/tree/main/src/agents/tier1): coordination tier · Orchestration, quality, and memory agents. · `src/agents/tier1`
- [Tier 2](https://github.com/ruvnet/marketing/tree/main/src/agents/tier2): analysis tier · Analytical intelligence agents for simulation, risk, attention, and historical memory. · `src/agents/tier2`
- [Tier 3](https://github.com/ruvnet/marketing/tree/main/src/agents/tier3): creative tier · Creative generation, mutation, and fatigue forecasting agents. · `src/agents/tier3`
- [Tier 4](https://github.com/ruvnet/marketing/tree/main/src/agents/tier4): causal tier · Attribution, incrementality, and causal reasoning agents. · `src/agents/tier4`
- [Tier 5](https://github.com/ruvnet/marketing/tree/main/src/agents/tier5): ops tier · Account health and cross-platform operations agents. · `src/agents/tier5`
- [Core services](https://github.com/ruvnet/marketing/blob/main/src/core/index.ts): shared core · Event bus, logging, and shared state management used across the runtime. · `src/core/index.ts`
- [Event bus](https://github.com/ruvnet/marketing/blob/main/src/core/event-bus.ts): messaging backbone · Internal communication backbone between agents and services. · `src/core/event-bus.ts`
- [State manager](https://github.com/ruvnet/marketing/blob/main/src/core/state-manager.ts): shared state · Shared swarm state for coordination, health, and operational context. · `src/core/state-manager.ts`
- [Domain services](https://github.com/ruvnet/marketing/blob/main/src/services/index.ts): workflow services · Business-facing services for analytics, attribution, campaign, and creative workflows. · `src/services/index.ts`
- [Security](https://github.com/ruvnet/marketing/blob/main/src/security/index.ts): cross-cutting · Input validation, secrets handling, and audit logging. · `src/security/index.ts`
- [Performance](https://github.com/ruvnet/marketing/blob/main/src/performance/index.ts): cross-cutting · Batching, caching, and connection pooling for sustained throughput. · `src/performance/index.ts`

### External infrastructure

Concrete platform integrations and runtime dependencies outside the app boundary.

- [Integrations](https://github.com/ruvnet/marketing/blob/main/src/integrations/index.ts): adapter facade · Facade for external platform and infrastructure adapters. · `src/integrations/index.ts`
- [GCP adapter](https://github.com/ruvnet/marketing/blob/main/src/integrations/gcp/index.ts): cloud adapter · Concrete Google Cloud integration layer. · `src/integrations/gcp/index.ts`
- [BigQuery](https://github.com/ruvnet/marketing/blob/main/src/integrations/gcp/bigquery-client.ts): analytics client · Analytics data access client. · `src/integrations/gcp/bigquery-client.ts`
- [Pub/Sub](https://github.com/ruvnet/marketing/blob/main/src/integrations/gcp/pubsub-client.ts): event client · Messaging and event transport client. · `src/integrations/gcp/pubsub-client.ts`
- [Storage](https://github.com/ruvnet/marketing/blob/main/src/integrations/gcp/storage-client.ts): artifact client · Artifact and file storage client. · `src/integrations/gcp/storage-client.ts`
- [Vertex AI](https://github.com/ruvnet/marketing/blob/main/src/integrations/gcp/vertex-ai-client.ts): ml client · ML inference and model access client. · `src/integrations/gcp/vertex-ai-client.ts`

## Connections

- App entry → Swarm coordinator: bootstraps · The package entrypoint exposes the swarm runtime and routes execution into the control plane.
- Start CLI → Swarm coordinator: starts · CLI startup initializes the swarm coordinator and runtime services.
- Status CLI → State manager: reads status · Status checks surface operational state and health.
- Swarm coordinator → Agent registry: dispatches · Routes tasks to the tiered agent hierarchy.
- Swarm coordinator → Event bus: publishes · Coordinates agent signaling through the internal event backbone.
- Swarm coordinator → State manager: updates · Maintains shared swarm lifecycle and coordination state.
- Agent registry → Base agent: extends · All agents share the common base abstraction.
- Agent registry → Tier 1: organizes · Tier 1 coordination, quality, and memory agents.
- Agent registry → Tier 2: organizes · Tier 2 analytical intelligence agents.
- Agent registry → Tier 3: organizes · Tier 3 creative and predictive agents.
- Agent registry → Tier 4: organizes · Tier 4 causal and attribution agents.
- Agent registry → Tier 5: organizes · Tier 5 account and cross-platform operations agents.
- Tier 1 → Event bus: signals · Coordination and quality roles exchange signals through the bus.
- Tier 2 → Domain services: analyzes · Analytical agents drive domain workflows through services.
- Tier 3 → Domain services: creates · Creative generation feeds campaign and content services.
- Tier 4 → Domain services: attributes · Causal analysis informs attribution services.
- Tier 5 → Domain services: operates · Account health and multi-platform tasks execute through domain services.
- Domain services → Integrations: calls · Domain workflows reach external adapters through the integration facade.
- Domain services → Security: validates · Service boundary applies validation, secrets handling, and audit logging.
- Domain services → Performance: optimizes · Services use shared throughput optimizations for sustained workloads.
- Integrations → GCP adapter: routes · Integration facade exposes the cloud adapter layer.
- GCP adapter → BigQuery: reads · Analytics data access.
- GCP adapter → Pub/Sub: publishes · Event transport and messaging.
- GCP adapter → Storage: stores · Artifact and file storage.
- GCP adapter → Vertex AI: inferences · Model and inference calls.
- Event bus → State manager: syncs · State and events remain coordinated across the swarm.
- Claude assets → Swarm coordinator: operates · Automation assets provide operator workflows for running the swarm.
- Flow runtime → Swarm state: persists · Automation runtime and swarm state are stored outside the app code.
- Plans → Swarm coordinator: informs · Design records define the intended control-plane architecture.
