# Sendico [![Build Status](https://ci.sendico.io/api/badges/1/status.svg?branch=main)](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 Aurora | `api/gateway/aurora/` | Card payouts simulator |
| 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 |

Gateway note: current dev compose workflows (`make services-up`, `make build-gateways`) use Aurora for card-payout flows (`chain`, `tron`, `aurora`, `tgsettle`). The MNTX gateway codebase is retained separately for Monetix-specific integration.

## Prerequisites

- Docker with Docker Compose plugin
- GNU Make
- Go toolchain
- Dart SDK
- Flutter SDK

## 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 list-services        # List all services and ports
make health               # Check service health
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)
make backend-up    # Start backend services only (no infrastructure/frontend changes)
make backend-down  # Stop backend services only
make backend-rebuild # Rebuild and restart backend services only
make list-services # Show service names, ports, and descriptions
```

### Build Groups

```bash
make build-core       # discovery, ledger, fees, documents
make build-fx         # oracle, ingestor
make build-payments   # orchestrator, quotation, methods
make build-gateways   # chain, tron, aurora, 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/sendico/callbacks/*" {
  capabilities = ["read"]
}

path "kv/metadata/sendico/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/sendico/callbacks/client-a/webhook secret="super-secret"
```