# 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/