How brni05/discos works
Project type and purpose
• DiscOS is a backend-only (service/daemon) application written in Node.js/TypeScript that bridges Discord and a Linux host shell.
• It listens to slash commands from Discord, executes them (or admin commands) on the server, and returns output or files via the Discord API.
File structure
Top-level directories and files:
• Dockerfile, docker-compose.yaml, setup/ – container or systemd preparation, environment & DB templates.
• src/ – application code:
• index.ts & startup.ts – bot bootstrapping and Discord gateway connection
• common.ts, config.ts – shared configuration & constants
• modules/ – each slash-command implementation (admin.ts, command.ts, file.ts, watch.ts, etc.)
• tools/ – helper subsystems (backend mode toggle, IPC server, queue utils, env/db validation)
• shared/ & types/ – shared types, interfaces, constants
• scripts/ – release tooling.
• .github/, .husky/, eslint/prettier configs – CI/CD, linting, pre-commit checks.
README for additional insights
• Describes two modes: standalone (all logic in one Node.js process) and external backend mode (validation via IPC server).
• Features slash commands for users (/dcos) and admins (/admos).
• Security emphasizes safe shell-escaping, ephemeral replies, minimal logging.
• Supported deployment: systemd service, Docker container, npm package.
Main components
a. Discord Cloud
• Discord Gateway (WebSocket) for event subscription
• Discord REST API & CDN for command registration, replies, file uploads/downloads
b. DiscOS Bot Process (Node.js/TypeScript)
• Startup & command registration
• Event dispatcher → module handlers
• Modules (user and admin commands)
• Tools (IPC client/server, queue manager, validators)
c. Linux Host Shell
• Child processes via cmd-executor.sh
• Working directory and OS user context
d. (Optional) External IPC Backend
• IPC server (Unix socket or TCP) for validating commands / payloads
e. Persistence / Config
• JSON file or environment variables (from setup/db.json, setup/.env)
f. Deployment envelope
• Docker container or Systemd unit
Relationships & data flow
1. User issues slash command in Discord → Discord Gateway → Bot Process event handler
2. Bot parses event → dispatches to the appropriate module (e.g. file.ts, watch.ts)
3. Module performs:
• CLI execution via cmd-executor.sh → Shell → returns stdout/stderr
• File I/O (read/write and send via Discord CDN)
• Admin commands adjust in-memory or JSON config
• If external backend mode: Bot ↔ IPC backend over IPC server
4. Bot sends response via Discord REST API (message or file attachment)
Architectural patterns & design principles
• Plugin/event-driven: each slash command is its own module under src/modules.
• Single responsibility: tools/ folder isolates cross-cutting concerns (validation, queuing, IPC).
• Config as code: environment variables + JSON DB for runtime toggles.
• Secure by default: shell escaping, ephemeral replies, minimal secrets.