# BTC Scalp Pulse Мобилен React индикатор за BTCUSDT скалпинг на 1m, 3m и 5m графики с Binance данни, EMA/RSI/VWAP сигнал и риск план. ## Masterplan - Помага на краткосрочни crypto трейдъри да оценят моментния BTCUSDT импулс без пълна trading платформа. - Фокус върху бързи 1, 3 и 5 минутни решения: `BUY`, `SELL` или `WAIT`. - Комбинира EMA 9/21/50, VWAP, RSI 14, ATR, momentum и volume ratio в score от 0 до 100. - Mobile-first dashboard с автоматично обновяване на 30 секунди, ръчен refresh и fallback при Binance API проблем. - Образователен инструмент: показва и причина за сигнала, risk plan, timeframe правила и къде е кодът. ## Tech Stack & Architecture - **Runtime:** статично browser приложение без build step, package manager или bundler. - **React:** `react@19.2.0` и `react-dom@19.2.0/client` през `https://esm.sh`. - **Templating:** `htm@3.1.1` в `src/jsx.js`; всички компоненти използват `html\`...\`` tagged templates. Не използвай JSX syntax, защото няма transpilation. - **Styling:** Tailwind CDN в `index.html` + custom design tokens/classes в `styles/main.css`. - **Data source:** Binance public REST `GET /api/v3/klines` за `BTCUSDT`, `limit=120`. - **State management:** React local state в `src/App.js`; theme state в `src/mainProviders.js`. - **Theme:** `Providers` пази `btc-scalp-dark` в `localStorage` и toggle-ва `.dark` върху `document.documentElement`. - **Architecture flow:** - `index.html` зарежда Tailwind CDN, `styles/main.css` и `src/main.js`. - `src/main.js` mount-ва `` в `#root`. - `src/mainProviders.js` inject-ва `dark` и `setDark` в child чрез `React.cloneElement`. - `src/App.js` управлява timeframe, candles, analysis, loading/error state и polling. - `src/lib/market.js` съдържа API fetch, fallback candles, indicator calculations и format helpers. - UI е split-нат в малки presentational компоненти под `src/components/`. ## File Structure ```txt index.html # BG HTML shell; Tailwind CDN; styles/main.css; mounts src/main.js styles/main.css # CSS variables, dark theme, orb backgrounds, signal glow, skeleton animation src/main.js # React root creation; renders Providers + App via htm src/mainProviders.js # Dark mode state; localStorage persistence; .dark class toggle src/jsx.js # htm binding: exports html tagged template, replacement for JSX src/App.js # Main dashboard state, 30s polling, Binance/fallback loading, layout src/lib/market.js # Binance klines fetch, fallback data, EMA/RSI/ATR/VWAP analysis, money/number formatters src/components/Header.js # App title, last update, manual refresh button, dark/light toggle src/components/TimeframeTabs.js # 1m/3m/5m selector with scalp hints src/components/SignalCard.js # Price, BUY/SELL/WAIT badge, score bar, reason text src/components/MetricsGrid.js # EMA/VWAP/RSI/ATR/volume ratio metric cards src/components/MiniChart.js # SVG line/area chart for last 52 closes, colored by signal src/components/RiskPanel.js # Direction, stop, target, R:R calculation src/components/StrategyPanel.js # Static Bulgarian rules per selected timeframe src/components/SourceCodePanel.js # Lists project files and copies a small logic snippet src/components/Skeleton.js # Loading placeholder; compact mode for sidebar src/components/EmptyState.js # Retry state if no analysis is available CLAUDE.md # Project documentation for future AI coding agents ``` ## Key Features ### Timeframe switching `src/App.js` defines supported timeframes: ```js [ { id: '1m', label: '1 мин', scalp: 'Много бърз вход' }, { id: '3m', label: '3 мин', scalp: 'Баланс шум/тренд' }, { id: '5m', label: '5 мин', scalp: 'По-чист импулс' } ] ``` `TimeframeTabs` calls `setTimeframe(item.id)`. The `useEffect` in `App` reloads data immediately and restarts the 30 second polling interval when `timeframe` changes. ### Market data loading `fetchCandles(timeframe)` in `src/lib/market.js` maps allowed timeframes through: ```js const BINANCE_INTERVALS = { '1m': '1m', '3m': '3m', '5m': '5m' }; ``` API request: ```txt GET https://api.binance.com/api/v3/klines?symbol=BTCUSDT&interval={1m|3m|5m}&limit=120 ``` Binance kline rows are normalized to: ```js { time: Number(row[0]), open: Number(row[1]), high: Number(row[2]), low: Number(row[3]), close: Number(row[4]), volume: Number(row[5]) } ``` Rows without finite `close` are filtered out. ### Fallback market scenario If Binance fails or returns empty data, `App.loadData()` uses `fallbackCandles(tf)` from `src/lib/market.js`. - On thrown fetch error, `error` is set to a Bulgarian warning message. - On empty fetch result, fallback is used silently. - Fallback produces 120 synthetic candles around base price `67500`, with wave/pulse/drift and timeframe-adjusted timestamps. ### Signal model `analyzeCandles(candles, timeframe)` returns: ```js { timeframe, price, change, signal, // BUY | SELL | WAIT direction, // LONG скалп | SHORT скалп | Изчакване score, // 0..100 ema9, ema21, ema50, rsi, atr, vwap, volumeRatio, momentum, stop, target, trend, // Възходящ | Низходящ | Страничен reason } ``` Scoring logic: - Starts at `50`. - `trendUp`: `ema9 > ema21 > ema50` and price above VWAP: `+22`. - `trendDown`: `ema9 < ema21 < ema50` and price below VWAP: `-22`. - RSI impulse: - `54 < RSI < 72`: `+12`. - `28 < RSI < 46`: `-12`. - Momentum over last 8 candles: - `> 0.08%`: `+8`. - `< -0.08%`: `-8`. - Volume confirmation if `volumeRatio > 1.15`: - with `trendUp`: `+6`. - with `trendDown`: `-6`. - Final score is rounded and clamped to `0..100`. Signal thresholds: - `BUY` when `score >= 67` - `SELL` when `score <= 33` - otherwise `WAIT` Risk levels: - BUY stop: `price - ATR * 1.15` - BUY target: `price + ATR * 1.85` - SELL stop: `price + ATR * 1.15` - SELL target: `price - ATR * 1.85` - WAIT stop/target: current price `RiskPanel.js` calculates R:R locally from `analysis.price`, `analysis.stop`, and `analysis.target`. ### Visual dashboard Primary dashboard includes: - `Header`: refresh, timestamp, dark/light toggle. - `SignalCard`: current BTCUSDT price, last candle change, signal badge, score progress bar, reason. - `MiniChart`: last 52 close prices as SVG area/line chart. - `MetricsGrid`: EMA 9, EMA 21, VWAP, RSI 14, ATR, volume ratio. - `RiskPanel`: direction, stop, target, risk/reward. - `StrategyPanel`: static trading rules for 1m, 3m, or 5m. - `SourceCodePanel`: educational “where code lives” card with clipboard copy. ## Design Guidelines - Language/UI copy is Bulgarian. - Layout is mobile-first: - Single column on small screens. - Two-column layout from `lg`: main content `1.15fr`, sidebar `0.85fr`. - Visual style: - Glassmorphism cards using `bg-[hsl(var(--card)/...)]`, borders, blur, and custom shadows. - Rounded cards via CSS tokens: `--radius-md`, `--radius-lg`. - Animated background orbs `.orb-one` and `.orb-two`. - Color system lives in `styles/main.css` as HSL CSS variables: - Primary orange: `--primary`. - Buy green: `--chart-buy: #22c55e`. - Sell rose: `--chart-sell: #fb7185`. - Wait amber: `--chart-wait: #f59e0b`. - Dark mode is default unless `localStorage.btc-scalp-dark === 'false'`. - Typography uses system sans stack with `Inter` first if available; no webfont is loaded. - Motion: - Skeleton shimmer and floating orbs are defined in CSS. - `prefers-reduced-motion: reduce` disables long animations/transitions. ## App Flow 1. User opens `index.html`. 2. `src/main.js` renders app. 3. `Providers` applies saved dark mode. 4. `App` defaults to `timeframe = '1m'`. 5. `loadData('1m')`: - sets loading, - fetches Binance candles, - falls back to synthetic candles if needed, - runs `analyzeCandles`, - updates `lastUpdate`. 6. Dashboard renders signal, chart, metrics, risk, and rules. 7. Every 30 seconds, current timeframe reloads. 8. User can: - switch to `1m`, `3m`, `5m`, - manually refresh, - toggle dark/light theme, - copy the explanatory code snippet from `SourceCodePanel`. Edge cases: - Binance API unavailable: use `fallbackCandles`, show error banner. - Binance returns empty array: use fallback without banner. - No analysis and not loading: show `EmptyState` retry. - Loading with no previous analysis: show `Skeleton`. - Loading with existing analysis: old analysis remains visible while refresh runs. - `MiniChart` assumes candles exist when rendered; `App` only renders it if `candles?.length`. ## Conventions - Use ES modules only. - Import React exactly from CDN unless intentionally updating all React CDN references: - `https://esm.sh/react@19.2.0` - `https://esm.sh/react-dom@19.2.0/client?deps=react@19.2.0` - Do not add JSX files or JSX syntax. Use: ```js import { html } from '../jsx.js'; export function ComponentName({ prop }) { return html`

