Cyber Hybrid Hub

A hybrid, interactive guessing-game and automated trading platform. Cyber Hybrid Hub integrates live Alpaca market data and paper trading with a Flutter frontend and a Postgres-backed Dart backend API.

---

Project Structure

The repository consists of two main components:

• Flutter Client (Root): The mobile and web application interface where users answer questions, track their scores, and where administrators can audit background synchronization tasks.
• Dart API Server (server/): A high-performance Dart API server that manages authentication, stores market data snapshots, serves questions, handles scoring, and executes trades via the Alpaca API.

---

Key Features

1. Market Guessing Game: Generates obfuscated price-movement questions for active US equities. Users swipe to guess direction (+10 for up, -10 for down) and earn scores based on closeness.
2. Spelling Challenge: An interactive, catalog-driven spelling game with integrated progress scoring.
3. Alpaca Ingestion & Trading Pipeline:
   • Ingests live 1Min bar data from Alpaca Market Data and aggregates them into two regular-session half-days (Morning: 9:30 AM–12:45 PM ET, Afternoon: 12:45 PM–4:00 PM ET) per trading day.
   • Executes paper trading orders automatically based on rule-evaluation matches and user confirmation.
   • Protects against rate-limiting (429) and enforces daily/hourly notional guardrails.
4. Admin Portal: A dedicated interface for operators to monitor database sync runs (universe sync, backfills, cleanup), pin unresolved failures (rate limits, partial runs), and trigger on-demand sync or retention cleanup tasks.

---

Architecture Diagram

flowchart TB
  subgraph flutter [Flutter App]
    UI[HomeScreen / Swipe UI]
    AdminUI[Admin Portal Screen]
    Hub[QuestionsHubService SignalR]
  end

  subgraph server [Dart API Server]
    API[Shelf Router Handlers]
    Worker[QuestionBackgroundWorker]
    Orchestrator[TradingOrchestrator]
    QP[QuestionPipeline]
    AlpacaMD[Alpaca Market Data Client]
    AlpacaTR[Alpaca Trading Client]
  end

  subgraph pg [Postgres Database]
    MD[market_data_snapshots]
    Runs[market_data_sync_runs]
    Q[questions]
    Config[user_trading_config]
    Orders[trade_orders]
  end

  AlpacaMD -->|REST Poll / Ingest| MD
  Worker --> Orchestrator
  Orchestrator --> MD
  Orchestrator --> Runs
  QP --> Q
  QP --> Hub
  Hub --> UI
  API --> UI
  AdminUI -->|Admin Actions| API
  API --> AlpacaTR
  AlpacaTR -->|POST Orders| Orders

---

Setup & Running

1. Prerequisites

• Flutter SDK (latest stable version)
• Dart SDK
• PostgreSQL (running locally)

2. Database Setup

Create the development and test databases:

createdb cyberhybridhub
createdb cyberhybridhub_test

3. Server Setup

Navigate to the server/ directory and configure environment variables:

cd server
cp .env.example .env

Update .env with your Postgres connection details and Alpaca API credentials.

Install dependencies and run the server:

dart pub get
dart run bin/server.dart

4. Running the Flutter App

From the root directory, run the Flutter application pointing to your local server:

flutter run --dart-define=API_BASE_URL=http://localhost:3000

---

Running Tests

Root scripts

To run the full validation suites, use the helper scripts located in the scripts/ directory:

./scripts/test-server.sh          # Runs server unit and integration tests (no live Alpaca)
./scripts/test-admin-portal.sh   # Runs Flutter + server admin portal test suites
./scripts/test-server-alpaca.sh   # Runs live Alpaca integration tests (requires keys in server/.env)

For more server-specific implementation details, check out the server README.