How ruvnet/marketing works
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: agents/index.ts Agent registry · swarm-coordinator.ts Swarm coordinator · services/index.ts Domain services · gcp/index.ts GCP adapter
Components 27
Operator / tooling plane
Claude automation assets, workflows, and persisted swarm state used to run and manage the repo.
- Claude assets · Prompting, commands, helpers, and skills for Claude Code / Claude-Flow operations.
.claude - Flow runtime · Claude-Flow daemon config and metrics used by the automation plane.
.claude-flow - Swarm state · External swarm state persisted outside the TypeScript app code.
.swarm/state.json - Plans · 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 · Top-level TypeScript entrypoint for the package.
src/index.ts - Start CLI · CLI command for starting the swarm runtime.
src/cli/swarm-start.ts - Status CLI · CLI command for checking swarm health and status.
src/cli/swarm-status.ts - Swarm coordinator · Central orchestration layer that routes tasks, manages lifecycle, and coordinates agent participation.
src/swarm/swarm-coordinator.ts - Agent registry · Aggregation point for the tiered agent hierarchy.
src/agents/index.ts - Base agent · Shared abstraction for all agents in the swarm.
src/agents/base-agent.ts - Tier 1 · Orchestration, quality, and memory agents.
src/agents/tier1 - Tier 2 · Analytical intelligence agents for simulation, risk, attention, and historical memory.
src/agents/tier2 - Tier 3 · Creative generation, mutation, and fatigue forecasting agents.
src/agents/tier3 - Tier 4 · Attribution, incrementality, and causal reasoning agents.
src/agents/tier4 - Tier 5 · Account health and cross-platform operations agents.
src/agents/tier5 - Core services · Event bus, logging, and shared state management used across the runtime.
src/core/index.ts - Event bus · Internal communication backbone between agents and services.
src/core/event-bus.ts - State manager · Shared swarm state for coordination, health, and operational context.
src/core/state-manager.ts - Domain services · Business-facing services for analytics, attribution, campaign, and creative workflows.
src/services/index.ts - Security · Input validation, secrets handling, and audit logging.
src/security/index.ts - Performance · 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 · Facade for external platform and infrastructure adapters.
src/integrations/index.ts - GCP adapter · Concrete Google Cloud integration layer.
src/integrations/gcp/index.ts - BigQuery · Analytics data access client.
src/integrations/gcp/bigquery-client.ts - Pub/Sub · Messaging and event transport client.
src/integrations/gcp/pubsub-client.ts - Storage · Artifact and file storage client.
src/integrations/gcp/storage-client.ts - Vertex AI · ML inference and model access client.
src/integrations/gcp/vertex-ai-client.ts
Connections 29
- 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.