Add comprehensive documentation for LeagueLedger

- Created architecture overview in development/architecture.md
- Added installation guide in getting-started/installation.md
- Developed user guide with detailed instructions in user-guide/overview.md, user-guide/teams.md, user-guide/qr-codes.md
- Implemented social login setup documentation in social_login_setup.md
- Updated index.md to include links to new documentation sections
- Configured mkdocs.yml for site structure and theme
- Added requirements.txt for documentation dependencies

docs/administration/admin-panel.md

@@ -0,0 +1,142 @@
+# Admin Panel
+
+The LeagueLedger Admin Panel provides administrators with powerful tools to manage all aspects of the system. This guide explains how to access and use the admin panel effectively.
+
+## Accessing the Admin Panel
+
+To access the admin panel:
+
+1. Log in to LeagueLedger using an admin account
+2. Click on your profile icon in the top-right corner
+3. Select "Admin Panel" from the dropdown menu
+
+!!! note "Admin Privileges"
+    Only users with admin privileges can access the admin panel. If you don't see this option, contact your system administrator.
+
+## Admin Panel Dashboard
+
+The admin dashboard provides an overview of system activity and key metrics:
+
+- **User Statistics**: Total users, active users, new registrations
+- **Team Statistics**: Total teams, active teams, team distribution
+- **Event Statistics**: Upcoming events, past events, attendance rates
+- **System Health**: Database status, background tasks, recent errors
+
+## Main Admin Sections
+
+### User Management
+
+In this section, you can manage all user accounts:
+
+- **View Users**: See a list of all registered users with filtering options
+- **Create Users**: Manually create new user accounts
+- **Edit Users**: Modify existing user information
+- **Verify/Unverify Users**: Manually verify or unverify user accounts
+- **Reset Passwords**: Help users recover access to their accounts
+- **Assign Roles**: Grant or revoke admin privileges
+- **Disable Accounts**: Temporarily or permanently disable user accounts
+
+### Team Management
+
+Manage teams and their members:
+
+- **View Teams**: Browse all teams with filtering and sorting options
+- **Create Teams**: Create new teams manually
+- **Edit Teams**: Update team information
+- **Manage Members**: Add or remove team members
+- **Transfer Ownership**: Change team ownership
+- **Archive Teams**: Deactivate teams when needed
+
+### QR Code Management
+
+Create and manage QR codes for points and achievements:
+
+- **Create QR Codes**: Generate new QR codes with specified point values
+- **Create QR Sets**: Group QR codes into themed sets for events
+- **View Usage**: Track which QR codes have been redeemed
+- **Print QR Codes**: Generate printable sheets for distribution
+- **Invalidate QR Codes**: Disable QR codes if needed
+
+### Event Management
+
+Create and manage events:
+
+- **Create Events**: Set up new events with date, time, and location
+- **Edit Events**: Modify event details
+- **Assign QR Sets**: Connect QR code sets to specific events
+- **Track Attendance**: Monitor event participation
+- **View Results**: See points and achievements awarded at events
+
+### System Configuration
+
+Configure system-wide settings:
+
+- **Email Settings**: Configure email server details and templates
+- **OAuth Providers**: Set up social login integration
+- **Appearance Settings**: Customize branding and UI elements
+- **General Settings**: Adjust system behavior and defaults
+
+## Administrative Tasks
+
+### Running Reports
+
+Generate reports to analyze system data:
+
+1. Navigate to the "Reports" section in the admin panel
+2. Select the report type (users, teams, events, etc.)
+3. Set the parameters and date range
+4. Click "Generate Report"
+5. View on screen or export to CSV/PDF
+
+### Managing Achievements
+
+Create and assign achievements:
+
+1. Go to the "Achievements" section
+2. Create achievement types with names, descriptions, and icons
+3. Set automatic achievement criteria or assign manually
+4. Link achievements to QR codes if desired
+
+### System Backup
+
+Back up your system data:
+
+1. Navigate to "System Tools"
+2. Select "Backup Database"
+3. Choose backup options (full or partial)
+4. Initiate the backup process
+5. Download the backup file or save to a configured location
+
+## Best Practices
+
+- **Regular Maintenance**: Schedule regular system checks and database optimization
+- **User Audits**: Periodically review user accounts and permissions
+- **QR Security**: Create new QR codes for each event to prevent reuse
+- **Data Backup**: Back up the database before making significant changes
+- **Testing**: Test new configurations in a staging environment before deploying
+
+## Troubleshooting
+
+### Common Issues
+
+- **User Can't Log In**: Check account status, verification status, and credentials
+- **QR Codes Not Working**: Verify QR code validity and ensure they're not already redeemed
+- **Email Delivery Problems**: Check email server settings and test mail functionality
+- **Performance Issues**: Monitor database size, optimize queries, check server resources
+
+### Getting Support
+
+If you encounter issues that you can't resolve:
+
+1. Check the [documentation](../index.md) for relevant guidance
+2. Consult the [developer documentation](../development/architecture.md) for technical details
+3. Contact system support with specific error information and screenshots
+
+## Next Steps
+
+For more detailed information about specific administrative functions, please refer to the following guides:
+
+- [User Management](user-management.md)
+- [Team Management](team-management.md)
+- [QR Code Management](qr-code-management.md)
+- [Event Management](event-management.md)

docs/deployment/docker.md

