chore: archive add-graphql-member-api proposal and create capability specs
Archive completed GraphQL API implementation proposal: - Move proposal to openspec/changes/archive/2025-11-20-add-graphql-member-api/ - Create capability specs in openspec/specs/: - database-layer: SQLAlchemy async with Alembic migrations - graphql-api: Strawberry GraphQL with FastAPI integration - member-crud: Member management with conditional validation - project-setup: Python 3.11+ with uv package manager All 73 tasks completed and validated. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Claude
@@ -0,0 +1,208 @@
|
||||
# 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/)
|
||||
Reference in New Issue
Block a user