# micode-ai/accounting-ai-agent architecture

> Architecture diagram of the GitHub repository micode-ai/accounting-ai-agent, 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/micode-ai/accounting-ai-agent
- Repository: https://github.com/micode-ai/accounting-ai-agent

## Overview

Accounting AI Agent is a web-based bookkeeping and financial-reporting product. Users enter through the Next.js application, authenticate against the REST API, and use AI chat or accounting features such as dashboards, HR records, and KSeF invoice operations. The backend separates HTTP handling from domain services and connects to PostgreSQL, Redis, wFirma, and AI services. The graph emphasizes documented capabilities and relationships visible in the supplied excerpts or SOURCE INDEX; unsampled subsystem internals are represented at their listed paths, without inferring unshown calls.

Main entry points: [`packages/api/src/services/ai-chat/ai-chat.service.ts`](https://github.com/micode-ai/accounting-ai-agent/blob/development/packages/api/src/services/ai-chat/ai-chat.service.ts) (AI chat service), [`packages/api/src/lib/prisma.ts`](https://github.com/micode-ai/accounting-ai-agent/blob/development/packages/api/src/lib/prisma.ts) (PostgreSQL), [`packages/api/src/services/auth.service.ts`](https://github.com/micode-ai/accounting-ai-agent/blob/development/packages/api/src/services/auth.service.ts) (Authentication), [`packages/api/src/middleware/auth.middleware.ts`](https://github.com/micode-ai/accounting-ai-agent/blob/development/packages/api/src/middleware/auth.middleware.ts) (Auth middleware)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web application"]
  node_webapp["Next.js application"]
  node_chatui["Chat interface<br/>[ChatContainer.tsx]"]
  node_ksefui["KSeF interface"]
end

subgraph group_api["API and identity"]
  node_api["REST API<br/>[index.ts]"]
  node_auth["Authentication<br/>[auth.service.ts]"]
  node_authmw["Auth middleware<br/>[auth.middleware.ts]"]
  node_chatcontroller["Chat endpoints"]
end

subgraph group_accounting["Accounting domains"]
  node_ksef["KSeF operations<br/>[ksef.service.ts]"]
  node_hr["HR management<br/>[hr.service.ts]"]
  node_dashboard["Business dashboard"]
  node_wfirma["wFirma accounting<br/>[invoice.service.ts]"]
end

subgraph group_ai["AI and messaging"]
  node_chatservice["AI chat service<br/>[ai-chat.service.ts]"]
  node_agent["Agent runner"]
  node_memory["AI memory"]
  node_telegram["Telegram bot"]
end

subgraph group_platform["Data and integrations"]
  node_db[("PostgreSQL<br/>[prisma.ts]")]
  node_redis[("Redis<br/>[redis.ts]")]
end

node_user(("End user"))
node_external{{"External AI provider"}}
node_ksefservice{{"National KSeF service"}}
node_wfirmaservice{{"wFirma service"}}

node_user -->|"uses"| node_webapp
node_webapp -->|"calls REST API"| node_api
node_chatui -.->|"sends chat requests"| node_chatcontroller
node_ksefui -.->|"uses KSeF API"| node_api
node_api -.->|"protects routes"| node_authmw
node_authmw -->|"verifies tokens"| node_auth
node_authmw -->|"loads user"| node_db
node_auth -->|"persists accounts"| node_db
node_auth -->|"checks tokens"| node_redis
node_chatcontroller -->|"handles messages"| node_chatservice
node_chatservice -->|"runs agent"| node_agent
node_chatservice -->|"extracts memory"| node_memory
node_chatservice -.->|"uses AI models"| node_external
node_telegram -->|"routes chat"| node_chatservice
node_ksef -.->|"exchanges invoices"| node_ksefservice
node_hr -.->|"stores HR records"| node_db
node_dashboard -.->|"reads business data"| node_db
node_wfirma -.->|"manages invoices"| node_wfirmaservice
node_ksefui -.->|"manages contractors"| node_ksef

click node_webapp "https://github.com/micode-ai/accounting-ai-agent/tree/development/packages/web/src/app"
click node_chatui "https://github.com/micode-ai/accounting-ai-agent/blob/development/packages/web/src/components/chat/ChatContainer.tsx"
click node_ksefui "https://github.com/micode-ai/accounting-ai-agent/blob/development/packages/web/src/components/ksef/KSeFContractorManager.tsx"
click node_api "https://github.com/micode-ai/accounting-ai-agent/blob/development/packages/api/src/index.ts"
click node_auth "https://github.com/micode-ai/accounting-ai-agent/blob/development/packages/api/src/services/auth.service.ts"
click node_authmw "https://github.com/micode-ai/accounting-ai-agent/blob/development/packages/api/src/middleware/auth.middleware.ts"
click node_chatcontroller "https://github.com/micode-ai/accounting-ai-agent/blob/development/packages/api/src/controllers/ai-chat.controller.ts"
click node_chatservice "https://github.com/micode-ai/accounting-ai-agent/blob/development/packages/api/src/services/ai-chat/ai-chat.service.ts"
click node_agent "https://github.com/micode-ai/accounting-ai-agent/blob/development/packages/api/src/services/ai-chat/langgraph-agent-runner.ts"
click node_memory "https://github.com/micode-ai/accounting-ai-agent/blob/development/packages/api/src/services/ai-memory/ai-memory.service.ts"
click node_telegram "https://github.com/micode-ai/accounting-ai-agent/blob/development/packages/api/src/services/telegram-bot/telegram-bot.service.ts"
click node_ksef "https://github.com/micode-ai/accounting-ai-agent/blob/development/packages/api/src/services/ksef/ksef.service.ts"
click node_hr "https://github.com/micode-ai/accounting-ai-agent/blob/development/packages/api/src/services/hr/hr.service.ts"
click node_dashboard "https://github.com/micode-ai/accounting-ai-agent/blob/development/packages/api/src/services/dashboard/dashboard.service.ts"
click node_wfirma "https://github.com/micode-ai/accounting-ai-agent/blob/development/packages/api/src/services/wfirma/invoice.service.ts"
click node_db "https://github.com/micode-ai/accounting-ai-agent/blob/development/packages/api/src/lib/prisma.ts"
click node_redis "https://github.com/micode-ai/accounting-ai-agent/blob/development/packages/api/src/lib/redis.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_chatui,node_ksefui,node_user toneBlue
class node_api,node_auth,node_authmw,node_chatcontroller toneAmber
class node_ksef,node_hr,node_dashboard,node_wfirma toneMint
class node_chatservice,node_agent,node_memory,node_telegram toneRose
class node_db,node_redis,node_external,node_ksefservice,node_wfirmaservice toneIndigo
```

## Components

### Web application

- [Next.js application](https://github.com/micode-ai/accounting-ai-agent/tree/development/packages/web/src/app): `packages/web/src/app`
- [Chat interface](https://github.com/micode-ai/accounting-ai-agent/blob/development/packages/web/src/components/chat/ChatContainer.tsx): `packages/web/src/components/chat/ChatContainer.tsx`
- [KSeF interface](https://github.com/micode-ai/accounting-ai-agent/blob/development/packages/web/src/components/ksef/KSeFContractorManager.tsx): `packages/web/src/components/ksef/KSeFContractorManager.tsx`

### API and identity

- [REST API](https://github.com/micode-ai/accounting-ai-agent/blob/development/packages/api/src/index.ts): `packages/api/src/index.ts`
- [Authentication](https://github.com/micode-ai/accounting-ai-agent/blob/development/packages/api/src/services/auth.service.ts): `packages/api/src/services/auth.service.ts`
- [Auth middleware](https://github.com/micode-ai/accounting-ai-agent/blob/development/packages/api/src/middleware/auth.middleware.ts): `packages/api/src/middleware/auth.middleware.ts`
- [Chat endpoints](https://github.com/micode-ai/accounting-ai-agent/blob/development/packages/api/src/controllers/ai-chat.controller.ts): `packages/api/src/controllers/ai-chat.controller.ts`

### Accounting domains

- [KSeF operations](https://github.com/micode-ai/accounting-ai-agent/blob/development/packages/api/src/services/ksef/ksef.service.ts): `packages/api/src/services/ksef/ksef.service.ts`
- [HR management](https://github.com/micode-ai/accounting-ai-agent/blob/development/packages/api/src/services/hr/hr.service.ts): `packages/api/src/services/hr/hr.service.ts`
- [Business dashboard](https://github.com/micode-ai/accounting-ai-agent/blob/development/packages/api/src/services/dashboard/dashboard.service.ts): `packages/api/src/services/dashboard/dashboard.service.ts`
- [wFirma accounting](https://github.com/micode-ai/accounting-ai-agent/blob/development/packages/api/src/services/wfirma/invoice.service.ts): `packages/api/src/services/wfirma/invoice.service.ts`

### AI and messaging

- [AI chat service](https://github.com/micode-ai/accounting-ai-agent/blob/development/packages/api/src/services/ai-chat/ai-chat.service.ts): `packages/api/src/services/ai-chat/ai-chat.service.ts`
- [Agent runner](https://github.com/micode-ai/accounting-ai-agent/blob/development/packages/api/src/services/ai-chat/langgraph-agent-runner.ts): `packages/api/src/services/ai-chat/langgraph-agent-runner.ts`
- [AI memory](https://github.com/micode-ai/accounting-ai-agent/blob/development/packages/api/src/services/ai-memory/ai-memory.service.ts): `packages/api/src/services/ai-memory/ai-memory.service.ts`
- [Telegram bot](https://github.com/micode-ai/accounting-ai-agent/blob/development/packages/api/src/services/telegram-bot/telegram-bot.service.ts): `packages/api/src/services/telegram-bot/telegram-bot.service.ts`

### Data and integrations

- [PostgreSQL](https://github.com/micode-ai/accounting-ai-agent/blob/development/packages/api/src/lib/prisma.ts): `packages/api/src/lib/prisma.ts`
- [Redis](https://github.com/micode-ai/accounting-ai-agent/blob/development/packages/api/src/lib/redis.ts): `packages/api/src/lib/redis.ts`

### Other components

- **End user**
- **External AI provider**
- **National KSeF service**
- **wFirma service**

## Connections

- End user → Next.js application: uses (evidence: `README.md`)
- Next.js application → REST API: calls REST API (evidence: `README.md`)
- Chat interface → Chat endpoints: sends chat requests
- KSeF interface → REST API: uses KSeF API
- REST API → Auth middleware: protects routes
- Auth middleware → Authentication: verifies tokens (evidence: `packages/api/src/middleware/auth.middleware.ts`)
- Auth middleware → PostgreSQL: loads user (evidence: `packages/api/src/middleware/auth.middleware.ts`)
- Authentication → PostgreSQL: persists accounts (evidence: `packages/api/src/services/auth.service.ts`)
- Authentication → Redis: checks tokens (evidence: `packages/api/src/services/auth.service.ts`)
- Chat endpoints → AI chat service: handles messages (evidence: `packages/api/src/controllers/ai-chat.controller.ts`)
- AI chat service → Agent runner: runs agent (evidence: `packages/api/src/services/ai-chat/ai-chat.service.ts`)
- AI chat service → AI memory: extracts memory (evidence: `packages/api/src/services/ai-chat/ai-chat.service.ts`)
- AI chat service → External AI provider: uses AI models (evidence: `README.md`)
- Telegram bot → AI chat service: routes chat (evidence: `packages/api/src/services/telegram-bot/telegram-bot.service.ts`)
- KSeF operations → National KSeF service: exchanges invoices
- HR management → PostgreSQL: stores HR records
- Business dashboard → PostgreSQL: reads business data
- wFirma accounting → wFirma service: manages invoices
- KSeF interface → KSeF operations: manages contractors
