System Requirements Document for fatakseride-ride

1. Introduction

FatakSeRide is a production-quality Android application for ride-hailing and logistics drivers operating on Indian platforms. Its tagline is "Ride Faster. Work Smarter."

The product intent is a driver-focused ride-request filtering and assistance tool. The driver selects a supported ride platform, configures filters, then uses the target ride app as normal. FatakSeRide observes the target app through legitimate Android accessibility mechanisms, detects genuine active ride/order requests, evaluates them entirely locally against the driver's filters, and assists with the appropriate platform-specific action — accepting, matching, or dismissing — only when it can do so confidently and safely.

The audience is a working driver on a bike or in a cab, in sunlight, glancing between two apps, reading Hindi and English. The application is not a generic taxi app and not a mockup: it is an instrument panel that tells the driver plainly what it saw, what it decided, and why. Correctness and safety outrank speed; when the application is uncertain, it does nothing.

2. System Overview

FatakSeRide is delivered as a real Android application composed of a Flutter/Dart user interface and native Android Kotlin performance-critical functionality, joined by Flutter Platform Channels or Pigeon.

The runtime pipeline is fixed:

Flutter UI → Platform Channel → Native Kotlin → AccessibilityService → Event Processor → Platform Adapter → Ride Parser → Filter Engine → Decision Engine → Action Engine → Verification.

Processing is event-driven. The AccessibilityService consumes AccessibilityEvents, debounces and deduplicates them, identifies the active Android package, and routes work to one of four independent platform adapters — UberAdapter, OlaAdapter, RapidoAdapter, PorterAdapter. Each adapter parses the current request UI into a RideRequest. The local FilterEngine evaluates the enabled filters with AND logic in a fixed cheap-first order. The Decision Engine produces MATCH, IGNORE, or NO ACTION. The Action Engine computes confidence, performs final validation, and dispatches a tap or gesture through GestureDescription and dispatchGesture(). Verification then confirms whether the action actually succeeded.

All ride information is evaluated locally before any filter decision. No ride information is sent to a server before that decision. Latency is measured, not claimed.

2a. Product Interpretation and Delivery Boundary

Delivery ownership. FatakSeRide is a first-party Android application. Its Flutter UI, native Kotlin AccessibilityService, adapters, parser, filter engine, decision engine, gesture engine, validation, verification, Room database, history, analytics, test mode, developer mode, permission center, and Flutter/Kotlin bridge are all application-owned and built as real, working functionality — not fake APIs, simulated acceptance, fake latency, hardcoded success, or placeholder methods.

Access ownership. The application owns its own driver identity. A driver independently begins using FatakSeRide; no external provisioning boundary is established. First use therefore requires self-service enrollment, and returning use requires verification before protected operational, configuration, history, subscription, and account state is reachable. Developer Mode and Developer Diagnostics are additionally restricted to an authorized or provisioned diagnostics operator. The Landing surface is anonymous and explains the product before any protected work; Login and Sign Up are the anonymous entry boundaries that establish and verify access.

Android permission boundary. Live accessibility-driven assistance cannot operate until the actually required Android permissions are granted — Accessibility Service, and where genuinely required Notification Access, Overlay, Foreground Service, and Notifications. The Permission Center shows only permissions actually required.

Target-app boundary. The target ride apps (Uber, Ola, Rapido, Porter) are external, provider-owned surfaces. FatakSeRide never assumes the target app is Flutter and never assumes a framework; it interacts only through legitimate Android accessibility/UI mechanisms. FatakSeRide does not own, modify, or simulate the target apps' behavior, and it does not invent target-app behavior when the UI is uncertain — it uses the provided screenshots/reference material and official Android capabilities.

Current vs. future. Everything specified in this document is current. No future-horizon capabilities are defined by the source.

Narrow exclusions. FatakSeRide does not collect passwords, OTPs, unrelated messages, or unnecessary personal information. It does not continuously screenshot, OCR, or poll the screen every few milliseconds. It does not use one universal adapter for every platform. It does not trigger on home screens, profiles, settings, maps, navigation, completed trips, login, OTP, messages, or unrelated popups. It does not rely on permanent coordinates such as x=500,y=1800, and does not hardcode screen coordinates as the primary interaction method. It does not fabricate missing ride data, guess missing required filter values, or blindly assume Accept and Match are the same action. It does not blindly repeat an action after failed verification.

