TradeSignal

Live Demo: tradesignal.capital

Built by Saad Kadri | LinkedIn | GitHub

Real-time insider trading intelligence platform for tracking SEC Form 4 filings, congressional trades, and market-moving transactions with LUNA—an AI-powered insights engine driven by Google Gemini.

Overview

TradeSignal is a comprehensive financial intelligence platform that aggregates and analyzes insider trading activity, congressional stock transactions, and market data to help users make informed investment decisions. Built with modern technologies and real-time data processing, featuring the LUNA intelligence layer for deep forensic analysis of market moves.

Tech Stack

Backend

FastAPI - High-performance async Python web framework
PostgreSQL - Primary database (Supabase hosted)
Redis - Caching and rate limiting
Celery - Distributed task queue for scheduled scraping
SQLAlchemy - ORM and database management
Prometheus - Metrics and monitoring

Frontend

React 18 - Modern UI library with hooks
TypeScript - Type-safe JavaScript
Vite - Fast build tool and dev server
Tailwind CSS - Utility-first styling
React Router - Client-side routing
React Query - Server state management

Infrastructure

Docker & Docker Compose - Containerization
Nginx - Reverse proxy (production)
Supabase - Managed PostgreSQL database
Grafana - Metrics visualization (optional)

Legacy System Architecture

TradeSignal uses a hybrid multi-language architecture following enterprise patterns used by major technology companies:

Python Backend (Legacy) - 🔒 Maintenance-only mode
- All existing 48,184 LOC AI/ML services (LUNA Engine, Gemini integration)
- Data pipelines (SEC scraping, congressional trades, Form 4 parsing)
- Financial calculations with Decimal precision
- Celery background tasks and scheduled jobs
- Status: Frozen - No new features, bug fixes only
TypeScript Backend (New) - 🚀 Active development
- Framework: Next.js API routes
- All NEW features and business logic
- All NEW API endpoints
- Communication: REST APIs + Shared PostgreSQL database
- Status: All future development happens here

Rationale: Optimized for AI-driven development team (Claude Code, Cursor, Gemini, Kilo Code). TypeScript provides compile-time safety, better AI code generation, and faster iteration cycles.

See legacysystem.md for detailed architecture documentation, decision rationale, and development workflows.

Key Features

Backend Services (25+ API Routers)

Core Services

Authentication - JWT-based auth with login, register, password reset
Insider Trades - SEC Form 4 scraping and tracking
Congressional Trades - Political stock transaction monitoring
Companies & Insiders - Detailed profiles and historical data
Billing - Stripe integration with 4-tier subscription system

Research & Analytics (PRO Features)

Research API - IVT, TS Score, Risk Level, Thesis data
AI Insights - AI-powered trade analysis and summaries
Patterns Detection - Insider trading pattern recognition
Enterprise Research - Advanced research endpoints

Data & Monitoring

News - Financial news aggregation and filtering
Federal Reserve - Fed calendar and economic event tracking
Earnings - Earnings calendar and reports
Stock Prices - Live market data integration
Data Health - Data quality monitoring

Administration

Admin Dashboard - User management and system administration
Scheduler - Automated scraping with configurable schedules
Tasks - Background task management
Health Checks - System monitoring and uptime tracking

User Features

Alerts - Custom trade alerts and notifications
Push Notifications - Real-time alerts for important trades
Contact & Support - Ticket system for user inquiries
Jobs - Career opportunities and applications

Enterprise Features

Webhooks - Custom webhook integrations
Enterprise API - High-volume API access
Marketing API - Campaign management

Frontend Pages (20+)

Authentication

Login, Register, Password Reset, Profile

Dashboard & Trading

Dashboard - Overview of recent trades and market activity
Trades - Insider trading activity with filtering
Congressional Trades - Political trading transparency
Market Overview - Live market indices and sector performance
Patterns - Trading pattern analysis

Company & Insider Research

Company Pages - Detailed company info with research badges (IVT, TS Score, Risk Level)
Insider Pages - Individual insider profiles and trade history

News & Events

News - Curated financial news feed
Fed Calendar - Upcoming economic events

AI & Research (PRO)

AI Insights - AI-powered analysis

Education

Lessons - Educational content for users
Strategies - Trading strategy guides

Account & Billing

Pricing - Subscription tiers and feature comparison
Order History - Billing and subscription management
Profile - User settings

Support & Info

