W3RD backend protocol

This repository contains the LAMP stack (Laravel 12) API backend for the multi-platform protocol with multitenancy (W3RD.io, SwampProtocol.io GamerProtocol.io) powering all frontend brands (TokenGames.io, DrewRoberts.com, Web3Journey.org). It serves as the single source of truth for user authentication, real-time updates, and subscription/billing logic and even the game state management.

Core Technology Stack

• Framework: Laravel 12
• Database: MySQL 8.0+ (Utilizing JSON type and efficient indexing)
• Real-Time: Laravel Reverb (WebSockets)
• Authentication: Laravel Sanctum (API Tokens)
• Billing: Laravel Cashier (Stripe)

Key Features and Architectural Concepts

1. Domain-Driven Architecture: Models, Controllers, and Services are organized into distinct domains (Auth, Game, Billing) for maintainability.
   • See models.md and services.md for detailed structures.
2. Two-Factor Authorization: Every request requires a Sanctum Bearer Token (user authentication) and an X-Client-Key (application authorization) found in the clients table.
3. Real-Time Gameplay: Laravel Reverb pushes instant game state updates to all subscribed clients.
4. Flexible Game State: All game boards and hands are stored in the unified games table using the JSON column type (MySQL 8.0+ required) and Laravel casting. Game titles are defined as PHP enums (Connect Four, Checkers, Hearts, Spades), allowing for unlimited game variations without database schema changes.
5. Matchmaking: Players can be matched in games through Quickplay, Lobbies (public & private) and Rematches.
6. Usage Metering: Custom database logic handles complex quotas: strikes (daily free losses) and quotas (monthly member games).

Required Composer Packages

These packages are essential for implementing the core features and security structures:

Package	Purpose	Notes
laravel/sanctum	API Authentication	Handles user login, token generation, and Bearer token validation.
laravel/cashier	Subscription Billing	Integrates with Stripe for managing Member/Master subscriptions and webhooks.
laravel/reverb	Real-Time Communication	The official first-party WebSocket server for Laravel Broadcasting.
guzzlehttp/guzzle	HTTP Client	Needed within your Billing Services to verify mobile app store receipts and interact with external APIs.
illuminate/database	Database Features	Ensure support for ULIDs and JSON column casting.

Documentation Links

For full implementation details, refer to the following files in the /docs directory:

• API Endpoints: api.md
• Database Migrations: database.md
• Model Definitions: models.md
• Game Services: services.md
• Admin Panel: admin.md
• Feature Expansion: expansion.md
• Matchmaking: matchmaking.md