Skip to content

QUICKSTART.md

Latest commit

 

History

History
330 lines (260 loc) · 7.64 KB

QUICKSTART.md

File metadata and controls

330 lines (260 loc) · 7.64 KB

EfficientPortfolioManagerv2 - Quick Start Guide

🎯 TL;DR - Get Running in 2 Minutes

Backend (Terminal 1)

cd EfficientPortfolioManagerv2/backend
source venv/bin/activate  # Windows: venv\Scripts\activate
python run.py
# ✅ Running on http://localhost:8000
# 📚 API Docs: http://localhost:8000/docs

Frontend (Terminal 2)

cd EfficientPortfolioManagerv2/frontend
npm install
npm run dev
# ✅ Running on http://localhost:3000

Open Browser

📊 What You Get

🏠 Home Page
  ├── Portfolio Optimizer Link
  └── Efficient Frontier Link

📈 Portfolio Optimizer (/optimizer)
  ├── Input: Tickers, Portfolio Value, Lookback Period
  └── Output: Weights, Sharpe Ratio, Discrete Shares

📉 Efficient Frontier (/frontier)
  ├── Input: Tickers, Lookback Period
  └── Output: Frontier Chart + Optimal Portfolio

💼 Portfolio Management (/portfolio)
  └── Coming Soon...

🎯 Try These

Test 1: Basic Optimization

  1. Go to http://localhost:3000/optimizer
  2. Enter: AAPL, MSFT, GOOGL
  3. Portfolio Value: 100000
  4. Lookback: 252
  5. Click "Optimize Portfolio"
  6. See: Optimal allocation, Sharpe ratio, discrete shares

Test 2: Efficient Frontier

  1. Go to http://localhost:3000/frontier
  2. Enter: AAPL, MSFT, GOOGL, AMZN, TSLA
  3. Lookback: 252
  4. Click "Generate Frontier"
  5. See: Frontier curve with optimal point highlighted

📁 Project Structure

EfficientPortfolioManagerv2/
│
├── backend/                    # FastAPI (Python)
│   ├── app/
│   │   ├── services/          # DataFetch, Optimization, Portfolio
│   │   ├── api/v1/            # REST endpoints
│   │   ├── models.py          # Request/response types
│   │   ├── database.py        # SQLAlchemy ORM
│   │   └── config.py          # Settings
│   ├── tests/                 # 66 passing tests
│   ├── requirements.txt       # Python dependencies
│   └── run.py                 # Development server
│
├── frontend/                   # Next.js (TypeScript/React)
│   ├── app/                   # Pages (home, optimizer, frontier)
│   ├── components/            # Navbar, Forms, Charts
│   ├── hooks/                 # useOptimize, useFrontier
│   ├── lib/                   # API client, types
│   ├── package.json           # npm dependencies
│   └── .env.local             # API configuration
│
└── memory-bank/               # Project documentation
    ├── projectBrief.md        # Vision & scope
    ├── decisions.md           # Architecture decisions
    ├── systemPatterns.md      # Design patterns
    ├── progress.md            # Phase tracking
    └── ... (more docs)

🔧 Commands Reference

Backend

cd backend
python run.py                  # Start dev server
pytest tests/ -v              # Run tests (66 passing)
pytest tests/ --cov           # With coverage report
pip install -r requirements.txt # Install dependencies

Frontend

cd frontend
npm run dev                    # Start dev server
npm run build                  # Production build
npm run lint                   # Check code quality
npm install                    # Install dependencies

🎨 Key Features

✅ Portfolio Optimization

  • Input: Tickers, portfolio value, lookback period
  • Output: Optimal weights, Sharpe ratio, discrete shares

✅ Efficient Frontier Visualization

  • Interactive SVG chart
  • 50-point frontier curve
  • Optimal portfolio highlighted

✅ Responsive Design

  • Desktop, tablet, mobile
  • Tailwind CSS styling
  • Smooth animations

✅ Type Safety

  • Full TypeScript (frontend)
  • Python type hints (backend)
  • Pydantic validation

✅ Error Handling

  • Form validation
  • API error messages
  • Loading states

