BTC-Portfolio/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Running the Application

Docker (recommended)

cd btc-portfolio
docker-compose up
# Frontend: http://localhost:3000
# Backend: http://localhost:8000

Local development

# Backend
cd btc-portfolio/backend
pip install -r requirements.txt
uvicorn app.main:app --reload

# Frontend
cd btc-portfolio/frontend
npm install && npm start

No automated tests are configured — testing is manual.

Architecture

Full-stack Bitcoin portfolio tracker:

• Frontend: React 18 SPA (btc-portfolio/frontend/src/) — dark theme, Bitcoin orange (#f7931a). JWT stored in localStorage. API URL configured via REACT_APP_API_URL.
• Backend: FastAPI (btc-portfolio/backend/app/) — SQLite + SQLAlchemy, JWT auth (HS256, 24h expiry), CoinGecko API for live BTC prices in EUR.
• Data flow: React → FastAPI (Bearer token) → SQLite + CoinGecko

Backend structure

app/
  main.py          # FastAPI app, CORS (localhost:3000 only)
  models.py        # User, Purchase ORM models
  auth.py          # JWT + bcrypt (SECRET_KEY hardcoded — env var for prod)
  dependencies.py  # get_current_user dependency
  routes/
    users.py       # POST /register, POST /login
    purchases.py   # CRUD /purchases, /purchases/{id}
    stats.py       # GET /stats (portfolio calculations)
    history.py     # GET /history (365 days BTC prices)
  services/
    btc.py         # CoinGecko integration (returns 0.0 on failure)

Frontend structure

src/
  App.js           # Routing (public: /login, /register; protected: /dashboard)
  pages/
    Dashboard.js   # Main view: stats, purchase management, charts
  components/
    AddPurchase.js      # Form: amount EUR + BTC price
    PurchaseList.js     # Table with inline edit/delete, sorted by date asc
    PortfolioChart.js   # Invested vs current value chart
    BTCHistoryChart.js  # 1-year BTC price history chart

Dashboard has a chart toggle (Both / Portfolio / 1-Year BTC) using tab state in Dashboard.js.

Database schema

• users: id, username (unique), password (bcrypt)
• purchases: id, amount_eur, price_eur, created_at, user_id (FK)

Database persists via Docker volume at /app/data/btc_portfolio.db.

Git Workflow

• Never work directly on main. All development happens on development (or a feature branch).
• After any merge/push to main, always switch back to development immediately.
• main is only touched to merge in completed work from development.