# 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](https://github.com/astral-sh/uv) package manager

### Setup

```bash
# 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](https://openspec.dev) 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:

```bash
# 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](mailto:info@markusgraf.ch)

## Acknowledgments

Built with support from:
- [Strawberry GraphQL](https://strawberry.rocks)
- [FastAPI](https://fastapi.tiangolo.com)
- [OpenSpec](https://openspec.dev)