Infrastructure
Services, ports, and communication protocols.
Services and ports
| Service | Port | Purpose |
|---|---|---|
| Payment Reconciler API | 8000 | Main REST API |
| LedgerMatch (REST) | 9000 | Single-transaction matching |
| LedgerMatch (gRPC) | 50051 | Bulk matching |
| Keycloak | 8080 | Authentication, user management |
| PostgreSQL (Payment Reconciler) | 5433 | Payment Reconciler database |
| PostgreSQL (LedgerMatch) | 5434 | LedgerMatch database |
| PostgreSQL (Keycloak) | — | Keycloak DB (internal to Docker) |
| Redis | 6379 | BullMQ queues, cache |
| RedisInsight | 5540 | Redis UI (optional) |
| Mailpit | 1025 (SMTP), 8025 (UI) | Dev email capture for invites and notifications |
| Ollama | 11434 | Local embeddings (when not using OpenAI) |
Port 5433 is used for Payment Reconciler DB to avoid conflict with a local PostgreSQL on 5432.
Communication protocols
| Protocol | Use |
|---|---|
| REST | All client-to-API communication. LedgerMatch single-transaction match. |
| gRPC | LedgerMatch bulk match when tenant has matchStrategy: 'grpc'. |
| Webhooks | Outbound HTTP POST to subscriber URLs with event payloads. |
| Keycloak | OAuth2/JWT. Token exchange, JWKS validation. |
Dependencies
| Dependency | Required | Impact if unavailable |
|---|---|---|
| LedgerMatch | Yes | Matching fails. Health check fails. |
| PostgreSQL | Yes | API cannot start. |
| Redis | Yes | Jobs and queue processing fail. |
| Keycloak | Production | Token exchange and JWT validation for documented integration. |
| Ollama | When using Ollama embeddings | LedgerMatch needs embeddings. Use EMBEDDING_PROVIDER=openai + OPENAI_API_KEY as alternative. |
Docker Compose layout
When you run docker-compose up, the stack includes:
- payment-reconciler-db — Payment Reconciler PostgreSQL
- ledger-match-db — LedgerMatch PostgreSQL
- ledger-match — LedgerMatch service (built from
../ledger-match-service) - ollama — Pulls
mxbai-embed-largefor embeddings - redis — BullMQ and cache
- keycloak + keycloak-db — Auth (optional for dev)
- payment-reconciler — The API (runs migrations, seed, start:dev)
The payment-reconciler container starts automatically and runs migrations, Keycloak realm setup, seed, and the dev server. For local development without the full container, you can run only the dependencies (DB, Redis, LedgerMatch, Keycloak) and run the API locally with npm run start:dev. See Development.
API Reference
For API base URL and authentication, see API Reference Overview.