Initial commit

2025-11-19 22:13:05 +01:00
commit df76a89c1b
7 changed files with 887 additions and 0 deletions
@@ -0,0 +1,320 @@
+# Project Context
+
+## Purpose
+This project provides a toolset for managing members of a non-profit society. It consists of a graphql api. A simple MCP server that connects to the graphql api provides the tools for AI agents to manage the society administration.
+
+## Tech Stack
+
+### Core Framework
+- **Python 3.11+** - Primary language
+- **uv** - Fast Python package and project manager
+- **FastAPI** - Async web framework and HTTP layer
+- **Strawberry GraphQL** - Schema-first GraphQL with Python type hints
+
+### Data Layer
+- **SQLAlchemy 2.0** - ORM with modern async support
+- **Alembic** - Database migration management
+- **SQLite** - Development and testing database
+- **PostgreSQL** - Production database (future)
+
+### Integration Layer
+- **MCP Server (Python)** - AI assistant integration
+- **httpx** - HTTP client for GraphQL queries
+
+## Project Conventions
+
+### Code Style
+
+#### Formatting
+- **Black** - Code formatting (line length: 88)
+- **isort** - Import sorting (Black-compatible profile)
+- **ruff** - Fast linting and additional formatting
+
+#### Type Hints
+- Use type hints extensively for all function signatures
+- Leverage Strawberry's type system for GraphQL schema
+- SQLAlchemy models should use Mapped[] type annotations
+- Prefer explicit types over Any where possible
+
+#### Naming Conventions
+- **Files**: lowercase_with_underscores.py
+- **Classes**: PascalCase (e.g., MemberModel, MemberType)
+- **Functions/Variables**: snake_case (e.g., get_member, member_id)
+- **Constants**: UPPER_SNAKE_CASE (e.g., MAX_MEMBERS)
+- **GraphQL Types**: PascalCase matching domain entities
+- **GraphQL Fields**: camelCase (Strawberry default)
+
+#### Code Organization
+- Keep modules focused and single-purpose
+- Prefer flat structure until complexity requires hierarchy
+- Group related functionality (models, resolvers, services)
+- Avoid circular dependencies through clear layering
+
+#### Dependency Management
+- **uv** for all Python package management
+  - `uv pip install <package>` - Install packages
+  - `uv pip compile requirements.in -o requirements.txt` - Lock dependencies
+  - `uv venv` - Create virtual environments
+  - `uv run` - Run commands in virtual environment
+- **pyproject.toml** - Project metadata and dependencies
+- **requirements.txt** or **uv.lock** - Locked dependency versions
+- Pin major versions, allow minor/patch updates
+- Regular dependency updates for security patches
+- Separate dev dependencies from production dependencies
+
+#### Documentation
+- **README.md** - Primary project documentation
+  - Project overview and purpose
+  - Quick start guide
+  - Installation instructions (uv setup)
+  - Basic usage examples
+  - Links to OpenSpec documentation
+  - Contributing guidelines
+  - License information
+- Keep README.md up-to-date with major changes
+- README is the entry point for new developers and AI assistants
+- For detailed specs, refer to `openspec/` directory
+
+### Architecture Patterns
+
+#### Layered Architecture
+```
+API Layer (FastAPI + Strawberry)
+    ↓
+Service Layer (Business Logic)
+    ↓
+Data Layer (SQLAlchemy Models)
+    ↓
+Database (SQLite/PostgreSQL)
+```
+
+#### GraphQL Schema Design
+- **Type hints as schema**: Use Python types to define GraphQL schema
+- **Simple, consistent filters**: Prefer explicit arguments over complex nested filters
+  - Good: `members(status: MemberStatus, joinedAfter: Date)`
+  - Avoid: `members(where: {and: [{status: {eq: ACTIVE}}]})`
+- **Introspection-friendly**: Design schema for AI consumption via introspection
+- **Field descriptions**: Document all fields for self-describing API
+
+#### Database Patterns
+- **Database-agnostic code**: Write portable SQLAlchemy code for SQLite/PostgreSQL
+- **Connection string switching**: Same code works with different databases
+- **Alembic migrations**: All schema changes via migrations
+- **Async operations**: Use async SQLAlchemy patterns where beneficial
+
+#### Authentication
+- **JWT tokens** at HTTP layer (FastAPI middleware)
+- **Service account** for MCP server (admin privileges)
+- GraphQL resolvers assume authenticated context
+- Future: User-specific MCP instances
+
+#### Simplicity Principles
+- Default to single-file implementations (<100 lines)
+- Avoid frameworks/abstractions without clear justification
+- Choose boring, proven patterns
+- Add complexity only with:
+  - Performance data showing need
+  - Concrete scale requirements
+  - Multiple proven use cases
+
+### Testing Strategy
+
+#### Testing Pyramid
+- **Unit Tests**: Core business logic and utilities
+- **Integration Tests**: Database operations and GraphQL resolvers
+- **E2E Tests**: Complete GraphQL query/mutation flows
+- **MCP Tests**: Tool definitions and API integration
+
+#### Framework & Tools
+- **pytest** - Test runner with async support
+- **pytest-asyncio** - Async test support
+- **httpx** - Test client for FastAPI/GraphQL
+- **SQLAlchemy test fixtures** - In-memory SQLite for fast tests
+
+#### Test Organization
+```
+tests/
+├── unit/           # Pure logic tests
+├── integration/    # Database + resolver tests
+├── e2e/           # Full API tests
+└── mcp/           # MCP server tests
+```
+
+#### Coverage Goals
+- Aim for >80% coverage on business logic
+- 100% coverage on critical paths (payments, memberships)
+- Focus on behavior, not implementation details
+- Test error cases and edge conditions
+
+#### Testing Conventions
+- One test file per module: `test_<module>.py`
+- Descriptive test names: `test_member_creation_with_valid_data`
+- Use fixtures for common setup (db session, test data)
+- Clean database state between tests
+- Mock external services (future: email, payment providers)
+
+### Git Workflow
+
+#### Branching Strategy with Worktrees
+- **main** - Production-ready code (primary worktree)
+- **Feature branches** - `feature/<description>` or `<change-id>` from OpenSpec
+- **Hotfix branches** - `hotfix/<issue>`
+- Use **git worktrees** for parallel development:
+  - Each branch gets its own directory
+  - Work on multiple features simultaneously
+  - No need to stash or switch contexts
+  - Example: `git worktree add ../clubber-feature-payments feature/payments`
+- Keep branches short-lived (1-3 days max)
+- Remove worktree and delete branch after merge
+
+#### Commit Conventions
+- Use conventional commits format:
+  - `feat:` - New features
+  - `fix:` - Bug fixes
+  - `refactor:` - Code refactoring
+  - `docs:` - Documentation changes
+  - `test:` - Test additions/changes
+  - `chore:` - Build, config, dependencies
+- Examples:
+  - `feat: add member payment tracking`
+  - `fix: correct member status calculation`
+  - `refactor: simplify GraphQL resolver logic`
+
+#### Pull Request Process
+1. Create worktree for feature branch from main
+2. Implement changes with tests in worktree
+3. Run tests and linting locally
+4. Create PR with clear description
+5. Link to OpenSpec change if applicable
+6. Review and address feedback
+7. Squash merge to main
+8. Remove worktree: `git worktree remove <path>`
+
+#### Pre-commit Checks
+- Black formatting
+- isort import sorting
+- ruff linting
+- Type checking (mypy)
+- Tests pass
+
+## Domain Context
+
+### Non-Profit Society Management
+This system manages members of a registered non-profit society (Verein/club).
+
+#### Core Entities
+- **Members**: Individuals who belong to the society
+  - Active, inactive, honorary members
+  - Membership start/end dates
+  - Contact information
+  - Payment status
+
+- **Memberships**: The relationship between members and the society
+  - Annual/lifetime memberships
+  - Membership fees
+  - Payment tracking
+  - Status changes over time
+
+- **Payments**: Financial transactions
+  - Membership fees
+  - Donations
+  - Event fees
+  - Payment methods and tracking
+
+- **Events** (future): Society activities and meetings
+  - Member participation
+  - Registration and attendance
+
+#### Business Rules
+- Members must have valid contact information
+- Membership status changes based on payment history
+- Privacy considerations for member data (GDPR compliance)
+- Financial records must be auditable
+- Society governance (board members, voting rights)
+
+#### Common Operations
+- Add new members
+- Track membership payments
+- Generate membership lists
+- Send payment reminders
+- Export reports for annual meetings
+- Member communication
+
+## Important Constraints
+
+### Technical Constraints
+- **Database portability**: Code must work with both SQLite and PostgreSQL
+- **Async-first**: Use async patterns for scalability
+- **Single-server deployment**: No distributed systems initially
+- **Limited resources**: Optimize for small-scale (<1000 members initially)
+- **Python-only**: Keep the stack simple with one primary language
+
+### Business Constraints
+- **Data privacy**: GDPR compliance for EU member data
+  - Right to access (export member data)
+  - Right to deletion (full data removal)
+  - Consent tracking for communications
+  - Data minimization principles
+- **Audit trail**: Financial transactions must be traceable
+- **Offline capability**: Export functionality for offline access to critical data
+- **Non-profit requirements**: Transparent financial reporting
+
+### AI Integration Constraints
+- **Schema introspection**: GraphQL schema must be AI-readable
+- **Simple query patterns**: Avoid complex nested filters
+- **Service account authentication**: MCP server uses admin credentials
+- **Rate limiting**: Protect against excessive API usage (future)
+- **Query complexity limits**: Prevent resource-intensive operations
+
+### Development Constraints
+- **Simplicity first**: Avoid premature optimization
+- **Incremental delivery**: Start with core features, expand gradually
+- **Solo developer**: Optimize for maintainability over cleverness
+- **Open source ready**: Clean, documented code for potential future contributors
+
+## External Dependencies
+
+### Current Dependencies
+- **Python Package Index (PyPI)**: Package registry (managed via uv)
+  - strawberry-graphql
+  - fastapi
+  - sqlalchemy
+  - alembic
+  - httpx
+  - pytest and testing tools
+- **uv**: Fast package installer and resolver
+
+### Future/Planned Dependencies
+- **Email Service** (future): Transactional emails
+  - Payment reminders
+  - Membership notifications
+  - Board communications
+  - Consider: SMTP, SendGrid, or similar
+
+- **Payment Processing** (future): Online payment collection
+  - Bank transfers (EU SEPA)
+  - Credit card processing
+  - Payment reconciliation
+  - Consider: Stripe, PayPal, or EU-specific providers
+
+- **Document Storage** (future): Member documents and files
+  - Meeting minutes
+  - Member applications
+  - Financial reports
+  - Consider: Local filesystem, S3-compatible storage
+
+- **Backup Service** (future): Automated backups
+  - Database backups
+  - Document backups
+  - Disaster recovery
+
+### MCP Integration
+- **Claude AI API**: For AI assistant features via MCP
+- **MCP Protocol**: Standard protocol for AI tool integration
+- **GraphQL Introspection**: Self-documenting API for AI consumption
+
+### Development Tools
+- **Git**: Version control
+- **GitHub** (optional): Code hosting and collaboration
+- **Docker** (optional): Containerization for deployment
+- **CI/CD** (future): Automated testing and deployment