# shamalsathsara/queen-aura architecture

> Architecture diagram of the GitHub repository shamalsathsara/queen-aura, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/shamalsathsara/queen-aura
- Repository: https://github.com/shamalsathsara/queen-aura

## Overview

Queen Aura is a modular WhatsApp assistant: users send commands or natural-language messages, the bot routes them into academic, media, AI, quiz, greeting, and group-administration features, then replies through WhatsApp. The graph includes documented capabilities even where implementation was not sampled; their internal wiring is omitted when evidence is unavailable. Sampled code supports the routing, session, university, downloader, poll, greeting, and moderation-state links shown.

Main entry points: [`src/routes.js`](https://github.com/shamalsathsara/queen-aura/blob/main/src/routes.js) (Command routes), [`AuraMain.js`](https://github.com/shamalsathsara/queen-aura/blob/main/AuraMain.js) (Bot event dispatcher), [`src/services/autoPollService.js`](https://github.com/shamalsathsara/queen-aura/blob/main/src/services/autoPollService.js) (IT quiz polls), [`src/core/middleware.js`](https://github.com/shamalsathsara/queen-aura/blob/main/src/core/middleware.js) (Access middleware)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["WhatsApp entry"]
  node_main["Bot event dispatcher<br/>[AuraMain.js]"]
  node_middleware["Access middleware<br/>[middleware.js]"]
end

subgraph group_interaction["Routing and state"]
  node_router["Intent and state router<br/>[router.js]"]
  node_routes["Command routes<br/>[routes.js]"]
  node_sessions[("Conversation sessions<br/>[session.js]")]
  node_ui["Interactive menus<br/>[components.js]"]
end

subgraph group_features["User features"]
  node_university["University resource hub"]
  node_drive["Drive resource access<br/>[driveHelper.js]"]
  node_ai["AI conversation manager<br/>[AIManager.js]"]
  node_ai_plugin["AI chat command<br/>[gemini.js]"]
  node_downloaders["Media download commands"]
  node_youtube["YouTube commands<br/>[youtube.js]"]
  node_social["Social downloads<br/>[social.js]"]
  node_sticker["Sticker creation<br/>[sticker.js]"]
  node_image["AI image generation<br/>[image.js]"]
  node_moderation["Group moderation<br/>[moderation.js]"]
  node_anti_link[("Anti-link settings<br/>[antiLinkManager.js]")]
  node_auto_reply["Natural-language replies<br/>[autoReply.js]"]
end

subgraph group_automation["Scheduled services"]
  node_autopoll["IT quiz polls<br/>[autoPollService.js]"]
  node_bugquiz["Bug challenges"]
  node_cmdquiz["Command quizzes<br/>[cmdQuizService.js]"]
  node_leaderboard["Quiz leaderboard"]
  node_greetings["Daily greetings"]
end

subgraph group_support["Runtime support"]
  node_system["Status and system commands<br/>[system.js]"]
  node_owner["Owner commands<br/>[owner.js]"]
  node_mode[("Public/private mode<br/>[modeManager.js]")]
  node_group_utils["Group authorization<br/>[groupUtils.js]"]
  node_time["Timezone utilities<br/>[timeUtils.js]"]
end

node_users(("WhatsApp users"))
node_whatsapp{{"WhatsApp / Baileys"}}

node_users -->|"send messages"| node_whatsapp
node_whatsapp -->|"delivers events"| node_main
node_main -->|"checks access"| node_middleware
node_main -->|"dispatches commands"| node_routes
node_routes -->|"registers intents"| node_router
node_router -->|"loads state"| node_sessions
node_router -->|"renders menus"| node_ui
node_routes -->|"routes university"| node_university
node_university -->|"stores navigation state"| node_sessions
node_university -->|"accesses files"| node_drive
node_routes -->|"routes chat"| node_ai_plugin
node_ai_plugin -->|"delegates prompts"| node_ai
node_routes -->|"routes text intents"| node_auto_reply
node_youtube -->|"downloads media"| node_downloaders
node_social -->|"downloads media"| node_downloaders
node_routes -->|"routes poll commands"| node_autopoll
node_autopoll -->|"records poll results"| node_leaderboard
node_bugquiz -->|"uses poll service"| node_autopoll
node_cmdquiz -->|"uses poll service"| node_autopoll
node_greetings -->|"checks local time"| node_time
node_main -->|"handles link policy"| node_anti_link
node_middleware -->|"checks mode"| node_mode
node_middleware -->|"checks permissions"| node_group_utils
node_routes -.->|"routes group commands"| node_moderation

click node_main "https://github.com/shamalsathsara/queen-aura/blob/main/AuraMain.js"
click node_middleware "https://github.com/shamalsathsara/queen-aura/blob/main/src/core/middleware.js"
click node_router "https://github.com/shamalsathsara/queen-aura/blob/main/src/core/router.js"
click node_routes "https://github.com/shamalsathsara/queen-aura/blob/main/src/routes.js"
click node_sessions "https://github.com/shamalsathsara/queen-aura/blob/main/src/state/session.js"
click node_ui "https://github.com/shamalsathsara/queen-aura/blob/main/src/ui/components.js"
click node_university "https://github.com/shamalsathsara/queen-aura/blob/main/src/features/university/universityHandler.js"
click node_drive "https://github.com/shamalsathsara/queen-aura/blob/main/src/utils/driveHelper.js"
click node_ai "https://github.com/shamalsathsara/queen-aura/blob/main/src/features/ai/AIManager.js"
click node_ai_plugin "https://github.com/shamalsathsara/queen-aura/blob/main/plugins/gemini.js"
click node_downloaders "https://github.com/shamalsathsara/queen-aura/blob/main/src/services/downloaderService.js"
click node_youtube "https://github.com/shamalsathsara/queen-aura/blob/main/plugins/youtube.js"
click node_social "https://github.com/shamalsathsara/queen-aura/blob/main/plugins/social.js"
click node_sticker "https://github.com/shamalsathsara/queen-aura/blob/main/plugins/sticker.js"
click node_image "https://github.com/shamalsathsara/queen-aura/blob/main/plugins/image.js"
click node_moderation "https://github.com/shamalsathsara/queen-aura/blob/main/plugins/moderation.js"
click node_anti_link "https://github.com/shamalsathsara/queen-aura/blob/main/src/state/antiLinkManager.js"
click node_auto_reply "https://github.com/shamalsathsara/queen-aura/blob/main/plugins/autoReply.js"
click node_autopoll "https://github.com/shamalsathsara/queen-aura/blob/main/src/services/autoPollService.js"
click node_bugquiz "https://github.com/shamalsathsara/queen-aura/blob/main/src/services/bugChallengeService.js"
click node_cmdquiz "https://github.com/shamalsathsara/queen-aura/blob/main/src/services/cmdQuizService.js"
click node_leaderboard "https://github.com/shamalsathsara/queen-aura/blob/main/src/services/leaderboardService.js"
click node_greetings "https://github.com/shamalsathsara/queen-aura/blob/main/src/services/dailyGreetingService.js"
click node_system "https://github.com/shamalsathsara/queen-aura/blob/main/src/features/system.js"
click node_owner "https://github.com/shamalsathsara/queen-aura/blob/main/src/features/owner.js"
click node_mode "https://github.com/shamalsathsara/queen-aura/blob/main/src/state/modeManager.js"
click node_group_utils "https://github.com/shamalsathsara/queen-aura/blob/main/src/utils/groupUtils.js"
click node_time "https://github.com/shamalsathsara/queen-aura/blob/main/src/utils/timeUtils.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_main,node_middleware,node_users toneBlue
class node_router,node_routes,node_sessions,node_ui toneAmber
class node_university,node_drive,node_ai,node_ai_plugin,node_downloaders,node_youtube,node_social,node_sticker,node_image,node_moderation,node_anti_link,node_auto_reply toneMint
class node_autopoll,node_bugquiz,node_cmdquiz,node_leaderboard,node_greetings toneRose
class node_system,node_owner,node_mode,node_group_utils,node_time,node_whatsapp toneIndigo
```

## Components

### WhatsApp entry

- [Bot event dispatcher](https://github.com/shamalsathsara/queen-aura/blob/main/AuraMain.js): `AuraMain.js`
- [Access middleware](https://github.com/shamalsathsara/queen-aura/blob/main/src/core/middleware.js): `src/core/middleware.js`

### Routing and state

- [Intent and state router](https://github.com/shamalsathsara/queen-aura/blob/main/src/core/router.js): `src/core/router.js`
- [Command routes](https://github.com/shamalsathsara/queen-aura/blob/main/src/routes.js): `src/routes.js`
- [Conversation sessions](https://github.com/shamalsathsara/queen-aura/blob/main/src/state/session.js): `src/state/session.js`
- [Interactive menus](https://github.com/shamalsathsara/queen-aura/blob/main/src/ui/components.js): `src/ui/components.js`

### User features

- [University resource hub](https://github.com/shamalsathsara/queen-aura/blob/main/src/features/university/universityHandler.js): `src/features/university/universityHandler.js`
- [Drive resource access](https://github.com/shamalsathsara/queen-aura/blob/main/src/utils/driveHelper.js): `src/utils/driveHelper.js`
- [AI conversation manager](https://github.com/shamalsathsara/queen-aura/blob/main/src/features/ai/AIManager.js): `src/features/ai/AIManager.js`
- [AI chat command](https://github.com/shamalsathsara/queen-aura/blob/main/plugins/gemini.js): `plugins/gemini.js`
- [Media download commands](https://github.com/shamalsathsara/queen-aura/blob/main/src/services/downloaderService.js): `src/services/downloaderService.js`
- [YouTube commands](https://github.com/shamalsathsara/queen-aura/blob/main/plugins/youtube.js): `plugins/youtube.js`
- [Social downloads](https://github.com/shamalsathsara/queen-aura/blob/main/plugins/social.js): `plugins/social.js`
- [Sticker creation](https://github.com/shamalsathsara/queen-aura/blob/main/plugins/sticker.js): `plugins/sticker.js`
- [AI image generation](https://github.com/shamalsathsara/queen-aura/blob/main/plugins/image.js): `plugins/image.js`
- [Group moderation](https://github.com/shamalsathsara/queen-aura/blob/main/plugins/moderation.js): `plugins/moderation.js`
- [Anti-link settings](https://github.com/shamalsathsara/queen-aura/blob/main/src/state/antiLinkManager.js): `src/state/antiLinkManager.js`
- [Natural-language replies](https://github.com/shamalsathsara/queen-aura/blob/main/plugins/autoReply.js): `plugins/autoReply.js`

### Scheduled services

- [IT quiz polls](https://github.com/shamalsathsara/queen-aura/blob/main/src/services/autoPollService.js): `src/services/autoPollService.js`
- [Bug challenges](https://github.com/shamalsathsara/queen-aura/blob/main/src/services/bugChallengeService.js): `src/services/bugChallengeService.js`
- [Command quizzes](https://github.com/shamalsathsara/queen-aura/blob/main/src/services/cmdQuizService.js): `src/services/cmdQuizService.js`
- [Quiz leaderboard](https://github.com/shamalsathsara/queen-aura/blob/main/src/services/leaderboardService.js): `src/services/leaderboardService.js`
- [Daily greetings](https://github.com/shamalsathsara/queen-aura/blob/main/src/services/dailyGreetingService.js): `src/services/dailyGreetingService.js`

### Runtime support

- [Status and system commands](https://github.com/shamalsathsara/queen-aura/blob/main/src/features/system.js): `src/features/system.js`
- [Owner commands](https://github.com/shamalsathsara/queen-aura/blob/main/src/features/owner.js): `src/features/owner.js`
- [Public/private mode](https://github.com/shamalsathsara/queen-aura/blob/main/src/state/modeManager.js): `src/state/modeManager.js`
- [Group authorization](https://github.com/shamalsathsara/queen-aura/blob/main/src/utils/groupUtils.js): `src/utils/groupUtils.js`
- [Timezone utilities](https://github.com/shamalsathsara/queen-aura/blob/main/src/utils/timeUtils.js): `src/utils/timeUtils.js`

### Other components

- **WhatsApp users**
- **WhatsApp / Baileys**

## Connections

- WhatsApp users → WhatsApp / Baileys: send messages (evidence: `README.md`)
- WhatsApp / Baileys → Bot event dispatcher: delivers events (evidence: `AuraMain.js`)
- Bot event dispatcher → Access middleware: checks access (evidence: `AuraMain.js`)
- Bot event dispatcher → Command routes: dispatches commands (evidence: `AuraMain.js`)
- Command routes → Intent and state router: registers intents (evidence: `src/routes.js`)
- Intent and state router → Conversation sessions: loads state (evidence: `src/core/router.js`)
- Intent and state router → Interactive menus: renders menus (evidence: `src/core/router.js`)
- Command routes → University resource hub: routes university (evidence: `src/routes.js`)
- University resource hub → Conversation sessions: stores navigation state (evidence: `src/features/university/universityHandler.js`)
- University resource hub → Drive resource access: accesses files (evidence: `src/features/university/universityHandler.js`)
- Command routes → AI chat command: routes chat (evidence: `src/routes.js`)
- AI chat command → AI conversation manager: delegates prompts (evidence: `plugins/gemini.js`)
- Command routes → Natural-language replies: routes text intents (evidence: `src/routes.js`)
- YouTube commands → Media download commands: downloads media (evidence: `plugins/youtube.js`)
- Social downloads → Media download commands: downloads media (evidence: `plugins/social.js`)
- Command routes → IT quiz polls: routes poll commands (evidence: `src/routes.js`)
- IT quiz polls → Quiz leaderboard: records poll results (evidence: `src/services/autoPollService.js`)
- Bug challenges → IT quiz polls: uses poll service (evidence: `src/services/bugChallengeService.js`)
- Command quizzes → IT quiz polls: uses poll service (evidence: `src/services/cmdQuizService.js`)
- Daily greetings → Timezone utilities: checks local time (evidence: `src/services/dailyGreetingService.js`)
- Bot event dispatcher → Anti-link settings: handles link policy (evidence: `AuraMain.js`)
- Access middleware → Public/private mode: checks mode (evidence: `src/core/middleware.js`)
- Access middleware → Group authorization: checks permissions (evidence: `src/core/middleware.js`)
- Command routes → Group moderation: routes group commands