System Requirements Document for mellow-fatakseride

1. Introduction

FatakSeRide is a driver-focused ride-request filtering and assistance application for Android. Its tagline is "Ride Faster. Work Smarter." The product is not a generic taxi app and not a mockup: it is a real, production-quality Android application that runs alongside the driver's ride-hailing apps (Uber, Ola, Rapido, Porter), detects genuine active ride/order requests through legitimate Android accessibility mechanisms, evaluates them locally against the driver's configured filters, and assists with the correct platform-specific action.

The audience is the working ride-hailing driver in India who operates one-handed, often in sunlight, with a very short decision window per request. The product's emotional register is instrument-grade trust: calm under pressure, zero tolerance for ambiguity, and a hard rule that when the system is uncertain it does nothing.

The secondary audience is the Developer / QA Engineer who validates the detection-to-action pipeline, filter boundaries, and platform adapters through Test Mode, the Filter Tester, and Developer Diagnostics.

2. System Overview

FatakSeRide is delivered as a Flutter/Dart user interface over a native Android Kotlin core. The Flutter layer owns all driver-facing screens, configuration, history, analytics, and diagnostics presentation. The Kotlin layer owns the performance-critical pipeline: the AccessibilityService, event processing, platform adapters, ride parsing, the local filter engine, the decision engine, the action engine, and post-action verification. The two layers communicate through Flutter Platform Channels or Pigeon.

The pipeline is strictly layered:

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 service reacts to AccessibilityEvent and inspects the accessibility tree via getRootInActiveWindow() and AccessibilityNodeInfo. It does not continuously screenshot, OCR, or poll the screen every few milliseconds. Debouncing and deduplication prevent repeated processing of the same request.

Four independent platform adapters exist — UberAdapter, OlaAdapter, RapidoAdapter, PorterAdapter — and no single universal implementation serves every platform. The active Android package is identified and routed to the correct adapter; unknown packages are ignored, and if the active package changes while an action is pending, the action is cancelled.

All filtering and decision-making happen locally. Ride information is never sent to a server before a filter decision is made. Actual latency is measured and reported; no guaranteed one-second performance is claimed.

The driver-facing surface includes Home, Live Rides, Filters, History, Analytics, Settings, Permissions, Permission Center, Subscription, Account, Wallet, Test Mode, Developer Mode, Filter Tester, and Developer Diagnostics, preceded by an anonymous Landing entry and identity access through Login and Sign Up.

Narrow exclusions. FatakSeRide does not collect passwords, OTPs, unrelated messages, or unnecessary personal information. It does not trigger on home screens, profiles, settings, maps, navigation, completed trips, login, OTP, messages, or unrelated popups. It does not randomly tap, swipe, or guess missing ride information. It does not hardcode screen coordinates as the primary interaction method. It does not leave core functionality as fake APIs, simulated acceptance, fake latency, hardcoded success, or placeholder methods.

2a. Product Interpretation and Delivery Boundary

FatakSeRide is a first-party Android application with its own Flutter UI and its own native Kotlin accessibility core. The driver installs it, grants the Android permissions it actually requires, signs in, selects a supported platform, configures filters, and turns Assist ON. From that point the application observes the target ride app through the Android accessibility framework and acts only when a request genuinely matches the driver's filters and the correct action can be confidently identified.

Identity is application-owned. A driver independently begins use through self-service enrollment and returns through verification; a provisioned Developer / QA Engineer reaches role-restricted diagnostics and test destinations through the same access boundary. The Landing surface is anonymous and explains the product before any protected work begins. Protected destinations — Home, Live Rides, Filters, History, Analytics, Settings, Permissions, Permission Center, Subscription, Account, Wallet, Test Mode, Developer Mode, Filter Tester, and Developer Diagnostics — require an established identity.

The current delivery horizon covers everything described in this document. No future-horizon capabilities are asserted here beyond the current product.

2b. Source Content Inventory

The supplied reference screenshots are behavioral and visual references for specific driver-facing surfaces. They are not a content source for factual entities, collections, or records, and no verified factual dataset is supplied for reproduction. Accordingly, no source content inventory is rendered.

2c. Page Content and Component Coverage

Landing

