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

```bash
# 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)

```bash
# 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:

```env
# 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

```bash
pytest
pytest --cov=app tests/
```

### Database Migrations

```bash
# Create migration
flask db migrate -m "Description"

# Apply migration
flask db upgrade

# Rollback
flask db downgrade
```

### Code Quality

```bash
# 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

```dockerfile
# 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