# mhkaycey/ai-content-planner architecture

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

- Interactive diagram: https://gitdiagram.com/mhkaycey/ai-content-planner
- Repository: https://github.com/mhkaycey/ai-content-planner

## Overview

#### Purpose and Runtime
This is a TypeScript Mastra AI service that turns a user-supplied topic into a concise summary and cross-platform content ideas. It runs through Mastra’s development/build/deployment runtime and calls Google Gemini using `GEMINI_API_KEY`. Primary bootstrap: `src/mastra/index.ts`.

#### Public Agent Boundary
The externally consumable interface is an Agent-to-Agent (A2A) endpoint for `contentPlanner`. Clients send JSON-RPC `message/send` requests containing user text; the route adapts that protocol into the Mastra agent execution path. Relevant boundary: `src/mastra/routes/a2a-agent-route.ts`.

#### Agent Orchestration
The content-planning agent owns conversational behavior: requesting a topic when absent, framing the strategist task, and invoking its specialized tool. It is the main reasoning/orchestration component rather than a general web controller. Path: `src/mastra/agents/contentPlannerAgent.ts`.

#### Content Generation Tool
`contentPlannerTool` is the modular capability responsible for Gemini-backed generation of topic insights and platform-specific recommendations, such as captions, post concepts, and hashtags. This separates model/API work from agent instructions and enables reuse in larger Mastra pipelines. Path: `src/mastra/tools/contentPlannerTool.ts`.

#### Workflow Layer
A dedicated Mastra workflow packages the planning operation as an executable staged process. This is the natural extension point for adding validation, research, approvals, scheduling, or additional generation steps without changing the A2A contract. Path: `src/mastra/workflows/contentPlannerWorkflow.ts`.

#### Quality Evaluation
Scoring definitions provide a quality-control boundary for generated planner output, likely usable in Mastra evaluation/observability workflows. They distinguish output assessment from generation logic. Path: `src/mastra/scores/contentPlannerScores.ts`.

#### Composition and Deployment
The Mastra entrypoint registers or exports the agent, workflow, routes, and related capabilities for local development and Mastra deployment. `telex.json` represents the external workflow/agent integration configuration, including the A2A endpoint reference. Paths: `src/mastra/index.ts`, `telex.json`, `.env.example`.

