Skip to content

CLAUDE.md

Latest commit

 

History

History
70 lines (48 loc) · 5.07 KB

CLAUDE.md

File metadata and controls

70 lines (48 loc) · 5.07 KB
Raw

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Build & Test Commands

# Build
dotnet build SocialAgent.slnx

# Run all tests
dotnet test SocialAgent.slnx

# Run a single test by fully qualified name
dotnet test SocialAgent.slnx --filter "FullyQualifiedName~AnalyticsServiceTests.GetEngagementSummary_WithPosts_CalculatesAverages"

# Run tests by class
dotnet test SocialAgent.slnx --filter "ClassName~AnalyticsServiceTests"

# Run with verbose output
dotnet test SocialAgent.slnx --verbosity normal

Architecture

SocialAgent is an A2A-enabled social media monitoring agent built on .NET 10. It hosts the A2A 1.0 protocol via the Microsoft Agent Framework (Microsoft.Agents.AI.Hosting.A2A.AspNetCore) and the upstream A2A .NET SDK (A2A, A2A.AspNetCore), running as an ASP.NET Core application in Kubernetes.

Core design principle: Plugin-based provider architecture with normalized data models. Each social media platform is an independent provider assembly.

Project Structure

  • src/SocialAgent.Core/ — Domain models (SocialPost, SocialNotification, SocialProfile, EngagementSummary), provider interface (ISocialMediaProvider), analytics interface (IAnalyticsService)
  • src/SocialAgent.Data/ — EF Core SocialAgentDbContext, repository pattern (ISocialDataRepository), supports PostgreSQL (prod) and SQLite (dev)
  • src/SocialAgent.Analytics/ — Analytics engine computing engagement summaries, top posts, follower insights, platform comparisons
  • src/SocialAgent.Providers.Mastodon/ — Mastodon REST API client implementing ISocialMediaProvider
  • src/SocialAgent.Providers.Bluesky/ — Bluesky AT Protocol client implementing ISocialMediaProvider
  • src/SocialAgent.Providers.Threads/ — Threads Graph API v1.0 client implementing ISocialMediaProvider. Adds ThreadsTokenStore (in-memory current token + expiry) and a RefreshTokenAsync method on the provider; the host owns the refresh schedule via ThreadsTokenRefreshService.
  • src/SocialAgent.Host/ — ASP.NET Core host, A2A request handler (SocialAgentA2AHandler implementing A2A.IAgentHandler), skill dispatcher (SkillDispatcher), skill metadata (SkillCatalog), stub AIAgent (SocialAgentStubAgent, framework-required name carrier), background polling service, and ThreadsTokenRefreshService (registered only when Threads is enabled — seeds the token from DB on startup, refreshes ahead of RefreshThresholdDays, persists via ISocialDataRepository)
  • tests/ — MSTest unit tests with NSubstitute for mocking
  • deploy/k8s/ — Kubernetes manifests (Deployment, Service, ConfigMap, Secret)

A2A Protocol

The agent speaks A2A protocol version 1.0. Endpoints:

  • GET /.well-known/agent-card.json — Agent card (A2A 1.0 discovery path)
  • POST /a2a — JSON-RPC binding (methods: SendMessage, GetTask, etc., per A2A.A2AMethods)
  • POST /a2a/message:send, /a2a/tasks/{id}, etc. — HTTP+JSON binding routes

Both transports are mapped to the same /a2a prefix; clients pick whichever they prefer.

Seven skills are exposed: engagement-summary, top-posts, recent-mentions, follower-insights, platform-comparison, check-notifications, provider-status. Skill dispatch is deterministic (keyword match, optionally LLM-assisted via SkillRouter) — there is no LLM in the request path by default. The AIAgent registered with the framework is a stub used only as a name carrier; all request handling flows through SocialAgentA2AHandler.

Provider Plugin Pattern

Each provider implements ISocialMediaProvider and is registered via DI extension methods. Providers are conditionally enabled via configuration. The polling service iterates all registered providers on a configurable interval.

Key Conventions

  • Nullable reference types enabled — respect null-safety throughout
  • ImplicitUsings enabled — no common using statements needed
  • TreatWarningsAsErrors enabled — all warnings are build errors
  • Central Package Management — all package versions in Directory.Packages.props
  • Async-first — all I/O is Task-based
  • NSubstitute is the mocking framework for tests
  • Configuration — standard .NET config stack: appsettings.json, environment variables, user secrets, k8s Secrets
  • Database — EF Core with SQLite for dev, PostgreSQL for prod. DatabaseMigrationService runs EnsureCreatedAsync plus dialect-aware CREATE TABLE IF NOT EXISTS patches for tables added after the initial deployment (e.g. ProviderTokens in 1.4.0). When adding a new table, extend DatabaseMigrationService.EnsureProviderTokensTableAsync-style patch logic so existing live databases pick up the change. This is an interim approach until proper EF Core migrations are adopted.

Future Integration

This agent is designed to collaborate with RockBot via the A2A protocol. RockBot can discover this agent's capabilities via the agent card endpoint and invoke skills via /a2a.