📱 Stock Trading Simulator

[](

A modern Android stock trading simulator app with real-time data integration, built with Kotlin, Jetpack Compose, and FastAPI.

🚀 Features

• Real-time Stock Data: Integrates with Polygon.io API for live market data
• Smart Caching: Room database caches data for 1 hour to minimize API calls
• Modern UI: Dark fintech theme with Material Design 3
• Portfolio Management: Track your holdings and performance
• Trading Simulation: Buy and sell stocks with virtual money
• Offline Support: Works with cached data when offline

🏗️ Architecture

Android App (Kotlin + Jetpack Compose)

• UI Layer: Compose screens with Material Design 3
• Data Layer: Room database for local storage
• Network Layer: Retrofit for API communication
• Repository Pattern: Clean architecture with data caching
• MVVM: ViewModels for UI state management

Backend API (Python + FastAPI)

• FastAPI: Async REST API server
• Polygon.io Integration: Real-time stock market data
• SQLite: Local data persistence and caching
• Smart Rate Limiting: Respects API limits with intelligent caching

🛠️ Setup Instructions

1. Backend Setup

cd api
uv sync
cp .env.example .env
# Edit .env and add your Polygon.io API key
uv run python main.py

2. Get Polygon.io API Key

1. Sign up at polygon.io
2. Get your free API key (2 calls/minute limit)
3. Add to api/.env: POLYGON_API_KEY=your_key_here

3. Android App

# Build and install
./gradlew assembleDebug
adb install app/build/outputs/apk/debug/app-debug.apk

# Launch
adb shell am start -n com.madebycommon.commonsimulator/.MainActivity

💾 Data Management

Caching Strategy

• Cache Duration: 1 hour (as requested)
• Fallback: Shows cached data if API is unavailable
• Cleanup: Automatically removes data older than 7 days

API Endpoints

• GET /api/v1/stocks/watchlist - Popular stocks
• GET /api/v1/stocks/quote/{symbol} - Individual stock quote
• GET /api/v1/stocks/search/{query} - Search stocks
• POST /api/v1/portfolio/trade - Execute trades

🎨 UI Design

• Dark Theme: Professional fintech appearance
• Color Palette: Vibrant greens for profits, reds for losses
• Typography: Clear, readable fonts optimized for financial data
• Loading States: Smooth loading indicators and error handling
• Responsive: Works on all screen sizes

📊 Technical Specs

Dependencies

• Kotlin 2.0.21 with Jetpack Compose
• Room 2.6.0 for local database
• Retrofit 2.9.0 for networking
• Material Design 3 for UI components
• FastAPI 0.116.1 for backend
• SQLAlchemy 2.0 for database ORM

Build Requirements

• Android: API 24+ (Android 7.0)
• Java: JDK 11+
• Python: 3.11+
• uv: For Python dependency management

🔄 Development Workflow

1. Start Backend: cd api && uv run python main.py
2. Build Android: ./gradlew assembleDebug
3. Install & Test: App connects to http://10.0.2.2:8000 (emulator)
4. Hot Reload: FastAPI auto-reloads on code changes

📈 Next Steps

• Add real-time portfolio value tracking
• Implement push notifications for price alerts
• Create detailed stock charts and analysis
• Add social features for sharing trades
• Implement advanced trading strategies

---

Built with ❤️ for the modern fintech experience