clubber/openspec/specs/project-setup/spec.md

# project-setup Specification

## Purpose
TBD - created by archiving change add-graphql-member-api. Update Purpose after archive.
## Requirements
### Requirement: Python project structure with uv dependency management

The project MUST use Python 3.11+ with uv for fast, reliable dependency management and provide a standard src/ layout for code organization.

#### Scenario: Developer initializes new development environment

**Given** a developer has cloned the repository
**When** they run `uv sync`
**Then** all dependencies are installed in a virtual environment
**And** the environment is ready for development within 30 seconds

#### Scenario: Developer runs the application

**Given** dependencies are installed
**When** developer runs `uv run uvicorn src.main:app --reload`
**Then** the FastAPI server starts on http://localhost:8000
**And** GraphQL playground is available at http://localhost:8000/graphql

### Requirement: Project configuration in pyproject.toml

The project MUST define all metadata, dependencies, and tool configurations in pyproject.toml following modern Python packaging standards.

**Dependencies required:**
- fastapi >= 0.104.0 (Web framework)
- strawberry-graphql[fastapi] >= 0.215.0 (GraphQL integration)
- sqlalchemy[asyncio] >= 2.0.0 (ORM with async support)
- aiosqlite >= 0.19.0 (Async SQLite driver)
- alembic >= 1.12.0 (Database migrations)
- pydantic-settings >= 2.0.0 (Configuration management)
- uvicorn[standard] >= 0.24.0 (ASGI server)

**Development dependencies required:**
- pytest >= 7.4.0 (Test framework)
- pytest-asyncio >= 0.21.0 (Async test support)
- black >= 23.0.0 (Code formatting)
- ruff >= 0.1.0 (Linting)
- isort >= 5.12.0 (Import sorting)

#### Scenario: Dependencies are declared with version constraints

**Given** pyproject.toml exists
**When** developer inspects [project.dependencies]
**Then** all required packages are listed with minimum versions
**And** version constraints allow patch/minor updates

#### Scenario: Development tools are configured

**Given** pyproject.toml contains tool configurations
**When** developer runs `black .`
**Then** code is formatted with line length 88
**When** developer runs `ruff check .`
**Then** code is linted against configured rules

### Requirement: Source directory structure following layered architecture

The project MUST organize code into src/ directory with clear separation of concerns across API, business logic, and data layers.

**Required directory structure:**
```
src/
├── __init__.py
├── main.py              # FastAPI application, startup/shutdown
├── config.py            # Settings and configuration
├── database.py          # Database connection, session factory
├── models/              # SQLAlchemy ORM models
│   ├── __init__.py
│   └── member.py
├── schemas/             # Strawberry GraphQL types
│   ├── __init__.py
│   └── member.py
└── resolvers/           # GraphQL query/mutation resolvers
    ├── __init__.py
    └── member.py
```

#### Scenario: Code is organized by architectural layer

**Given** the src/ directory exists
**When** a developer navigates the codebase
**Then** models/ contains only SQLAlchemy ORM definitions
**And** schemas/ contains only Strawberry GraphQL type definitions
**And** resolvers/ contains only GraphQL resolver functions
**And** each module has clear, single responsibility

#### Scenario: Main application entry point is defined

**Given** src/main.py exists
**When** the file is imported
**Then** it exports a FastAPI `app` instance
**And** app includes GraphQL route at /graphql
**And** app includes startup event to verify database connection

### Requirement: Testing infrastructure with pytest

The project MUST provide pytest configuration for running async tests with database fixtures and code coverage reporting.

#### Scenario: Async tests can be executed

**Given** pytest and pytest-asyncio are installed
**When** developer runs `pytest`
**Then** all tests in tests/ directory are discovered
**And** async test functions execute correctly
**And** test results are displayed with pass/fail status

#### Scenario: Database fixtures are available for tests

**Given** tests/conftest.py defines database fixtures
**When** a test function requests `db_session` fixture
**Then** an isolated test database session is provided
**And** session is rolled back after test completion
**And** no test data persists between test runs

### Requirement: Code quality tooling configuration

The project MUST configure black, ruff, and isort for consistent code formatting and linting with settings in pyproject.toml.

**Black configuration:**
- Line length: 88 characters
- Target version: Python 3.11
- Skip string normalization: false

**Ruff configuration:**
- Line length: 88 characters
- Select: E, F, W, I (pycodestyle, pyflakes, warnings, isort)
- Ignore: E501 (line too long, handled by black)

**Isort configuration:**
- Profile: black (compatible settings)
- Multi-line output: 3 (vertical hanging indent)

#### Scenario: Code formatting is enforced

