🎯 System Overview
Project Introduction
The Milimus Tournament is a comprehensive tournament management system designed to handle all aspects of competitive gaming tournaments. Built with modern web technologies, it provides a seamless experience for organizers, teams, players, and spectators.
Technology Stack
Laravel 12
Backend Framework
React 19
Frontend Library
TypeScript
Type Safety
Inertia.js
SPA Framework
SQLite/MySQL
Database
Vite
Build Tool
Key Features
🏆 Tournament Management
Complete tournament lifecycle management with automated bracket generation and match scheduling.
👥 Team & Player Management
Comprehensive team registration, player profiles, and digital ID generation system.
💰 Payment Integration
M-Pesa integration for seamless payment processing and financial management.
📱 Modern UI/UX
Responsive design with modern UI components and excellent user experience.
System Architecture
The system follows a modern MVC architecture with:
- Backend: Laravel 12 with service layer architecture
- Frontend: React 19 with TypeScript and Inertia.js
- Database: SQLite for development, MySQL for production
- Authentication: Laravel Sanctum for API authentication
- File Storage: Laravel Storage with local/cloud support
🚀 Installation & Setup
Prerequisites
- PHP 8.2 or higher
- Composer
- Node.js 18+ and npm
- SQLite or MySQL
- Git
Installation Steps
- Clone the repository:
git clone https://github.com/your-username/the-milimus-tournament.git cd the-milimus-tournament - Install PHP dependencies:
composer install - Install Node.js dependencies:
npm install - Environment setup:
cp .env.example .env php artisan key:generate - Database setup:
php artisan migrate php artisan db:seed - Build assets:
npm run build - Start the server:
php artisan serve
Configuration
Configure the following in your .env file:
- Database connection settings
- M-Pesa API credentials
- Email configuration
- File storage settings
🏗️ System Architecture
Backend Architecture
The backend follows Laravel's MVC pattern with additional service layer:
- Models: Eloquent models for data representation
- Controllers: Handle HTTP requests and responses
- Services: Business logic and external integrations
- Observers: Model event handling
- Notifications: Email and system notifications
Frontend Architecture
The frontend is built with React 19 and TypeScript:
- Components: Reusable UI components
- Pages: Route-based page components
- Hooks: Custom React hooks for state management
- Context: Global state management
- Types: TypeScript type definitions
Database Design
Key entities and relationships:
- Users: Authentication and user management
- Tournaments: Tournament information and settings
- Teams: Team registration and management
- Players: Player profiles and statistics
- Matches: Game matches and results
- Brackets: Tournament bracket structure
📊 Data Models
Core Models
User Model
Handles authentication, roles, and user management with Laravel Sanctum integration.
Tournament Model
Manages tournament information, settings, and lifecycle with automated bracket generation.
Team Model
Handles team registration, formation, and management with approval workflows.
Player Model
Manages player profiles, statistics, and digital ID generation system.
Key Relationships
- User → Teams: One-to-many relationship for team ownership
- Team → Players: One-to-many relationship for team members
- Tournament → Teams: Many-to-many relationship for registrations
- Tournament → Matches: One-to-many relationship for game matches
- Match → Teams: Many-to-many relationship for competing teams
Model Features
- Soft Deletes: All models support soft deletion
- Timestamps: Automatic created_at and updated_at tracking
- Observers: Model event handling for business logic
- Validation: Comprehensive data validation rules
- Relationships: Well-defined model relationships
🔌 API Documentation
Authentication Endpoints
- POST /api/register - User registration
- POST /api/login - User authentication
- POST /api/logout - User logout
- POST /api/refresh - Token refresh
Tournament Endpoints
- GET /api/tournaments - List all tournaments
- POST /api/tournaments - Create new tournament
- GET /api/tournaments/{id} - Get tournament details
- PUT /api/tournaments/{id} - Update tournament
- DELETE /api/tournaments/{id} - Delete tournament
Team Management Endpoints
- GET /api/teams - List all teams
- POST /api/teams - Create new team
- GET /api/teams/{id} - Get team details
- PUT /api/teams/{id} - Update team
- POST /api/teams/{id}/players - Add player to team
Payment Endpoints
- POST /api/payments/mpesa - Initiate M-Pesa payment
- POST /api/payments/callback - M-Pesa callback
- GET /api/payments/{id} - Get payment status
⚛️ Frontend Components
Layout Components
- AppLayout: Main application layout with navigation
- GuestLayout: Layout for unauthenticated users
- AdminLayout: Administrative interface layout
- TeamManagerLayout: Team management interface
UI Components
- Button: Reusable button component with variants
- Input: Form input component with validation
- Modal: Modal dialog component
- Table: Data table component with sorting
- Card: Content card component
Feature Components
- TournamentCard: Tournament display component
- TeamFormation: Team formation interface
- BracketViewer: Tournament bracket display
- PaymentForm: Payment processing form
- PlayerProfile: Player profile display
Component Architecture
All components are built with:
- TypeScript: Type safety and better development experience
- Props Interface: Well-defined component props
- Responsive Design: Mobile-first approach
- Accessibility: WCAG compliance
- Reusability: Modular and reusable design
🎨 User Interface
Design System
The UI follows a modern design system with:
- Color Palette: Professional blue and purple gradient theme
- Typography: Segoe UI font family for readability
- Spacing: Consistent 8px grid system
- Components: Reusable UI components
- Icons: Lucide React icon library
Responsive Design
- Mobile First: Designed for mobile devices first
- Breakpoints: 768px, 1024px, 1200px
- Grid System: CSS Grid and Flexbox
- Touch Friendly: Appropriate touch targets
User Experience
- Intuitive Navigation: Clear and logical navigation structure
- Loading States: Proper loading indicators
- Error Handling: User-friendly error messages
- Feedback: Toast notifications and success messages
- Accessibility: Screen reader support and keyboard navigation
⭐ Core Features
Tournament Management
Tournament Creation
Create and configure tournaments with custom settings, rules, and formats.
Bracket Generation
Automated bracket generation with support for single and double elimination.
Match Management
Schedule, track, and manage tournament matches with real-time updates.
Results Tracking
Track match results, standings, and tournament progress.
Team & Player Management
- Team Registration: Complete team registration process
- Player Profiles: Detailed player profiles with statistics
- Digital IDs: Automated digital ID generation for players
- Formation Management: Team formation and lineup management
- Approval Workflow: Two-tier approval system for registrations
Payment Integration
- M-Pesa Integration: Seamless payment processing
- Payment Tracking: Real-time payment status updates
- Receipt Generation: Automated receipt generation
- Refund Management: Handle refunds and cancellations
🚀 Advanced Features
Two-Tier Approval System
Comprehensive approval workflow for team registrations:
- First Tier: Team official approval
- Second Tier: Tournament organizer approval
- Status Tracking: Real-time approval status updates
- Notifications: Email notifications for all stakeholders
Enhanced Bracketing System
Advanced tournament bracket management:
- Algorithm Testing: Comprehensive bracket algorithm testing
- Data Scoping: Advanced data scoping and filtering
- Bracket Visualization: Interactive bracket display
- Match Scheduling: Intelligent match scheduling
Content Management
- Hero Slides: Dynamic hero section management
- News System: News and announcements management
- Sponsor Management: Sponsor information and display
- Testimonials: User testimonials and reviews
- Gallery: Image and media gallery management
- Vlog System: Video content management
💼 Business Logic
Service Layer
The system uses a comprehensive service layer for business logic:
- TournamentBracketService: Bracket generation and management
- TeamRegistrationService: Team registration workflow
- MpesaService: Payment processing integration
- OtpService: One-time password generation
- EmailSettingsService: Email configuration management
- DataScopingService: Data filtering and scoping
Business Rules
- Team Size Limits: Configurable team size restrictions
- Registration Deadlines: Tournament registration deadlines
- Payment Requirements: Payment validation and verification
- Approval Workflows: Multi-tier approval processes
- Match Rules: Configurable match rules and regulations
Data Validation
- Input Validation: Comprehensive input validation
- Business Rule Validation: Custom business rule validation
- Data Integrity: Database integrity constraints
- Error Handling: Graceful error handling and recovery
🔒 Security
Authentication & Authorization
- Laravel Sanctum: API token authentication
- Role-Based Access: Granular permission system
- Password Security: Bcrypt password hashing
- Session Management: Secure session handling
- CSRF Protection: Cross-site request forgery protection
Data Security
- Input Sanitization: All inputs are sanitized
- SQL Injection Prevention: Eloquent ORM protection
- XSS Protection: Cross-site scripting prevention
- File Upload Security: Secure file upload handling
- Data Encryption: Sensitive data encryption
API Security
- Rate Limiting: API rate limiting
- Token Expiration: Automatic token expiration
- CORS Configuration: Proper CORS setup
- Request Validation: Comprehensive request validation
🗄️ Database
Database Design
The system uses a well-designed relational database with:
- Normalized Structure: Proper database normalization
- Foreign Keys: Referential integrity constraints
- Indexes: Optimized database indexes
- Soft Deletes: Soft deletion for data recovery
- Timestamps: Automatic timestamp tracking
Key Tables
- users: User authentication and profiles
- tournaments: Tournament information and settings
- teams: Team registration and management
- players: Player profiles and statistics
- game_matches: Tournament matches and results
- brackets: Tournament bracket structure
- payments: Payment transactions and status
Database Features
- Migrations: Version-controlled database schema
- Seeders: Database seeding for development
- Factories: Model factories for testing
- Backups: Automated database backups
- Performance: Query optimization and caching
👤 User Guide
Getting Started
- Account Creation: Register for a new account
- Email Verification: Verify your email address
- Profile Setup: Complete your user profile
- Team Registration: Register your team for tournaments
Team Management
- Create Team: Set up your team profile
- Add Players: Invite players to join your team
- Team Formation: Configure your team lineup
- Submit for Approval: Submit team for tournament approval
Tournament Participation
- Browse Tournaments: View available tournaments
- Register Team: Register your team for tournaments
- Make Payment: Complete tournament registration payment
- Track Progress: Monitor your team's tournament progress
👨💻 Developer Guide
Development Setup
- Clone Repository: Clone the project repository
- Install Dependencies: Install PHP and Node.js dependencies
- Environment Configuration: Set up your development environment
- Database Setup: Configure and seed the database
- Start Development Server: Run the development server
Code Structure
- Backend: Laravel MVC structure with service layer
- Frontend: React components with TypeScript
- Database: Eloquent models with migrations
- API: RESTful API endpoints
- Testing: PHPUnit and Pest testing framework
Contributing
- Code Standards: Follow PSR-12 coding standards
- Testing: Write tests for new features
- Documentation: Update documentation for changes
- Pull Requests: Submit pull requests for review