diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..c068d60
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,72 @@
+# 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`.