@@ -0,0 +1,344 @@
+# Docker Deployment
+
+This guide covers deploying LeagueLedger using Docker and Docker Compose, which is the recommended approach for both development and production environments.
+
+## Prerequisites
+
+Before deploying LeagueLedger with Docker, ensure you have:
+
+- **Docker**: Version 20.10.0 or higher
+- **Docker Compose**: Version 2.0.0 or higher
+- **Git**: For cloning the repository (optional)
+- **Basic Docker knowledge**: Understanding of containers and Docker Compose
+
+## Quick Deployment
+
+For a quick deployment using default settings:
+
+```bash
+# Clone the repository
+git clone https://github.com/yourusername/leagueledger.git
+cd leagueledger
+
+# Create and configure the environment file
+cp .env.example .env
+# Edit the .env file with your preferred text editor
+
+# Start the containers
+docker-compose up -d
+```
+
+## Docker Compose Configuration
+
+LeagueLedger's Docker setup includes multiple services defined in `docker-compose.yml`:
+
+### Services Overview
+
+- **app**: The main LeagueLedger application
+- **db**: MySQL database for persistent storage
+- **phpmyadmin**: Web interface for database management
+- **mailpit**: Email testing service that captures all outgoing emails
+
+### Important Configuration Parameters
+
+#### Application Service
+
+```yaml
+app:
+  build: .
+  container_name: pubquiz_app
+  restart: unless-stopped
+  depends_on:
+    db:
+      condition: service_healthy
+  environment:
+    # Database configuration
+    DB_HOST: "db"
+    DB_PORT: "3306"
+    DB_NAME: "pubquiz_db"
+    DB_USER: "pubquiz_user"
+    DB_PASS: "pubquiz_pass"
+    # ... other environment variables
+  ports:
+    - "8000:8000"
+  volumes:
+    - ./:/app:delegated
+```
+
+#### Database Service
+
+```yaml
+db:
+  image: mysql:8.0
+  container_name: pubquiz_mysql
+  restart: always
+  environment:
+    MYSQL_DATABASE: "pubquiz_db"
+    MYSQL_USER: "pubquiz_user"
+    MYSQL_PASSWORD: "pubquiz_pass"
+    MYSQL_ROOT_PASSWORD: "root_pass"
+  ports:
+    - "3306:3306"
+  # ... other settings
+```
+
+## Environment Configuration
+
+The `.env` file contains important configuration options:
+
+```
+# Database Configuration
+DATABASE_URL=mysql+pymysql://pubquiz_user:pubquiz_pass@db:3306/pubquiz_db
+
+# Security
+SECRET_KEY=your-secure-secret-key
+
+# Email Configuration
+MAIL_USERNAME=your-email@example.com
+MAIL_PASSWORD=your-email-password
+MAIL_FROM=noreply@example.com
+MAIL_PORT=587
+MAIL_SERVER=smtp.example.com
+MAIL_TLS=True
+MAIL_SSL=False
+MAIL_FROM_NAME=LeagueLedger
+
+# OAuth Configuration
+# ... provider-specific settings
+```
+
+## Production Deployment Considerations
+
+For production deployments, make the following adjustments:
+
+### 1. Secure Database Configuration
+
+Update the MySQL environment variables in `docker-compose.yml`:
+
+```yaml
+db:
+  environment:
+    MYSQL_DATABASE: "your_production_db"
+    MYSQL_USER: "your_production_user"
+    MYSQL_PASSWORD: "your_strong_password"
+    MYSQL_ROOT_PASSWORD: "your_very_strong_root_password"
+```
+
+### 2. Persistent Storage
+
+Add volumes for persistent data storage:
+
+```yaml
+db:
+  volumes:
+    - leagueledger_db_data:/var/lib/mysql
+
+volumes:
+  leagueledger_db_data:
+```
+
+### 3. Email Configuration
+
+For production, replace Mailpit with a real SMTP server in your `.env` file:
+
+```
+MAIL_USERNAME=your-production-email@yourdomain.com
+MAIL_PASSWORD=your-email-password
+MAIL_FROM=noreply@yourdomain.com
+MAIL_PORT=587
+MAIL_SERVER=smtp.yourdomain.com
+MAIL_TLS=True
+MAIL_SSL=False
+MAIL_FROM_NAME=LeagueLedger
+```
+
+### 4. HTTPS Setup
+
+For secure access, you should add an HTTPS proxy such as Traefik or Nginx:
+
+```yaml
+services:
+  app:
+    # ... existing configuration
+    labels:
+      - "traefik.enable=true"
+      - "traefik.http.routers.leagueledger.rule=Host(`leagueledger.yourdomain.com`)"
+      - "traefik.http.routers.leagueledger.entrypoints=websecure"
+      - "traefik.http.routers.leagueledger.tls.certresolver=myresolver"
+
+  traefik:
+    image: traefik:v2.9
+    ports:
+      - "80:80"
+      - "443:443"
+    volumes:
+      - "/var/run/docker.sock:/var/run/docker.sock:ro"
+      - "./traefik/config:/etc/traefik"
+      - "./traefik/letsencrypt:/letsencrypt"
+    # ... additional Traefik configuration
+```
+
+### 5. OAuth Callback URLs
+
+Update the OAuth provider configuration in your `.env` file to use your production domain:
+
+```
+# OAuth Callback URLs
+LEAGUELEDGER_BASE_URL=https://leagueledger.yourdomain.com
+```
+
+## Container Management
+
+### Starting Services
+
+```bash
+# Start all services in the background
+docker-compose up -d
+
+# Start a specific service
+docker-compose up -d app
+```
+
+### Stopping Services
+
+```bash
+# Stop all services
+docker-compose down
+
+# Stop services without removing containers
+docker-compose stop
+```
+
+### Viewing Logs
+
+```bash
+# View logs for all services
+docker-compose logs
+
+# Follow logs for a specific service
+docker-compose logs -f app
+
+# See the last 100 lines of logs
+docker-compose logs --tail=100 app
+```
+
+### Restarting Services
+
+```bash
+# Restart all services
+docker-compose restart
+
+# Restart a specific service
+docker-compose restart app
+```
+
+## Database Management
+
+### Accessing the Database
+
+You can access the database using phpMyAdmin at:
+```
+http://localhost:8001
+```
+
+Or connect directly to MySQL:
+```bash
+docker-compose exec db mysql -upubquiz_user -ppubquiz_pass pubquiz_db
+```
+
+### Database Backups
+
+Create a backup:
+```bash
+docker-compose exec db mysqldump -uroot -proot_pass pubquiz_db > backup_$(date +%Y-%m-%d_%H-%M-%S).sql
+```
+
+Restore a backup:
+```bash
+cat backup_file.sql | docker-compose exec -T db mysql -uroot -proot_pass pubquiz_db
+```
+
+## Troubleshooting
+
+### Common Issues
+
+#### Container Fails to Start
+
+Check the logs:
+```bash
+docker-compose logs app
+```
+
+#### Database Connection Issues
+
+Verify the database is running and healthy:
+```bash
+docker-compose ps db
+```
+
+Ensure environment variables are correct:
+```bash
+docker-compose exec app env | grep DB_
+```
+
+#### Email Not Working
+
+Check Mailpit interface at `http://localhost:8025` to see if emails are being captured.
+
+If using a real SMTP server, verify credentials and connectivity:
+```bash
+docker-compose exec app python -c "from app.utils.mail import test_mail_connection; test_mail_connection()"
+```
+
+## Updating LeagueLedger
+
+To update to a newer version:
+
+```bash
+# Pull the latest changes
+git pull
+
+# Rebuild and restart containers
+docker-compose up -d --build
+```
+
+## Scaling for Production
+
+For high-traffic production environments, consider:
+
+1. **Horizontal Scaling**: Run multiple instances behind a load balancer
+2. **Database Scaling**: Move the database to a managed service
+3. **Redis Cache**: Add a Redis container for improved performance
+4. **CDN Integration**: Use a CDN for static assets
+
+A more advanced `docker-compose.prod.yml` might include:
+
+```yaml
+version: "3.9"
+
+services:
+  app:
+    deploy:
+      replicas: 3
+    environment:
+      REDIS_URL: "redis://redis:6379/0"
+  
+  redis:
+    image: redis:7.0
+    volumes:
+      - redis_data:/data
+
+  db:
+    volumes:
+      - db_data:/var/lib/mysql
+
+volumes:
+  db_data:
+  redis_data:
+```
+
+## Next Steps
+
+- [Production Setup](production.md): Additional production environment considerations
+- [Scaling](scaling.md): Detailed guidance on scaling LeagueLedger
+- [Backup & Recovery](backup-recovery.md): Comprehensive backup strategies

