FortuneBet Backend

FortuneBet Backend is the server-side application that powers the FortuneBet system. It fetches and processes odds and results for various sports (e.g. football, basketball, ice hockey), manages upcoming events, evaluates bet outcomes, as well as managing the different branches and companies that will be using the system.

Table of Contents

• Installation
• Environment Configuration
• Running the Application
• Database Management
• Testing and Code Quality
• API Documentation
• Project Structure
• Core Services Overview
• Roles and Access Control
• Code Organization Guidelines
• Further Details

Installation

Before running the application, ensure you have the following installed:

• Go (1.20+ recommended)
• Docker
• Air — for live reloading during development
• SQLC
• Migrate
• Swag

Clone the repository:

git clone https://github.com/your-org/fortunebet-backend.git
cd fortunebet-backend

Environment Configuration

Create a .env file in the root directory. This file is critical for running the application as it contains database credentials, secret keys, third-party integrations, and configuration flags.

Sample variables you might include:

ENV=development
PORT=8080
DB_URL=postgresql://root:secret@localhost:5422/gh?sslmode=disable
REFRESH_EXPIRY=
JWT_KEY=
ACCESS_EXPIRY=
LOG_LEVEL=debug
AFRO_SMS_API_KEY=
AFRO_SMS_SENDER_NAME=
AFRO_SMS_RECEIVER_PHONE_NUMBER=
BET365_TOKEN=
POPOK_CLIENT_ID=
POPOK_SECRET_KEY=
POPOK_BASE_URL=
POPOK_CALLBACK_URL=

Running the Application

To run the application:

make run

To start the server with live reload (using air):

make air

To build the binary:

make build

Database Management

Start the database using Docker Compose:

make db-up

Stop it:

make db-down

Create a new migration:

make migrations/new name=add_new_table

Apply all pending migrations:

make migrations/up

Testing and Code Quality

Run all tests:

make test

Generate a coverage report:

make coverage

API Documentation

Generate Swagger docs:

make swagger

This will output files to the docs/ directory.

Project Structure

├── cmd/
│   └── main.go                  # Application entry point
├── internal/
│   ├── config/                  # Configuration and environment loading
│   │   └── config.go
│   ├── domain/                  # Domain models, constants, and roles
│   │   ├── sportmarket.go       # Market types (e.g., FootballMarket)
│   │   └── roles.go             # Role definitions (e.g., RoleSuperAdmin, RoleAdmin, etc.)
│   ├── repository/              # Database interaction layer
│   │   ├── branch.go            # Branch related queries and conversion functions
│   │   ├── company.go           # Company-related database functions
│   │   ├── user.go              # User repository methods
│   │   └── ...                  # Other repository files
│   ├── services/                # Business logic and core services
│   │   ├── odds/
│   │   │   └── service.go       # Fetching odds from external APIs
│   │   └── result/
│   │       ├── service.go       # Parsing and storing results
│   │       └── eval.go          # Evaluation logic for bet outcomes
│   └── web_server/              # HTTP handlers, routes, middleware, and cron jobs
│       ├── cron.go              # Scheduled background tasks
│       └── handlers/
│           ├── branch_handler.go  # Branch-related API endpoints
│           ├── manager.go         # Manager-related endpoints
│           └── ...                # Additional handlers (e.g., for companies, users, etc.)
├── db/
│   └── migrations/              # SQL migration files
│       ├── 000001_fortune.up.sql
│       └── ...                  # Further migration files
├── docs/
│   ├── swagger/                 # Swagger/OpenAPI documentation files
│   │   ├── swagger.yaml
│   │   └── swagger.json
│   └── docs.go                  # Swaggo-generated docs (do not edit manually)
├── gen/
│   └── db/                      # SQLC-generated Go code for database access
│       └── ...                  # Generated files (e.g., queries.go)
├── makefile                     # Development and operations commands
├── .env                         # Environment configuration file (not checked in)
└── README.md                    # Project documentation

Core Services Overview

FortuneBet includes a wide suite of services for a modern betting platform:

• Notification Service: Sends alerts to users/admins about odds changes, results, etc.
• Ticket System: Manages bet tickets, results, and statuses.
• Temporary Ticket QR/Shortcode System: Fast bet placement and redemption.
• Fraud Prevention: Detects suspicious activity and prevents account abuse.
• Bet Expiration: Bets expire after one year; claims must be handled manually.
• Self-Protection: Limits bets based on user behavior to promote responsible betting.
• Betting System: Core logic for placing, modifying, and canceling bets.
• Bet365 Odds Integration: Real-time odds sync with Bet365.
• Event Disabling: Admins can disable events (e.g. suspicious or restricted).
• Odds Management: Admins can dynamically adjust odds.
• Odds Update Log: Track and audit all odds changes.
• Game Management: Remove games or leagues from the market.
• Wallet System: Handles transactions, deposits, and withdrawals.
• Super Admin Panel: Master control for the whole system.
• Branch Manager Dashboard: Local control for branches and terminals.
• User Management: User roles, activity tracking, limits.
• Live Betting: Real-time betting during live matches.
• Cashout System: Enables early bet redemption.
• Bonus & Promotions: Incentivize users with custom promotions.
• Risk Analysis: Detect high-risk bets and patterns.
• Affiliate & Referrals: Referral tracking and commission.
• Reports & Analytics: Generate operational insights.
• Compliance Tools: Support for KYC, AML, and legal requirements.

Roles and Access Control

FortuneBet uses role-based access control to secure routes and platform features. The defined roles are:

package domain

type Role string

const (
	RoleSuperAdmin    Role = "super_admin"
	RoleAdmin         Role = "admin"
	RoleBranchManager Role = "branch_manager"
	RoleCustomer      Role = "customer"
	RoleCashier       Role = "cashier"
)

Super Admin — Full system control

Admin — Represents a company admin that controls everything for company

Branch Manager — Handles local branch users and operations

Customer — Places and tracks bets

Cashier — Handles customer funds and transactions in branches

These roles determine route access and permissions in the admin interface.

Code Organization Guidelines

• Services:
  Add new business logic or functionality under the /internal/services directory.
  For example, create a new service in /internal/services/your_service/service.go.

• Routes and Handlers:
  Define new HTTP routes and API endpoint logic inside /internal/web_server/handlers.
  Create separate files for different modules (e.g., users, companies, branches, etc.).

• SQL Queries and Code Generation (SQLC):
  Write your raw SQL queries in the /db/query directory.
  Then generate type-safe Go code with SQLC by running:

  make sqlc-gen
  

Further Details

Our long-term goal is to become a trusted betting provider, offering white-label sportsbook solutions for other operators to use in their shops and platforms.

Planned Features:

• Multi-language and currency support
• Full virtual games integration
• Regulatory audit logging