How frionode/luna works
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: brain.js brain.js · luna.js luna.js · setup.js setup.js · redis.js redis.js
Components 25
Runtime surfaces
Boot, WhatsApp transport, and the HTTP dashboard.
Bot core
Event orchestration and specialized handlers.
- brain.js · Central event dispatcher that normalizes inbound WhatsApp activity and routes it to feature logic.
bloom/brain.js - statusview.js · Specialized handler for status-viewing and related event flow.
bloom/statusview.js - ttthandle.js · Dedicated interaction handler for a separate game or challenge flow.
bloom/ttthandle.js
Command modules
Domain-specific command families loaded by the bot.
- group · Group administration command family.
bloom/base/group.js - owner · Owner-only and privileged control actions.
bloom/base/owner.js - user · User-facing command family.
bloom/base/user.js - games · Interactive game commands.
bloom/base/games.js - riddle · Riddle and challenge-style interactions.
bloom/base/riddle.js - fun · Lightweight entertainment and playful commands.
bloom/base/fun.js - media · Media handling and content utilities.
bloom/base/media.js - apis · Commands backed by external APIs.
bloom/base/apis.js - menu · Menu and command discovery surface.
bloom/base/menu.js
Support services
Auth, persistence, cache, and external integrations.
- auth.js · Authentication and WhatsApp session handling.
colors/auth.js - schema.js · Configuration and persistence schema layer.
colors/schema.js - setup.js · Startup initialization for configuration and persistence.
colors/setup.js - redis.js · Fast runtime state and ephemeral cache.
colors/redis.js - groq.js · AI-style response or external generation integration.
colors/groq.js - react.js · Automated reaction/response helper.
colors/react.js - pokemon.js · Background gameplay or spawn-related feature support.
colors/pokemon.js
Deployment
Container and hosting entry points.
- Dockerfile · Container image definition.
Dockerfile - docker-compose · Containerized runtime composition.
docker-compose.yml - fly.toml · Fly.io deployment configuration.
fly.toml
Connections 30
- 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.