# Milestone 1: Project Kickoff & Initial Plan

**Due:** 02.03.2026  
**Status:** Submitted

## What We're Building

A distributed stock provider that doesn't fall over when things go sideways. Think of it as a financial data middleman with trust issues—it assumes everything will fail, so it plans accordingly.

The core idea? Multiple backend instances serving real-time stock data through a load balancer. When one dies, the other picks up the slack. No downtime, no drama.

## The Architecture Play

We're going with a classic N-tier setup, fully containerized:

**Frontend** → React dashboard showing live tickers and which backend instance is currently doing the heavy lifting.

**Load Balancer** → Traefik sits at the gate, running health checks every few seconds. If an instance stops responding, traffic gets rerouted. Simple, effective.

**Backend Instances** → Two identical Node.js containers. They authenticate via JWT, fetch stock prices, and log heartbeats to prove they're alive.

**Database** → PostgreSQL handles user credentials and caches stock prices. This keeps data consistent across instances and prevents hammering external APIs.

**Authentication** → JWT-based. No token, no data. Every protected endpoint checks for `Authorization: Bearer <token>`.

## Why This Matters

Financial systems can't afford downtime. A crashed server means missed trades, angry users, and lost revenue. By running multiple instances behind a load balancer, we ensure the service stays up even when individual components fail.

The caching layer is equally critical—external APIs have rate limits and can be unreliable. By storing recent prices in PostgreSQL, we maintain service continuity even when Yahoo Finance decides to take a nap.

## Tech Stack Decisions

- **Node.js** for backend: Fast, async-friendly, perfect for I/O-heavy operations
- **React** for frontend: Component-based, easy to show real-time updates
- **Traefik** for load balancing: Built-in health checks, Docker-native, minimal config
- **PostgreSQL** for persistence: ACID compliance, reliable, handles concurrent connections well
- **Docker Compose** for orchestration: Single command deployment, reproducible environments
