# TrenchOnChain — Marketing Site

> TrenchOnChain is a Solana memecoin trading signals platform. This is the main marketing website (trenchonchain.fun) built with React + Vite + TailwindCSS v4.

## Project Overview

- **Domain**: https://trenchonchain.fun
- **Stack**: React 18, Vite 6, TailwindCSS 4, Radix UI, Lucide icons, Recharts, Motion (Framer Motion)
- **Language**: TypeScript
- **Purpose**: Landing page / marketing site for the TrenchOnChain trading bot
- **Backend**: `TOCBack/` — FastAPI backend (port 8000) for auth, payments (Solana), leaderboard API, terminal API
- **Deployment**: Static site (dist/) served via Nginx + API reverse-proxied to FastAPI

## Key Features

- **Multilingual**: French, English, Spanish, German, Portuguese — via `language-context.tsx` (URL path detection: `/fr`, `/en`, etc.)
- **Live Leaderboard**: Real-time token signals with performance data from `leaderboard_site.py` → `signal_tracking.db` (read-only)
- **Token Cards**: Carousel of top signals with OHLCV charts (GeckoTerminal free fallback, Birdeye primary)
- **Payment System**: Solana-based VIP subscription — unique wallet per payment, on-chain verification
- **Telegram Auth**: Login via Telegram OAuth Widget → JWT tokens → session
- **SEO**: sitemap.xml, robots.txt, hreflang (fr/en), JSON-LD, Open Graph, Twitter Cards, dynamic meta per language
- **PWA**: Install prompt, service worker, offline-ready shell
- **SSE Live Updates**: Server-Sent Events for real-time signal feed (`/api/sse/live`)

## Directory Structure

- `src/app/App.tsx` — Main application component (single-page layout)
- `src/app/components/` — All UI sections (hero, features, rankings, CTA, footer, navbar…)
- `src/app/components/ui/` — Shadcn/Radix primitive components (accordion, dialog, tabs…)
- `src/app/components/language-context.tsx` — i18n provider with URL path detection
- `src/app/components/auth-context.tsx` — Telegram auth + JWT session management
- `src/app/components/token-cards-section.tsx` — Live token signal cards with skeleton loading
- `src/app/components/rankings-section.tsx` — Leaderboard tables (24h/7d/30d/all-time)
- `src/app/components/payment-modal.tsx` — Solana VIP payment flow (QR code, status polling)
- `src/app/components/seo-head.tsx` — Dynamic SEO meta tags
- `TOCBack/` — Python FastAPI backend
- `TOCBack/leaderboard_site.py` — Main API server: signals, stats, charts, user data, SSE
- `TOCBack/payments.py` — Solana payment: create wallet, verify TX, admin sweep, VIP activation
- `TOCBack/auth.py` — Telegram OAuth + JWT issuance + VIP check
- `TOCBack/terminal_api.py` — Terminal-specific endpoints (pulse, live signals, admin toggle)
- `TOCBack/admin_notify.py` — Admin notification system
- `TOCBack/user_panel.py` — User panel API
- `public/` — Static assets (images, manifest)
- `static/` — Logo (toc.jpg), OG images

## API Endpoints (TOCBack — FastAPI on port 8000)

### Signals (leaderboard_site.py)
- `GET /api/signals/top25` — Top 25 all-time (sorted by multiplier desc)
- `GET /api/signals/top10-48h` — Top 10 last 48 hours
- `GET /api/signals/top10-24h` — Top 10 last 24 hours
- `GET /api/signals/recent-winners` — Top 10 recent winners (7d, ≥1.4x)
- `GET /api/signals/recent` — 25 most recent signals
- `GET /api/signals/progressions` — Recent multiplier progression events (last 10 min)
- `GET /api/signals/all?page=1&limit=25` — Paginated all signals
- `GET /api/signals/{address}` — Single token by contract address
- `GET /api/stats` — Global stats (total signals, win rate, avg multiplier)
- `GET /api/prices` — SOL/BTC/ETH prices (CoinGecko proxy, cached)
- `GET /api/chart/ohlcv?address=...&timeframe=1H` — OHLCV chart data (Birdeye → GeckoTerminal fallback)
- `GET /api/sse/live` — Server-Sent Events for real-time signal updates

### Auth (auth.py)
- `POST /api/auth/telegram` — Telegram OAuth login → JWT token
- `GET /api/auth/me` — Current user info from JWT
- `GET /api/auth/vip-check` — Lightweight VIP status check

### Payments (payments.py)
- `POST /api/payments/create` — Create payment (generates unique Solana wallet)
- `GET /api/payments/status/{id}` — Check payment status (polls Solana RPC)
- `POST /api/payments/cancel/{id}` — Cancel pending payment
- `GET /api/payments/config` — Public payment plans & prices

### Terminal (terminal_api.py)
- `GET /api/terminal/status` — Terminal enabled/disabled
- `GET /api/terminal/pulse?hours=48` — Pulse feed (signals with cooldown)
- `GET /api/terminal/signals/live` — All active signals (Insider only)
- `GET /api/terminal/signals/{ca}` — Single token detail

### User (leaderboard_site.py)
- `GET /api/user/profile` — Full user profile (VIP status, stats)
- `GET /api/user/wallets` — User's wallets from bot DB
- `GET /api/user/settings` — User settings
- `GET /api/user/copytrade` — Copy trade configurations
- `POST /api/user/settings` — Save settings
- `POST /api/user/copytrade` — Save copy trade config

### Legacy
- `GET /leaderboard` — Backward-compatible legacy endpoint
- `GET /health` — Health check

## SEO Files

- `robots.txt` — Crawl policy (allows /, blocks /admin/, /api/private/)
- `sitemap.xml` — URL entries with hreflang (/, /en, /fr) + image tags
- `llms.txt` — This file (LLM context for AI assistants)

## Build & Run

```bash
# Frontend
npm install && npm run build     # outputs to dist/

# Backend API
cd TOCBack
pip install -r requirements.txt
uvicorn leaderboard_site:app --host 0.0.0.0 --port 8000
```

## Related Projects

- **Bot**: Python Telegram/Discord trading bot (parent directory)
- **Terminal**: Trading terminal web app (`../Terminal/`)
- **Rust Engine**: Native Solana trading execution engine (`../RUST/`)
- **Shared DB**: `signal_tracking.db` (read by site), `trench_bot.db` (read/write by bot + Rust engine)