# kekborkek/max_buisnes_bot architecture

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

- Interactive diagram: https://gitdiagram.com/kekborkek/max_buisnes_bot
- Repository: https://github.com/kekborkek/max_buisnes_bot

## Overview

This MAX bot and mini-app help individual entrepreneurs understand and track tax, contribution, and reporting deadlines, alongside personal tasks. The main journey is profile questions → a tailored calendar → reminders and guidance → completion tracking; the mini-app provides list, month, detail, settings, task, sharing, and iCalendar views. The README documents the broad workflow and runtime layout; source excerpts and the index support selected internal links. Some endpoint and handler details are unsampled, so those links are omitted or grounded in README statements.

Main entry points: [`backend/app/bot/handlers`](https://github.com/kekborkek/max_buisnes_bot/tree/main/backend/app/bot/handlers) (Bot handlers), [`backend/app/calendar/build.py`](https://github.com/kekborkek/max_buisnes_bot/blob/main/backend/app/calendar/build.py) (Calendar assembly), [`miniapp/src/screens`](https://github.com/kekborkek/max_buisnes_bot/tree/main/miniapp/src/screens) (Mini-app screens), [`backend/app/api/routes.py`](https://github.com/kekborkek/max_buisnes_bot/blob/main/backend/app/api/routes.py) (HTTP API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_bot["MAX bot"]
  node_bot_entry["Bot routing<br/>[router.py]"]
  node_bot_handlers["Bot handlers"]
  node_bot_context["Dialog context<br/>[context.py]"]
  node_task_parse["Task parsing<br/>[dateparse.py]"]
end

subgraph group_calendar["Calendar services"]
  node_calendar_build["Calendar assembly<br/>[build.py]"]
  node_catalog["Deadline catalog<br/>[loader.py]"]
  node_dates["Date rules<br/>[dates.py]"]
  node_reminders["Reminder scheduling<br/>[reminders.py]"]
  node_weekly_digest["Weekly digest<br/>[digest.py]"]
end

subgraph group_backend["API and state"]
  node_http_api["HTTP API<br/>[routes.py]"]
  node_api_service["Calendar API service<br/>[service.py]"]
  node_ics["iCalendar feeds<br/>[ics.py]"]
  node_tasks_api["Task endpoints<br/>[tasks.py]"]
  node_database[("Application database<br/>[db.py]")]
  node_max_client["MAX client<br/>[max_client.py]"]
end

subgraph group_miniapp["Mini-app"]
  node_miniapp_ui["Mini-app screens"]
  node_miniapp_source["Data source<br/>[source.ts]"]
  node_miniapp_http["API client<br/>[http.ts]"]
  node_bridge["MAX bridge<br/>[bridge.ts]"]
  node_miniapp_router["Screen navigation<br/>[router.tsx]"]
end

node_user(("Entrepreneur"))
node_max_api["MAX Bot API"]

node_user -->|"sends messages"| node_max_api
node_max_api -->|"webhook updates"| node_bot_entry
node_bot_entry -->|"dispatches to"| node_bot_handlers
node_bot_handlers -->|"uses dialog"| node_bot_context
node_bot_handlers -.->|"parses task text"| node_task_parse
node_bot_handlers -->|"requests calendar"| node_calendar_build
node_calendar_build -->|"loads obligations"| node_catalog
node_calendar_build -.->|"applies date rules"| node_dates
node_calendar_build -->|"stores calendar"| node_database
node_reminders -->|"reads and records"| node_database
node_reminders -->|"sends reminders"| node_max_client
node_weekly_digest -->|"sends digest"| node_max_client
node_http_api -->|"uses calendar service"| node_api_service
node_http_api -->|"routes task requests"| node_tasks_api
node_http_api -->|"routes feed requests"| node_ics
node_api_service -->|"reads event state"| node_database
node_tasks_api -->|"reads and writes tasks"| node_database
node_user -->|"opens mini-app"| node_miniapp_ui
node_miniapp_ui -->|"navigates screens"| node_miniapp_router
node_miniapp_ui -->|"requests data"| node_miniapp_source
node_miniapp_source -->|"selects API source"| node_miniapp_http
node_miniapp_http -->|"calls API"| node_http_api
node_miniapp_http -->|"gets MAX launch data"| node_bridge
node_miniapp_ui -.->|"requests calendar feed"| node_ics

click node_bot_entry "https://github.com/kekborkek/max_buisnes_bot/blob/main/backend/app/bot/router.py"
click node_bot_handlers "https://github.com/kekborkek/max_buisnes_bot/tree/main/backend/app/bot/handlers"
click node_bot_context "https://github.com/kekborkek/max_buisnes_bot/blob/main/backend/app/bot/context.py"
click node_task_parse "https://github.com/kekborkek/max_buisnes_bot/blob/main/backend/app/bot/dateparse.py"
click node_calendar_build "https://github.com/kekborkek/max_buisnes_bot/blob/main/backend/app/calendar/build.py"
click node_catalog "https://github.com/kekborkek/max_buisnes_bot/blob/main/backend/app/calendar/loader.py"
click node_dates "https://github.com/kekborkek/max_buisnes_bot/blob/main/backend/app/calendar/dates.py"
click node_reminders "https://github.com/kekborkek/max_buisnes_bot/blob/main/backend/app/calendar/reminders.py"
click node_weekly_digest "https://github.com/kekborkek/max_buisnes_bot/blob/main/backend/app/calendar/digest.py"
click node_http_api "https://github.com/kekborkek/max_buisnes_bot/blob/main/backend/app/api/routes.py"
click node_api_service "https://github.com/kekborkek/max_buisnes_bot/blob/main/backend/app/api/service.py"
click node_ics "https://github.com/kekborkek/max_buisnes_bot/blob/main/backend/app/api/ics.py"
click node_tasks_api "https://github.com/kekborkek/max_buisnes_bot/blob/main/backend/app/api/tasks.py"
click node_database "https://github.com/kekborkek/max_buisnes_bot/blob/main/backend/app/core/db.py"
click node_max_client "https://github.com/kekborkek/max_buisnes_bot/blob/main/backend/app/core/max_client.py"
click node_miniapp_ui "https://github.com/kekborkek/max_buisnes_bot/tree/main/miniapp/src/screens"
click node_miniapp_source "https://github.com/kekborkek/max_buisnes_bot/blob/main/miniapp/src/data/source.ts"
click node_miniapp_http "https://github.com/kekborkek/max_buisnes_bot/blob/main/miniapp/src/data/http.ts"
click node_bridge "https://github.com/kekborkek/max_buisnes_bot/blob/main/miniapp/src/bridge.ts"
click node_miniapp_router "https://github.com/kekborkek/max_buisnes_bot/blob/main/miniapp/src/router.tsx"

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_bot_entry,node_bot_handlers,node_bot_context,node_task_parse toneBlue
class node_calendar_build,node_catalog,node_dates,node_reminders,node_weekly_digest toneAmber
class node_http_api,node_api_service,node_ics,node_tasks_api,node_database,node_max_client,node_max_api toneMint
class node_miniapp_ui,node_miniapp_source,node_miniapp_http,node_bridge,node_miniapp_router toneRose
class node_user toneIndigo
```

## Components

### MAX bot

- [Bot routing](https://github.com/kekborkek/max_buisnes_bot/blob/main/backend/app/bot/router.py): `backend/app/bot/router.py`
- [Bot handlers](https://github.com/kekborkek/max_buisnes_bot/tree/main/backend/app/bot/handlers): `backend/app/bot/handlers`
- [Dialog context](https://github.com/kekborkek/max_buisnes_bot/blob/main/backend/app/bot/context.py): `backend/app/bot/context.py`
- [Task parsing](https://github.com/kekborkek/max_buisnes_bot/blob/main/backend/app/bot/dateparse.py): `backend/app/bot/dateparse.py`

### Calendar services

- [Calendar assembly](https://github.com/kekborkek/max_buisnes_bot/blob/main/backend/app/calendar/build.py): `backend/app/calendar/build.py`
- [Deadline catalog](https://github.com/kekborkek/max_buisnes_bot/blob/main/backend/app/calendar/loader.py): `backend/app/calendar/loader.py`
- [Date rules](https://github.com/kekborkek/max_buisnes_bot/blob/main/backend/app/calendar/dates.py): `backend/app/calendar/dates.py`
- [Reminder scheduling](https://github.com/kekborkek/max_buisnes_bot/blob/main/backend/app/calendar/reminders.py): `backend/app/calendar/reminders.py`
- [Weekly digest](https://github.com/kekborkek/max_buisnes_bot/blob/main/backend/app/calendar/digest.py): `backend/app/calendar/digest.py`

### API and state

- [HTTP API](https://github.com/kekborkek/max_buisnes_bot/blob/main/backend/app/api/routes.py): `backend/app/api/routes.py`
- [Calendar API service](https://github.com/kekborkek/max_buisnes_bot/blob/main/backend/app/api/service.py): `backend/app/api/service.py`
- [iCalendar feeds](https://github.com/kekborkek/max_buisnes_bot/blob/main/backend/app/api/ics.py): `backend/app/api/ics.py`
- [Task endpoints](https://github.com/kekborkek/max_buisnes_bot/blob/main/backend/app/api/tasks.py): `backend/app/api/tasks.py`
- [Application database](https://github.com/kekborkek/max_buisnes_bot/blob/main/backend/app/core/db.py): `backend/app/core/db.py`
- [MAX client](https://github.com/kekborkek/max_buisnes_bot/blob/main/backend/app/core/max_client.py): `backend/app/core/max_client.py`

### Mini-app

- [Mini-app screens](https://github.com/kekborkek/max_buisnes_bot/tree/main/miniapp/src/screens): `miniapp/src/screens`
- [Data source](https://github.com/kekborkek/max_buisnes_bot/blob/main/miniapp/src/data/source.ts): `miniapp/src/data/source.ts`
- [API client](https://github.com/kekborkek/max_buisnes_bot/blob/main/miniapp/src/data/http.ts): `miniapp/src/data/http.ts`
- [MAX bridge](https://github.com/kekborkek/max_buisnes_bot/blob/main/miniapp/src/bridge.ts): `miniapp/src/bridge.ts`
- [Screen navigation](https://github.com/kekborkek/max_buisnes_bot/blob/main/miniapp/src/router.tsx): `miniapp/src/router.tsx`

### Other components

- **Entrepreneur**
- **MAX Bot API**

## Connections

- Entrepreneur → MAX Bot API: sends messages (evidence: `README.md`)
- MAX Bot API → Bot routing: webhook updates (evidence: `README.md`)
- Bot routing → Bot handlers: dispatches to (evidence: `backend/app/bot/router.py`)
- Bot handlers → Dialog context: uses dialog (evidence: `backend/app/bot/handlers/service.py`)
- Bot handlers → Task parsing: parses task text
- Bot handlers → Calendar assembly: requests calendar (evidence: `README.md`)
- Calendar assembly → Deadline catalog: loads obligations (evidence: `backend/app/calendar/loader.py`)
- Calendar assembly → Date rules: applies date rules
- Calendar assembly → Application database: stores calendar (evidence: `README.md`)
- Reminder scheduling → Application database: reads and records (evidence: `backend/app/calendar/reminders.py`)
- Reminder scheduling → MAX client: sends reminders (evidence: `backend/app/calendar/reminders.py`)
- Weekly digest → MAX client: sends digest (evidence: `backend/app/calendar/digest.py`)
- HTTP API → Calendar API service: uses calendar service (evidence: `backend/app/api/routes.py`)
- HTTP API → Task endpoints: routes task requests (evidence: `backend/app/api/routes.py`)
- HTTP API → iCalendar feeds: routes feed requests (evidence: `backend/app/api/routes.py`)
- Calendar API service → Application database: reads event state (evidence: `backend/app/api/service.py`)
- Task endpoints → Application database: reads and writes tasks (evidence: `backend/app/api/tasks.py`)
- Entrepreneur → Mini-app screens: opens mini-app (evidence: `README.md`)
- Mini-app screens → Screen navigation: navigates screens (evidence: `miniapp/src/App.tsx`)
- Mini-app screens → Data source: requests data (evidence: `miniapp/src/App.tsx`)
- Data source → API client: selects API source (evidence: `miniapp/src/data/source.ts`)
- API client → HTTP API: calls API (evidence: `miniapp/src/data/http.ts`)
- API client → MAX bridge: gets MAX launch data (evidence: `miniapp/src/data/http.ts`)
- Mini-app screens → iCalendar feeds: requests calendar feed
