# ultsi/blakkisvuohi architecture

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

- Interactive diagram: https://gitdiagram.com/ultsi/blakkisvuohi
- Repository: https://github.com/ultsi/blakkisvuohi

## Overview

BläkkisVuohi is a Telegram bot for recording drinks and estimating current blood-alcohol concentration (EBAC). Users add drinks through commands or the guided /start flow; the bot calculates and reports estimates. Group commands extend this with member and drink summaries, while separate commands provide personal history, charts and statistics. The graph follows the documented capabilities and indexed module references; several command implementations and runtime wiring were not sampled, so uncertain links are omitted.

Main entry points: [`app/db/users.js`](https://github.com/ultsi/blakkisvuohi/blob/master/app/db/users.js) (User profiles), [`app/db/groups.js`](https://github.com/ultsi/blakkisvuohi/blob/master/app/db/groups.js) (Group summaries), [`app/lib/commands.js`](https://github.com/ultsi/blakkisvuohi/blob/master/app/lib/commands.js) (Command dispatch), [`app/init.js`](https://github.com/ultsi/blakkisvuohi/blob/master/app/init.js) (Message hooks)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingress["Bot and commands"]
  node_entry["Bot entry<br/>[index.js]"]
  node_hooks["Message hooks<br/>[init.js]"]
  node_dispatch["Command dispatch<br/>[commands.js]"]
end

subgraph group_drinks["Drinks and EBAC"]
  node_drinkflow["Guided drinking<br/>[juo.js]"]
  node_adddrink["Add drink<br/>[juoma.js]"]
  node_backdate["Backdated drinks<br/>[jalkikellotus.js]"]
  node_drinkshortcuts["Drink shortcuts<br/>[kalja033.js]"]
  node_drinkmath["Alcohol calculations<br/>[alcomath.js]"]
end

subgraph group_community["Users and groups"]
  node_profile["User profiles<br/>[users.js]"]
  node_profilecmd["Profile commands<br/>[tunnus.js]"]
  node_settingsflow["Setup settings<br/>[asetukset.js]"]
  node_groupdata["Group summaries<br/>[groups.js]"]
  node_groupcommands["Group commands<br/>[promillet.js]"]
end

subgraph group_insights["History and statistics"]
  node_drinkhistory["Drink history<br/>[annokset.js]"]
  node_chart["Group chart<br/>[kuvaaja.js]"]
  node_chartengine["Chart rendering<br/>[linechart.js]"]
  node_statistics["Usage statistics<br/>[stats.js]"]
  node_statscommands["Statistics commands<br/>[stats.js]"]
end

subgraph group_shared["Shared runtime"]
  node_messages["Message helpers<br/>[message.js]"]
  node_settings["Bot settings<br/>[settings.js]"]
end

node_telegram(("Telegram user"))
node_postgres[("PostgreSQL")]

node_telegram -->|"sends updates"| node_hooks
node_entry -->|"initializes"| node_hooks
node_hooks -->|"forwards updates"| node_dispatch
node_hooks -->|"loads commands"| node_adddrink
node_dispatch -->|"loads user"| node_profile
node_dispatch -->|"reads settings"| node_settings
node_dispatch -.->|"dispatches flow"| node_drinkflow
node_drinkflow -->|"records drinks"| node_profile
node_drinkflow -->|"calculates EBAC"| node_drinkmath
node_adddrink -->|"checks alcohol"| node_drinkmath
node_adddrink -->|"builds replies"| node_messages
node_backdate -->|"checks alcohol"| node_drinkmath
node_drinkshortcuts -->|"records drinks"| node_profile
node_profilecmd -->|"updates profile"| node_profile
node_settingsflow -->|"updates settings"| node_profile
node_groupcommands -->|"fetches summaries"| node_groupdata
node_groupdata -->|"builds member data"| node_profile
node_groupdata -->|"calculates EBAC"| node_drinkmath
node_drinkhistory -->|"fetches drink data"| node_groupdata
node_chart -->|"fetches drink data"| node_groupdata
node_chart -->|"renders chart"| node_chartengine
node_chart -->|"loads users"| node_profile
node_statscommands -->|"fetches statistics"| node_statistics
node_profile -->|"queries"| node_postgres
node_groupdata -->|"queries"| node_postgres
node_statistics -->|"queries"| node_postgres

click node_entry "https://github.com/ultsi/blakkisvuohi/blob/master/index.js"
click node_hooks "https://github.com/ultsi/blakkisvuohi/blob/master/app/init.js"
click node_dispatch "https://github.com/ultsi/blakkisvuohi/blob/master/app/lib/commands.js"
click node_drinkflow "https://github.com/ultsi/blakkisvuohi/blob/master/app/commands/start/juo.js"
click node_adddrink "https://github.com/ultsi/blakkisvuohi/blob/master/app/commands/juoma.js"
click node_backdate "https://github.com/ultsi/blakkisvuohi/blob/master/app/commands/jalkikellotus.js"
click node_drinkshortcuts "https://github.com/ultsi/blakkisvuohi/blob/master/app/commands/kalja033.js"
click node_drinkmath "https://github.com/ultsi/blakkisvuohi/blob/master/app/lib/alcomath.js"
click node_profile "https://github.com/ultsi/blakkisvuohi/blob/master/app/db/users.js"
click node_profilecmd "https://github.com/ultsi/blakkisvuohi/blob/master/app/commands/tunnus.js"
click node_settingsflow "https://github.com/ultsi/blakkisvuohi/blob/master/app/commands/start/asetukset.js"
click node_groupdata "https://github.com/ultsi/blakkisvuohi/blob/master/app/db/groups.js"
click node_groupcommands "https://github.com/ultsi/blakkisvuohi/blob/master/app/commands/promillet.js"
click node_drinkhistory "https://github.com/ultsi/blakkisvuohi/blob/master/app/commands/annokset.js"
click node_chart "https://github.com/ultsi/blakkisvuohi/blob/master/app/commands/kuvaaja.js"
click node_chartengine "https://github.com/ultsi/blakkisvuohi/blob/master/app/lib/linechart.js"
click node_statistics "https://github.com/ultsi/blakkisvuohi/blob/master/app/db/stats.js"
click node_statscommands "https://github.com/ultsi/blakkisvuohi/blob/master/app/commands/stats.js"
click node_messages "https://github.com/ultsi/blakkisvuohi/blob/master/app/lib/message.js"
click node_settings "https://github.com/ultsi/blakkisvuohi/blob/master/app/settings.js"

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_hooks,node_dispatch,node_telegram toneBlue
class node_drinkflow,node_adddrink,node_backdate,node_drinkshortcuts,node_drinkmath,node_postgres toneAmber
class node_profile,node_profilecmd,node_settingsflow,node_groupdata,node_groupcommands toneMint
class node_drinkhistory,node_chart,node_chartengine,node_statistics,node_statscommands toneRose
class node_messages,node_settings toneIndigo
```

## Components

### Bot and commands

- [Bot entry](https://github.com/ultsi/blakkisvuohi/blob/master/index.js): `index.js`
- [Message hooks](https://github.com/ultsi/blakkisvuohi/blob/master/app/init.js): `app/init.js`
- [Command dispatch](https://github.com/ultsi/blakkisvuohi/blob/master/app/lib/commands.js): `app/lib/commands.js`

### Drinks and EBAC

- [Guided drinking](https://github.com/ultsi/blakkisvuohi/blob/master/app/commands/start/juo.js): `app/commands/start/juo.js`
- [Add drink](https://github.com/ultsi/blakkisvuohi/blob/master/app/commands/juoma.js): `app/commands/juoma.js`
- [Backdated drinks](https://github.com/ultsi/blakkisvuohi/blob/master/app/commands/jalkikellotus.js): `app/commands/jalkikellotus.js`
- [Drink shortcuts](https://github.com/ultsi/blakkisvuohi/blob/master/app/commands/kalja033.js): `app/commands/kalja033.js`
- [Alcohol calculations](https://github.com/ultsi/blakkisvuohi/blob/master/app/lib/alcomath.js): `app/lib/alcomath.js`

### Users and groups

- [User profiles](https://github.com/ultsi/blakkisvuohi/blob/master/app/db/users.js): `app/db/users.js`
- [Profile commands](https://github.com/ultsi/blakkisvuohi/blob/master/app/commands/tunnus.js): `app/commands/tunnus.js`
- [Setup settings](https://github.com/ultsi/blakkisvuohi/blob/master/app/commands/start/asetukset.js): `app/commands/start/asetukset.js`
- [Group summaries](https://github.com/ultsi/blakkisvuohi/blob/master/app/db/groups.js): `app/db/groups.js`
- [Group commands](https://github.com/ultsi/blakkisvuohi/blob/master/app/commands/promillet.js): `app/commands/promillet.js`

### History and statistics

- [Drink history](https://github.com/ultsi/blakkisvuohi/blob/master/app/commands/annokset.js): `app/commands/annokset.js`
- [Group chart](https://github.com/ultsi/blakkisvuohi/blob/master/app/commands/kuvaaja.js): `app/commands/kuvaaja.js`
- [Chart rendering](https://github.com/ultsi/blakkisvuohi/blob/master/app/lib/linechart.js): `app/lib/linechart.js`
- [Usage statistics](https://github.com/ultsi/blakkisvuohi/blob/master/app/db/stats.js): `app/db/stats.js`
- [Statistics commands](https://github.com/ultsi/blakkisvuohi/blob/master/app/commands/stats.js): `app/commands/stats.js`

### Shared runtime

- [Message helpers](https://github.com/ultsi/blakkisvuohi/blob/master/app/lib/message.js): `app/lib/message.js`
- [Bot settings](https://github.com/ultsi/blakkisvuohi/blob/master/app/settings.js): `app/settings.js`

### Other components

- **Telegram user**
- **PostgreSQL**

## Connections

- Telegram user → Message hooks: sends updates (evidence: `app/init.js`)
- Bot entry → Message hooks: initializes (evidence: `index.js`)
- Message hooks → Command dispatch: forwards updates (evidence: `app/init.js`)
- Message hooks → Add drink: loads commands (evidence: `app/init.js`)
- Command dispatch → User profiles: loads user (evidence: `app/lib/commands.js`)
- Command dispatch → Bot settings: reads settings (evidence: `app/lib/commands.js`)
- Command dispatch → Guided drinking: dispatches flow
- Guided drinking → User profiles: records drinks (evidence: `app/commands/start/juo.js`)
- Guided drinking → Alcohol calculations: calculates EBAC (evidence: `app/commands/start/juo.js`)
- Add drink → Alcohol calculations: checks alcohol (evidence: `app/commands/juoma.js`)
- Add drink → Message helpers: builds replies (evidence: `app/commands/juoma.js`)
- Backdated drinks → Alcohol calculations: checks alcohol (evidence: `app/commands/jalkikellotus.js`)
- Drink shortcuts → User profiles: records drinks (evidence: `app/commands/kalja033.js`)
- Profile commands → User profiles: updates profile (evidence: `app/commands/tunnus.js`)
- Setup settings → User profiles: updates settings (evidence: `app/commands/start/asetukset.js`)
- Group commands → Group summaries: fetches summaries (evidence: `app/commands/promillet.js`)
- Group summaries → User profiles: builds member data (evidence: `app/db/groups.js`)
- Group summaries → Alcohol calculations: calculates EBAC (evidence: `app/db/groups.js`)
- Drink history → Group summaries: fetches drink data (evidence: `app/commands/annokset.js`)
- Group chart → Group summaries: fetches drink data (evidence: `app/commands/kuvaaja.js`)
- Group chart → Chart rendering: renders chart (evidence: `app/commands/kuvaaja.js`)
- Group chart → User profiles: loads users (evidence: `app/commands/kuvaaja.js`)
- Statistics commands → Usage statistics: fetches statistics (evidence: `app/commands/stats.js`)
- User profiles → PostgreSQL: queries (evidence: `app/db/users.js`)
- Group summaries → PostgreSQL: queries (evidence: `app/db/groups.js`)
- Usage statistics → PostgreSQL: queries (evidence: `app/db/stats.js`)
