System Architecture

Overview

Zou is built on Flask, a lightweight Python web framework, and follows a modular architecture that separates concerns into blueprints (routing), services (business logic), and models (data layer).

Core Components

Flask Application

The main application is initialized in zou/app/__init__.py and configured with:

Flask-SQLAlchemy - Database ORM for PostgreSQL
Flask-JWT-Extended - JWT token authentication
Flask-Principal - Role-based permissions
Flask-Migrate - Database schema migrations
Flask-Mail - Email notifications
Flasgger - OpenAPI/Swagger documentation

zou/app/__init__.py

app = Flask(__name__)
app.config.from_object(config)

db = SQLAlchemy(app)
migrate = Migrate(app, db)
jwt = JWTManager(app)
Principal(app)
mail = Mail()
mail.init_app(app)

Configuration

The application configuration is environment-driven through zou/app/config.py, supporting:

Authentication strategies (local, LDAP, SAML)
Database connection pooling
JWT token expiration
File storage backends (local, S3, Swift)
Email settings
Search indexer (Meilisearch)
Two-factor authentication enforcement

Key Configuration Options

AUTH_STRATEGY = "auth_local_classic"  # or auth_remote_ldap, auth_local_no_password
JWT_ACCESS_TOKEN_EXPIRES = timedelta(days=7)
JWT_REFRESH_TOKEN_EXPIRES = timedelta(days=15)

DATABASE = {
    "drivername": "postgresql+psycopg",
    "host": "localhost",
    "port": "5432",
    "username": "postgres",
    "password": "mysecretpassword",
    "database": "zoudb",
}

FS_BACKEND = "local"  # or "s3", "swift"
ENFORCE_2FA = False  # Require 2FA for all users

Blueprint Architecture

Zou uses Flask blueprints to organize routes into logical modules. Each blueprint handles a specific domain:

Blueprint Structure

zou/app/blueprints/
├── auth/          # Authentication & user session management
├── assets/        # Asset entity operations
├── shots/         # Shot entity operations
├── tasks/         # Task management
├── persons/       # User/person management
├── projects/      # Project operations
├── comments/      # Comments and reviews
├── files/         # File uploads and previews
├── playlists/     # Playlist management
├── events/        # Event streaming
├── crud/          # Generic CRUD operations
└── ...

Blueprint Registration

All blueprints are registered in zou/app/api.py:

zou/app/api.py

def configure_api_routes(app):
    app.register_blueprint(auth_blueprint)
    app.register_blueprint(assets_blueprint)
    app.register_blueprint(breakdown_blueprint)
    app.register_blueprint(chats_blueprint)
    app.register_blueprint(comments_blueprint)
    app.register_blueprint(crud_blueprint)
    # ... more blueprints

Example Blueprint

Each blueprint defines routes and maps them to resource classes:

zou/app/blueprints/auth/__init__.py

from flask import Blueprint

routes = [
    ("/auth/login", LoginResource),
    ("/auth/logout", LogoutResource),
    ("/auth/authenticated", AuthenticatedResource),
    ("/auth/refresh-token", RefreshTokenResource),
    ("/auth/totp", TOTPResource),
]

blueprint = Blueprint("auth", "auth")
api = configure_api_from_blueprint(blueprint, routes)

Service Layer

The service layer contains all business logic and sits between blueprints (controllers) and models (data layer).

Service Organization

zou/app/services/
├── auth_service.py           # Authentication logic
├── persons_service.py        # User management
├── projects_service.py       # Project operations
├── assets_service.py         # Asset operations
├── shots_service.py          # Shot operations
├── tasks_service.py          # Task management
├── files_service.py          # File handling
├── comments_service.py       # Comments and feedback
├── notifications_service.py  # Notification system
├── emails_service.py         # Email sending
└── ...

Service Pattern

Services provide reusable business logic functions:

# Example from base_service.py
def get_instance(model, instance_id, exception):
    """
    Get instance of any model from its ID and raise given exception if not found.
    """
    if instance_id is None:
        raise exception()
    
    try:
        instance = model.get(instance_id)
    except StatementError:
        raise exception()
    
    if instance is None:
        raise exception()
    
    return instance

Services are stateless and focus on business logic. They handle:

Data validation and transformation
Permission checks
Event emission
Cache management
External API calls

Data Flow

Request Lifecycle

HTTP Request arrives at a blueprint route
Route dispatches to a Resource class method (GET, POST, PUT, DELETE)
Resource validates input and calls service functions
Service performs business logic and database operations
Model interacts with PostgreSQL via SQLAlchemy
Response is serialized and returned as JSON

Database Layer

Base Model

All models inherit from BaseMixin which provides:

UUID primary keys
Audit timestamps (created_at, updated_at)
Common query methods (get, get_by, get_all)
CRUD operations (create, update, delete)
Serialization support

