CCMA/README.md

CCMA - Chaotic Creature Member Administration

File-based member administration for Chaos Computer Club Mannheim e.V.

The member store remains readable without this application. Every member has a directory containing member.json, contributions.json, an append-only events.jsonl, and a files/ directory.

Development

Requires Python 3.11+ with Tk support.

python -m venv .venv
.venv/bin/pip install -r requirements.txt
.venv/bin/ccma

For development tools and tests, install the dev extra as well:

.venv/bin/pip install -e '.[dev]'

Alternatively, without installation:

PYTHONPATH=src python -m ccma

On first start, select or create the central member-store directory. The VERSION file is the single source for application and package versions.

Store layout

member-store/
├── repository.json
├── hausmeister.json
├── rules/
└── members/
    └── <uuid>/
        ├── member.json
        ├── contributions.json
        ├── events.jsonl
        └── files/

Housekeeper rules

The housekeeper runs every rule for every member. Built-in Python rules live in ccma/rules/scripts/. A member store can add rules in its rules/ directory. If a store rule has the same filename as a built-in rule, the store version replaces the built-in version.

Store rules are trusted executable Python code. Only place reviewed rules from trusted sources in this directory. Rules return structured RuleAction objects; CCMA performs all file writes, duplicate checks, audit events, and atomic updates.

hausmeister.json is written only after a complete run. Each refreshed task gets the pending run ID. A failed run therefore cannot advance the stored counter or silently resolve existing tasks.

Claims and payments

Claims are stored in the member's contributions.json. A claim consists of signed line items; fees increase and credits reduce its total. Payments remain separate records and allocations connect one payment to one or more claims. This supports partial payments, shared annual payments, unallocated credit, and optional GnuCash transaction IDs without duplicating a bank transaction.

Claim status and outstanding balance are derived from line items and payment allocations. Reminders are separate processes and only change the amount when they explicitly add a fee line item. Every change is also appended to the member's events.jsonl audit trail.

Do not place a real member store inside the source repository.