# frionode/luna architecture

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

- Interactive diagram: https://gitdiagram.com/frionode/luna
- Repository: https://github.com/frionode/luna

## Overview

1. **Overall shape**
   - This is a **Node.js WhatsApp automation bot** built on **Baileys**.
   - It has two main runtime surfaces: a **WhatsApp event-driven bot** and a small **Express-based dashboard** for runtime visibility.

2. **Primary entry point and boot flow**
   - `luna.js` is the main startup file.
   - On boot it initializes authentication/session state, connects to WhatsApp, loads persistent configuration, and starts the HTTP dashboard.
   - The startup path depends on deployment style: local QR login or cloud session replay from `SESSION` / paired credentials.

3. **Inbound event boundary: WhatsApp**
   - The WhatsApp connection is the core transport boundary.
   - Messages, group events, status updates, reactions, and other Baileys events are funneled into the bot logic rather than handled directly in feature modules.

4. **Core orchestration layer**
   - `bloom/brain.js` appears to be the central message dispatcher/orchestrator.
   - It is the likely place where incoming events are normalized and then routed to command groups, moderation logic, game logic, and auto-replies.
   - `bloom/statusview.js` and `bloom/ttthandle.js` sit beside it as specialized event handlers for status viewing and a separate interaction/game flow.

5. **Feature modules by domain**
   - `bloom/base/` is organized by command family:
     - `group.js` for group administration
     - `owner.js` for privileged/admin-only actions
     - `user.js` for user-facing commands
     - `games.js`, `riddle.js`, `fun.js` for interactive features
     - `media.js` and `apis.js` for content/API-backed utilities
     - `religion.js`, `luna.js`, `menu.js`, `reload.js`, `utils.js` for other command sets and shared helpers
   - This suggests a **modular command registry** rather than one monolithic handler.

6. **Service/integration layer**
   - The `colors/` directory looks like the support layer for external integrations and shared runtime services.
   - Key responsibilities include:
     - `auth.js` for session/authentication handling
     - `redis.js` for cache/ephemeral state
     - `schema.js` and `setup.js` for configuration and persistence initialization
     - `groq.js` and `react.js` for AI-like or automated response features
     - `pokemon.js`, `exp.js`, `typed.js`, `mess.js`, `font.css`, `luna.html` as feature/UI/support assets
   - This layer likely isolates credentials, storage, and third-party API calls from bot logic.

7. **Persistence and runtime state**
   - The project is explicitly stateful.
   - **MongoDB** is the main source of durable configuration and runtime settings.
   - **Redis** is used for cache, stability, and usage tracking.
   - `baileys_store.json` indicates additional local storage for Baileys state, and `temp/` is used for transient files/media.

8. **Dashboard and monitoring**
   - The README describes a built-in web dashboard served on **port 3000** by the Express app.
   - Its purpose is operational: uptime, usage, and major runtime errors.
   - `colors/luna.html` and related assets likely back this dashboard UI.

9. **Automation and gameplay**
   - The bot is not just command-response; it also runs background behaviors:
     - Pokémon spawning
     - status watching
     - group logging/startup messages
     - automatic reactions
   - These behaviors are tied to group configuration stored dynamically, so the bot can operate in one or more designated WhatsApp groups.

10. **Configuration model**
   - `.env` is used primarily for first boot and bootstrap secrets:
     - `SESSION`, `MONGO`, `REDIS`, `OWNERNUMBER`, `INVITE`
   - After startup, the bot migrates much of its configuration into MongoDB, which means runtime behavior is partially server-managed rather than purely env-driven.

11. **Deployment boundaries**
   - The repo includes `Dockerfile`, `docker-compose.yml`, and `fly.toml`, so it supports containerized and Fly.io-style deployment.
   - The architecture is therefore designed to run in:
     - local terminal mode with QR auth
     - cloud/VPS mode with session replay
     - Dockerized environments with external Mongo/Redis

12. **Important external dependencies**
   - **Baileys**: WhatsApp transport/session layer
   - **MongoDB**: durable config/state
   - **Redis**: cache and fast runtime state
   - Optional third-party APIs appear to support niche features, especially around media, weather, and AI-style responses.

13. **How data flows through the system**
   - WhatsApp event comes in via Baileys.
   - `brain.js`/specialized handlers classify the event.
   - The relevant `bloom/base/*` module executes the command or feature.
   - Support functions in `colors/*` handle auth, storage, caching, or external API calls.
   - Results are sent back to WhatsApp, while state changes may be written to MongoDB/Redis and transient artifacts to `temp/`.

