Integration Guide

Quick guide for integrating the CompletionStatistics component into the AgentSwarm workflow.

Quick Start

1. Import the Component

import CompletionStatistics from '@/components/CompletionStatistics';

2. Use in Your Page/Component

function AgentSwarmCompletionPage({ projectId }: { projectId: string }) {
  const stats = {
    total_time_minutes: 45,
    agents_deployed: 8,
    features_completed: 12,
    features_total: 12,
    tests_passed: 48,
    tests_total: 50,
    code_quality_score: 92,
    github_issues_created: 5,
    pull_requests_merged: 3,
  };

  return (
    <div className="container mx-auto p-8">
      <CompletionStatistics stats={stats} />
    </div>
  );
}

Integration with AgentSwarm Workflow

Step 1: Add to Stage 11 (Completion)

In your AgentSwarm workflow component, add the CompletionStatistics display when stage reaches 11:

import CompletionStatistics from '@/components/CompletionStatistics';

function AgentSwarmWorkflow({ projectId }: { projectId: string }) {
  const [currentStage, setCurrentStage] = useState(1);
  const [completionStats, setCompletionStats] = useState(null);

  // When workflow reaches stage 11
  useEffect(() => {
    if (currentStage === 11) {
      fetchCompletionStats(projectId).then(setCompletionStats);
    }
  }, [currentStage, projectId]);

  return (
    <div>
      {/* Stages 1-10... */}

      {currentStage === 11 && completionStats && (
        <div className="mt-8">
          <CompletionStatistics stats={completionStats} />
        </div>
      )}
    </div>
  );
}

Step 2: Fetch Stats from API

Create a service to fetch completion statistics:

// src/services/AgentSwarmService.ts
import apiClient from '@/utils/apiClient';

export const agentSwarmService = {
  async getCompletionStats(projectId: string) {
    const { data } = await apiClient.get(
      `/v1/admin/agent-swarm/projects/${projectId}/completion-stats`
    );
    return data;
  },
};

Step 3: Use React Query for Data Fetching

import { useQuery } from '@tanstack/react-query';
import { agentSwarmService } from '@/services/AgentSwarmService';
import CompletionStatistics from '@/components/CompletionStatistics';

function Stage11Completion({ projectId }: { projectId: string }) {
  const { data, isLoading, error } = useQuery({
    queryKey: ['agentSwarmCompletion', projectId],
    queryFn: () => agentSwarmService.getCompletionStats(projectId),
    enabled: !!projectId,
  });

  if (isLoading) {
    return (
      <div className="flex items-center justify-center py-12">
        <Loader2 className="w-8 h-8 animate-spin text-green-400" />
        <span className="ml-3 text-gray-400">Loading completion statistics...</span>
      </div>
    );
  }

  if (error) {
    return (
      <div className="text-center py-12">
        <p className="text-red-400">Failed to load completion statistics</p>
      </div>
    );
  }

  if (!data) return null;

  return <CompletionStatistics stats={data} />;
}

Backend API Response Format

Your backend should return data in this format:

{
  "total_time_minutes": 45,
  "agents_deployed": 8,
  "features_completed": 12,
  "features_total": 12,
  "tests_passed": 48,
  "tests_total": 50,
  "code_quality_score": 92,
  "github_issues_created": 5,
  "pull_requests_merged": 3
}

Example Backend Endpoint (Python/FastAPI)

from fastapi import APIRouter, Depends
from pydantic import BaseModel

router = APIRouter()

class CompletionStats(BaseModel):
    total_time_minutes: int
    agents_deployed: int
    features_completed: int
    features_total: int
    tests_passed: int
    tests_total: int
    code_quality_score: int  # 0-100
    github_issues_created: int
    pull_requests_merged: int

@router.get("/v1/admin/agent-swarm/projects/{project_id}/completion-stats")
async def get_completion_stats(project_id: str) -> CompletionStats:
    # Fetch from database or calculate from project data
    stats = calculate_project_stats(project_id)
    return stats

Responsive Layouts

Full Width Layout

<div className="w-full">
  <CompletionStatistics stats={stats} />
</div>

Centered Container

<div className="container max-w-7xl mx-auto px-4 py-8">
  <CompletionStatistics stats={stats} />
</div>

With Additional Actions

