163 lines
5.2 KiB
Markdown
163 lines
5.2 KiB
Markdown
# Sendico [](https://ci.sendico.io/repos/1)
|
|
|
|
|
|
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
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
make infra-up # Start infrastructure only (MongoDB, NATS, Vault)
|
|
make services-up # Start application services only (assumes infra is running)
|
|
```
|
|
|
|
### Build Groups
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
make test # Run all tests (API + frontend)
|
|
make test-api # Run Go API tests only
|
|
make test-frontend # Run Flutter tests only
|
|
```
|
|
|
|
### Update Dependencies
|
|
|
|
```bash
|
|
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`):
|
|
|
|
```hcl
|
|
path "kv/data/callbacks/*" {
|
|
capabilities = ["read"]
|
|
}
|
|
|
|
path "kv/metadata/callbacks/*" {
|
|
capabilities = ["read", "list"]
|
|
}
|
|
```
|
|
|
|
Create policy + role (example):
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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`):
|
|
|
|
```bash
|
|
vault kv put kv/callbacks/client-a/webhook secret="super-secret"
|
|
```
|