PRD Summary - RoundAway Express¶

Overview¶

Product Name: RoundAway Express Type: SaaS Logistics Platform for Courier Services Target Market: International courier companies and independent couriers

Core Value Proposition¶

Enable couriers to manage shipments, track flights, and deliver packages with real-time visibility from sender to recipient.

Key Features¶

MVP Features¶

Feature	Priority	Status
User registration/login	P0	Done
Shipment creation	P0	Done
QR code scanning	P0	Done
Flight tracking	P0	Done
Delivery confirmation	P0	Done
Multi-tenancy	P0	Done
Shipments board	P1	Done

P1 Features (Next Release)¶

Warehouse management
Push notifications
Email notifications
Delivery proof upload

P2 Features (Future)¶

Analytics dashboard
Courier performance metrics
Multi-language support

User Segments¶

Courier¶

Create and manage shipments
Scan QR codes for pickup/delivery
Track flights
Confirm deliveries

Operator¶

Manage all shipments
Assign shipments to bags
Monitor warehouse
Handle exceptions

Admin¶

Manage users and tenants
View analytics
Configure system

Business Model¶

Subscription per tenant (monthly/annual)
Based on shipment volume tiers
Free tier for testing (limited volume)

Success Metrics¶

Active couriers using the platform
Shipments delivered successfully
QR scan success rate
Flight tracking accuracy

Implementation Status¶

Funcionalidades Core¶

Feature	Description	Status
Gestión de Encomiendas	CRUD completo, estados, tracking ID único	✅
Gestión de Maletas	Capacidad en kg, peso actual, asociación con courier	✅
Gestión de Vuelos	Ruta, fecha, agrupación de maletas, vuelos con escalas	✅
Tracking Público	`GET /api/v1/track/{tracking_id}` sin autenticación	✅
Subida de Fotos de Entrega	HEIC→JPEG, multi-cloud, thumbnail automático	✅

Estados de Shipment: RECEIVED → VERIFIED → PAID → PACKAGED → IN_TRANSIT → AT_PICKUP_POINT → OUT_FOR_DELIVERY → DELIVERED (+ RETURNED, CANCELLED)

Data Model¶

Entidades Principales¶

User: id, email, name, password_hash, role (ADMIN/COURIER), tenant_id, tier, api_key
Tenant: id, name, slug, custom_domain, theme_config_path
Shipment: id, tracking_id, sender_, recipient_, origin, destination, description, weight, price, status, payment_status, delivery_proof_url, tenant_id
Bag: id, user_id, tenant_id, route, departure_date, capacity_kg, current_weight, status (SCHEDULED, DEPARTED, ARRIVED, DELAYED)
Flight: id, origin, destination, departure_date, user_id, tenant_id, status (SCHEDULED, DEPARTED, ARRIVED, CANCELLED, DELAYED)
BagFlight: bag_id, flight_id, assigned_at (N:M)
TenantStorageConfig: id, tenant_id, provider, gcp_bucket, gcp_service_account_json, aws_s3_bucket, aws_, azure_, is_active
AuditLog: id, tenant_id, user_id, action, entity_type, entity_id, details, created_at

Relaciones¶

Tenant → User, Shipment, Bag, Flight (1:N)
User → Bag, Flight (1:N)
Bag → Shipment (1:N via BagShipment)
Bag → Flight (N:M via BagFlight) - Permite múltiples flights por bag (escalas)

API Coverage¶

Método	Endpoint	Auth	Status
POST	/api/v1/auth/register	Público	✅
POST	/api/v1/auth/login	Público	✅
POST	/api/v1/auth/refresh	Refresh	✅
POST	/api/v1/auth/logout	JWT	✅
POST	/api/v1/auth/verify-email	Público	✅
POST	/api/v1/auth/reset-password	Público	✅
GET	/api/v1/shipments	JWT (Admin)	✅
POST	/api/v1/shipments	JWT (Admin)	✅
GET	/api/v1/shipments/{id}	JWT (Admin)	✅
PUT	/api/v1/shipments/{id}	JWT (Admin)	✅
DELETE	/api/v1/shipments/{id}	JWT (Admin)	✅
GET	/api/v1/track/{tracking_id}	Público	✅
GET	/api/v1/bags	JWT	✅
POST	/api/v1/bags	JWT (Admin)	✅
GET	/api/v1/bags/my	JWT (Courier)	✅
PUT	/api/v1/bags/{id}/deliver	JWT (Courier)	✅
POST	/api/v1/bags/{id}/flights/{flight_id}	JWT	✅
DELETE	/api/v1/bags/{id}/flights/{flight_id}	JWT	✅
GET	/api/v1/bags/{id}/flights	JWT	✅
GET	/api/v1/flights	JWT (Admin)	✅
POST	/api/v1/flights	JWT (Admin)	✅
GET	/api/v1/tenants/me	JWT	✅
GET	/api/v1/tenants/theme	JWT	✅
POST	/api/v1/upload/delivery/{shipment_id}	JWT	✅
GET	/api/v1/upload/health	JWT	✅

