# oonexusoo/personal-finance-manager architecture

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

- Interactive diagram: https://gitdiagram.com/oonexusoo/personal-finance-manager
- Repository: https://github.com/oonexusoo/personal-finance-manager

## Overview

Personal Finance Manager is a Go service for user accounts, income and expense tracking, categorization, receipt attachments, live balance updates, and currency conversion. The main workflow is an authenticated client request routed by the API to transaction or category handlers, with services and repositories applying domain logic and persisting data in PostgreSQL; transaction changes can trigger a user-specific WebSocket balance update. Currency requests are proxied by the API to a separate gRPC service. The README documents the major capabilities; arrows reflect only relationships visible in sampled files or README, so unsampled subsystem links are omitted.

Main entry points: [`cmd/api/main.go`](https://github.com/oonexusoo/personal-finance-manager/blob/main/cmd/api/main.go) (HTTP API), [`internal/transactions/handler.go`](https://github.com/oonexusoo/personal-finance-manager/blob/main/internal/transactions/handler.go) (Transaction endpoints), [`internal/auth/service.go`](https://github.com/oonexusoo/personal-finance-manager/blob/main/internal/auth/service.go) (Identity service), [`internal/websocket/handler.go`](https://github.com/oonexusoo/personal-finance-manager/blob/main/internal/websocket/handler.go) (WebSocket handler)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API and identity"]
  node_api_server["HTTP API<br/>[main.go]"]
  node_auth_http["Account endpoints<br/>[handler.go]"]
  node_auth_logic["Identity service<br/>[service.go]"]
  node_auth_data["User repository<br/>[repository.go]"]
  node_jwt_guard["JWT middleware<br/>[middleware.go]"]
end

subgraph group_finance["Finance domain"]
  node_transactions["Transaction endpoints<br/>[handler.go]"]
  node_tx_logic["Transaction service<br/>[service.go]"]
  node_tx_data["Transaction repository<br/>[repository.go]"]
  node_categories["Category endpoints<br/>[handler.go]"]
  node_category_logic["Category service<br/>[service.go]"]
  node_category_data["Category repository<br/>[repository.go]"]
  node_receipt_files["Receipt files<br/>[handler.go]"]
end

subgraph group_realtime["Live updates"]
  node_ws_handler["WebSocket handler<br/>[handler.go]"]
  node_ws_hub["User broadcast hub<br/>[hub.go]"]
end

subgraph group_currency["Currency conversion"]
  node_currency_routes["Currency API routes<br/>[main.go]"]
  node_currency_client["gRPC currency client<br/>[client.go]"]
  node_currency_server["Currency service<br/>[server.go]"]
  node_grpc_entry["gRPC server<br/>[main.go]"]
end

subgraph group_persistence["Persistence"]
  node_postgres[("PostgreSQL<br/>[postgres.go]")]
  node_models["Domain models<br/>[models.go]"]
end

node_client(("Finance client"))

node_client -->|"sends requests"| node_api_server
node_api_server -->|"routes auth"| node_auth_http
node_api_server -->|"routes transactions"| node_transactions
node_api_server -->|"routes categories"| node_categories
node_api_server -->|"guards routes"| node_jwt_guard
node_api_server -->|"routes WebSocket"| node_ws_handler
node_auth_http -->|"calls"| node_auth_logic
node_auth_logic -->|"reads and writes"| node_auth_data
node_jwt_guard -->|"validates tokens"| node_auth_logic
node_transactions -->|"calls"| node_tx_logic
node_transactions -->|"attachment access"| node_tx_data
node_transactions -->|"stores and serves"| node_receipt_files
node_tx_logic -->|"queries transactions"| node_tx_data
node_categories -->|"calls"| node_category_logic
node_category_logic -->|"queries categories"| node_category_data
node_api_server -->|"queries balance"| node_tx_data
node_api_server -->|"broadcasts balance"| node_ws_hub
node_ws_handler -->|"registers clients"| node_ws_hub
node_client -->|"opens connection"| node_ws_handler
node_api_server -->|"configures routes"| node_currency_routes
node_currency_routes -->|"requests rates or conversion"| node_currency_client
node_currency_client -->|"calls gRPC"| node_grpc_entry
node_grpc_entry -->|"registers service"| node_currency_server

click node_api_server "https://github.com/oonexusoo/personal-finance-manager/blob/main/cmd/api/main.go"
click node_auth_http "https://github.com/oonexusoo/personal-finance-manager/blob/main/internal/auth/handler.go"
click node_auth_logic "https://github.com/oonexusoo/personal-finance-manager/blob/main/internal/auth/service.go"
click node_auth_data "https://github.com/oonexusoo/personal-finance-manager/blob/main/internal/auth/repository.go"
click node_jwt_guard "https://github.com/oonexusoo/personal-finance-manager/blob/main/internal/auth/middleware.go"
click node_transactions "https://github.com/oonexusoo/personal-finance-manager/blob/main/internal/transactions/handler.go"
click node_tx_logic "https://github.com/oonexusoo/personal-finance-manager/blob/main/internal/transactions/service.go"
click node_tx_data "https://github.com/oonexusoo/personal-finance-manager/blob/main/internal/transactions/repository.go"
click node_categories "https://github.com/oonexusoo/personal-finance-manager/blob/main/internal/categories/handler.go"
click node_category_logic "https://github.com/oonexusoo/personal-finance-manager/blob/main/internal/categories/service.go"
click node_category_data "https://github.com/oonexusoo/personal-finance-manager/blob/main/internal/categories/repository.go"
click node_receipt_files "https://github.com/oonexusoo/personal-finance-manager/blob/main/internal/transactions/handler.go"
click node_ws_handler "https://github.com/oonexusoo/personal-finance-manager/blob/main/internal/websocket/handler.go"
click node_ws_hub "https://github.com/oonexusoo/personal-finance-manager/blob/main/internal/websocket/hub.go"
click node_currency_routes "https://github.com/oonexusoo/personal-finance-manager/blob/main/cmd/api/main.go"
click node_currency_client "https://github.com/oonexusoo/personal-finance-manager/blob/main/internal/currency/client.go"
click node_currency_server "https://github.com/oonexusoo/personal-finance-manager/blob/main/internal/currency/server.go"
click node_grpc_entry "https://github.com/oonexusoo/personal-finance-manager/blob/main/cmd/grpc-server/main.go"
click node_postgres "https://github.com/oonexusoo/personal-finance-manager/blob/main/internal/database/postgres.go"
click node_models "https://github.com/oonexusoo/personal-finance-manager/blob/main/internal/models/models.go"

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_api_server,node_auth_http,node_auth_logic,node_auth_data,node_jwt_guard,node_client toneBlue
class node_transactions,node_tx_logic,node_tx_data,node_categories,node_category_logic,node_category_data,node_receipt_files toneAmber
class node_ws_handler,node_ws_hub toneMint
class node_currency_routes,node_currency_client,node_currency_server,node_grpc_entry toneRose
class node_postgres,node_models toneIndigo
```

## Components

### API and identity

- [HTTP API](https://github.com/oonexusoo/personal-finance-manager/blob/main/cmd/api/main.go): `cmd/api/main.go`
- [Account endpoints](https://github.com/oonexusoo/personal-finance-manager/blob/main/internal/auth/handler.go): `internal/auth/handler.go`
- [Identity service](https://github.com/oonexusoo/personal-finance-manager/blob/main/internal/auth/service.go): `internal/auth/service.go`
- [User repository](https://github.com/oonexusoo/personal-finance-manager/blob/main/internal/auth/repository.go): `internal/auth/repository.go`
- [JWT middleware](https://github.com/oonexusoo/personal-finance-manager/blob/main/internal/auth/middleware.go): `internal/auth/middleware.go`

### Finance domain

- [Transaction endpoints](https://github.com/oonexusoo/personal-finance-manager/blob/main/internal/transactions/handler.go): `internal/transactions/handler.go`
- [Transaction service](https://github.com/oonexusoo/personal-finance-manager/blob/main/internal/transactions/service.go): `internal/transactions/service.go`
- [Transaction repository](https://github.com/oonexusoo/personal-finance-manager/blob/main/internal/transactions/repository.go): `internal/transactions/repository.go`
- [Category endpoints](https://github.com/oonexusoo/personal-finance-manager/blob/main/internal/categories/handler.go): `internal/categories/handler.go`
- [Category service](https://github.com/oonexusoo/personal-finance-manager/blob/main/internal/categories/service.go): `internal/categories/service.go`
- [Category repository](https://github.com/oonexusoo/personal-finance-manager/blob/main/internal/categories/repository.go): `internal/categories/repository.go`
- [Receipt files](https://github.com/oonexusoo/personal-finance-manager/blob/main/internal/transactions/handler.go): `internal/transactions/handler.go`

### Live updates

- [WebSocket handler](https://github.com/oonexusoo/personal-finance-manager/blob/main/internal/websocket/handler.go): `internal/websocket/handler.go`
- [User broadcast hub](https://github.com/oonexusoo/personal-finance-manager/blob/main/internal/websocket/hub.go): `internal/websocket/hub.go`

### Currency conversion

- [Currency API routes](https://github.com/oonexusoo/personal-finance-manager/blob/main/cmd/api/main.go): `cmd/api/main.go`
- [gRPC currency client](https://github.com/oonexusoo/personal-finance-manager/blob/main/internal/currency/client.go): `internal/currency/client.go`
- [Currency service](https://github.com/oonexusoo/personal-finance-manager/blob/main/internal/currency/server.go): `internal/currency/server.go`
- [gRPC server](https://github.com/oonexusoo/personal-finance-manager/blob/main/cmd/grpc-server/main.go): `cmd/grpc-server/main.go`

### Persistence

- [PostgreSQL](https://github.com/oonexusoo/personal-finance-manager/blob/main/internal/database/postgres.go): `internal/database/postgres.go`
- [Domain models](https://github.com/oonexusoo/personal-finance-manager/blob/main/internal/models/models.go): `internal/models/models.go`

### Other components

- **Finance client**

## Connections

- Finance client → HTTP API: sends requests (evidence: `README.md`)
- HTTP API → Account endpoints: routes auth (evidence: `cmd/api/main.go`)
- HTTP API → Transaction endpoints: routes transactions (evidence: `cmd/api/main.go`)
- HTTP API → Category endpoints: routes categories (evidence: `cmd/api/main.go`)
- HTTP API → JWT middleware: guards routes (evidence: `cmd/api/main.go`)
- HTTP API → WebSocket handler: routes WebSocket (evidence: `cmd/api/main.go`)
- Account endpoints → Identity service: calls (evidence: `internal/auth/handler.go`)
- Identity service → User repository: reads and writes (evidence: `internal/auth/service.go`)
- JWT middleware → Identity service: validates tokens (evidence: `internal/auth/middleware.go`)
- Transaction endpoints → Transaction service: calls (evidence: `internal/transactions/handler.go`)
- Transaction endpoints → Transaction repository: attachment access (evidence: `internal/transactions/handler.go`)
- Transaction endpoints → Receipt files: stores and serves (evidence: `internal/transactions/handler.go`)
- Transaction service → Transaction repository: queries transactions (evidence: `internal/transactions/service.go`)
- Category endpoints → Category service: calls (evidence: `internal/categories/handler.go`)
- Category service → Category repository: queries categories (evidence: `internal/categories/service.go`)
- HTTP API → Transaction repository: queries balance (evidence: `cmd/api/main.go`)
- HTTP API → User broadcast hub: broadcasts balance (evidence: `cmd/api/main.go`)
- WebSocket handler → User broadcast hub: registers clients (evidence: `internal/websocket/handler.go`)
- Finance client → WebSocket handler: opens connection (evidence: `README.md`)
- HTTP API → Currency API routes: configures routes (evidence: `cmd/api/main.go`)
- Currency API routes → gRPC currency client: requests rates or conversion (evidence: `cmd/api/main.go`)
- gRPC currency client → gRPC server: calls gRPC (evidence: `internal/currency/client.go`)
- gRPC server → Currency service: registers service (evidence: `cmd/grpc-server/main.go`)
