Overview

GoldVeldspar is a market-intelligence service for EVE Online traders. It collects public market order snapshots from CCP’s official ESI API, stores time-series price data, evaluates user-defined watch rules, and delivers alerts through Telegram and a web app.

The platform targets traders who care about hub spreads, price drops, volume spikes, and arbitrage signals — without running their own scripts or manual spreadsheet monitoring.

Users can search a catalog of roughly 19k marketable item types, create watches with multiple rule types, receive Telegram DMs when rules fire, request on-demand spread advice, and browse alerts, charts, and catalog data in a signed-in web UI.

The system is designed as a game-agnostic core with EVE as the first vertical — new games can be added via adapter modules without schema rewrites.

Context

EVE station traders and industrialists already pay for market tools, but many workflows still depend on manual hub checks or heavy third-party sites. The product goal was a lightweight, Telegram-first companion at a realistic price point (€5/month Pro tier) that catches opportunities faster than manual monitoring.

Key requirements included:

• official API only — EVE ESI, no scraping or ToS risk;
• polite data collection — bounded ESI budget, ~10-minute cadence, rate-limit awareness;
• multi-hub coverage — Jita, Amarr, Dodixie, Rens, Hek;
• honest coverage model — full catalog search with tiered snapshot refresh (hot → watched → background);
• small-team operations — one VPS, staging + production, CI/CD, observability, runbooks;
• multilingual UX — EN / UA / RU in bot and web.

Responsibilities

Responsibilities across the project included:

• end-to-end product architecture and monorepo structure;
• FastAPI REST API, auth, tier gating, watches, and advice endpoints;
• Celery workers and beat: ESI snapshots, alert evaluation, maintenance tasks;
• Telegram bot (aiogram 3): commands, i18n, webhook delivery;
• Next.js apps: marketing site, user web app, admin dashboard;
• PostgreSQL + TimescaleDB schema, Alembic migrations, SDE catalog import;
• tiered snapshot strategy (hot / watched / catalog LRU);
• Hetzner deployment, Docker Compose, Caddy TLS, GitLab CI/CD;
• Prometheus alerts, Grafana dashboards, Loki logging, emergency shutdown runbook.

Solution

GoldVeldspar runs as a monorepo with shared Python packages and separate deployable apps (api, workers, bot, web, admin, marketing).

Data flow:

• Celery beat triggers tiered ESI snapshot runs every ~10 minutes;
• workers aggregate best ask/bid per item × hub and write to TimescaleDB;
• a separate alert evaluator (every minute, DB-only) checks active watches;
• fired alerts are dispatched to Telegram; history is visible in the web app;
• Pro users can call /advice or use the web Advice panel for spread hints from latest snapshots.

User tiers (current model): Free — 5 active watches, 15-minute alert refresh; Pro (€5/mo) — 100 watches, 1-minute refresh, full spread advice modes.

Primary channels: Telegram bot, signed-in web app (search, watches, alerts, advice, catalog), and an admin dashboard for operators.

Technical Details

Stack

• Python 3.12, FastAPI, SQLAlchemy (async), Pydantic, Celery, Redis
• aiogram 3, Fluent i18n (EN / UA / RU)
• PostgreSQL 16 + TimescaleDB hypertables, Alembic
• Next.js (marketing, web, admin), Tailwind CSS
• Docker Compose, Caddy, GitLab CI/CD, Hetzner VPS
• Prometheus, Grafana, Loki, Alertmanager → Telegram

Architecture

• adapter pattern — SourceAdapter contract; EVE implementation wraps ESI with error-limit handling;
• snapshot tiers — hot items (all hubs, every tick) → watched items (hub set from rules) → catalog LRU (Jita-first, budget-capped);
• rule engine — JSONB watch rules; six rule types in Phase 1;
• multi-environment — isolated Compose projects for staging and production on one VPS;
• auth — email link codes via bot /link; shared cookie domain across marketing and web.

Functionality

Implemented functionality includes:

• EVE trade hub snapshots (five regions × tiered item sets);
• SDE catalog import (~19k searchable types);
• watch CRUD with tier quotas;
• alert types: price below, drop %, new low, volume spike, availability, arbitrage;
• spread advice: per-item, best-now, buy-at-hub scan;
• item price charts (snapshot-derived);
• admin: source health, freshness, users by tier, catalog browse;
• maintenance mode: Caddy 503 routes and documented service shutdown.

Challenges

Main challenges included:

• ESI volume vs coverage — full catalog × all hubs every 10 minutes is infeasible; solved with tiered refresh and honest UX on watch create;
• stale-but-useful data — advice and alerts use aggregated best bid/ask, not full order-book depth;
• multi-surface consistency — same tier limits and rules in API, bot, and web;
• operations on a budget — staging, production, and observability on one VPS with safe deploy and rollback;
• product honesty — marketing and tier copy aligned with what is actually monitored.

Result

The platform is live on staging and production, with automated staging deploys and manual production promotion.

Delivered:

• full pipeline: ESI → TimescaleDB → rules → Telegram DM;
• multi-hub arbitrage and spread advice on snapshotted items;
• searchable EVE catalog with hot-item monitoring and watched-item refresh;
• web, bot, and admin surfaces with i18n;
• CI/CD, metrics, alerts, and emergency shutdown procedures.

The architecture is positioned for Stripe billing and future games via new source adapters without rewriting the core schema.

Notes

• Official EVE ESI only; no character authentication in Phase 1.
• Advice is indicative (~10 min snapshot age, before fees and hauling).
• Billing (Stripe) planned; tier limits enforced in code today.
• EVE-first wedge; framework is game-agnostic by design.