StocKings 👑

Fork of a project for the Python for Big Data course. Built with @touikss and @syrdahar.

Stock market visualization dashboard built with Python / Dash / Plotly and TimescaleDB.
Market data (Boursorama + Euronext) is automatically imported at startup and stored in a time-series database.

---

Features

Tab	Description
Prices	Display one or more stock prices as a line chart or candlestick chart, with optional logarithmic scale. Period selection via shortcuts (1d, 5d, 1m, 6m, YTD, 1y, 5y, Max) or a date picker. Each stock has its own color; the legend allows toggling individual curves.
Bollinger Bands	Display Bollinger Bands (moving average + standard deviations) for a selected stock.
Raw Data	Daily statistics table for selected stocks: min, max, open, close, mean, standard deviation — one row per day.
Portfolio	Original feature: build a fictional portfolio (stock + quantity held). The chart displays the total portfolio value over time (∑ quantity × closing price). Peak (date + amount) and trough (date + amount) stats are automatically computed for the selected period.
Companies	Directory of indexed companies with search by name, symbol, ISIN, or Boursorama code.

---

Downloading the Data

Data is available at:

https://www.lrde.epita.fr/~ricou/pybd/projet/

Download the two archives:

wget https://www.lrde.epita.fr/~ricou/pybd/projet/bourso.tgz
wget https://www.lrde.epita.fr/~ricou/pybd/projet/euronext.tgz

Extract them into the data/ folder at the project root:

tar -xzf bourso.tgz   -C data/
tar -xzf euronext.tgz -C data/

Expected data/ structure

data/
├── boursorama/
│   ├── 2019/
│   │   ├── compA 2019-01-01 09:05:02.607291.bz2
│   │   ├── compB 2019-01-01 09:05:02.607291.bz2
│   │   └── ...
│   ├── 2020/
│   │   └── ...
│   └── ...
└── euronext/
    ├── 2020/
    │   ├── 2020-05-03.xlsx
    │   └── ...
    ├── 2021/
    │   └── ...
    └── ...

Boursorama format: intraday snapshots (~every 10 min during market hours), serialized as pickle bz2.
Euronext format: one .xlsx or .csv file per day, containing daily OHLCV data for all listed securities.

Data import starts automatically in the background when the application launches. Depending on the data volume, it may take several minutes before charts are populated.

---

Installation & Setup

Prerequisites

• Docker ≥ 24
• Docker Compose ≥ 2 (included in Docker Desktop)

Running the app

# 1. Clone the repository
git clone git@github.com:Tooom123/StocKings.git
cd stock-exchange-visualizer

# 2. Place the data (see section above)

# 3. Start
docker compose up --build

The application is accessible at the address shown in the terminal, by default:

http://localhost:8050

To stop:

docker compose down

To reset from scratch (database included):

docker compose down -v
rm -rf /tmp/bourse/timescaledb

---

Technical Architecture

stock-exchange-visualizer/
├── bourse/
│   ├── app.py                 # Dash application + callbacks
│   ├── etl.py                 # Import pipeline (Pandas, ThreadPoolExecutor)
│   ├── timescaledb_model.py   # TimescaleDB access layer (do not modify)
│   └── assets/
│       ├── style.css          # Custom dark theme
│       └── crown.png          # Logo
├── compose.yml                # Docker services (dashboard + database)
├── Dockerfile                 # Python image (uv, Python 3.14)
└── pyproject.toml             # Python dependencies

Stack

Component	Technology
Frontend	Dash + Dash Bootstrap Components
Charts	Plotly
Data processing	Pandas
Database	TimescaleDB (time-series PostgreSQL extension)
Package manager	uv
Containerization	Docker + Docker Compose

Main tables

Table	Content
companies	Company registry (name, symbol, ISIN, Boursorama/Euronext codes)
markets	Referenced financial markets
stocks	Intraday ticks (date, cid, value, volume) — Boursorama source
daystocks	Daily OHLCV aggregates + mean + standard deviation — Euronext source + Boursorama aggregation

---

Development Notes

• The file bourse/timescaledb_model.py must not be modified (project contract).
• Data is mounted as a volume (./data → /mnt/data inside the container): no rebuild needed to add new data.
• Import is incremental: already-processed files are tracked in the file_done table and are not re-imported.