117 lines
4.0 KiB
Markdown
117 lines
4.0 KiB
Markdown
# 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).
|