sendico/SETUP.md

# Sendico Development Environment - Setup Guide

Complete Docker Compose + Makefile build system for local development.

## 🎯 What's Included

**13 Services:**
- ✅ Discovery (Service Registry)
- ✅ FX Oracle & FX Ingestor
- ✅ Billing Fees
- ✅ Ledger (Double-Entry Accounting)
- ✅ Payments Orchestrator
- ✅ Chain Gateway (Blockchain)
- ✅ MNTX Gateway (Card Payouts)
- ✅ TGSettle Gateway (Telegram Settlements)
- ✅ Notification
- ✅ BFF (Backend for Frontend / Server)
- ✅ Frontend (Flutter Web)

**Infrastructure:**
- MongoDB Replica Set (3 nodes)
- NATS with JetStream
- Vault (single node, for application data only)

---

## 🚀 Quick Start

```bash
# 1. First time setup
make init

# 2. Start everything
make up

# 3. Initialize Vault (if services need blockchain keys, external API keys)
make vault-init

# 4. Check status
make status

# 5. View frontend
open http://localhost:3000
```

---

## 📋 Prerequisites

- Docker & Docker Compose
- Make
- Go 1.24+ (for local proto generation)
- protoc, protoc-gen-go, protoc-gen-go-grpc (for proto generation)

---

## 🔧 Configuration

### Environment Variables

Edit `.env.dev` (created after `make init`):

```bash
# MongoDB
MONGO_USER=dev_root
MONGO_PASSWORD=dev_password_123

# NATS
NATS_USER=dev_nats
NATS_PASSWORD=nats_password_123

# Vault (for application data only)
VAULT_ADDR=http://dev-vault:8200
```

**IMPORTANT:** These are plaintext credentials for dev infrastructure only!

---

## 📊 Service Ports

**Infrastructure:**
- MongoDB: `localhost:27017`
- NATS: `localhost:4222`
- NATS Monitoring: `localhost:8222`
- Vault: `localhost:8200`

**Services:**
- Discovery: `localhost:9407`
- FX Oracle: `localhost:50051` (gRPC), `localhost:9400` (metrics)
- FX Ingestor: `localhost:9102`
- Billing Fees: `localhost:50060` (gRPC), `localhost:9402` (metrics)
- Ledger: `localhost:50052` (gRPC), `localhost:9401` (metrics)
- Payments Orchestrator: `localhost:50062` (gRPC), `localhost:9403` (metrics)
- Chain Gateway: `localhost:50070` (gRPC), `localhost:9404` (metrics)
- MNTX Gateway: `localhost:50075` (gRPC), `localhost:9405` (metrics), `localhost:8084` (HTTP)
- TGSettle Gateway: `localhost:50080` (gRPC), `localhost:9406` (metrics)
- Notification: `localhost:8081`
- BFF: `localhost:8080`
- Frontend: `localhost:3000`

---

## 🛠️ Common Commands

### Lifecycle

```bash
make up          # Start all services
make down        # Stop all services
make restart     # Restart all services
make status      # Check status
make clean       # Remove everything (containers + volumes)
```

### Development

```bash
# View logs
make logs                      # All services
make logs SERVICE=dev-ledger   # Specific service

# Rebuild after code changes
make rebuild SERVICE=dev-ledger

# Regenerate protobuf
make proto
```

### Selective Startup

```bash
# Start infrastructure only
make infra-up

# Then start services
make services-up

# Or start specific service groups
make build-core      # discovery, ledger, billing-fees
make build-fx        # fx-oracle, fx-ingestor
make build-payments  # payments-orchestrator
make build-gateways  # chain, mntx, tgsettle
```

---

## 🔐 Vault Setup

Vault is **only for application data** (blockchain keys, external API keys).
Infrastructure credentials (MongoDB, NATS) are in `.env.dev`.

### Initialize Vault

```bash
make vault-init
```

This will:
1. Initialize Vault with 1 key share
2. Unseal Vault automatically
3. Save keys to `vault-keys.txt` (NEVER commit this!)
4. Display root token

### Using Vault in Services

Services that need Vault (e.g., Chain Gateway for blockchain keys):
1. Set `VAULT_ADDR` in service environment
2. Use Vault client to fetch secrets at runtime
3. Store secrets in Vault: `kv/data/chain/ethereum/private_key`

---

## 🏗️ Development Workflow

### Typical Day

```bash
# Morning: Start environment
make up

# Work on ledger service
vim api/ledger/internal/service/ledger/posting.go

# Rebuild ledger
make rebuild SERVICE=dev-ledger

# View logs
make logs SERVICE=dev-ledger

# Test
curl http://localhost:9401/health

# End of day
make down
```

