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>
This commit is contained in:
Claude
@@ -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)
|
||||
@@ -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
|
||||
@@ -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
|
||||
@@ -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
|
||||
Reference in New Issue
Block a user