Backend Modules¶

Auth Module (`modules/auth/`)¶

Domain: - User entity (Hybrid Pattern with factory methods) - Tenant entity - Session entity - AuthRepositoryProtocol interface

Application: - LoginUseCase, RegisterUseCase, RefreshTokenUseCase - LogoutUseCase, VerifyEmailUseCase, ResetPasswordUseCase - Protocols: JWTServiceProtocol, PasswordServiceProtocol, SessionServiceProtocol, EmailServiceProtocol

Infrastructure: - UserModel, TenantModel, SessionModel (SQLModel) - SQLModelAuthRepository implementation - JWTService, PasswordService implementations

Presentation: - POST /api/v1/auth/register - POST /api/v1/auth/login - POST /api/v1/auth/refresh - POST /api/v1/auth/logout - POST /api/v1/auth/verify-email - POST /api/v1/auth/reset-password - GET /api/v1/auth/oauth/{provider}

Shipments Module (`modules/shipments/`)¶

Domain: - Shipment entity (frozen dataclass with create() factory) - Bag entity (frozen dataclass with create() factory) - Flight entity (frozen dataclass with create() factory) - FlightAlertSubscription entity - Enums: ShipmentStatus, PaymentStatus, BagStatus, FlightStatus

Application: - CreateShipmentUseCase, GetShipmentUseCase - UpdateShipmentUseCase, DeleteShipmentUseCase - AssignToBagUseCase, MarkDeliveredUseCase - SubscribeFlightAlertsUseCase, HandleFlightWebhookUseCase - FlightAlertServiceProtocol

Infrastructure: - ShipmentModel, BagModel, FlightModel, BagShipmentModel - FlightAlertSubscriptionModel - ShipmentRepository, BagRepository, FlightRepository - FlightAlertSubscriptionRepository - AviationstackClient (legacy polling API) - AeroDataBoxClient (Flight Alert webhook API)

Presentation: - GET/POST /api/v1/shipments - GET/PUT/DELETE /api/v1/shipments/{id} - GET/POST /api/v1/bags - GET/POST /api/v1/flights - POST /api/v1/flights/{id}/sync - GET /api/v1/track/{tracking_id} (public) - GET /api/v1/courier/bags - PUT /api/v1/courier/deliver/{shipment_id} - POST /api/v1/flights/webhook (AeroDataBox webhook receiver)

Notifications Module (`modules/notifications/`)¶

Domain: - NotificationEvent entity

Infrastructure: - RedisPubSubManager (pub/sub for multi-tenant messaging) - ConnectionManager (WebSocket connection management) - WhatsAppCloudAdapter (moved from core/integrations/) - EmailAdapter, FCMAdapter

Presentation: - WebSocket /ws/notifications - POST /api/v1/notifications/webhook/whatsapp

Core Modules¶

`core/config.py`¶

Environment configuration, multi-domain settings, rate limiting.

`core/database.py`¶

Async database engine, session management, RLS context manager.

`core/security/`¶

JWT service, password hashing, token encryption.

`core/versioning.py`¶

API version detection and DTO factory.

`shared/email/`¶

Cross-module transactional email functionality: - EmailServiceProtocol - Interface for email services - MockEmailProvider - Dev/testing (saves to logs/emails/) - ResendProvider - Production (Resend.com API) - SMTPProvider - Production (SMTP server)

Data Flow¶

Create Shipment Flow¶

Client → POST /api/v1/shipments
       → Route (presentation)
       → CreateShipmentUseCase (application)
       → ShipmentRepository interface (domain)
       → SQLModelShipmentRepository (infrastructure)
       → Database

Authentication Flow¶

Client → POST /api/v1/auth/login
       → Route (presentation)
       → LoginUseCase (application)
       → AuthRepository interface (domain)
       → SQLModelAuthRepository (infrastructure)
         → JWTService (create tokens)
         → PasswordService (verify password)
         → Database (verify credentials)
       → Response with tokens

Backend Modules¶

Auth Module (modules/auth/)¶

Shipments Module (modules/shipments/)¶

Notifications Module (modules/notifications/)¶