═══════════════════════════════════════════════════════════════════════════════ RAZARZ MIGRATION - QUICK START GUIDE ═══════════════════════════════════════════════════════════════════════════════

🎯 PROJECT OVERVIEW ═══════════════════════════════════════════════════════════════════════════════

Goal: Migrate complete Node.js backend (gitibot-back-main/) to Go microservices

What We’re Building: ✓ 10+ microservices (wallet, watcher, market, transaction, payment, etc.) ✓ 40+ REST API endpoints for TMA frontend ✓ 7 external API integrations (Exonyx, Paystar, FinnoTech, vouchers, prices) ✓ Complete blockchain operations (TON, TRON, BNB) ✓ Admin panel backend ✓ Real-time WebSocket updates

Timeline: 8 weeks (6 phases)

═══════════════════════════════════════════════════════════════════════════════ 📁 PROJECT STRUCTURE ═══════════════════════════════════════════════════════════════════════════════

gitinext-golang/ ├── MIGRATION-PLAN.txt ← DETAILED TASK BREAKDOWN (read this!) ├── PROGRESS.txt ← DAILY PROGRESS TRACKING (update daily) ├── QUICK-START.txt ← THIS FILE │ ├── services/ ← Go Microservices │ ├── gateway/ [PARTIAL] API gateway, HTTP routes │ ├── wallet/ [BROKEN] Signers placeholder │ ├── watcher/ [EMPTY] Just stubs │ ├── account/ [BASIC] User management │ ├── storage/ [WORKING] MinIO integration │ ├── telegrambot/ [BASIC] Bot structure │ ├── market/ [TODO] Create new │ ├── transaction/ [TODO] Create new │ ├── payment/ [TODO] Create new │ ├── voucher/ [TODO] Create new │ ├── blockchain/ [TODO] Create new │ ├── support/ [TODO] Create new │ └── kyc/ [TODO] Create new │ ├── packages/ ← Shared utilities │ ├── logger/ Structured logging │ ├── metrics/ Prometheus metrics │ ├── database/ Database helpers │ ├── errors/ Error handling │ └── … (more utilities) │ ├── shared-schema/ ← Protobuf definitions │ ├── proto/ .proto files │ └── proto-gen/go/ Generated Go code │ └── gitibot-back-main/ ← Node.js Reference (DO NOT MODIFY) ├── services/ Business logic to port ├── models/ Database models to port ├── api/controllers/ API endpoints to port └── … (complete working system)

gitinext-telegram/ ← TMA Frontend (separate repo) └── APIINTEGRATION*.md API requirements

═══════════════════════════════════════════════════════════════════════════════ 🚀 HOW TO START ═══════════════════════════════════════════════════════════════════════════════

STEP 1: Read Documentation (30 minutes) 1. Read MIGRATION-PLAN.txt (full task details) 2. Skim Node.js README: gitibot-back-main/README.md 3. Check TMA API requirements: gitinext-telegram/API_INTEGRATION_QUICK_REFERENCE.md

STEP 2: Set Up Environment cd /opt/cryptotel/enterprise/stacks/gitinext/gitinext-golang

# Check Go version go version # Should be 1.25.0+

# Check workspace cat go.work # Verify all services listed

STEP 3: Start First Task (Phase 0, Task 0.1: Fix TON Signer)

# 1. Read task details grep -A 100 “TASK 0.1” MIGRATION-PLAN.txt

# 2. Update progress tracker vim PROGRESS.txt # Mark task as [▶] In Progress

# 3. Navigate to file cd services/wallet/internal/wallet/service/signer/ vim ton_tron_placeholders.go

# 4. Follow implementation steps in MIGRATION-PLAN.txt

# 5. Test your changes go test ./…

# 6. Update progress tracker vim ../../../../PROGRESS.txt # Mark task as [✓] Complete

═══════════════════════════════════════════════════════════════════════════════ 📋 PHASE 0 TASKS (WEEK 1 - START HERE!) ═══════════════════════════════════════════════════════════════════════════════

These are CRITICAL - everything else depends on these:

[ ] 0.1 - Fix TON Signer 4-6 hours 🔴 CRITICAL File: services/wallet/internal/wallet/service/signer/ton_tron_placeholders.go What: Replace placeholder with real tonutils-go implementation Why: Can’t create TON wallets without this

[ ] 0.2 - Fix TRON Signer 4-6 hours 🔴 CRITICAL File: services/wallet/internal/wallet/service/signer/ton_tron_placeholders.go What: Replace placeholder with real gotron-sdk implementation Why: Can’t create TRON wallets without this

[ ] 0.3 - Complete TON Watcher 8-10 hours 🔴 CRITICAL Files: services/watcher/internal/watcher/chains/ton/watcher.go services/watcher/internal/watcher/chains/ton/client.go What: Implement RPC client, block fetching, deposit detection Why: Can’t detect TON deposits without this

[ ] 0.4 - Complete TRON Watcher 8-10 hours 🔴 CRITICAL Files: services/watcher/internal/watcher/chains/tron/watcher.go services/watcher/internal/watcher/chains/tron/client.go (create) What: Implement TronGrid client, TRC20 event parsing Why: Can’t detect TRON/USDT deposits without this

[ ] 0.5 - Create Balance Service 4-6 hours 🔴 HIGH Files: services/wallet/internal/balance/ (create new directory) What: RPC clients for balance queries, Redis caching Why: TMA needs to display wallet balances

