Table of Contents
01 · Project Overview
GannAstro is a proprietary trading intelligence dashboard built to identify crypto assets whose price geometry aligns with active planetary aspects. The core hypothesis is that W.D. Gann's observation — that price moves in geometric proportion to time — can be operationalised by mapping a token's price logarithm to a 360° circle and detecting when major planets form Square (90°) or Trine (120°) aspects to that angle.
The system operates across three scanner generations: V1 (basic aspect detection), V2 (full multi-planet scanner with momentum tools), and V3 (persistent universal token database with Gann degree indexing). All three are live simultaneously.
02 · Technology Stack
03 · System Architecture
The application is a monorepo with a unified Vite SSR build. The Express server handles both API routes and server-side rendering in a single process. All persistent state lives in either MySQL (catalog data) or JSON files under /private (alerts, journal, settings).
- src/server/entry.ts — Express server: registers all API handlers + SSR render
- src/server/api/ — Handler files (GET/POST per route, registered in entry.ts)
- src/server/services/ — Business logic: fetchers, resolvers, stores
- src/lib/ — Pure computation: Gann engine, planetary engine, Circle of 8
- src/pages/ — React route components (SSR-rendered)
- src/components/ — Shared UI components
04 · Gann Price Engine
The Gann engine maps any token price to a 360° geometric circle using the formula: priceDegree = (log₁₀(price) % 1) × 360. This is the fractional part of the base-10 logarithm scaled to a full circle — the core of Gann's "Square of Nine" price geometry.
Gann Circle of 8 — An advanced extension using 8 multiplicative factors [1, 1.125, 1.25, 1.5, 2, 0.875, 0.75, 0.6667] applied to the base price. Each factor maps to a 45° sector. The engine detects which sector the current price occupies and computes runway to the next level.
- src/lib/gann-engine.ts — Core Gann degree, level ladder, aspect scoring, fmtDeg
- src/lib/gann-engine-v2.ts — V2 with VSOP87 planets, extended aspects, scanAspectWindowsV2
- src/lib/gann-circle-of-8.ts — Circle of 8 with configurable factors and sector detection
05 · Planetary Ephemeris Engine
Planetary positions are computed in real-time using VSOP87 theory combined with Keplerian orbital mechanics from Jean Meeus's Astronomical Algorithms 2nd Ed. No external ephemeris API is called — all computation is pure TypeScript running server-side.
Aspect Detection Logic: For each planet, the angular distance to the token's Gann angle is computed. If this distance is within the configured orb (default 1.0°) of a major aspect angle, an aspect is flagged. Applying aspects (planet moving toward exact) are weighted higher in signal scoring.
06 · V3 Universal Token Database
The V3 catalog is a MySQL-backed persistent token database that ingests listings from every major CEX and DEX source. Unlike V1/V2 which operated on ephemeral in-memory lists, V3 preserves listing-level identity across runs.
- CoinMarketCap — top 500+ CEX listings with dateAdded, price, market cap
- Binance — full spot pair list with base/quote resolution
- DexScreener — DEX pairs across Ethereum, BSC, Solana, Polygon, Arbitrum, Base
- PumpSwap, PancakeSwap, Uniswap — DEX-native pair discovery
- KuCoin, Bybit, Bitget, Gate.io, MEXC, OKX — 10 CEX public feeds
07 · Gann Breach Detection System
The Gann Breach system scans token prices against their computed Gann level ladders and flags tokens where the current price is within the configured orb of a Gann level. Three independent breach modes operate with separate stores and APIs.
CEX Long-Running Scan: The CEX scan covers 500+ pairs and exceeds the 10-second preview proxy timeout. A dedicated /api/cex-breach/long endpoint handles this. The UI fires the POST and polls GET to confirm results.
08 · Momentum & Signal Detection Tools
09 · Signal Journal & Outcome Tracking
The Signal Journal is a persistent evidence-and-outcome ledger. Every signal generated by the system is logged with its entry conditions. Outcome checkpoints at 15m, 1h, 4h, 24h, and 7d record price excursion and whether the target level was hit.
10 · API Endpoints Reference
11 · Exchange & Data Integrations
12 · Settings & Configuration
All system parameters are configurable at runtime via the Settings page and persisted to /private/gannastro-settings.json.
- API Keys tab — CMC_API_KEY, ETHERSCAN_API_KEY, TELEGRAM_BOT_TOKEN, TELEGRAM_CHAT_ID
- Gann Parameters tab — Circle of 8 factors, angle mode (log10 vs rank), orb tolerance
- Scanner Config tab — scan cadence (setInterval ms), alert thresholds, deduplication window
- Data Sources tab — enable/disable individual exchange feeds, chain selection
- Planets & Aspects tab — planet selection, aspect types, applying-only filter
13 · Trading Strategy Logic
The core trading hypothesis has three layers that must align for a high-conviction signal:
Signal Scoring: Each aspect is scored by type (Square = reversal, Trine = continuation), orb (tighter = higher score), and applying/separating status. Compound signals (breach + aspect + momentum) are the highest-priority alerts.
Mint Date Accuracy: The Gann angle is only as accurate as the mint date. Priority chain: hardcoded known dates → CMC dateAdded → DexScreener pair creation → Etherscan contract creation → RPC fallback.