# destinym01/accounting-bot architecture

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

- Interactive diagram: https://gitdiagram.com/destinym01/accounting-bot
- Repository: https://github.com/destinym01/accounting-bot

## Overview

AccBot is an active personal-finance web dashboard backed by a JWT-protected NestJS API; the README says the Telegram bot is retired. The main workflow is bank mail ingestion into categorized transactions and balance updates, followed by web review, correction, and reporting. Other distinct workflows cover budgets, cash envelopes, recurring bookings, categories, and merchant memory. The graph emphasizes documented features and sampled controller-to-service calls; several API feature internals are represented at their exact controller paths because their service code was not sampled.

Main entry points: [`web/src/app/core/services/api.service.ts`](https://github.com/destinym01/accounting-bot/blob/main/web/src/app/core/services/api.service.ts) (API client), [`api/src/ingestion/ingestion.service.ts`](https://github.com/destinym01/accounting-bot/blob/main/api/src/ingestion/ingestion.service.ts) (Ingestion runner), [`web/src/app/app.routes.ts`](https://github.com/destinym01/accounting-bot/blob/main/web/src/app/app.routes.ts) (Dashboard pages), [`api/src/ingestion/ingestion.controller.ts`](https://github.com/destinym01/accounting-bot/blob/main/api/src/ingestion/ingestion.controller.ts) (Ingestion controls)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web dashboard"]
  node_webapp["Dashboard pages<br/>[app.routes.ts]"]
  node_webapi["API client<br/>[api.service.ts]"]
end

subgraph group_api["REST API"]
  node_auth["JWT authentication<br/>[jwt.guard.ts]"]
  node_settings["Settings"]
end

subgraph group_ingest["Mail ingestion"]
  node_ingestctl["Ingestion controls"]
  node_ingestion["Ingestion runner"]
  node_mail["Bank mail client<br/>[mail.client.ts]"]
  node_categorizer["Transaction categorizer"]
  node_status["Ingestion status"]
end

subgraph group_finance["Finance features"]
  node_transactions["Transactions"]
  node_ledger["Balance ledger<br/>[ledger.service.ts]"]
  node_balance["Balance history"]
  node_budget["Budgets"]
  node_cash["Cash envelopes<br/>[cash.controller.ts]"]
  node_recurring["Recurring rules"]
  node_categories["Categories"]
  node_merchants["Merchant memory"]
end

subgraph group_reporting["Insights and reports"]
  node_statistics["Statistics"]
  node_analytics["Analytics"]
  node_compare["Period comparison"]
  node_tips["Financial tips<br/>[tips.controller.ts]"]
  node_reports["Email reports"]
  node_calculator["Growth calculator"]
end

node_person(("Account owner"))
node_database[("MongoDB")]
node_gmail["Bank mailbox"]
node_mistral["Mistral AI"]
node_smtp["Gmail SMTP"]

node_person -->|"uses"| node_webapp
node_webapp -->|"guards routes"| node_auth
node_webapp -->|"requests data"| node_webapi
node_webapi -->|"calls API"| node_transactions
node_webapi -->|"calls API"| node_balance
node_webapi -->|"calls API"| node_budget
node_webapi -->|"calls API"| node_cash
node_webapi -->|"calls API"| node_recurring
node_webapi -->|"calls API"| node_categories
node_webapi -->|"calls API"| node_merchants
node_webapi -->|"calls API"| node_settings
node_webapi -->|"calls API"| node_statistics
node_webapi -->|"calls API"| node_analytics
node_webapi -->|"calls API"| node_compare
node_webapi -->|"calls API"| node_tips
node_webapi -->|"calls API"| node_reports
node_webapi -->|"calls API"| node_calculator
node_person -->|"requests mail check"| node_ingestctl
node_ingestctl -->|"runs check"| node_ingestion
node_ingestctl -->|"reads status"| node_status
node_ingestion -->|"fetches messages"| node_mail
node_gmail -->|"provides messages"| node_mail
node_ingestion -->|"categorizes unknowns"| node_categorizer
node_ingestion -->|"uses remembered categories"| node_merchants
node_ingestion -->|"applies booked entries"| node_ledger
node_ingestion -->|"records run"| node_status
node_transactions -->|"updates balance"| node_ledger
node_transactions -->|"reads and writes"| node_database
node_balance -->|"reads and writes"| node_database
node_budget -->|"reads and writes"| node_database
node_cash -->|"reads and writes"| node_database
node_recurring -->|"reads and writes"| node_database
node_categories -->|"reads and writes"| node_database
node_merchants -->|"reads and writes"| node_database
node_settings -->|"reads and writes"| node_database
node_statistics -->|"queries"| node_database
node_analytics -->|"queries"| node_database
node_compare -.->|"requests narrative"| node_mistral
node_tips -.->|"requests tips"| node_mistral
node_reports -->|"sends email"| node_smtp

click node_webapp "https://github.com/destinym01/accounting-bot/blob/main/web/src/app/app.routes.ts"
click node_webapi "https://github.com/destinym01/accounting-bot/blob/main/web/src/app/core/services/api.service.ts"
click node_auth "https://github.com/destinym01/accounting-bot/blob/main/api/src/auth/jwt.guard.ts"
click node_transactions "https://github.com/destinym01/accounting-bot/blob/main/api/src/transactions/transactions.controller.ts"
click node_ledger "https://github.com/destinym01/accounting-bot/blob/main/api/src/shared/ledger/ledger.service.ts"
click node_balance "https://github.com/destinym01/accounting-bot/blob/main/api/src/balance/balance.controller.ts"
click node_budget "https://github.com/destinym01/accounting-bot/blob/main/api/src/budget/budget.controller.ts"
click node_cash "https://github.com/destinym01/accounting-bot/blob/main/api/src/cash/cash.controller.ts"
click node_recurring "https://github.com/destinym01/accounting-bot/blob/main/api/src/recurring/recurring.controller.ts"
click node_categories "https://github.com/destinym01/accounting-bot/blob/main/api/src/categories/categories.controller.ts"
click node_merchants "https://github.com/destinym01/accounting-bot/blob/main/api/src/merchants/merchants.controller.ts"
click node_settings "https://github.com/destinym01/accounting-bot/blob/main/api/src/settings/settings.controller.ts"
click node_ingestctl "https://github.com/destinym01/accounting-bot/blob/main/api/src/ingestion/ingestion.controller.ts"
click node_ingestion "https://github.com/destinym01/accounting-bot/blob/main/api/src/ingestion/ingestion.service.ts"
click node_mail "https://github.com/destinym01/accounting-bot/blob/main/api/src/ingestion/mail.client.ts"
click node_categorizer "https://github.com/destinym01/accounting-bot/blob/main/api/src/ingestion/categorizer.service.ts"
click node_status "https://github.com/destinym01/accounting-bot/blob/main/api/src/ingestion/ingestion-status.service.ts"
click node_statistics "https://github.com/destinym01/accounting-bot/blob/main/api/src/statistics/statistics.controller.ts"
click node_analytics "https://github.com/destinym01/accounting-bot/blob/main/api/src/analytics/analytics.controller.ts"
click node_compare "https://github.com/destinym01/accounting-bot/blob/main/api/src/compare/compare.controller.ts"
click node_tips "https://github.com/destinym01/accounting-bot/blob/main/api/src/tips/tips.controller.ts"
click node_reports "https://github.com/destinym01/accounting-bot/blob/main/api/src/reports/reports.controller.ts"
click node_calculator "https://github.com/destinym01/accounting-bot/blob/main/api/src/calculator/calculator.controller.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_webapp,node_webapi toneBlue
class node_auth,node_settings,node_database toneAmber
class node_ingestctl,node_ingestion,node_mail,node_categorizer,node_status toneMint
class node_transactions,node_ledger,node_balance,node_budget,node_cash,node_recurring,node_categories,node_merchants toneRose
class node_statistics,node_analytics,node_compare,node_tips,node_reports,node_calculator,node_person,node_gmail,node_mistral,node_smtp toneIndigo
```

## Components

### Web dashboard

- [Dashboard pages](https://github.com/destinym01/accounting-bot/blob/main/web/src/app/app.routes.ts): `web/src/app/app.routes.ts`
- [API client](https://github.com/destinym01/accounting-bot/blob/main/web/src/app/core/services/api.service.ts): `web/src/app/core/services/api.service.ts`

### REST API

- [JWT authentication](https://github.com/destinym01/accounting-bot/blob/main/api/src/auth/jwt.guard.ts): `api/src/auth/jwt.guard.ts`
- [Settings](https://github.com/destinym01/accounting-bot/blob/main/api/src/settings/settings.controller.ts): `api/src/settings/settings.controller.ts`

### Mail ingestion

- [Ingestion controls](https://github.com/destinym01/accounting-bot/blob/main/api/src/ingestion/ingestion.controller.ts): `api/src/ingestion/ingestion.controller.ts`
- [Ingestion runner](https://github.com/destinym01/accounting-bot/blob/main/api/src/ingestion/ingestion.service.ts): `api/src/ingestion/ingestion.service.ts`
- [Bank mail client](https://github.com/destinym01/accounting-bot/blob/main/api/src/ingestion/mail.client.ts): `api/src/ingestion/mail.client.ts`
- [Transaction categorizer](https://github.com/destinym01/accounting-bot/blob/main/api/src/ingestion/categorizer.service.ts): `api/src/ingestion/categorizer.service.ts`
- [Ingestion status](https://github.com/destinym01/accounting-bot/blob/main/api/src/ingestion/ingestion-status.service.ts): `api/src/ingestion/ingestion-status.service.ts`

### Finance features

- [Transactions](https://github.com/destinym01/accounting-bot/blob/main/api/src/transactions/transactions.controller.ts): `api/src/transactions/transactions.controller.ts`
- [Balance ledger](https://github.com/destinym01/accounting-bot/blob/main/api/src/shared/ledger/ledger.service.ts): `api/src/shared/ledger/ledger.service.ts`
- [Balance history](https://github.com/destinym01/accounting-bot/blob/main/api/src/balance/balance.controller.ts): `api/src/balance/balance.controller.ts`
- [Budgets](https://github.com/destinym01/accounting-bot/blob/main/api/src/budget/budget.controller.ts): `api/src/budget/budget.controller.ts`
- [Cash envelopes](https://github.com/destinym01/accounting-bot/blob/main/api/src/cash/cash.controller.ts): `api/src/cash/cash.controller.ts`
- [Recurring rules](https://github.com/destinym01/accounting-bot/blob/main/api/src/recurring/recurring.controller.ts): `api/src/recurring/recurring.controller.ts`
- [Categories](https://github.com/destinym01/accounting-bot/blob/main/api/src/categories/categories.controller.ts): `api/src/categories/categories.controller.ts`
- [Merchant memory](https://github.com/destinym01/accounting-bot/blob/main/api/src/merchants/merchants.controller.ts): `api/src/merchants/merchants.controller.ts`

### Insights and reports

- [Statistics](https://github.com/destinym01/accounting-bot/blob/main/api/src/statistics/statistics.controller.ts): `api/src/statistics/statistics.controller.ts`
- [Analytics](https://github.com/destinym01/accounting-bot/blob/main/api/src/analytics/analytics.controller.ts): `api/src/analytics/analytics.controller.ts`
- [Period comparison](https://github.com/destinym01/accounting-bot/blob/main/api/src/compare/compare.controller.ts): `api/src/compare/compare.controller.ts`
- [Financial tips](https://github.com/destinym01/accounting-bot/blob/main/api/src/tips/tips.controller.ts): `api/src/tips/tips.controller.ts`
- [Email reports](https://github.com/destinym01/accounting-bot/blob/main/api/src/reports/reports.controller.ts): `api/src/reports/reports.controller.ts`
- [Growth calculator](https://github.com/destinym01/accounting-bot/blob/main/api/src/calculator/calculator.controller.ts): `api/src/calculator/calculator.controller.ts`

### Other components

- **Account owner**
- **MongoDB**
- **Bank mailbox**
- **Mistral AI**
- **Gmail SMTP**

## Connections

- Account owner → Dashboard pages: uses
- Dashboard pages → JWT authentication: guards routes
- Dashboard pages → API client: requests data
- API client → Transactions: calls API
- API client → Balance history: calls API
- API client → Budgets: calls API
- API client → Cash envelopes: calls API
- API client → Recurring rules: calls API
- API client → Categories: calls API
- API client → Merchant memory: calls API
- API client → Settings: calls API
- API client → Statistics: calls API
- API client → Analytics: calls API
- API client → Period comparison: calls API
- API client → Financial tips: calls API
- API client → Email reports: calls API
- API client → Growth calculator: calls API
- Account owner → Ingestion controls: requests mail check
- Ingestion controls → Ingestion runner: runs check
- Ingestion controls → Ingestion status: reads status
- Ingestion runner → Bank mail client: fetches messages
- Bank mailbox → Bank mail client: provides messages
- Ingestion runner → Transaction categorizer: categorizes unknowns
- Ingestion runner → Merchant memory: uses remembered categories
- Ingestion runner → Balance ledger: applies booked entries
- Ingestion runner → Ingestion status: records run
- Transactions → Balance ledger: updates balance
- Transactions → MongoDB: reads and writes
- Balance history → MongoDB: reads and writes
- Budgets → MongoDB: reads and writes
- Cash envelopes → MongoDB: reads and writes
- Recurring rules → MongoDB: reads and writes
- Categories → MongoDB: reads and writes
- Merchant memory → MongoDB: reads and writes
- Settings → MongoDB: reads and writes
- Statistics → MongoDB: queries
- Analytics → MongoDB: queries
- Period comparison → Mistral AI: requests narrative
- Financial tips → Mistral AI: requests tips
- Email reports → Gmail SMTP: sends email