Backend Architecture
Service Overview
BattlesBit backend is composed of multiple services that communicate via NATS JetStream.
┌─────────────────────────────────────────────────────────────────┐
│ Client Apps │
│ (Web, Mobile, Desktop) │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ GraphQL API │
│ (cmd/web service) │
└─────────────────────────────────────────────────────────────────┘
│
┌───────────────────────┼───────────────────────┐
│ │ │
▼ ▼ ▼
┌───────────────┐ ┌───────────────┐ ┌───────────────┐
│ PostgreSQL │ │ NATS │ │ Redis │
│ (Ent ORM) │ │ JetStream │ │ (Cache) │
└───────────────┘ └───────────────┘ └───────────────┘
│
┌───────────┬───────────┼───────────┬───────────┐
│ │ │ │ │
▼ ▼ ▼ ▼ ▼
┌───────────┐ ┌───────────┐ ┌───────────┐ ┌───────────┐ ┌───────────┐
│ Arena │ │ Market │ │ Matcher │ │Achievement│ │ Notify │
│ Worker │ │ Service │ │ Service │ │ Worker │ │ Worker │
└───────────┘ └───────────┘ └───────────┘ └───────────┘ └───────────┘Services
Web Service (cmd/web)
Main GraphQL API server.
Responsibilities:
- User authentication (JWT)
- GraphQL queries and mutations
- Request validation
- Authorization
Key Dependencies:
- All use cases
- Ent client
- NATS (for publishing)
Arena Service (cmd/arena)
Position calculation worker.
Responsibilities:
- Process new positions
- Real-time PnL calculation
- SL/TP monitoring
- Liquidation checks
- Position closure
NATS Streams:
POSITIONS(subjects:positions.new,positions.close,positions.cancel)
Market Service (cmd/market)
Market data streaming.
Responsibilities:
- Binance WebSocket connection
- Price broadcasting
- Asset cache management
Matcher Service (cmd/matcher)
Matchmaking worker.
Responsibilities:
- Process join requests
- Queue management per game
- Match creation when thresholds met
- Close expired matches
NATS Streams:
MATCHMAKING(subject:matchmaking.add)
Achievement Service (cmd/achievement)
Achievement processing.
Responsibilities:
- Process achievement events
- Evaluate rules
- Grant achievements
Workflow Engine: Temporal
Notification Service (cmd/notifications)
Notification delivery.
Responsibilities:
- Email sending (OTP)
- Push notifications (Firebase)
- Process notification queue
NATS Streams:
NOTIFICATIONS(subject:notifications.otp_email)
Directory Structure
service/
├── cmd/ # Service entry points
│ ├── web.go
│ ├── arena.go
│ ├── market.go
│ ├── matcher.go
│ ├── achievement.go
│ └── notifications.go
│
├── internal/
│ ├── adapters/ # External interfaces
│ │ ├── auth/ # Authentication
│ │ ├── cache/ # Caching
│ │ ├── clients/ # External clients
│ │ │ ├── email/
│ │ │ ├── firebase/
│ │ │ ├── market/ # Binance client
│ │ │ ├── nats/
│ │ │ ├── s3/
│ │ │ ├── solana/
│ │ │ └── temporal/
│ │ ├── controllers/ # HTTP handlers
│ │ │ ├── http/
│ │ │ ├── arena/
│ │ │ ├── market/
│ │ │ ├── matcher/
│ │ │ └── notifications/
│ │ ├── hdwallet/ # HD wallet impl
│ │ └── jwt/ # JWT handling
│ │
│ ├── application/
│ │ ├── caches/ # GraphQL caches
│ │ └── usecases/ # Business logic
│ │
│ ├── domain/
│ │ ├── entities/ # Domain types
│ │ └── services/ # Service interfaces
│ │
│ ├── ent/ # Database models (generated)
│ │ └── schema/ # Schema definitions
│ │
│ ├── graph/ # GraphQL (generated)
│ │ ├── schemas/ # .graphqls files
│ │ └── resolvers/ # Resolver impls
│ │
│ └── config/ # Configuration
│
└── pkg/ # Shared utilities
├── errors/
├── fields/
└── queue/Data Flow Examples
Opening a Position
1. Client → GraphQL mutation: createPosition
2. Web service → GameUseCase.CreatePosition()
3. Validate: participant, balance, max positions
4. Create position (status: pending)
5. Publish to NATS: positions.new
6. Arena worker receives message
7. Subscribe to market price updates
8. Wait for entry condition (market/limit)
9. Update position status: open
10. Loop: calculate PnL, check SL/TP/liquidation
11. On close: update v_balance, notifyJoining a Match
1. Client → GraphQL mutation: joinGame
2. Web service → MatchMakingUseCase.AddParticipant()
3. Validate: balance >= entry_fee
4. Publish to NATS: matchmaking.add
5. Matcher receives message
6. Add to game-specific queue
7. Check if min_players reached
8. If yes: GameUseCase.Join()
- Withdraw entry fees
- Create match
- Create participants
- Notify usersMatch Settlement
1. Matcher runs ProcessCloseMatches() periodically
2. Query: status IN (open, pending) AND end_time <= now
3. For each match: TryCloseMatch()
- Update status: closed
- Notify participants
- Send achievement events
- CalculateMatchRewards()
- Rank by v_balance
- Winner: money + cup + XP + items
- Losers: -cup + XPTechnology Decisions
| Component | Technology | Reason |
|---|---|---|
| API | GraphQL | Flexible queries, real-time subscriptions |
| Database | PostgreSQL | ACID, relations, JSON support |
| ORM | Ent | Type-safe, GraphQL integration |
| Messaging | NATS JetStream | Persistence, replay, exactly-once |
| Workflows | Temporal | Long-running processes, retries |
| Blockchain | Solana | Fast, low fees |
| Market Data | Binance | Reliable, WebSocket support |
Configuration
Environment-based configuration via Viper.
Key config areas:
- Database connection
- NATS connection
- Redis connection
- Binance API URLs
- Solana RPC endpoints
- JWT secrets
- Firebase credentials
- Email SMTP settings
Last updated on