init — Facade module exposing shared cross-cutting concerns for the PocketPaw cloud ecosystem

This module serves as the public interface for shared utilities, services, and infrastructure used across the PocketPaw cloud platform. It acts as a barrel export that aggregates cross-cutting concerns—authentication, workspace management, event handling, licensing, and agent orchestration—making them discoverable and accessible to dependent modules. By centralizing these imports, it establishes clear dependencies and prevents circular import chains within the cloud subsystem.

Categories: architecture — module organization and facade patterns, dependency injection — fastapi and inversion of control, multi-tenancy — workspace scoping and data isolation, cross-cutting concerns — auth, errors, events shared across all features
Concepts: barrel_export_pattern, facade_pattern, multi_tenancy, workspace_scoping, dependency_injection, event_driven_architecture, cross_cutting_concerns, fastapi_dependencies, error_handling, authentication
Words: 1336 | Version: 1

Purpose

The shared/__init__.py module exists as a facade and aggregation point for infrastructure-level functionality that spans multiple business domains within PocketPaw’s cloud services. Rather than having individual feature modules (workspace, user, agent, etc.) discover and import their dependencies scattered across the codebase, this module curates and re-exports all common, reusable concerns.

This solves several architectural problems:

Dependency Clarity: Dependent code clearly sees what foundational services are available by importing from shared
Circular Import Prevention: By centralizing re-exports in one place, circular dependency chains are broken at the seam between feature layers
API Stability: The shared module acts as a contract—internal reorganizations don’t break downstream modules as long as re-exports remain stable
Onboarding: New developers understand the ecosystem immediately by seeing all shared primitives in one place

Key Components and Their Roles

Based on the import graph, this module aggregates these major concerns:

Foundational Infrastructure

errors: Custom exception hierarchy for cloud operations (authentication failures, workspace violations, etc.)
deps: FastAPI dependency injection layer; provides factories for injecting authenticated context, workspace scoping, and rate-limit quotas into route handlers

API Layer

router: FastAPI router definitions; aggregates all HTTP endpoints exposed by the cloud module

Core Domain Models

workspace: Workspace entity and workspace-scoped operations; represents the isolation boundary for multi-tenant data
user: User identity, authentication tokens, and user preferences
agent: AI agent definitions and agent lifecycle management
session: User session tracking and context propagation
license: Licensing and subscription state; controls feature access

Feature Domains

comment: Collaborative commenting on agents, workspaces, and artifacts
file: File storage and versioning within workspaces
group: User group management for RBAC within workspaces
invite: Workspace invitations and join flows
message: Direct messaging between agents and users
notification: Event-driven notifications (real-time alerts, digests)
pocket: Pocket objects (the primary business entity in PocketPaw)

Integration Points

agent_bridge: Bridges between cloud-hosted user data and external AI agent platforms
event_handlers: Event subscriptions and handlers; ties domain events to side effects (notifications, agent triggers, etc.)
core: Likely low-level utilities (validation, serialization, time handling)

How It Works

Import Resolution Flow

When a module outside shared/ (e.g., a route handler or a service class) needs access to cross-cutting concerns:

# Instead of:
from ee.cloud.errors import ValidationError
from ee.cloud.deps import get_current_user
from ee.cloud.workspace import WorkspaceService
# ... repeat for 10+ imports

# Developers write:
from ee.cloud.shared import (
    ValidationError,
    get_current_user,
    WorkspaceService,
    # ... all in one well-known location
)

Dependency Graph Structure

shared/__init__.py (THIS MODULE)
  ↓ (re-exports)
  ├─ errors → exception types consumed by all handlers
  ├─ deps → FastAPI dependency functions injected into route signatures
  ├─ workspace → workspace context injected by deps
  ├─ user → user context injected by deps
  ├─ license → checked by authorization decorators
  ├─ event_handlers → subscribed to domain events
  └─ ... (domain services)
  ↑ (imported by)
  ├─ api.handlers (HTTP route handlers)
  ├─ services (business logic)
  └─ tasks (background jobs)

Initialization Sequence

When the cloud module loads:

FastAPI application initializes
shared/__init__.py imports all sub-modules (errors, deps, router, etc.)
Dependency injection container is configured (in deps)
Event handlers register themselves (in event_handlers)
Routes are registered with the app (via router)
Workspace and user middleware inject context into request objects
Application is ready to serve requests

Authorization and Security