• Information and state: Product identity — the FATAKSERIDE wordmark and the tagline "Ride Faster. Work Smarter."; a plain-language explanation that FatakSeRide is a driver-focused ride-request filtering and assistance application; a description of the assistance workflow (select a supported platform, configure filters, use the target ride app, FatakSeRide detects relevant requests, evaluates them locally, and assists with the platform-specific action); the four supported platforms presented as monochrome glyphs inside instrument bezels; the safety posture (local evaluation, no ride data sent to a server before a filter decision, DO NOTHING when uncertain).
• Primary actions: Begin self-service enrollment; proceed to returning verification.
• Supporting actions: Read the assistance workflow explanation; view the supported platform set.
• Domain entities: Supported platform identity (Uber, Ola, Rapido, Porter); product identity and tagline.
• Component responsibilities: Anonymous entry surface; wordmark and tagline block; workflow explanation block; platform bezel row; enrollment and verification entry controls.
• States: Loading (static content, no network dependency); empty (not applicable — content is fixed); success (content rendered, entry controls active); error (not applicable to static content); recovery (not applicable).

Login

• Information and state: Returning verification for the Ride-Hailing Driver and for the provisioned Developer / QA Engineer; the identity being verified; verification progress; verification failure reason.
• Primary actions: Submit returning verification credentials; enter the application.
• Supporting actions: Navigate to self-service enrollment; retry after a failed verification.
• Domain entities: Driver identity; Developer / QA Engineer identity; verification session.
• Component responsibilities: Credential entry; verification submission; failure messaging; navigation to enrollment.
• States: Loading (verification in progress); empty (no credentials entered); success (identity verified, protected destinations become reachable); error (verification rejected — reason shown, credentials retained for correction); recovery (retry without losing entered context).

Sign Up

• Information and state: Self-service enrollment for a driver independently beginning use; the fields required to establish the driver's identity; enrollment progress; enrollment failure reason.
• Primary actions: Submit enrollment; establish the driver identity.
• Supporting actions: Navigate to returning verification; correct rejected enrollment input.
• Domain entities: Driver identity; enrollment record.
• Component responsibilities: Enrollment field entry; submission; validation messaging; navigation to verification.
• States: Loading (enrollment submission in progress); empty (no fields entered); success (identity established, driver proceeds to protected destinations); error (enrollment rejected — reason shown, entered values retained); recovery (correct and resubmit).

Home

• Information and state: The FATAKSERIDE wordmark and the tagline "Ride Faster. Work Smarter."; Assist ON/OFF state; the selected platform; the current filters; matched today; accepted today; ignored today; average processing time; the STOP ASSIST control.
• Primary actions: Toggle Assist ON/OFF; invoke STOP ASSIST; change the selected platform; review current filters.
• Supporting actions: Navigate to Live Rides, Filters, History, Analytics, Settings, Permissions, Permission Center, Subscription, Account, Wallet, Test Mode, Developer Mode.
• Domain entities: Assistance state; selected platform; active filter configuration; daily counters (matched, accepted, ignored); average processing time.
• Component responsibilities: Master ASSIST bezel carrying the ON/OFF state and control; platform selection rail; current-filter summary; daily counter strip; average processing time readout; STOP ASSIST plate; navigation to all other destinations.
• States: Loading (assistance state and counters being read from local storage); empty (no requests processed today — counters read zero); success (Assist ON with live counters updating); error (accessibility service not connected or a required permission missing — the affected readout shows its unavailable state and the Permission Center is reachable); recovery (grant the missing permission and re-establish the service connection).

Live Rides

• Information and state: Currently detected and recently processed ride-request activity; per request: platform, request type, fare, pickup distance, trip distance, pickup address, destination address, ride type, rating, action type, timestamp, action bounds, confidence; the filter outcome for each request; the action outcome including ACTION_UNCONFIRMED where verification failed.
• Primary actions: Review a detected request and its outcome; review the rejection reason for an ignored request.
• Supporting actions: Navigate to History for older activity; navigate to Developer Diagnostics for pipeline detail.
• Domain entities: RideRequest; filter result; action result; rejection reason; confidence.
• Component responsibilities: Live request ledger; per-request detail; outcome and reason display; confidence readout.
• States: Loading (awaiting the first event of the session); empty (no current ride activity — an explicit no-current-activity state); success (requests listed with outcomes); error (a request could not be parsed or an action was unconfirmed — the affected entry shows its error or ACTION_UNCONFIRMED state); recovery (the entry remains visible with its reason; no blind repetition occurs).

Filters

• Information and state: Platform selection; the full set of supported filters — Minimum Fare, Maximum Fare, Minimum Trip Distance, Maximum Trip Distance, Maximum Pickup Distance, Minimum Fare/KM, Maximum Fare/KM, Ride Type, Platform, Request Type; each filter's enabled/disabled state and value; the AND-logic relationship between all enabled filters.
• Primary actions: Enable or disable a filter; set a filter value; select the platform; save the filter configuration.
• Supporting actions: Clear a filter value; review which filters are currently active.
• Domain entities: Filter configuration; filter enablement; filter values; selected platform.
• Component responsibilities: Per-filter enablement control; per-filter value entry; platform selection; configuration persistence; active-filter summary.
• States: Loading (configuration being read from local storage); empty (no filters enabled — all requests pass the filter stage); success (configuration saved and applied to subsequent evaluations); error (an entered value is invalid — the field shows the error and the configuration is not saved); recovery (correct the value and save again).