Support & FAQ - Help center and documentation
Contact & Careers - Public pages for inquiries and job listings
Blog - Company blog
About, Terms, Privacy - Legal and informational pages

Subscription Tiers

Feature	Free	Plus	PRO	Enterprise
Insider Trades	Limited	Full	Full	Full
Congressional Trades	View	Full	Full	Full
Research Badges (IVT, TS Score, Risk)	-	-	✓	✓
AI Insights	-	-	✓	✓
Pattern Detection	-	-	✓	✓
Custom Alerts	3	10	Unlimited	Unlimited
API Access	-	-	Limited	Full
Webhooks	-	-	-	✓
Priority Support	-	-	✓	✓

Current Status (December 2025)

Production Fixes Completed ✅

Backend Fixes:

Fixed Forum API double prefix bug causing 404 errors (forum.py:30)
Corrected CORS middleware ordering to prevent request blocking (main.py:427-438)
Removed orphaned pattern_analysis_service imports (legacy LUNA migration cleanup)
Backend health checks passing on Render.com production environment

Frontend Fixes:

Removed Chart Patterns from navigation (feature deprecated during LUNA migration)
Created Release Notes page with full version history
Fixed AI dialog dark theme styling (all ProtectedRoute dialogs)
Fixed Dashboard font consistency to match Landing page dark theme aesthetic
Updated stat cards to use opacity backgrounds with borders

Active Development 🔄

Setting up TypeScript backend infrastructure (Next.js API routes)
Planning REST API communication layer between Python and TypeScript services
Designing shared database access patterns
Configuring Render.com deployment for multi-service architecture

Known Issues 🔧

Requiring Environment Configuration:

Fed Calendar 503 errors - Need FRED_API_KEY configured on Render.com
Stale insider trades data - Celery Beat scheduler verification needed
CORS origins - Verify CORS_ORIGINS environment variable includes all production domains

See RENDER_ENV_SETUP.md for environment variable configuration guide.

Quick Start

Prerequisites

Docker & Docker Compose
Node.js 18+ (for local frontend development)
Python 3.11+ (for local backend development)

Environment Setup

Clone the repository:

git clone https://github.com/skadri1601/TradeSignal.git
cd TradeSignal

Create environment files:

# Backend environment
cp backend/.env.example backend/.env

# Frontend environment
cp frontend/.env.example frontend/.env

Configure environment variables (see below)

Docker Deployment (Recommended)

Start all services with Docker Compose:

# Start all services
docker-compose up -d

# View logs
docker-compose logs -f

# Stop services
docker-compose down

Access the application:

Frontend: http://localhost:3000
Backend API: http://localhost:8000
API Documentation: http://localhost:8000/docs
Metrics: http://localhost:8000/metrics

Local Development

Backend

cd backend
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate
pip install -r requirements.txt
uvicorn app.main:app --reload --port 8000

Celery Worker (for background tasks)

cd backend
celery -A app.core.celery_app worker --loglevel=info --pool=solo -n worker@%h

Frontend

cd frontend
npm install
npm run dev

Environment Variables

Backend Key Variables

# Database (Supabase)
DATABASE_URL=postgresql://user:pass@db.supabase.co:5432/postgres

# Redis
REDIS_URL=redis://localhost:6379/0

# JWT Authentication
SECRET_KEY=your-secret-key-here
ACCESS_TOKEN_EXPIRE_MINUTES=30

# Stripe Billing
STRIPE_SECRET_KEY=sk_test_...
STRIPE_WEBHOOK_SECRET=whsec_...

# SEC API
SEC_USER_AGENT=YourApp/1.0 (your@email.com)

# Feature Flags
ENABLE_AI_INSIGHTS=true
ENABLE_WEBHOOKS=true
SCHEDULER_ENABLED=true

Frontend Key Variables

VITE_API_URL=http://localhost:8000
VITE_STRIPE_PUBLISHABLE_KEY=pk_test_...

API Documentation

Interactive API documentation is available at:

Swagger UI: http://localhost:8000/docs
ReDoc: http://localhost:8000/redoc

Key API Endpoints

