Buddai Web Server

Express-based REST back end that powers the Buddai console and integrations. It handles authentication, agent metadata, model registry, environment variables, and bridges to external messaging providers (WhatsApp, Telegram) plus calendar/agenda synchronisation.

Functional Overview

• Authentication & Security

  • /login endpoint validates MongoDB credentials and returns AES-encrypted JWTs.
  • authMiddleware decrypts/verifies tokens before granting access to protected routes.
  • Configuration of JWT/AES secrets and expiry via environment variables.

• Agent Management API (/agents)

  • Lists agent definitions loaded from agents/*.agent.yml on startup.
  • Supports CRUD operations for UI workflows (create, update, delete).
  • Dynamically regenerates IDs and merges updates.

• Models API (/models)

  • Exposes available LLM models and MCP service metadata for the front-end.

• Environment Variables API (/environment_vars)

  • Surfaces configured environment variables, marking secrets for UI masking.
  • Allows updates (in-memory) for quick prototyping and UI adjustments.

• Location API (/location)

  • Proxy endpoints for reading/updating the current user location.

• Messaging Bridges

  • WhatsApp (/whatsapp/status) – QR-based pairing UI + status page; inbound messages routed through Baileys client.
  • Telegram (/telegram) – Simple send/edit wrappers around Telegram Bot API.

• Agenda & Calendar Integration

  • agendaService manages cron-like reminders via Agenda/MongoDB.
  • syncCalendarService coordinates calendar synchronisation with downstream MCPs.

Architecture

• index.js – Express bootstrap, route wiring, service lifecycle (WhatsApp, agenda, sync).
• src/routes/ – HTTP controllers:
  • web/loginController, web/agentsController, web/modelsController for UI API.
  • whatsappController, telegramController, locationController, environmentVarsController for external integrations.
• src/services/ – Core business logic (agents, agenda, messaging, syncing, supervisor calls).
• src/clients/ – Client adapters (e.g., Baileys WhatsApp client).
• src/helpers/ – Utility helpers for message parsing, env var formatting.

Setup & Configuration

Prerequisites

• Node.js ≥ 20.x
• MongoDB instance reachable from the server.
• WhatsApp device for QR pairing (optional).
• Telegram bot token (optional).

Environment Variables

Variable	Purpose	Default
PORT	Server port	8025
MONGO_HOST	MongoDB host for login verification	localhost
JWT_SECRET	JWT signing secret	buddai_supersecret
JWT_EXPIRY	JWT expiration	100y
AES_SECRET	AES encryption key for tokens	buddai_aes256key
TELEGRAM_BOT_TOKEN	Token for Telegram API	required for Telegram
WHATSAPP_*	Credentials/configuration consumed by Baileys	as needed
SYNC_*	Calendar sync configuration	as needed

Ensure MongoDB has users matching login attempts (username/password); the server tests credentials by connecting to mongodb://username:password@MONGO_HOST:27017/username.

Installation

npm install

Development

npm run dev

• Consider using DEBUG=web-server:* to view detailed logs.
• Pair WhatsApp via /whatsapp/status QR page after server starts.

Production

npm run build  # optional: bundle/static assets if needed
node index.js

• Use process managers (PM2, systemd) to supervise the service.
• Configure environment variables and secrets via deployment platform.

API Summary

Endpoint	Method(s)	Description	Auth
/login	POST	Validate MongoDB credentials and issue token	Public
/agents	GET/POST/PUT/DELETE	Manage agent definitions	Protected
/models	GET	List available models	Protected
/environment_vars	GET/PUT	View/update env vars cache	Protected
/location	GET/POST	Manage user location	Public
/whatsapp/status	GET	Status/QR page for WhatsApp bridge	Public
/telegram/send etc.	POST	Telegram messaging helpers	Public/Protected (depending on route)

All protected routes require Authorization: Bearer <encrypted-token> header (token from /login).

Messaging Workflow

• WhatsApp inbound messages → whatsappService → processIncomingMessage helper → callSupervisor (MCP supervisor) → responses returned via Baileys.
• Telegram outbound messages use fetch calls against Telegram Bot API (sendMessage, editMessageText).

Calendar & Agenda

• Agenda jobs persisted in MongoDB for reminders.
• Sync service orchestrates calendar updates; ensure required MCP services are reachable.

Docker

• Dockerfile builds the service with Node 22, copies dependencies, and exposes port 8025.
• Use docker build -t buddai/web-server web_server to create an image.
• Compose with other stack services using provided docker-compose files.

Logging

• Uses debug namespaces (web-server:*).
• Enable via DEBUG=web-server:* or more granular selectors.

Roadmap Ideas

• Harden login flow with rate limiting/captcha.
• Persist environment variable edits to backing store.
• Add WebSocket/SSE for realtime supervisor updates.
• Expand Telegram router with webhooks and inbound handling.

License

Internal Buddai project. Reach out to maintainers for usage or redistribution guidance.