# CLAUDE.md

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

## Running the Application

### Docker (recommended)
```bash
cd btc-portfolio
docker-compose up
# Frontend: http://localhost:3000
# Backend: http://localhost:8000
```

### Local development
```bash
# 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`.