/api/v1/auth/* - Authentication
/api/v1/trades/* - Insider trades
/api/v1/congressional-trades/* - Congressional trades
/api/v1/companies/* - Company data
/api/v1/insiders/* - Insider profiles
/api/v1/research/* - Research data (PRO)
/api/v1/ai/* - AI insights (PRO)
/api/v1/news/* - Financial news
/api/v1/admin/* - Administration

Project Structure

TradeSignal/
├── backend/                 # FastAPI backend
│   ├── app/
│   │   ├── core/           # Core utilities (security, cache, celery)
│   │   ├── models/         # SQLAlchemy database models
│   │   ├── routers/        # API endpoint routes (25+)
│   │   ├── schemas/        # Pydantic request/response schemas
│   │   ├── services/       # Business logic layer
│   │   ├── tasks/          # Celery background tasks
│   │   ├── middleware/     # Custom middleware
│   │   └── main.py         # Application entry point
│   ├── tests/              # Backend tests
│   └── requirements.txt    # Python dependencies
├── frontend/               # React frontend
│   ├── src/
│   │   ├── api/           # API client functions
│   │   ├── components/    # React components
│   │   │   ├── research/  # Research badges (IVT, TS Score, Risk)
│   │   │   ├── layout/    # Layout components
│   │   │   └── ...
│   │   ├── contexts/      # React contexts (Auth, Notifications)
│   │   ├── hooks/         # Custom React hooks
│   │   ├── pages/         # Page components (20+)
│   │   └── App.tsx        # Application root
│   └── package.json       # Node dependencies
├── Docs/                   # Documentation
├── docker-compose.yml     # Docker orchestration
└── README.md             # This file

Development Workflow

Create feature branch: git checkout -b feature/your-feature
Make changes and test locally
Run tests: pytest (backend) / npm test (frontend)
Commit changes: git commit -m "feat: your feature"
Push and create PR: git push origin feature/your-feature

Testing

Backend

cd backend
pytest                          # Run all tests
pytest tests/test_trades_api.py  # Run specific test
pytest --cov=app               # Run with coverage

Frontend

cd frontend
npm test              # Run tests
npm run test:watch    # Watch mode

Deployment

Production deployment guide:

Set production environment variables
Configure SSL/TLS certificates
Set up production database (Supabase recommended)
Configure Redis for production
Deploy with Docker Compose or Kubernetes
Set up monitoring and logging
Configure backup strategy

See backend/README.md and frontend/README.md for detailed deployment instructions.

Documentation

Legacy System Architecture - Multi-language architecture (Python + TypeScript)
Backend README - Python backend setup (maintenance mode)
Frontend README - React frontend setup and development
Docs/ - Additional documentation
API Documentation - Interactive API docs at http://localhost:8000/docs

Support

Documentation: See Docs/ directory
Issues: Create a GitHub issue

Author

Saad Kadri - Full-Stack Developer

Portfolio: saadkadri.dev
LinkedIn: linkedin.com/in/saad-kadri-58b8bb205
GitHub: github.com/skadri1601

Name		Name	Last commit message	Last commit date
Latest commit History 174 Commits
.github/workflows		.github/workflows
Docs		Docs
backend		backend
data_pipeline		data_pipeline
frontend		frontend
grafana/provisioning/datasources		grafana/provisioning/datasources
scripts		scripts
.env.example		.env.example
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
docker-compose.grafana.yml		docker-compose.grafana.yml
docker-compose.monitoring.yml		docker-compose.monitoring.yml
docker-compose.yml		docker-compose.yml
legacysystem.md		legacysystem.md
package-lock.json		package-lock.json
package.json		package.json
prometheus.yml		prometheus.yml
render.yaml		render.yaml
scrape_all.py		scrape_all.py
vercel.json		vercel.json

License

skadri1601/TradeSignal

Folders and files

Latest commit

History

Repository files navigation

TradeSignal

Overview

Tech Stack

Backend

Frontend

Infrastructure

Legacy System Architecture

Key Features

Backend Services (25+ API Routers)

Core Services

Research & Analytics (PRO Features)

Data & Monitoring

Administration

User Features

Enterprise Features

Frontend Pages (20+)

Authentication

Dashboard & Trading

Company & Insider Research

News & Events

AI & Research (PRO)

Education

Account & Billing

Support & Info

Subscription Tiers

Current Status (December 2025)

Production Fixes Completed ✅

Active Development 🔄

Known Issues 🔧

Quick Start

Prerequisites

Environment Setup

Docker Deployment (Recommended)

Local Development

Backend

Celery Worker (for background tasks)

Frontend

Environment Variables

Backend Key Variables

Frontend Key Variables

API Documentation

Key API Endpoints

Project Structure

Development Workflow

Testing

Backend

Frontend

Deployment

Documentation

Support

Author

License

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors 2

Languages

Packages