2c. Page Content and Component Coverage

The application's page inventory is fixed and ordered: Landing, Login, Sign Up, Home, Live Rides, Filters, History, Analytics, Settings, Permissions, Subscription, Account, Test Mode, Developer Mode, Filter Tester, Developer Diagnostics, Permission Center.

Landing

• Information/state: Anonymous first impression. FATAKSERIDE wordmark, tagline "Ride Faster. Work Smarter.", a plain statement that FatakSeRide is a driver-focused ride-request filtering and assistance app for supported platforms (Uber, Ola, Rapido, Porter), and a diagrammatic explanation that requests are evaluated locally on the device.
• Primary actions: Proceed to Sign Up (begin using FatakSeRide); proceed to Login (returning driver).
• Supporting actions: Read the local-evaluation and safety statement.
• Domain entities: None persisted; static product identity content.
• Component responsibilities: Wordmark block; tagline block; schematic pipeline diagram (Flutter → Platform Channel → Kotlin → AccessibilityService); entry controls to Sign Up and Login.
• States: Loading (static content, no data fetch); empty (not applicable); success (content rendered); error (not applicable); recovery (not applicable).

Login

• Information/state: Returning verification surface. Driver identity fields; validation and failure messaging.
• Primary actions: Verify returning driver identity and enter the protected application.
• Supporting actions: Navigate to Sign Up; navigate back to Landing.
• Domain entities: Driver identity credential (application-owned); session continuity.
• Component responsibilities: Credential input; submit control; error display; navigation to Sign Up.
• States: Loading (verification in progress); empty (blank form); success (protected application reachable); error (invalid credentials, verification failure); recovery (retry, or route to Sign Up).

Sign Up

• Information/state: Self-service enrollment surface. Enrollment fields; validation and failure messaging.
• Primary actions: Establish a new driver identity and enter the protected application.
• Supporting actions: Navigate to Login; navigate back to Landing.
• Domain entities: Driver identity (application-owned).
• Component responsibilities: Enrollment input; submit control; error display; navigation to Login.
• States: Loading (enrollment in progress); empty (blank form); success (identity established, protected application reachable); error (validation failure, enrollment failure); recovery (correct input and retry, or route to Login).

Home

• Information/state: Driver control center. FATAKSERIDE wordmark; tagline "Ride Faster. Work Smarter."; Assist ON/OFF state; selected platform; current filters; Matched today; Accepted today; Ignored today; average processing time; STOP ASSIST availability.
• Primary actions: Toggle Assist ON/OFF; select the supported platform; open the numbered filter pipeline to review current thresholds; STOP ASSIST (emergency stop).
• Supporting actions: Navigate to Live Rides, Filters, History, Analytics, Settings, Permissions, Subscription, Account, Test Mode, Developer Mode.
• Domain entities: Assist state; selected platform; current filter configuration; daily counters (matched, accepted, ignored); average processing time.
• Component responsibilities: Wordmark and tagline block; ASSIST ON/OFF rocker; selected-platform chip with 4px platform rule; numbered filter pipeline list (01 Platform, 02 Validity, 03 Fare, 04 Pickup, 05 Trip, 06 ₹/km, 07 Ride type, 08 Request type) with current thresholds; ruled three-column stat band (Matched / Accepted / Ignored); average processing time readout; full-width STOP ASSIST bar pinned above bottom navigation; bottom navigation with five labelled items.
• States: Loading (counters and configuration loading from Room); empty (no activity today — counters at zero); success (Assist state, platform, filters, counters, and average processing time rendered); error (configuration or counter read failure); recovery (retry read; Assist remains in its last known safe state).

Live Rides

