GitiNext Developer Onboarding

Complete guide for new Golang developers — backend system, Docker Swarm DevOps, technical workspace patterns, system design, and launch readiness for a crypto exchange wallet on Telegram.

Last Updated: 2025-02-12

System Overview
Live Docker Swarm Stack
Service-by-Service Deep Dive
Design Patterns & System Design
Development Progress vs Launch
Services Left for Full Crypto Exchange Wallet
Local Development & DevOps
Key Files & Where to Look
Links to Existing Docs

1. System Overview

Product Context

GitiNext is a crypto exchange wallet on Telegram delivered via:

Telegram Mini App (TMA) — Web-based UI for wallet, market, swap, deposit, withdrawal
Telegram Bot — In-chat commands, notifications, webhook mode for scale

Tech Stack

Layer	Technology
Language	Go 1.22+
Orchestration	Docker Swarm
Reverse Proxy	Traefik (HTTPS, Let’s Encrypt)
Database	PostgreSQL 18
Cache	Redis 7
Messaging	NATS (JetStream), RabbitMQ
Object Storage	MinIO (S3-compatible)
Secrets	HashiCorp Vault (optional)

Architecture Diagram

flowchart TB
    subgraph clients [Clients]
        TMA[Telegram Mini App]
        Bot[Telegram Bot]
        Admin[Admin Panel]
    end

    subgraph traefik [Traefik]
        T[api.nextgiti.cloud]
        B[api.gitinext.com/bot]
        D[docs.nextgiti.cloud]
    end

    subgraph entry [Entry Points]
        Gateway[Gateway :8080]
        TelegramBot[Telegram Bot :8080]
    end

    subgraph services [Core Services]
        Wallet[Wallet :7080/:9092]
        Account[Account :8083/:9093]
        Market[Market :7081]
        Payment[Payment :7085]
        Swap[Swap :7088]
        Withdrawal[Withdrawal :7086]
        Voucher[Voucher :7087]
        Ledger[Ledger :8080/:9090]
        Storage[Storage :8084]
    end

    subgraph watchers [Blockchain Watchers]
        WTON[watcher-ton]
        WTRON[watcher-tron]
        WETH[watcher-eth]
        WBNB[watcher-bnb]
        WBTC[watcher-btc]
    end

    subgraph infra [Shared Infrastructure]
        PG[(PostgreSQL)]
        Redis[(Redis)]
        NATS[NATS]
        RabbitMQ[RabbitMQ]
        MinIO[MinIO]
        Vault[Vault]
    end

    TMA --> T
    Bot --> B
    Admin --> T
    T --> Gateway
    B --> TelegramBot
    D --> DocsService[docs :8000]

    Gateway --> Wallet
    Gateway --> Account
    Gateway --> Market
    Gateway --> Payment
    Gateway --> Swap
    Gateway --> Withdrawal
    Gateway --> Voucher
    Gateway --> Ledger
    Gateway --> Storage

    TelegramBot --> Wallet
    TelegramBot --> Account
    TelegramBot --> Payment
    TelegramBot --> Withdrawal
    TelegramBot --> Voucher

    Wallet --> PG
    Wallet --> Redis
    Account --> PG
    Account --> Redis
    Market --> PG
    Market --> Redis
    Market --> MinIO
    Payment --> PG
    Payment --> RabbitMQ
    Swap --> PG
    Swap --> Redis
    Withdrawal --> PG
    Voucher --> PG
    Ledger --> PG
    Ledger --> NATS
    Storage --> PG
    Storage --> MinIO

    WTON --> PG
    WTON --> RabbitMQ
    WTRON --> PG
    WTRON --> RabbitMQ
    WETH --> PG
    WETH --> RabbitMQ
    WBNB --> PG
    WBNB --> RabbitMQ
    WBTC --> PG
    WBTC --> RabbitMQ

2. Live Docker Swarm Stack

Source of truth: docker-compose.swarm.yml

Service Categories

Category	Services	Purpose
Infrastructure	postgres, redis, nats, rabbitmq, minio, vault	Data, cache, messaging, storage, secrets
Entry points	gateway (2 replicas), telegrambot	REST API + bot webhook
Core business	wallet (2), account (2), market (2), payment (1), swap (2), withdrawal (2), voucher (2), ledger (2), storage (2)	Wallet, identity, prices, fiat, swaps, crypto withdraw, vouchers, accounting, files
Blockchain	watcher-ton, watcher-tron, watcher-eth, watcher-bnb, watcher-btc	Deposit detection per chain
Supporting	docs (2), swagger-ui (1), migrator (1)	Documentation, API specs, DB migrations