📊 API Endpoints

Optimize Portfolio

POST http://localhost:8000/api/v1/optimize

Request:
{
  "tickers": ["AAPL", "MSFT", "GOOGL"],
  "lookback_days": 252,
  "portfolio_value": 100000
}

Response:
{
  "weights": {"AAPL": 0.4, "MSFT": 0.3, "GOOGL": 0.3},
  "expected_return": 0.12,
  "volatility": 0.18,
  "sharpe_ratio": 0.56,
  "discrete_shares": {"AAPL": 133, "MSFT": 100, "GOOGL": 100}
}

Generate Frontier

GET http://localhost:8000/api/v1/efficient-frontier?tickers=AAPL,MSFT,GOOGL&lookback_days=252

Response:
{
  "frontier_points": [
    {"volatility": 0.15, "expected_return": 0.10},
    ...
  ],
  "optimal_portfolio": {
    "weights": {...},
    "expected_return": 0.12,
    "volatility": 0.18,
    "sharpe_ratio": 0.56
  }
}

⚠️ Troubleshooting

Backend Won't Start

# Check Python version (need 3.10+)
python --version

# Verify venv is activated
which python  # Should show venv path

# Reinstall dependencies
pip install -r requirements.txt

Frontend Won't Start

# Check Node version (need 18+)
node --version

# Clear cache and reinstall
rm -rf node_modules package-lock.json
npm install

# Check .env.local exists
cat .env.local

CORS Errors

❌ Access to XMLHttpRequest blocked by CORS policy

✅ Solution: Backend should have CORS enabled
   Check app/main.py has CORSMiddleware configured
   Verify frontend NEXT_PUBLIC_API_BASE_URL matches backend URL

API Connection Failed

❌ Failed to fetch from API

✅ Solution:
   1. Check backend is running: http://localhost:8000/docs
   2. Check .env.local: NEXT_PUBLIC_API_BASE_URL=http://localhost:8000
   3. Check network tab in DevTools (browser console)

📈 What's Working

✅ Backend (66 tests passing)

  • DataFetchService: Fetch historical prices from Yahoo Finance
  • OptimizationService: Calculate optimal portfolio with max-Sharpe
  • PortfolioService: Save/retrieve portfolios and optimization history
  • API endpoints: /optimize and /efficient-frontier

✅ Frontend (Fully scaffolded)

  • Home page with feature overview
  • Optimizer page with form and results
  • Frontier page with visualization
  • Type-safe API integration
  • Responsive mobile design

✅ Database

  • SQLAlchemy ORM models
  • Portfolio persistence
  • Optimization history tracking

🚀 Next Phase: Local Integration Testing

  1. Start both servers (see "Quick Start" above)
  2. Test main workflows:
    • Optimizer: Input tickers → Get allocation
    • Frontier: Input tickers → View chart
  3. Test error cases:
    • Invalid tickers
    • Empty inputs
    • Network failures
  4. Test mobile:
    • Chrome DevTools → Mobile view
    • Verify responsive design

📚 More Information

  • Detailed Status: See development-status.md
  • Implementation Checklist: See IMPLEMENTATION_CHECKLIST.md
  • Frontend Details: See frontend/README.md
  • Backend Details: See backend/README.md
  • Project Brief: See memory-bank/projectBrief.md

🎓 Tech Stack Summary

Backend

  • FastAPI (web framework)
  • Pydantic v2 (validation)
  • PyPortfolioOpt (optimization)
  • yfinance (market data)
  • SQLAlchemy (ORM)
  • Redis (optional caching)
  • pytest (testing)

Frontend

  • Next.js 14 (framework)
  • React 18 (UI library)
  • TypeScript (type safety)
  • Tailwind CSS (styling)
  • Axios (HTTP client)
  • React Hook Form (forms)

💾 Saving Your Work

All code is in git-ready directories:

git add .
git commit -m "Phase 8: Frontend scaffolding complete"
git push

🎉 You're Ready!

Everything is set up and ready to go. Run the commands above and start exploring!

Questions? Check the memory-bank files or code comments.

Happy optimizing! 📊📈