clubber/openspec/changes/archive/2025-11-20-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 - Technology stack and conventions
• FastAPI Documentation
• Strawberry GraphQL
• SQLAlchemy 2.0
• Alembic