Personal project2026MIT

Stock Alerts: architecture

Self-hosted price alerts for a small group of users. It started as a Python script with alarms in a CSV; I turned it into a three-service application.

  • NestJS
  • TypeScript
  • Prisma
  • PostgreSQL
  • Python
  • pandas
  • React
  • Docker
Code on GitHub

Context

I wanted technical-analysis strategies (moving averages, RSI, MACD, Bollinger Bands, support and resistance), a web interface and accounts for a small group of people. Everything had to run for free on a home Mini PC with 8 GB of RAM.

How it fits together

The backend and the worker never call each other: the database is the only integration point.
Diagram: the frontend calls the backend over REST; the backend and the worker read and write PostgreSQL and never call each other; the worker fetches prices from yfinance and sends email and Telegram notifications when an alarm triggers.FrontendReact SPA · NetlifyBackendNestJS · REST · JWTPostgreSQLonly integration pointWorkerPython · hourly cronNotificationsEmail · TelegramPricesyfinance via PriceProvideron triggerprices

Every hour, the worker loads active alarms grouped by symbol, fetches each price once, evaluates each alarm with its strategy and records the triggers. The backend owns the CRUD and validates each alarm's parameters against its strategy's schema.

Decisions

Two languages, each where it fits

The strategy engine is a numerical problem, and Python's pandas ecosystem is far more mature than the Node alternatives. NestJS with Clean Architecture handles the API, authentication and business rules.

The database as the only integration point

No RPC or queues between services. Fewer processes on a low-memory server, and each service is deployed and tested on its own.

Price provider behind a port

Finnhub's free tier stopped providing daily historical data, so I now use yfinance. Both adapters implement the same port: switching providers doesn't touch the strategy engine.

Strategies as templates

Each alarm is an instance of a strategy, with its own ticker, market and parameters. Adding a strategy means registering it, without touching existing ones.

Independent notifications

Email and Telegram both send on every trigger, and either can fail without affecting the other. A per-alarm notification status prevents duplicate sends.

Zero-cost deployment

The static frontend runs on Netlify; the backend, worker and Postgres run on the Mini PC, exposed through Tailscale Funnel: no domain, no port forwarding, and it works behind CGNAT. In production the worker runs from crontab to save memory.

Tests against a real database

Unit tests in both services and integration tests against a real Postgres 16 in Docker, ephemeral (tmpfs). The worker applies the same Prisma migrations as the backend.