Architecture

POST /v1/ai/copilot/swarm
    │
    ├─→ aiOrchestrator.ts (src/services/aiOrchestrator.ts)
    │   │
    │   ├─→ Route to specialist agent based on query intent
    │   ├─→ Execute tools (D1 queries, R2 presigned URLs, etc.)
    │   ├─→ Optional: request human approval before actions
    │   └─→ Log execution to ai_agent_logs table
    │
    ├─→ POST /v1/ai/rag/query
    │   └─→ Vectorize.similarity_search() → Workers AI generate()
    │
    └─→ POST /v1/ai/queue/event
        └─→ Cloudflare Queue → async processing

7 AI Agents

Agent	Role	Capabilities	Tools
Accountant	Financial operations	Invoice generation, payment tracking, GST/TDS compliance, journal entries, bank reconciliation	D1 queries, accounting engine, GST calculator
Secretary	Administrative ops	Notice drafting, meeting scheduling, agenda preparation, minutes generation	D1 queries, WhatsApp sender, email
Compliance	Regulatory compliance	GST return prep, TDS filing, audit trail review, DPDP compliance	D1 queries, GST/TDS engines, audit log reader
Communication	Messaging & alerts	Broadcast notices, payment reminders, emergency alerts, visitor notifications	WhatsApp API, push notifications, email
Analytics	Data analysis	Financial reports, defaulter analysis, trend detection, anomaly flagging	D1 queries, Workers AI, CSV export
Gatekeeper	Security operations	ANPR matching, visitor auto-checkout, RFID verification, boom barrier control	DO WebSocket, ANPR webhook, RFID webhook
Emergency	Emergency response	SOS broadcasting, lockdown management, escalation to authorities, first-responder alerts	DO WebSocket, SMS/WhatsApp blast, incident logging

AI Agent DB Tables

Table	Purpose
ai_agent_logs	Execution log: agent_name, action, input, output, tokens_used, cost_estimate, status
ai_agent_memories	Persistent memory: agent_name, memory_key, memory_value_json, embedding_vector, ttl_expiry
ai_agent_tools	Tool registry: tool_name, handler_endpoint, requires_approval, is_enabled
society_tasks	Task queue: assigned_to_type (AI_AGENT/EMPLOYEE/VENDOR), ai_agent_type, status workflow

RAG Pipeline

// POST /v1/ai/rag/query
{
  "query": "What is the society's pet policy according to bylaws?",
  "model": "@cf/meta/llama-3.1-8b-instruct"
}

// Pipeline:
// 1. Embed query via Workers AI embedding model
// 2. Vectorize.similarity_search(query_embedding, topK=5)
// 3. Retrieve matching document chunks from ai_agent_memories
// 4. Generate answer with context via Workers AI
// 5. Return { answer, sources[] }

Task Workflow

society_tasks status flow:
  TODO → IN_PROGRESS → AI_PROCESSING → PENDING_REVIEW → COMPLETED
                                                  ↓
                                             CANCELLED

assigned_to_type:
  AI_AGENT    — processed by specialist agent
  COMMITTEE   — manual review by committee member
  EMPLOYEE    — assigned to society staff
  VENDOR      — assigned to external vendor
  SELF        — self-service by resident