# jigar-chaudhary-137/clubops-ai-by-nextbuildx architecture

> Architecture diagram of the GitHub repository jigar-chaudhary-137/clubops-ai-by-nextbuildx, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-09). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jigar-chaudhary-137/clubops-ai-by-nextbuildx
- Repository: https://github.com/jigar-chaudhary-137/clubops-ai-by-nextbuildx

## Overview

ClubOps AI is a multi-tenant operations workspace for college clubs. Organizers use the protected React workspace to manage events, tasks, volunteers, meetings, documents, risks, and announcements through the API. AI capabilities add meeting extraction, grounded document search, risk analysis, announcement drafting, and proposed operational actions; the documented safety model requires confirmation before AI mutations. Delivery includes in-app notifications and multi-channel announcements, including WhatsApp. The graph combines documented product workflows with relationships visible in sampled source and the source index; unsampled subsystem internals are represented at their existing directories.

Main entry points: [`server/src/ai/services/ai.service.js`](https://github.com/jigar-chaudhary-137/clubops-ai-by-nextbuildx/blob/main/server/src/ai/services/ai.service.js) (AI Orchestration), [`client/src/routes/AppRoutes.jsx`](https://github.com/jigar-chaudhary-137/clubops-ai-by-nextbuildx/blob/main/client/src/routes/AppRoutes.jsx) (Workspace Routes), [`server/src/services/announcements/announcementDeliveryService.js`](https://github.com/jigar-chaudhary-137/clubops-ai-by-nextbuildx/blob/main/server/src/services/announcements/announcementDeliveryService.js) (Announcement Delivery), [`server/src/ai/controllers`](https://github.com/jigar-chaudhary-137/clubops-ai-by-nextbuildx/tree/main/server/src/ai/controllers) (AI Controllers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workspace["Workspace UI"]
  node_routes["Workspace Routes<br/>[AppRoutes.jsx]"]
  node_tasks_ui["Task Workspace<br/>[TasksPage.jsx]"]
  node_documents_ui["Document Workspace<br/>[DocumentsPage.jsx]"]
  node_auth_context["Session Context<br/>[AuthContext.jsx]"]
  node_api_client["API Client<br/>[client.js]"]
end

subgraph group_operations["Club Operations"]
  node_operations_data[("Operations Records")]
  node_operation_services["Operations Services"]
end

subgraph group_intelligence["AI Intelligence"]
  node_meeting_processing["Meeting Processing"]
  node_ai_service["AI Orchestration<br/>[ai.service.js]"]
  node_operations_agent["Operations Agent<br/>[operationsAgent.js]"]
  node_rag_engine["Knowledge Retrieval<br/>[ragEngine.js]"]
  node_document_ingestion["Document Ingestion"]
  node_risk_engine["Risk Analysis<br/>[riskEngine.js]"]
  node_gemini["Gemini Client<br/>[client.js]"]
end

subgraph group_delivery["Communication"]
  node_announcement_delivery["Announcement Delivery"]
  node_broadcast_service["Broadcast Tracking"]
  node_whatsapp_service["WhatsApp Delivery"]
  node_notification_service["Notifications"]
  node_realtime["SSE Connections<br/>[realtime.js]"]
end

subgraph group_platform["API and State"]
  node_api_routes["API Routes"]
  node_auth_middleware["Authentication<br/>[auth.js]"]
  node_ai_controllers["AI Controllers"]
  node_knowledge_controller["Knowledge Controller"]
  node_announcement_controller["Announcement Controller"]
  node_whatsapp_controller["WhatsApp Controller"]
  node_notification_controller["Notification Controller"]
  node_response_helpers["API Response Helpers<br/>[apiResponse.js]"]
end

node_organizer(("Organizer"))

node_organizer -->|"uses workspace"| node_routes
node_routes -->|"routes to"| node_tasks_ui
node_routes -->|"routes to"| node_documents_ui
node_routes -->|"loads session"| node_auth_context
node_tasks_ui -->|"requests tasks"| node_api_client
node_api_client -.->|"calls API"| node_api_routes
node_api_routes -->|"guards requests"| node_auth_middleware
node_api_routes -->|"routes AI"| node_ai_controllers
node_ai_controllers -->|"delegates AI"| node_ai_service
node_ai_controllers -->|"routes knowledge"| node_knowledge_controller
node_knowledge_controller -->|"queries knowledge"| node_rag_engine
node_documents_ui -.->|"uploads documents"| node_document_ingestion
node_ai_service -->|"extracts meeting actions"| node_meeting_processing
node_ai_service -->|"analyzes event risks"| node_risk_engine
node_ai_service -->|"runs agent"| node_operations_agent
node_rag_engine -->|"synthesizes answers"| node_gemini
node_risk_engine -->|"requests analysis"| node_gemini
node_risk_engine -->|"reads operational data"| node_operations_data
node_ai_service -->|"applies confirmed actions"| node_operation_services
node_organizer -.->|"confirms proposals"| node_ai_service
node_announcement_controller -->|"dispatches announcement"| node_announcement_delivery
node_announcement_delivery -->|"tracks deliveries"| node_broadcast_service
node_announcement_delivery -->|"sends WhatsApp"| node_whatsapp_service
node_whatsapp_controller -->|"updates delivery status"| node_whatsapp_service
node_whatsapp_controller -->|"retries delivery"| node_broadcast_service
node_notification_controller -->|"fetches notifications"| node_notification_service
node_notification_controller -->|"opens SSE"| node_realtime
node_announcement_delivery -->|"publishes updates"| node_realtime
node_ai_service -->|"reads workspace context"| node_operations_data
node_ai_controllers -->|"formats responses"| node_response_helpers

click node_routes "https://github.com/jigar-chaudhary-137/clubops-ai-by-nextbuildx/blob/main/client/src/routes/AppRoutes.jsx"
click node_tasks_ui "https://github.com/jigar-chaudhary-137/clubops-ai-by-nextbuildx/blob/main/client/src/pages/tasks/TasksPage.jsx"
click node_documents_ui "https://github.com/jigar-chaudhary-137/clubops-ai-by-nextbuildx/blob/main/client/src/pages/documents/DocumentsPage.jsx"
click node_auth_context "https://github.com/jigar-chaudhary-137/clubops-ai-by-nextbuildx/blob/main/client/src/context/AuthContext.jsx"
click node_api_client "https://github.com/jigar-chaudhary-137/clubops-ai-by-nextbuildx/blob/main/client/src/services/api/client.js"
click node_operations_data "https://github.com/jigar-chaudhary-137/clubops-ai-by-nextbuildx/tree/main/server/src/models"
click node_operation_services "https://github.com/jigar-chaudhary-137/clubops-ai-by-nextbuildx/tree/main/server/src/services"
click node_meeting_processing "https://github.com/jigar-chaudhary-137/clubops-ai-by-nextbuildx/blob/main/server/src/ai/extraction/meetingProcessor.js"
click node_ai_service "https://github.com/jigar-chaudhary-137/clubops-ai-by-nextbuildx/blob/main/server/src/ai/services/ai.service.js"
click node_operations_agent "https://github.com/jigar-chaudhary-137/clubops-ai-by-nextbuildx/blob/main/server/src/ai/agents/operationsAgent.js"
click node_rag_engine "https://github.com/jigar-chaudhary-137/clubops-ai-by-nextbuildx/blob/main/server/src/ai/rag/ragEngine.js"
click node_document_ingestion "https://github.com/jigar-chaudhary-137/clubops-ai-by-nextbuildx/tree/main/server/src/ai/rag"
click node_risk_engine "https://github.com/jigar-chaudhary-137/clubops-ai-by-nextbuildx/blob/main/server/src/ai/risk/riskEngine.js"
click node_gemini "https://github.com/jigar-chaudhary-137/clubops-ai-by-nextbuildx/blob/main/server/src/ai/gemini/client.js"
click node_announcement_delivery "https://github.com/jigar-chaudhary-137/clubops-ai-by-nextbuildx/blob/main/server/src/services/announcements/announcementDeliveryService.js"
click node_broadcast_service "https://github.com/jigar-chaudhary-137/clubops-ai-by-nextbuildx/blob/main/server/src/services/broadcast.service.js"
click node_whatsapp_service "https://github.com/jigar-chaudhary-137/clubops-ai-by-nextbuildx/blob/main/server/src/services/whatsapp.service.js"
click node_notification_service "https://github.com/jigar-chaudhary-137/clubops-ai-by-nextbuildx/blob/main/server/src/services/notification.service.js"
click node_realtime "https://github.com/jigar-chaudhary-137/clubops-ai-by-nextbuildx/blob/main/server/src/utils/realtime.js"
click node_api_routes "https://github.com/jigar-chaudhary-137/clubops-ai-by-nextbuildx/tree/main/server/src/routes"
click node_auth_middleware "https://github.com/jigar-chaudhary-137/clubops-ai-by-nextbuildx/blob/main/server/src/middleware/auth.js"
click node_ai_controllers "https://github.com/jigar-chaudhary-137/clubops-ai-by-nextbuildx/tree/main/server/src/ai/controllers"
click node_knowledge_controller "https://github.com/jigar-chaudhary-137/clubops-ai-by-nextbuildx/blob/main/server/src/ai/controllers/knowledge.controller.js"
click node_announcement_controller "https://github.com/jigar-chaudhary-137/clubops-ai-by-nextbuildx/blob/main/server/src/controllers/announcement.controller.js"
click node_whatsapp_controller "https://github.com/jigar-chaudhary-137/clubops-ai-by-nextbuildx/blob/main/server/src/controllers/whatsapp.controller.js"
click node_notification_controller "https://github.com/jigar-chaudhary-137/clubops-ai-by-nextbuildx/blob/main/server/src/controllers/notification.controller.js"
click node_response_helpers "https://github.com/jigar-chaudhary-137/clubops-ai-by-nextbuildx/blob/main/server/src/utils/apiResponse.js"

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_routes,node_tasks_ui,node_documents_ui,node_auth_context,node_api_client toneBlue
class node_operations_data,node_operation_services toneAmber
class node_meeting_processing,node_ai_service,node_operations_agent,node_rag_engine,node_document_ingestion,node_risk_engine,node_gemini toneMint
class node_announcement_delivery,node_broadcast_service,node_whatsapp_service,node_notification_service,node_realtime toneRose
class node_api_routes,node_auth_middleware,node_ai_controllers,node_knowledge_controller,node_announcement_controller,node_whatsapp_controller,node_notification_controller,node_response_helpers,node_organizer toneIndigo
```

## Components

### Workspace UI

- [Workspace Routes](https://github.com/jigar-chaudhary-137/clubops-ai-by-nextbuildx/blob/main/client/src/routes/AppRoutes.jsx): `client/src/routes/AppRoutes.jsx`
- [Task Workspace](https://github.com/jigar-chaudhary-137/clubops-ai-by-nextbuildx/blob/main/client/src/pages/tasks/TasksPage.jsx): `client/src/pages/tasks/TasksPage.jsx`
- [Document Workspace](https://github.com/jigar-chaudhary-137/clubops-ai-by-nextbuildx/blob/main/client/src/pages/documents/DocumentsPage.jsx): `client/src/pages/documents/DocumentsPage.jsx`
- [Session Context](https://github.com/jigar-chaudhary-137/clubops-ai-by-nextbuildx/blob/main/client/src/context/AuthContext.jsx): `client/src/context/AuthContext.jsx`
- [API Client](https://github.com/jigar-chaudhary-137/clubops-ai-by-nextbuildx/blob/main/client/src/services/api/client.js): `client/src/services/api/client.js`

### Club Operations

- [Operations Records](https://github.com/jigar-chaudhary-137/clubops-ai-by-nextbuildx/tree/main/server/src/models): `server/src/models`
- [Operations Services](https://github.com/jigar-chaudhary-137/clubops-ai-by-nextbuildx/tree/main/server/src/services): `server/src/services`

### AI Intelligence

- [Meeting Processing](https://github.com/jigar-chaudhary-137/clubops-ai-by-nextbuildx/blob/main/server/src/ai/extraction/meetingProcessor.js): `server/src/ai/extraction/meetingProcessor.js`
- [AI Orchestration](https://github.com/jigar-chaudhary-137/clubops-ai-by-nextbuildx/blob/main/server/src/ai/services/ai.service.js): `server/src/ai/services/ai.service.js`
- [Operations Agent](https://github.com/jigar-chaudhary-137/clubops-ai-by-nextbuildx/blob/main/server/src/ai/agents/operationsAgent.js): `server/src/ai/agents/operationsAgent.js`
- [Knowledge Retrieval](https://github.com/jigar-chaudhary-137/clubops-ai-by-nextbuildx/blob/main/server/src/ai/rag/ragEngine.js): `server/src/ai/rag/ragEngine.js`
- [Document Ingestion](https://github.com/jigar-chaudhary-137/clubops-ai-by-nextbuildx/tree/main/server/src/ai/rag): `server/src/ai/rag`
- [Risk Analysis](https://github.com/jigar-chaudhary-137/clubops-ai-by-nextbuildx/blob/main/server/src/ai/risk/riskEngine.js): `server/src/ai/risk/riskEngine.js`
- [Gemini Client](https://github.com/jigar-chaudhary-137/clubops-ai-by-nextbuildx/blob/main/server/src/ai/gemini/client.js): `server/src/ai/gemini/client.js`

### Communication

- [Announcement Delivery](https://github.com/jigar-chaudhary-137/clubops-ai-by-nextbuildx/blob/main/server/src/services/announcements/announcementDeliveryService.js): `server/src/services/announcements/announcementDeliveryService.js`
- [Broadcast Tracking](https://github.com/jigar-chaudhary-137/clubops-ai-by-nextbuildx/blob/main/server/src/services/broadcast.service.js): `server/src/services/broadcast.service.js`
- [WhatsApp Delivery](https://github.com/jigar-chaudhary-137/clubops-ai-by-nextbuildx/blob/main/server/src/services/whatsapp.service.js): `server/src/services/whatsapp.service.js`
- [Notifications](https://github.com/jigar-chaudhary-137/clubops-ai-by-nextbuildx/blob/main/server/src/services/notification.service.js): `server/src/services/notification.service.js`
- [SSE Connections](https://github.com/jigar-chaudhary-137/clubops-ai-by-nextbuildx/blob/main/server/src/utils/realtime.js): `server/src/utils/realtime.js`

### API and State

- [API Routes](https://github.com/jigar-chaudhary-137/clubops-ai-by-nextbuildx/tree/main/server/src/routes): `server/src/routes`
- [Authentication](https://github.com/jigar-chaudhary-137/clubops-ai-by-nextbuildx/blob/main/server/src/middleware/auth.js): `server/src/middleware/auth.js`
- [AI Controllers](https://github.com/jigar-chaudhary-137/clubops-ai-by-nextbuildx/tree/main/server/src/ai/controllers): `server/src/ai/controllers`
- [Knowledge Controller](https://github.com/jigar-chaudhary-137/clubops-ai-by-nextbuildx/blob/main/server/src/ai/controllers/knowledge.controller.js): `server/src/ai/controllers/knowledge.controller.js`
- [Announcement Controller](https://github.com/jigar-chaudhary-137/clubops-ai-by-nextbuildx/blob/main/server/src/controllers/announcement.controller.js): `server/src/controllers/announcement.controller.js`
- [WhatsApp Controller](https://github.com/jigar-chaudhary-137/clubops-ai-by-nextbuildx/blob/main/server/src/controllers/whatsapp.controller.js): `server/src/controllers/whatsapp.controller.js`
- [Notification Controller](https://github.com/jigar-chaudhary-137/clubops-ai-by-nextbuildx/blob/main/server/src/controllers/notification.controller.js): `server/src/controllers/notification.controller.js`
- [API Response Helpers](https://github.com/jigar-chaudhary-137/clubops-ai-by-nextbuildx/blob/main/server/src/utils/apiResponse.js): `server/src/utils/apiResponse.js`

### Other components

- **Organizer**

## Connections

- Organizer → Workspace Routes: uses workspace (evidence: `client/src/routes/AppRoutes.jsx`)
- Workspace Routes → Task Workspace: routes to (evidence: `client/src/routes/AppRoutes.jsx`)
- Workspace Routes → Document Workspace: routes to (evidence: `client/src/routes/AppRoutes.jsx`)
- Workspace Routes → Session Context: loads session (evidence: `client/src/App.jsx`)
- Task Workspace → API Client: requests tasks (evidence: `client/src/pages/tasks/TasksPage.jsx`)
- API Client → API Routes: calls API (evidence: `README.md`)
- API Routes → Authentication: guards requests (evidence: `server/src/routes/announcements.routes.js`)
- API Routes → AI Controllers: routes AI
- AI Controllers → AI Orchestration: delegates AI (evidence: `server/src/ai/controllers/ai.controller.js`)
- AI Controllers → Knowledge Controller: routes knowledge (evidence: `server/src/ai/routes/ai.routes.js`)
- Knowledge Controller → Knowledge Retrieval: queries knowledge (evidence: `server/src/ai/controllers/knowledge.controller.js`)
- Document Workspace → Document Ingestion: uploads documents (evidence: `README.md`)
- AI Orchestration → Meeting Processing: extracts meeting actions (evidence: `server/src/ai/services/ai.service.js`)
- AI Orchestration → Risk Analysis: analyzes event risks (evidence: `server/src/ai/services/ai.service.js`)
- AI Orchestration → Operations Agent: runs agent (evidence: `server/src/ai/services/ai.service.js`)
- Knowledge Retrieval → Gemini Client: synthesizes answers (evidence: `server/src/ai/rag/ragEngine.js`)
- Risk Analysis → Gemini Client: requests analysis (evidence: `server/src/ai/risk/riskEngine.js`)
- Risk Analysis → Operations Records: reads operational data (evidence: `server/src/ai/risk/riskEngine.js`)
- AI Orchestration → Operations Services: applies confirmed actions (evidence: `server/src/ai/services/ai.service.js`)
- Organizer → AI Orchestration: confirms proposals (evidence: `README.md`)
- Announcement Controller → Announcement Delivery: dispatches announcement (evidence: `server/src/controllers/announcement.controller.js`)
- Announcement Delivery → Broadcast Tracking: tracks deliveries (evidence: `server/src/services/announcements/announcementDeliveryService.js`)
- Announcement Delivery → WhatsApp Delivery: sends WhatsApp (evidence: `server/src/services/announcements/announcementDeliveryService.js`)
- WhatsApp Controller → WhatsApp Delivery: updates delivery status (evidence: `server/src/controllers/whatsapp.controller.js`)
- WhatsApp Controller → Broadcast Tracking: retries delivery (evidence: `server/src/controllers/whatsapp.controller.js`)
- Notification Controller → Notifications: fetches notifications (evidence: `server/src/controllers/notification.controller.js`)
- Notification Controller → SSE Connections: opens SSE (evidence: `server/src/controllers/notification.controller.js`)
- Announcement Delivery → SSE Connections: publishes updates (evidence: `server/src/services/announcements/announcementDeliveryService.js`)
- AI Orchestration → Operations Records: reads workspace context (evidence: `server/src/ai/services/ai.service.js`)
- AI Controllers → API Response Helpers: formats responses (evidence: `server/src/ai/controllers/ai.controller.js`)