${prop}

`; } ``` - Component files use PascalCase names and named exports: `Header`, `SignalCard`, `RiskPanel`. - Keep data/calculation logic in `src/lib/market.js`; keep components mostly presentational. - Reuse `money()` and `number()` from `src/lib/market.js` for display formatting. - Styling approach: - Tailwind utility classes in components for layout and spacing. - CSS variables/custom animations in `styles/main.css`. - Prefer existing tokens like `hsl(var(--card))`, `hsl(var(--primary))`, `--radius-lg`. - To add a new timeframe: 1. Add item to `TIMEFRAMES` in `src/App.js`. 2. Add matching interval to `BINANCE_INTERVALS` in `src/lib/market.js`. 3. Update `fallbackCandles()` minute mapping if needed. 4. Add timeframe-specific rules in `StrategyPanel.js`. - To add a new metric: 1. Calculate it in `analyzeCandles()`. 2. Return it in the analysis object. 3. Display it in `MetricsGrid.js` or a new component. - Do not present this as financial advice; preserve the footer disclaimer in `src/App.js`. ## Platform (GenMB) This app is built and hosted on GenMB. **Runtime:** Browser sandbox (iframe) or Cloud Run. No Node.js server — all code runs client-side unless `backend/` exists. **Dependencies:** CDN-only (esm.sh, cdn.tailwindcss.com, unpkg). Use ES module imports with full CDN URLs. No `npm install` at runtime. **Entry point:** `index.html` must include all CDN script tags. Tailwind via CDN with inline config. **Built-in services (relative API paths only, never hardcode domains):** - `/api/ai/completion` — AI proxy | `/api/data/{appId}/*` — PostgreSQL (DataConnect SDK) - `/api/storage/{appId}/*` — File uploads (GCS) | `/api/auth/google/*` — Google OAuth - `/api/contact/submit` — Contact form | SDKs: `window.genmb.db`, `.storage`, `.auth` **File structure:** `index.html` (entry), `src/` (source), `styles/` (CSS), `backend/` (optional FastAPI), `CLAUDE.md` (this file). **Cannot:** Install npm packages at runtime, access filesystem, make direct server-side calls from frontend, modify infra.