diff --git a/README.md b/README.md
new file mode 100644
index 0000000..221b673
--- /dev/null
+++ b/README.md
@@ -0,0 +1,117 @@
+# Joachim Hummel – Portfolio
+
+Personal portfolio website for Joachim Hummel — Senior IT-Consultant, DevOps Engineer, KI-Automation Experte.
+
+Built with React + Vite (frontend) and Express 5 (API), running as a pnpm monorepo.
+
+---
+
+## Prerequisites
+
+- **Node.js** 24+
+- **pnpm** 10+ — install via `npm install -g pnpm`
+- **PostgreSQL** 14+ — local installation or a hosted instance (e.g. Supabase, Neon, Railway)
+
+---
+
+## Installation
+
+```bash
+# 1. Clone the repository
+git clone <repo-url>
+cd <repo-folder>
+
+# 2. Install all workspace dependencies
+pnpm install
+```
+
+---
+
+## Environment Variables
+
+Create a `.env` file in the project root (or export the variables in your shell):
+
+```env
+# PostgreSQL connection string (required)
+DATABASE_URL=postgresql://user:password@localhost:5432/portfolio
+
+# Session secret — any long random string (required)
+SESSION_SECRET=your-very-long-random-secret-here
+
+# Brevo (Sendinblue) API key — required for the contact form to send emails
+BREVO_API_KEY=your-brevo-api-key
+```
+
+> **Brevo API key:** Sign up for free at [brevo.com](https://www.brevo.com), then generate an API key under *SMTP & API → API Keys*.
+
+---
+
+## Database Setup
+
+Push the schema to your PostgreSQL database (run once, or after schema changes):
+
+```bash
+pnpm --filter @workspace/db run push
+```
+
+---
+
+## Running Locally
+
+Start both services in separate terminal windows:
+
+```bash
+# Terminal 1 — API server (http://localhost:8080)
+pnpm --filter @workspace/api-server run dev
+
+# Terminal 2 — Frontend (http://localhost:23924)
+pnpm --filter @workspace/joachim-portfolio run dev
+```
+
+Open **http://localhost:23924** in your browser.
+
+---
+
+## Project Structure
+
+```
+artifacts/
+  api-server/          # Express 5 API — contact form, health check
+  joachim-portfolio/   # React + Vite frontend (portfolio site)
+lib/
+  db/                  # Drizzle ORM schema & migrations
+  api-spec/            # OpenAPI spec + generated client hooks
+  api-client-react/    # Generated React Query hooks (from Orval)
+scripts/               # Utility scripts
+```
+
+---
+
+## Useful Commands
+
+| Command | Description |
+|---------|-------------|
+| `pnpm install` | Install all dependencies |
+| `pnpm run typecheck` | Full TypeScript check across all packages |
+| `pnpm run build` | Typecheck + build all packages |
+| `pnpm --filter @workspace/db run push` | Push DB schema changes (dev only) |
+| `pnpm --filter @workspace/api-spec run codegen` | Regenerate API hooks from OpenAPI spec |
+
+---
+
+## Production Build
+
+```bash
+# Build frontend static files
+pnpm --filter @workspace/joachim-portfolio run build
+# Output: artifacts/joachim-portfolio/dist/public
+
+# Build API server
+pnpm --filter @workspace/api-server run build
+# Output: artifacts/api-server/dist/index.mjs
+
+# Start API server in production
+NODE_ENV=production PORT=8080 node --enable-source-maps artifacts/api-server/dist/index.mjs
+```
+
+Serve the frontend's `dist/public` folder via any static file server (Nginx, Caddy, etc.) and proxy `/api/*` requests to the API server.