Each epic, feature, and story below links to its tracking issue on GitHub. Board: https://github.com/users/sandhya1631/projects/2

Pain Point — Wants to trade systematically but lacks coding knowledge or time to watch charts all day. Impact — Can deploy a personalized, autonomous trading agent in a risk-free paper environment to test strategies without losing real savings.

Pain Point — Studying algorithmic trading and LLM capabilities but hindered by complex broker infrastructure. Impact — A plug-and-play platform to experiment with prompt strategies, agent tool calling, and deterministic guardrails.

Pain Point — Suffers from revenge trading and over-leveraging. Impact — Hardcoded safety barriers that physically prevent impulsive, destructive orders from reaching the exchange.

---

Description — Scaffold the client application, base layouts, and API client with auth-token handling.

• US-0.1.1 — Client Scaffold & Tailwind Setup (#15) — As an operator, I want an initialized Next.js UI with Tailwind CSS and base layouts, so that the team has a standard design system.
  • Acceptance: app compiles cleanly; navigation header; persistent sidebar; base theme styling.
• US-0.1.2 — API Client & Auth Interceptors (#16) — As a frontend developer, I want a centralized API fetch client with token interceptors, so that API calls attach JWT tokens automatically.
  • Acceptance: injects Bearer <token> on outbound requests; handles 401 Unauthorized globally.

Description — Stand up FastAPI + async PostgreSQL, implement JWT-based user authentication, and encrypt stored Alpaca broker credentials.

• US-0.2.1 — FastAPI & Async PostgreSQL Setup (#17) — As a developer, I want a FastAPI skeleton connected to PostgreSQL via Async SQLAlchemy, so that non-blocking DB operations are supported.
• US-0.2.2 — User Authentication & JWT Auth (#18) — As a user, I want to register and log in securely, so that only authorized operators access trading controls and logs.
  • Acceptance: bcrypt password hashing; POST /auth/login returns a signed JWT; unauthenticated access to protected routes is blocked.
• US-0.2.3 — Encrypted Alpaca Credential Vault (#19) — As a user, I want my Alpaca API key and secret stored using encryption, so that plaintext credentials are never exposed in the DB.
  • Acceptance: symmetric encryption (Fernet) before storage; runtime decryption for broker calls.

Description — Set up Docker Compose for a local multi-service environment, a GitHub Actions CI pipeline, and an abstracted LLM client factory supporting both OpenAI and local Ollama.

• US-0.3.1 — Docker Compose Environment (#35) — As a developer, I want a multi-container Docker Compose file (backend, db, frontend), so that setup is reproducible in one command.
  • Acceptance: docker compose up --build brings up all services; env vars load cleanly from .env.
• US-0.3.2 — GitHub Actions CI Pipeline (#20) — As a developer, I want automated linting and testing on pull requests, so that broken builds are prevented from merging.
  • Acceptance: runs Ruff and PyTest on PRs; enforces test pass before merge.
• US-0.3.3 — Abstracted LLM Client Factory (#21) — As an engineer, I want a unified LLM interface supporting OpenAI and local Ollama, so that model providers can be switched via .env.
  • Acceptance: LLM_PROVIDER switches OpenAI ↔ Ollama without changing orchestration code.

---

Description — Fetch OHLCV price bars for the watchlist and compute deterministic technical indicators (RSI, SMA).

• US-1.1.1 — Fetch Candlestick OHLCV Data (#22) — As a trading engine, I want to pull 5-minute price bars for a stock watchlist via the Alpaca Data API, so that the system has live market context.
  • Acceptance: retrieves latest 50 bars for the watchlist (AAPL, NVDA, SPY); handles rate limits with retries.
• US-1.1.2 — Technical Indicator Math (#23) — As a quant engine, I want to calculate 14-period RSI and 20/50-SMA using pandas-ta, so that indicator values are deterministic.
  • Acceptance: outputs valid floats rounded to 2 decimals; zero NaN values.

Description — Poll account balances/positions and dispatch/confirm order execution against the Alpaca Paper Trading API.

• US-1.2.1 — Account & Portfolio Polling (#24) — As a portfolio tracker, I want to poll cash, buying power, and open positions from the Alpaca Paper API, so that balances remain synchronized.
  • Acceptance: parses responses into typed Pydantic models; handles empty position states cleanly.
• US-1.2.2 — Order Placement & Confirmation (#25) — As an execution service, I want to dispatch market/limit orders to Alpaca Paper Trading, so that approved trades are executed.
  • Acceptance: dispatches valid orders (symbol, qty, side, type); returns broker order UUID and status.

---

Description — Define strict JSON schemas for agent actions (place_order, hold) and summarize market state into a structured, token-bounded prompt.

• US-2.1.1 — Tool Schema Definition & Validation (#26) — As an agent engine, I want strict JSON schemas for actions (place_order, hold), so that the LLM only outputs valid function calls.
  • Acceptance: enforces schema validation; malformed JSON fails gracefully into an error log without crashing.
• US-2.1.2 — Market State Summarization (#27) — As a prompt builder, I want to format indicators, positions, and cash into a structured prompt, so that the LLM has concise reasoning context.
  • Acceptance: prompt under 1,500 tokens; instructs the LLM to justify actions with numerical values.

Description — Run a scheduled decision loop every 15 minutes during market hours, logging each execution cycle and its results to PostgreSQL.

• US-2.2.1 — Scheduled Decision Loop (#28) — As a background runner, I want a scheduler to run the agent loop every 15 minutes during market hours, so that trading is autonomous.
  • Acceptance: checks market clock (is_open == True); logs execution cycles and results to PostgreSQL.

---

Description — Enforce hardcoded pre-trade checks (max capital allocation, low cash, closed market) that block unsafe orders before they reach the broker, verified by a dedicated safety test suite.

• US-3.1.1 — Max Capital Allocation Guard (#29) — As a risk manager, I want to reject any buy order exceeding 10% of portfolio equity, so that capital is not over-concentrated.
  • Acceptance: if qty * price > 0.10 * equity, reject immediately and log the reason.
• US-3.1.2 — Low-Cash & Closed-Market Check (#30) — As a risk guardrail, I want to block trades if cash is insufficient or the market is closed, so that invalid orders never reach the broker.
  • Acceptance: rejects buys when order_cost > cash or the market clock is closed; the broker is never called.
• US-3.1.3 — Safety Guardrail Test Suite (#31) — As a tester, I want synthetic tests for malformed or illegal trades, so that the safety boundary is proven 100% effective.
  • Acceptance: 100% of illegal test orders (oversized qty, low cash, closed market) fail at the guardrail layer.

---

Description — Real-time portfolio/positions UI, a chronological agent reasoning and audit-trail timeline, and manual trigger / kill-switch controls for operators.

• US-4.1.1 — Real-Time Portfolio & Positions UI (#32) — As an operator, I want to view cash, portfolio equity, and open positions on a web dashboard, so that account status is clear.
  • Acceptance: renders live equity cards, unrealized PnL badges, and an active positions table.
• US-4.1.2 — Agent Reasoning & Audit Trail UI (#33) — As an auditor, I want a chronological timeline showing indicator snapshots, LLM rationale, and trade outcomes, so that AI decisions are transparent.
  • Acceptance: timeline displays each cycle; expands to show rationale, indicators, and broker order ID.
• US-4.1.3 — Manual Trigger & Kill Switch (#34) — As an operator, I want a "Trigger Now" button and an emergency "Kill Switch", so that I can control cycles during live testing and demos.
  • Acceptance: "Trigger Now" runs an on-demand cycle; "Kill Switch" stops all broker order dispatching instantly.