digiserver-v2/README.md

DigiServer v2 - Blueprint Architecture

Modern Flask application with blueprint architecture, designed for scalability and maintainability.

🎯 Project Goals

• Modular Architecture: Blueprints for better code organization
• Scalability: Redis caching, Celery background tasks
• Security: Input validation, rate limiting, CSRF protection
• Performance: Optimized Docker image, database indexes
• Maintainability: Type hints, comprehensive tests, clear documentation

📁 Project Structure

digiserver-v2/
├── app/
│   ├── app.py                  # Application factory
│   ├── config.py               # Environment-based configuration
│   ├── extensions.py           # Flask extensions
│   ├── blueprints/
│   │   ├── __init__.py
│   │   ├── main.py            # Dashboard & home
│   │   ├── auth.py            # Authentication
│   │   ├── admin.py           # Admin panel
│   │   ├── players.py         # Player management
│   │   ├── groups.py          # Group management
│   │   ├── content.py         # Media upload & management
│   │   └── api.py             # REST API endpoints
│   ├── models/
│   │   ├── __init__.py
│   │   ├── user.py
│   │   ├── player.py
│   │   ├── group.py
│   │   ├── content.py
│   │   ├── player_feedback.py
│   │   └── server_log.py
│   ├── utils/
│   │   ├── __init__.py
│   │   ├── logger.py
│   │   ├── uploads.py
│   │   ├── decorators.py
│   │   └── validators.py
│   ├── templates/
│   │   ├── base.html
│   │   ├── auth/
│   │   ├── admin/
│   │   ├── players/
│   │   ├── groups/
│   │   └── errors/
│   └── static/
│       ├── css/
│       ├── js/
│       ├── uploads/
│       └── resurse/
├── tests/
│   ├── __init__.py
│   ├── conftest.py
│   ├── test_auth.py
│   ├── test_players.py
│   └── test_api.py
├── docker-compose.yml
├── Dockerfile
├── requirements.txt
├── .env.example
└── README.md

🚀 Quick Start

Development

# Clone the repository
git clone <repository-url>
cd digiserver-v2

# Create virtual environment
python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Set up environment variables
cp .env.example .env
# Edit .env with your settings

# Initialize database
flask init-db
flask create-admin

# Run development server
flask run

Docker (Production)

# Build and start containers
docker compose up -d

# View logs
docker compose logs -f

# Stop containers
docker compose down

🔧 Configuration

Configuration is environment-based (development, production, testing).

Environment Variables

Create a .env file:

# Flask
FLASK_ENV=production
SECRET_KEY=your-secret-key-here

# Database
DATABASE_URL=sqlite:///instance/dashboard.db

# Redis
REDIS_HOST=redis
REDIS_PORT=6379

# Admin Defaults
ADMIN_USER=admin
ADMIN_PASSWORD=secure-password

# Optional
SENTRY_DSN=your-sentry-dsn

📊 Features

Current (v2.0.0)

• ✅ Blueprint architecture
• ✅ Environment-based configuration
• ✅ User authentication & authorization
• ✅ Admin panel
• ✅ Player management
• ✅ Group management
• ✅ Content upload & management
• ✅ REST API
• ✅ Redis caching (production)
• ✅ Health check endpoint

Planned

• ⏳ Celery background tasks
• ⏳ Rate limiting
• ⏳ API authentication (JWT)
• ⏳ Unit & integration tests
• ⏳ API documentation (Swagger)
• ⏳ Monitoring & metrics (Prometheus)

🛠️ Development

Running Tests

pytest
pytest --cov=app tests/

Database Migrations

# Create migration
flask db migrate -m "Description"

# Apply migration
flask db upgrade

# Rollback
flask db downgrade

Code Quality

# Format code
black app/

# Lint
flake8 app/
pylint app/

# Type check
mypy app/

📖 API Documentation

Authentication

All API endpoints require authentication via session or API key.

Endpoints

• GET /api/playlists - Get playlist for player
• POST /api/player-feedback - Submit player feedback
• GET /health - Health check

See /docs for full API documentation (Swagger UI).

🔒 Security

• CSRF protection enabled
• Rate limiting on API endpoints
• Input validation using Marshmallow
• SQL injection prevention (SQLAlchemy ORM)
• XSS prevention (Jinja2 autoescaping)
• Secure password hashing (bcrypt)

📈 Performance

• Redis caching for frequently accessed data
• Database indexes on foreign keys
• Lazy loading for relationships
• Static file compression (nginx)
• Multi-stage Docker build (~800MB)

🐳 Docker

Multi-stage Build

# Build stage (heavy dependencies)
FROM python:3.11-slim as builder
# ... build dependencies

# Runtime stage (slim)
FROM python:3.11-slim
# ... only runtime dependencies

Docker Compose Services

• digiserver: Main Flask application
• redis: Cache and session storage
• worker: Celery background worker (optional)
• nginx: Reverse proxy (production)

📝 Migration from v1

See MIGRATION.md for detailed migration guide from digiserver v1.

Key differences:

• Blueprint-based routing instead of monolithic app.py
• Environment-based configuration
• Redis caching in production
• Improved error handling
• Type hints throughout codebase

🤝 Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📄 License

This project is part of the DigiServer digital signage system.

🙏 Acknowledgments

• Built with Flask and modern Python practices
• Inspired by Flask best practices and 12-factor app principles
• Based on lessons learned from DigiServer v1

📞 Support

For issues and feature requests, please use the GitHub issue tracker.

---

Status: 🚧 Work in Progress - Blueprint architecture implementation
Version: 2.0.0-alpha
Last Updated: 2025-11-12