### After Changing Protos

```bash
# Regenerate protos
make proto

# Rebuild affected services
make rebuild SERVICE=dev-ledger
make rebuild SERVICE=dev-payments-orchestrator
```

### Frontend Development

For faster iteration, run frontend locally instead of Docker:

```bash
# Start backend services only
make infra-up
make services-up

# Run frontend locally
cd frontend/pweb
flutter run -d chrome
```

---

## 🔍 Debugging

### MongoDB Replica Set Issues

```bash
# Check replica set status
docker exec -it dev-mongo-1 mongosh -u dev_root -p dev_password_123 --eval "rs.status()"

# Reinitialize
make down
make up
docker logs dev-mongo-init
```

### Service Can't Connect to MongoDB

```bash
# Check if replica set is initialized
docker logs dev-mongo-init

# Check MongoDB is healthy
docker ps | grep mongo
```

### Vault Sealed

```bash
# Get unseal key from vault-keys.txt
UNSEAL_KEY=$(grep 'Unseal Key 1:' vault-keys.txt | awk '{print $NF}')

# Unseal
docker exec dev-vault vault operator unseal $UNSEAL_KEY
```

### Service Crash Loop

```bash
# Check logs
make logs SERVICE=dev-ledger

# Check environment variables
docker inspect dev-ledger | grep -A 20 Env

# Rebuild from scratch
make rebuild SERVICE=dev-ledger
```

---

## 📦 Docker Images

All images tagged as `sendico-dev/<service>:latest`:
- `sendico-dev/discovery:latest`
- `sendico-dev/ledger:latest`
- `sendico-dev/billing-fees:latest`
- `sendico-dev/fx-oracle:latest`
- `sendico-dev/fx-ingestor:latest`
- `sendico-dev/payments-orchestrator:latest`
- `sendico-dev/chain-gateway:latest`
- `sendico-dev/mntx-gateway:latest`
- `sendico-dev/tgsettle-gateway:latest`
- `sendico-dev/notification:latest`
- `sendico-dev/bff:latest`
- `sendico-dev/frontend:latest`

---

## 🧪 Testing Full Flow

```bash
# 1. Start everything
make up

# 2. Check all services are healthy
make status

# 3. Test discovery
curl http://localhost:9407/health

# 4. Test ledger
curl http://localhost:9401/health

# 5. Test BFF
curl http://localhost:8080/api/v1/health

# 6. Test frontend
open http://localhost:3000
```

---

## 🗑️ Cleanup

```bash
# Stop everything
make down

# Remove volumes (fresh start)
make clean

# Remove images
docker rmi $(docker images 'sendico-dev/*' -q)
```

---

## 📂 File Structure

```
sendico/
├── docker-compose.dev.yml      # All service definitions
├── .env.dev                    # Plaintext credentials
├── Makefile                    # Build commands
├── SETUP.md                    # This file
├── vault-keys.txt              # Vault keys (gitignored)
└── docker/
    └── dev/
        ├── README.md           # Detailed docs
        ├── mongo.key           # MongoDB keyfile
        ├── vault/
        │   └── config.hcl      # Vault config
        └── *.dockerfile        # Service builds
```

---

## 🆘 Getting Help

```bash
# Show all available commands
make help

# List all services
make list-services

# Check service health
make health
```

---

## 🎓 Next Steps

1. **Initialize Vault with secrets** for Chain Gateway
2. **Seed test data** into MongoDB
3. **Run integration tests**
4. **Add monitoring** (Prometheus/Grafana - optional)
5. **Document API endpoints** in each service

---

## ⚠️ Important Notes

- **Never commit `.env.dev`** - Contains credentials
- **Never commit `vault-keys.txt`** - Contains Vault keys
- **Vault is for app data only** - Not for infrastructure secrets
- **Use `dev-` prefix** for all service names to avoid conflicts
- **MongoDB keyfile** must have `400` permissions

---

## 📝 Troubleshooting Checklist

- [ ] Docker is running
- [ ] Docker Compose v2 is installed (`docker compose version`)
- [ ] `.env.dev` exists and has correct values
- [ ] Vault is initialized and unsealed (`make vault-init`)
- [ ] MongoDB replica set is initialized (`docker logs dev-mongo-init`)
- [ ] All services are healthy (`make status`)
- [ ] No port conflicts on host machine
- [ ] Proto generation succeeded (`make proto`)

---

**Ready to build? Run `make init && make up`** 🚀