# Treding Forex Ai Blueprint

## Product Vision

Membuat Telegram trading assistant untuk forex yang membantu user mengambil keputusan secara disiplin melalui analisis teknikal, signal probabilistik, dan risk management. Bot mengutamakan mode `WAIT` ketika setup tidak jelas.

## Target User

- Trader pemula yang butuh struktur entry, SL, TP, dan risiko.
- Trader aktif yang ingin monitoring cepat via Telegram.
- Operator Hermes/VPS yang ingin menjalankan bot dengan konfigurasi `.env`.

## Core Features

- Forex signal generator.
- Gold/XAUUSD quick signal.
- Free-text market query.
- Trading mode selector.
- Risk-based position sizing.
- Paper trade execution.
- Watchlist.
- Alert guide.
- Settings and safety status.

## User Flow

1. User membuka `/start`.
2. Bot menampilkan menu.
3. User memilih market atau mengetik pertanyaan bebas.
4. Bot mengambil candle data.
5. Strategy engine membuat signal.
6. Risk manager mengecek batas risiko.
7. Bot menampilkan signal card dan tombol action.
8. Jika user memilih trade, order masuk ke paper broker.

## Telegram Menu Flow

```text
/start
  Forex Signal
    EURUSD / GBPUSD / USDJPY / GBPJPY / AUDUSD
      Scalping / Intraday / Swing / Conservative / Aggressive
  Gold / XAUUSD
  Watchlist
  Price Alert
  Settings
  Help
```

## Market Selection Flow

Pair dideteksi dari tombol atau free text. Alias seperti `XAUSD` dinormalisasi ke `XAUUSD`.

## AI Signal Flow

Saat ini AI layer dibuat sebagai deterministic strategy engine agar dapat dites. Integrasi LLM bisa ditambahkan sebagai `aiReview` setelah data market dan signal numerik selesai, bukan sebagai satu-satunya pembuat keputusan.

## Realtime Price Flow

Provider default `demo` menghasilkan candle stabil untuk development. Provider `twelvedata` dipakai jika `TWELVEDATA_API_KEY` diisi. Jika API gagal, bot fallback ke demo dan menampilkan warning.

## Technical Analysis Flow

Strategy engine mengevaluasi:

- EMA 20, 50, 200.
- RSI.
- MACD.
- ATR.
- Support and resistance.
- Candle range and volatility.
- Market structure sederhana.
- Risk reward ratio.

## Multi Timeframe Analysis Flow

- Scalping: M1, M5, M15.
- Intraday: M15, H1, H4.
- Swing: H4, D1, W1.
- Conservative: H1, H4, D1.
- Aggressive: M5, M15, H1.

## Risk Management Flow

Risk manager mengecek:

- Signal bukan `WAIT`.
- Confidence melewati threshold mode.
- Stop loss valid.
- Risk per trade.
- Max daily loss.
- Max open trades.
- Position size.

## Alert Flow

MVP menyediakan menu dan instruksi. Versi berikutnya perlu scheduler/queue untuk mengecek harga berkala.

## Watchlist Flow

Watchlist disimpan di JSON store per chat ID. Bisa dipindah ke PostgreSQL setelah bot masuk multi-user production.

## Database Design

MVP memakai file JSON:

- `pending-orders.json`: order preview yang menunggu konfirmasi.
- `paper-trades.json`: jurnal paper trade.
- `watchlists.json`: watchlist per chat.

Production upgrade:

- `users`
- `watchlists`
- `signals`
- `orders`
- `positions`
- `alerts`
- `audit_logs`

## API Integration Design

- Market data: Twelve Data atau provider lain.
- Broker: adapter baru per broker, misalnya OANDA, MT5 bridge, atau cTrader.
- Telegram: Telegraf polling.

## System Architecture

```text
Telegram User
  -> Telegraf Bot
  -> TradingService
  -> MarketDataService
  -> ForexStrategy
  -> RiskManager
  -> BrokerAdapter
  -> JsonStore
```

## Queue Architecture

MVP tidak memakai queue. Untuk production alert dan auto-trading multi-pair, gunakan Redis + BullMQ:

- `price-scan`
- `signal-generate`
- `order-execute`
- `risk-audit`
- `telegram-notify`

## Telegram UI Example

```text
Treding Forex Ai

Market: XAUUSD
Mode: Intraday
Action: WAIT
Confidence: 58%

Reason:
- EMA belum selaras.
- RSI netral.
- RR belum cukup.

Action:
[Refresh Signal] [Add Watchlist]
```

## Signal Card Example

```text
Market: EURUSD
Current Price: 1.08420
Trend: Bullish
Signal: BUY
Confidence: 72%
Entry Area: 1.08420
Stop Loss: 1.08190
Take Profit 1: 1.08765
Take Profit 2: 1.08880
Risk Level: Medium
Risk Reward: 1:2.0
Invalidation: Signal batal jika harga close di bawah stop loss atau EMA 20 turun di bawah EMA 50.
```

## Security and Risk Disclaimer

- Tidak ada profit guarantee.
- Real trading nonaktif secara default.
- Secret hanya melalui `.env`.
- Broker adapter real harus diaudit sebelum `ENABLE_REAL_TRADING=true`.
- Semua error message dibuat aman dan tidak membocorkan token.

## Development Roadmap

1. MVP Telegram + paper trading.
2. Integrasi market data realtime.
3. Alert scheduler.
4. PostgreSQL persistence.
5. AI review layer.
6. Broker adapter sandbox.
7. Broker adapter live dengan kill switch.
8. Dashboard web untuk audit dan monitoring.