14. **Diagram boundary suggestion**
   - A good architecture diagram should show:
     - WhatsApp as the external message source/sink
     - the bot core/orchestrator
     - feature command modules
     - support services for auth/cache/persistence/external APIs
     - the Express dashboard as a separate HTTP surface
     - deployment/runtime infrastructure around them

Main entry points: [`bloom/brain.js`](https://github.com/frionode/luna/blob/main/bloom/brain.js) (brain.js), [`luna.js`](https://github.com/frionode/luna/blob/main/luna.js) (luna.js), [`colors/setup.js`](https://github.com/frionode/luna/blob/main/colors/setup.js) (setup.js), [`colors/redis.js`](https://github.com/frionode/luna/blob/main/colors/redis.js) (redis.js)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime surfaces"]
  node_luna_js["luna.js<br/>boot<br/>[luna.js]"]
  node_whatsapp(("WhatsApp<br/>baileys transport"))
  node_dashboard["Dashboard<br/>express ui<br/>[luna.html]"]
end

subgraph group_core["Bot core"]
  node_brain["brain.js<br/>orchestrator<br/>[brain.js]"]
  node_statusview["statusview.js<br/>status handler<br/>[statusview.js]"]
  node_ttt["ttthandle.js<br/>game flow<br/>[ttthandle.js]"]
end

subgraph group_features["Command modules"]
  node_group_cmd["group<br/>admin commands<br/>[group.js]"]
  node_owner_cmd["owner<br/>privileged commands<br/>[owner.js]"]
  node_user_cmd["user<br/>[user.js]"]
  node_games_cmd["games<br/>game commands<br/>[games.js]"]
  node_riddle_cmd["riddle<br/>puzzle commands<br/>[riddle.js]"]
  node_fun_cmd["fun<br/>entertainment<br/>[fun.js]"]
  node_media_cmd["media<br/>content commands<br/>[media.js]"]
  node_apis_cmd["apis<br/>api commands<br/>[apis.js]"]
  node_menu_cmd["menu<br/>navigation<br/>[menu.js]"]
end

subgraph group_services["Support services"]
  node_auth["auth.js<br/>session auth<br/>[auth.js]"]
  node_schema["schema.js<br/>config schema<br/>[schema.js]"]
  node_setup["setup.js<br/>bootstrap setup<br/>[setup.js]"]
  node_redis[("redis.js<br/>cache store<br/>[redis.js]")]
  node_groq["groq.js<br/>ai integration<br/>[groq.js]"]
  node_react["react.js<br/>auto response<br/>[react.js]"]
  node_pokemon["pokemon.js<br/>background feature<br/>[pokemon.js]"]
end

subgraph group_infra["Deployment"]
  node_dockerfile["Dockerfile<br/>container build"]
  node_compose["docker-compose<br/>local stack<br/>[docker-compose.yml]"]
  node_fly["fly.toml<br/>hosting config<br/>[fly.toml]"]
end

node_luna_js -->|"connects"| node_whatsapp
node_luna_js -->|"loads"| node_auth
node_luna_js -->|"initializes"| node_setup
node_luna_js -->|"starts"| node_brain
node_luna_js -->|"serves"| node_dashboard
node_whatsapp -->|"events"| node_brain
node_whatsapp -->|"status events"| node_statusview
node_whatsapp -->|"interaction events"| node_ttt
node_brain -->|"routes"| node_group_cmd
node_brain -->|"routes"| node_owner_cmd
node_brain -->|"routes"| node_user_cmd
node_brain -->|"routes"| node_games_cmd
node_brain -->|"routes"| node_riddle_cmd
node_brain -->|"routes"| node_fun_cmd
node_brain -->|"routes"| node_media_cmd
node_brain -->|"routes"| node_apis_cmd
node_brain -->|"routes"| node_menu_cmd
node_brain -->|"reads/writes"| node_redis
node_brain -->|"delegates"| node_groq
node_brain -->|"delegates"| node_react
node_setup -->|"applies"| node_schema
node_setup -->|"connects"| node_redis
node_setup -->|"boots"| node_auth
node_statusview -->|"uses"| node_react
node_luna_js -->|"loads config"| node_schema
node_luna_js -->|"opens cache"| node_redis
node_luna_js -->|"enables"| node_pokemon
node_dockerfile -->|"builds"| node_luna_js
node_compose -->|"uses"| node_dockerfile
node_fly -->|"targets"| node_compose

click node_luna_js "https://github.com/frionode/luna/blob/main/luna.js"
click node_dashboard "https://github.com/frionode/luna/blob/main/colors/luna.html"
click node_brain "https://github.com/frionode/luna/blob/main/bloom/brain.js"
click node_statusview "https://github.com/frionode/luna/blob/main/bloom/statusview.js"
click node_ttt "https://github.com/frionode/luna/blob/main/bloom/ttthandle.js"
click node_group_cmd "https://github.com/frionode/luna/blob/main/bloom/base/group.js"
click node_owner_cmd "https://github.com/frionode/luna/blob/main/bloom/base/owner.js"
click node_user_cmd "https://github.com/frionode/luna/blob/main/bloom/base/user.js"
click node_games_cmd "https://github.com/frionode/luna/blob/main/bloom/base/games.js"
click node_riddle_cmd "https://github.com/frionode/luna/blob/main/bloom/base/riddle.js"
click node_fun_cmd "https://github.com/frionode/luna/blob/main/bloom/base/fun.js"
click node_media_cmd "https://github.com/frionode/luna/blob/main/bloom/base/media.js"
click node_apis_cmd "https://github.com/frionode/luna/blob/main/bloom/base/apis.js"
click node_menu_cmd "https://github.com/frionode/luna/blob/main/bloom/base/menu.js"
click node_auth "https://github.com/frionode/luna/blob/main/colors/auth.js"
click node_schema "https://github.com/frionode/luna/blob/main/colors/schema.js"
click node_setup "https://github.com/frionode/luna/blob/main/colors/setup.js"
click node_redis "https://github.com/frionode/luna/blob/main/colors/redis.js"
click node_groq "https://github.com/frionode/luna/blob/main/colors/groq.js"
click node_react "https://github.com/frionode/luna/blob/main/colors/react.js"
click node_pokemon "https://github.com/frionode/luna/blob/main/colors/pokemon.js"
click node_dockerfile "https://github.com/frionode/luna/tree/main/Dockerfile"
click node_compose "https://github.com/frionode/luna/blob/main/docker-compose.yml"
click node_fly "https://github.com/frionode/luna/blob/main/fly.toml"

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_luna_js,node_whatsapp,node_dashboard toneBlue
class node_brain,node_statusview,node_ttt toneAmber
class node_group_cmd,node_owner_cmd,node_user_cmd,node_games_cmd,node_riddle_cmd,node_fun_cmd,node_media_cmd,node_apis_cmd,node_menu_cmd toneMint
class node_auth,node_schema,node_setup,node_redis,node_groq,node_react,node_pokemon toneRose
class node_dockerfile,node_compose,node_fly toneIndigo
```

## Components

### Runtime surfaces

Boot, WhatsApp transport, and the HTTP dashboard.

- [luna.js](https://github.com/frionode/luna/blob/main/luna.js): boot · Main process entry point; initializes auth, state, bot connection, and dashboard. · `luna.js`
- **WhatsApp**: baileys transport · External message/event boundary for the bot.
- [Dashboard](https://github.com/frionode/luna/blob/main/colors/luna.html): express ui · HTTP visibility surface for uptime and runtime status. · `colors/luna.html`

### Bot core

Event orchestration and specialized handlers.

- [brain.js](https://github.com/frionode/luna/blob/main/bloom/brain.js): orchestrator · Central event dispatcher that normalizes inbound WhatsApp activity and routes it to feature logic. · `bloom/brain.js`
- [statusview.js](https://github.com/frionode/luna/blob/main/bloom/statusview.js): status handler · Specialized handler for status-viewing and related event flow. · `bloom/statusview.js`
- [ttthandle.js](https://github.com/frionode/luna/blob/main/bloom/ttthandle.js): game flow · Dedicated interaction handler for a separate game or challenge flow. · `bloom/ttthandle.js`

### Command modules

Domain-specific command families loaded by the bot.

- [group](https://github.com/frionode/luna/blob/main/bloom/base/group.js): admin commands · Group administration command family. · `bloom/base/group.js`
- [owner](https://github.com/frionode/luna/blob/main/bloom/base/owner.js): privileged commands · Owner-only and privileged control actions. · `bloom/base/owner.js`
- [user](https://github.com/frionode/luna/blob/main/bloom/base/user.js): user commands · User-facing command family. · `bloom/base/user.js`
- [games](https://github.com/frionode/luna/blob/main/bloom/base/games.js): game commands · Interactive game commands. · `bloom/base/games.js`
- [riddle](https://github.com/frionode/luna/blob/main/bloom/base/riddle.js): puzzle commands · Riddle and challenge-style interactions. · `bloom/base/riddle.js`
- [fun](https://github.com/frionode/luna/blob/main/bloom/base/fun.js): entertainment · Lightweight entertainment and playful commands. · `bloom/base/fun.js`
- [media](https://github.com/frionode/luna/blob/main/bloom/base/media.js): content commands · Media handling and content utilities. · `bloom/base/media.js`
- [apis](https://github.com/frionode/luna/blob/main/bloom/base/apis.js): api commands · Commands backed by external APIs. · `bloom/base/apis.js`
- [menu](https://github.com/frionode/luna/blob/main/bloom/base/menu.js): navigation · Menu and command discovery surface. · `bloom/base/menu.js`

### Support services

Auth, persistence, cache, and external integrations.

- [auth.js](https://github.com/frionode/luna/blob/main/colors/auth.js): session auth · Authentication and WhatsApp session handling. · `colors/auth.js`
- [schema.js](https://github.com/frionode/luna/blob/main/colors/schema.js): config schema · Configuration and persistence schema layer. · `colors/schema.js`
- [setup.js](https://github.com/frionode/luna/blob/main/colors/setup.js): bootstrap setup · Startup initialization for configuration and persistence. · `colors/setup.js`
- [redis.js](https://github.com/frionode/luna/blob/main/colors/redis.js): cache store · Fast runtime state and ephemeral cache. · `colors/redis.js`
- [groq.js](https://github.com/frionode/luna/blob/main/colors/groq.js): ai integration · AI-style response or external generation integration. · `colors/groq.js`
- [react.js](https://github.com/frionode/luna/blob/main/colors/react.js): auto response · Automated reaction/response helper. · `colors/react.js`
- [pokemon.js](https://github.com/frionode/luna/blob/main/colors/pokemon.js): background feature · Background gameplay or spawn-related feature support. · `colors/pokemon.js`

### Deployment

Container and hosting entry points.

- [Dockerfile](https://github.com/frionode/luna/tree/main/Dockerfile): container build · Container image definition. · `Dockerfile`
- [docker-compose](https://github.com/frionode/luna/blob/main/docker-compose.yml): local stack · Containerized runtime composition. · `docker-compose.yml`
- [fly.toml](https://github.com/frionode/luna/blob/main/fly.toml): hosting config · Fly.io deployment configuration. · `fly.toml`

## Connections

- luna.js → WhatsApp: connects · Boot establishes the WhatsApp connection.
- luna.js → auth.js: loads · Boot reads or replays session state.
- luna.js → setup.js: initializes · Boot prepares runtime configuration and persistence.
- luna.js → brain.js: starts · Main process hands inbound events to the orchestrator.
- luna.js → Dashboard: serves · Starts the visibility dashboard surface.
- WhatsApp → brain.js: events · WhatsApp messages and events enter the dispatcher.
- WhatsApp → statusview.js: status events · Status-related activity is routed to the status handler.
- WhatsApp → ttthandle.js: interaction events · Dedicated interaction flow receives its own event stream.
- brain.js → group: routes · Dispatches administrative group actions.
- brain.js → owner: routes · Dispatches privileged owner actions.
- brain.js → user: routes · Dispatches user-facing commands.
- brain.js → games: routes · Dispatches game commands.
- brain.js → riddle: routes · Dispatches puzzle commands.
- brain.js → fun: routes · Dispatches entertainment commands.
- brain.js → media: routes · Dispatches media/content commands.
- brain.js → apis: routes · Dispatches API-backed commands.
- brain.js → menu: routes · Routes menu/help requests.
- brain.js → redis.js: reads/writes · Uses cache and ephemeral runtime state.
- brain.js → groq.js: delegates · May delegate AI-like generation or responses.
- brain.js → react.js: delegates · May trigger automatic reactions or replies.
- setup.js → schema.js: applies · Setup uses the configuration schema.
- setup.js → redis.js: connects · Setup prepares cache/runtime storage.
- setup.js → auth.js: boots · Setup participates in auth and session initialization.
- statusview.js → react.js: uses · Status-related flows can trigger automated reactions.
- luna.js → schema.js: loads config · Startup reads persisted configuration.
- luna.js → redis.js: opens cache · Startup connects to ephemeral state storage.
- luna.js → pokemon.js: enables · Boot can enable background feature loops.
- Dockerfile → luna.js: builds · Container image runs the main entry point.
- docker-compose → Dockerfile: uses · Compose deploys the container image.
- fly.toml → docker-compose: targets · Hosting config supports deployed runtime topology.