# TrenchOnChain — Trading Terminal

> Web-based trading terminal for the TrenchOnChain Solana memecoin signals platform. Built with React + Vite + TailwindCSS v4. Currently in active development (maintenance page shown to users).
> For the full detailed documentation, see: https://terminal.trenchonchain.fun/llms-full.txt

## Project Overview

- **Stack**: React 18, Vite 6, TailwindCSS 4, Radix UI, Lucide icons, Recharts, React Router 7
- **Language**: TypeScript
- **Purpose**: Full-featured trading terminal (signals dashboard, copy trading, portfolio, leaderboard)
- **Backend**: Shares the same FastAPI backend as the marketing site (`../New TOC/TOCBack/`)
- **State**: In development — maintenance gate checks `/api/terminal/status` before rendering

## Key Features

- **Live Signal Feed (Pulse)**: Real-time token signals with star ratings, multipliers, OHLCV charts
- **Copy Trading**: Add tracked wallets, configure buy/sell mirroring, performance stats
- **Portfolio**: Open positions, P&L tracking, trade history
- **Leaderboard**: Top performers by timeframe (24h, 7d, 30d, all-time)
- **Trading Panel**: Floating buy/sell panel with slippage, priority fees
- **Token Detail Modal**: Full token analysis with chart, holders, DEX info
- **Telegram Auth**: Login via Telegram OAuth for Insider-only features
- **i18n**: French and English (`src/app/i18n/`)
- **Themes**: Dark/light mode via `ThemeContext.tsx`
- **Admin Panel**: Protected admin routes for terminal configuration
- **Skeleton Loading**: Proper skeleton screens on API failure (no mock fallback in production)

## Directory Structure

### Pages & Routes
- `src/app/App.tsx` — Router setup (React Router 7)
- `src/app/components/Layout.tsx` — Main layout with header, sidebar, maintenance gate
- `src/app/components/PulsePage.tsx` — Live signal feed (main page)
- `src/app/components/TerminalPage.tsx` — Trading terminal view
- `src/app/components/CopyTradePage.tsx` — Copy trading configuration
- `src/app/components/PortfolioPage.tsx` — User portfolio & positions
- `src/app/components/LeaderboardPage.tsx` — Signal leaderboard
- `src/app/components/HistoryPage.tsx` — Trade history
- `src/app/components/InsiderPage.tsx` — VIP subscription page
- `src/app/components/AdminPage.tsx` — Admin dashboard
- `src/app/components/CoursesPage.tsx` — Educational content
- `src/app/components/PrivacyPage.tsx` — Privacy policy

### Components
- `src/app/components/TokenCard.tsx` — Signal card (star rating, multiplier, age warning)
- `src/app/components/TokenDetailModal.tsx` — Token analysis modal
- `src/app/components/FloatingTradePanel.tsx` — Buy/sell panel overlay
- `src/app/components/FloatingPnlWidget.tsx` — P&L widget (real data in live mode)
- `src/app/components/TradingChart.tsx` — OHLCV candlestick chart
- `src/app/components/Header.tsx` — Top navigation bar
- `src/app/components/MiniTrackerPopup.tsx` — Wallet tracker mini popup
- `src/app/components/MiniCopyTradePopup.tsx` — Copy trade mini popup
- `src/app/components/CopyTradePanel.tsx` — Full copy trade panel
- `src/app/components/PnlCard.tsx` — Individual P&L card
- `src/app/components/MultiplierColors.tsx` — Multiplier color coding
- `src/app/components/SkeletonLoaders.tsx` — Skeleton loading components

### Context Providers
- `src/app/components/TelegramAuthContext.tsx` — Auth provider (JWT session)
- `src/app/components/InsiderContext.tsx` — VIP/Insider status provider
- `src/app/components/DisplaySettingsContext.tsx` — Display preferences
- `src/app/components/ThemeContext.tsx` — Dark/light theme

### Services & Data
- `src/app/services/data-service.ts` — API client (`apiFetch()` with mock fallback in dev only)
- `src/app/hooks/` — Custom React hooks
- `src/app/i18n/` — Translation files (fr, en)
- `src/app/utils/` — Utility functions
- `src/app/data/` — Mock data for development only
- `src/app/components/ui/` — Shadcn/Radix primitives (accordion, dialog, tabs…)

## API Dependencies

The terminal consumes the same FastAPI backend as the marketing site (`../New TOC/TOCBack/`):

### Terminal-Specific
- `GET /api/terminal/status` — Terminal enabled/disabled (checked on every load)
- `GET /api/terminal/pulse?hours=48` — Pulse feed with signal cooldown
- `GET /api/terminal/signals/live` — All active signals (Insider only)
- `GET /api/terminal/signals/{ca}` — Single token detail
- `POST /api/terminal/admin/toggle` — Admin: enable/disable terminal

### Shared with Marketing Site
- `GET /api/signals/top25` — Top 25 all-time signals
- `GET /api/signals/top10-48h` — Top 10 last 48h
- `GET /api/signals/{address}` — Token detail
- `GET /api/chart/ohlcv?address=...` — OHLCV chart data
- `GET /api/stats` — Global stats
- `GET /api/prices` — SOL/BTC/ETH prices
- `GET /api/sse/live` — Server-Sent Events real-time feed
- `POST /api/auth/telegram` — Authentication
- `GET /api/auth/me` — Current user info
- `GET /api/auth/vip-check` — VIP status
- `GET /api/user/profile` — User profile
- `GET /api/user/wallets` — User wallets
- `GET /api/user/copytrade` — Copy trade configs

## Build & Run

```bash
# Install deps
npm install

# Dev server (uses mock data if no API_BASE_URL)
npm run dev

# Production build (outputs to dist/)
npm run build
```

## Related Projects

- **Marketing Site**: Landing page (`../New TOC/`)
- **Bot**: Python Telegram/Discord trading bot (parent directory)
- **Rust Engine**: Native Solana trading execution engine (`../RUST/`)
- **Shared DB**: `signal_tracking.db` (read by site/terminal), `trench_bot.db` (read/write by bot + Rust)