# Bytelyst Mobile Trading App - Bootstrap Checklist and Roadmap

Date: 2026-02-15  
Scope: Mobile app bootstrap for iOS + Android with shared domain/trading core

## Goal

Ship an enterprise-grade mobile trading app baseline with:
- Native iOS support (Swift/SwiftUI)
- Native Android support (Kotlin/Jetpack Compose)
- Shared trading core using Kotlin Multiplatform (KMP) for deterministic business logic parity

## Recommended Architecture

- `iOS App`: SwiftUI, Combine/async-await, native secure key storage (Keychain)
- `Android App`: Kotlin, Jetpack Compose, Coroutines/Flow, EncryptedSharedPreferences/Keystore
- `Shared Core (KMP)`:
  - Profile/trade lifecycle models
  - Risk checks (SL/TP, max daily loss, position sizing guards)
  - Order/position/history reconciliation logic
  - API DTO mappers and validation
- `Backend Integration`: Existing bot service + dashboard APIs + Supabase auth/data plane

## Minimum Viable Features (Mobile)

- Login and session management
- Profile list with risk/strategy summary
- Market watchlist with live price updates
- Active orders view (profile-scoped, trade-id visible)
- Open positions view (profile-scoped, PnL + SL/TP status)
- Trade history view (full lifecycle trace by `trade_id`)
- Manual trade actions: buy/sell/close position
- Profile configuration: risk basics + entry mode + long-only toggle
- Notifications: push + in-app inbox for order filled, SL hit, TP hit, risk-limit halt
- In-app chat: support/ops chat and AI-assist chat fallback for profile guidance
- Health/status screen: bot connectivity, AI status/fallback mode

## Enterprise Readiness Gates

- Deterministic lifecycle mapping by `trade_id` across orders/positions/history
- Profile isolation for same-symbol concurrent exposure (virtual sub-positions)
- Offline-safe local cache with replay-safe sync
- Audit logging and immutable client event trail
- Strong auth: token refresh, device binding, secure storage
- Observability: crash reporting, API latency/error telemetry, trace IDs
- Notification reliability: token health checks, retry policy, delivery/error metrics
- Release controls: feature flags, staged rollout, rollback plan

## Phase Roadmap with Checklists

### Phase 0 - Product and Platform Baseline

- [ ] Finalize mobile product requirements and acceptance criteria
- [ ] Freeze API contracts for orders/positions/history/trade lifecycle
- [ ] Define canonical `trade_id` contract for mobile UI and backend parity
- [ ] Confirm profile-level strategy + risk schema consumed by mobile
- [ ] Define environment strategy: dev/stage/prod with safe key injection
- [ ] Establish branch, CI, and release conventions for mobile repos

### Phase 1 - Project Bootstrap (Swift + Kotlin + KMP)

- [ ] Create `ios-app` project (SwiftUI, modular structure)
- [ ] Create `android-app` project (Compose, modular structure)
- [ ] Create `shared-kmp` module and wire iOS/Android consumption
- [ ] Implement shared domain models: profile/order/position/trade history
- [ ] Implement shared API client contracts and validation layer
- [ ] Add lint/format/static analysis for all targets
- [ ] Add baseline unit test framework for iOS/Android/shared

### Phase 2 - Authentication and Core Data Flows

- [ ] Implement auth screens and secure token handling
- [ ] Implement refresh token lifecycle and forced re-auth guardrails
- [ ] Implement profile list screen with strategy/risk snapshot
- [ ] Implement watchlist + live market feed subscription
- [ ] Implement resilient local cache (read-through + stale marker)
- [ ] Implement sync manager with idempotent delta updates
- [ ] Implement push notification permissions + device token registration
- [ ] Implement in-app notification inbox sync and read/unread state

### Phase 3 - Trading Lifecycle UI (MVP Trading)

- [ ] Implement Active Orders screen with `trade_id`, profile, order status
- [ ] Implement Open Positions screen with profile-scoped aggregation
- [ ] Implement Trade History screen with lifecycle timeline by `trade_id`
- [ ] Implement manual Buy/Sell/Close actions with explicit confirmations
- [ ] Implement SL/TP display and editable fields per position/profile rules
- [ ] Add lifecycle discrepancy banner when backend/mobile states diverge
- [ ] Implement in-app chat module (support thread + AI assistant conversation UI)

### Phase 4 - Risk, Automation, and Execution Controls

- [ ] Expose profile execution config: `long_only`, entry mode, risk toggles
- [ ] Surface backend auto-trade status and execution reason codes
- [ ] Implement risk-limit halt UI states (daily loss, consecutive losses)
- [ ] Add emergency controls: pause profile, disable new entries, close all
- [ ] Add profile-level notification routing and critical alert escalation
- [ ] Implement notification preference center (per profile/event severity/channel)

### Phase 5 - Reliability, Compliance, and Operations

- [ ] Add structured mobile telemetry with correlation IDs to backend logs
- [ ] Add crash analytics and startup health probes
- [ ] Add integration tests for `orders -> positions -> history` parity
- [ ] Add contract tests against backend and Supabase schemas
- [ ] Add penetration/security checks (OWASP MASVS baseline)
- [ ] Add notification delivery monitoring and dead-letter handling runbook
- [ ] Add chat transcript retention policy and PII redaction controls
- [ ] Prepare release runbooks, rollback checklist, and on-call handbook

### Phase 6 - Store Readiness and Scale

- [ ] App Store/Play Store metadata and compliance packaging
- [ ] Performance budget validation (cold start, list render, live stream load)
- [ ] Battery/network efficiency tuning for live trading sessions
- [ ] Feature flag strategy for staged rollout by cohort
- [ ] Post-launch SLO tracking and incident response workflow

## Suggested Task Tracking Format

Use this format as implementation starts:

- [ ] `Task name`  
  Platform: `iOS` | `Android` | `KMP` | `Backend`  
  Owner: `TBD`  
  Commit: `pending`

Example after completion:

- [x] `Implement Active Orders screen with trade_id and profile badges`  
  Platform: `iOS, Android`  
  Owner: `TBD`  
  Commit: `https://github.com/<org>/<repo>/commit/<sha>`

## Initial Backlog (MVP-first, recommended order)

- [ ] Boot repositories and CI for iOS/Android/KMP
- [ ] Implement auth + token refresh
- [ ] Implement profile list + watchlist
- [ ] Implement orders/positions/history with strict `trade_id` mapping
- [ ] Implement manual trade actions + confirmations
- [ ] Implement profile execution/risk settings surface
- [ ] Implement notification stack (push + in-app inbox + preferences)
- [ ] Implement in-app support/AI chat module
- [ ] Implement health/status panel with AI fallback visibility
- [ ] Run lifecycle parity tests against backend and close gaps

## Open Questions (Non-Blocking)

- [ ] Should mobile support broker-level advanced order types at MVP (stop-limit, trailing-stop), or defer to Phase 5+?
- [ ] Should mobile include profile creation/edit at MVP, or remain read-and-execute only initially?
- [ ] Should AI-assisted profile suggestion run on-device fallback when AI service is unavailable, or server-side fallback only?