• Information/state: Live monitoring and action workspace. Detected ride requests as they arrive; per-request platform, request type, fare, pickup distance, trip distance, pickup address, destination address, ride type, rating, action type, timestamp, action bounds, confidence; filter result; verification outcome; deduplication state.
• Primary actions: Observe detected requests and their decisions; observe the platform action taken and its verification result.
• Supporting actions: Inspect a request's parsed fields and decision reason; observe ACTION_UNCONFIRMED records.
• Domain entities: RideRequest; filter result; action type; confidence; verification outcome; request fingerprint.
• Component responsibilities: Live request list; per-request detail with ruled label/value pairs; verdict badge (MATCH / IGNORE / NO ACTION) as a solid rectangular stamp; failing-stage indication in the numbered pipeline; platform rule and swatch; verification status.
• States: Loading (awaiting events); empty (no active requests detected); success (request detected, evaluated, actioned, and verified); error (parse failure, adapter failure, action failure); recovery (request ignored or recorded as ACTION_UNCONFIRMED; no blind repeat).

Filters

• Information/state: Configuration workspace. Supported platforms; all filter fields — Minimum Fare, Maximum Fare, Minimum Trip Distance, Maximum Trip Distance, Maximum Pickup Distance, Minimum Fare/KM, Maximum Fare/KM, Ride Type, Platform, Request Type; enabled/disabled state per filter.
• Primary actions: Enable or disable each filter; set each filter's threshold or selection; save the configuration.
• Supporting actions: Review the numbered evaluation order; clear a filter.
• Domain entities: Filter configuration persisted in Room.
• Component responsibilities: Numbered filter rows with stage markers; threshold inputs in tabular figures; enable toggles; platform selection; save control; validation messaging.
• States: Loading (configuration loading from Room); empty (no filters enabled); success (configuration saved); error (invalid threshold, save failure); recovery (correct input and retry; previous configuration retained).

History

• Information/state: Revisitable local record of processed ride requests and outcomes stored in Room. Per-entry platform, request type, fare, pickup distance, trip distance, pickup address, destination address, ride type, rating, action type, timestamp, action bounds, confidence, filter result, and verification outcome.
• Primary actions: Browse and inspect past processed requests and their outcomes.
• Supporting actions: Filter or scan the record by platform or outcome.
• Domain entities: Persisted RideRequest records and their decisions and outcomes.
• Component responsibilities: History list; per-entry detail with ruled label/value pairs; verdict badge; timestamp in muted type.
• States: Loading (reading from Room); empty (no history yet); success (records rendered); error (read failure); recovery (retry read).

Analytics

• Information/state: Historical performance views derived from locally stored request outcomes. Matched, accepted, and ignored counts over time; average processing time; per-platform breakdown.
• Primary actions: Review historical performance.
• Supporting actions: Change the observed period or platform breakdown.
• Domain entities: Aggregated outcomes derived from persisted RideRequest records.
• Component responsibilities: Ruled stat bands with tabular numerals; per-platform breakdown using platform line colours as rules, dots, and chips only.
• States: Loading (aggregation in progress); empty (no data to aggregate); success (aggregates rendered); error (aggregation failure); recovery (retry).

Settings

• Information/state: General application settings workspace.
• Primary actions: Review and change general application settings.
• Supporting actions: Navigate to Permissions, Subscription, Account, Test Mode, Developer Mode.
• Domain entities: Application settings persisted in Room.
• Component responsibilities: Ruled settings rows with label/value pairs; toggles and selectors.
• States: Loading (settings loading from Room); empty (defaults in effect); success (settings saved); error (save failure); recovery (retry; previous value retained).

Permissions

• Information/state: Permission-related navigation destination for operational setup. Current grant state of the actually required permissions.
• Primary actions: Navigate to the Permission Center for permission management.
• Supporting actions: Review which permissions are required and why.
• Domain entities: Permission grant state.
• Component responsibilities: Permission summary rows; navigation into the Permission Center.
• States: Loading (grant state read); empty (not applicable); success (grant state rendered); error (read failure); recovery (retry).

Subscription

• Information/state: Subscription management destination. Current subscription state.
• Primary actions: Review and manage the driver's subscription.
• Supporting actions: Review subscription status and terms.
• Domain entities: Subscription state bound to the driver identity.
• Component responsibilities: Subscription status block; management controls.
• States: Loading (subscription state read); empty (no active subscription); success (state rendered); error (read or update failure); recovery (retry).

Account

