Initial commit: Quality App v2 - FG Scan Module with Reports

2026-01-25 22:25:18 +02:00
commit 3c5a273a89
66 changed files with 15368 additions and 0 deletions
--- a/documentation/ARCHITECTURE.md
+++ b/documentation/ARCHITECTURE.md
@@ -0,0 +1,492 @@
+# Quality App v2 - Architecture & Development Guide
+
+## Architecture Overview
+
+Quality App v2 is built on a modular, scalable Flask architecture with the following design principles:
+
+### Layered Architecture
+
+```
+┌─────────────────────────────────────┐
+│     User Interface (Templates)      │  Jinja2 Templates, HTML/CSS/JS
+├─────────────────────────────────────┤
+│      Flask Routes & Views           │  Route handlers, request processing
+├─────────────────────────────────────┤
+│    Business Logic & Services        │  Authentication, authorization
+├─────────────────────────────────────┤
+│    Database Layer (Models)          │  Direct SQL queries with pooling
+├─────────────────────────────────────┤
+│    External Services (MariaDB)      │  Persistent data storage
+└─────────────────────────────────────┘
+```
+
+## Application Initialization Flow
+
+1. **App Factory** (`app/__init__.py`)
+   - Creates Flask application instance
+   - Loads configuration
+   - Initializes logging
+   - Registers blueprints
+   - Sets up error handlers
+   - Configures request/response handlers
+
+2. **Configuration Loading** (`app/config.py`)
+   - Loads environment variables
+   - Sets Flask configuration
+   - Manages different environments (dev, test, prod)
+
+3. **Database Initialization** (`app/database.py`)
+   - Creates connection pool
+   - Manages connections
+   - Executes queries safely
+
+4. **Route Registration**
+   - Main routes (login, dashboard, logout)
+   - Module routes (quality, settings)
+   - Error handlers
+
+## Authentication Flow
+
+```
+User Input
+    ↓
+Login Form POST
+    ↓
+authenticate_user() in auth.py
+    ↓
+Query User from Database
+    ↓
+Verify Password Hash
+    ↓
+Store in Session
+    ↓
+Redirect to Dashboard
+```
+
+### Password Security
+
+- Passwords hashed using SHA256
+- Salt-based hashing recommended for production
+- Never stored in plain text
+- Separate credentials table for additional security
+
+## Database Connection Management
+
+### Connection Pooling
+
+- Uses `DBUtils.PooledDB` for connection pooling
+- Prevents connection exhaustion
+- Automatic connection recycling
+- Thread-safe operations
+
+```python
+# Connection flow:
+get_db() → Check if connection exists in g
+         → Get from pool if not
+         → Return connection
+         
+close_db() → Called on request teardown
+          → Returns connection to pool
+```
+
+## Module Architecture
+
+### Module Structure
+
+Each module follows this pattern:
+
+```
+app/modules/[module_name]/
+├── __init__.py           # Package initialization
+└── routes.py             # Module routes and views
+```
+
+### Adding a New Module
+
+1. Create module directory:
+   ```bash
+   mkdir app/modules/new_module
+   ```
+
+2. Create `__init__.py`:
+   ```python
+   # Module initialization
+   ```
+
+3. Create `routes.py`:
+   ```python
+   from flask import Blueprint
+   
+   new_module_bp = Blueprint('new_module', __name__, url_prefix='/new-module')
+   
+   @new_module_bp.route('/', methods=['GET'])
+   def index():
+       return render_template('modules/new_module/index.html')
+   ```
+
+4. Register in `app/__init__.py`:
+   ```python
+   from app.modules.new_module.routes import new_module_bp
+   app.register_blueprint(new_module_bp)
+   ```
+
+5. Create templates in `app/templates/modules/new_module/`
+
+## Request/Response Lifecycle
+
+```
+Request Received
+    ↓
+check_license_middleware() [if applicable]
+    ↓
+check_authentication() [before_request]
+    ↓
+Route Handler Execution
+    ↓
+Template Rendering / JSON Response
+    ↓
+after_request() processing
+    ↓
+close_db() [teardown]
+    ↓
+Response Sent
+```
+
+## Template Hierarchy
+
+### Base Template (`base.html`)
+- Navigation bar (except on login page)
+- Flash message display
+- Main content area
+- Footer
+- Script includes
+
+### Child Templates
+All pages extend `base.html`:
+
+```html
+{% extends "base.html" %}
+
+{% block title %}Page Title{% endblock %}
+
+{% block extra_css %}
+<!-- Page-specific CSS -->
+{% endblock %}
+
+{% block content %}
+<!-- Page content -->
+{% endblock %}
+
+{% block extra_js %}
+<!-- Page-specific JS -->
+{% endblock %}
+```
+
+## Static Files Organization
+
+### CSS
+- `base.css` - Common styles, responsive design
+- `login.css` - Login page specific styles
+- Module-specific CSS can be added as needed
+
+### JavaScript
+- `base.js` - Common utilities, bootstrap initialization
+- Module-specific JS can be added as needed
+
+### Images
+- Logo files
+- Module icons
+- User avatars (future enhancement)
+
+## Database Schema
+
+### Users Table
+```sql
+CREATE TABLE users (
+    id INT PRIMARY KEY AUTO_INCREMENT,
+    username VARCHAR(255) UNIQUE,
+    email VARCHAR(255),
+    full_name VARCHAR(255),
+    role VARCHAR(50),
+    is_active TINYINT(1),
+    created_at TIMESTAMP,
+    updated_at TIMESTAMP
+);
+```
+
+### User Credentials Table
+```sql
+CREATE TABLE user_credentials (
+    id INT PRIMARY KEY AUTO_INCREMENT,
+    user_id INT FOREIGN KEY,
+    password_hash VARCHAR(255),
+    created_at TIMESTAMP,
+    updated_at TIMESTAMP
+);
+```
+
+### Quality Inspections Table
+```sql
+CREATE TABLE quality_inspections (
+    id INT PRIMARY KEY AUTO_INCREMENT,
+    inspection_type VARCHAR(100),
+    status VARCHAR(50),
+    inspector_id INT FOREIGN KEY,
+    inspection_date DATETIME,
+    notes TEXT,
+    created_at TIMESTAMP,
+    updated_at TIMESTAMP
+);
+```
+
+### Application Settings Table
+```sql
+CREATE TABLE application_settings (
+    id INT PRIMARY KEY AUTO_INCREMENT,
+    setting_key VARCHAR(255) UNIQUE,
+    setting_value LONGTEXT,
+    setting_type VARCHAR(50),
+    created_at TIMESTAMP,
+    updated_at TIMESTAMP
+);
+```
+
+## Error Handling
+
+### Error Pages
+- `404.html` - Page not found
+- `500.html` - Internal server error
+- `403.html` - Access forbidden
+
+### Error Handlers
+```python
+@app.errorhandler(404)
+def page_not_found(e):
+    return render_template('errors/404.html'), 404
+```
+
+## Logging
+
+### Configuration
+- Location: `/app/data/logs/app.log`
+- Format: `timestamp - logger - level - message`
+- Rotating file handler (10 files, 10MB each)
+- Configurable log level via environment variable
+
+### Usage
+```python
+import logging
+logger = logging.getLogger(__name__)
+
+logger.info("Information message")
+logger.warning("Warning message")
+logger.error("Error message")
+```
+
+## Configuration Management
+
+### Development vs Production
+
+```python
+class DevelopmentConfig(Config):
+    DEBUG = True
+    SESSION_COOKIE_SECURE = False
+
+class ProductionConfig(Config):
+    DEBUG = False
+    SESSION_COOKIE_SECURE = True
+```
+
+### Environment Variables
+All sensitive configuration through `.env`:
+- Database credentials
+- Flask secret key
+- API keys (future)
+- Feature flags
+
+## Security Considerations
+
+### Implemented
+- ✅ CSRF protection (Flask default)
+- ✅ SQL injection prevention (parameterized queries)
+- ✅ Secure password hashing
+- ✅ Session security (HTTPOnly cookies)
+- ✅ Authentication on protected routes
+
+### Recommended for Production
+- 🔒 HTTPS/TLS
+- 🔒 Content Security Policy (CSP) headers
+- 🔒 CORS configuration
+- 🔒 Rate limiting
+- 🔒 Audit logging
+- 🔒 Two-factor authentication
+
+## Testing Strategy
+
+### Unit Tests (Future)
+```python
+# tests/test_auth.py
+def test_authenticate_user_valid_credentials():
+    # Test successful authentication
+
+def test_authenticate_user_invalid_password():
+    # Test password validation
+```
+
+### Integration Tests (Future)
+```python
+# tests/test_routes.py
+def test_login_page_loads():
+    # Test login page accessibility
+
+def test_dashboard_requires_authentication():
+    # Test authentication requirement
+```
+
+## Performance Optimization
+
+### Database
+- Connection pooling
+- Query optimization
+- Indexed lookups
+- Prepared statements
+
+### Frontend
+- Bootstrap CDN (cached by browser)
+- Minified CSS/JS
+- Image optimization
+
+### Application
+- Request/response compression
+- Caching headers
+- Session caching
+
+## Docker Deployment Considerations
+
+### Multi-stage Build (Future Enhancement)
+```dockerfile
+# Builder stage
+FROM python:3.11 AS builder
+# ... build dependencies ...
+
+# Runtime stage
+FROM python:3.11-slim
+# ... copy only necessary files ...
+```
+
+### Security Best Practices
+- Non-root user (future enhancement)
+- Health checks configured
+- Minimal base image
+- No unnecessary packages
+
+## Git Workflow
+
+### Branching Strategy
+```
+main (production)
+  ↑
+develop (staging)
+  ↑
+feature/* (development)
+```
+
+### Commit Messages
+```
+[type]: [description]
+
+Types: feat, fix, docs, style, refactor, test, chore
+```
+
+## Deployment Pipeline
+
+1. **Development** → Push to feature branch
+2. **Testing** → Merge to develop, run tests
+3. **Staging** → Deploy to staging environment
+4. **Production** → Merge to main, deploy
+
+## Monitoring & Logging
+
+### Application Logs
+- Location: `/app/data/logs/app.log`
+- Includes: Errors, warnings, info messages
+- Rotation: 10 files x 10MB
+
+### Database Logs
+- Enable in MariaDB: `general_log = 1`
+- Monitor slow queries: `slow_query_log = 1`
+
+### Container Health
+```bash
+docker-compose ps  # View health status
+```
+
+## Scaling Strategies
+
+### Horizontal Scaling
+1. Load balancer (Nginx/HAProxy)
+2. Multiple app instances
+3. Shared database
+
+### Vertical Scaling
+1. Increase container resources
+2. Optimize database queries
+3. Add caching layer
+
+## Documentation Standards
+
+### Docstrings
+```python
+def function_name(param1, param2):
+    """
+    Short description.
+    
+    Longer description if needed.
+    
+    Args:
+        param1: Description
+        param2: Description
+    
+    Returns:
+        Description of return value
+    """
+    pass
+```
+
+### Comments
+- Explain WHY, not WHAT
+- Use for complex logic
+- Keep up-to-date
+
+## Code Style
+
+### Python (PEP 8)
+- 4 spaces indentation
+- Max line length 100 characters
+- Meaningful variable names
+- Docstrings for public functions
+
+### HTML/CSS/JavaScript
+- 4 spaces indentation
+- Semantic HTML
+- BEM naming for CSS classes
+- ES6+ JavaScript
+
+## Future Architecture Enhancements
+
+1. **API Layer** - REST API for mobile apps
+2. **Caching** - Redis for session/query caching
+3. **Queue System** - Celery for async tasks
+4. **Microservices** - Separate services for scaling
+5. **Monitoring** - Prometheus + Grafana
+6. **Message Queue** - RabbitMQ/Kafka
+7. **Search Engine** - Elasticsearch
+8. **CDN** - Static file distribution
+
+## References
+
+- Flask Documentation: https://flask.palletsprojects.com/
+- SQLAlchemy (for future migration): https://www.sqlalchemy.org/
+- Bootstrap 5: https://getbootstrap.com/
+- MariaDB: https://mariadb.com/kb/
+- Docker: https://docs.docker.com/