Main entry points: [`src/mastra/routes/a2a-agent-route.ts`](https://github.com/mhkaycey/ai-content-planner/blob/main/src/mastra/routes/a2a-agent-route.ts) (A2A agent route), [`src/mastra/tools/contentPlannerTool.ts`](https://github.com/mhkaycey/ai-content-planner/blob/main/src/mastra/tools/contentPlannerTool.ts) (Content planner tool), [`src/mastra/index.ts`](https://github.com/mhkaycey/ai-content-planner/blob/main/src/mastra/index.ts) (Mastra entrypoint), [`src/mastra/workflows/contentPlannerWorkflow.ts`](https://github.com/mhkaycey/ai-content-planner/blob/main/src/mastra/workflows/contentPlannerWorkflow.ts) (Content planner workflow)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_public["Public Boundary"]
  node_a2a(("A2A clients<br/>external clients"))
  node_route{{"A2A agent route<br/>JSON-RPC adapter<br/>[a2a-agent-route.ts]"}}
end

subgraph group_planning["Planning Runtime"]
  node_entrypoint["Mastra entrypoint<br/>runtime composition<br/>[index.ts]"]
  node_agent["Content planner agent<br/>agent orchestration"]
  node_tool["Content planner tool<br/>generation capability"]
  node_gemini(("Google Gemini<br/>model API"))
  node_workflow["Content planner workflow<br/>staged workflow"]
end

subgraph group_quality["Quality &amp; Deployment"]
  node_telex["Telex integration config<br/>[telex.json]"]
  node_scores["Content planner scores<br/>quality scoring"]
  node_env["Environment template<br/>runtime credentials<br/>[.env.example]"]
end

node_a2a -->|"JSON-RPC message/send"| node_route
node_telex -->|"A2A endpoint"| node_route
node_route -->|"execute agent"| node_agent
node_entrypoint -.->|"registers"| node_route
node_entrypoint -.->|"registers"| node_agent
node_entrypoint -.->|"registers"| node_workflow
node_agent -->|"invokes"| node_tool
node_workflow -->|"planning stage"| node_tool
node_tool -->|"generate content"| node_gemini
node_env -.->|"GEMINI_API_KEY"| node_tool
node_workflow -.->|"evaluate output"| node_scores

click node_telex "https://github.com/mhkaycey/ai-content-planner/blob/main/telex.json"
click node_route "https://github.com/mhkaycey/ai-content-planner/blob/main/src/mastra/routes/a2a-agent-route.ts"
click node_entrypoint "https://github.com/mhkaycey/ai-content-planner/blob/main/src/mastra/index.ts"
click node_agent "https://github.com/mhkaycey/ai-content-planner/blob/main/src/mastra/agents/contentPlannerAgent.ts"
click node_tool "https://github.com/mhkaycey/ai-content-planner/blob/main/src/mastra/tools/contentPlannerTool.ts"
click node_workflow "https://github.com/mhkaycey/ai-content-planner/blob/main/src/mastra/workflows/contentPlannerWorkflow.ts"
click node_scores "https://github.com/mhkaycey/ai-content-planner/blob/main/src/mastra/scores/contentPlannerScores.ts"
click node_env "https://github.com/mhkaycey/ai-content-planner/blob/main/.env.example"

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_a2a,node_route toneBlue
class node_entrypoint,node_agent,node_tool,node_gemini,node_workflow toneAmber
class node_telex,node_scores,node_env toneMint
```

## Components

### Public Boundary

- **A2A clients**: external clients
- [A2A agent route](https://github.com/mhkaycey/ai-content-planner/blob/main/src/mastra/routes/a2a-agent-route.ts): JSON-RPC adapter · Adapts message/send requests into Mastra agent execution. · `src/mastra/routes/a2a-agent-route.ts`

### Planning Runtime

- [Mastra entrypoint](https://github.com/mhkaycey/ai-content-planner/blob/main/src/mastra/index.ts): runtime composition · Registers agents, workflows, and routes for Mastra runtime. · `src/mastra/index.ts`
- [Content planner agent](https://github.com/mhkaycey/ai-content-planner/blob/main/src/mastra/agents/contentPlannerAgent.ts): agent orchestration · Manages conversation and invokes the planning capability. · `src/mastra/agents/contentPlannerAgent.ts`
- [Content planner tool](https://github.com/mhkaycey/ai-content-planner/blob/main/src/mastra/tools/contentPlannerTool.ts): generation capability · Generates topic insights and platform-specific recommendations. · `src/mastra/tools/contentPlannerTool.ts`
- **Google Gemini**: model API
- [Content planner workflow](https://github.com/mhkaycey/ai-content-planner/blob/main/src/mastra/workflows/contentPlannerWorkflow.ts): staged workflow · Extension point for validation, research, approvals, and scheduling. · `src/mastra/workflows/contentPlannerWorkflow.ts`

### Quality & Deployment

- [Telex integration config](https://github.com/mhkaycey/ai-content-planner/blob/main/telex.json): integration config · Declares the external A2A integration. · `telex.json`
- [Content planner scores](https://github.com/mhkaycey/ai-content-planner/blob/main/src/mastra/scores/contentPlannerScores.ts): quality scoring · Assesses generated planner output independently of generation. · `src/mastra/scores/contentPlannerScores.ts`
- [Environment template](https://github.com/mhkaycey/ai-content-planner/blob/main/.env.example): runtime credentials · Documents GEMINI_API_KEY configuration. · `.env.example`

## Connections

- A2A clients → A2A agent route: JSON-RPC message/send
- Telex integration config → A2A agent route: A2A endpoint
- A2A agent route → Content planner agent: execute agent
- Mastra entrypoint → A2A agent route: registers
- Mastra entrypoint → Content planner agent: registers
- Mastra entrypoint → Content planner workflow: registers
- Content planner agent → Content planner tool: invokes
- Content planner workflow → Content planner tool: planning stage
- Content planner tool → Google Gemini: generate content
- Environment template → Content planner tool: GEMINI_API_KEY
- Content planner workflow → Content planner scores: evaluate output