# cue2g/ciwok_bot architecture

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

- Interactive diagram: https://gitdiagram.com/cue2g/ciwok_bot
- Repository: https://github.com/cue2g/ciwok_bot

## Overview

ciwokBot is a Telegram bot for registering task work against groups and service types. Users register a group and unit value, start a task flow, select a service, and submit an assignee and quantity; the bot calculates a value and sends the task to an external endpoint. A direct `/tarea` command also submits task details. MongoDB-backed group, user, and active-session state supports these flows. The excerpts show command wiring, persistence calls, and submission; other runtime details are included only where documented or visible in the sampled files.

Main entry points: [`src/cmds.ts`](https://github.com/cue2g/ciwok_bot/blob/master/src/cmds.ts) (Command registry), [`src/controllers/botController.ts`](https://github.com/cue2g/ciwok_bot/blob/master/src/controllers/botController.ts) (Task calculation), [`src/cmds/start.ts`](https://github.com/cue2g/ciwok_bot/blob/master/src/cmds/start.ts) (Start task flow), [`src/controllers/groupsControllers.ts`](https://github.com/cue2g/ciwok_bot/blob/master/src/controllers/groupsControllers.ts) (Group service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Bot runtime"]
  node_runtime["Bot and health host<br/>[app.ts]"]
  node_registry["Command registry<br/>[cmds.ts]"]
end

subgraph group_flows["Task flows"]
  node_addgroup["Register group<br/>[addGroup.ts]"]
  node_start["Start task flow<br/>[start.ts]"]
  node_services["Choose service<br/>[services.ts]"]
  node_directtask["Direct task<br/>[tarea.ts]"]
end

subgraph group_domain["Domain services"]
  node_tasklogic["Task calculation<br/>[botController.ts]"]
  node_groupctrl["Group service"]
  node_userctrl["User service<br/>[usersController.ts]"]
  node_activectrl["Active session service"]
end

subgraph group_data["Persistence"]
  node_groups[("Groups<br/>[Groups.ts]")]
  node_users[("Users<br/>[Users.ts]")]
  node_activeusers[("Active users<br/>[ActiveUsers.ts]")]
end

node_operator(("Telegram user"))
node_telegram(("Telegram"))
node_api{{"Task API"}}
node_mongo[("MongoDB")]

node_operator -->|"sends commands"| node_telegram
node_runtime -->|"registers commands"| node_registry
node_registry -->|"routes /start"| node_start
node_registry -->|"routes command"| node_addgroup
node_registry -->|"routes action"| node_services
node_registry -->|"routes command"| node_directtask
node_telegram -.->|"delivers updates"| node_registry
node_addgroup -->|"checks and creates"| node_groupctrl
node_start -->|"checks group"| node_groupctrl
node_start -->|"registers session"| node_activectrl
node_start -->|"checks and creates"| node_userctrl
node_start -->|"sends service menu"| node_telegram
node_services -->|"updates and reads"| node_activectrl
node_services -->|"saves task"| node_tasklogic
node_directtask -->|"checks group"| node_groupctrl
node_directtask -->|"submits task"| node_tasklogic
node_tasklogic -->|"gets group value"| node_groupctrl
node_tasklogic -->|"gets author"| node_userctrl
node_tasklogic -->|"posts task"| node_api
node_tasklogic -->|"announces task"| node_telegram
node_groupctrl -->|"queries and writes"| node_groups
node_userctrl -->|"queries and writes"| node_users
node_activectrl -->|"queries and writes"| node_activeusers
node_runtime -->|"connects"| node_mongo
node_runtime -->|"launches bot"| node_telegram

click node_runtime "https://github.com/cue2g/ciwok_bot/blob/master/app.ts"
click node_registry "https://github.com/cue2g/ciwok_bot/blob/master/src/cmds.ts"
click node_addgroup "https://github.com/cue2g/ciwok_bot/blob/master/src/cmds/addGroup.ts"
click node_start "https://github.com/cue2g/ciwok_bot/blob/master/src/cmds/start.ts"
click node_services "https://github.com/cue2g/ciwok_bot/blob/master/src/cmds/services.ts"
click node_directtask "https://github.com/cue2g/ciwok_bot/blob/master/src/cmds/tarea.ts"
click node_tasklogic "https://github.com/cue2g/ciwok_bot/blob/master/src/controllers/botController.ts"
click node_groupctrl "https://github.com/cue2g/ciwok_bot/blob/master/src/controllers/groupsControllers.ts"
click node_userctrl "https://github.com/cue2g/ciwok_bot/blob/master/src/controllers/usersController.ts"
click node_activectrl "https://github.com/cue2g/ciwok_bot/blob/master/src/controllers/activeUsersController.ts"
click node_groups "https://github.com/cue2g/ciwok_bot/blob/master/src/models/Groups.ts"
click node_users "https://github.com/cue2g/ciwok_bot/blob/master/src/models/Users.ts"
click node_activeusers "https://github.com/cue2g/ciwok_bot/blob/master/src/models/ActiveUsers.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_runtime,node_registry,node_operator toneBlue
class node_addgroup,node_start,node_services,node_directtask,node_mongo toneAmber
class node_tasklogic,node_groupctrl,node_userctrl,node_activectrl toneMint
class node_groups,node_users,node_activeusers,node_api toneRose
class node_telegram toneIndigo
```

## Components

### Bot runtime

- [Bot and health host](https://github.com/cue2g/ciwok_bot/blob/master/app.ts): `app.ts`
- [Command registry](https://github.com/cue2g/ciwok_bot/blob/master/src/cmds.ts): `src/cmds.ts`

### Task flows

- [Register group](https://github.com/cue2g/ciwok_bot/blob/master/src/cmds/addGroup.ts): `src/cmds/addGroup.ts`
- [Start task flow](https://github.com/cue2g/ciwok_bot/blob/master/src/cmds/start.ts): `src/cmds/start.ts`
- [Choose service](https://github.com/cue2g/ciwok_bot/blob/master/src/cmds/services.ts): `src/cmds/services.ts`
- [Direct task](https://github.com/cue2g/ciwok_bot/blob/master/src/cmds/tarea.ts): `src/cmds/tarea.ts`

### Domain services

- [Task calculation](https://github.com/cue2g/ciwok_bot/blob/master/src/controllers/botController.ts): `src/controllers/botController.ts`
- [Group service](https://github.com/cue2g/ciwok_bot/blob/master/src/controllers/groupsControllers.ts): `src/controllers/groupsControllers.ts`
- [User service](https://github.com/cue2g/ciwok_bot/blob/master/src/controllers/usersController.ts): `src/controllers/usersController.ts`
- [Active session service](https://github.com/cue2g/ciwok_bot/blob/master/src/controllers/activeUsersController.ts): `src/controllers/activeUsersController.ts`

### Persistence

- [Groups](https://github.com/cue2g/ciwok_bot/blob/master/src/models/Groups.ts): `src/models/Groups.ts`
- [Users](https://github.com/cue2g/ciwok_bot/blob/master/src/models/Users.ts): `src/models/Users.ts`
- [Active users](https://github.com/cue2g/ciwok_bot/blob/master/src/models/ActiveUsers.ts): `src/models/ActiveUsers.ts`

### Other components

- **Telegram user**
- **Telegram**
- **Task API**
- **MongoDB**

## Connections

- Telegram user → Telegram: sends commands (evidence: `README.md`)
- Bot and health host → Command registry: registers commands (evidence: `app.ts`)
- Command registry → Start task flow: routes /start (evidence: `src/cmds.ts`)
- Command registry → Register group: routes command (evidence: `src/cmds.ts`)
- Command registry → Choose service: routes action (evidence: `src/cmds.ts`)
- Command registry → Direct task: routes command (evidence: `src/cmds.ts`)
- Telegram → Command registry: delivers updates
- Register group → Group service: checks and creates (evidence: `src/cmds/addGroup.ts`)
- Start task flow → Group service: checks group (evidence: `src/cmds/start.ts`)
- Start task flow → Active session service: registers session (evidence: `src/cmds/start.ts`)
- Start task flow → User service: checks and creates (evidence: `src/cmds/start.ts`)
- Start task flow → Telegram: sends service menu (evidence: `src/cmds/start.ts`)
- Choose service → Active session service: updates and reads (evidence: `src/cmds/services.ts`)
- Choose service → Task calculation: saves task (evidence: `src/cmds/services.ts`)
- Direct task → Group service: checks group (evidence: `src/cmds/tarea.ts`)
- Direct task → Task calculation: submits task (evidence: `src/cmds/tarea.ts`)
- Task calculation → Group service: gets group value (evidence: `src/controllers/botController.ts`)
- Task calculation → User service: gets author (evidence: `src/controllers/botController.ts`)
- Task calculation → Task API: posts task (evidence: `src/controllers/botController.ts`)
- Task calculation → Telegram: announces task (evidence: `src/controllers/botController.ts`)
- Group service → Groups: queries and writes (evidence: `src/controllers/groupsControllers.ts`)
- User service → Users: queries and writes (evidence: `src/controllers/usersController.ts`)
- Active session service → Active users: queries and writes (evidence: `src/controllers/activeUsersController.ts`)
- Bot and health host → MongoDB: connects (evidence: `app.ts`)
- Bot and health host → Telegram: launches bot (evidence: `app.ts`)
