# 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/](file:///home/nathan/cyberhybridhub.com/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

```mermaid
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](https://docs.flutter.dev/get-started/install) (latest stable version)
*   [Dart SDK](https://dart.dev/get-dart)
*   [PostgreSQL](https://www.postgresql.org/) (running locally)

### 2. Database Setup
Create the development and test databases:
```bash
createdb cyberhybridhub
createdb cyberhybridhub_test
```

### 3. Server Setup
Navigate to the `server/` directory and configure environment variables:
```bash
cd server
cp .env.example .env
```
Update `.env` with your Postgres connection details and Alpaca API credentials.

Install dependencies and run the server:
```bash
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:
```bash
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:

```bash
./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](file:///home/nathan/cyberhybridhub.com/server/README.md).