# brni05/discos architecture

> Architecture diagram of the GitHub repository brni05/discos, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-09-19). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/brni05/discos
- Repository: https://github.com/brni05/discos

## Overview

##### 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.

## Diagram (Mermaid)

```mermaid
graph TD
  subgraph "Discord Cloud"
    GW["Discord Gateway\n(WebSocket)"]:::network
    API["Discord REST API & CDN\n(REST)"]:::network
  end

  subgraph "DiscOS Bot (Node.js/TypeScript)"
    subgraph "Startup Layer"
      Index["index.ts"]:::core
      Startup["startup.ts"]:::core
      SlashReg["slash-commands.ts"]:::core
    end

    EventDispatcher["Event Dispatcher"]:::core

    subgraph "Command Modules"
      Admin["admin.ts"]:::core
      Clear["clear.ts"]:::core
      CmdMod["command.ts"]:::core
      Debug["debug.ts"]:::core
      FileMod["file.ts"]:::core
      Watch["watch.ts"]:::core
    end

    subgraph "Tools"
      BackendMode["backend.ts"]:::core
      IPCClient["ipcServer.ts"]:::host
      Queue["queue-utils.ts"]:::core
      ValDB["validateDb.ts"]:::core
      ValEnv["validateDotenv.ts"]:::core
    end

    subgraph "Shared Config & Types"
      Common["common.ts"]:::core
      Config["config.ts"]:::core
      SharedTypes["shared/index.ts"]:::core
    end
  end

  subgraph "Host OS Shell"
    Shell["cmd-executor.sh"]:::host
  end

  subgraph "Persistence / Config"
    DB["setup/db.json"]:::persistence
    Env["setup/.env"]:::persistence
  end

  subgraph "Deployment"
    Dock["Dockerfile\ndocker-compose.yaml"]:::deployment
    Service["setup/discos.service"]:::deployment
  end

  %% Connections
  GW -->|events| Index
  Index --> Startup
  Startup --> SlashReg
  SlashReg --> EventDispatcher

  EventDispatcher -->|dispatch| Admin
  EventDispatcher -->|dispatch| Clear
  EventDispatcher -->|dispatch| CmdMod
  EventDispatcher -->|dispatch| Debug
  EventDispatcher -->|dispatch| FileMod
  EventDispatcher -->|dispatch| Watch

  EventDispatcher -->|exec| Shell
  Shell -->|output| EventDispatcher

  EventDispatcher -->|respond| API

  EventDispatcher -->|IPC requests| IPCClient
  IPCClient -.->|IPC socket| Shell

  BackendMode --> EventDispatcher
  Queue --> EventDispatcher
  ValDB --> Startup
  ValEnv --> Startup

  Common --> Startup
  Config --> Startup
  SharedTypes --> Admin
  SharedTypes --> Queue

  DB --> ValDB
  Env --> ValEnv

  Dock --> Index
  Dock --> Shell
  Service --> Index
  Service --> Shell

  %% Click Events
  click Index "https://github.com/brni05/discos/blob/main/src/index.ts"
  click Startup "https://github.com/brni05/discos/blob/main/src/startup.ts"
  click SlashReg "https://github.com/brni05/discos/blob/main/src/slash-commands.ts"
  click Common "https://github.com/brni05/discos/blob/main/src/common.ts"
  click Config "https://github.com/brni05/discos/blob/main/src/config.ts"
  click Admin "https://github.com/brni05/discos/blob/main/src/modules/admin.ts"
  click Clear "https://github.com/brni05/discos/blob/main/src/modules/clear.ts"
  click CmdMod "https://github.com/brni05/discos/blob/main/src/modules/command.ts"
  click Debug "https://github.com/brni05/discos/blob/main/src/modules/debug.ts"
  click FileMod "https://github.com/brni05/discos/blob/main/src/modules/file.ts"
  click Watch "https://github.com/brni05/discos/blob/main/src/modules/watch.ts"
  click BackendMode "https://github.com/brni05/discos/blob/main/src/tools/backend.ts"
  click IPCClient "https://github.com/brni05/discos/blob/main/src/tools/ipcServer.ts"
  click Queue "https://github.com/brni05/discos/blob/main/src/tools/queue-utils.ts"
  click ValDB "https://github.com/brni05/discos/blob/main/src/tools/validateDb.ts"
  click ValEnv "https://github.com/brni05/discos/blob/main/src/tools/validateDotenv.ts"
  click SharedTypes "https://github.com/brni05/discos/blob/main/src/shared/index.ts"
  click Shell "https://github.com/brni05/discos/blob/main/src/.sh/cmd-executor.sh"
  click DB "https://github.com/brni05/discos/blob/main/setup/db.json"
  click Env "https://github.com/brni05/discos/blob/main/setup/.env"

  classDef network fill:#CEF,stroke:#69F
  classDef core fill:#CFC,stroke:#393
  classDef host fill:#FDD,stroke:#D33
  classDef persistence fill:#CCC,stroke:#666
  classDef deployment fill:#FFD,stroke:#DA0
```
