diff --git a/README.md b/README.md new file mode 100644 index 0000000..62b8a76 --- /dev/null +++ b/README.md @@ -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) diff --git a/openspec/changes/add-initial-readme/proposal.md b/openspec/changes/add-initial-readme/proposal.md new file mode 100644 index 0000000..40cde4d --- /dev/null +++ b/openspec/changes/add-initial-readme/proposal.md @@ -0,0 +1,16 @@ +# Add Initial README + +## Why +The project currently has no README.md file. According to `openspec/project.md`, we maintain a README.md as the primary project documentation and entry point for developers and AI assistants. A README is essential for anyone discovering this repository on Codeberg. + +## What Changes +- Add README.md to project root describing current state +- Document the project's purpose and vision +- Explain OpenSpec-based development workflow +- Provide setup instructions for contributors +- **Note**: README describes *current* state only, not planned features + +## Impact +- Affected specs: project-documentation (new capability) +- Affected code: None (documentation only) +- No breaking changes diff --git a/openspec/changes/add-initial-readme/specs/project-documentation/spec.md b/openspec/changes/add-initial-readme/specs/project-documentation/spec.md new file mode 100644 index 0000000..165125f --- /dev/null +++ b/openspec/changes/add-initial-readme/specs/project-documentation/spec.md @@ -0,0 +1,34 @@ +# Project Documentation Specification + +## ADDED Requirements + +### Requirement: README File +The project root SHALL contain a README.md file that serves as the primary entry point for developers and AI assistants. + +#### Scenario: Repository discovery +- **WHEN** a developer or AI assistant discovers the repository +- **THEN** they can read README.md to understand project purpose and current state + +### Requirement: Current State Documentation +The README.md SHALL accurately describe only the current implementation state, not planned features. + +#### Scenario: Accurate project status +- **WHEN** reading the README.md +- **THEN** it reflects what is actually implemented +- **AND** does not promise or describe unimplemented features + +### Requirement: Getting Started Guide +The README.md SHALL include instructions for contributors to get started with development. + +#### Scenario: New contributor onboarding +- **WHEN** a new contributor wants to start developing +- **THEN** README.md provides clear setup steps +- **AND** explains the OpenSpec-based workflow + +### Requirement: OpenSpec Reference +The README.md SHALL reference the OpenSpec documentation structure for detailed specifications. + +#### Scenario: Finding detailed specs +- **WHEN** a developer needs detailed technical specifications +- **THEN** README.md directs them to the `openspec/` directory +- **AND** explains how to read and create proposals diff --git a/openspec/changes/add-initial-readme/tasks.md b/openspec/changes/add-initial-readme/tasks.md new file mode 100644 index 0000000..dc4c51a --- /dev/null +++ b/openspec/changes/add-initial-readme/tasks.md @@ -0,0 +1,13 @@ +# Implementation Tasks + +## 1. Documentation +- [x] 1.1 Draft README.md content reflecting current project state +- [x] 1.2 Include project overview and purpose +- [x] 1.3 Document OpenSpec workflow for contributors +- [x] 1.4 Add getting started section for contributors +- [x] 1.5 Include license and contact information +- [x] 1.6 Review README.md for accuracy against project.md + +## 2. Validation +- [x] 2.1 Verify OpenSpec validation passes +- [x] 2.2 Ensure README.md aligns with openspec/project.md conventions