**Given** black is configured in pyproject.toml
**When** developer runs `black --check .`
**Then** all Python files are checked for formatting
**And** exit code is 0 if all files are formatted correctly
**And** exit code is 1 if any files need formatting

#### Scenario: Code quality checks pass

**Given** ruff is configured in pyproject.toml
**When** developer runs `ruff check .`
**Then** all Python files are linted
**And** no errors are reported for compliant code
**And** clear error messages are shown for violations

### Requirement: Environment configuration with .env support

The project MUST support environment-based configuration using .env files with pydantic-settings for type-safe config values.

#### Scenario: Default configuration works for development

**Given** no .env file exists
**When** application starts
**Then** it uses default SQLite database path
**And** it runs in debug mode
**And** application starts successfully

#### Scenario: Environment variables override defaults

**Given** .env file contains `DATABASE_URL=sqlite+aiosqlite:///./test.db`
**When** application loads configuration
**Then** settings.database_url equals "sqlite+aiosqlite:///./test.db"
**And** custom database path is used

#### Scenario: Configuration is type-safe

**Given** src/config.py defines Settings class
**When** invalid configuration value is provided
**Then** pydantic validation raises clear error
**And** application fails fast on startup

### Requirement: Development scripts for common tasks

The project MUST provide executable scripts for database seeding and common development tasks.

**Required scripts:**
- scripts/seed.py - Populate database with sample member

#### Scenario: Seed script creates sample data

**Given** database schema exists from migrations
**When** developer runs `uv run python scripts/seed.py`
**Then** sample member is created in database
**And** script is idempotent (safe to run multiple times)
**And** success message is displayed

### Requirement: Automated Test Suite with Pytest
The project SHALL provide a comprehensive test suite using pytest to verify all features and prevent regressions.

#### Scenario: Run test suite successfully
- **GIVEN** the project is set up with dependencies installed
- **WHEN** the developer runs `uv run pytest`
- **THEN** all tests SHALL execute
- **AND** test results SHALL be displayed with pass/fail status
- **AND** the command SHALL exit with code 0 if all tests pass

#### Scenario: Run tests with verbose output
- **GIVEN** the project has tests implemented
- **WHEN** the developer runs `uv run pytest --verbose`
- **THEN** detailed test output SHALL be displayed
- **AND** each test name and result SHALL be shown

#### Scenario: Run specific test categories
- **GIVEN** tests are organized in subdirectories
- **WHEN** the developer runs `uv run pytest tests/unit`
- **THEN** only unit tests SHALL execute
- **WHEN** the developer runs `uv run pytest tests/integration`
- **THEN** only integration tests SHALL execute

### Requirement: Test Organization Structure
Tests SHALL be organized in a clear directory structure separating different test types.

#### Scenario: Test directory structure exists
- **GIVEN** the project repository
- **WHEN** inspecting the directory structure
- **THEN** a `tests/` directory SHALL exist at the project root
- **AND** subdirectories `tests/unit/`, `tests/integration/`, `tests/e2e/`, and `tests/mcp/` SHALL exist
- **AND** a `tests/conftest.py` file SHALL exist for shared fixtures

#### Scenario: Test files follow naming convention
- **GIVEN** test files in the `tests/` directory
- **WHEN** examining file names
- **THEN** all test files SHALL be named `test_*.py`
- **AND** test file names SHALL correspond to the modules they test (e.g., `test_validation.py` for `validation.py`)

### Requirement: Shared Test Fixtures
The test suite SHALL provide reusable fixtures for common test setup via conftest.py.

#### Scenario: Database fixture provides in-memory SQLite
- **GIVEN** tests need database access
- **WHEN** a test function requests the `db` fixture
- **THEN** an in-memory SQLite database SHALL be created
- **AND** the database SHALL have all tables created via Alembic migrations or direct schema creation
- **AND** the database SHALL be cleaned up after the test completes

#### Scenario: Async session fixture provides database sessions
- **GIVEN** tests need to interact with the database
- **WHEN** a test function requests the `async_session` fixture
- **THEN** an async SQLAlchemy session SHALL be provided
- **AND** the session SHALL be connected to the test database
- **AND** the session SHALL be closed after the test completes

#### Scenario: GraphQL client fixture provides test client
- **GIVEN** tests need to make GraphQL requests
- **WHEN** a test function requests the `graphql_client` fixture
- **THEN** a FastAPI test client SHALL be provided
- **AND** the client SHALL be configured to use the test database
- **AND** the client SHALL support async GraphQL queries and mutations

### Requirement: Unit Tests for Validation Logic
Unit tests SHALL verify validation functions work correctly with valid and invalid inputs.

