Ledger Service — Mini-FinTech Platform

Ledger Service is the core of a financial system implementing double-entry accounting. It acts as a single source of truth for balances and transactions.

Features

• Double-entry accounting (Σ DEBIT == Σ CREDIT)
• Money stored in minor units (int64, no floats)
• Idempotent transactions
• Clean Architecture
• PostgreSQL + SQL migrations
• gRPC API with reflection
• CI with lint, unit and integration tests

Quickstart

make tools
make run
make migrate-up
make test

Check gRPC reflection:

grpcurl -plaintext localhost:8081 list

Make targets

• make tools — install dev tools
• make migrate-up / make migrate-down
• make proto
• make test-unit
• make test-integration
• make test
• make lint
• make lint-ci
• make check

Configuration

Environment variables:

• DB_DSN — PostgreSQL DSN
• GRPC_PORT — gRPC port

Example:

DB_DSN=postgres://ledger:ledger@localhost:5432/ledger?sslmode=disable
GRPC_PORT=8081

Architecture

Clean Architecture with explicit responsibility separation.

cmd/ledger
internal/
  config/
  db/
  domain/
  repo/postgres/
  service/
    integration/
  transport/grpc/
proto/ledger/v1/
migrations/
test/

Layers

domain

• Entities, errors, invariants

service

• Validation
• Business rules
• Idempotency

repo

• PostgreSQL access
• SQL → domain error mapping

transport/grpc

• gRPC API
• Domain → gRPC status mapping
• No business logic

Core concepts

Double-entry accounting

Each transaction contains at least:

• DEBIT
• CREDIT

Invariant:

Σ DEBIT == Σ CREDIT

Money representation

• Stored in minor units
• int64
• Floats forbidden

Example:

1000 = 10.00 RUB

Commit message convention

This project uses Conventional Commits:

• feat: new feature
• fix: bug fix
• docs: documentation
• refactor: refactoring
• test: tests
• ci: CI changes
• chore: maintenance

Examples:

• feat: add balance endpoint
• fix(repo): handle pgx.ErrNoRows
• ci: add postgres integration job

Contributing

See CONTRIBUTING.md.

License

MIT — see LICENSE.