# dannyahia/hermes architecture

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

- Interactive diagram: https://gitdiagram.com/dannyahia/hermes
- Repository: https://github.com/dannyahia/hermes

## Overview

Hermes is a personal-finance application for tracking money across accounts, transactions, budgets, categories, loans and recurring activity, with dashboards and financial reports. The main user path is authenticated web pages and actions into domain use cases, then repository-backed persistence; reports can also be exported, and spending can be captured through wallet and Telegram integrations. The source excerpts show several key wiring points, but not most page-to-use-case calls, so those links are marked unverified rather than assumed.

Main entry points: [`src/core/entities/transaction.ts`](https://github.com/dannyahia/hermes/blob/main/src/core/entities/transaction.ts) (Finance entities), [`src/app/layout.tsx`](https://github.com/dannyahia/hermes/blob/main/src/app/layout.tsx) (Finance pages), [`src/app/api/reports/export/route.ts`](https://github.com/dannyahia/hermes/blob/main/src/app/api/reports/export/route.ts) (Report export API), [`src/infra/repositories/drizzle-transaction.repository.ts`](https://github.com/dannyahia/hermes/blob/main/src/infra/repositories/drizzle-transaction.repository.ts) (Transaction repository)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Web experience"]
  node_auth_ui["Sign-in UI<br/>[login-form.tsx]"]
  node_app_ui["Finance pages<br/>[layout.tsx]"]
  node_transactions_ui["Transactions UI<br/>[page.tsx]"]
  node_accounts_ui["Accounts UI<br/>[page.tsx]"]
  node_dashboard_ui["Dashboard UI<br/>[page.tsx]"]
  node_reports_ui["Reports UI<br/>[page.tsx]"]
end

subgraph group_finance["Finance workflows"]
  node_transaction_flow["Transaction operations"]
  node_account_flow["Account operations"]
  node_budget_flow["Budget tracking"]
  node_category_flow["Categories"]
  node_dashboard_flow["Financial overview"]
  node_reports_flow["Reports"]
  node_loan_flow["Loans and plans"]
  node_recurring_flow["Recurring activity"]
  node_report_export["Report export API<br/>[route.ts]"]
end

subgraph group_domain["Domain model"]
  node_domain_entities["Finance entities<br/>[transaction.ts]"]
  node_repo_contracts["Repository contracts"]
end

subgraph group_platform["Platform and storage"]
  node_auth["Authentication<br/>[server.ts]"]
  node_transaction_repo["Transaction repository"]
  node_installment_repo["Installment repository"]
  node_database[("PostgreSQL<br/>[schema.ts]")]
  node_email["Email sender"]
end

subgraph group_capture["Capture integrations"]
  node_capture_flow["Payment capture"]
  node_capture_api["Wallet capture API<br/>[route.ts]"]
  node_chat_service["Chat orchestration<br/>[chat.ts]"]
  node_telegram["Telegram adapter"]
end

node_user(("User"))

node_user -.->|"signs in"| node_auth_ui
node_user -.->|"uses"| node_app_ui
node_auth_ui -.->|"authenticates"| node_auth
node_app_ui -.->|"renders"| node_transactions_ui
node_transactions_ui -.->|"manages transactions"| node_transaction_flow
node_app_ui -.->|"renders"| node_accounts_ui
node_accounts_ui -.->|"manages accounts"| node_account_flow
node_app_ui -.->|"renders"| node_dashboard_ui
node_dashboard_ui -.->|"loads overview"| node_dashboard_flow
node_app_ui -.->|"renders"| node_reports_ui
node_reports_ui -.->|"loads reports"| node_reports_flow
node_reports_ui -.->|"requests export"| node_report_export
node_report_export -->|"builds report"| node_reports_flow
node_report_export -->|"reads transactions"| node_transaction_repo
node_report_export -->|"exports PDF"| node_database
node_transaction_flow -.->|"persists transactions"| node_transaction_repo
node_transaction_repo -->|"queries tables"| node_database
node_installment_repo -->|"queries plans"| node_database
node_transaction_repo -->|"implements contract"| node_repo_contracts
node_installment_repo -->|"maps plans"| node_domain_entities
node_transaction_flow -.->|"creates transactions"| node_domain_entities
node_account_flow -.->|"uses finance entities"| node_domain_entities
node_budget_flow -.->|"uses finance entities"| node_domain_entities
node_category_flow -.->|"uses finance entities"| node_domain_entities
node_dashboard_flow -.->|"calculates metrics"| node_domain_entities
node_loan_flow -->|"uses repositories"| node_repo_contracts
node_loan_flow -->|"loads and saves plans"| node_installment_repo
node_recurring_flow -.->|"uses finance entities"| node_domain_entities
node_auth -->|"uses schema"| node_database
node_auth -->|"sends email"| node_email
node_capture_api -->|"records payment"| node_capture_flow
node_capture_api -->|"announces capture"| node_chat_service
node_chat_service -->|"dispatches messages"| node_telegram

click node_auth_ui "https://github.com/dannyahia/hermes/blob/main/src/app/(auth)/login/login-form.tsx"
click node_app_ui "https://github.com/dannyahia/hermes/blob/main/src/app/layout.tsx"
click node_transactions_ui "https://github.com/dannyahia/hermes/blob/main/src/app/transactions/page.tsx"
click node_accounts_ui "https://github.com/dannyahia/hermes/blob/main/src/app/accounts/page.tsx"
click node_dashboard_ui "https://github.com/dannyahia/hermes/blob/main/src/app/dashboard/page.tsx"
click node_reports_ui "https://github.com/dannyahia/hermes/blob/main/src/app/reports/page.tsx"
click node_auth "https://github.com/dannyahia/hermes/blob/main/src/infra/auth/server.ts"
click node_transaction_flow "https://github.com/dannyahia/hermes/tree/main/src/modules/transactions/application"
click node_account_flow "https://github.com/dannyahia/hermes/tree/main/src/modules/accounts/application"
click node_budget_flow "https://github.com/dannyahia/hermes/tree/main/src/modules/budgets/application"
click node_category_flow "https://github.com/dannyahia/hermes/tree/main/src/modules/categories/application"
click node_dashboard_flow "https://github.com/dannyahia/hermes/tree/main/src/modules/dashboard/application"
click node_reports_flow "https://github.com/dannyahia/hermes/tree/main/src/modules/reports/application"
click node_loan_flow "https://github.com/dannyahia/hermes/blob/main/src/modules/installments/application/create-installment-plan.use-case.ts"
click node_recurring_flow "https://github.com/dannyahia/hermes/tree/main/src/modules/recurring-transactions/application"
click node_domain_entities "https://github.com/dannyahia/hermes/blob/main/src/core/entities/transaction.ts"
click node_repo_contracts "https://github.com/dannyahia/hermes/blob/main/src/core/contracts/transaction-repository.ts"
click node_transaction_repo "https://github.com/dannyahia/hermes/blob/main/src/infra/repositories/drizzle-transaction.repository.ts"
click node_installment_repo "https://github.com/dannyahia/hermes/blob/main/src/infra/repositories/drizzle-installment-plan.repository.ts"
click node_database "https://github.com/dannyahia/hermes/blob/main/src/infra/database/schema.ts"
click node_report_export "https://github.com/dannyahia/hermes/blob/main/src/app/api/reports/export/route.ts"
click node_capture_flow "https://github.com/dannyahia/hermes/tree/main/src/modules/capture/application"
click node_capture_api "https://github.com/dannyahia/hermes/blob/main/src/app/api/capture/wallet/route.ts"
click node_chat_service "https://github.com/dannyahia/hermes/blob/main/src/shared/server/chat.ts"
click node_telegram "https://github.com/dannyahia/hermes/blob/main/src/infra/telegram/telegram-chat-channel.ts"
click node_email "https://github.com/dannyahia/hermes/blob/main/src/infra/email/resend-email-sender.adapter.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_auth_ui,node_app_ui,node_transactions_ui,node_accounts_ui,node_dashboard_ui,node_reports_ui,node_user toneBlue
class node_transaction_flow,node_account_flow,node_budget_flow,node_category_flow,node_dashboard_flow,node_reports_flow,node_loan_flow,node_recurring_flow,node_report_export toneAmber
class node_domain_entities,node_repo_contracts toneMint
class node_auth,node_transaction_repo,node_installment_repo,node_database,node_email toneRose
class node_capture_flow,node_capture_api,node_chat_service,node_telegram toneIndigo
```

## Components

### Web experience

- [Sign-in UI](https://github.com/dannyahia/hermes/blob/main/src/app/(auth)/login/login-form.tsx): `src/app/(auth)/login/login-form.tsx`
- [Finance pages](https://github.com/dannyahia/hermes/blob/main/src/app/layout.tsx): `src/app/layout.tsx`
- [Transactions UI](https://github.com/dannyahia/hermes/blob/main/src/app/transactions/page.tsx): `src/app/transactions/page.tsx`
- [Accounts UI](https://github.com/dannyahia/hermes/blob/main/src/app/accounts/page.tsx): `src/app/accounts/page.tsx`
- [Dashboard UI](https://github.com/dannyahia/hermes/blob/main/src/app/dashboard/page.tsx): `src/app/dashboard/page.tsx`
- [Reports UI](https://github.com/dannyahia/hermes/blob/main/src/app/reports/page.tsx): `src/app/reports/page.tsx`

### Finance workflows

- [Transaction operations](https://github.com/dannyahia/hermes/tree/main/src/modules/transactions/application): `src/modules/transactions/application`
- [Account operations](https://github.com/dannyahia/hermes/tree/main/src/modules/accounts/application): `src/modules/accounts/application`
- [Budget tracking](https://github.com/dannyahia/hermes/tree/main/src/modules/budgets/application): `src/modules/budgets/application`
- [Categories](https://github.com/dannyahia/hermes/tree/main/src/modules/categories/application): `src/modules/categories/application`
- [Financial overview](https://github.com/dannyahia/hermes/tree/main/src/modules/dashboard/application): `src/modules/dashboard/application`
- [Reports](https://github.com/dannyahia/hermes/tree/main/src/modules/reports/application): `src/modules/reports/application`
- [Loans and plans](https://github.com/dannyahia/hermes/blob/main/src/modules/installments/application/create-installment-plan.use-case.ts): `src/modules/installments/application/create-installment-plan.use-case.ts`
- [Recurring activity](https://github.com/dannyahia/hermes/tree/main/src/modules/recurring-transactions/application): `src/modules/recurring-transactions/application`
- [Report export API](https://github.com/dannyahia/hermes/blob/main/src/app/api/reports/export/route.ts): `src/app/api/reports/export/route.ts`

### Domain model

- [Finance entities](https://github.com/dannyahia/hermes/blob/main/src/core/entities/transaction.ts): `src/core/entities/transaction.ts`
- [Repository contracts](https://github.com/dannyahia/hermes/blob/main/src/core/contracts/transaction-repository.ts): `src/core/contracts/transaction-repository.ts`

### Platform and storage

- [Authentication](https://github.com/dannyahia/hermes/blob/main/src/infra/auth/server.ts): `src/infra/auth/server.ts`
- [Transaction repository](https://github.com/dannyahia/hermes/blob/main/src/infra/repositories/drizzle-transaction.repository.ts): `src/infra/repositories/drizzle-transaction.repository.ts`
- [Installment repository](https://github.com/dannyahia/hermes/blob/main/src/infra/repositories/drizzle-installment-plan.repository.ts): `src/infra/repositories/drizzle-installment-plan.repository.ts`
- [PostgreSQL](https://github.com/dannyahia/hermes/blob/main/src/infra/database/schema.ts): `src/infra/database/schema.ts`
- [Email sender](https://github.com/dannyahia/hermes/blob/main/src/infra/email/resend-email-sender.adapter.ts): `src/infra/email/resend-email-sender.adapter.ts`

### Capture integrations

- [Payment capture](https://github.com/dannyahia/hermes/tree/main/src/modules/capture/application): `src/modules/capture/application`
- [Wallet capture API](https://github.com/dannyahia/hermes/blob/main/src/app/api/capture/wallet/route.ts): `src/app/api/capture/wallet/route.ts`
- [Chat orchestration](https://github.com/dannyahia/hermes/blob/main/src/shared/server/chat.ts): `src/shared/server/chat.ts`
- [Telegram adapter](https://github.com/dannyahia/hermes/blob/main/src/infra/telegram/telegram-chat-channel.ts): `src/infra/telegram/telegram-chat-channel.ts`

### Other components

- **User**

## Connections

- User → Sign-in UI: signs in
- User → Finance pages: uses
- Sign-in UI → Authentication: authenticates
- Finance pages → Transactions UI: renders
- Transactions UI → Transaction operations: manages transactions
- Finance pages → Accounts UI: renders
- Accounts UI → Account operations: manages accounts
- Finance pages → Dashboard UI: renders
- Dashboard UI → Financial overview: loads overview
- Finance pages → Reports UI: renders
- Reports UI → Reports: loads reports
- Reports UI → Report export API: requests export
- Report export API → Reports: builds report (evidence: `src/app/api/reports/export/route.ts`)
- Report export API → Transaction repository: reads transactions (evidence: `src/app/api/reports/export/route.ts`)
- Report export API → PostgreSQL: exports PDF (evidence: `src/app/api/reports/export/route.ts`)
- Transaction operations → Transaction repository: persists transactions
- Transaction repository → PostgreSQL: queries tables (evidence: `src/infra/repositories/drizzle-transaction.repository.ts`)
- Installment repository → PostgreSQL: queries plans (evidence: `src/infra/repositories/drizzle-installment-plan.repository.ts`)
- Transaction repository → Repository contracts: implements contract (evidence: `src/infra/repositories/drizzle-transaction.repository.ts`)
- Installment repository → Finance entities: maps plans (evidence: `src/infra/repositories/drizzle-installment-plan.repository.ts`)
- Transaction operations → Finance entities: creates transactions
- Account operations → Finance entities: uses finance entities
- Budget tracking → Finance entities: uses finance entities
- Categories → Finance entities: uses finance entities
- Financial overview → Finance entities: calculates metrics
- Loans and plans → Repository contracts: uses repositories (evidence: `src/modules/installments/application/create-installment-plan.use-case.ts`)
- Loans and plans → Installment repository: loads and saves plans (evidence: `src/modules/installments/application/create-installment-plan.use-case.ts`)
- Recurring activity → Finance entities: uses finance entities
- Authentication → PostgreSQL: uses schema (evidence: `src/infra/auth/server.ts`)
- Authentication → Email sender: sends email (evidence: `src/infra/auth/server.ts`)
- Wallet capture API → Payment capture: records payment (evidence: `src/app/api/capture/wallet/route.ts`)
- Wallet capture API → Chat orchestration: announces capture (evidence: `src/app/api/capture/wallet/route.ts`)
- Chat orchestration → Telegram adapter: dispatches messages (evidence: `src/shared/server/chat.ts`)
