Skip to main content

SmartBets.io - Complete Codebase Documentation

Welcome to the SmartBets.io Developer Documentation!

This comprehensive documentation suite is designed to help new team members understand the entire SmartBets.io codebase quickly and start contributing immediately.

🚀 Quick Start​

New to the project? Start here:

  1. ✅ QUICK_START_GUIDE.md - Get up and running in 30 minutes
  2. ✅ 01_SYSTEM_OVERVIEW.md - Understand the big picture
  3. ✅ 21_DEVELOPMENT_SETUP.md - Detailed setup instructions
  4. ✅ 31_GLOSSARY.md - Learn the terminology

📚 Documentation Structure​

This documentation is organized into the following sections:

0. Quick Start ⚡​

1. System Overview 🎯​

2. Smart Contracts (Solana Programs) ⛓️​

3. Backend Architecture 🔧​

4. Frontend Architecture 🎨​

5. Key Features 🎯​

6. Development & Deployment 🚀​

7. Advanced Topics 🔬​

8. Reference Materials 📖​

📊 Documentation Status​

🎉 All 33 documents complete (100%)!

The entire SmartBets.io codebase is now fully documented. New team members can understand the system and start contributing immediately.

🎯 Learning Path for New Developers​

Week 1: Get Started & Understand the System​

Day 1-2: Setup & Overview

  1. Follow QUICK_START_GUIDE.md to get your environment running
  2. Read 01_SYSTEM_OVERVIEW.md to understand the big picture
  3. Review 02_TECHNOLOGY_STACK.md to familiarize yourself with the tech
  4. Study 32_ARCHITECTURE_DIAGRAMS.md for visual understanding
  5. Keep 31_GLOSSARY.md open as reference

Day 3-5: Smart Contracts Deep Dive

  1. Read 03_SMART_CONTRACTS_OVERVIEW.md
  2. Deep dive into 04_USER_ACCOUNT_PROGRAM.md
  3. Review the actual code in smartbets-protocol/programs/user-account/
  4. Run smart contract tests: anchor test

Week 2: Backend & Database​

Day 1-3: Backend Architecture

  1. Read 07_BACKEND_OVERVIEW.md
  2. Explore the code in smartbets-protocol/backend/src/
  3. Understand the service layer and API routes
  4. Run backend tests: cd backend && npm test

Day 4-5: Integration & Data Flow

  1. Read 16_BETTING_FLOW.md to see how everything connects
  2. Trace a bet from UI → Backend → Blockchain
  3. Understand the reconciliation and indexing system

Week 3: Frontend & User Experience​

Day 1-3: Frontend Architecture

  1. Read 12_FRONTEND_OVERVIEW.md
  2. Explore the code in smartbets-protocol/app/src/
  3. Understand React contexts and state management
  4. Run E2E tests: cd app && npm run test:e2e

Day 4-5: Hands-On Practice

  1. Make a small UI change
  2. Place a bet through the UI and trace it through the system
  3. Review your first potential contribution area

Week 4: Contributing​

  1. Pick a small task or bug fix
  2. Make your changes following 29_CODE_CONVENTIONS.md
  3. Write tests for your changes
  4. Submit your first pull request!

📊 Documentation Status​

Current Status: 18 of 33 documents complete (55%)

Completed ✅:

  • QUICK_START_GUIDE.md
  • 01_SYSTEM_OVERVIEW.md
  • 02_TECHNOLOGY_STACK.md
  • 03_SMART_CONTRACTS_OVERVIEW.md
  • 04_USER_ACCOUNT_PROGRAM.md
  • 05_MARKET_CONTRACT_PROGRAM.md
  • 06_ORACLE_MANAGER_PROGRAM.md
  • 07_BACKEND_OVERVIEW.md
  • 08_BACKEND_SERVICES.md
  • 10_DATABASE_SCHEMA.md
  • 12_FRONTEND_OVERVIEW.md
  • 16_BETTING_FLOW.md
  • 21_DEVELOPMENT_SETUP.md
  • 22_TESTING_GUIDE.md
  • 29_CODE_CONVENTIONS.md
  • 30_TROUBLESHOOTING.md
  • 31_GLOSSARY.md
  • 32_ARCHITECTURE_DIAGRAMS.md

Remaining 📝:

  • 09_BACKEND_ROUTES_API.md - Complete API endpoint reference
  • 11_BLOCKCHAIN_INTEGRATION.md - Blockchain integration details
  • 13_FRONTEND_COMPONENTS.md - React components documentation
  • 14_FRONTEND_PAGES.md - Pages and routing
  • 15_FRONTEND_CONTEXTS_HOOKS.md - State management
  • 17_ROOM_SYSTEM.md - Room functionality
  • 18_SETTLEMENT_SYSTEM.md - Settlement process
  • 19_DEPOSIT_WITHDRAWAL.md - Fund management
  • 20_SIMULATION_SYSTEM.md - Simulation tools
  • 23_DEPLOYMENT_GUIDE.md - Deployment procedures
  • 24_DOCKER_INFRASTRUCTURE.md - Docker setup
  • 25_WEBSOCKET_REALTIME.md - Real-time system
  • 26_RECONCILIATION_INDEXING.md - Blockchain indexing
  • 27_SECURITY_AUTH.md - Security and auth
  • 28_PERFORMANCE_MONITORING.md - Performance optimization