Networks

internal (gitinext_net) — Service-to-service communication
traefik-public — External routing via Traefik

Secrets

vault_role_id — Vault AppRole (external Docker secret)
vault_secret_id — Vault AppRole (external Docker secret)

Key URLs (Traefik Labels)

URL	Service
`https://api.nextgiti.cloud`	Gateway
`https://api.gitinext.com` (PathPrefix `/bot/webhook`)	Telegram Bot
`https://docs.nextgiti.cloud`	Docs
`https://storage.nextgiti.cloud`	Storage
`https://cdn.nextgiti.cloud`	MinIO S3 API
`https://minio.nextgiti.cloud`	MinIO Console
`https://rabbit.nextgiti.cloud`	RabbitMQ Management
`https://vault.nextgiti.cloud`	Vault UI (optional)

3. Service-by-Service Deep Dive

Gateway

Attribute	Value
Image	`registry.nextgiti.cloud/gateway:latest`
Ports	HTTP 8080
Replicas	2
Responsibilities	REST API entry point, JWT auth, rate limiting, CORS, proxy to wallet/market/account/payment/withdrawal/voucher/storage/ledger
Dependencies	Redis, Postgres (card verification), all backend services
Key env	`JWT_SECRET`, `ACCOUNT_JWT_SECRET`, `TELEGRAM_BOT_TOKEN`, `*_SERVICE_URL`
Files	`services/gateway/`

Wallet

Attribute	Value
Image	`registry.nextgiti.cloud/wallet:latest`
Ports	HTTP 7080, gRPC 9092
Replicas	2
Responsibilities	HD wallet generation (TON/TRON/ETH/BSC/BTC), balance queries, deposit addresses, sweep system, Trust Wallet Core (optional)
Dependencies	Postgres, Redis, RPC endpoints (QuickNode, Ankr, etc.), Vault (optional)
Key env	`WALLET_ENC_KEY`, `_RPC_ENDPOINT`, `ENABLE_TWC_PLUGIN`, `VAULT_`
Files	`services/wallet/`

Account

Attribute	Value
Image	`registry.nextgiti.cloud/account:latest`
Ports	HTTP 8083, gRPC 9093
Replicas	2
Responsibilities	User management, Telegram auth, phone verification (SMS), identity verification (UID API), card verification, level-two verification
Dependencies	Postgres, Redis, Storage (identity images), SMS provider (SMSIR)
Key env	`JWT_SECRET`, `ACCOUNT_JWT_SECRET`, `SMSIR_`, `UID_API_`
Files	`services/account/`

Payment

Attribute	Value
Image	`registry.nextgiti.cloud/payment:latest`
Ports	HTTP 7085
Replicas	1
Responsibilities	PayStar integration (IRT deposits/withdrawals), card-to-card, bank statement sync
Dependencies	Postgres, Redis, RabbitMQ
Key env	`PAYSTAR_*`, `RABBITMQ_URL`
Files	`services/payment/`

Swap

Attribute	Value
Image	`registry.nextgiti.cloud/swap:latest`
Ports	HTTP 7088, gRPC 9094
Replicas	2
Responsibilities	Internal asset swaps, fee routing (system/liquidity/treasury), rate aggregation (Nobitex, KuCoin, CoinGecko)
Dependencies	Postgres, Redis
Key env	`NOBITEX_`, `KUCOIN_`, `SWAP_FEE_*_PERCENT`
Files	`services/swap/`

Withdrawal

Attribute	Value
Image	`registry.nextgiti.cloud/withdrawal:latest`
Ports	HTTP 7086
Replicas	2
Responsibilities	Crypto withdrawals via hot wallets, Exonyx integration, TWC signing
Dependencies	Postgres, Redis, Wallet (gRPC), Telegram Bot (notifications), RPC endpoints
Key env	`WITHDRAWAL_HOT_WALLET_ENCRYPTION_KEY`, `EXONYX_`, `WITHDRAWAL_BLOCKCHAIN_`
Files	`services/withdrawal/`

Market

