Sendico

Financial services platform providing payment orchestration, ledger accounting, FX conversion, and multi-rail payment processing.

Architecture

• Backend: Go microservices with gRPC inter-service communication
• Frontend: Flutter/Dart web application
• Infrastructure: Woodpecker CI/CD, Docker, MongoDB, NATS, Vault

Services

Service	Path	Description
Discovery	api/discovery/	Service registry
Ledger	api/ledger/	Double-entry accounting
Orchestrator	api/payments/orchestrator/	Payment orchestration
Quotation	api/payments/quotation/	Payment quotation
Payment Methods	api/payments/methods/	Payment methods
Billing Fees	api/billing/fees/	Fee calculation
Billing Documents	api/billing/documents/	Billing documents
FX Oracle	api/fx/oracle/	FX quote provider
FX Ingestor	api/fx/ingestor/	FX rate ingestion
Gateway Chain	api/gateway/chain/	EVM blockchain gateway
Gateway TRON	api/gateway/tron/	TRON blockchain gateway
Gateway MNTX	api/gateway/mntx/	Card payouts
Gateway TGSettle	api/gateway/tgsettle/	Telegram settlements with MNTX
Notification	api/notification/	Notifications
BFF	api/edge/bff/	Backend for frontend
Callbacks	api/edge/callbacks/	Webhook callbacks delivery
Frontend	frontend/pweb/	Flutter web UI

Development

Development uses Docker Compose via the Makefile. Run make help for all available commands.

Quick Start

make init       # First-time setup (generates keys, .env.dev, builds images)
make up         # Start all services
make vault-init # Initialize Vault (if needed)

Common Commands

make build                # Build all service images
make up                   # Start all services
make down                 # Stop all services
make restart              # Restart all services
make status               # Show service status
make logs                 # View all logs
make logs SERVICE=dev-ledger  # View logs for a specific service
make rebuild SERVICE=dev-ledger # Rebuild and restart a specific service
make clean                # Remove all containers and volumes

Selective Start

make infra-up      # Start infrastructure only (MongoDB, NATS, Vault)
make services-up   # Start application services only (assumes infra is running)

Build Groups

make build-core       # discovery, ledger, fees, documents
make build-fx         # oracle, ingestor
make build-payments   # orchestrator
make build-gateways   # chain, tron, mntx, tgsettle
make build-api        # notification, callbacks, bff
make build-frontend   # Flutter web UI

Code Generation

make generate            # Generate all code (protobuf + Flutter)
make generate-api        # Generate protobuf code only
make generate-frontend   # Generate Flutter code only (build_runner)
make proto               # Alias for generate-api

Testing

make test           # Run all tests (API + frontend)
make test-api       # Run Go API tests only
make test-frontend  # Run Flutter tests only

Update Dependencies

make update            # Update all Go and Flutter dependencies
make update-api        # Update Go dependencies only
make update-frontend   # Update Flutter dependencies only

Callbacks Secret References

Callbacks (api/edge/callbacks) supports three secret reference formats:

• env:MY_SECRET_ENV to read from environment variables.
• vault:some/path#field to read a field from Vault KV v2.
• some/path#field to read from Vault KV v2 when secrets.vault is configured.

If #field is omitted, callbacks uses secrets.vault.default_field (default: value).

Callbacks Vault Auth (Dev + Prod)

Callbacks now authenticates to Vault through a sidecar Vault Agent (AppRole), same pattern as chain/tron gateways.

• Dev compose:
  • service: dev-callbacks-vault-agent
  • shared token file: /run/vault/token
  • app reads token via VAULT_TOKEN_FILE=/run/vault/token and token_env: VAULT_TOKEN
• Prod compose:
  • service: sendico_callbacks_vault_agent
  • same token sink and env flow
  • AppRole creds are injected at deploy from CALLBACKS_VAULT_SECRET_PATH (default sendico/edge/callbacks/vault)

Required Vault policy (minimal read-only for KV v2 mount kv):

path "kv/data/sendico/callbacks/*" {
  capabilities = ["read"]
}

path "kv/metadata/sendico/callbacks/*" {
  capabilities = ["read", "list"]
}

Create policy + role (example):

vault policy write callbacks callbacks-policy.hcl
vault write auth/approle/role/callbacks \
  token_policies="callbacks" \
  token_ttl="1h" \
  token_max_ttl="24h"
vault read -field=role_id auth/approle/role/callbacks/role-id
vault write -f -field=secret_id auth/approle/role/callbacks/secret-id

Store AppRole creds for prod deploy pipeline:

vault kv put kv/sendico/edge/callbacks/vault \
  role_id="<callbacks-role-id>" \
  secret_id="<callbacks-secret-id>"

Store webhook signing secrets (example path consumed by secret_ref):

vault kv put kv/sendico/callbacks/client-a/webhook secret="super-secret"