docs/development/architecture.md

@@ -0,0 +1,188 @@
+# System Architecture
+
+This document provides an overview of the LeagueLedger system architecture to help developers understand the system's structure and components.
+
+## Overview
+
+LeagueLedger is built with a modern web architecture using FastAPI as the backend framework and a combination of server-rendered templates and JavaScript for the frontend. The system follows a modular design pattern to maintain separation of concerns and enable easy extension.
+
+## Architecture Diagram
+
+```mermaid
+graph TD
+    Client[Client Browser] --> FastAPI[FastAPI Application]
+    FastAPI --> Templates[Jinja2 Templates]
+    FastAPI --> Static[Static Files]
+    FastAPI --> Auth[Authentication]
+    FastAPI --> DB[Database]
+    Auth --> OAuth[OAuth Providers]
+    Auth --> Local[Local Auth]
+    FastAPI --> Email[Email Service]
+    FastAPI --> QR[QR Code Generation]
+    
+    subgraph "Data Layer"
+    DB --> SQLAlchemy[SQLAlchemy ORM]
+    SQLAlchemy --> Models[Data Models]
+    end
+    
+    subgraph "Application Layer"
+    FastAPI --> Routes[API Routes]
+    Routes --> Views[View Controllers]
+    Views --> Services[Services]
+    end
+```
+
+## Core Components
+
+### Backend Framework
+
+LeagueLedger uses [FastAPI](https://fastapi.tiangolo.com/), a modern, high-performance web framework for building APIs with Python 3.7+ based on standard Python type hints.
+
+Key FastAPI components used:
+- **Dependency Injection**: For database sessions, authentication, and other services
+- **Pydantic Models**: For data validation and serialization
+- **Middleware**: For session management, authentication, and error handling
+
+### Database
+
+The system uses SQLAlchemy as an ORM (Object-Relational Mapper) to interact with the database. Key database components include:
+
+- **SQLAlchemy Models**: Defined in `app/models/`
+- **Database Configuration**: Found in `app/db.py`
+- **Migrations**: Handled through custom migration scripts in `app/db_migrations.py`
+
+The data model centers around these core entities:
+- **Users**: User accounts and authentication
+- **Teams**: Groups of users competing together
+- **TeamMemberships**: Relationship between users and teams
+- **QRCodes**: Generated codes for awarding points
+- **QRSets**: Collections of QR codes for specific events
+- **Events**: Scheduled activities
+- **TeamAchievements**: Recognitions earned by teams
+
+### Authentication System
+
+Authentication is handled through multiple mechanisms:
+
+- **Session-based Authentication**: For traditional username/password login
+- **OAuth Authentication**: For social login via multiple providers
+- **Authentication Middleware**: Integrated with Starlette's authentication system
+
+OAuth providers are implemented as pluggable components, allowing easy addition of new providers.
+
+### Frontend
+
+The frontend is primarily built with:
+
+- **Jinja2 Templates**: For server-side rendering of HTML
+- **Tailwind CSS**: For responsive styling
+- **JavaScript**: For interactive elements
+- **Static Assets**: CSS, JS, images stored in `app/static/`
+
+### Template Engine
+
+[Jinja2](https://jinja.palletsprojects.com/) is used as the template engine with:
+
+- **Base Templates**: Providing layout scaffolding
+- **Template Inheritance**: Enabling consistent UI across pages
+- **Template Globals**: For user context and common functions
+
+### QR Code System
+
+QR codes are central to the application's functionality:
+
+- **Generation**: Creating unique QR codes with the `qrcode` library
+- **Scanning**: Web-based scanning using the device camera
+- **Points Attribution**: Mapping scanned codes to point values and teams
+
+### Internationalization
+
+The application supports multiple languages through:
+
+- **Babel**: For i18n infrastructure
+- **Translation Files**: Stored in `app/i18n/locales/`
+- **Language Selection**: User-configurable preferences
+
+## Data Flow
+
+### Request Lifecycle
+
+1. **Client Request**: Browser sends HTTP request
+2. **Middleware Processing**: Session, authentication, template globals
+3. **Route Handling**: Matching URL to appropriate handler
+4. **View Controller**: Processing business logic
+5. **Database Interactions**: Through SQLAlchemy models
+6. **Template Rendering**: Creating HTML with Jinja2
+7. **Response**: Returning HTML or redirect to client
+
+### Authentication Flow
+
+1. **Login Request**: User submits credentials
+2. **Verification**: Checking against stored hash
+3. **Session Creation**: Creating session on successful auth
+4. **OAuth Flow** (for social login):
+   - Redirect to provider
+   - Provider authentication
+   - Callback with authorization code
+   - Token exchange
+   - User info retrieval
+   - Account creation or linking
+
+## Directory Structure
+
+```
+leagueledger/
+├── app/                    # Application code
+│   ├── auth/               # Authentication components
+│   ├── i18n/               # Internationalization
+│   ├── models/             # Database models
+│   ├── static/             # Static files
+│   ├── templates/          # HTML templates
+│   ├── utils/              # Utility functions
+│   └── views/              # View controllers
+├── docs/                   # Documentation
+├── scripts/                # Helper scripts
+└── tests/                  # Test suite
+```
+
+## Development Patterns
+
+### Dependency Injection
+
+FastAPI's dependency injection system is used extensively to:
+- Provide database sessions
+- Ensure authentication
+- Validate permissions
+- Supply configuration
+
+Example:
+```python
+@router.get("/secure-endpoint")
+async def secure_endpoint(db: Session = Depends(get_db), 
+                         current_user: User = Depends(get_current_user)):
+    # Function implementation
+```
+
+### Service Pattern
+
+Business logic is organized into service modules to separate concerns:
+- **Data access**: Database operations
+- **Business rules**: Application logic
+- **Presentation**: View rendering and response formatting
+
+### Error Handling
+
+Centralized error handling through:
+- **Exception handlers**: For API errors
+- **Custom templates**: For user-friendly error pages
+- **Logging**: Comprehensive error logging
+
+## Next Steps
+
+For more detailed information about the development aspects, refer to:
+
+- [API Reference](api-reference.md)
+- [Database Schema](database-schema.md)
+- [Frontend Development](frontend-dev.md)
+- [Backend Development](backend-dev.md)
+- [Testing](testing.md)

docs/getting-started/installation.md

@@ -0,0 +1,143 @@
+# Installation Guide
+
+This guide will walk you through the process of installing LeagueLedger on your system.
+
+## Prerequisites
+
+Before installing LeagueLedger, make sure you have the following prerequisites:
+
+- Python 3.10 or higher
+- pip (Python package manager)
+- Git (optional, for cloning the repository)
+- Docker and Docker Compose (optional, for containerized deployment)
+
+## Option 1: Installation with Docker (Recommended)
+
+The easiest way to get LeagueLedger up and running is using Docker and Docker Compose.
+
+### Step 1: Clone the Repository
+
+```bash
+git clone https://github.com/yourusername/leagueledger.git
+cd leagueledger
+```
+
+### Step 2: Create Environment File
+
+Create a `.env` file in the project root or copy from the example:
+
+```bash
+cp .env.example .env
+```
+
+Edit the `.env` file to configure your environment variables.
+
+### Step 3: Start with Docker Compose
+
+```bash
+docker-compose up -d
+```
+
+This will start all the required services including:
+- Web application
+- MySQL database
+- PHPMyAdmin for database management
+- Mailpit for email testing
+
+### Step 4: Access the Application
+
+Once the containers are running, you can access:
+- LeagueLedger web interface at [http://localhost:8000](http://localhost:8000)
+- PHPMyAdmin at [http://localhost:8001](http://localhost:8001)
+- Mailpit (email testing) at [http://localhost:8025](http://localhost:8025)
+
+## Option 2: Manual Installation
+
+For development or if you prefer not to use Docker, you can install LeagueLedger manually.
+
+### Step 1: Clone the Repository
+
+```bash
+git clone https://github.com/yourusername/leagueledger.git
+cd leagueledger
+```
+
+### Step 2: Create a Virtual Environment
+
+```bash
+python -m venv venv
+```
+
+Activate the virtual environment:
+
+=== "Windows"
+    ```
+    venv\Scripts\activate
+    ```
+
+=== "macOS/Linux"
+    ```
+    source venv/bin/activate
+    ```
+
+### Step 3: Install Dependencies
+
+```bash
+pip install -r requirements.txt
+```
+
+### Step 4: Configure Environment Variables
+
+Create a `.env` file in the project root with the following content:
+
+```
+SECRET_KEY=your-secure-secret-key
+DATABASE_URL=sqlite:///./leagueledger.db
+
+# Email configuration
+MAIL_USERNAME=your-email@example.com
+MAIL_PASSWORD=your-email-password
+MAIL_FROM=noreply@example.com
+MAIL_PORT=587
+MAIL_SERVER=smtp.example.com
+MAIL_TLS=True
+MAIL_SSL=False
+MAIL_FROM_NAME=LeagueLedger
+```
+
+Customize the values as needed.
+
+### Step 5: Initialize the Database
+
+```bash
+python -c "from app.db_init import init_db; init_db()"
+```
+
+### Step 6: Run the Application
+
+```bash
+uvicorn app.main:app --reload
+```
+
+The application should now be accessible at [http://localhost:8000](http://localhost:8000).
+
+## Verifying the Installation
+
+After installation, you can verify that LeagueLedger is working correctly by:
+
+1. Opening your browser and navigating to [http://localhost:8000](http://localhost:8000)
+2. Creating a new user account via the registration page
+3. Logging in with your new credentials
+
+The default admin credentials for the seeded database are:
+- Username: `admin`
+- Password: `password`
+
+!!! warning "Security Note"
+    If using the seeded database in production, make sure to change the default admin password immediately.
+
+## Next Steps
+
+- [Configuration Guide](configuration.md): Configure LeagueLedger for your specific needs
+- [Quick Start Guide](quick-start.md): Get started with using LeagueLedger
+- [Social Login Setup](../integrations/social-login.md): Set up authentication with social media providers

docs/index.md

@@ -0,0 +1,49 @@
+# LeagueLedger Documentation
+
+Welcome to the official documentation for LeagueLedger, a comprehensive team management and points tracking system designed for organizing competitions, tracking achievements, and managing team-based events.
+
+## About LeagueLedger
+
+LeagueLedger is a flexible platform that helps event organizers, team managers, and participants track points, achievements, and standings. Whether you're running pub quizzes, sports leagues, or any team-based competition, LeagueLedger provides the tools to streamline your operations.
+
+## Key Features
+
+- **Team Management**: Create, join, and manage teams with flexible access controls
+- **Points Tracking**: Award points to teams and individuals through various mechanisms
+- **QR Code System**: Generate and scan QR codes for easy point attribution
+- **Achievements**: Recognize accomplishments with customizable achievements
+- **Leaderboard**: Real-time standings for teams and individuals
+- **Event Management**: Organize and track attendance for events
+- **Social Login**: Multiple authentication options for streamlined user access
+- **Responsive Design**: Works on desktop and mobile devices
+
+## Documentation Structure
+
+This documentation is organized into several sections:
+
+- **[Getting Started](getting-started/installation.md)**: Installation, configuration, and quick start guide
+- **[User Guide](user-guide/overview.md)**: Comprehensive instructions for end users
+- **[Administration](administration/admin-panel.md)**: Managing users, teams, QR codes, and events
+- **[Development](development/architecture.md)**: Technical details for developers
+- **[Deployment](deployment/docker.md)**: Guides for deploying to production environments
+- **[Integrations](integrations/social-login.md)**: Working with external services
+
+## Quick Links
+
+- [Installation Guide](getting-started/installation.md)
+- [User Accounts](user-guide/user-accounts.md)
+- [Team Management](user-guide/teams.md)
+- [QR Code System](user-guide/qr-codes.md)
+- [Admin Panel](administration/admin-panel.md)
+
+## Support
+
+If you encounter any issues or have questions not covered in this documentation, please:
+
+1. Check the [FAQ section](faq.md)
+2. Search for similar issues in our [GitHub repository](https://github.com/yourusername/leagueledger/issues)
+3. Open a new issue if your problem hasn't been addressed
+
+## Contributing
+
+We welcome contributions to both the LeagueLedger project and its documentation. See our [Contributing Guide](contributing.md) for more information.

docs/requirements.txt

@@ -0,0 +1,6 @@
+mkdocs>=1.5.0
+mkdocs-material>=9.2.0
+mkdocstrings>=0.22.0
+mkdocstrings-python>=1.5.0
+pymdown-extensions>=10.1
+mike>=1.1.2

docs/social_login_setup.md

@@ -0,0 +1,233 @@
+# Setting Up Social Login in LeagueLedger
+
+LeagueLedger supports multiple social login (OAuth) providers to give your users various options for authentication. This document explains how to set up each supported provider.
+
+## Table of Contents
+1. [General Setup](#general-setup)
+2. [Callback URLs](#callback-urls)
+3. [Provider-Specific Instructions](#provider-specific-instructions)
+   - [Google](#google)
+   - [GitHub](#github)
+   - [Facebook](#facebook)
+   - [Microsoft](#microsoft)
+   - [Discord](#discord)
+   - [LinkedIn](#linkedin)
+   - [Authentik](#authentik)
+4. [Troubleshooting](#troubleshooting)
+
+## General Setup
+
+To enable social login in LeagueLedger, you need to:
+
+1. Register your application with the desired OAuth provider(s)
+2. Obtain client ID and client secret credentials
+3. Add these credentials to your environment variables or `.env` file
+4. Restart the application
+
+Only providers with valid credentials will appear on the login page.
+
+## Callback URLs
+
+Each OAuth provider requires you to configure a **Redirect URI** (also known as a callback URL). This is where the provider redirects users after they authenticate.
+
+For LeagueLedger, use the following pattern:
+```
+https://your-domain.com/auth/oauth-callback/{provider_id}
+```
+
+Replace:
+- `your-domain.com` with your actual domain
+- `{provider_id}` with one of: `google`, `github`, `facebook`, `microsoft`, `discord`, `linkedin`, or `authentik`
+
+For local development, use:
+```
+http://localhost:8000/auth/oauth-callback/{provider_id}
+```
+
+**Important:** Most OAuth providers require exact URL matches, including protocol (http/https), domain, path, and any query parameters. Make sure to register the exact URL as shown above.
+
+## Provider-Specific Instructions
+
+### Google
+
+1. Go to [Google Cloud Console](https://console.cloud.google.com/)
+2. Create a new project or select an existing one
+3. Navigate to "APIs & Services" > "Credentials"
+4. Click "Create Credentials" > "OAuth client ID"
+5. Select "Web application" as the application type
+6. Add the following authorized redirect URI:
+   ```
+   http://localhost:8000/auth/oauth-callback/google
+   ```
+   (Plus your production URL if applicable)
+7. Click "Create"
+8. Note the Client ID and Client Secret
+9. Add to your `.env` file:
+   ```
+   GOOGLE_CLIENT_ID=your-client-id
+   GOOGLE_CLIENT_SECRET=your-client-secret
+   ```
+
+### GitHub
+
+1. Go to [GitHub Developer Settings](https://github.com/settings/developers)
+2. Click "New OAuth App"
+3. Fill in your application details:
+   - Application name: "LeagueLedger"
+   - Homepage URL: Your app's URL or `http://localhost:8000`
+   - Authorization callback URL:
+     ```
+     http://localhost:8000/auth/oauth-callback/github
+     ```
+4. Click "Register application"
+5. Generate a new client secret
+6. Add to your `.env` file:
+   ```
+   GITHUB_CLIENT_ID=your-client-id
+   GITHUB_CLIENT_SECRET=your-client-secret
+   ```
+
+### Facebook
+
+1. Go to [Facebook Developers](https://developers.facebook.com/)
+2. Create a new app (choose "Consumer" or "Business" type)
+3. Navigate to "Add a Product" > "Facebook Login" > "Web"
+4. In Settings > Basic, note your App ID and App Secret
+5. In Facebook Login > Settings, add the following OAuth Redirect URI:
+   ```
+   http://localhost:8000/auth/oauth-callback/facebook
+   ```
+6. Add to your `.env` file:
+   ```
+   FACEBOOK_CLIENT_ID=your-app-id
+   FACEBOOK_CLIENT_SECRET=your-app-secret
+   ```
+
+### Microsoft
+
+1. Go to [Azure Portal](https://portal.azure.com/)
+2. Navigate to "App registrations"
+3. Click "New registration"
+4. Enter a name for your application
+5. For "Supported account types," choose an option based on your needs
+   (typically "Accounts in any organizational directory and personal Microsoft accounts")
+6. Add the following Redirect URI (type: Web):
+   ```
+   http://localhost:8000/auth/oauth-callback/microsoft
+   ```
+7. Click "Register"
+8. Note the Application (client) ID
+9. Create a client secret: Navigate to "Certificates & secrets" > "New client secret"
+10. Add to your `.env` file:
+    ```
+    MICROSOFT_CLIENT_ID=your-client-id
+    MICROSOFT_CLIENT_SECRET=your-client-secret
+    MICROSOFT_TENANT=common
+    ```
+    Note: Use `common` for multi-tenant apps, or your specific tenant ID
+
+### Discord
+
+1. Go to the [Discord Developer Portal](https://discord.com/developers/applications)
+2. Click "New Application"
+3. Enter a name and click "Create"
+4. Go to the "OAuth2" section in the left sidebar
+5. Note the Client ID and generate a Client Secret
+6. Add the following redirect URL:
+   ```
+   http://localhost:8000/auth/oauth-callback/discord
+   ```
+7. In the "OAuth2 URL Generator" section, select the "identify" and "email" scopes
+8. Add to your `.env` file:
+   ```
+   DISCORD_CLIENT_ID=your-client-id
+   DISCORD_CLIENT_SECRET=your-client-secret
+   ```
+
+### LinkedIn
+
+1. Go to the [LinkedIn Developer Portal](https://www.linkedin.com/developers/)
+2. Click "Create app"
+3. Fill in the required app details:
+   - App name: "LeagueLedger"
+   - LinkedIn Page: Your company's LinkedIn page (or your personal page if needed)
+   - App logo: Upload your app logo
+   - Legal agreement: Accept the terms
+4. Click "Create app"
+5. Add the "Sign In with LinkedIn" product to your app
+6. Configure OAuth settings:
+   - Authorized redirect URLs:
+     ```
+     http://localhost:8000/auth/oauth-callback/linkedin
+     ```
+     (Plus your production URL if applicable)
+7. Under "OAuth 2.0 settings", note the Client ID and generate a Client Secret
+8. Request the appropriate scopes:
+   - r_liteprofile (for basic profile information)
+   - r_emailaddress (for user email address)
+9. Add to your `.env` file:
+   ```
+   LINKEDIN_CLIENT_ID=your-client-id
+   LINKEDIN_CLIENT_SECRET=your-client-secret
+   ```
+
+### Authentik
+
+1. Access your Authentik admin interface
+2. Go to "Applications" > "Providers" > "Create"
+3. Select "OAuth2/OIDC Provider"
+4. Configure the provider:
+   - Name: LeagueLedger
+   - Client Type: Confidential
+   - Redirect URIs:
+     ```
+     http://localhost:8000/auth/oauth-callback/authentik
+     ```
+   - Signing Key: Select an appropriate key or create one
+5. Save the provider
+6. Create an application:
+   - Go to "Applications" > "Applications" > "Create"
+   - Name: LeagueLedger
+   - Slug: leagueledger
+   - Provider: Select the provider you just created
+7. Save the application
+8. Note the Client ID and Client Secret
+9. Add to your `.env` file:
+   ```
+   AUTHENTIK_CLIENT_ID=your-client-id
+   AUTHENTIK_CLIENT_SECRET=your-client-secret
+   AUTHENTIK_CONFIG_URL=https://your-authentik-domain/application/o/leagueledger/.well-known/openid-configuration
+   ```
+
+## Troubleshooting
+
+### Common Issues:
+
+1. **Provider not showing on login page**
+   - Check that client ID and secret are correctly set in your environment/`.env` file
+   - Verify that values are not empty strings
+   - Check application logs for initialization errors
+
+2. **Authentication Error after provider login**
+   - Verify that the redirect URI is exactly as registered with the provider
+   - Check for protocol mismatch (http vs https)
+   - Ensure all required scopes have been granted
+
+3. **"Can't retrieve user email" errors**
+   - Ensure you've requested the email scope from the provider
+   - Some providers (like GitHub) require special permissions for email access
+
+### Checking Provider Status:
+
+You can check which providers are correctly configured by examining the login page:
+- Only providers with valid credentials will appear as login options
+- Look at application logs during startup for provider initialization messages
+
+### Provider-Specific Tips:
+
+- **Google**: Ensure the Google+ API is enabled in your Google Cloud project
+- **GitHub**: For private email addresses, request the `user:email` scope
+- **Discord**: Discord applications might need to be verified if you have a large user base
+- **Microsoft**: Ensure the Microsoft Graph API permissions include User.Read
+
+For more help, check the [official documentation](https://example.com/leagueledger/docs) or open an issue on the project repository.

docs/user-guide/overview.md

@@ -0,0 +1,125 @@
+# LeagueLedger User Guide
+
+Welcome to the LeagueLedger User Guide. This section provides detailed instructions on how to use LeagueLedger as an end user.
+
+## Getting Started as a User
+
+### Creating an Account
+
+To use LeagueLedger, you'll first need to create an account:
+
+1. Navigate to the [LeagueLedger homepage](http://localhost:8000)
+2. Click on the "Sign Up" or "Register" button
+3. Fill in the required information:
+   - Username
+   - Email address
+   - Password
+4. Complete the verification process through the email sent to your address
+5. Log in with your new credentials
+
+### Logging In
+
+You can log in using:
+- Your username and password
+- Social login (if configured by your administrator) via Google, GitHub, Microsoft, and other supported providers
+
+## Core Features
+
+### User Dashboard
+
+After logging in, you'll see your dashboard with:
+
+- Your personal points totals
+- Teams you're a member of
+- Recent activities and achievements
+- Upcoming events
+- Quick access to common actions
+
+### Teams
+
+Teams are the core organizational unit in LeagueLedger:
+
+- **Joining Teams**: Find teams through search or receive invitations
+- **Creating Teams**: Start your own team and invite others
+- **Team Management**: View team statistics, achievements, and members
+
+### QR Codes and Points
+
+Points in LeagueLedger are typically awarded through QR codes:
+
+- **Scanning QR Codes**: Use the scan feature to capture QR codes at events
+- **Points History**: Track all your earned points and achievements
+- **Team Points**: View how your contributions affect team standings
+
+### Events
+
+LeagueLedger tracks various events:
+
+- **Upcoming Events**: See what events are scheduled
+- **Event Registration**: Sign up for events individually or as a team
+- **Event Attendance**: Check in to events using QR codes
+
+### Leaderboards
+
+Track standings and achievements:
+
+- **Individual Leaderboards**: See how you rank among all participants
+- **Team Leaderboards**: View team rankings
+- **Event-specific Leaderboards**: Standings for particular events
+
+## User Settings
+
+### Profile Management
+
+Customize your experience through the profile settings:
+
+1. Navigate to "My Account" or "Settings"
+2. Update your:
+   - Profile picture
+   - Personal information
+   - Email preferences
+   - Notification settings
+
+### Account Security
+
+Manage your account security:
+
+- Change your password
+- Enable/disable social login connections
+- View active sessions
+
+## Navigation Guide
+
+### Main Menu
+
+The main menu provides access to all major features:
+
+- **Dashboard**: Your personal overview
+- **Teams**: Access to teams you belong to
+- **Events**: Upcoming and past events
+- **QR Scanner**: Tool to scan QR codes
+- **Leaderboards**: Overall standings
+- **Profile**: Your personal settings
+
+### Mobile Navigation
+
+On mobile devices, the menu is accessible through the hamburger icon (≡) in the top corner.
+
+## Getting Help
+
+If you encounter any issues while using LeagueLedger:
+
+- Check the FAQ section
+- Contact your organization's administrator
+- Submit a support request through the "Help" section
+
+## Next Steps
+
+For more detailed information about specific features, please refer to the following guides:
+
+- [User Accounts](user-accounts.md): Detailed account management information
+- [Teams](teams.md): Complete team management guide
+- [QR Codes](qr-codes.md): Everything about the QR code system
+- [Points & Achievements](points-and-achievements.md): How points and achievements work
+- [Leaderboard](leaderboard.md): Understanding the leaderboard system
+- [Events](events.md): Comprehensive events guide

docs/user-guide/qr-codes.md

@@ -0,0 +1,241 @@
+# QR Codes System
+
+The QR code system is a core feature of LeagueLedger, enabling easy point attribution and event participation tracking. This guide explains how QR codes work in the system and how to use them effectively.
+
+## Overview
+
+LeagueLedger's QR code system allows organizers to:
+
+- Create point-valued QR codes that users can scan
+- Group codes into sets for specific events or purposes
+- Track redemption and usage statistics
+- Print codes for physical distribution
+
+Users can scan these codes to:
+
+- Earn points for themselves or their team
+- Check in to events
+- Claim achievements
+- Verify attendance
+
+## QR Code Types
+
+LeagueLedger supports several types of QR codes:
+
+### Point Value Codes
+
+These codes represent specific point values that are awarded when scanned:
+
+- **Standard Points**: Fixed point values (e.g., 5, 10, 25 points)
+- **Variable Points**: Point values that may fluctuate based on factors like time, location, or number of scans
+- **Team-Specific Points**: Codes that only award points to specific teams
+
+### Functional Codes
+
+These codes trigger specific actions in the system:
+
+- **Check-In Codes**: For event attendance verification
+- **Achievement Codes**: Unlock specific achievements when scanned
+- **Registration Codes**: Link to team registration or event signup
+- **Information Codes**: Open detailed information about an event or challenge
+
+## Scanning QR Codes
+
+### Mobile Scanning
+
+To scan a QR code using a mobile device:
+
+1. Log in to LeagueLedger on your mobile browser
+2. Navigate to the "Scan" option in the menu
+3. Allow camera permissions if prompted
+4. Point your camera at the QR code
+5. The system will automatically detect and process the code
+6. A confirmation screen will display the points awarded or action taken
+
+### Desktop Scanning
+
+For desktop users with webcams:
+
+1. Log in to LeagueLedger
+2. Click on the "Scan QR Code" option in the navigation menu
+3. Allow camera permissions when prompted
+4. Position the QR code in front of your webcam
+5. The system will process the code once detected
+
+### Upload Scanning
+
+If you have a QR code image file:
+
+1. Go to the "Scan QR" page
+2. Select the "Upload QR Code Image" option
+3. Choose the image file from your device
+4. Submit the image for processing
+
+## Creating QR Codes (Administrators)
+
+Administrators can create QR codes through the admin panel:
+
+### Creating Individual QR Codes
+
+1. Navigate to the Admin Panel > QR Codes
+2. Click on "Create New QR Code"
+3. Fill in the required information:
+   - Point value
+   - Description
+   - Redemption limit (how many times it can be scanned)
+   - Expiration date (if applicable)
+   - Team restrictions (if applicable)
+4. Click "Generate Code"
+5. The new QR code will be displayed and added to the database
+
+### Creating QR Code Sets
+
+For organizing multiple codes together:
+
+1. Go to Admin Panel > QR Codes > QR Sets
+2. Select "Create New Set"
+3. Provide a name and description for the set
+4. Choose the number of codes to generate in this set
+5. Configure the point values (fixed, random, or custom distribution)
+6. Set any common properties (expiration, redemption limits)
+7. Generate the set
+
+### Printing QR Codes
+
+To print physical copies of QR codes:
+
+1. Go to Admin Panel > QR Codes or QR Sets
+2. Select the code(s) you wish to print
+3. Click "Print QR Codes"
+4. Choose the print format:
+   - Standard layout
+   - Compact grid
+   - Labels
+   - Individual cards
+5. Configure printing options (size, labels, etc.)
+6. Click "Generate Printable PDF"
+7. Print the generated document
+
+## Managing QR Codes
+
+### Monitoring Usage
+
+Track QR code usage through the Admin Panel:
+
+1. Go to Admin Panel > QR Codes
+2. View the list of codes with usage statistics
+3. Click on a specific code for detailed redemption history
+4. See who scanned the code, when, and how many points were awarded
+
+### Deactivating Codes
+
+To disable a QR code:
+
+1. Navigate to Admin Panel > QR Codes
+2. Find the code you wish to deactivate
+3. Click "Edit" or select the code
+4. Toggle the "Active" status to inactive
+5. Save changes
+
+The code will remain in the system for record-keeping but can no longer be redeemed.
+
+### Modifying Codes
+
+To change a QR code's properties:
+
+1. Go to Admin Panel > QR Codes
+2. Select the code to modify
+3. Click "Edit"
+4. Update the desired properties
+5. Save changes
+
+!!! warning "Active Codes"
+    Modifying the point value or redemption rules of already-distributed codes may cause confusion for users. Consider creating new codes instead of changing existing ones.
+
+## Best Practices
+
+### Security
+
+- **Regenerate Codes Regularly**: Create new QR codes for each event to prevent reuse
+- **Limit Redemptions**: Set appropriate scan limits to prevent abuse
+- **Verify Location**: For important events, consider enabling location verification
+- **Monitor Unusual Activity**: Check for patterns that might indicate QR code sharing
+
+### Organization
+
+- **Meaningful Names**: Use descriptive names for QR sets and codes
+- **Color Coding**: Consider printing different point values on different colored paper
+- **Tracking Identifiers**: Include visible IDs on printed codes for easy reference
+- **Backup Copies**: Maintain digital backups of all generated codes
+
+### Distribution
+
+- **Strategic Placement**: Place higher-value codes in less obvious locations
+- **Staffed Stations**: For high-value codes, consider having staff present
+- **Time-Limited Availability**: Make codes available only during specific periods
+- **Progressive Difficulty**: Structure code placement so finding codes gets progressively harder
+
+## Troubleshooting
+
+### Common Issues
+
+#### QR Code Not Scanning
+
+If a code isn't being recognized:
+
+- Ensure adequate lighting
+- Hold the device steady and at an appropriate distance
+- Make sure the code isn't damaged or obscured
+- Try using the image upload option instead
+
+#### Points Not Awarded
+
+If scanning succeeds but points aren't awarded:
+
+- Check if the user is logged in
+- Verify if the code has reached its redemption limit
+- Check if the code has expired
+- Confirm the user hasn't already scanned this code
+
+#### Printing Problems
+
+For issues with printed QR codes:
+
+- Ensure printer resolution is adequate (300 DPI minimum recommended)
+- Avoid scaling codes to very small sizes
+- Print test codes and verify they scan correctly before mass production
+- Use high-contrast printing (black on white background)
+
+## Use Cases and Examples
+
+### Hunt/Challenge Events
+
+Create a scavenger hunt by placing QR codes throughout a venue:
+
+- Place codes with varying point values in different locations
+- Create clues that lead participants to code locations
+- Track progress and award bonus points for completing the full hunt
+
+### Attendance Tracking
+
+Use QR codes for verifying attendance:
+
+- Generate unique check-in codes for each event
+- Place codes at event entrances
+- Have participants scan on arrival
+- Generate attendance reports from the admin panel
+
+### Reward Programs
+
+Implement a progressive reward system:
+
+- Issue QR codes for completing certain tasks
+- Create achievement sets that unlock when specific codes are collected
+- Offer special rewards for collecting complete sets
+
+## Next Steps
+
+- [Team Management](teams.md): Learn how teams accumulate and manage points
+- [Events](events.md): How to integrate QR codes with events
+- [Points & Achievements](points-and-achievements.md): More about the points system
+- [QR Code Management](../administration/qr-code-management.md): Advanced administration of QR codes

docs/user-guide/teams.md

@@ -0,0 +1,300 @@
+# Teams
+
+Teams are a core feature of LeagueLedger, allowing users to form groups that compete and collaborate. This guide explains how to create, join, and manage teams within the system.
+
+## Teams Overview
+
+In LeagueLedger, teams provide a way for users to:
+
+- Collaborate toward common goals
+- Compete against other teams
+- Share resources and achievements
+- Track collective progress
+
+Each team has:
+
+- A unique name and profile
+- A team owner (creator by default)
+- Team members with different roles
+- A team points total (sum of members' contributions)
+- Team-specific achievements and stats
+
+## Creating a Team
+
+### Basic Team Creation
+
+To create a new team:
+
+1. Log in to your LeagueLedger account
+2. Navigate to the "Teams" section from the main menu
+3. Click the "Create New Team" button
+4. Fill in the required information:
+   - Team name (unique within the system)
+   - Short description
+   - Team logo (optional)
+5. Select team visibility:
+   - Public: Visible to all users
+   - Private: Visible only to members and invitees
+6. Choose join settings:
+   - Open: Anyone can join
+   - Request: Users can request to join
+   - Invite-only: Only invited users can join
+7. Click "Create Team"
+
+You'll automatically become the team owner with full administrative privileges.
+
+### Team Settings
+
+After creating a team, you can configure additional settings:
+
+1. Go to your team page
+2. Click on "Team Settings" (visible to team owners and admins)
+3. Customize options such as:
+   - Banner image
+   - Team biography
+   - Contact information
+   - Social media links
+   - Team rules or guidelines
+
+## Joining Teams
+
+### Finding Teams to Join
+
+To discover teams you might want to join:
+
+1. Navigate to the "Teams" section
+2. Click on "Browse Teams" or "Join Team"
+3. Browse available teams with options to:
+   - Search by name or keywords
+   - Filter by various criteria
+   - Sort by size, activity, or points
+4. Click on any team to view its details
+
+### Joining an Open Team
+
+For teams with "Open" join settings:
+
+1. View the team details page
+2. Click the "Join Team" button
+3. You'll immediately be added as a member
+
+### Requesting to Join
+
+For teams with "Request" join settings:
+
+1. View the team details page
+2. Click "Request to Join"
+3. Optional: Add a short message to the team owner
+4. Submit your request
+5. Wait for approval from a team admin or owner
+6. You'll receive a notification when your request is approved or denied
+
+### Joining via Invitation
+
+If you receive a team invitation:
+
+1. Check your notifications or email for the invitation
+2. Click the invitation link
+3. Review the team details
+4. Click "Accept" to join or "Decline" to refuse
+
+## Team Roles and Management
+
+### Team Roles
+
+LeagueLedger teams have a hierarchy of roles:
+
+- **Owner**: The team creator with full control
+- **Admin**: Can manage members and some team settings
+- **Member**: Regular team participant
+- **Guest**: Limited temporary access (optional feature)
+
+### Team Member Management
+
+As a team owner or admin, you can manage team members:
+
+1. Go to your team page
+2. Click on "Manage Members"
+3. From this panel, you can:
+   - Invite new members
+   - Remove existing members
+   - Change member roles
+   - Review join requests
+   - Send team announcements
+
+### Transferring Ownership
+
+To transfer team ownership:
+
+1. Go to "Team Settings" > "Advanced"
+2. Select "Transfer Ownership"
+3. Choose a team member to become the new owner
+4. Confirm the transfer
+
+!!! warning "Irreversible Action"
+    Transferring ownership cannot be undone. The new owner will have complete control over the team.
+
+## Team Activities
+
+### Team Points
+
+Teams earn points when members:
+
+- Scan QR codes
+- Complete challenges
+- Participate in events
+- Earn achievements
+- Contribute through other scoring actions
+
+The team leaderboard reflects the cumulative points of all team members.
+
+### Team Achievements
+
+Teams can unlock special achievements based on:
+
+- Total team points milestones
+- Full team participation in events
+- Completing special team challenges
+- Consistent activity over time
+
+Team achievements are displayed on the team profile and contribute to the team's prestige.
+
+### Team Events
+
+Teams can participate in events together:
+
+1. Find an event in the "Events" section
+2. Register as a team (by team owner/admin)
+3. Coordinate team member participation
+4. Earn team points through event activities
+
+## Team Communication
+
+### Team Chat
+
+Teams have access to a built-in chat system:
+
+1. Go to your team page
+2. Click on the "Team Chat" tab
+3. Send messages visible to all team members
+4. Share updates, strategies, or coordinate activities
+
+### Announcements
+
+Team owners and admins can make official announcements:
+
+1. Go to "Manage Members"
+2. Select "Create Announcement"
+3. Write your message
+4. Choose notification options
+5. Publish to all members
+
+## Advanced Team Features
+
+### Team Statistics
+
+View detailed team performance:
+
+1. Go to your team page
+2. Select the "Statistics" tab
+3. Explore metrics such as:
+   - Points over time
+   - Member contributions
+   - Achievement progress
+   - Event participation
+   - Comparison with other teams
+
+### Team Challenges
+
+Some events feature special team challenges:
+
+- Collaborative tasks requiring multiple team members
+- Inter-team competitions
+- Timed challenges with team scoring
+- Special team-only QR codes
+
+### Private Team QR Codes
+
+Team owners can create team-specific QR codes:
+
+1. Go to "Team Settings" > "QR Codes"
+2. Select "Create Team QR"
+3. Configure the code settings
+4. Generate and share with team members only
+
+These codes may offer bonus points or special achievements when scanned by team members.
+
+## Leaving or Dissolving a Team
+
+### Leaving a Team
+
+To leave a team you're a member of:
+
+1. Go to the team page
+2. Click on "Team Settings" or "Manage Membership"
+3. Select "Leave Team"
+4. Confirm your decision
+
+!!! note "Team Owner"
+    If you're the team owner, you must first transfer ownership before leaving.
+
+### Dissolving a Team
+
+To completely dissolve a team (owner only):
+
+1. Go to "Team Settings" > "Advanced"
+2. Select "Dissolve Team"
+3. Read the warning about this irreversible action
+4. Enter your password to confirm
+5. The team will be permanently removed
+
+## Best Practices
+
+### For Team Owners
+
+- Establish clear team goals and guidelines
+- Regularly communicate with team members
+- Recognize individual contributions
+- Delegate responsibilities to trusted admins
+- Keep team information and graphics up-to-date
+
+### For Team Members
+
+- Regularly check team announcements
+- Coordinate with teammates for events
+- Share strategies for finding and scanning QR codes
+- Help recruit quality new members
+- Represent your team positively in competitions
+
+## Troubleshooting
+
+### Common Issues
+
+#### Can't Find a Team
+
+If you can't locate a specific team:
+- Check if you spelled the team name correctly
+- The team might be set to private visibility
+- The team may have been dissolved
+
+#### Can't Join a Team
+
+If you're unable to join:
+- The team might be invite-only
+- Your request might be pending approval
+- You may have reached the maximum number of teams you can join
+- The team might have reached its member capacity
+
+#### Points Not Showing for Team
+
+If points aren't appearing:
+- There may be a delay in point calculation
+- Verify that your individual points are displaying correctly
+- Check that you're properly affiliated with the team
+
+## Next Steps
+
+- [QR Codes](qr-codes.md): Learn how to earn points through QR codes
+- [Points & Achievements](points-and-achievements.md): Understand the points system
+- [Events](events.md): Discover how to participate in events as a team
+- [Team Management](../administration/team-management.md): For administrators managing multiple teams