mikrotik-bot/AI_CONTEXT.md

AI_CONTEXT: MikroTik Telegram Bot

ARCH:CORE

• Lang: Python 3.10+
• Stack: aiogram3+librouteros+fastapi+aiosqlite
• Deploy: Docker/bare
• Auth: TG_user_id whitelist

FUNCS:MAIN

1. WiFi_Monitor: /clients, live_polling_30s, pagination
2. History: /history, sessions_DB, date_filters
3. Stats: /stats, rx/tx_aggregation, top_users
4. Events: FastAPI_webhook + polling_hybrid

FILES:KEY

• bot.py: main_logic, TG_handlers, API_polling
• db.py: aiosqlite_schema, CRUD_ops
• requirements.txt: deps_list
• docker-compose.yml: container_config
• docker-compose.portainer.yml: watchtower_autodeploy
• DEPLOY.md: portainer_setup_instructions

API:MT_PATHS

• WiFi_clients: /interface/wifi/registration-table (RouterOS7+)
• Fields: mac-address, interface, ssid, uptime, signal, band

DB:SCHEMA

clients(mac PK, name, custom_name, last_seen)
sessions(id, mac FK, ip, start/end_time, rx/tx_bytes, source)

ENVS:REQ

TG_BOT_TOKEN=bot_token
MT_API_HOST=router_ip
MT_API_USER=api_user  
MT_API_PASS=api_pass
ALLOWED_USER_IDS=123,456

DEPLOY:AUTODEPLOY

Method1:Watchtower (recommended)

• docker-compose.portainer.yml → portainer_stack
• watchtower checks updates every 5min
• auto rebuild+restart on code changes

Method2:GitHub_Registry

• .github/workflows/docker.yml → ghcr.io
• webhook triggers portainer update
• requires public repo or PAT

DEPLOY:QUICK

docker build -t mt-bot .
docker run --env-file .env mt-bot

CMDS:TG

• /start → main_menu
• /clients → wifi_list_paginated
• /history [days] → sessions_history
• /stats [days] → traffic_stats

ENDPOINTS:API

• GET /health → healthcheck
• GET /event?mac=XX&ip=XX&type=XX → webhook

POLL:LOGIC

• 30s_interval MT_API_check
• upsert_clients → track_sessions
• close_sessions_for_disconnected

WEBHOOK:FETCH

• GET /event?mac=XX&ip=XX&type=XX
• saves_to_DB + notifies_TG_users

NOTES:DEV

• RouterOS7 fields differ from v6
• no rx/tx in wifi_registration_table
• polling+webhook hybrid for reliability
• pagination: 10items/page, nav_buttons
• healthcheck: curl localhost:8000/health