BreakoutDesk

1. Product Overview

BreakoutDesk is a trading research and paper-trading workspace for finding stocks that may be breaking out after a quiet consolidation period.

If you are new to trading, think of it this way: some stocks move sideways for a while, then suddenly move above their recent price range with stronger volume. Traders call this a breakout. BreakoutDesk scans a fixed US stock/ETF universe and highlights tickers that match a defined swing-trading strategy.

This project is built for learning, research, and pilot paper trading. It is not financial advice and it should not be treated as an automatic money-making system.

What It Does

• Scans US stocks and ETFs using Alpaca market data.
• Looks for daily breakout candidates based on a proprietary swing-trading workflow.
• Shows flagged tickers in a clean dashboard.
• Displays daily candlestick chart data for selected tickers.
• Lets the user change screening configuration from a Setup page.
• Lets the user include or exclude selected screening filters.
• Supports manual paper-trade approval before any order is sent.
• Logs flagged tickers, trade approvals, configuration changes, and feedback in JSONL files.

Trading Idea In Plain English

BreakoutDesk helps review stocks that may be transitioning from a quiet trading range into a stronger move. It combines price action, volume behavior, liquidity, and trend context into a configurable screening workflow.

The exact screening logic and thresholds are treated as proprietary strategy IP and are intentionally not documented here.

Unique Features

• Beginner-friendly setup: the screening workflow is configurable instead of hidden inside code.
• Rule include/exclude toggles: users can test the screening workflow with or without selected filters.
• Manual approval workflow: the app does not blindly trade every signal; the user must approve paper trades.
• Paper trading first: designed for safe experimentation before any real trading workflow.
• Configurable trade sizing: supports shares, per-trade dollar amount, or percentage of account buying power.
• Configurable exit plan: paper-trade risk and target settings can be adjusted before approval.
• Audit-friendly logs: important events are saved as JSONL files under logs/.
• Feedback capture: users can save standalone feedback or ticker-level feedback with timestamps.

What Gets Logged

Runtime logs are written under logs/:

• logs/flagged_tickers.jsonl - every successfully flagged ticker with timestamp and configuration snapshot.
• logs/trade_actions.jsonl - manual paper-trade approvals and Alpaca order results.
• logs/feedback.jsonl - all feedback entries.
• logs/ticker_feedback.jsonl - ticker-level feedback linked to a ticker/candidate when available.
• logs/config_changes.jsonl - strategy setup changes.
• logs/strategy_config.json - latest saved setup.

Main Screens

• Scanner: run the daily scan, review candidates, inspect charts, and approve paper trades.
• Setup: change screening configuration, include/exclude filters, configure position sizing, and configure exit settings.
• Activity: review recent JSONL log activity.

Current Scope

• Data provider: Alpaca.
• Trading mode: paper trading.
• Trade action: manual approval only.
• Universe: fixed US stock/ETF list for v1.
• Future v2 direction: larger tradable universe, stronger persistence, and richer trading workflows.

2. How To Run

Prerequisites

Install:

• Python 3.12 or compatible Python 3 version.
• Node.js and npm.
• Alpaca API credentials with market-data access and paper-trading access.

Backend Setup

From the project root:

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Create a local .env file in the project root:

APCA_API_KEY_ID=your_key_id
APCA_API_SECRET_KEY=your_secret_key
APCA_API_BASE_URL=https://data.alpaca.markets
ALPACA_DATA_FEED=iex
ALPACA_AUTH_MODE=trading
ALPACA_BROKER_ENV=paper

Start the backend:

uvicorn backend.main:app --reload --port 8000

Backend URL:

http://localhost:8000

Interactive API docs:

http://localhost:8000/docs

Frontend Setup

Open a second terminal:

cd breakout-scanner
npm install
npm run dev

Frontend URL:

http://localhost:5173

The Vite frontend proxies /api requests to the backend at:

http://localhost:8000

Useful API Routes

• GET /api/health - check whether the API is running.
• GET /api/strategy-config - load the active strategy, sizing, and exit setup.
• PUT /api/strategy-config - save configurable setup and include/exclude toggles.
• POST /api/breakout-scans - scan the market for breakout candidates.
• POST /api/candlestick-chart - load daily candlestick data for one ticker.
• POST /api/paper-trades - manually approve a long paper trade for a flagged ticker.
• POST /api/feedback - log standalone or ticker-level feedback.
• GET /api/activity - read recent scanner, trade, and feedback logs.

Alpaca Troubleshooting

If you see this error:

Alpaca rejected the market-data request. Check the API key, secret, data subscription, and APCA_API_BASE_URL.

Run the notebook diagnostics:

jupyter notebook .tests/playbook.ipynb

The notebook checks:

• Whether .env is loaded correctly.
• Raw Alpaca market-data requests.
• Alpaca SDK market-data requests.
• Paper-trading account access.
• Broker sandbox credential behavior.

Build Check

Backend syntax check:

python3 -m compileall backend

Frontend production build:

cd breakout-scanner
npm run build