• Information/state: Account management destination. Driver identity and account details.
• Primary actions: Review and manage the driver's account.
• Supporting actions: Review identity details.
• Domain entities: Driver identity and account state.
• Component responsibilities: Account detail rows; management controls.
• States: Loading (account state read); empty (not applicable); success (state rendered); error (read or update failure); recovery (retry).

Test Mode

• Information/state: Protected test workflow for validating non-live safety and decision scenarios. The numbered filter pipeline rendered as eight ruled rows (01 Platform → 08 Request type) with the failing stage turning red.
• Primary actions: Run non-live validation scenarios; observe the pipeline stage that fails.
• Supporting actions: Navigate to the Filter Tester.
• Domain entities: Test scenario inputs and their decision outcomes.
• Component responsibilities: Numbered pipeline list; scenario controls; verdict badges as solid rectangular stamps; failing reason in 11px uppercase.
• States: Loading (test harness readying); empty (no scenario run yet); success (scenario outcome rendered); error (scenario execution failure); recovery (re-run scenario).

Developer Mode

• Information/state: Restricted technical workspace for diagnostics and development operation. Entry point to Developer Diagnostics.
• Primary actions: Enter the restricted diagnostics workspace.
• Supporting actions: Navigate to Developer Diagnostics.
• Domain entities: Diagnostics access state.
• Component responsibilities: Restricted entry control; navigation into Developer Diagnostics.
• States: Loading (authorization check); empty (not applicable); success (diagnostics reachable); error (authorization failure); recovery (retry authorization).

Filter Tester

• Information/state: Scenario-based tester for filter, missing-data, package, duplicate, and emergency-stop outcomes. The defined test examples: ₹199 + minimum ₹200 → IGNORE; ₹200 + minimum ₹200 → MATCH; ₹300 + pickup 7 km + maximum pickup 5 km → IGNORE; ₹900 / 30 km → ₹30/km; missing required data → NO ACTION; unknown package → IGNORE; package changes → CANCEL; duplicate event → PROCESS ONCE; emergency stop → CANCEL.
• Primary actions: Run each defined scenario and observe its outcome.
• Supporting actions: Inspect the failing stage and reason for each scenario.
• Domain entities: Scenario inputs; computed fare/km; decision outcomes.
• Component responsibilities: Scenario list; numbered pipeline rendering; verdict badges; computed value display in tabular figures.
• States: Loading (scenarios readying); empty (no scenario run yet); success (all scenario outcomes rendered); error (scenario execution failure); recovery (re-run).

Developer Diagnostics

• Information/state: Restricted diagnostics workspace showing current package, service status, last event, parsed RideRequest, filter result, action type, confidence, bounds, errors, and real latency.
• Primary actions: Inspect the live pipeline state and measured latency.
• Supporting actions: Inspect the last event, parsed request, decision, action, confidence, bounds, and errors.
• Domain entities: Current package; service status; last AccessibilityEvent; parsed RideRequest; filter result; action type; confidence; bounds; errors; measured latency.
• Component responsibilities: Ruled diagnostic rows with label/value pairs; tabular numerals for latency and confidence; flat diagram of the Flutter → Platform Channel → Kotlin → AccessibilityService path; error list.
• States: Loading (diagnostics stream connecting); empty (no event observed yet); success (diagnostics rendered); error (service unavailable, stream failure); recovery (reconnect; errors surfaced rather than hidden).

Permission Center

• Information/state: Focused permission management workspace for Accessibility Service and other actually required Android permissions — Notification Access, Overlay, Foreground Service, and Notifications where genuinely required. Shows only permissions actually required.
• Primary actions: Review each required permission and its current grant state; open the Android system surface to grant a required permission.
• Supporting actions: Review why each permission is required.
• Domain entities: Permission grant state per required permission.
• Component responsibilities: Icon-plus-label pictograms for each permission; ruled grant-state rows; grant controls.
• States: Loading (grant state read); empty (not applicable); success (grant state rendered, live assistance unblocked when all required permissions are granted); error (read failure); recovery (retry; live assistance remains blocked until required permissions are granted).

3. Functional Requirements