Attribute	Value
Image	`registry.nextgiti.cloud/market:latest`
Ports	HTTP 7081, gRPC 9092
Replicas	2
Responsibilities	Asset prices, KuCoin API, Nobitex, chart data
Dependencies	Postgres, Redis, MinIO
Key env	`KUCOIN_`, `NOBITEX_`, `MINIO_*`
Files	`services/market/`

Watchers (TON, TRON, ETH, BNB, BTC)

Attribute	Value
Images	`registry.nextgiti.cloud/watcher-{ton,tron,eth,bnb,btc}:latest`
Replicas	1 each
Responsibilities	Block polling, deposit detection, cursor tracking, RabbitMQ events for notifications
Dependencies	Postgres, Redis, RabbitMQ, RPC providers

Telegram Bot

Attribute	Value
Image	`registry.nextgiti.cloud/telegrambot:latest`
Ports	HTTP 8080
Replicas	1
Responsibilities	Bot commands, webhook handler, TMA integration, notifications from RabbitMQ
Dependencies	Redis, Postgres, Account, Wallet, Payment, Withdrawal, Voucher, Storage
Key env	`BOT_TOKEN`, `BOT_WEBHOOK_URL`, `RABBITMQ_URL`
Files	`services/telegrambot/`

Ledger

Attribute	Value
Image	`registry.nextgiti.cloud/ledger:latest`
Ports	HTTP 8080, gRPC 9090
Replicas	2
Responsibilities	Double-entry general ledger, accounting, NATS events
Dependencies	Postgres, NATS
Files	`services/ledger/`

Storage

Attribute	Value
Image	`registry.nextgiti.cloud/storage:latest`
Ports	HTTP 8084
Replicas	2
Responsibilities	File uploads, MinIO integration, CDN URLs
Dependencies	Postgres, Redis, MinIO
Files	`services/storage/`

Voucher

Attribute	Value
Image	`registry.nextgiti.cloud/voucher:latest`
Ports	HTTP 7087
Replicas	2
Responsibilities	PS Voucher, HOT Voucher, UTOPIA Voucher integrations
Dependencies	Postgres
Files	`services/voucher/`

4. Design Patterns & System Design

From .cursor/rules/go-chain-project.mdc:

Interfaces (Immutable)

type Deriver interface {
    FromMnemonic(m string, path string, curve Curve) (PrivKey, PubKey, error)
}
type Signer interface {
    Address(pub PubKey, chain Chain) (string, error)
    SignTx(chain Chain, priv PrivKey, payload []byte) ([]byte, error)
}

Implementations: tonSigner (pure-Go), tronSigner (pure-Go), optional twcSigner (build tag twc)
Do not change without review

Idempotency

Idempotency keys on deposit/withdraw workflows
Sagas + Outbox pattern for external effects
No duplicate processing of same request

Concurrency

No unbounded concurrency: worker pools or p-limit equivalents
No per-request DB/Redis dials; use connection pools (singletons)

Resilience

Backoff + Jitter on all external calls
Circuit breaker where applicable
No unbounded timers; use context + abort

Observability

Prometheus metrics on all services
OTEL traces (planned)
Graceful shutdown with queue drain

Security

BIP39/32 derivation, ed25519 (TON), secp256k1 (TRON)
No raw private keys in logs; redact secrets
Structured logging only

Monorepo Layout

/cmd
  /gateway
  /watcher
  /wallet
  ...
/internal
  /config
  /db
  /events
  /keys
  ...
/packages
  /blockchain
  /rpc
  /vault
  /metrics
  ...
/shared-schema
  /proto
  ...
/migrations

5. Development Progress vs Launch

Completed

Component	Status
All 5 watchers (TON, TRON, ETH, BSC, BTC)	Deployed; deposit detection working
Wallet	HD generation, TON/TRON/ETH/BSC/BTC, TWC optional, sweep system
Payment	PayStar integration (IRT deposits/withdrawals)
Swap	Nobitex, KuCoin, fee routing, liquidity management
Withdrawal	Exonyx integration, crypto withdrawal processing
Account	Auth, identity (UID), card verification, level-two verification
Ledger	Double-entry general ledger, NATS
Storage	MinIO, file uploads
Voucher	PS, HOT, UTOPIA integrations

Partial / Known Issues

