digiserver-v2/BLUEPRINT_GUIDE.md

Blueprint Architecture - Quick Reference

📦 Blueprint Structure

app/
├── blueprints/
│   ├── __init__.py        # Package initialization
│   ├── main.py            # Dashboard, health check
│   ├── auth.py            # Login, register, logout
│   ├── admin.py           # Admin panel, user management
│   ├── players.py         # Player CRUD, fullscreen view
│   ├── groups.py          # Group management, assignments
│   ├── content.py         # Media upload, file management
│   └── api.py             # REST API endpoints

---

🔗 URL Mapping

Main Blueprint (/)

• GET / - Dashboard with statistics
• GET /health - Health check (database, disk)

Auth Blueprint (/auth)

• GET /auth/login - Login page
• POST /auth/login - Process login
• GET /auth/logout - Logout
• GET /auth/register - Register page
• POST /auth/register - Process registration
• GET /auth/change-password - Change password page
• POST /auth/change-password - Update password

Admin Blueprint (/admin)

• GET /admin/ - Admin panel
• POST /admin/user/create - Create user
• POST /admin/user/<id>/role - Change user role
• POST /admin/user/<id>/delete - Delete user
• POST /admin/theme - Change theme
• POST /admin/logo/upload - Upload logo
• POST /admin/logs/clear - Clear logs
• GET /admin/system/info - System info (JSON)

Players Blueprint (/players)

• GET /players/ - List all players
• GET /players/add - Add player page
• POST /players/add - Create player
• GET /players/<id>/edit - Edit player page
• POST /players/<id>/edit - Update player
• POST /players/<id>/delete - Delete player
• POST /players/<id>/regenerate-auth - Regenerate auth code
• GET /players/<id> - Player page
• GET /players/<id>/fullscreen - Player fullscreen view
• POST /players/<id>/reorder - Reorder content
• POST /players/bulk/delete - Bulk delete players
• POST /players/bulk/assign-group - Bulk assign to group

Groups Blueprint (/groups)

• GET /groups/ - List all groups
• GET /groups/create - Create group page
• POST /groups/create - Create group
• GET /groups/<id>/edit - Edit group page
• POST /groups/<id>/edit - Update group
• POST /groups/<id>/delete - Delete group
• GET /groups/<id>/manage - Manage group page
• GET /groups/<id>/fullscreen - Group fullscreen view
• POST /groups/<id>/add-player - Add player to group
• POST /groups/<id>/remove-player/<player_id> - Remove player
• POST /groups/<id>/add-content - Add content to group
• POST /groups/<id>/remove-content/<content_id> - Remove content
• POST /groups/<id>/reorder-content - Reorder content
• GET /groups/<id>/stats - Group statistics (JSON)

Content Blueprint (/content)

• GET /content/ - List all content
• GET /content/upload - Upload page
• POST /content/upload - Upload file
• GET /content/<id>/edit - Edit content page
• POST /content/<id>/edit - Update content
• POST /content/<id>/delete - Delete content
• POST /content/bulk/delete - Bulk delete content
• GET /content/upload-progress/<upload_id> - Upload progress (JSON)
• GET /content/preview/<id> - Preview content
• GET /content/<id>/download - Download content
• GET /content/statistics - Content statistics (JSON)
• GET /content/check-duplicates - Check duplicates (JSON)
• GET /content/<id>/groups - Content groups info (JSON)

API Blueprint (/api)

• GET /api/health - API health check
• GET /api/playlists/<player_id> - Get player playlist (auth required)
• POST /api/player-feedback - Submit player feedback (auth required)
• GET /api/player-status/<player_id> - Get player status
• GET /api/upload-progress/<upload_id> - Get upload progress
• GET /api/system-info - System statistics
• GET /api/groups - List all groups
• GET /api/content - List all content
• GET /api/logs - Get server logs (query params: limit, level, since)

---

🔒 Authentication & Authorization

Login Required

Most routes require authentication via @login_required decorator:

from flask_login import login_required

@players_bp.route('/')
@login_required
def players_list():
    # Route logic

Admin Required

Admin routes use custom @admin_required decorator:

from app.blueprints.admin import admin_required

@admin_bp.route('/')
@login_required
@admin_required
def admin_panel():
    # Route logic

API Authentication

API routes use @verify_player_auth for player authentication:

from app.blueprints.api import verify_player_auth

