clubber/openspec/changes/add-graphql-member-api/proposal.md

# Proposal: Add GraphQL Member API

**Change ID:** `add-graphql-member-api`
**Status:** Draft
**Created:** 2025-11-20
**Author:** System

## Overview

This proposal implements the foundational GraphQL API for member management in the Clubber application. It establishes the complete Python project infrastructure and delivers basic CRUD operations for member records through a GraphQL interface backed by SQLite.

## Motivation

**Why now?**
- The project currently has only documentation; we need working code to validate the architecture
- Member management is the core domain entity for a club/society management system
- A simple, working API provides a foundation for iterative development

**What problem does this solve?**
- Enables creating, reading, updating, and deleting member records
- Provides a type-safe GraphQL API for future client applications
- Establishes project structure, tooling, and development patterns
- Validates technology stack choices (FastAPI, Strawberry, SQLAlchemy)

**Why this approach?**
- GraphQL provides flexible queries and strong typing for client needs
- Strawberry integrates naturally with Python type hints and FastAPI
- SQLAlchemy offers database-agnostic code for future PostgreSQL migration
- Alembic ensures schema changes are versioned and reproducible

## Scope

### In Scope

**Project Infrastructure:**
- Python project setup with uv dependency management
- pyproject.toml with all dependencies (FastAPI, Strawberry, SQLAlchemy, Alembic)
- Source directory structure (models, schemas, resolvers, services)
- Development tooling (black, ruff, isort, pytest)
- Testing infrastructure with pytest-asyncio

**Database Layer:**
- SQLAlchemy async models for Member entity
- Alembic configuration and initial migration
- SQLite database for development
- Database connection and session management

**GraphQL API:**
- Strawberry GraphQL schema definition
- FastAPI application with GraphQL endpoint
- Member type with all fields (name, address, contact)
- Query resolvers (getMember, listMembers)
- Mutation resolvers (createMember, updateMember, deleteMember)

**Member Management:**
- Member model with:
  - First name (required)
  - Last name (optional)
  - Address fields (street, apartment number, zip, city, country) - all optional
  - Email address (optional, format validated when provided, non-unique)
  - Phone number (optional, format validated when provided, non-unique)
- CRUD operations with conditional validation
- Only firstName required for member creation
- Database seed script with one sample member

### Out of Scope

- MCP server integration (future enhancement)
- Authentication and authorization (future security layer)
- Member status tracking (active/inactive/honorary)
- Membership and payment tracking (separate features)
- Email/phone uniqueness constraints (may add later if needed)
- PostgreSQL support (database-agnostic code only)
- API rate limiting or advanced security
- Frontend/client implementation
- Deployment configuration

### Dependencies

- No dependencies on other changes (this is foundational)
- Future changes will build on this API structure

## Changes

### New Capabilities

Four new capabilities with detailed specifications:

1. **project-setup** - Python project foundation
   - Location: `openspec/changes/add-graphql-member-api/specs/project-setup/spec.md`
   - Establishes pyproject.toml, directory structure, tooling

2. **database-layer** - SQLAlchemy models and migrations
   - Location: `openspec/changes/add-graphql-member-api/specs/database-layer/spec.md`
   - Defines Member model, Alembic setup, database connections

3. **graphql-api** - GraphQL schema and FastAPI integration
   - Location: `openspec/changes/add-graphql-member-api/specs/graphql-api/spec.md`
   - Strawberry schema, types, resolvers, FastAPI endpoint

4. **member-crud** - Member business operations
   - Location: `openspec/changes/add-graphql-member-api/specs/member-crud/spec.md`
   - Create, read, update, delete operations with validation

### Modified Capabilities

None (no existing code to modify)

### Removed Capabilities

None

## Impact Analysis

### Breaking Changes

None (this is the first implementation)

### Migration Path

Not applicable (greenfield development)

### Risks and Mitigations

| Risk | Impact | Mitigation |
|------|--------|------------|
| Technology stack mismatch | High | Align with project.md specifications; validate with simple implementation first |
| Database schema changes | Medium | Use Alembic from the start; follow migration best practices |
| Validation complexity | Low | Start with simple format validation; enhance later if needed |
| Over-engineering | Medium | Keep implementation minimal; no premature abstractions |

### Performance Considerations

- SQLite is single-writer; acceptable for <1000 members initially
- No pagination in v1 (listMembers returns all); add when needed
- Database connection pooling deferred until PostgreSQL migration

### Security Considerations

- No authentication in v1 (explicitly out of scope)
- Basic input validation (email/phone format)
- SQL injection protected by SQLAlchemy ORM
- GDPR compliance deferred to future auth/privacy features

## Success Criteria

### Definition of Done

- [ ] All code passes `ruff` and `black` checks
- [ ] All tests pass with `pytest`
- [ ] Database migrations apply successfully with `alembic upgrade head`
- [ ] GraphQL schema is introspectable via GraphiQL
- [ ] Sample member exists in database after seed script
- [ ] All CRUD operations work via GraphQL playground
- [ ] Documentation includes setup instructions

### Validation Steps

1. Clone repository and navigate to project root
2. Run `uv sync` to install dependencies
3. Run `alembic upgrade head` to create database
4. Run `python scripts/seed.py` to create sample member
5. Start server with `uv run uvicorn src.main:app --reload`
6. Open GraphiQL at http://localhost:8000/graphql
7. Execute queries and mutations to verify CRUD operations
8. Run `pytest` to verify all tests pass

### Metrics

- Code coverage: Minimum 80% for new code
- GraphQL schema: 100% of spec requirements implemented
- Database migrations: Zero manual SQL required
- Setup time: <5 minutes from clone to running server

## Timeline

This proposal includes tasks.md with ~15-20 discrete work items, estimated to be completable in sequence. No explicit timeline commitment per OpenSpec conventions.

## Alternatives Considered

### REST API instead of GraphQL

**Rejected because:**
- GraphQL provides better flexibility for future client needs
- Type safety and introspection are valuable for development
- Project.md explicitly specifies Strawberry GraphQL

### Skip Alembic, use create_all()

**Rejected because:**
- Migrations are essential for production schema evolution
- Small cost now, significant benefit later
- Aligns with project.md best practices

### PostgreSQL from the start

**Rejected because:**
- Adds complexity without immediate value
- SQLite sufficient for development and testing
- Database-agnostic code enables future migration

## References

- [project.md](/openspec/project.md) - Technology stack and conventions
- [FastAPI Documentation](https://fastapi.tiangolo.com/)
- [Strawberry GraphQL](https://strawberry.rocks/)
- [SQLAlchemy 2.0](https://docs.sqlalchemy.org/en/20/)
- [Alembic](https://alembic.sqlalchemy.org/)