From e27701e9bf98fd407bf626347d357592f22aafd4 Mon Sep 17 00:00:00 2001
From: Markus Graf <info@markusgraf.ch>
Date: Thu, 20 Nov 2025 12:53:09 +0100
Subject: [PATCH] docs: update README with API server setup and usage
 instructions
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Add comprehensive documentation for running the GraphQL API:
- Complete setup instructions (dependencies, migrations, seeding)
- Server startup commands and endpoints
- Member data model documentation
- GraphQL query and mutation examples
- curl command examples

Replace placeholder "when implemented" comments with actual working instructions.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
---
 README.md | 151 ++++++++++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 148 insertions(+), 3 deletions(-)

diff --git a/README.md b/README.md
index 62b8a76..92a1767 100644
--- a/README.md
+++ b/README.md
@@ -60,9 +60,154 @@ cd clubber
 # Install uv if not already installed
 curl -LsSf https://astral.sh/uv/install.sh | sh
 
-# Set up the project (when implemented)
-# uv venv
-# uv pip install -e .
+# Install dependencies
+uv sync
+
+# Run database migrations
+uv run alembic upgrade head
+
+# (Optional) Seed the database with sample data
+PYTHONPATH=. uv run python scripts/seed.py
+```
+
+### Running the Server
+
+Start the development server:
+
+```bash
+uv run uvicorn src.main:app --host 127.0.0.1 --port 8000 --reload
+```
+
+The `--reload` flag enables auto-restart when code changes are detected.
+
+Access the API:
+- **GraphQL Playground**: http://127.0.0.1:8000/graphql
+- **API Documentation**: http://127.0.0.1:8000/docs
+- **Root Endpoint**: http://127.0.0.1:8000/
+
+## API Usage Examples
+
+### Member Data Model
+
+Members have the following fields:
+- `firstName` (required) - Member's first name
+- `lastName` (optional) - Member's last name
+- `street` (optional) - Street address
+- `apartmentNumber` (optional) - Apartment or unit number
+- `zip` (optional) - Postal code
+- `city` (optional) - City
+- `country` (optional) - Country
+- `email` (optional) - Email address (validated when provided)
+- `phone` (optional) - Phone number in E.164 format (validated when provided)
+
+**Key Feature**: Only `firstName` is required. All other fields are optional and can be populated later. Email and phone are validated only when provided (not when null/empty).
+
+### GraphQL Queries
+
+List all members:
+```graphql
+{
+  members {
+    id
+    firstName
+    lastName
+    email
+    phone
+    city
+  }
+}
+```
+
+Get a single member:
+```graphql
+{
+  member(id: 1) {
+    id
+    firstName
+    lastName
+    email
+    street
+    city
+    country
+  }
+}
+```
+
+### GraphQL Mutations
+
+Create a member (minimal - only firstName):
+```graphql
+mutation {
+  createMember(input: {
+    firstName: "Alice"
+  }) {
+    id
+    firstName
+    email
+  }
+}
+```
+
+Create a member with all fields:
+```graphql
+mutation {
+  createMember(input: {
+    firstName: "Bob"
+    lastName: "Johnson"
+    street: "123 Main St"
+    apartmentNumber: "4B"
+    zip: "12345"
+    city: "Springfield"
+    country: "USA"
+    email: "bob.johnson@example.com"
+    phone: "+14155551234"
+  }) {
+    id
+    firstName
+    lastName
+    email
+    phone
+  }
+}
+```
+
+Update a member:
+```graphql
+mutation {
+  updateMember(input: {
+    id: 1
+    email: "updated@example.com"
+    phone: "+14155559999"
+  }) {
+    id
+    firstName
+    email
+    phone
+  }
+}
+```
+
+Delete a member:
+```graphql
+mutation {
+  deleteMember(id: 2)
+}
+```
+
+### Using curl
+
+Query members:
+```bash
+curl -X POST http://127.0.0.1:8000/graphql \
+  -H "Content-Type: application/json" \
+  -d '{"query": "{ members { id firstName lastName email } }"}'
+```
+
+Create a member:
+```bash
+curl -X POST http://127.0.0.1:8000/graphql \
+  -H "Content-Type: application/json" \
+  -d '{"query": "mutation { createMember(input: { firstName: \"Charlie\" }) { id firstName } }"}'
 ```
 
 ## Development Workflow