status-im/status-bot
1
0
Fork 0
mirror of https://github.com/status-im/status-bot.git synced 2026-08-27 10:41:08 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: add mkdocs

Browse Source 
Signed-off-by: apentori <pentori.alexis@proton.me>
This commit is contained in:
apentori
2026-08-18 19:11:29 +02:00
parent e81df82a56
commit 3495699592
8 changed files with 259 additions and 87 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/SUMMARY.md
-26
View File
@@ -1,26 +0,0 @@
# Summary
## Principle
- [Architecture](./overivew.md#architecture)
- [Account](./overview.md#account-setup)
## Development
- [Modules](./development/modules.md)
- [Database](./development/database.md)
## Usages
- [Messaging API](./usage/messaging.md)
- [Community Monitoring](./usage/monitoring.md)
- [Receiver](/usage/receiver.md)
## Deployement
- [Docker Deployement](./deployement/docker.md)
- [Configuration](./deployement/configuration.md)
- [Metrics](./deployement/metrics.md)
docs/deployment/configuration.md
+10 -15
View File
@@ -1,13 +1,14 @@
# Configuration
The bot is configured through a YAML file (`config.yaml`) and environment variables.
Environment variables override values from the YAML file.
The bot is configured through a YAML file (`config.yaml`), environment variables, and an optional `.env` file.
## Loading order
1. `config.yaml` — base configuration
2. Shell environment variables — override YAML values
3. `.env` file — override YAML values (loaded from the same directory as `config.yaml`)
Sources are resolved in priority order (highest first). A value is taken from the first source that defines it; later sources only fill in settings not set by a higher-priority source:
1. `config.yaml` — highest priority; overrides environment variables and the `.env` file
2. Shell environment variables — override the `.env` file
3. `.env` file — lowest priority, used as fallback (loaded from the current working directory)
## Usage
@@ -42,12 +43,6 @@ logging:
## Reference
### `sleep`
| Type | Default | Description |
|------|---------|-------------|
| `int` | `10` | Sleep interval in minutes between monitoring cycles |
### `files`
| Field | Type | Default | Description |
@@ -66,7 +61,7 @@ files:
| Field | Type | Default | Env var | Description |
|-------|------|---------|---------|-------------|
| `name` | `str` | `""` | `BOT__NAME` | Status display name used to log in |
| `public_key` | `str` | `"BOT__PUBLIC_KEY"` | — | Expected public key for verification |
| `public_key` | `str` | `""` | `BOT__PUBLIC_KEY` | Expected public key for verification |
| `password` | `str` | `""` | `BOT__PASSWORD` | Status account password |
| `mnemonic_phrase` | `str` | `""` | `BOT__MNEMONIC_PHRASE` | 12-word recovery phrase (used when `init_account: true`) |
| `init_account` | `bool` | `false` | `BOT__INIT_ACCOUNT` | If `false`, the account must already exist. If `true`, creates or restores the account using `mnemonic_phrase` |
@@ -78,7 +73,7 @@ files:
```yaml
bot:
display_name: 'my-bot'
name: 'my-bot'
public_key: '0x...'
password: 'ChangeMe'
mnemonic_phrase: 'word1 word2 ... word12'
@@ -93,7 +88,7 @@ Parameter to connect to the Status Backend instance.
| Field | Type | Default | Env var | Description |
|-------|------|---------|---------|-------------|
| `domain` | `str` | `"localhost"` | `BACKEND__DOMAIN` | Status Backend hostname (`localhost` for local, `status-backend` for Docker) |
| `port` | `int` | `8080` | `BACKEND__BACKEND_PORT` | Status Backend API port |
| `backend_port` | `int` | `8080` | `BACKEND__BACKEND_PORT` | Status Backend API port |
| `is_secure` | `bool` | `false` | `BACKEND__IS_SECURE` | Use HTTPS instead of HTTP |
```yaml
backend:
@@ -191,7 +186,7 @@ Event payloads are kept in plaintext in-memory so they can be handled correctly;
| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `directories` | `list[str]` | `["./modules"]` | Directories to scan for module `.py` files |
| `directories` | `list[str]` | `["./modules", "bot/modules"]` | Directories to scan for module `.py` files |
| `enabled` | `list[str]` | `[]` | List of module names to enable |
| `settings` | `dict` | `{}` | Per-module settings (each module defines its own schema) |
docs/deployment/docker.md
+3
View File
@@ -0,0 +1,3 @@
# Docker deployement
docs/overview.md → docs/index.md
+2 -1
View File
@@ -24,6 +24,7 @@ graph TB
The Status Bot use [status-python-sdk](https://github.com/status-im/status-python-sdk) for the interraction with Status Backend.
The Status-Backend use external services:
* CoinGecko - Optional to get token price
* EVM access - (Infura for example) required to interract with Token Gated community.
@@ -51,4 +52,4 @@ It first need to export a backup, then import it in the docker container under `
> Note: the account backup need to also be imported in Status Backend
The full configuration explaination can be found at [./deployment/configuration.md]
The full configuration explaination can be found in the [configuration](deployment/configuration.md) page.
docs/stylesheets/extra.css
+104
View File
@@ -0,0 +1,104 @@
/* ==========================================================================
Status.app Theme Overrides for MkDocs Material
========================================================================== */
:root,
[data-md-color-scheme="slate"] {
/* Status Palette */
--status-bg: #090a10; /* Ultra-dark background */
--status-card-bg: #12141d; /* Card/sidebar background */
--status-accent-blue: #4360df; /* Primary brand blue */
--status-accent-purple: #814bf6; /* Accent purple */
--status-text: #eceef8; /* Primary text */
--status-text-muted: #8b92b0; /* Muted secondary text */
--status-border: #1e2235; /* Soft subtle border */
/* Material Theme Token Remapping */
--md-default-bg-color: var(--status-bg);
--md-default-bg-color--light: var(--status-card-bg);
--md-default-bg-color--lighter: #1a1d2c;
--md-default-fg-color: var(--status-text);
--md-default-fg-color--light: var(--status-text-muted);
--md-default-fg-color--lighter: #687093;
/* Primary Accent & Links */
--md-primary-fg-color: var(--status-bg);
--md-accent-fg-color: var(--status-accent-blue);
/* Code Syntax Highlighting Cards */
--md-code-bg-color: #0d0f17;
--md-code-fg-color: #e2e8f0;
}
/* Base Body & Layout */
body {
background-color: var(--status-bg);
color: var(--status-text);
}
/* Header Navbar */
.md-header {
background-color: rgba(9, 10, 16, 0.85) !important;
backdrop-filter: blur(12px);
border-bottom: 1px solid var(--status-border);
}
/* Navigation & Sidebar Cards */
.md-sidebar__inner {
background-color: var(--status-card-bg);
border-radius: 12px;
border: 1px solid var(--status-border);
padding: 1rem;
}
.md-nav__link {
color: var(--status-text-muted);
border-radius: 6px;
transition: color 0.2s ease, background-color 0.2s ease;
}
.md-nav__link--active,
.md-nav__link:hover {
color: #ffffff !important;
background-color: rgba(67, 96, 223, 0.15);
}
/* Content Area Styling */
.md-content {
background-color: var(--status-bg);
}
/* Code Blocks */
.md-typeset pre > code {
border-radius: 10px;
border: 1px solid var(--status-border);
background-color: var(--status-card-bg);
}
/* Admonitions / Callout Boxes */
.md-typeset .admonition,
.md-typeset details {
border-radius: 10px;
border: 1px solid var(--status-border);
box-shadow: 0 4px 20px rgba(0, 0, 0, 0.25);
background-color: var(--status-card-bg);
}
.md-typeset .admonition.note {
border-left-color: var(--status-accent-blue);
}
.md-typeset .admonition.tip {
border-left-color: var(--status-accent-purple);
}
/* Links */
.md-typeset a {
color: #6380ff;
text-decoration: none;
}
.md-typeset a:hover {
color: #a3b5ff;
text-decoration: underline;
}
docs/usage/monitoring.md
+96 -45
View File
@@ -1,58 +1,109 @@
# Community Monitoring
# Monitoring
The Status Bot can be used to monitore activity in community
The Status Bot can store the messages and Community information to allow some analytics.
## Fetch Data
## Received messages
**No personal data is collected from users.**
The messages received by the bot account can be store in the database with the module `receiver`.
Data from `Messages` and `Chats` are hashed with sha256 and a pepper, to avoid storing information openly.
### Messages
| Field | Type | Hashed | Description |
|----|----|----|---|
| id | String | Hashed | Message Id |
| whisper_timestamp | - | DateTime | Timstamp of reception by the last network node |
| from_ | String | Hashed | Address of the sender |
| alias | String | Hashed | User Alias |
| seen | Boolean | - | Flag indicating if the message has been seen |
| rtl | Boolean | - | Flag indicating |
| line_count | Integer | - | |
| text | String | Hashed | Content of the messages |
| chat_id | String | Hashed | Id of the chat link to this message |
| local_chat_id | String | Hashed | Chat id for the local backend instance |
| clock | BigInteger | - | Unix timestamp of the message reception |
| replace | String | - | |
| response_to | String | Hashed | User Id to whom the message is responding |
| ens_name | String | Hashed | ENS name of the sender |
| display_name | String | Hashed | Display Name of the sender |
| timestamp | DateTime | - | timestamp of the message sent |
| content_type | Integer | - | Number indicating the type of message content |
| message_type | Integer | - | Type of message |
| contact_request_state | Integer | - | |
| compressed_key | String | - | Key used to compress the message |
| received_timestamp | DateTime | - | timestamp of the message reception |
### Chats
| Field | Type | Hashed | Description |
|----|----|----|----|
| id | String | | |
| type | String | | |
| name | String | | |
| received_timestamp | DateTime | | |
| description | String | | |
| color | String | | |
| emoji | String | | |
| active | Boolean | | |
| viewers_can_post_reactions | Boolean | | |
| chat_type | Integer | | |
| timestamp | DateTime | | |
| last_clock_value | BigInteger | | |
| deleted_at_clock_value | Integer | | |
| read_messages_at_clock_value | Integer | | |
| unviewed_messages_count | Integer | | |
| unviewed_mentions_count | Integer | | |
| membership_update_events | Integer | | |
| identicon | String | | |
| muted | Boolean | | |
| mute_till | DateTime | | |
| community_id | String | | |
| category_id | String | | |
| joined | String | | |
| Field | Hashed | Description |
|:----------------------|:---------|:------------------------------------------------------------|
| **id** | **Yes** | The message's ID |
| **whisper_timestamp** | No | The whisper timestamp of the message |
| **from** | **Yes** | The public key of the user |
| **message_type** | No | The message type |
| **seen** | No | True if the message has been seen otherwise False |
| **chat_id** | No | The chat ID is a combination of community ID and channel ID |
| **community_id** | No | The ID of the community |
| **response_to** | **Yes** | Ithe public key of the user who the response is for |
| **timestamp** | No | The timestamp of the message |
| **deleted** | No | True if the message was deleted otherwise False |
## Community Monitoring
Status Bot account information can be found in [`config.yaml`](./config.yaml).
The module `communities_monitoring` will allow to periodically fetch information of the community the bot account has access.
## How it works
The data by the Bot are the following.
```mermaid
graph LR
subgraph Communities[Status App]
subgraph Status[Status Community]
StatusMessages[Messages]
StatusInfo[Information]
end
subgraph Logos[Logos Community]
LogosMessages[Messages]
LogosInfo[Information]
end
### Community
end
| Field | Type | Description |
|----|----|----|
| id | String | Community Id |
| url | String | Url to join the community |
| name | String | Name of the community |
| verified | Boolean | Flag if the community is verified |
| tags | String | All the community tags separated by a `,` |
| is_member | Boolean | Flag indicating the community the bot has joined |
| joined_timestamp | DateTime | Timestamp when the account joined the community. `None` when the account has not joined. |
| requested_timestamp | DateTime | Timestamp when the join request was submitted. `None` when no request was made. |
| encrypted | String | Whether the community messaging is encrypted. |
| number_members | Integer | Total number of community members. |
subgraph Bot[Docker Container]
RawDataLocal[(Raw Data)]
Script[monitor.py]
end
### Channels
subgraph IFT[IFT Infrastructure]
RawDataIFT[(Raw Data)]
ProcessedDataIFT[(Processed Data)]
end
Communities <--> |class Account| Script
Script --> |SHA256| RawDataLocal
RawDataLocal --> |Airbyte| RawDataIFT
RawDataIFT --> |dbt| ProcessedDataIFT
```
* `id`: Id of the channel.
* `chat_id`: Chat id of the channel.
* `community_id`: Id of the channel's community.
* `name`: Name of the channel.
* `description`: Description of the channel.
* `can_post`: Can the Bot Post into the channel.
* `can_view`: Can the Bot view the channel.
* `can_post_reaction`: Can the bot react to a Post.
* `token_gated`: Is the channel access limited with a token.
| Key | Type | Description |
|----|----|-------------|
| `id` | String | The channel's own id | | |
| `chat_id` | String | The community id and channel id joined together. Value to use to map a message to a channel. |
| `name` | String | The channel name | | |
| `description` | String | The channel description. |
| `can_post` | Boolean | Whether the account can send messages to the channel. [`chats`](./account.md#chats) only lists channels where this is `True`. |
| `can_view` | Boolean | Whether the account can read the channel. |
| `can_post_reaction` | Boolean | Whether the account can post emoji reactions. |
| `token_gated` | Boolean | Whether access to the channel is gated behind a token. |
mkdocs.yml
+40
View File
@@ -0,0 +1,40 @@
site_name: Status Bot Documentation
theme:
name: material
palette:
- scheme: slate
primary: custom
accent: custom
font:
text: Inter
code: JetBrains Mono
features:
- navigation.sections
- navigation.instant
- navigation.tracking
- content.code.copy
- content.code.annotate
extra_css:
- stylesheets/extra.css
nav:
- index.md
- Usage:
- Messaging: usage/messaging.md
- Monitoring: usage/monitoring.md
- Deployment:
- Configuration: deployment/configuration.md
- Docker: deployment/docker.md
- Metrics: deployment/metrics.md
- Development:
- Database: development/database.md
- Modules: development/modules.md
markdown_extensions:
- pymdownx.superfences:
custom_fences:
- name: mermaid
class: mermaid
format: !!python/name:pymdownx.superfences.fence_code_format
pyproject.toml
+4
View File
@@ -21,6 +21,10 @@ dependencies = [
[project.optional-dependencies]
dev = ["pytest"]
docs = [
"mkdocs>=1.5.3",
"mkdocs-material>=9.5.0",
]
[project.scripts]
status-bot = "main:main"