zou/app/models/base.py

class BaseMixin(object):
    id = db.Column(UUIDType(binary=False), primary_key=True, default=fields.gen_uuid)
    created_at = db.Column(db.DateTime, default=date_helpers.get_utc_now_datetime)
    updated_at = db.Column(db.DateTime, default=date_helpers.get_utc_now_datetime,
                          onupdate=date_helpers.get_utc_now_datetime)
    
    @classmethod
    def get(cls, id):
        return db.session.get(cls, id)
    
    @classmethod
    def create(cls, **kw):
        instance = cls(**kw)
        db.session.add(instance)
        db.session.commit()
        return instance

Connection Pooling

Zou uses SQLAlchemy’s connection pooling for performance:

SQLALCHEMY_ENGINE_OPTIONS = {
    "pool_size": 30,           # Max persistent connections
    "max_overflow": 60,        # Additional connections when pool exhausted
    "pool_pre_ping": True,     # Verify connections before use
    "pool_recycle": 3600,      # Recycle connections after 1 hour
    "pool_reset_on_return": "commit",  # Clean up transaction state
}

Caching Strategy

Zou uses Redis for caching frequently accessed data:

Memoization - Function result caching with TTL
Auth tokens - JWT token blacklist for logout
User data - Current user profile caching
Project data - Active project information

from zou.app.utils import cache

@cache.cache.memoize(120)  # Cache for 2 minutes
def get_project(project_id):
    return Project.get(project_id).serialize()

Event System

Zou emits events for major operations, allowing plugins and external systems to react:

from zou.app.utils import events

events.emit(
    "task:status-changed",
    {"task_id": task.id, "new_status_id": status.id},
    project_id=task.project_id
)

Events are processed asynchronously and can trigger:

Email notifications
Slack/Discord messages
Webhook calls to external systems
Status automations
Search index updates

Extensions & Integrations

Search Indexing

Zou integrates with Meilisearch for full-text search:

INDEXER = {
    "host": "localhost",
    "port": "7700",
    "protocol": "http",
    "key": os.getenv("INDEXER_KEY"),
}

File Storage

Supports multiple storage backends:

Local filesystem - Default for development
Amazon S3 - Scalable cloud storage
OpenStack Swift - Object storage

Authentication Providers

Local - Built-in password authentication
LDAP/Active Directory - Enterprise directory integration
SAML SSO - Single sign-on support
Two-Factor Auth - TOTP, Email OTP, FIDO2/WebAuthn

Scalability Considerations

Horizontal Scaling

Zou can be scaled horizontally by:

Load balancing multiple Flask instances
Shared Redis for cache and sessions
PostgreSQL read replicas for read-heavy workloads
CDN for static file delivery
Background workers for async tasks (email, exports)

Performance Optimization

Database query optimization with indexes
N+1 query prevention with eager loading
Response caching with Redis
Connection pooling for database
Pagination for large result sets
Thumbnail generation for preview files

Next Steps

Data Model

Explore the core entities and their relationships

Authentication

Learn about JWT tokens and auth strategies

Permissions

Understand role-based access control

API Reference

Browse the complete API documentation

Get Started

Core Concepts

Configuration

CLI Reference

Overview

Core Components

Flask Application

Configuration

Blueprint Architecture

Blueprint Structure

Blueprint Registration

Example Blueprint

Service Layer

Service Organization

Service Pattern

Data Flow

Request Lifecycle

Database Layer

Base Model

Connection Pooling

Caching Strategy

Event System

Extensions & Integrations

Search Indexing

File Storage

Authentication Providers

Scalability Considerations

Next Steps

Data Model

Authentication

Permissions

API Reference

Build docs developers (and LLMs) love

Get Started

Core Concepts

Configuration

CLI Reference

Documentation Index

​Overview

​Core Components

​Flask Application

​Configuration

​Blueprint Architecture

​Blueprint Structure

​Blueprint Registration

​Example Blueprint

​Service Layer

​Service Organization

​Service Pattern

​Data Flow

​Request Lifecycle

​Database Layer

​Base Model

​Connection Pooling

​Caching Strategy

​Event System

​Extensions & Integrations

​Search Indexing

​File Storage

​Authentication Providers

​Scalability Considerations

​Next Steps

Data Model

Authentication

Permissions

API Reference

Build docs developers (and LLMs) love

Overview

Core Components

Flask Application

Configuration

Blueprint Architecture

Blueprint Structure

Blueprint Registration

Example Blueprint

Service Layer

Service Organization

Service Pattern

Data Flow

Request Lifecycle

Database Layer

Base Model

Connection Pooling

Caching Strategy

Event System

Extensions & Integrations

Search Indexing

File Storage

Authentication Providers

Scalability Considerations

Next Steps