#### Scenario: Test firstName validation with valid input
- **GIVEN** a valid firstName "Alice"
- **WHEN** `validate_first_name("Alice")` is called
- **THEN** no exception SHALL be raised

#### Scenario: Test firstName validation with empty string
- **GIVEN** an empty firstName ""
- **WHEN** `validate_first_name("")` is called
- **THEN** a ValidationError SHALL be raised
- **AND** the error message SHALL indicate firstName cannot be empty

#### Scenario: Test email validation with valid email
- **GIVEN** a valid email "test@example.com"
- **WHEN** `validate_email("test@example.com")` is called
- **THEN** no exception SHALL be raised

#### Scenario: Test email validation with invalid email
- **GIVEN** an invalid email "not-an-email"
- **WHEN** `validate_email("not-an-email")` is called
- **THEN** a ValidationError SHALL be raised
- **AND** the error message SHALL indicate invalid email format

#### Scenario: Test email validation with None
- **GIVEN** email is None
- **WHEN** `validate_email(None)` is called
- **THEN** no exception SHALL be raised (None is allowed)

#### Scenario: Test phone validation with valid E.164 number
- **GIVEN** a valid phone "+41791234567"
- **WHEN** `validate_phone("+41791234567")` is called
- **THEN** no exception SHALL be raised

#### Scenario: Test phone validation with invalid number
- **GIVEN** an invalid phone "123"
- **WHEN** `validate_phone("123")` is called
- **THEN** a ValidationError SHALL be raised

#### Scenario: Test phone validation with None
- **GIVEN** phone is None
- **WHEN** `validate_phone(None)` is called
- **THEN** no exception SHALL be raised (None is allowed)

### Requirement: Integration Tests for Member Model
Integration tests SHALL verify database operations with the Member model.

#### Scenario: Create member with minimal data
- **GIVEN** a test database session
- **WHEN** a Member is created with only firstName="Alice"
- **THEN** the member SHALL be persisted to the database
- **AND** the member SHALL have an auto-generated ID
- **AND** created_at and updated_at timestamps SHALL be populated
- **AND** all optional fields SHALL be None

#### Scenario: Create member with complete data
- **GIVEN** a test database session
- **WHEN** a Member is created with all fields populated
- **THEN** the member SHALL be persisted with all data
- **AND** all fields SHALL match the provided values

#### Scenario: Member timestamps are set correctly
- **GIVEN** a newly created member
- **THEN** created_at SHALL be set to current time
- **AND** updated_at SHALL be set to current time
- **AND** created_at SHALL equal updated_at for new members

### Requirement: Integration Tests for GraphQL Queries
Integration tests SHALL verify GraphQL query resolvers return correct data.

#### Scenario: Query single member by ID
- **GIVEN** a member exists with ID 1
- **WHEN** the `member(id: 1)` query is executed
- **THEN** the member data SHALL be returned
- **AND** all requested fields SHALL match the database record

#### Scenario: Query member with non-existent ID
- **GIVEN** no member exists with ID 999
- **WHEN** the `member(id: 999)` query is executed
- **THEN** None SHALL be returned
- **AND** no error SHALL be raised

#### Scenario: List all members
- **GIVEN** multiple members exist in the database
- **WHEN** the `members` query is executed
- **THEN** an array of all members SHALL be returned
- **AND** members SHALL be sorted by last_name (nulls last), then first_name

#### Scenario: List members when database is empty
- **GIVEN** no members exist in the database
- **WHEN** the `members` query is executed
- **THEN** an empty array SHALL be returned

### Requirement: Integration Tests for GraphQL Mutations
Integration tests SHALL verify GraphQL mutation resolvers create, update, and delete members correctly.

#### Scenario: Create member with minimal data
- **GIVEN** CreateMemberInput with only firstName="Bob"
- **WHEN** the `createMember` mutation is executed
- **THEN** a new member SHALL be created in the database
- **AND** the member SHALL have firstName="Bob"
- **AND** all optional fields SHALL be None
- **AND** the mutation SHALL return the created member with ID

#### Scenario: Create member with complete data
- **GIVEN** CreateMemberInput with all fields populated
- **WHEN** the `createMember` mutation is executed
- **THEN** a new member SHALL be created with all data
- **AND** all fields SHALL match the input

#### Scenario: Create member with invalid email
- **GIVEN** CreateMemberInput with email="not-an-email"
- **WHEN** the `createMember` mutation is executed
- **THEN** a ValidationError SHALL be raised
- **AND** no database record SHALL be created