═══════════════════════════════════════════════════════════════════════════════ 🔧 DEVELOPMENT WORKFLOW ═══════════════════════════════════════════════════════════════════════════════

For Each Task:

READ
- Open MIGRATION-PLAN.txt
- Find your task (e.g., “TASK 0.1”)
- Read implementation steps
- Check reference Node.js code location
UPDATE PROGRESS
- Open PROGRESS.txt
- Mark task as [▶] In Progress
- Add entry to daily log
CODE
- Follow implementation steps from MIGRATION-PLAN.txt
- Reference Node.js code when needed
- Add inline comments explaining WHY
- Write unit tests
TEST
- Run: go test ./…
- Check all tests pass
- Test manually if needed
UPDATE PROGRESS
- Mark task as [✓] Complete
- Update progress percentage
- Update daily log with:
```
   - Time spent
   - What was accomplished
   - Any blockers encountered
```
COMMIT
- Git commit with descriptive message
- Reference task number (e.g., “Task 0.1: Implement TON signer”)

═══════════════════════════════════════════════════════════════════════════════ 🛠️ USEFUL COMMANDS ═══════════════════════════════════════════════════════════════════════════════

Build specific service

cd services/wallet && go build ./cmd/server

Run specific service

cd services/wallet && go run ./cmd/server/main.go

Test specific service

cd services/wallet && go test ./…

Test with verbose output

go test -v ./…

Build all services

make build # (if Makefile configured)

Run docker compose (when ready)

docker-compose up -d

View logs

docker-compose logs -f wallet

Check progress

cat PROGRESS.txt

View specific task details

grep -A 50 “TASK 0.1” MIGRATION-PLAN.txt

═══════════════════════════════════════════════════════════════════════════════ 📚 KEY REFERENCES ═══════════════════════════════════════════════════════════════════════════════

Node.js Codebase (Reference Implementation): - Services: gitibot-back-main/services/ - Models: gitibot-back-main/models/ - Controllers: gitibot-back-main/api/controllers/ - README: gitibot-back-main/README.md

Frontend Requirements: - API List: gitinext-telegram/API_INTEGRATION_QUICK_REFERENCE.md - Roadmap: gitinext-telegram/API_INTEGRATION_ROADMAP.md

Go Best Practices: - System Rules: .cursor/rules/ (project structure & patterns) - Packages: gitinext-golang/packages/ (shared utilities)

External APIs: - Exonyx Blockchain: https://api.exonyxco.com/api/v1/reseller - TronGrid: https://api.trongrid.io - TON RPC: https://toncenter.com/api/v2/jsonRPC - CoinGecko: https://api.coingecko.com/api/v3/ - Nobitex (Toman): https://api.nobitex.ir/

Libraries: - TON: github.com/xssnick/tonutils-go - TRON: github.com/fbsobreira/gotron-sdk - Ethereum (crypto): github.com/ethereum/go-ethereum

═══════════════════════════════════════════════════════════════════════════════ ⚠️ IMPORTANT NOTES ═══════════════════════════════════════════════════════════════════════════════

DO: ✓ Follow implementation steps in MIGRATION-PLAN.txt exactly ✓ Reference Node.js code for business logic understanding ✓ Write unit tests for all new code ✓ Update PROGRESS.txt daily ✓ Add inline comments explaining WHY, not just WHAT ✓ Use shared packages (logger, metrics, database, etc.) ✓ Follow Go best practices (error handling, context, etc.) ✓ Test each service independently before integration

DON’T: ✗ Modify Node.js code (gitibot-back-main/) - it’s reference only ✗ Skip tests - they prevent regressions ✗ Skip progress updates - we need to track velocity ✗ Hardcode values - use config/environment variables ✗ Ignore errors - handle them properly ✗ Copy-paste without understanding - port logic, don’t translate ✗ Start Phase 2 before Phase 0 is complete - dependencies matter!

═══════════════════════════════════════════════════════════════════════════════ 🆘 TROUBLESHOOTING ═══════════════════════════════════════════════════════════════════════════════

Problem: “package not found” Solution: Run: go mod tidy && go mod download

Problem: “import cycle” Solution: Restructure to avoid circular dependencies, use interfaces

Problem: Task unclear Solution: Check MIGRATION-PLAN.txt for detailed steps, or check Node.js reference

Problem: Test failures Solution: Read test output carefully, add debug logging, check Node.js behavior

Problem: Can’t find Node.js reference Solution: Use grep: grep -r “functionName” gitibot-back-main/

═══════════════════════════════════════════════════════════════════════════════ ✅ READY TO START? ═══════════════════════════════════════════════════════════════════════════════

Your first task is: Fix TON Signer (Task 0.1)

Steps: 1. Read: grep -A 100 “TASK 0.1” MIGRATION-PLAN.txt 2. Open: vim services/wallet/internal/wallet/service/signer/ton_tron_placeholders.go 3. Mark in progress: vim PROGRESS.txt (change [ ] to [▶]) 4. Implement following MIGRATION-PLAN.txt steps 5. Test: cd services/wallet && go test ./… 6. Mark complete: vim PROGRESS.txt (change [▶] to [✓]) 7. Commit: git commit -m “Task 0.1: Implement TON signer with tonutils-go”

Estimated time: 4-6 hours

Good luck! 🚀

═══════════════════════════════════════════════════════════════════════════════ END OF QUICK START GUIDE ═══════════════════════════════════════════════════════════════════════════════