d-back

📚 Documentation

Comprehensive documentation is available online in English, Spanish (Español), and German (Deutsch), including API reference, user guides, and examples.

Translations are automatically synchronized with Crowdin. The Crowdin Sync workflow uploads source files and downloads completed translations.

Quick Links

• English Documentation - Full documentation in English
• Spanish Documentation - Documentación completa en español
• German Documentation - Vollständige Dokumentation auf Deutsch

The documentation is available in multiple languages. Use the language selector in the navigation to switch between languages.

Building Documentation Locally

# Install documentation dependencies
pip install -e .[docs]

# Serve documentation locally with live reload (all languages)
mkdocs serve

# Build documentation (generates site/ directory with all languages)
mkdocs build

After running mkdocs serve, access the documentation at:

• English: http://127.0.0.1:8000/
• Spanish: http://127.0.0.1:8000/es/
• German: http://127.0.0.1:8000/de/

Note: The documentation uses mkdocs-static-i18n for multilingual support with the Material for MkDocs theme.

Welcome to d-back – the backend service that powers the magical d-zone ambient life simulation!

🎯 Project Overview

d-zone is an ambient life simulation where the presence and activity of users in a Discord server subtly influence a living digital environment. Think of it as a digital terrarium that reacts to your community's energy!

d-back serves as the intelligent bridge between Discord servers and the beautiful d-zone frontend. It provides real-time user data through WebSocket connections, creating an immersive experience where every Discord user becomes part of a living, breathing digital ecosystem.

Currently, d-back uses sophisticated mock data to simulate user activity, making it perfect for development, testing, and demonstration purposes.

✨ Features

• 🔌 WebSocket Server: Real-time communication with the d-zone frontend
• 👥 User Activity Simulation: Mock Discord user data with realistic presence states
• 🎨 Role Color Support: Beautiful user representation with Discord role colors
• 🌐 Multi-Server Support: Handle multiple Discord servers simultaneously
• 📊 Status Tracking: Monitor online, idle, DND, and offline user states
• 🔒 OAuth2 Ready: Built-in support for Discord OAuth2 authentication
• 📁 Static File Serving: Serve frontend assets directly from the backend
• 🚀 Easy Configuration: Simple command-line options and programmatic setup
• 🧪 Development Friendly: Comprehensive mock data for testing and development

🛠️ Installation

Step-by-Step Setup

1. Clone the repository:

   git clone https://github.com/NNTin/d-back.git
   cd d-back
   

2. Create a virtual environment (recommended):

   # On Windows
   python -m venv .venv
   .venv\Scripts\activate
   
   # On macOS/Linux
   python3 -m venv .venv
   source .venv/bin/activate
   

3. Install the package:

   # Install in development mode (recommended for contributors)
   pip install -e .
   
   # Or install directly from requirements
   pip install -r requirements.txt
   

4. Verify installation:

   d_back --version
   

🚀 Usage

Quick Start

The simplest way to get d-back running:

# Start the server with default settings (localhost:3000)
d_back

# Or run as a Python module
python -m d_back

Command Line Options

# Custom host and port
d_back --host 0.0.0.0 --port 8080

# Serve custom static files
d_back --static-dir ./my-frontend-build

# Get help
d_back --help

Programmatic Usage

Use d-back in your Python projects:

import asyncio
from d_back.server import WebSocketServer

async def main():
    # Create server instance
    server = WebSocketServer(port=3000, host="localhost")
    
    # Optional: Set up custom callbacks
    server.on_get_user_data = my_user_data_callback
    server.on_get_server_data = my_server_data_callback
    
    # Start the server
    print("Starting d-back server...")
    await server.start()

# Run the server
asyncio.run(main())

Testing the WebSocket Connection

You can test the server using any WebSocket client:

// JavaScript example for testing
const socket = new WebSocket('ws://localhost:3000');

socket.onopen = () => {
    console.log('Connected to d-back!');
    // Request user data for a mock server
    socket.send(JSON.stringify({
        type: 'get_user_data',
        serverId: '232769614004748288'
    }));
};

socket.onmessage = (event) => {
    const data = JSON.parse(event.data);
    console.log('Received:', data);
};

⚙️ Configuration

Command Line Arguments

Mock Server Configuration

d-back comes with pre-configured mock Discord servers for testing:

• d-world server (232769614004748288): Main development server with active users
• docs server (482241773318701056): Documentation server
• oauth2 server (123456789012345678): Protected server for OAuth testing
• my repos server (987654321098765432): Repository showcase server

Environment Variables

While d-back doesn't currently use environment variables for configuration, you can extend it easily:

import os
from d_back.server import WebSocketServer

# Example: Use environment variables
port = int(os.getenv('D_BACK_PORT', 3000))
host = os.getenv('D_BACK_HOST', 'localhost')

server = WebSocketServer(port=port, host=host)

Custom Data Providers

Replace mock data with your own:

from d_back.server import WebSocketServer

async def my_user_data_provider(server_id):
    # Your custom logic here
    return {
        "user123": {
            "uid": "user123",
            "username": "MyUser",
            "status": "online",
            "roleColor": "#ff6b6b"
        }
    }

server = WebSocketServer()
server.on_get_user_data = my_user_data_provider

📜 License

This project is licensed under the MIT License. See LICENSE for details.