# ruanlopes1350/shark_guardian_bot architecture

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

- Interactive diagram: https://gitdiagram.com/ruanlopes1350/shark_guardian_bot
- Repository: https://github.com/ruanlopes1350/shark_guardian_bot

## Overview

Shark Guardian TS is a WhatsApp group-management bot. Incoming WhatsApp messages pass through the central interceptor, which applies automatic safety checks and resolves commands; accepted commands proceed through command classes, controllers, and business services to SQLite-backed repositories, with standardized replies sent through the WhatsApp connection. The README also describes moderation, group administration, economy, stickers, and YouTube downloads. Some subsystem links reflect documented architecture and capabilities; unsampled implementation details are not inferred.

Main entry points: [`src/middleware/interceptadorMensagem.ts`](https://github.com/ruanlopes1350/shark_guardian_bot/blob/main/src/middleware/interceptadorMensagem.ts) (Message interceptor), [`src/utils/RespostaComum.ts`](https://github.com/ruanlopes1350/shark_guardian_bot/blob/main/src/utils/RespostaComum.ts) (Standard replies), [`src/command`](https://github.com/ruanlopes1350/shark_guardian_bot/tree/main/src/command) (Command handlers), [`src/repository/repositorioGrupo.ts`](https://github.com/ruanlopes1350/shark_guardian_bot/blob/main/src/repository/repositorioGrupo.ts) (Group repository)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Bot Runtime"]
  node_entry["Bot entry<br/>[index.ts]"]
  node_interceptor["Message interceptor"]
  node_registry["Command registry"]
  node_commands["Command handlers"]
  node_reply["Standard replies<br/>[RespostaComum.ts]"]
end

subgraph group_moderation["Safety and Groups"]
  node_groupctl["Group controller"]
  node_groupservice["Group services<br/>[servicoGrupo.ts]"]
  node_autmod["Automatic moderation"]
  node_antilink["Anti-link rules<br/>[servicoAntiLink.ts]"]
end

subgraph group_features["Bot Features"]
  node_mediacontrol["Media controller"]
  node_mediaservice["Media services<br/>[servicoMidia.ts]"]
  node_userctl["User controller"]
  node_userservice["User services<br/>[servicoUsuario.ts]"]
end

subgraph group_data["Persistence"]
  node_reposgroup["Group repository"]
  node_reposuser["User repository"]
  node_reposcmd["Command repository"]
  node_dbconnect["SQLite connection<br/>[DbConnect.ts]"]
  node_database[("SQLite database")]
end

node_members(("WhatsApp users"))
node_whatsapp(("WhatsApp"))
node_youtube["YouTube"]
node_ffmpeg["FFmpeg"]

node_members -->|"send messages"| node_whatsapp
node_whatsapp -->|"deliver events"| node_entry
node_entry -->|"process messages"| node_interceptor
node_entry -->|"register commands"| node_registry
node_entry -->|"connect socket"| node_whatsapp
node_interceptor -->|"resolve command"| node_registry
node_interceptor -->|"read group rules"| node_reposgroup
node_interceptor -->|"read user state"| node_reposuser
node_interceptor -->|"moderate messages"| node_whatsapp
node_interceptor -->|"dispatch accepted command"| node_commands
node_commands -->|"delegate group actions"| node_groupctl
node_commands -->|"delegate media actions"| node_mediacontrol
node_commands -->|"delegate user actions"| node_userctl
node_groupctl -->|"delegate group rules"| node_groupservice
node_groupctl -->|"delegate moderation"| node_autmod
node_groupservice -->|"read and write group data"| node_reposgroup
node_autmod -->|"read and write moderation data"| node_reposgroup
node_autmod -->|"record user sanctions"| node_reposuser
node_antilink -->|"read and write link rules"| node_reposgroup
node_mediacontrol -->|"delegate media work"| node_mediaservice
node_mediaservice -.->|"download media"| node_youtube
node_mediaservice -.->|"convert media"| node_ffmpeg
node_userctl -->|"delegate user actions"| node_userservice
node_userservice -->|"read and write user data"| node_reposuser
node_registry -->|"sync command settings"| node_reposcmd
node_reposgroup -->|"query database"| node_dbconnect
node_reposuser -->|"query database"| node_dbconnect
node_reposcmd -->|"query database"| node_dbconnect
node_dbconnect -->|"read and write"| node_database
node_reply -->|"send formatted replies"| node_whatsapp
node_commands -->|"format responses"| node_reply
node_groupservice -->|"send responses"| node_reply
node_autmod -->|"send responses"| node_reply
node_mediaservice -->|"send media"| node_reply
node_userservice -->|"send responses"| node_reply

click node_entry "https://github.com/ruanlopes1350/shark_guardian_bot/blob/main/src/index.ts"
click node_interceptor "https://github.com/ruanlopes1350/shark_guardian_bot/blob/main/src/middleware/interceptadorMensagem.ts"
click node_registry "https://github.com/ruanlopes1350/shark_guardian_bot/blob/main/src/core/RegistradorComandos.ts"
click node_commands "https://github.com/ruanlopes1350/shark_guardian_bot/tree/main/src/command"
click node_reply "https://github.com/ruanlopes1350/shark_guardian_bot/blob/main/src/utils/RespostaComum.ts"
click node_groupctl "https://github.com/ruanlopes1350/shark_guardian_bot/blob/main/src/controller/controladorGrupo.ts"
click node_groupservice "https://github.com/ruanlopes1350/shark_guardian_bot/blob/main/src/service/servicoGrupo.ts"
click node_autmod "https://github.com/ruanlopes1350/shark_guardian_bot/blob/main/src/service/servicoModeracaoAutomatica.ts"
click node_antilink "https://github.com/ruanlopes1350/shark_guardian_bot/blob/main/src/service/servicoAntiLink.ts"
click node_mediacontrol "https://github.com/ruanlopes1350/shark_guardian_bot/blob/main/src/controller/controladorMidia.ts"
click node_mediaservice "https://github.com/ruanlopes1350/shark_guardian_bot/blob/main/src/service/servicoMidia.ts"
click node_userctl "https://github.com/ruanlopes1350/shark_guardian_bot/blob/main/src/controller/controladorUsuario.ts"
click node_userservice "https://github.com/ruanlopes1350/shark_guardian_bot/blob/main/src/service/servicoUsuario.ts"
click node_reposgroup "https://github.com/ruanlopes1350/shark_guardian_bot/blob/main/src/repository/repositorioGrupo.ts"
click node_reposuser "https://github.com/ruanlopes1350/shark_guardian_bot/blob/main/src/repository/repositorioUsuario.ts"
click node_reposcmd "https://github.com/ruanlopes1350/shark_guardian_bot/blob/main/src/repository/repositorioComando.ts"
click node_dbconnect "https://github.com/ruanlopes1350/shark_guardian_bot/blob/main/src/config/db/DbConnect.ts"

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_entry,node_interceptor,node_registry,node_commands,node_reply,node_members toneBlue
class node_groupctl,node_groupservice,node_autmod,node_antilink toneAmber
class node_mediacontrol,node_mediaservice,node_userctl,node_userservice toneMint
class node_reposgroup,node_reposuser,node_reposcmd,node_dbconnect,node_database toneRose
class node_whatsapp,node_youtube,node_ffmpeg toneIndigo
```

## Components

### Bot Runtime

- [Bot entry](https://github.com/ruanlopes1350/shark_guardian_bot/blob/main/src/index.ts): `src/index.ts`
- [Message interceptor](https://github.com/ruanlopes1350/shark_guardian_bot/blob/main/src/middleware/interceptadorMensagem.ts): `src/middleware/interceptadorMensagem.ts`
- [Command registry](https://github.com/ruanlopes1350/shark_guardian_bot/blob/main/src/core/RegistradorComandos.ts): `src/core/RegistradorComandos.ts`
- [Command handlers](https://github.com/ruanlopes1350/shark_guardian_bot/tree/main/src/command): `src/command`
- [Standard replies](https://github.com/ruanlopes1350/shark_guardian_bot/blob/main/src/utils/RespostaComum.ts): `src/utils/RespostaComum.ts`

### Safety and Groups

- [Group controller](https://github.com/ruanlopes1350/shark_guardian_bot/blob/main/src/controller/controladorGrupo.ts): `src/controller/controladorGrupo.ts`
- [Group services](https://github.com/ruanlopes1350/shark_guardian_bot/blob/main/src/service/servicoGrupo.ts): `src/service/servicoGrupo.ts`
- [Automatic moderation](https://github.com/ruanlopes1350/shark_guardian_bot/blob/main/src/service/servicoModeracaoAutomatica.ts): `src/service/servicoModeracaoAutomatica.ts`
- [Anti-link rules](https://github.com/ruanlopes1350/shark_guardian_bot/blob/main/src/service/servicoAntiLink.ts): `src/service/servicoAntiLink.ts`

### Bot Features

- [Media controller](https://github.com/ruanlopes1350/shark_guardian_bot/blob/main/src/controller/controladorMidia.ts): `src/controller/controladorMidia.ts`
- [Media services](https://github.com/ruanlopes1350/shark_guardian_bot/blob/main/src/service/servicoMidia.ts): `src/service/servicoMidia.ts`
- [User controller](https://github.com/ruanlopes1350/shark_guardian_bot/blob/main/src/controller/controladorUsuario.ts): `src/controller/controladorUsuario.ts`
- [User services](https://github.com/ruanlopes1350/shark_guardian_bot/blob/main/src/service/servicoUsuario.ts): `src/service/servicoUsuario.ts`

### Persistence

- [Group repository](https://github.com/ruanlopes1350/shark_guardian_bot/blob/main/src/repository/repositorioGrupo.ts): `src/repository/repositorioGrupo.ts`
- [User repository](https://github.com/ruanlopes1350/shark_guardian_bot/blob/main/src/repository/repositorioUsuario.ts): `src/repository/repositorioUsuario.ts`
- [Command repository](https://github.com/ruanlopes1350/shark_guardian_bot/blob/main/src/repository/repositorioComando.ts): `src/repository/repositorioComando.ts`
- [SQLite connection](https://github.com/ruanlopes1350/shark_guardian_bot/blob/main/src/config/db/DbConnect.ts): `src/config/db/DbConnect.ts`
- **SQLite database**

### Other components

- **WhatsApp users**
- **WhatsApp**
- **YouTube**
- **FFmpeg**

## Connections

- WhatsApp users → WhatsApp: send messages
- WhatsApp → Bot entry: deliver events
- Bot entry → Message interceptor: process messages
- Bot entry → Command registry: register commands
- Bot entry → WhatsApp: connect socket
- Message interceptor → Command registry: resolve command
- Message interceptor → Group repository: read group rules
- Message interceptor → User repository: read user state
- Message interceptor → WhatsApp: moderate messages
- Message interceptor → Command handlers: dispatch accepted command
- Command handlers → Group controller: delegate group actions
- Command handlers → Media controller: delegate media actions
- Command handlers → User controller: delegate user actions
- Group controller → Group services: delegate group rules
- Group controller → Automatic moderation: delegate moderation
- Group services → Group repository: read and write group data
- Automatic moderation → Group repository: read and write moderation data
- Automatic moderation → User repository: record user sanctions
- Anti-link rules → Group repository: read and write link rules
- Media controller → Media services: delegate media work
- Media services → YouTube: download media
- Media services → FFmpeg: convert media
- User controller → User services: delegate user actions
- User services → User repository: read and write user data
- Command registry → Command repository: sync command settings
- Group repository → SQLite connection: query database
- User repository → SQLite connection: query database
- Command repository → SQLite connection: query database
- SQLite connection → SQLite database: read and write
- Standard replies → WhatsApp: send formatted replies
- Command handlers → Standard replies: format responses
- Group services → Standard replies: send responses
- Automatic moderation → Standard replies: send responses
- Media services → Standard replies: send media
- User services → Standard replies: send responses