FR-01 — Product identity and audience (explicit) As a Ride-Hailing Driver, I should use an Android application named FatakSeRide with the tagline "Ride Faster. Work Smarter." that is built for drivers rather than passengers, so that the tool I use matches my working role.

• Trigger/input: Application launch.
• Observable result: The product presents itself as FatakSeRide with the tagline "Ride Faster. Work Smarter." and driver-focused framing.
• Access state: Anonymous on Landing.
• Failure/recovery: Not applicable.
• Continuation: Proceed to Sign Up or Login.

FR-02 — Core assistance loop (explicit) As a Ride-Hailing Driver, I should select a supported ride platform, configure filters, use the target ride app, and have FatakSeRide detect relevant ride requests, evaluate them locally, and assist with the appropriate platform-specific action, so that qualifying requests are handled without me watching the screen continuously.

• Trigger/input: Assist ON, a supported platform selected, filters configured, and the driver using the target ride app.
• Observable result: Detected requests are evaluated locally and the appropriate platform-specific action is assisted.
• Access state: Protected; requires verified driver identity and granted required Android permissions.
• Failure/recovery: When uncertain, FatakSeRide does nothing.
• Continuation: The driver continues using the target ride app; results appear in Live Rides and History.

FR-03 — Technology stack (explicit) As a Developer / Diagnostics operator, I should have FatakSeRide built with Flutter/Dart for its UI and native Android Kotlin for performance-critical functionality, using AccessibilityService, AccessibilityEvent, AccessibilityNodeInfo, GestureDescription, dispatchGesture(), Room, and Flutter Platform Channels or Pigeon, so that the UI and the latency-critical pipeline each use the right technology.

• Trigger/input: Build and runtime.
• Observable result: The UI is Flutter/Dart; performance-critical functionality is native Android Kotlin; the named Android and Flutter APIs are used.
• Access state: Not applicable.
• Failure/recovery: Compilation or runtime errors are fixed before the application is declared complete.
• Continuation: The Flutter/Kotlin integration is verified.

FR-04 — Fixed architecture (explicit) As a Developer / Diagnostics operator, I should have the pipeline implemented as Flutter UI → Platform Channel → Native Kotlin → AccessibilityService → Event Processor → Platform Adapter → Ride Parser → Filter Engine → Decision Engine → Action Engine → Verification, so that each stage has one clear responsibility.

• Trigger/input: Runtime event flow.
• Observable result: Each stage of the pipeline is present and performs its named responsibility.
• Access state: Not applicable.
• Failure/recovery: Errors are surfaced in Developer Diagnostics.
• Continuation: The pipeline continues to the next stage.

FR-05 — Low latency with measured performance (explicit) As a Ride-Hailing Driver, I should have the complete detection-to-action pipeline optimized for low latency, with critical processing kept in Kotlin and no ride information sent to a server before a filter decision, so that decisions are fast and my ride data stays local.

• Trigger/input: An AccessibilityEvent arrives.
• Observable result: Critical processing occurs in Kotlin; no ride information leaves the device before the filter decision; actual latency is measured and displayed.
• Access state: Protected.
• Failure/recovery: Latency is reported truthfully; no guaranteed one-second performance is claimed.
• Continuation: The measured latency appears on Home as average processing time and in Developer Diagnostics as real latency.

FR-06 — Event-driven processing (explicit) As a Ride-Hailing Driver, I should have FatakSeRide process only relevant AccessibilityEvents with debouncing and deduplication, so that it does not drain my battery or hammer the screen.

• Trigger/input: AccessibilityEvents from the active window.
• Observable result: Only relevant events are processed; debouncing and deduplication are applied.
• Access state: Protected.
• Failure/recovery: Duplicate events are processed once.
• Continuation: Processing proceeds to package detection.

FR-07 — Separate platform adapters (explicit) As a Developer / Diagnostics operator, I should have separate UberAdapter, OlaAdapter, RapidoAdapter, and PorterAdapter implementations, so that each platform's UI is handled on its own terms.

• Trigger/input: Active package identified.
• Observable result: The matching adapter handles the request; no universal implementation serves every platform.
• Access state: Protected.
• Failure/recovery: An unknown package is ignored.
• Continuation: The adapter produces a parsed RideRequest.

