TeamDynamics Docs

┌──────────────────────────────────────────────────────────────┐
│                    Next.js Frontend                         │
│  ┌─────────┐  ┌──────────┐  ┌──────────┐  ┌────────────┐  │
│  │  Login / │  │  Setup   │  │Simulation│  │  Report /  │  │
│  │Register │  │  Page    │  │  Page     │  │ Dashboard  │  │
│  └────┬────┘  └─────┬────┘  └─────┬─────┘  └──────┬─────┘  │
│       │  Auth Context (JWT)  │ WebSocket   │ REST API   │  │
└───────┼──────────────────────┼─────────────┼────────────┘  │
        │                      │             │               │
┌───────┼──────────────────────┼─────────────┼───────────────┐
│       ▼     FastAPI Backend  ▼             ▼               │
│  ┌─────────────────────────────────────────────────────┐   │
│  │         Auth Router ─── Simulation Router           │   │
│  │         Agent Router ── Document Router              │   │
│  │         WebSocket Router (Background Tasks)         │   │
│  ├─────────────────────────────────────────────────────┤   │
│  │              Simulation Engine (Orchestrator)       │   │
│  ├──────────┬──────────┬──────────┬───────────────────┤   │
│  │ Agent 1  │ Agent 2  │ Agent N  │ Per-Agent LLM     │   │
│  │ (LLM)    │ (LLM)    │ (LLM)    │ Model Override    │   │
│  ├──────────┴──────────┴──────────┴───────────────────┤   │
│  │   Personality-Weighted State Machine               │   │
│  │   (Morale, Stress, Loyalty, Productivity)          │   │
│  ├────────────────────────────────────────────────────┤   │
│  │   Decision Engine  │  World State  │ Round Agenda  │   │
│  │   (Proposals,      │  (Budget,     │ (5 Phases,    │   │
│  │    Voting,          │  Deadline,    │  Crisis-aware │   │
│  │    Hierarchy)       │  Reputation)  │  Modifiers)   │   │
│  ├────────────────────────────────────────────────────┤   │
│  │   Hidden Agendas │ Random Events │ Agent Memory    │   │
│  └────────────────────────────────────────────────────┘   │
│  ┌────────────────────────────────────────────────────┐   │
│  │  PostgreSQL (asyncpg)  │  Report Generator (LLM)  │   │
│  └────────────────────────────────────────────────────┘   │
└───────────────────────────────────────────────────────────┘

Round Start
  │
  ├─→ World State tick (deadline approaches, budget burns, debt creeps)
  │
  ├─→ Phase transition check (broadcast phase shift announcement)
  │
  ├─→ Roll for Random Event (may inject chaos)
  │
  ├─→ Each agent processes (sequentially):
  │   ├── Typing indicator broadcast
  │   ├── Reviews personality, memory, hidden agenda
  │   ├── Reads World State constraints & round agenda
  │   ├── Evaluates hierarchy position & decision context
  │   ├── Generates via LLM (per-agent model override)
  │   └── Produces: public_message, internal_thought,
  │                  state_changes, memory_update, action, action_detail
  │
  ├─→ Apply personality-weighted state changes
  ├─→ Process action through Decision Engine (proposals/votes/consequences)
  ├─→ Check for critical events (resignation, burnout)
  ├─→ Apply resignation effects to World State
  │
  ├─→ God Mode check: Player can intervene via WebSocket
  │
  └─→ Record metrics snapshot → Check end conditions → Next Round
       └─→ If final round or all resigned → Determine Outcome

interface CreateSimulationRequest {
  company: {
    name: string;           // 1-100 chars
    culture: string;        // 1-1000 chars
  };
  agents: {
    id: string;
    name: string;
    role: string;
    type: string;           // e.g. "Strict & Burned Out"
    color?: string;
    personality: {
      empathy: number;           // 0-100
      ambition: number;          // 0-100
      stressTolerance: number;   // 0-100
      agreeableness: number;     // 0-100
      assertiveness: number;     // 0-100
    };
    motivation?: string;    // Career motivation text
    expertise?: string;     // Domain expertise area
    model?: string;         // Per-agent LLM model override
  }[];
  crisis: {
    scenario: "rnd1" | "rnd2" | "rnd3" | "rnd4" | "custom";
    custom_description?: string;
  };
  params: {
    duration_weeks: number; // 1-52 (default: 12)
    pacing: "slow" | "normal" | "fast";
  };
}

// Sent on each agent message during simulation
interface WebSocketPayload {
  type: "init" | "message" | "completed" | "error" | "typing_start";
  data?: {                     // Agent message data
    id: number;
    round: number;
    agent_id: string;
    agent_name: string;
    type: "public" | "thought" | "system";
    content: string;
    thought?: string;          // Internal thought (hidden insight)
    state_changes?: {
      morale?: number;         // Delta (e.g., -5, +10)
      stress?: number;
      loyalty?: number;
      productivity?: number;
    };
    timestamp: string;
  };
  agents: AgentState[];        // Updated agent states
  metrics: {
    avgMorale: number;
    avgStress: number;
    productivity: number;
    resignations: number;
    avgLoyalty: number;
    teamCohesion: number;      // Composite metric
  };
  worldState?: {               // Dynamic world constraints
    budgetRemaining: number;
    customerSatisfaction: number;
    companyReputation: number;
    teamCapacity: number;
    technicalDebt: number;
    deadlineWeeksLeft: number;
  };
  decisionStatus?: {           // Decision engine state
    proposalCount: number;
    hasDecision: boolean;
    decidedProposal?: string;
    leadingProposal?: string;
    leadingSupport: number;
    escalationCount: number;
    resignThreats: string[];
  };
  currentRound: number;
  totalRounds: number;
  status: "idle" | "running" | "completed";
  metricsHistory?: { round: number; morale: number; stress: number;
                     productivity: number; loyalty: number; cohesion: number; }[];
}

interface ReportResponse {
  simulation_id: string;
  company_name: string;
  crisis_name: string;
  total_rounds: number;
  completed_rounds: number;
  executive_summary: string;     // AI-generated overview
  critical_finding: string;      // Most critical issue identified
  simulation_overview: string;   // Detailed scenario description
  key_metrics: {
    total_agents: number;
    active_agents: number;
    resignations: number;
    avg_morale: number;
    avg_stress: number;
    avg_loyalty: number;
    avg_productivity: number;
    productivity_drop: number;
    simulation_weeks: number;
    total_planned_weeks: number;
  };
  analysis_insights: string;     // In-depth analysis paragraph
  conclusion: string;            // Final summary
  agent_reports: {
    id: string;
    name: string;
    role: string;
    starting_morale: number;
    ending_morale: number;
    peak_stress: number;
    has_resigned: boolean;
    resigned_week?: number;
    status: "Failed" | "Critical" | "Stressed" | "Stable" | "Thriving";
    status_label: string;        // e.g., "Resigned • Week 9"
  }[];
  productivity_drop: number;
  recommendations: string[];     // 3-5 AI-generated actions
  timeline: {                    // Per-round metrics for charts
    round: number;
    morale: number;
    stress: number;
    output: number;
  }[];
}