117 lines
3.2 KiB
Markdown
117 lines
3.2 KiB
Markdown
 
|
# 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)
|