FR-08 — Package detection and routing (explicit) As a Ride-Hailing Driver, I should have FatakSeRide identify the active Android package and route it to the correct adapter, ignore unknown packages, and cancel a pending action if the active package changes, so that no action lands in the wrong app.

• Trigger/input: Active package identification during event processing.
• Observable result: Known packages route to their adapter; unknown packages are ignored; a package change during a pending action cancels that action.
• Access state: Protected.
• Failure/recovery: Unknown package → IGNORE; package change → CANCEL.
• Continuation: Processing resumes only for a known, active package.

FR-09 — Genuine request detection only (explicit) As a Ride-Hailing Driver, I should have FatakSeRide detect only genuine active ride/order requests and never trigger on home screens, profiles, settings, maps, navigation, completed trips, login, OTP, messages, or unrelated popups, so that it never acts on something that is not a live request.

• Trigger/input: AccessibilityEvent from the target app.
• Observable result: Only genuine active ride/order requests proceed; the listed non-request surfaces do not trigger.
• Access state: Protected.
• Failure/recovery: Non-request surfaces produce no action.
• Continuation: Genuine requests proceed to parsing.

FR-10 — Accessibility tree inspection (explicit) As a Developer / Diagnostics operator, I should have FatakSeRide use getRootInActiveWindow() and AccessibilityNodeInfo to inspect text, contentDescription, resourceName, className, clickable state, enabled state, visibility, bounds, and available actions, so that request detection and action targeting rest on real UI evidence.

• Trigger/input: Relevant AccessibilityEvent.
• Observable result: The listed node properties are inspected.
• Access state: Protected.
• Failure/recovery: Missing evidence reduces confidence and can lead to NO ACTION.
• Continuation: Parsed evidence feeds the adapter and parser.

FR-11 — Framework independence (explicit) As a Developer / Diagnostics operator, I should have FatakSeRide interact only through legitimate Android accessibility/UI mechanisms and never assume the target app is Flutter, so that it works against native Android, Flutter, React Native, custom rendering, or another framework.

• Trigger/input: Any target-app interaction.
• Observable result: Interaction occurs through Android accessibility/UI mechanisms only.
• Access state: Protected.
• Failure/recovery: Unsupported UI evidence leads to NO ACTION rather than a guess.
• Continuation: Processing continues with available evidence.

FR-12 — Action type support (explicit) As a Ride-Hailing Driver, I should have FatakSeRide support NONE, TAP_ACCEPT, SWIPE_ACCEPT, MATCH, TAP_MATCH, DISMISS, and CUSTOM_GESTURE, and never blindly assume Accept and Match are the same action, so that the right control is used on each platform.

• Trigger/input: Action detection against the current request UI.
• Observable result: The correct action type is selected from the supported set; Accept and Match are distinguished.
• Access state: Protected.
• Failure/recovery: If the correct action cannot be confidently identified, nothing is done.
• Continuation: The selected action proceeds to confidence calculation and final validation.

FR-13 — Multilingual action text (explicit) As a Ride-Hailing Driver, I should have FatakSeRide support English and Hindi action text — including Accept, Accept Ride, Accept Order, Match, Confirm, स्वीकार, स्वीकार करें, मैच, मिलान — and also inspect contentDescription, accessibility labels, resource IDs, and accessibility actions, so that action detection works in either language and beyond visible text.

• Trigger/input: Action control inspection.
• Observable result: English and Hindi action text is recognized; contentDescription, accessibility labels, resource IDs, and accessibility actions are inspected.
• Access state: Protected.
• Failure/recovery: Unrecognized action text reduces confidence and can lead to NO ACTION.
• Continuation: The recognized action proceeds to confidence calculation.

FR-14 — Dynamic swipe geometry (explicit) As a Ride-Hailing Driver, I should have FatakSeRide dynamically locate the current swipe-to-accept control, obtain its bounds, calculate start/end points from those bounds, and use GestureDescription with dispatchGesture(), so that swipes land correctly on any screen size.

• Trigger/input: A swipe-to-accept control is detected.
• Observable result: Start and end points are computed from the control's current bounds and dispatched as a gesture.
• Access state: Protected.
• Failure/re