TradeX

TradeX is an AI-powered equity research and trading platform that combines fundamental analysis, portfolio monitoring, trading workflows, and risk controls in one dashboard.

The product is designed around two complementary modes:

• Research Agent: screens equities, generates investment research, builds DCF-based valuation views, analyzes competitive moats, and produces long or short thesis reports with conviction scoring.
• Trading Agent: monitors a portfolio, evaluates strategy signals, manages orders and trades, applies risk checks, and supports paper-first execution workflows through Alpaca.

This repository is a product and engineering exploration of how an investor workflow could connect research, validation, trading, and risk management in a single system.

This project is for educational and portfolio purposes only. It is not financial advice, and it should not be used for live trading without extensive review, testing, and appropriate safeguards.

Problem

Individual investors and small operators often use fragmented tools for stock research, valuation, watchlists, portfolio tracking, trade execution, and risk monitoring. That fragmentation makes it harder to connect an investment thesis to an actual trading decision, and harder still to audit why a trade happened.

TradeX explores a more integrated workflow:

1. Screen a broad stock universe for potential opportunities.
2. Run deeper fundamental and qualitative research.
3. Convert high-conviction research into structured trade candidates.
4. Apply risk controls before any trade is submitted.
5. Track portfolio state, orders, trades, system health, and notifications.

Product Principles

• Paper trading first: trading workflows are designed to start in paper mode.
• Research does not automatically equal execution: research output can inform trading, but the trading layer applies its own strategy and risk checks.
• Risk controls are product features: position limits, approval thresholds, circuit breakers, and audit logs are treated as first-class requirements.
• Explainability matters: research reports, strategy tags, rationale fields, and audit records are intended to make decisions traceable.
• Single-user v1: the current product scope focuses on a single operator rather than multi-tenant collaboration.

Core Features

Research

• Universe screening for long and short candidates
• Quantamental scoring based on financial and market data
• DCF modeling with valuation scenarios
• Moat and management-quality analysis
• Thesis validation and conviction scoring
• Research reports and watchlist management

Trading

• Portfolio overview, positions, orders, trades, and P&L views
• Strategy engine with momentum, event-driven, statistical, and options modules
• Market regime detection
• Pre-trade risk checks
• Paper/live portfolio modes
• Alpaca reconciliation and trade stream support
• Strategy performance reporting

Operations

• Supabase-backed persistence
• Audit logging for important system and user actions
• Background scheduler for research, trading, reconciliation, health checks, and notifications
• Email and in-app notification support
• System health and metrics endpoints

Architecture

TradeX is split into a Python backend, a Next.js frontend, and a Supabase database.

frontend/          Next.js dashboard
backend/           FastAPI API, research engine, trading engine
supabase/          Database migrations and row-level security policies
tests/             Backend test suite
docs/              Product and design documentation

Backend

The backend is a FastAPI application. It exposes API routes for research, trading, portfolio state, settings, system health, and notifications.

Important areas:

• backend/main.py initializes the API, scheduler, database, trading engine, and route registration.
• backend/api/ contains the public API surfaces.
• backend/engine/research/ contains the screening, DCF, moat, and thesis generation logic.
• backend/engine/trading/ contains portfolio, strategy, order execution, reconciliation, regime detection, and risk-management logic.
• backend/data/ contains external data clients and caching.
• backend/notifications/ contains notification dispatching, email, and push support.

Frontend

The frontend is a Next.js application with a dashboard-style interface.

Current sections include:

• Dashboard
• Research screening
• Research reports
• Watchlist
• Portfolio
• Orders
• Trade log
• Settings
• System health

Database

Supabase/PostgreSQL stores research, trading, portfolio, audit, cache, and notification data. The migrations define tables for:

• Stocks
• Screen results
• Research reports
• Watchlist items
• Portfolios
• Positions
• Orders
• Trades
• Risk configuration
• Risk events
• Audit logs
• Strategy performance
• Daily snapshots
• Data cache
• Notifications

Tech Stack

• Backend: Python, FastAPI, APScheduler, Pydantic
• Frontend: Next.js, React, TypeScript, Tailwind CSS, TanStack Query, Recharts
• Database/Auth/Realtime: Supabase
• Brokerage: Alpaca
• Market and financial data: Financial Modeling Prep, FRED, SEC EDGAR, Yahoo Finance fallback
• LLM: Anthropic Claude
• Notifications: Resend email, Supabase-backed notifications

Getting Started

1. Clone the repository

git clone https://github.com/ishita1989/TradeX.git
cd TradeX

2. Configure environment variables

Copy the example environment file and provide local values:

cp .env.example .env

The backend expects credentials for Supabase, Alpaca, data providers, Anthropic, and optional notifications. Keep .env private. It is ignored by Git.

3. Install backend dependencies

This project uses Python 3.9+.

pip install -e ".[dev]"

4. Run the backend

uvicorn backend.main:app --reload

By default, the API is available at:

http://localhost:8000

5. Install frontend dependencies

cd frontend
npm install

6. Run the frontend

npm run dev

By default, the dashboard is available at:

http://localhost:3000

Testing

Run the backend test suite with:

pytest

Run the frontend lint check with:

cd frontend
npm run lint

Product Documentation

The detailed product/design spec lives here:

• Equity Research & Trading Agent Design

Additional product-thinking docs:

• Product Brief
• Prioritization
• Architecture
• User Stories
• Risks And Guardrails

Safety And Security Notes

• Do not commit .env files, private keys, certificates, or credential JSON.
• Use paper trading before considering any live trading flow.
• Treat all generated research as an input for human review, not as an autonomous decision-maker.
• Review all risk controls, approval thresholds, and brokerage permissions before connecting real accounts.
• Enable GitHub secret scanning before making the repository public.

Repository Status

This project is an active prototype and product-thinking portfolio project. Some features are implemented end to end, while others represent planned or partially implemented product direction.