CFD instrument technical and fundamental analysis application. Provides market data retrieval with multi-provider fallback, technical indicators, and analysis endpoints via a REST API.

• Python 3.13 / FastAPI / Pydantic 2
• SQLAlchemy 2 (async, SQLite for MVP)
• Data providers: yfinance (primary), Twelve Data, Financial Modeling Prep
• Analysis: pandas-ta, TA-Lib

• Next.js 14 (App Router) / TypeScript 5
• TailwindCSS 3.4 with CSS custom properties (dark theme)
• lightweight-charts v5 for interactive candlestick charts
• Docker Compose for full-stack deployment

• Python 3.12–3.13
• TA-Lib C library installed on the system

cd backend
python -m venv .venv
# Windows
.venv\Scripts\activate
# Linux/macOS
source .venv/bin/activate

pip install -e ".[dev]"
cp .env.example .env
# Edit .env with your API keys (optional — yfinance works without keys)

uvicorn app.main:app --reload

cd frontend
npm install
npm run dev

The frontend is available at http://localhost:3000.

cp backend/.env.example backend/.env
# Edit backend/.env with your API keys

docker compose up --build

The application is available at http://localhost (nginx reverse proxy). Health check: GET /api/v1/health. API documentation: http://localhost/api/v1/docs.

┌──────────────┐      ┌──────────────┐
│   Frontend   │      │   Backend    │
│  Next.js 14  │◄────►│  FastAPI     │
│  :3000       │      │  :8000       │
└──────┬───────┘      └──────┬───────┘
       │                     │
       └────────┬────────────┘
                │
         ┌──────▼──────┐
         │   nginx     │
         │   :80       │
         └─────────────┘

The backend is organized into independent domain modules that communicate through core models:

backend/app/
├── api/v1/          # REST + WebSocket endpoints
├── core/            # Settings, database, shared models, logging
└── modules/
    ├── data_acquisition/      # Multi-provider market data (yfinance, Twelve Data, FMP)
    ├── technical_analysis/    # 9 oscillators, 12 MAs, 5 pivot types
    ├── pattern_recognition/   # Candlestick, S/R, Fibonacci, IKI, geometric
    ├── fundamental_analysis/  # Forex/commodity/index macro analysis (FRED, FMP)
    ├── signal_aggregation/    # Weighted signal scoring and consolidation
    └── strategy_generator/    # Entry/exit scenarios with SL/TP levels

Import boundaries are enforced by import-linter contracts defined in pyproject.toml.

GET /api/v1/market-data/EURUSD?timeframe=H1&period=30d

Supported symbols include forex pairs (EURUSD, GBPUSD, …), commodities (GOLD, SILVER, …), indices (US500, US30, …), and more. Timeframes: M15, H1, H4, D1. Period format: {n}d, {n}m, {n}y.

POST /api/v1/technical-analysis
{"symbol": "EURUSD", "timeframe": "H1", "period": "90d"}

Returns 9 oscillator/momentum indicators (RSI, MACD, Stochastic, CCI, ADX, AO, Momentum, Williams %R, Ultimate Oscillator), 12 moving averages (SMA + EMA for periods 5–200), 5 pivot point types (Classic, Fibonacci, Camarilla, Woodie, DeMark), and an aggregated signal summary.

POST /api/v1/patterns
{"symbol": "EURUSD", "timeframe": "H1", "period": "180d"}

Detects candlestick patterns (15 types via TA-Lib), support/resistance levels with strength scoring, Fibonacci retracement levels, IKI (Impulse-Correction-Impulse) patterns, and geometric chart patterns (triangle, wedge, flag, pennant).

POST /api/v1/fundamental-analysis
{"symbol": "EURUSD"}

Automatically routes to the correct analyzer based on instrument type. Forex pairs compare interest rate and inflation differentials between base and quote currencies. Commodities analyze COT positioning, USD strength, and rate environment. Indices evaluate regional macro data (rates, unemployment). Data sourced from FRED API and Financial Modeling Prep.

POST /api/v1/analysis
{"symbol": "EURUSD", "timeframe": "H1"}

Triggers an asynchronous 6-step pipeline: data fetch → technical analysis → pattern recognition → fundamental analysis → signal aggregation → strategy generation. Returns an analysis_id to poll via GET /api/v1/analysis/{id} or subscribe via WS /api/v1/ws/analysis/{id} for live progress updates. The final report includes weighted signal scoring, entry point scenarios (aggressive and conservative), SL/TP levels, and confidence percentages.

Copy backend/.env.example to backend/.env. For production see .env.production.example.

# Backend — unit & integration tests
cd backend
python -m pytest tests/ -v

# Architecture boundary checks
lint-imports

# Frontend lint & type-check
cd frontend
npm run lint
npm run build

# E2E tests (requires running frontend)
cd frontend
npm run test:e2e

# Performance tests (requires k6 CLI)
k6 run tests/performance/analysis.k6.js

Contributions are welcome! Please read the Contributing Guide before submitting a pull request.

To report a security vulnerability, please see SECURITY.md for instructions.

See CHANGELOG.md for a detailed history of changes.

This project is licensed under the MIT License.