History

• Information and state: Revisitable history of locally processed ride requests and their outcomes; 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, action result, and any recorded ACTION_UNCONFIRMED.
• Primary actions: Review a past request and its outcome; review the reason a request was ignored or left unactioned.
• Supporting actions: Navigate to Analytics for aggregate performance; navigate to Live Rides for current activity.
• Domain entities: Persisted RideRequest records; filter results; action results; rejection reasons.
• Component responsibilities: Chronological history ledger; per-entry detail; outcome and reason display.
• States: Loading (history being read from the Room database); empty (no history recorded yet); success (entries listed with outcomes); error (a history read fails — the failure is surfaced and the list remains usable); recovery (retry the read).

Analytics

• Information and state: Ride performance, earnings, distance, completion, rejection, and acceptance analytics; a period selector; total earnings; total rides; quick stats covering accepted rides, completed rides, distance, and average speed; an earnings overview with daily earnings across the period; ride performance covering completed rides, rejected rides, total distance, average fare per completed ride, and acceptance rate with accepted and rejected counts; a boost performance card.
• Primary actions: Select the reporting period; review performance figures.
• Supporting actions: Navigate to History for the underlying records; navigate to Wallet for balance and transactions.
• Domain entities: Earnings totals; ride counts; distance totals; average speed; average fare; acceptance rate; accepted and rejected counts; daily earnings series.
• Component responsibilities: Period selector; total earnings card; total rides card; quick stats tiles; earnings overview chart; ride performance rows; acceptance rate display; boost performance card.
• States: Loading (aggregates being computed from local history); empty (no rides in the selected period — figures read zero and the chart shows an empty series); success (figures and chart rendered for the selected period); error (aggregation fails — the failure is surfaced and the period selector remains usable); recovery (reselect the period or retry).

Settings

• Information and state: Application settings and persisted operational preferences; the current values of each setting.
• Primary actions: Change a setting; persist the change.
• Supporting actions: Navigate to Permissions and Permission Center; navigate to Account; navigate to Subscription.
• Domain entities: Application settings; operational preferences.
• Component responsibilities: Setting rows with their current values; change controls; persistence.
• States: Loading (settings being read from local storage); empty (settings at their defaults); success (change persisted and applied); error (a change cannot be persisted — the failure is surfaced and the previous value is retained); recovery (retry the change).

Permissions

• Information and state: The permission-related navigation destination for the application's required capabilities; the set of permissions the application actually requires.
• Primary actions: Navigate to the Permission Center to review and grant permissions.
• Supporting actions: Review which capabilities depend on which permissions.
• Domain entities: Required permission set.
• Component responsibilities: Permission overview; navigation into the Permission Center.
• States: Loading (permission status being read); empty (not applicable — the required set is fixed); success (status shown); error (status cannot be read — the failure is surfaced); recovery (retry the read).

Permission Center

• Information and state: Only the permissions actually required by the application, such as Accessibility Service, Notification Access, Overlay, Foreground Service, and Notifications; the current grant state of each; which capability depends on each.
• Primary actions: Grant a required permission; open the relevant Android system settings surface for a permission that cannot be granted in-app.
• Supporting actions: Review why a permission is required.
• Domain entities: Required permission; grant state; dependent capability.
• Component responsibilities: Per-permission row with grant state; grant action; system-settings handoff; dependency explanation.
• States: Loading (grant states being read); empty (not applicable — the required set is fixed); success (all required permissions granted and the dependent capabilities are available); error (a permission is denied or revoked — the affected capability is shown as unavailable and the reason is stated); recovery (grant the permission and re-check).

Subscription

• Information and state: Subscription management for the driver application; the current subscription state; available subscription options.
• Primary actions: Review the current subscription; select a subscription option.
• Supporting actions: Navigate to Wallet for balance and transactions; navigate to Account.
• Domain entities: Subscription state; subscription option.
• Component responsibilities: Current subscription display; option selection; state persistence.
• States: Loading (subscription state being read); empty (no active subscription); success (subscription state shown and updated); error (a subscription change fails — the failure is surfaced and the previous state is retained); recovery (retry the change).

Account