#### Scenario: Update member successfully
- **GIVEN** a member exists with ID 1
- **WHEN** the `updateMember` mutation is executed with id=1 and email="new@example.com"
- **THEN** the member's email SHALL be updated to "new@example.com"
- **AND** the updated_at timestamp SHALL be refreshed
- **AND** all other fields SHALL remain unchanged

#### Scenario: Update member with non-existent ID
- **GIVEN** no member exists with ID 999
- **WHEN** the `updateMember` mutation is executed with id=999
- **THEN** a MemberNotFoundError SHALL be raised
- **AND** the error message SHALL indicate member not found

#### Scenario: Delete member successfully
- **GIVEN** a member exists with ID 1
- **WHEN** the `deleteMember` mutation is executed with id=1
- **THEN** the member SHALL be removed from the database
- **AND** the mutation SHALL return true
- **AND** subsequent queries for that member SHALL return None

#### Scenario: Delete member with non-existent ID
- **GIVEN** no member exists with ID 999
- **WHEN** the `deleteMember` mutation is executed with id=999
- **THEN** a MemberNotFoundError SHALL be raised

### Requirement: E2E Tests for GraphQL API
End-to-end tests SHALL verify complete GraphQL request/response flows over HTTP.

#### Scenario: Execute GraphQL query via HTTP POST
- **GIVEN** the FastAPI application with GraphQL endpoint
- **WHEN** a POST request is sent to /graphql with a query
- **THEN** the query SHALL be executed
- **AND** a JSON response SHALL be returned with data or errors

#### Scenario: GraphQL introspection query
- **GIVEN** the GraphQL API is running
- **WHEN** an introspection query for __schema is executed
- **THEN** the complete schema SHALL be returned
- **AND** all types, queries, and mutations SHALL be included

#### Scenario: GraphQL type introspection
- **GIVEN** the GraphQL API is running
- **WHEN** an introspection query for __type(name: "Member") is executed
- **THEN** the Member type definition SHALL be returned
- **AND** all fields with their types SHALL be included

### Requirement: MCP Server Tests
Tests SHALL verify MCP server tool definitions and execution.

#### Scenario: MCP server initializes successfully
- **GIVEN** a valid CLUBBER_API_URL
- **WHEN** the MCP server is instantiated
- **THEN** the server SHALL initialize without errors
- **AND** the GraphQL client SHALL be configured

#### Scenario: List tools returns all 6 tools
- **GIVEN** an initialized MCP server
- **WHEN** `list_tools()` is called
- **THEN** 6 tools SHALL be returned
- **AND** tools SHALL include: list_members, get_member, create_member, update_member, get_graphql_schema, execute_graphql_query

#### Scenario: Execute list_members tool
- **GIVEN** members exist in the database
- **WHEN** the `list_members` tool is invoked
- **THEN** a formatted list of all members SHALL be returned

#### Scenario: Execute get_member tool
- **GIVEN** a member exists with ID 1
- **WHEN** the `get_member` tool is invoked with id=1
- **THEN** the member's data SHALL be returned as formatted text

#### Scenario: Execute create_member tool
- **GIVEN** valid member input data
- **WHEN** the `create_member` tool is invoked
- **THEN** a new member SHALL be created via the GraphQL API
- **AND** the created member data SHALL be returned

#### Scenario: Execute get_graphql_schema tool
- **GIVEN** the GraphQL API is accessible
- **WHEN** the `get_graphql_schema` tool is invoked
- **THEN** the complete schema SHALL be retrieved via introspection
- **AND** formatted schema information SHALL be returned

#### Scenario: Execute execute_graphql_query tool with simple query
- **GIVEN** a valid GraphQL query string
- **WHEN** the `execute_graphql_query` tool is invoked
- **THEN** the query SHALL be executed against the API
- **AND** formatted JSON results SHALL be returned

#### Scenario: Execute execute_graphql_query tool with variables
- **GIVEN** a GraphQL query with variables
- **WHEN** the `execute_graphql_query` tool is invoked with query and variables
- **THEN** the query SHALL be executed with variable substitution
- **AND** results SHALL be returned

### Requirement: Test Documentation in README
The README SHALL document how to run tests and understand test organization.

#### Scenario: README contains test running instructions
- **GIVEN** the README.md file
- **WHEN** reading the documentation
- **THEN** a "Running Tests" section SHALL exist
- **AND** the section SHALL document the `uv run pytest` command
- **AND** examples of running specific test categories SHALL be provided

#### Scenario: README documents test organization
- **GIVEN** the README.md file
- **WHEN** reading the documentation
- **THEN** a "Test Organization" section SHALL exist
- **AND** the section SHALL explain the tests/ directory structure
- **AND** the section SHALL describe unit, integration, e2e, and mcp test categories