# Architecture

## Current State

The project currently uses a static frontend:

- `index.html` for the premium landing page.
- `styles.css` for design tokens, responsive layout, UI components, landing motion and typography.
- `assets/hero-whale-premium.webp` for the optimized hero background, with PNG kept as fallback and social preview source.
- `assets/favicon/` for the user-provided Crypto Whale favicon and transparent logo pack.
- `assets/flags/` for circular SVG language flag icons used by the landing switchers.
- `assets/hero-tail-premium-glow-clean.png` for the controlled premium hero whale-tail glow overlay.
- `terminal/` for the first separate static dashboard route with shared terminal typography and motion in `terminal/terminal.css`.
- `terminal/arbitrage/` for the first platform workspace route.
- `terminal/bundles/btc-usdt-binance-bybit/` for the first bundle detail route.
- `terminal/listings/` for listings radar and exchange event cards.
- `terminal/announcements/` for normalized announcement feed and related bundle context.
- `terminal/futures/` for futures, basis spread and open interest module.
- `terminal/funding/` for funding rate opportunities and hedge direction warnings.
- `terminal/watchlist/` for saved assets and reusable platform presets.
- `terminal/alerts/` for alert rule and notification channel UX.
- `terminal/settings/` for profile, security and account readiness UX.
- `dashboard/` for the premium institutional command center shell with route-aware Overview, Scanner, Spot/Futures/Funding, Spreads, Listings, Exchange Status, Alerts, Watchlist and Settings views.
- `login/` and `register/` for static auth onboarding shells.
- `billing/` for subscription plan and usage guard UX.
- `admin/` for static admin overview, users, bundles and health pages.
- `en/`, `ru/`, `ua/`, `cs/`, `es/`, `it/`, `de/`, `pt/`, `vi/`, `fr/` for static language route shells.
- `src/i18n/` for language config, translations, URL handling, localStorage persistence and client-side geo fallback.
- `packages/mock-data/` for stable demo records and filtering helpers that model the future API contract.
- `packages/access-control/` for subscription feature gates, RBAC checks and usage guard states.
- `packages/notifications/` for deterministic alert payloads and mock Telegram, email and webhook delivery results.
- `packages/arbitrage-engine/` for core spread, fee, convergence, confidence and ranking calculations.
- `packages/risk-engine/` for risk scoring, labeling and explanation logic.
- `server/exchange-announcements.mjs` for the 39-source Fundoor-style exchange registry, official public exchange announcement adapters, event classification, asset extraction and source status reporting.
- `server/app-services-api.mjs` for lightweight production API routes such as `/api/market/funding` and `/api/market/events`.
- `tests/` for Node built-in test coverage of calculation engines.

## Target State

The technical specification recommends a monorepo:

```text
apps/
  web/
  api/
packages/
  ui/
  types/
  config/
  db/
  exchange-connectors/
  arbitrage-engine/
  risk-engine/
  event-engine/
  notifications/
  billing/
  utils/
docs/
```

## Proposed Migration

Phase 1.1 should migrate the static prototype into `apps/web` using Next.js, TypeScript and a reusable component system. The current static page should be treated as the visual baseline.

## Data Strategy

Start with realistic mock data for:

- Arbitrage bundles
- Spread history
- Listings
- Announcements
- Funding rates
- Exchange status
- Risk explanations
- Users, roles and subscription plans
- Watchlist entries and alert rules

The mock layer should be structured so real exchange connectors can replace it without rewriting the UI.

`/terminal/listings/` and `/terminal/announcements/` now hydrate from `/api/market/events` when live sources respond. Embedded cards remain as static fallback content for degraded exchange APIs or offline previews.

The first shared mock data module now lives in `packages/mock-data/`. Static HTML still embeds records directly for compatibility, while the package acts as the migration source for the future Next.js/API implementation.

Feature gating and RBAC are modeled in `packages/access-control/`. This keeps billing and admin authorization logic testable before a real auth provider is introduced.

Notification delivery is modeled in `packages/notifications/`. It does not send network requests; it validates targets, builds payloads and returns mock queued delivery states.

## I18n Strategy

The static build now supports a landing-page i18n runtime:

- URL language segments use `en`, `ru`, `ua`, `cs`, `es`, `it`, `de`, `pt`, `vi`, `fr`.
- Ukrainian uses internal code `ua` and HTML `lang="uk"`.
- Manual selection is saved in `crypto_whale_language`.
- Direct language URLs and stored selections have priority over geo.
- Client-side geo detection uses a short timeout and falls back to EN without GPS prompts.