Solution Overview

What we're building

Agentic Paper Trader is a full-stack, autonomous trading system that connects a Large Language Model (LLM) to a simulated brokerage account (Alpaca Paper Trading) through a strict, deterministic safety layer. It is not a trading-signal app for humans to read — the agent itself decides and acts, within hardcoded limits that no LLM output can override.

Type of application: A containerized, multi-service web application consisting of:

• A background agent service (Python) that polls market data on a fixed schedule, asks an LLM to reason over it, and validates/executes any resulting trade decision
• A web dashboard (React) that lets a human operator observe — but not directly control — what the agent is doing and why
• A PostgreSQL database that stores a full audit trail of every decision, whether it was approved or rejected, and the market context behind it

Hosting: All services run as containers orchestrated with Docker Compose. This keeps the agent loop, the API/backend, the dashboard, and the database reproducible across every team member's machine and, later, a single deployable unit for demo/grading purposes. We are not targeting a distributed cloud deployment this semester — a single-host Compose setup is sufficient for an MVP and keeps operational complexity low.

Types of users:

• The Aspiring Retail Investor — wants systematic, emotion-free trading without writing code
• The Student/Academic Researcher — wants a sandbox to experiment with agent tool-calling and prompt strategies without building broker plumbing from scratch
• The Risk-Conscious Trader — needs hardcoded guardrails that a human (or an LLM) cannot override in the moment

All three interact with the system the same way: they configure a strategy, then observe the agent's autonomous behavior through the dashboard. No user places trades manually.

Why this architecture

The central risk in this project isn't market risk — it's that LLMs are probabilistic and can hallucinate numbers, miscalculate position sizing, or emit malformed instructions. We chose a three-layer separation of concerns specifically to contain that risk:

1. Context Layer — deterministic, code-only. Computes exact indicators (RSI, SMA) from real price data using Python math libraries. The LLM never does this math itself.
2. Reasoning Layer — the LLM only reasons over already-computed, trusted context and emits a structured tool call (place_order, hold). It cannot execute anything directly.
3. Execution & Safety Layer — deterministic code re-validates every LLM-proposed action against hardcoded rules (max 10% capital exposure, trading-hours checks) before it ever reaches the Alpaca API. A structurally valid order is still rejected if it violates a safety rule.

Alternatives we considered and rejected:

• Let the LLM call the broker API directly — rejected, because a single hallucinated parameter (e.g. wrong share count) could execute a real, unintended trade with no checkpoint in between.
• A fully rules-based system with no LLM at all — rejected, because it removes the natural-language reasoning and multi-factor synthesis (news, indicators, context) that is the actual subject of this project; it would just be a traditional trading bot.
• Human-in-the-loop approval for every trade — rejected for the MVP scope, since the goal is autonomous operation; instead we substitute human review with deterministic, code-level review, which is faster and removes emotional bias entirely.

This separation means the system's safety properties don't depend on the LLM behaving well — they hold even if the LLM is wrong, inconsistent, or adversarially prompted.