# lilwndrr/personal-ai-accountant architecture

> Architecture diagram of the GitHub repository lilwndrr/personal-ai-accountant, 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/lilwndrr/personal-ai-accountant
- Repository: https://github.com/lilwndrr/personal-ai-accountant

## Overview

This appears to be a Telegram-based personal-finance application: users submit transaction documents, review parsed transactions, categorize them, and request reports. The tree identifies parsing, deduplication, categorization, bot state handling, and persistence components, but no README or runtime source excerpts establish how they connect. Dashed, uncited edges below represent the workflow implied by component names; the exact runtime wiring remains unverified.

Main entry points: [`src/main/java/com/example/springaitest/bot/service/UploadWorkFlowService.java`](https://github.com/lilwndrr/personal-ai-accountant/blob/main/src/main/java/com/example/springaitest/bot/service/UploadWorkFlowService.java) (Upload workflow), [`src/main/java/com/example/springaitest/api/config/service/CategorizationService.java`](https://github.com/lilwndrr/personal-ai-accountant/blob/main/src/main/java/com/example/springaitest/api/config/service/CategorizationService.java) (Categorization), [`src/main/java/com/example/springaitest/bot/events/EventsListener.java`](https://github.com/lilwndrr/personal-ai-accountant/blob/main/src/main/java/com/example/springaitest/bot/events/EventsListener.java) (Message events), [`src/main/java/com/example/springaitest/api/config/Repository/TransactionRepository.java`](https://github.com/lilwndrr/personal-ai-accountant/blob/main/src/main/java/com/example/springaitest/api/config/Repository/TransactionRepository.java) (Transactions)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_bot["Telegram bot"]
  node_bot_runtime["Bot runtime<br/>[MainBot.java]"]
  node_event_listener["Message events"]
  node_state_handlers["Conversation states"]
  node_upload_workflow["Upload workflow"]
  node_file_service["Telegram files"]
  node_review_callbacks["Review callbacks"]
  node_sessions["User sessions"]
  node_reports["Reports<br/>[ReportService.java]"]
  node_commands["Bot commands"]
end

subgraph group_ingestion["Transaction processing"]
  node_document_parser["Document parser"]
  node_deduplication["Transaction deduplication"]
  node_categorization["Categorization"]
end

subgraph group_storage["Finance data"]
  node_transactions[("Transactions")]
  node_categories[("Categories")]
  node_merchant_mappings[("Merchant mappings")]
end

subgraph group_support["Application support"]
  node_seeder["Data seeder<br/>[DataSeeder.java]"]
  node_application["Spring application"]
end

node_user(("Telegram user"))
node_telegram["Telegram"]
node_ollama["Ollama model"]

node_user -.->|"sends documents"| node_telegram
node_telegram -.->|"delivers messages"| node_event_listener
node_event_listener -.->|"dispatches input"| node_state_handlers
node_state_handlers -.->|"starts upload"| node_upload_workflow
node_upload_workflow -.->|"fetches files"| node_file_service
node_upload_workflow -.->|"parses documents"| node_document_parser
node_upload_workflow -.->|"checks duplicates"| node_deduplication
node_upload_workflow -.->|"categorizes transactions"| node_categorization
node_categorization -.->|"requests categorization"| node_ollama
node_categorization -.->|"uses categories"| node_categories
node_categorization -.->|"uses mappings"| node_merchant_mappings
node_upload_workflow -.->|"stores transactions"| node_transactions
node_review_callbacks -.->|"updates transactions"| node_transactions
node_event_listener -.->|"tracks sessions"| node_sessions
node_commands -.->|"requests reports"| node_reports
node_reports -.->|"reads transactions"| node_transactions
node_seeder -.->|"seeds data"| node_categories
node_application -.->|"initializes"| node_bot_runtime

click node_bot_runtime "https://github.com/lilwndrr/personal-ai-accountant/blob/main/src/main/java/com/example/springaitest/bot/MainBot.java"
click node_event_listener "https://github.com/lilwndrr/personal-ai-accountant/blob/main/src/main/java/com/example/springaitest/bot/events/EventsListener.java"
click node_state_handlers "https://github.com/lilwndrr/personal-ai-accountant/tree/main/src/main/java/com/example/springaitest/bot/state"
click node_upload_workflow "https://github.com/lilwndrr/personal-ai-accountant/blob/main/src/main/java/com/example/springaitest/bot/service/UploadWorkFlowService.java"
click node_file_service "https://github.com/lilwndrr/personal-ai-accountant/blob/main/src/main/java/com/example/springaitest/bot/service/TelegramFileService.java"
click node_review_callbacks "https://github.com/lilwndrr/personal-ai-accountant/blob/main/src/main/java/com/example/springaitest/bot/service/CallbackHandlerService.java"
click node_sessions "https://github.com/lilwndrr/personal-ai-accountant/blob/main/src/main/java/com/example/springaitest/bot/model/UserSessionService.java"
click node_document_parser "https://github.com/lilwndrr/personal-ai-accountant/blob/main/src/main/java/com/example/springaitest/api/config/service/DocumentParserService.java"
click node_deduplication "https://github.com/lilwndrr/personal-ai-accountant/blob/main/src/main/java/com/example/springaitest/api/config/service/TransactionDeduplicationService.java"
click node_categorization "https://github.com/lilwndrr/personal-ai-accountant/blob/main/src/main/java/com/example/springaitest/api/config/service/CategorizationService.java"
click node_transactions "https://github.com/lilwndrr/personal-ai-accountant/blob/main/src/main/java/com/example/springaitest/api/config/Repository/TransactionRepository.java"
click node_categories "https://github.com/lilwndrr/personal-ai-accountant/blob/main/src/main/java/com/example/springaitest/api/config/Repository/CategoryRepository.java"
click node_merchant_mappings "https://github.com/lilwndrr/personal-ai-accountant/blob/main/src/main/java/com/example/springaitest/api/config/Repository/MerchantMappingRepository.java"
click node_reports "https://github.com/lilwndrr/personal-ai-accountant/blob/main/src/main/java/com/example/springaitest/bot/service/ReportService.java"
click node_commands "https://github.com/lilwndrr/personal-ai-accountant/tree/main/src/main/java/com/example/springaitest/bot/commands"
click node_seeder "https://github.com/lilwndrr/personal-ai-accountant/blob/main/src/main/java/com/example/springaitest/api/config/DataSeeder.java"
click node_application "https://github.com/lilwndrr/personal-ai-accountant/blob/main/src/main/java/com/example/springaitest/SpringAiTestApplication.java"

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_runtime,node_event_listener,node_state_handlers,node_upload_workflow,node_file_service,node_review_callbacks,node_sessions,node_reports,node_commands,node_user toneBlue
class node_document_parser,node_deduplication,node_categorization toneAmber
class node_transactions,node_categories,node_merchant_mappings toneMint
class node_seeder,node_application toneRose
class node_telegram,node_ollama toneIndigo
```

## Components

### Telegram bot

- [Bot runtime](https://github.com/lilwndrr/personal-ai-accountant/blob/main/src/main/java/com/example/springaitest/bot/MainBot.java): `src/main/java/com/example/springaitest/bot/MainBot.java`
- [Message events](https://github.com/lilwndrr/personal-ai-accountant/blob/main/src/main/java/com/example/springaitest/bot/events/EventsListener.java): `src/main/java/com/example/springaitest/bot/events/EventsListener.java`
- [Conversation states](https://github.com/lilwndrr/personal-ai-accountant/tree/main/src/main/java/com/example/springaitest/bot/state): `src/main/java/com/example/springaitest/bot/state`
- [Upload workflow](https://github.com/lilwndrr/personal-ai-accountant/blob/main/src/main/java/com/example/springaitest/bot/service/UploadWorkFlowService.java): `src/main/java/com/example/springaitest/bot/service/UploadWorkFlowService.java`
- [Telegram files](https://github.com/lilwndrr/personal-ai-accountant/blob/main/src/main/java/com/example/springaitest/bot/service/TelegramFileService.java): `src/main/java/com/example/springaitest/bot/service/TelegramFileService.java`
- [Review callbacks](https://github.com/lilwndrr/personal-ai-accountant/blob/main/src/main/java/com/example/springaitest/bot/service/CallbackHandlerService.java): `src/main/java/com/example/springaitest/bot/service/CallbackHandlerService.java`
- [User sessions](https://github.com/lilwndrr/personal-ai-accountant/blob/main/src/main/java/com/example/springaitest/bot/model/UserSessionService.java): `src/main/java/com/example/springaitest/bot/model/UserSessionService.java`
- [Reports](https://github.com/lilwndrr/personal-ai-accountant/blob/main/src/main/java/com/example/springaitest/bot/service/ReportService.java): `src/main/java/com/example/springaitest/bot/service/ReportService.java`
- [Bot commands](https://github.com/lilwndrr/personal-ai-accountant/tree/main/src/main/java/com/example/springaitest/bot/commands): `src/main/java/com/example/springaitest/bot/commands`

### Transaction processing

- [Document parser](https://github.com/lilwndrr/personal-ai-accountant/blob/main/src/main/java/com/example/springaitest/api/config/service/DocumentParserService.java): `src/main/java/com/example/springaitest/api/config/service/DocumentParserService.java`
- [Transaction deduplication](https://github.com/lilwndrr/personal-ai-accountant/blob/main/src/main/java/com/example/springaitest/api/config/service/TransactionDeduplicationService.java): `src/main/java/com/example/springaitest/api/config/service/TransactionDeduplicationService.java`
- [Categorization](https://github.com/lilwndrr/personal-ai-accountant/blob/main/src/main/java/com/example/springaitest/api/config/service/CategorizationService.java): `src/main/java/com/example/springaitest/api/config/service/CategorizationService.java`

### Finance data

- [Transactions](https://github.com/lilwndrr/personal-ai-accountant/blob/main/src/main/java/com/example/springaitest/api/config/Repository/TransactionRepository.java): `src/main/java/com/example/springaitest/api/config/Repository/TransactionRepository.java`
- [Categories](https://github.com/lilwndrr/personal-ai-accountant/blob/main/src/main/java/com/example/springaitest/api/config/Repository/CategoryRepository.java): `src/main/java/com/example/springaitest/api/config/Repository/CategoryRepository.java`
- [Merchant mappings](https://github.com/lilwndrr/personal-ai-accountant/blob/main/src/main/java/com/example/springaitest/api/config/Repository/MerchantMappingRepository.java): `src/main/java/com/example/springaitest/api/config/Repository/MerchantMappingRepository.java`

### Application support

- [Data seeder](https://github.com/lilwndrr/personal-ai-accountant/blob/main/src/main/java/com/example/springaitest/api/config/DataSeeder.java): `src/main/java/com/example/springaitest/api/config/DataSeeder.java`
- [Spring application](https://github.com/lilwndrr/personal-ai-accountant/blob/main/src/main/java/com/example/springaitest/SpringAiTestApplication.java): `src/main/java/com/example/springaitest/SpringAiTestApplication.java`

### Other components

- **Telegram user**
- **Telegram**
- **Ollama model**

## Connections

- Telegram user → Telegram: sends documents
- Telegram → Message events: delivers messages
- Message events → Conversation states: dispatches input
- Conversation states → Upload workflow: starts upload
- Upload workflow → Telegram files: fetches files
- Upload workflow → Document parser: parses documents
- Upload workflow → Transaction deduplication: checks duplicates
- Upload workflow → Categorization: categorizes transactions
- Categorization → Ollama model: requests categorization
- Categorization → Categories: uses categories
- Categorization → Merchant mappings: uses mappings
- Upload workflow → Transactions: stores transactions
- Review callbacks → Transactions: updates transactions
- Message events → User sessions: tracks sessions
- Bot commands → Reports: requests reports
- Reports → Transactions: reads transactions
- Data seeder → Categories: seeds data
- Spring application → Bot runtime: initializes