While this module doesn’t implement authorization itself, it serves as the collection point for security primitives:

user: Contains user identity and authentication token validation
session: Manages session expiration and revocation
license: Enforces feature access control (e.g., pro features only available to paid workspaces)
deps: Provides injectors like get_current_user() that middleware uses to authenticate requests
group: Enables RBAC (role-based access control) within workspaces
workspace: Enforces data isolation—one workspace cannot access another’s data

Security checks cascade: authentication (user) → session validation → workspace membership → feature licensing → RBAC (group/role).

Dependencies and Integration

What This Module Depends On

All the modules it imports (errors, router, workspace, etc.) are internal siblings within the cloud subsystem. They form a tightly coupled domain model—workspace operations require user context, notifications require event handlers, etc.

What Depends on This Module

Based on the import graph structure, this module is imported by:

HTTP Route Handlers: api.handlers modules use shared services and dependency injection
Background Job Processors: Async tasks use event handlers and workspace context
Tests: Test suites import shared fixtures, mocks, and service factories

Integration Pattern

The module follows the barrel export pattern:

# shared/__init__.py (THIS FILE)
"""Shared cross-cutting concerns for the PocketPaw cloud module."""
# Implicit re-exports via standard Python import mechanics

The single docstring signals intent: “this is a facade for shared infrastructure.” Dependent code then imports as:

from ee.cloud.shared import get_current_user, WorkspaceError

Internally, each imported submodule (e.g., errors.py, deps.py) is a focused, single-responsibility module.

Design Decisions

1. Minimal Module—Maximum Clarity

The __init__.py contains only a docstring and implicit re-exports. This is intentional:

No runtime logic or initialization code clutters the file
Import statements are self-documenting (the import list IS the API contract)
Changes to internal module organization don’t require code edits here (only structural reorganization)

2. Facade Over Inheritance

Instead of a base class that all services inherit from, the shared module aggregates services. This allows:

Services to be composed freely without coupling to a base hierarchy
Event handlers and dependencies to be injected rather than tightly coupled
Easier testing (mock any service by injecting a test double)

3. Workspace as the Data Isolation Boundary

Workspace appears prominently in the exports because it’s the multi-tenancy seam. Every feature (workspace, message, file, group, invite, notification) is workspace-scoped. By centralizing workspace as a shared concept, the module enforces consistent isolation across all domains.

4. Event-Driven Side Effects

event_handlers is exported alongside domain services because the architecture decouples triggering an event (e.g., “user added to group”) from handling it (“send notification”). Event handlers subscribe to domain events and perform side effects, reducing direct coupling between services.

5. Dependency Injection as a First-Class Concern

deps is a shared export because FastAPI route handlers rely on dependency injection for:

Current user context (populated by auth middleware)
Workspace scoping (populated by workspace middleware)
Database session lifecycle management This keeps route handlers thin and testable.

Concepts and Patterns

Barrel Export Pattern: Aggregate multiple submodules under a single public interface
Facade Pattern: Present a unified interface to a complex subsystem (errors, services, dependencies)
Multi-Tenancy via Workspace Scoping: Each operation is implicitly scoped to a workspace; data isolation is enforced at the domain layer
Dependency Injection: Services and context are injected into handlers, not instantiated globally
Event-Driven Architecture: Domain events trigger handlers asynchronously or synchronously
Cross-Cutting Concerns: Authentication, logging, validation, and error handling span all features; this module aggregates them
FastAPI Dependency Injection: Using FastAPI’s Depends() to inject authenticated context and workspace scope into route signatures

When to Use This Module

Starting a New Feature: Import shared services and dependency injectors as the foundation
Writing Route Handlers: Use deps to inject user and workspace context
Handling Domain Events: Subscribe to events in event_handlers and import event types
Testing: Mock services from shared and inject them into the code under test
Onboarding New Developers: This module is the map of the entire cloud subsystem’s infrastructure

What NOT to Do

Don’t add feature-specific code here: This module is for truly cross-cutting, infrastructure-level concerns only
Don’t instantiate services directly: Use dependency injection; let the deps layer manage lifecycles
Don’t bypass workspace scoping: Always enforce workspace boundaries; never query all workspaces in a request context
Don’t create new circular dependencies: If a sibling module (e.g., workspace.py) needs to import from another sibling (e.g., user.py), ensure no bidirectional imports exist; break cycles with interfaces or events

Last updated: April 29, 2026

5 min read

Edit this page

Was this page helpful?