Simplex - Risk-Based Portfolio Allocation Platform

A risk-first portfolio designer that teaches Indian investors how to allocate across equity, gold, debt, and crypto -- without telling them what stock to buy.

What This App Does

• Risk Assessment - Questionnaire-based risk profiling with scoring engine
• Portfolio Design - Asset-class allocation ranges based on individual risk score
• Stock Suggestions - Vector-similarity-based stock matching using ChromaDB
• AI Research Chat - Conversational interface powered by DeepSeek / Gemini for stock research
• Live News Feed - Real-time market news with sentiment analysis via Finnhub
• Education - Learn why diversification reduces risk with interactive content
• Tax Awareness - High-level tax information (LTCG, STCG, 80C)
• Visualizations - Charts, risk meters, allocation breakdowns

What This App Does NOT Do

• No direct "Buy stock X" recommendations
• No trade execution
• No personalized financial advice (SEBI compliance)
• No broker integration

Tech Stack

Layer	Technology
Frontend	React.js (Vite)
Backend	Python (FastAPI)
Vector DB	ChromaDB (cosine similarity)
LLM Providers	DeepSeek / Google Gemini (fallback chain)
Charts	Chart.js / Recharts
News API	Finnhub
Risk Engine	Rule-based (no ML)

Getting Started

Prerequisites

• Python 3.10+
• Node.js 18+
• API keys (see backend/.env.example)

Backend

cd backend
pip install -r requirements.txt

Copy the example environment file and fill in your API keys:

cp .env.example .env

Environment variables:

Variable	Required	Description
DEEPSEEK_API_KEY	Yes (or GEMINI)	DeepSeek API key for AI chat
DEEPSEEK_MODEL	No	Model name, defaults to deepseek-chat
GEMINI_API_KEY	Yes (or DEEPSEEK)	Google Gemini API key (recommended)
FINNHUB_API_KEY	No	Finnhub key for live news feed

Start the backend server:

uvicorn app.main:app --reload

Seed the Vector Database

The app uses ChromaDB for stock similarity search. Seed it with NIFTY 500 data:

cd backend

# Option 1: Load from bundled JSON (fast, no network)
python -m scripts.seed_from_json

# Option 2: Fetch live data from yfinance (slow, ~15-30 min)
python -m scripts.seed_vector_db
python -m scripts.seed_vector_db --test   # test with 5 stocks
python -m scripts.seed_vector_db --force  # clear and reseed

Frontend

cd frontend
npm install
npm run dev

The frontend runs on http://localhost:5173 by default.

Project Structure

simplex/
├── frontend/                  # React + Vite
│   └── src/
│       ├── components/        # Reusable UI components
│       │   ├── Navbar          # Navigation bar
│       │   ├── RiskMeter       # Risk score gauge
│       │   ├── RiskResult      # Risk assessment output
│       │   ├── AllocationChart # Portfolio pie chart
│       │   ├── NewsAlerts      # Live news ticker
│       │   ├── NewsPreferences # News filter settings
│       │   ├── NotificationBell# Alert notifications
│       │   ├── TopPerformers   # Top stock cards
│       │   └── Disclaimer      # Legal footer
│       ├── pages/             # Route-level pages
│       │   ├── LandingPage
│       │   ├── RiskQuestionnaire
│       │   ├── PortfolioPage
│       │   ├── MyPortfolio
│       │   ├── ResearchChat
│       │   ├── EducationPage
│       │   └── TaxInfoPage
│       └── services/          # API client layer
├── backend/                   # FastAPI
│   ├── app/
│   │   ├── main.py            # App entry point
│   │   ├── routes/            # API endpoints
│   │   ├── services/          # Business logic
│   │   │   ├── risk_service          # Risk scoring
│   │   │   ├── allocation_service    # Portfolio allocation
│   │   │   ├── vector_db_service     # ChromaDB wrapper
│   │   │   ├── stock_vectorizer      # Stock-to-vector conversion
│   │   │   ├── suggestion_service    # Personalized suggestions
│   │   │   ├── conversation_service  # AI chat (DeepSeek/Gemini)
│   │   │   ├── news_service          # Finnhub news aggregation
│   │   │   ├── sentiment_service     # News sentiment analysis
│   │   │   ├── portfolio_service     # Portfolio management
│   │   │   ├── stock_service         # Stock data
│   │   │   └── analytics_service     # Usage analytics
│   │   ├── models/            # Pydantic schemas
│   │   ├── data/              # Static data + ChromaDB store
│   │   └── jobs/              # Background schedulers
│   └── scripts/               # DB seeding utilities
├── .env.example
└── README.md

API Endpoints

Method	Endpoint	Description
GET	/	API info
GET	/health	Health check
GET	/disclaimer	Legal disclaimer
POST	/api/risk/calculate	Calculate risk score
GET	/api/allocation/{risk}	Get allocation for risk level
GET	/api/education/topics	Education content
GET	/api/stocks/...	Stock data endpoints
POST	/api/portfolio/...	Portfolio management
POST	/api/personalization/...	Personalized suggestions
POST	/api/conversation/...	AI research chat
GET	/api/news/...	Market news and alerts

Legal Disclaimer

IMPORTANT: This platform provides educational information and generalized portfolio frameworks. It does not offer investment advice, stock recommendations, or tax advisory services. Consult a SEBI-registered advisor for personalized advice.

License

MIT