@api_bp.route('/playlists/<int:player_id>')
@verify_player_auth
def get_player_playlist(player_id):
    # Access authenticated player via request.player

---

🚀 Performance Features

Caching

Routes with caching enabled:

• Dashboard: 60 seconds
• Player playlist: 5 minutes (memoized function)

Clear cache on data changes:

from app.extensions import cache

# Clear specific memoized function
cache.delete_memoized(get_player_playlist, player_id)

# Clear all cache
cache.clear()

Rate Limiting

API endpoints have rate limiting:

@api_bp.route('/playlists/<int:player_id>')
@rate_limit(max_requests=30, window=60)  # 30 requests per minute
def get_player_playlist(player_id):
    # Route logic

---

🎨 Template Usage

URL Generation

Always use blueprint-qualified names in templates:

Old (v1):

<a href="{{ url_for('login') }}">Login</a>
<a href="{{ url_for('dashboard') }}">Dashboard</a>
<a href="{{ url_for('add_player') }}">Add Player</a>

New (v2):

<a href="{{ url_for('auth.login') }}">Login</a>
<a href="{{ url_for('main.dashboard') }}">Dashboard</a>
<a href="{{ url_for('players.add_player') }}">Add Player</a>

Context Processors

Available in all templates:

• server_version - Server version string
• build_date - Build date string
• logo_exists - Boolean, whether custom logo exists
• theme - Current theme ('light' or 'dark')

---

📝 Common Patterns

Creating a New Route

1. Choose the appropriate blueprint based on functionality
2. Add the route with proper decorators:

@blueprint_name.route('/path', methods=['GET', 'POST'])
@login_required  # If authentication needed
def route_name():
    try:
        # Route logic
        log_action('info', 'Success message')
        flash('Success message', 'success')
        return redirect(url_for('blueprint.route'))
    except Exception as e:
        db.session.rollback()
        log_action('error', f'Error: {str(e)}')
        flash('Error message', 'danger')
        return redirect(url_for('blueprint.route'))

Adding Caching

For view caching:

@cache.cached(timeout=60, key_prefix='my_key')
def my_route():
    # Route logic

For function memoization:

@cache.memoize(timeout=300)
def my_function(param):
    # Function logic

API Response Format

Consistent JSON responses:

# Success
return jsonify({
    'success': True,
    'data': {...}
})

# Error
return jsonify({
    'error': 'Error message'
}), 400

---

🔧 Extension Access

Import extensions from centralized location:

from app.extensions import db, bcrypt, cache, login_manager

Never initialize extensions directly in blueprints - they're initialized in extensions.py and registered in app.py.

---

🧪 Testing Routes

Manual Testing

# Start development server
flask run

# Test specific blueprint
curl http://localhost:5000/api/health
curl http://localhost:5000/health

# Test authenticated route
curl -H "Authorization: Bearer <auth_code>" http://localhost:5000/api/playlists/1

Unit Testing

def test_dashboard(client, auth):
    auth.login()
    response = client.get('/')
    assert response.status_code == 200

---

📊 Blueprint Registration

Blueprints are registered in app/app.py:

def register_blueprints(app: Flask) -> None:
    """Register all blueprints."""
    from app.blueprints.main import main_bp
    from app.blueprints.auth import auth_bp
    from app.blueprints.admin import admin_bp
    from app.blueprints.players import players_bp
    from app.blueprints.groups import groups_bp
    from app.blueprints.content import content_bp
    from app.blueprints.api import api_bp
    
    app.register_blueprint(main_bp)
    app.register_blueprint(auth_bp)
    app.register_blueprint(admin_bp)
    app.register_blueprint(players_bp)
    app.register_blueprint(groups_bp)
    app.register_blueprint(content_bp)
    app.register_blueprint(api_bp)

---

✅ Checklist for Adding New Features

• Choose appropriate blueprint
• Add route with proper decorators
• Implement error handling (try/except)
• Add logging with log_action()
• Add flash messages for user feedback
• Clear cache if data changes
• Add type hints to parameters
• Update this documentation
• Add unit tests
• Test manually in browser/API client

---

This architecture provides:

• ✅ Separation of concerns - Each blueprint handles specific functionality
• ✅ Scalability - Easy to add new blueprints
• ✅ Maintainability - Clear organization and naming
• ✅ Performance - Built-in caching and optimization
• ✅ Security - Proper authentication and authorization
• ✅ API-first - RESTful API alongside web interface