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)

Scans Module (`modules/scans/`)¶

Domain: - Scan entity (frozen dataclass with create() factory) - ScanValidationResult enum (valid, hmac_invalid, wrong_tenant, entity_not_found, qr_decode_error, rate_limited) - ScanRepository interface

Application: - CreateScanUseCase - Creates scan with HMAC-SHA256 validation, rate limiting (100/hour) - GetScansUseCase - Retrieves scans with filters - ReviewScanUseCase - Admin marks scan as reviewed

Infrastructure: - ScanModel (SQLModel) - ScanRepositoryImpl implementation

Presentation: - POST /api/v1/scans - Create scan (validates HMAC, saves regardless of validity) - GET /api/v1/scans - List scans (filtered by user/tenant) - GET /api/v1/scans/{id} - Get single scan - PATCH /api/v1/scans/{id}/review - Admin review scan - GET /api/v1/scans/entity/{type}/{id} - Get entity details by type

QR Code Format:

{
  "t": "pkg" | "bag",  // entity type
  "i": "uuid",          // entity ID
  "c": "hmac_sha256",   // HMAC signature
  "v": 1                // version
}

HMAC Calculation:

message = entity_type + entity_id
hmac = HMAC-SHA256(tenant_secret, message)

Rate Limiting: 100 scans per hour per user. Scans are always saved to DB regardless of validation result.

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

Ver también: Architecture Overview · Clean Architecture rules

Backend Modules¶

Auth Module (modules/auth/)¶

Shipments Module (modules/shipments/)¶

Scans Module (modules/scans/)¶

Notifications Module (modules/notifications/)¶