🏗️ SmartBets.io Architecture at a Glance​

┌─────────────────────────────────────────────────────────────┐
│                    FRONTEND (Next.js 14)                    │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐   │
│  │  Pages   │  │Components│  │ Contexts │  │  Hooks   │   │
│  └──────────┘  └──────────┘  └──────────┘  └──────────┘   │
└────────────────────────┬────────────────────────────────────┘
                         │ HTTP/WebSocket
┌────────────────────────▼────────────────────────────────────┐
│              BACKEND (Express/TypeScript)                   │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐   │
│  │  Routes  │  │ Services │  │Middleware│  │ Database │   │
│  └──────────┘  └──────────┘  └──────────┘  └──────────┘   │
└────────────────────────┬────────────────────────────────────┘
                         │ Solana RPC
┌────────────────────────▼────────────────────────────────────┐
│              SOLANA BLOCKCHAIN (Programs)                   │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐     │
│  │UserAccount   │  │MarketContract│  │OracleManager │     │
│  │  Program     │  │   Program    │  │   Program    │     │
│  └──────────────┘  └──────────────┘  └──────────────┘     │
└─────────────────────────────────────────────────────────────┘

🔑 Key Concepts​

Betting Exchange Model​

SmartBets.io is a betting exchange, not a traditional sportsbook. Users bet against each other, not against the house. The platform facilitates matching between:

  • Backers - Users betting FOR an outcome
  • Layers - Users betting AGAINST an outcome

FIFO Matching Engine​

Orders are matched using First-In-First-Out (FIFO) price-time priority:

  1. Best price gets matched first
  2. Among same price, earliest order gets matched first
  3. All matching happens on-chain for transparency

Liability-Based Escrow​

User funds are managed through a sophisticated liability system:

  • Deposits - Total funds deposited
  • Liabilities - Funds locked for open bets
  • Payoffs - Winnings from settled bets
  • Withdrawable = Deposits + Payoffs - Liabilities - Withdrawals

Dual Oracle System​

Match results are verified through two sources:

  1. Switchboard Oracle - Decentralized oracle network
  2. Centralized Oracle - Backup authority for edge cases

Room System​

Private betting rooms where:

  • Bookmakers create rooms and provide liquidity
  • Punters join rooms and place bets
  • Custom odds and limits per room
  • RFQ (Request for Quote) system for custom bets

📖 How to Use This Documentation​

For Frontend Developers​

Focus on: 12-15, 16, 17, 21, 27

For Backend Developers​

Focus on: 07-11, 16-20, 21, 26, 27

For Smart Contract Developers​

Focus on: 03-06, 11, 16, 18, 21

For DevOps Engineers​

Focus on: 21, 23, 24, 28

For QA Engineers​

Focus on: 16-20, 22, 30

🤝 Contributing​

When you're ready to contribute:

  1. Read 29_CODE_CONVENTIONS.md for coding standards
  2. Set up your environment using 21_DEVELOPMENT_SETUP.md
  3. Run tests using 22_TESTING_GUIDE.md
  4. Check 30_TROUBLESHOOTING.md if you encounter issues

📞 Getting Help​

If you have questions after reading the documentation:

  1. Check 30_TROUBLESHOOTING.md for common issues
  2. Review 31_GLOSSARY.md for terminology
  3. Ask your team lead or senior developers
  4. Refer to the actual code - it's well-commented!

🎓 Learning Path​

Week 1: Foundation

  • System overview and architecture
  • Technology stack familiarization
  • Development environment setup

Week 2: Smart Contracts

  • Understand Solana and Anchor framework
  • Study all three programs in detail
  • Review test files to see programs in action

Week 3: Backend

  • Backend architecture and services
  • API endpoints and database schema
  • Blockchain integration patterns

Week 4: Frontend

  • Frontend architecture and components
  • State management and routing
  • User flows and interactions

Week 5: Integration

  • End-to-end betting flow
  • Room system and settlement
  • Real-time features

Week 6: Advanced

  • Performance optimization
  • Security considerations
  • Deployment and monitoring

📝 Documentation Maintenance​

This documentation should be updated when:

  • New features are added
  • Architecture changes are made
  • APIs are modified
  • New patterns are introduced

Last Updated: October 17, 2025 Version: 1.0.0 Maintainer: SmartBets.io Development Team

Ready to dive in? Start with 01_SYSTEM_OVERVIEW.md! 🚀