Issue	Service	Action
PayStar token/refresh errors	payment	Update PAYSTAR_* credentials; refresh token
TON watcher RPC 429 rate limits	watcher-ton	Add/rotate TON RPC providers
Wallet ¹⁄₂ replicas	wallet	Add node or reduce resource request
Ledger image missing	ledger	Build and push ledger image

Remaining (from remaining-tasks.md)

Tier A: EIP-1559 gas safety, risk/AML engine, idempotency keys, commit SHA tracking
Blockchain: BTC UTXO transaction builder (sweep/withdrawal execution)
Product: Support service, KYC service, WebSocket server, admin backend migration
Testing: Smoke tests, rollback drill, alerting coverage

6. Services Left for Full Crypto Exchange Wallet

Gap	Service / Feature	Status	Priority
Tier A hardening	Gas safety, risk engine, idempotency	Not done	P0
BTC execution	UTXO tx builder	Deposit OK; sweep/withdraw pending	P0
Support	Support service	Not created	P1
KYC	KYC service	Partially in account	P1
Realtime	WebSocket server	Not created	P2
Admin	Admin panel backend	Still Node.js	P2
Market enhancements	CoinGecko, Nobitex clients	Structure exists	P2

7. Local Development & DevOps

Quick Start

# 1. Clone and setup
git clone https://github.com/GITINEXT/gitinext-golang.git
cd gitinext-golang

# 2. Environment
cp .env.production.template .env
# Edit .env with your config

# 3. Dev tools
make dev-setup
make work-sync

# 4. Proto generation
make gen-proto

Run Locally

make run-gateway
make run-wallet
make run-watcher-ton
make run-telegrambot
# etc.

Docker

File	Purpose
`docker-compose.yaml`	Local development
`docker-compose.swarm.yml`	Production Swarm

Build & Deploy

# Build all images
make docker-build-all

# Push to registry
make docker-push-all

# Deploy stack
docker stack deploy -c docker-compose.swarm.yml gitinext-golang --with-registry-auth

# Production deploy script
./scripts/deploy-production.sh

Logs

make aux-logs SVC=gateway
make aux-logs SVC=wallet
docker service logs gitinext-golang_gateway --tail 100 -f

Useful Commands

# Service status
docker service ls | grep gitinext-golang

# Scale service
docker service scale gitinext-golang_wallet=3

# Update service
docker service update --force gitinext-golang_wallet

8. Key Files & Where to Look

Purpose	Location
Swarm stack	`docker-compose.swarm.yml`
Services	`services/{gateway,wallet,account,payment,swap,withdrawal,telegrambot,watcher,...}`
Shared code	`packages/{blockchain,rpc,vault,metrics,...}`
Protobuf	`shared-schema/`
Migrations	`services/*/migrations/`
Config	`config/config.yaml`, `.env`, `.env.production.template`
Docs	`docs/`, `docs/portal/`, `docs/architecture/`
Scripts	`scripts/` (deploy, vault, migrator)

9. Links to Existing Docs

Doc	Purpose
Onboarding Portal	Quick entry point
Architecture Portal	High-level topology
Microservices	Service catalog
Production Overview	Production readiness definition
Remaining Tasks	Consolidated checklist
Blockchain Production Status	Watcher/deposit/sweep status
Production Ready Checklist	Tier A/B/C hardening
Current Status Summary	API/service status
Docker and Logs Review	Log review guide
Guides	Deployment, Wallet, Signer, Vault

End of Developer Onboarding

GitiNext Developer Onboarding

Table of Contents

1. System Overview

Product Context

Tech Stack

Architecture Diagram

2. Live Docker Swarm Stack

Service Categories

Networks

Secrets

Key URLs (Traefik Labels)

3. Service-by-Service Deep Dive

Gateway

Wallet

Account

Payment

Swap

Withdrawal

Market

Watchers (TON, TRON, ETH, BNB, BTC)

Telegram Bot

Ledger

Storage

Voucher

4. Design Patterns & System Design

Interfaces (Immutable)

Idempotency

Concurrency

Resilience

Observability

Security

Monorepo Layout

5. Development Progress vs Launch

Completed

Partial / Known Issues

Remaining (from remaining-tasks.md)

6. Services Left for Full Crypto Exchange Wallet

7. Local Development & DevOps

Quick Start

Run Locally

Docker

Build & Deploy

Logs

Useful Commands

8. Key Files & Where to Look

9. Links to Existing Docs