<div className="space-y-8">
  <CompletionStatistics stats={stats} />

  <div className="flex justify-center gap-4">
    <Button onClick={handleDownloadReport}>
      Download Report
    </Button>
    <Button onClick={handleViewDeployment} variant="outline">
      View Deployment
    </Button>
  </div>
</div>

State Management

With Local State

function CompletionPage() {
  const [stats, setStats] = useState<CompletionStats | null>(null);

  useEffect(() => {
    fetchStats().then(setStats);
  }, []);

  return stats ? <CompletionStatistics stats={stats} /> : <Loading />;
}

With WebSocket Updates

function LiveCompletionStats({ projectId }: { projectId: string }) {
  const [stats, setStats] = useState<CompletionStats | null>(null);

  useEffect(() => {
    const ws = new WebSocket(`ws://localhost:8000/ws/project/${projectId}/stats`);

    ws.onmessage = (event) => {
      const data = JSON.parse(event.data);
      if (data.type === 'completion_stats') {
        setStats(data.stats);
      }
    };

    return () => ws.close();
  }, [projectId]);

  return stats ? <CompletionStatistics stats={stats} /> : <Loading />;
}

Testing Your Integration

1. Mock Data Test

// Quick test with mock data
const mockStats = {
  total_time_minutes: 45,
  agents_deployed: 8,
  features_completed: 12,
  features_total: 12,
  tests_passed: 48,
  tests_total: 50,
  code_quality_score: 92,
  github_issues_created: 5,
  pull_requests_merged: 3,
};

<CompletionStatistics stats={mockStats} />

2. Test Different States

// Perfect completion
const perfect = { ...mockStats, features_completed: 12, tests_passed: 50 };

// Partial completion
const partial = { ...mockStats, features_completed: 8, tests_passed: 40 };

// Quick build
const quick = { ...mockStats, total_time_minutes: 15, agents_deployed: 3 };

3. Use Demo Page

Visit the demo page for interactive testing:

http://localhost:5177/completion-statistics-demo

Common Issues

Issue: Stats Not Updating

Solution: Ensure React Query cache is invalidated or use refetchInterval:

const { data } = useQuery({
  queryKey: ['completionStats', projectId],
  queryFn: () => fetchStats(projectId),
  refetchInterval: 5000, // Refetch every 5 seconds
});

Issue: Layout Breaking on Mobile

Solution: Add proper container padding:

<div className="w-full px-4 md:px-6 lg:px-8">
  <CompletionStatistics stats={stats} />
</div>

Issue: Animations Not Working

Solution: Ensure Framer Motion is installed and imported correctly. The component handles all animations internally.

Performance Tips

1. Memoize Stats: If stats don't change frequently:

const memoizedStats = useMemo(() => stats, [stats.code_quality_score]);

2. Lazy Load: If part of a larger page:

const CompletionStatistics = lazy(() => import('@/components/CompletionStatistics'));

3. Preload Data: Fetch stats before stage 11:

useEffect(() => {
  if (currentStage === 10) {
    queryClient.prefetchQuery(['completionStats', projectId]);
  }
}, [currentStage]);

Adding to App Routes

If you want the demo page accessible:

// src/App.tsx
import CompletionStatisticsDemo from '@/pages/CompletionStatisticsDemo';

// Inside your routes
<Route
  path="/completion-statistics-demo"
  element={
    <>
      <Header />
      <CompletionStatisticsDemo />
      <Footer />
    </>
  }
/>

Customization

Custom Container

<div className="bg-gray-900 p-8 rounded-lg">
  <CompletionStatistics stats={stats} />
</div>

With Header

<div className="space-y-6">
  <div className="text-center">
    <h1 className="text-3xl font-bold mb-2">Project Complete</h1>
    <p className="text-gray-400">Review your build statistics below</p>
  </div>
  <CompletionStatistics stats={stats} />
</div>

Support

• Component: /src/components/CompletionStatistics.tsx
• Documentation: /src/components/CompletionStatistics.README.md
• Examples: /src/components/CompletionStatistics.example.tsx
• Tests: /src/components/__tests__/CompletionStatistics.test.tsx
• Demo: /src/pages/CompletionStatisticsDemo.tsx

---

Ready to integrate! Follow the steps above to add the CompletionStatistics component to your AgentSwarm workflow.