docs: add initial README and OpenSpec proposal

Add comprehensive README.md documenting project purpose, architecture, tech stack, and development workflow. Includes OpenSpec proposal (add-initial-readme) with project documentation specification. The README describes current state only (early development phase) and serves as entry point for developers and AI assistants. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
2025-11-19 22:26:28 +01:00
parent df76a89c1b
commit 57b37c366d
4 changed files with 179 additions and 0 deletions
@@ -0,0 +1,116 @@
+# 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)