# senjumarru/miniwallet architecture

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

- Interactive diagram: https://gitdiagram.com/senjumarru/miniwallet
- Repository: https://github.com/senjumarru/miniwallet

## Overview

MiniWallet is a Go payment and wallet core. Its main workflow accepts an authenticated, rate-limited payment request, applies idempotency and payment rules, creates a provider checkout session, and returns the result. Provider webhooks update payment state; a background reconciler checks stale pending payments. SQLite is the documented durable store, with an in-memory implementation also present. The tree does not include the README’s referenced server entry point, so startup wiring is not represented; some storage and provider connections are documented but not visible in the sampled call sites.

Main entry points: [`internal/httpapi/handler.go`](https://github.com/senjumarru/miniwallet/blob/main/internal/httpapi/handler.go) (HTTP Routes), [`internal/service/payment.go`](https://github.com/senjumarru/miniwallet/blob/main/internal/service/payment.go) (Payment Service), [`internal/provider/client.go`](https://github.com/senjumarru/miniwallet/blob/main/internal/provider/client.go) (Provider Client), [`internal/service/reconciler.go`](https://github.com/senjumarru/miniwallet/blob/main/internal/service/reconciler.go) (Reconciler)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["HTTP API"]
  node_http["HTTP Routes<br/>[handler.go]"]
  node_auth["JWT Auth<br/>[auth.go]"]
  node_limits["Rate Limits<br/>[ratelimit.go]"]
  node_httpmiddleware["HTTP Middleware<br/>[middleware.go]"]
  node_responses["API Responses<br/>[response.go]"]
  node_server["HTTP Server<br/>[server.go]"]
end

subgraph group_payments["Payment Domain"]
  node_payment["Payment Service<br/>[payment.go]"]
  node_reconciler["Reconciler<br/>[reconciler.go]"]
  node_contracts["Service Contracts<br/>[interfaces.go]"]
  node_domain["Payment Models<br/>[models.go]"]
  node_clock["Domain Clock<br/>[clock.go]"]
end

subgraph group_provider["Provider Integration"]
  node_providerclient["Provider Client<br/>[client.go]"]
  node_circuit["Circuit Breaker<br/>[circuit_breaker.go]"]
  node_providercontract["Provider Contract<br/>[provider.go]"]
end

subgraph group_persistence["Persistence"]
  node_sqlite[("SQLite Database<br/>[sqlite.go]")]
  node_sqlrepos["SQLite Repositories<br/>[repositories.go]"]
  node_memory["Memory Storage<br/>[memory.go]"]
  node_schema["Database Schema<br/>[001_init.sql]"]
end

subgraph group_operations["Operations"]
  node_config["Configuration<br/>[config.go]"]
  node_metrics["Prometheus Metrics<br/>[metrics.go]"]
end

node_client(("API Client"))
node_providerapi["PSP"]

node_client -->|"sends requests"| node_http
node_http -->|"applies JWT"| node_auth
node_http -->|"applies limits"| node_limits
node_http -->|"calls service"| node_payment
node_http -->|"formats errors"| node_responses
node_http -.->|"wraps routes"| node_httpmiddleware
node_payment -.->|"creates checkout"| node_providerclient
node_payment -->|"uses models"| node_domain
node_payment -->|"uses interfaces"| node_contracts
node_payment -.->|"persists state"| node_sqlrepos
node_payment -.->|"alternative storage"| node_memory
node_reconciler -->|"checks status"| node_providerclient
node_reconciler -.->|"loads stale payments"| node_sqlrepos
node_providerclient -->|"calls PSP"| node_providerapi
node_providerclient -->|"checks circuit"| node_circuit
node_providerclient -.->|"implements contract"| node_providercontract
node_sqlrepos -.->|"queries database"| node_sqlite
node_sqlite -.->|"uses schema"| node_schema
node_reconciler -->|"uses clock"| node_clock
node_providerclient -->|"records metrics"| node_metrics
node_http -->|"exposes metrics"| node_metrics
node_server -.->|"serves handler"| node_http
node_config -.->|"configures startup"| node_server

click node_http "https://github.com/senjumarru/miniwallet/blob/main/internal/httpapi/handler.go"
click node_auth "https://github.com/senjumarru/miniwallet/blob/main/internal/httpapi/auth.go"
click node_limits "https://github.com/senjumarru/miniwallet/blob/main/internal/httpapi/ratelimit.go"
click node_httpmiddleware "https://github.com/senjumarru/miniwallet/blob/main/internal/httpapi/middleware.go"
click node_responses "https://github.com/senjumarru/miniwallet/blob/main/internal/httpapi/response.go"
click node_server "https://github.com/senjumarru/miniwallet/blob/main/internal/httpapi/server.go"
click node_payment "https://github.com/senjumarru/miniwallet/blob/main/internal/service/payment.go"
click node_reconciler "https://github.com/senjumarru/miniwallet/blob/main/internal/service/reconciler.go"
click node_contracts "https://github.com/senjumarru/miniwallet/blob/main/internal/service/interfaces.go"
click node_domain "https://github.com/senjumarru/miniwallet/blob/main/internal/domain/models.go"
click node_clock "https://github.com/senjumarru/miniwallet/blob/main/internal/domain/clock.go"
click node_providerclient "https://github.com/senjumarru/miniwallet/blob/main/internal/provider/client.go"
click node_circuit "https://github.com/senjumarru/miniwallet/blob/main/internal/provider/circuit_breaker.go"
click node_providercontract "https://github.com/senjumarru/miniwallet/blob/main/internal/provider/provider.go"
click node_sqlite "https://github.com/senjumarru/miniwallet/blob/main/internal/storage/sqlite/sqlite.go"
click node_sqlrepos "https://github.com/senjumarru/miniwallet/blob/main/internal/storage/sqlite/repositories.go"
click node_memory "https://github.com/senjumarru/miniwallet/blob/main/internal/storage/memory/memory.go"
click node_schema "https://github.com/senjumarru/miniwallet/blob/main/migrations/001_init.sql"
click node_config "https://github.com/senjumarru/miniwallet/blob/main/internal/config/config.go"
click node_metrics "https://github.com/senjumarru/miniwallet/blob/main/internal/metrics/metrics.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_http,node_auth,node_limits,node_httpmiddleware,node_responses,node_server,node_client toneBlue
class node_payment,node_reconciler,node_contracts,node_domain,node_clock toneAmber
class node_providerclient,node_circuit,node_providercontract toneMint
class node_sqlite,node_sqlrepos,node_memory,node_schema toneRose
class node_config,node_metrics,node_providerapi toneIndigo
```

## Components

### HTTP API

- [HTTP Routes](https://github.com/senjumarru/miniwallet/blob/main/internal/httpapi/handler.go): `internal/httpapi/handler.go`
- [JWT Auth](https://github.com/senjumarru/miniwallet/blob/main/internal/httpapi/auth.go): `internal/httpapi/auth.go`
- [Rate Limits](https://github.com/senjumarru/miniwallet/blob/main/internal/httpapi/ratelimit.go): `internal/httpapi/ratelimit.go`
- [HTTP Middleware](https://github.com/senjumarru/miniwallet/blob/main/internal/httpapi/middleware.go): `internal/httpapi/middleware.go`
- [API Responses](https://github.com/senjumarru/miniwallet/blob/main/internal/httpapi/response.go): `internal/httpapi/response.go`
- [HTTP Server](https://github.com/senjumarru/miniwallet/blob/main/internal/httpapi/server.go): `internal/httpapi/server.go`

### Payment Domain

- [Payment Service](https://github.com/senjumarru/miniwallet/blob/main/internal/service/payment.go): `internal/service/payment.go`
- [Reconciler](https://github.com/senjumarru/miniwallet/blob/main/internal/service/reconciler.go): `internal/service/reconciler.go`
- [Service Contracts](https://github.com/senjumarru/miniwallet/blob/main/internal/service/interfaces.go): `internal/service/interfaces.go`
- [Payment Models](https://github.com/senjumarru/miniwallet/blob/main/internal/domain/models.go): `internal/domain/models.go`
- [Domain Clock](https://github.com/senjumarru/miniwallet/blob/main/internal/domain/clock.go): `internal/domain/clock.go`

### Provider Integration

- [Provider Client](https://github.com/senjumarru/miniwallet/blob/main/internal/provider/client.go): `internal/provider/client.go`
- [Circuit Breaker](https://github.com/senjumarru/miniwallet/blob/main/internal/provider/circuit_breaker.go): `internal/provider/circuit_breaker.go`
- [Provider Contract](https://github.com/senjumarru/miniwallet/blob/main/internal/provider/provider.go): `internal/provider/provider.go`

### Persistence

- [SQLite Database](https://github.com/senjumarru/miniwallet/blob/main/internal/storage/sqlite/sqlite.go): `internal/storage/sqlite/sqlite.go`
- [SQLite Repositories](https://github.com/senjumarru/miniwallet/blob/main/internal/storage/sqlite/repositories.go): `internal/storage/sqlite/repositories.go`
- [Memory Storage](https://github.com/senjumarru/miniwallet/blob/main/internal/storage/memory/memory.go): `internal/storage/memory/memory.go`
- [Database Schema](https://github.com/senjumarru/miniwallet/blob/main/migrations/001_init.sql): `migrations/001_init.sql`

### Operations

- [Configuration](https://github.com/senjumarru/miniwallet/blob/main/internal/config/config.go): `internal/config/config.go`
- [Prometheus Metrics](https://github.com/senjumarru/miniwallet/blob/main/internal/metrics/metrics.go): `internal/metrics/metrics.go`

### Other components

- **API Client**
- **PSP**

## Connections

- API Client → HTTP Routes: sends requests (evidence: `internal/httpapi/handler.go`)
- HTTP Routes → JWT Auth: applies JWT (evidence: `internal/httpapi/handler.go`)
- HTTP Routes → Rate Limits: applies limits (evidence: `internal/httpapi/handler.go`)
- HTTP Routes → Payment Service: calls service (evidence: `internal/httpapi/handler.go`)
- HTTP Routes → API Responses: formats errors (evidence: `internal/httpapi/response.go`)
- HTTP Routes → HTTP Middleware: wraps routes
- Payment Service → Provider Client: creates checkout
- Payment Service → Payment Models: uses models (evidence: `internal/service/payment.go`)
- Payment Service → Service Contracts: uses interfaces (evidence: `internal/service/interfaces.go`)
- Payment Service → SQLite Repositories: persists state
- Payment Service → Memory Storage: alternative storage
- Reconciler → Provider Client: checks status (evidence: `internal/service/reconciler.go`)
- Reconciler → SQLite Repositories: loads stale payments
- Provider Client → PSP: calls PSP (evidence: `README.md`)
- Provider Client → Circuit Breaker: checks circuit (evidence: `internal/provider/client.go`)
- Provider Client → Provider Contract: implements contract
- SQLite Repositories → SQLite Database: queries database
- SQLite Database → Database Schema: uses schema
- Reconciler → Domain Clock: uses clock (evidence: `internal/service/reconciler.go`)
- Provider Client → Prometheus Metrics: records metrics (evidence: `internal/provider/client.go`)
- HTTP Routes → Prometheus Metrics: exposes metrics (evidence: `internal/httpapi/handler.go`)
- HTTP Server → HTTP Routes: serves handler
- Configuration → HTTP Server: configures startup
