Frontend Modules¶

Tech Stack¶

Framework: Flet (Python) - cross-platform (web, mobile, desktop)
Communication: httpx for async API calls
Images: SVG exclusively
Typography: System (Inter on web)
Architecture: Clean Architecture + Clean Code

Module Structure¶

modules/<module>/
├── domain/               # Entities, repositories (abstract), usecases
├── data/                # Datasources, repository implementations
└── presentation/         # Controllers, pages, components

Domain Layer¶

Can Import	Cannot Import
`core.error`	`flet`, `httpx`, other modules

Data Layer¶

Can Import	Cannot Import
`domain`, `core.network`, `core.error`	`flet`, `shared`

Presentation Layer¶

Can Import	Cannot Import
`domain`, `core.theme`, `flet`	`data`, `shared`

Core Layer¶

core/
├── config.py           # Environment configuration
├── error/              # Result type (Success/Failure)
├── di/                 # Service locator
├── network/            # ApiClient (httpx async)
├── router/             # AppRouter
├── security/           # Rate limiter, input validation, IP blocklist
├── storage/            # SharedPreferences, session storage
├── theme/              # Theme system (tokens + builder)
└── realtime/           # WebSocket client

Shared Layer¶

shared/
├── i18n/               # Translations service (t, t_text, t_drawer)
├── components/         # Shared components (app_bar, reactive_text_field)
├── pages/              # Shared pages (dashboard)
└── page_manager.py     # Singleton for page state

Design System (Kinetic Courier)¶

Colors¶

Token	Light Value	Usage
`primary`	`#006e2d`	Primary actions, Spotify Green
`on-primary`	`#ffffff`	Text on primary
`surface`	`#f4fcef`	Background
`on-surface`	`#161d16`	Primary text

Typography (Inter)¶

Style	Size	Weight	Usage
Display	48px	700	Hero sections
Title	24px	600	Screen headers
Subtitle	18px	500	Section headers
Body	16px	400	General content
Caption	12px	500	Metadata

Spacing¶

Base unit: 4px
Touch target minimum: 44px
Safe area bottom: constant(safe-area-inset-bottom)

Shapes¶

Cards: 16px radius
Buttons: Pill-shaped (primary), 12px (secondary)
Inputs: 8px radius

Key Pages¶

Route	Page	Description
`/login`	LoginPage	Authentication
`/dashboard`	DashboardPage	Main dashboard with NavigationDrawer
`/forgot-password`	ForgotPasswordPage	Password reset request
`/reset-password`	ResetPasswordPage	New password entry
`/track`	TrackingPage	Public tracking (no auth)
`/shipments/board`	ShipmentsBoardPage	Kanban-style board

Security Features¶

Token encryption (Fernet/AES) in SharedPreferences
HTTPS enforcement in production
Rate limiting (30 req/min for tracking)
IP blocklist after 50 failed attempts
Input validation and sanitization
Honeypot anti-bot field

i18n System¶

Translation files in assets/i18n/: - en.json - English - es.json - Spanish

Function	Usage	Returns
`t("key")`	Static labels	`str`
`t_text("key", page, **kwargs)`	Reactive Text	`ft.Text`
`t_drawer(destination, "nav.home")`	NavigationDrawer labels	updates `dest.label`

Change language with set_language(Lang("es")) + refresh_and_update(page).

Testing¶

uv run pytest test/ -v

Current coverage: 254 tests passing (2 skipped)

Module	Tests
core/error	3
core/theme	6
auth/domain	22
core/storage	8
validators	13
translations	20
core/security	37
modules/tracking	37
modules/shipments	18
core/realtime	12