AeroDataBox Integration¶

Flight Alert API provides real-time flight status updates via webhooks.

Webhook Payload Format (AeroDataBox)¶

{
  "eventType": "flight.updated",
  "subscriptionId": "uuid-subscription-id",
  "subject": {
    "flight": {"number": "PU302", "airline": {"iata": "PU"}},
    "departureDate": "2026-05-11",
    "departure": {
      "airport": {"icao": "SPJC"},
      "scheduled": {"time": "2026-05-11T18:10:00Z"},
      "estimated": {"time": "2026-05-11T18:10:00Z"},
      "actual": {"time": "2026-05-11T18:31:00Z"},
      "status": "landed"
    },
    "arrival": {
      "airport": {"icao": "LEMD"},
      "scheduled": {"time": "2026-05-12T13:05:00Z"},
      "estimated": {"time": "2026-05-12T12:30:00Z"},
      "actual": {"time": "2026-05-12T12:29:00Z"}
    },
    "lastUpdated": "2026-05-12T12:29:00Z"
  }
}

Status Mapping (AeroDataBox → Shipment)¶

AeroDataBox	Shipment Status
SCHEDULED	PACKAGED
BOARDING	IN_TRANSIT
DEPARTED	IN_TRANSIT
EN_ROUTE	IN_TRANSIT
LANDED	AT_PICKUP_POINT
ARRIVED	AT_PICKUP_POINT
CANCELLED	CANCELLED
DIVERTED	CANCELLED
DELAYED	IN_TRANSIT

Features¶

Dual provider: Aviationstack (polling) + AeroDataBox (webhooks)
Webhook notifications on flight status changes
Subscriptions persisted in flight_alert_subscription table
Automatic subscription renewal
Configurable notification level per tenant (basic/complete)
WhatsApp notifications to recipients
Real-time WebSocket updates for couriers

Storage Module¶

Multi-cloud storage for delivery proof images with automatic HEIC→JPEG conversion.

Architecture¶

Backend media handling (no presigned URLs) for greater control
Multi-provider support: GCP Cloud Storage, AWS S3, Azure Blob Storage
Automatic image processing: HEIC/HEIF → JPEG conversion, 300x300px thumbnails
Tenant isolation: Paths structured as {tenant_id}/{tracking_id}/delivery/

Features¶

Feature	Description
HEIC→JPEG	Automatic conversion using pillow-heif
Thumbnail	300x300px thumbnail generated automatically
Validation	jpg/jpeg/png/heic/heif, max 8MB, min 100x100px
Multi-cloud	GCP, AWS, Azure providers via configuration
Tenant isolation	Storage paths include tenant_id for RLS

Upload Flow¶

1. Courier toma foto con la app (puede ser HEIC)
2. App envía a /api/v1/upload/delivery/{shipment_id}
3. Backend valida tipo, tamaño, dimensiones
4. Si es HEIC/HEIF → convierte a JPEG
5. Genera thumbnail 300x300px
6. Sube original + thumbnail a cloud storage
7. Retorna URLs al frontend

Test Coverage¶

Category	Count	Coverage
Unit Tests	112	Domain logic, use cases, repositories
Integration Tests	139	API endpoints
Security Tests	48	Tenant isolation, token security, CORS, rate limiting
Core Versioning	23	API versioning
Storage Module	53	Image processing, upload, entities
Total	471	~90%

Security Tests Breakdown¶

Test File	Tests	Description
`test_tenant_isolation.py`	5	Cross-tenant data access prevention
`test_token_security.py`	15	JWT creation, validation, rotation
`test_cors_security.py`	14	CORS configuration validation
`test_rate_limiting.py`	9	Rate limit enforcement
`test_sql_injection_prevention.py`	5	SQL injection prevention

Migrations¶

Migration	Description
f99a55372a6f	Initial auth tables (User, Tenant, Session, Role)
f99a55372a7g	Add RLS policies
xxx_create_shipments_snake_case	Shipments, Bags, Flights tables
a1b2c3d4e5f6	Add verification_code, reset_code columns
xxx_create_tenant_storage_config	Tenant storage provider configuration

Para specs completas y roadmap, ver el PRD.md en PRD_PATH.

Product Vision¶

SaaS-Courier es una plataforma SaaS de gestión de paquetería con experiencia UX/UI profesional como diferenciador principal. Sistema multi-tenant donde cada cliente (partner) puede personalizar su interfaz manteniendo funcionalidades según su plan contratado.

Propuesta de valor: Gestión de paquetería fácil y dinámica con la mejor experiencia UX/UI en web y móvil.

Development Roadmap¶

Fase 1: Core ✅¶

Configurar proyecto base Flet ✅
Sistema de temas (light/dark) ✅
i18n (EN/ES) ✅
Auth Module ✅
Dashboard ✅

Fase 2: Features¶

Tracking público
Shipments (CRUD)
Bags & Flights
Profile/Settings

Fase 3: MVP Completo¶

Reports
Payments & Facturas
Testing y polish UX