📄 Sponsor Tracking Web App Design Document
📌 Overview

This project is a web-based system to track sponsorship (invite/referral) relationships for a Minecraft server.

Users:

Authenticate via Discord OAuth2
Must belong to a specific Discord guild
Receive a unique sponsor code
Can sponsor multiple users
Must themselves be sponsored (except initial/manual cases)

Admins:

Defined in config.php
Can view the full sponsorship tree
🏗️ Tech Stack
Backend: PHP (8.x recommended)
Frontend: HTML, CSS, JavaScript (vanilla)
Database: SQLite
Web Server: Nginx
Auth: Discord OAuth2
🔐 Authentication Flow
Steps:
User clicks Login with Discord
Redirect to Discord OAuth2
User authorizes
App receives:
Discord ID
Username
Avatar
App checks:
User is in required Discord guild
If valid:
Create or update user in DB
Start session
👤 User Model
Table: users
CREATE TABLE users (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    discord_id TEXT UNIQUE NOT NULL,
    discord_username TEXT NOT NULL,
    minecraft_username TEXT,
    sponsor_code TEXT UNIQUE NOT NULL,
    sponsor_id INTEGER,
    is_admin INTEGER DEFAULT 0,
    created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
    FOREIGN KEY (sponsor_id) REFERENCES users(id)
);
🔑 Sponsor Code System
Generated on first login
Format: Random alphanumeric (e.g. A7F3K9)
Permanent (never changes)
Must be unique
Example Generation (PHP):
function generateSponsorCode($length = 6) {
    return strtoupper(substr(bin2hex(random_bytes(4)), 0, $length));
}
🔁 Sponsorship Logic
Rules
A user:
Can sponsor multiple users
Can have only one sponsor
A user must:
Set Minecraft username before sponsoring others
First Login Flow
User logs in via Discord
If new user:
Prompt for:
Sponsor code
Validate:
Sponsor exists
Create user:
Assign sponsor_id
Unsponsoring
A user can remove someone they sponsor
Effects:
Target user:
sponsor_id = NULL
Status becomes “unsponsored”
Cannot sponsor others until responsored (optional enforcement)
🎮 Minecraft Username Linking
Requirement
Users must set minecraft_username before:
Sponsoring others
Validation
Must be:
Unique (recommended)
Valid Minecraft format (3–16 chars, alphanumeric + _)
🧑‍💼 Admin System
Admin Definition

In config.php:

return [
    'admin_discord_ids' => [
        '123456789012345678',
        '987654321098765432'
    ]
];
Admin Detection

On login:

$isAdmin = in_array($discord_id, $config['admin_discord_ids']);
🌳 Sponsorship Tree
Admin Feature

Admins can view:

Full sponsorship hierarchy
Data Structure

Recursive relationship via sponsor_id

Example Tree
User A
├── User B
│   ├── User D
│   └── User E
└── User C
Implementation Options
Option 1 (Simple - Recommended)
Recursive PHP function
Render nested <ul>
Option 2 (Advanced)
JS visualization (e.g. tree graph)
🖥️ Pages / Routes
Public
/
Landing page
Login button
Authenticated
/dashboard
Show:
Sponsor code
Sponsor (who invited you)
People you sponsor
/set-minecraft
Set/update Minecraft username
/sponsor
Enter sponsor code (first-time only or responsor)
Admin Only
/admin/tree
Full sponsorship tree
🔌 API Endpoints (Optional but Recommended)
Auth
GET /auth/login
GET /auth/callback
User
GET /api/me
POST /api/set-minecraft
POST /api/sponsor
Admin
GET /api/admin/tree
⚠️ Validation Rules
Sponsor Code
Must exist
Cannot sponsor yourself
Sponsoring
Must have Minecraft username set
Minecraft Username
3–16 characters
Regex:
^[a-zA-Z0-9_]{3,16}$
🔒 Security Considerations
Use prepared statements (PDO)
Store sessions securely
Validate all input
Rate-limit sponsor attempts (basic)
Verify Discord token server-side
📁 Suggested Project Structure
/app
  /controllers
  /models
  /views
/config
  config.php
/public
  index.php
  assets/
/routes
  web.php
🚀 Future Improvements
Minecraft plugin integration (API validation)
Visual tree (graph UI)
Notifications when sponsored
Audit logs
Rate limiting & abuse detection
❓ Open Considerations

You may still want to decide later:

Should unsponsored users:
Lose ability to log in?
Or just limited features? (currently: limited)
Should there be:
A root/system user?
✅ Summary

This system provides:

Discord-authenticated user accounts
Sponsor/referral tracking
Tree-based relationship visualization
Admin oversight tools
Lightweight, SQLite-backed architecture