RealizeAlpha

RealizeAlpha is a professional-grade Flutter mobile app for multi-account brokerage management (Robinhood, Schwab, Fidelity), featuring AI-powered trade signals, automated agentic trading, and institutional-grade options analytics including Gamma Exposure (GEX) and institutional flow tracking.

Getting Started

• Product Overview & Scope: PRODUCT.md — Target personas, core product principles, capability pillars, and strategic scope boundaries.
• Documentation Site: RealizeAlpha Docs (docs/index.md) — Detailed feature guides, architecture references, and API research.
• Roadmap & Release History: ROADMAP.md & CHANGELOG.md — Active development priorities and release notes.
• Coding Agent & Contributor Guide: AGENTS.md — Repository layout, safety invariants, and verification commands.

Features

For full product context and architectural boundaries, see PRODUCT.md. For recent release highlights, see CHANGELOG.md.

Multi-Brokerage, Banking & Retirement

• Multi-Brokerage Connectivity: Connect live Robinhood and Charles Schwab accounts alongside Fidelity CSV imports (positions & transaction history), a full-featured Paper Trading Simulator (with guest-to-authenticated account migration), and instant Demo mode.
• Schwab Real-Time Streamer & Throttling: Sub-second WebSocket streaming (wss://streamer-api.schwab.com/ws) for equities (LEVELONE_EQUITIES), options & Greeks (LEVELONE_OPTIONS), account/order activity (ACCT_ACTIVITY), chart candles (CHART_EQUITY), futures, and forex with Real-Time Stream Throttling & Battery Conservation (250ms per-symbol throttling, viewport-bounded subscriptions, and background lifecycle pausing).
• Multi-Account Aggregation & Retirement: Unified cross-account portfolio view with persistent active-account switching, Traditional/Roth IRA support (ira_traditional, ira_roth), annual IRS contribution tracking, Robinhood Gold Match Maximizer, spending accounts, and connected OAuth agent management.
• Stock Lending (SLIP), Cash Sweeps & Banking: Track loaned securities, 102% collateral backing, and monthly SLIP payments alongside high-yield cash sweep APY projections and multi-bank FDIC coverage, plus ACH Transfers & Linked Bank Accounts.

Progressive Portfolio, Risk & Tax Optimization

• Progressive Portfolio & Action Center: Decision-focused workspace with hero P&L metrics, an account-aware Action Center with context-first deep-linking, top movers, and dedicated Performance, Positions, Risk, Insights, Taxes, and Strategies tabs powered by a unified Portfolio Analytics Controller.
• Multi-Asset Allocation & Risk Parity Rebalancing: Interactive allocation charts across all 7 asset classes (Stocks, Options, Crypto, Forex, Futures, Fixed Income, Cash), sector/industry breakdowns, drift analysis, AI Asset Allocation (including All-Weather presets), on-device Marginal Contribution to Risk (MCR %), and Risk Parity & Inverse-Volatility Portfolio Rebalancing.
• Quantitative Risk, Margin & Circuit Breakers: Beta-Weighted Portfolio Greeks, Correlation Matrix, portfolio stress testing, tail-risk & liquidity scoring, ESG Scoring, Margin Calls & Financing Costs, , , pre-trade checks, , and .

Options, Futures, Crypto & Forex Trading

• Option Chain Screener & Strategy Builder: Filter option chains by Delta, Gamma, Theta, Vega, and IV with AI "Find Best Contract" suggestions, visual payoff diagrams, Options Collateral & Tier Upgrades, and redesigned Option Instrument Position Cards.
• Multi-Leg Spreads, Combo Orders & Roll Assistant: Structural order templates for Verticals, Straddles, Strangles, Iron Condors, and Calendars; Combo Orders (Stock + Option Packages); Options Strategy Roll Assistant; Multi-Leg Options Defense & Roll Playbook (including 0DTE Pin Risk & Ex-Dividend Early Assignment alerts); and Landscape Charting & Matrix View.
• Advanced Order Types & Templates: Trailing Stop, Stop-Limit, and Time-in-Force (GTC, IOC) orders across equities and options with reusable Order Templates.
• Futures, Crypto & Forex Execution: Live futures position tracking, margin calculations, , and ; dedicated and (Micro/Mini/Standard lots, live pip values); plus the quantitative .

Trade Signals, Backtesting & Agentic Trading

• Multi-Indicator Agentic Trading: Autonomous and semi-autonomous trading powered by a 19-Indicator Technical Evaluation System across 15m, 1h, and 1d intervals, Agentic Reasoning Mode, live-quote BUY price validation, authoritative dynamic/fixed position sizing, Custom Indicators, strategy templates, and a 5-Tier GEX Sequential Stop Queue with trailing stops and emergency kill switches.
• Macro Regime Assessment: 19-indicator institutional macro engine (VIX, MOVE, Yield Curve, Credit Spreads, Market Breadth) classifying global market regimes (RISK_ON, RISK_OFF, NEUTRAL) with weighted 0–100 scoring and strategy guidance.
• Historical Backtesting & Alpha Discovery: Test multi-indicator strategies across custom date ranges and intervals with equity curves, Sharpe ratio, profit factor, drawdown analytics, reusable templates, Alpha Factor Discovery (Information Coefficient & ICIR), and Event Study Analyzer.

Quantitative Derivatives & Market Intelligence

• Gamma Exposure (GEX) Analysis: Portfolio-wide and per-symbol net/gross gamma profiling, gamma flip transition levels, call/put walls, Market Maker Pinning Gauge, spot-shift sensitivity, and an on-device Dart Black-Scholes fallback engine.
• Options Flow Analysis: Real-time institutional sweep, block, whale, and 0DTE/1DTE flow detection with 30+ smart flags and trade-specific verification checklists.
• Smart Money, Insider & Political Disclosures: Track institutional accumulation and officer activity via Whale Watch, Insider Activity, Institutional Ownership, SEC EDGAR Filings (13F, Form 4, 8-K), Congress & STOCK Act Filings, Short Interest & Borrow Availability, and Retail Order Flow.
• Screeners, Charting & Market Data: Multi-benchmark historical charts, (SMA, EMA, VWAP, Bollinger Bands, TTM Squeeze), , and .

AI Copilot, Behavioral Coaching & Local MCP

• Unified AI Conviction & Factor Alignment: Synthesizes multi-factor quantitative models (Trend, Momentum, Volatility, Flow & GEX), adversarial stress tests, and Gemini 3.1 Flash-Lite reasoning into an institutional conviction rating (0–100, Very High to Conflicted) embedded directly on order tickets and instrument research.
• Local Model Context Protocol (MCP) Client: On-device Dart MCP client paired with Gemini to inspect live balances, positions, orders, and watchlists, generate AI Price Targets, and draft Markdown Instrument Notes.
• AI Devil's Advocate & Thesis Stress Tester: Pre-trade adversarial critique computing a 0–100 Resilience Score (Fragile, Moderate, Resilient), surfacing the "Killer Question" vulnerability, options skew traps, event hazards, and shock scenarios directly inside research and order sheets.
• AI Trade Post-Mortem & Trading Coach: Post-trade execution grading (0–100, A–F) separating decision quality from outcome luck (goodWin, badWin, goodLoss, badLoss), automatic cognitive bias tagging into the Trading Psychology & Emotion Journal, streak tracking, challenge verification, and Sentiment Analysis foundations.

Social, Investor Groups 2.0 & Protected Copy Trading

• Investor Groups 2.0: Private and public groups with member roles, real-time Group Activity Feeds, Group Chat, Shared Analysis Boards, Verified Track Records, and collaborative Group Watchlists.
• Protected Copy Trading: Mirror or inverse-copy stock and option trades from group leaders with manual approval or auto-execution, position/notional caps, take-profit/stop-loss rules, and a pre-trade Copy Trade Risk Guardian.

Platform, Security & Mobile Experience

• Zero-Plaintext Security & Feature Gating: Hardware-backed credential encryption via flutter_secure_storage (iOS Keychain / Android Keystore), biometric authentication (FaceID/TouchID), Balance Visibility Masking, and Feature Access & Beta Labs Gating.
• Native Mobile Experience & Offline Resilience: Encrypted Offline Mode & Resilient Caching, iOS Live Activities & Dynamic Island, Home Screen Widgets, Trade Signal Push Notifications, Custom Price & Event Alerts, Universal Deep Linking & Referrals, and Material 3 UI & Accessibility Polish.

Architecture Overview

RealizeAlpha utilizes a combination of technologies:

• Mobile App: Developed using the Flutter SDK and Dart for cross-platform deployment (iOS, Android).
• Backend Services: Firebase Functions (written in TypeScript/JavaScript) are used for:
  • Securely interacting with brokerage APIs (see Brokerage Endpoints).
  • Handling business logic that shouldn't reside on the client.
  • Integrating with AI services (e.g., Google AI Gemini API via MCP Integration).
• Authentication: Firebase Authentication manages user sign-in and security with encrypted on-device token storage (see Secure Token Storage).
• Database/Storage: Cloud Firestore stores user documents, preferences, and portfolio telemetry (see Entity-Relationship Diagram).
• Hosting & CI/CD: Firebase Hosting is used for web components, with GitHub Actions CI/CD automation (see Mobile CI Setup).

Latest Release

• RealizeAlpha | Apple App Store: TestFlight only, production release coming soon. (See TestFlight Deployment Guide).
• RealizeAlpha | Google Play Store: Internal testing only, production release coming soon.

Build

Dependencies

In order to build and debug locally, you must install the following dependencies:

• Android Studio (for Android deployment)
• XCode (for iOS deployment)
• Flutter SDK
• VS Code
• Dart & Flutter VS Code extensions

To ensure your installation was successful, run this command:

flutter doctor -v

Once you see a "No issues found!" message, you are ready to start running the application.

Run & Debug

In VS Code, F5 key, the Run icon, or from the Run menu to start debugging. If prompted choose the Flutter configuration.

Android Device

1. Enable USB debugging on your Android device.
2. Plug in your device.
3. Open the command palette (Ctrl+Shift+P) and enter Flutter: Select Device
   Or
   Navigate to the project directory and run the flutter command.

   flutter run
   

Debugging Notes

Wireless debugging

• On device, open Settings > System > Developer options.
  • Enable USB debugging & Wireless debugging.
• Connect device to computer over USB. Accept pairing notification on device.
• Open Android Studio > Tools > Device Manager and pair device.
• Run these commands to connect wirelessly:

  $ ${HOME}/AppData/Local/Android/Sdk/platform-tools/adb tcpip 5555
  restarting in TCP mode port: 5555
  $ ${HOME}/AppData/Local/Android/Sdk/platform-tools/adb connect 192.168.86.36
  connected to 192.168.86.36:5555
  

• Unplug device and start debugging.

iOS Device

1. Enable developer on your iOS device.
2. Open Devices and Simulators window in XCode and ensure that your device is paired and connected.
3. Open the command palette (Ctrl+Shift+P) and enter Flutter: Select Device
   Or
   Navigate to the project directory and run the flutter command.

   flutter run --release
   

Debugging Notes

• For error Exception: Error running pod install, run the following commands:

  rm -rf ./ios/Pods;rm ./ios/Podfile.lock;flutter clean;flutter pub get
  flutter build ios
  # or flutter run
  

  If that doesn't work try a pod repo update.

  cd ios
  pod repo update
  flutter build ios
  

  If that doesn't work try a pod update in ios. Then in Xcode clean build folder, and build again.

Web

Select a browser from the device selector. Note: Direct client-side brokerage requests in the browser are restricted by CORS unless routed through backend Cloud Functions.

Emulator

Select an iOS Simulator or Android Emulator from the device selector and run flutter run.

Install

Device

1. Connect your Android device to your computer with a USB cable.

2. Navigate to the project directory and run the flutter command.

   flutter install
   

   The response should contain the following status message.

   Installing app.apk to Pixel 5...
   Uninstalling old version...
   Installing build\app\outputs\flutter-apk\app.apk...                 5.2s
   

Maintain

Upgrade dependencies

Flutter upgrades

To ensure you are using the latest packages, run these commands to check and upgrade them:

flutter pub outdated
flutter pub upgrade --major-versions
flutter pub upgrade --tighten

Firebase upgrades

Run these commands in both functions and firebase folders for Firebase function deployment and running admin tools respectively.

npm install -g npm-check-updates
ncu -u
npm install

Generate App Icons & Launch Images

1. Replace src/robinhood_options_mobile/icon.png with the latest icon PNG image at the maximum possible resolution (1024x1024).
2. Run dart run flutter_launcher_icons in the project directory to generate all icons for iOS and Android.
3. Run dart run flutter_native_splash:create in the project directory to generate all splash screens for iOS, Android, and Web.

Linting (javascript & typescript)

To fix issues with code formatting such as:

10 errors and 0 warnings potentially fixable with the --fix option. Error: functions predeploy error: Command terminated with non-zero exit code 1

Run the following command in the functions directory.

npm run lint -- --fix

You can do this automatically in VS Code by installing the eslint plugin.

Manage Firebase Auth Claims

Change a user role to admin

• Download Service Account private key from https://console.firebase.google.com/project/realizealpha/settings/serviceaccounts/adminsdk
• Open src/robinhood_options_mobile/firebase/firebase-admin.js Node.js file.
  • Change the path of the downloaded file at the following line: var serviceAccount = require("/path/to/service-account-key.json");
  • Change the UID of the user that you want to grant the admin role to:

    admin.credential.setCustomUserClaims('<USER_UID>', {
        role: 'admin'
    });
    

• Save and execute the Node.js script from the firebase folder.

  node firebase-admin.js
  

Seed Agentic Trading Data

To seed initial data for the Agentic Trading feature, run the following command in the functions directory:

firebase functions:call seedAgenticTrading

or

firebase functions:shell
> seedAgenticTrading({data:{full:true}})

Invoke Agentic Trading Cron Job Manually

To manually invoke the Agentic Trading cron job, run the following command in the functions directory:

# firebase functions:call agenticTradingCronInvoke
firebase functions:shell
> agenticTradingCronInvoke({data:null})

Publish

Firebase Hosting

firebase.json was changed to modify the hosting property "source": "." to "public": "build/web" in order to deploy custom builds.

#flutter build web --web-renderer html
flutter build web --release
firebase deploy --only hosting

Previously, the public folder was deployed with this configuration:

{
  "hosting": {
    "public": "public",
    "ignore": [
      "firebase.json",
      "**/.*",
      "**/node_modules/**"
    ],
    "rewrites": [
      {
        "source": "**",
        "destination": "/index.html"
      }
    ]
  }
}

Firebase Functions

Functions will automatically deploy with hosting deployments with firebase deploy. To deploy only the functions, use the following command.

firebase deploy --only functions

The following secrets should be configured to prevent storing sensitive passwords and tokens in source control.

# Change the value of an existing secret
firebase functions:secrets:set GEMINI_API_KEY
# View the value of a secret
firebase functions:secrets:access GEMINI_API_KEY

Firebase Firestore

To deploy the Firestore rules and indexes, use the following command.

firebase deploy --only firestore

To export the current Firestore indexes to the local files, use the following command.

firebase firestore:indexes > ./firebase/firestore.indexes.json
# firebase firestore:indexes --export
#firebase firestore:rules > ./firebase/firestore.rules

Android Play Store

Build app bundle

flutter build appbundle --release

Generate APKs

This command generates an .apk file used to publish an installation file.

flutter build apk --release

Apple App Store

Build IPA

flutter build ipa --release

If you get an error, see Debugging Notes section above to clean the project.

Upload to App Store

1. Install Transporter App
2. Add ipa file from ./build/ios/ipa/
3. Verify and Deliver

For complete App Store Connect and TestFlight build instructions, see TestFlight Deployment.

Test

For testing standards, architecture patterns, and regression test conventions, see Testing Standards.

Unit & Widget Tests

flutter test

Integration Tests

To run the end-to-end integration tests:

flutter test integration_test/app_test.dart

Contribute

Before contributing or running coding agents in this repository, review AGENTS.md for architectural guidelines, security/trading invariants, and verification commands, and PRODUCT.md for product principles and scope boundaries.

Agent Skills & Workflows

RealizeAlpha provides structured agent skills for roadmap planning, implementation, and documentation synchronization:

• Roadmap Ideation (.github/skills/roadmap-ideation/SKILL.md): Propose evidence-backed roadmap items and link GitHub issues (> /roadmap-ideation).
• Roadmap Execution (.agents/skills/roadmap/SKILL.md): Implement the highest-priority actionable feature from ROADMAP.md end-to-end with tests and docs (> /roadmap).
• Automated Documentation Sync (.agents/skills/update-docs/SKILL.md): Increment the app version and synchronize CHANGELOG.md, ROADMAP.md, README.md, and .github/copilot-instructions.md (> /update-docs [nextversion]).

Future Enhancements

This project is actively evolving. For the product vision and strategic scope boundaries, see PRODUCT.md. For the prioritized backlog of planned features and enhancements, see ROADMAP.md.

Key areas of planned development include:

• Portfolio, Tax & Risk Analytics: Multi-asset Brinson & Greek return attribution, Risk Parity & inverse-volatility rebalancing, and cross-account tax optimization.
• Derivatives & Execution: Futures SPAN margin health & intraday seasonality, 0DTE regime playbooks, and advanced multi-leg strategy automation.
• Social & Copy Trading: Options contract adaptation and defined-risk guardrails for group copy trading, verified track records, and collaborative research.
• Platform Foundation: Offline resilience, accessibility, security hardening, and App Store / Play Store production readiness.

See the full documentation for detailed descriptions of each feature and planned enhancement.