# 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.

```bash
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:

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

Alternatively, without installation:

```bash
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.

The splash screen remains visible for at least five seconds by default. This
advanced setting is intentionally not exposed in the options dialog. It can be
changed directly in `config.json`, including disabling the minimum with `0`:

```json
"splash_minimum_seconds": 0
```

## Store layout

```text
member-store/
├── repository.json
├── housekeeper.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.

`housekeeper.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.

Overdue claims are evaluated by the reminder rule. It creates housekeeper tasks
for the next configured reminder level. Reminder drafts do not change a claim;
only confirming actual dispatch starts the new payment deadline and adds an
optional fee line item. A claim-level dunning hold suppresses automatic and
manual reminder preparation until it is removed or expires.

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