clubber/README.md

Clubber

A toolset for managing members of non-profit societies (Vereine) with AI-powered administration.

Overview

Clubber provides a GraphQL API for member management combined with an MCP (Model Context Protocol) server that enables AI assistants to help with society administration tasks.

Current Status: Early development - OpenSpec documentation and project structure in place.

Architecture

The system consists of two main components:

1. GraphQL API - Core backend for member data management

   • Built with FastAPI and Strawberry GraphQL
   • Database-agnostic design (SQLite for development, PostgreSQL for production)
   • SQLAlchemy 2.0 ORM with async support

2. MCP Server - AI assistant integration layer

   • Connects to the GraphQL API
   • Provides tools for AI agents to manage society operations
   • Service account authentication

Tech Stack

• Python 3.11+ - Primary language
• uv - Fast package and project manager
• FastAPI - Async web framework
• Strawberry GraphQL - Type-safe GraphQL with Python type hints
• SQLAlchemy 2.0 - Database ORM
• Alembic - Database migrations

Project Structure

clubber/
├── openspec/           # Specification-driven development
│   ├── project.md      # Project conventions and context
│   ├── specs/          # Current specifications
│   └── changes/        # Change proposals
├── CLAUDE.md           # AI assistant instructions
└── README.md           # This file

Getting Started

Prerequisites

• Python 3.11 or higher
• uv package manager

Setup

# Clone the repository
git clone ssh://git@codeberg.org/gurix/clubber.git
cd clubber

# Install uv if not already installed
curl -LsSf https://astral.sh/uv/install.sh | sh

# Set up the project (when implemented)
# uv venv
# uv pip install -e .

Development Workflow

This project uses OpenSpec for specification-driven development:

1. Review existing specs in openspec/specs/
2. Create change proposals in openspec/changes/ before implementing features
3. Validate proposals with openspec validate --strict
4. Implement changes following the proposal
5. Archive completed changes after deployment

See openspec/AGENTS.md for detailed workflow instructions.

Working with Git Worktrees

We use git worktrees for parallel development:

# Create a worktree for a feature branch
git worktree add ../clubber-feature-name feature/feature-name

# Work in the worktree
cd ../clubber-feature-name

# Remove worktree after merge
git worktree remove ../clubber-feature-name

Contributing

1. Read openspec/project.md for project conventions
2. For new features, create an OpenSpec proposal first
3. Follow the coding style (Black, isort, ruff)
4. Write tests for new functionality
5. Use conventional commits (feat:, fix:, docs:, etc.)

License

The MIT License

Contact

Markus Graf - info@markusgraf.ch

Acknowledgments

Built with support from:

• Strawberry GraphQL
• FastAPI
• OpenSpec