• Information and state: Driver account management destination; the driver's account information as held by the application.
• Primary actions: Review account information; update account information.
• Supporting actions: Navigate to Subscription; navigate to Wallet; navigate to Settings.
• Domain entities: Driver account record.
• Component responsibilities: Account information display; update controls; persistence.
• States: Loading (account information being read); empty (not applicable — an established identity has account information); success (information shown and updates persisted); error (an update fails — the failure is surfaced and the previous values are retained); recovery (retry the update).

Wallet

• Information and state: Available balance; referral rewards; recent transactions with their amounts and descriptions; a security notice stating that wallet and payment information are protected.
• Primary actions: Review the available balance; review recent transactions.
• Supporting actions: View all transactions; navigate to Subscription.
• Domain entities: Wallet balance; referral rewards; transaction record with amount and description.
• Component responsibilities: Available balance display; referral rewards display; recent transactions list; view-all control; security notice.
• States: Loading (balance and transactions being read); empty (no transactions recorded — the list shows an empty state and the balance reads its current value); success (balance and transactions rendered); error (balance or transactions cannot be read — the failure is surfaced); recovery (retry the read).

Test Mode

• Information and state: Driver-facing test-mode entry for safely exercising supported filtering behavior; the current test-mode state.
• Primary actions: Enter test mode; leave test mode.
• Supporting actions: Navigate to the Filter Tester.
• Domain entities: Test-mode state.
• Component responsibilities: Test-mode entry and exit; state indication; navigation to the Filter Tester.
• States: Loading (test-mode state being read); empty (test mode not active); success (test mode active and filtering behavior can be exercised safely); error (test mode cannot be entered — the failure is surfaced); recovery (retry entry).

Developer Mode

• Information and state: Developer and QA entry for diagnostics and validation workflows; the current developer-mode state.
• Primary actions: Enter developer mode; leave developer mode.
• Supporting actions: Navigate to the Filter Tester; navigate to Developer Diagnostics.
• Domain entities: Developer-mode state.
• Component responsibilities: Developer-mode entry and exit; state indication; navigation to the Filter Tester and Developer Diagnostics.
• States: Loading (developer-mode state being read); empty (developer mode not active); success (developer mode active and diagnostics destinations reachable); error (developer mode cannot be entered — the failure is surfaced); recovery (retry entry).

Filter Tester

• Information and state: A dedicated test destination for filter boundaries, missing data, package, duplicate, and emergency-stop cases; the entered test inputs and the resulting outcome. The supported test cases are: ₹199 with minimum ₹200 → IGNORE; ₹200 with minimum ₹200 → MATCH; ₹300 with pickup 7 km and maximum pickup 5 km → IGNORE; ₹900 over 30 km → ₹30/km; missing required data → NO ACTION; unknown package → IGNORE; package changes → CANCEL; duplicate event → PROCESS ONCE; emergency stop → CANCEL.
• Primary actions: Enter test inputs; run a test case; review the resulting outcome.
• Supporting actions: Review the reason for a NO ACTION, IGNORE, or CANCEL outcome; navigate to Developer Diagnostics.
• Domain entities: Test input; test outcome; outcome reason.
• Component responsibilities: Test input entry; test execution; outcome display; reason display.
• States: Loading (test execution in progress); empty (no test inputs entered); success (outcome shown, including MATCH, IGNORE, NO ACTION, CANCEL, PROCESS ONCE, and the ₹30/km fare-per-km result); error (a test cannot be executed — the failure is surfaced); recovery (correct the input and rerun).

Developer Diagnostics

• Information and state: Current package; service status; last event; parsed RideRequest; filter result; action type; confidence; bounds; errors; real latency.
• Primary actions: Review the current pipeline state; review the last event and its parsed request; review the filter result, action type, confidence, and bounds; review recorded errors; review measured latency.
• Supporting actions: Navigate to the Filter Tester; navigate to Developer Mode.
• Domain entities: Active package; service status; accessibility event; parsed RideRequest; filter result; action type; confidence; action bounds; error record; measured latency.
• Component responsibilities: Package readout; service status readout; last-event readout; parsed-request readout; filter-result readout; action-type and confidence readout; bounds readout; error list; latency readout.
• States: Loading (diagnostic values being read from the running pipeline); empty (no event has been observed yet — readouts show their no-data state); success (all diagnostic values rendered, including real measured latency); error (the service is not connected or a pipeline stage reports an error — the error is listed with its stage); recovery (re-establish the service connection and re-read).

3. Functional Requirements

Each requirement below is a distinct story point. Provenance is marked explicit, basic_default, or required_inference.

FR-01 — Product identity. As a Ride-Hailing Driver, I should see the application identified as FATAKSERIDE with the tagline "Ride Faster. Work Smarter." so that I know I am using the correct product. (explicit)

• Trigger: application launch. Observable result: the wordmark and tagline are displayed. Failure/recovery: not applicable to static identity. Continuation: the driver proceeds to the Landing entry or to verification.

FR-02 — Driver-focused assistance purpose. As a Ride-Hailing Driver, I should use an application whose purpose is ride-request filtering and assistance — not a generic taxi app — so that my workflow is built around detecting, evaluating, and acting on ride requests. (explicit)

• Trigger: any use of the application. Observable result: the product's surfaces and behavior are organized around platform selection, filtering, detection, evaluation, and platform-specific action assistance. Failure/recovery: not applicable. Continuation: the driver configures and operates assistance.

FR-03 — Flutter UI over native Kotlin core. As a Ride-Hailing Driver, I should interact with a Flutter/Dart user interface backed by native Android Kotlin for performance-critical functionality so that the interface is responsive while the detection-to-action pipeline stays fast. (explicit)

• Trigger: any interaction. Observable result: UI behavior is delivered by Flutter/Dart; performance-critical processing is delivered by native Kotlin. Failure/recovery: a bridge failure is surfaced rather than silently swallowed. Continuation: the driver continues operating the application.

FR-04 — Layered architecture. As a Developer / QA Engineer, I should have the system built on the layered architecture 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 a single responsibility and can be validated independently. (explicit)

• Trigger: system construction and any pipeline execution. Observable result: each stage exists and passes its output to the next. Failure/recovery: a stage failure is reported at that stage. Continuation: the pipeline either completes or halts safely.

FR-05 — Low latency with measured results. 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 arrive within the request window. (explicit)

• Trigger: a relevant accessibility event. Observable result: the filter decision is produced locally and the measured latency is recorded. Failure/recovery: latency is measured and reported truthfully; no guaranteed one-second performance is claimed. Continuation: the decision proceeds to action evaluation.

FR-06 — Event-driven processing. As a Ride-Hailing Driver, I should have the application process only relevant accessibility events with debouncing and deduplication, and never continuously screenshot, OCR, or poll the screen every few milliseconds, so that the application is efficient and does not waste battery. (explicit)

• Trigger: an AccessibilityEvent. Observable result: only relevant events are processed; duplicate events within the deduplication window are not reprocessed. Failure/recovery: an irrelevant event is discarded without side effects. Continuation: the next relevant event is processed normally.

FR-07 — Separate platform adapters. As a Developer / QA Engineer, I should have separate UberAdapter, OlaAdapter, RapidoAdapter, and PorterAdapter implementations, never one universal implementation for every platform, so that each platform's request UI is handled on its own terms. (explicit)

• Trigger: an event from a supported package. Observable result: the event is routed to that platform's adapter. Failure/recovery: an adapter failure is contained to that platform. Continuation: other adapters continue to operate.

FR-08 — Package detection and routing. As a Ride-Hailing Driver, I should have the active Android package identified and routed to the correct adapter, with unknown packages ignored, so that the application only acts inside supported ride apps. (explicit)

• Trigger: an accessibility event carrying a package name. Observable result: a supported package routes to its adapter; an unknown package is ignored. Failure/recovery: an unknown package produces no action. Continuation: processing resumes when a supported package becomes active.

FR-09 — Cancel on package change. As a Ride-Hailing Driver, I should have a pending action cancelled if the active package changes while that action is pending, so that an action is never delivered to the wrong application. (explicit)

• Trigger: a package change detected while an action is pending. Observable result: the pending action is cancelled. Failure/recovery: the cancellation is recorded; no action is dispatched. Continuation: processing resumes for the newly active package if it is supported.

FR-10 — Genuine request detection only. As a Ride-Hailing Driver, I should have the application 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 the application never acts outside a real request. (explicit)

• Trigger: an accessibility event from a supported package. Observable result: only a genuine active request proceeds; all listed non-request surfaces are excluded. Failure/recovery: a non-request surface produces no action. Continuation: the next event is evaluated normally.

FR-11 — Accessibility tree inspection. As a Developer / QA Engineer, I should have the system 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 are grounded in the real UI. (explicit)

• Trigger: a relevant event. Observable result: the listed node properties are read and used. Failure/recovery: a node that cannot be read is treated as unavailable rather than guessed. Continuation: evaluation proceeds with the available evidence.

FR-12 — Framework independence. As a Developer / QA Engineer, I should have the application interact through legitimate Android accessibility/UI mechanisms without assuming the target app is Flutter, so that it works against native Android, Flutter, React Native, custom-rendered, or other target implementations. (explicit)