Eagraí Clainne

Family Organization System - A gRPC-based application for organizing family activities, events, items, and rewards.

Overview

Eagraí Clainne is a Go-based backend service that provides APIs for managing family organization tasks including:

• User Management: Create and manage family member accounts with authentication
• Events: Schedule and coordinate family events with participant tracking
• Items: Track family items and assign them to users with deadlines
• Rewards: Create reward systems and allow users to claim rewards

The service is built using:

• Connect RPC (gRPC-compatible protocol)
• Protocol Buffers for API definitions
• PostgreSQL for data persistence
• JWT authentication with role-based access control (RBAC)

Client Library

A Go client library is available in pkg/client/ for building CLI tools and applications:

import "eagraiclainne.ie/pkg/client"

c, _ := client.New("http://localhost:8080", nil)
loginResp, _ := c.Users.Login(ctx, "user@example.com", "password")
c.SetAuthToken(loginResp.Token)
event, _ := c.Events.Create(ctx, &client.CreateEventParams{...})

See pkg/client/README.md for full documentation and examples.

Architecture

The project follows a clean architecture with clear separation of concerns:

cmd/server/          - Server entry point and configuration
internal/
  auth/              - Authentication, JWT handling, RBAC, and interceptors
  database/          - Database abstraction layer with generic table operations
  services/          - Business logic for each domain (user, event, item, reward)
proto/api/core/v1/   - Protocol Buffer API definitions
gen/go/api/core/v1/  - Generated Go code from Protocol Buffers

Development Setup

📖 For detailed local development instructions, see LOCAL_DEVELOPMENT.md

Quick Start

Local development runs on a kind cluster (see deploy/README.md):

# One-time: bootstrap the kind cluster + local registry
make cluster-up

# Build the image and deploy database, observability and app
make deploy

# Fresh database only: seed a family to log in with
make seed-family

The app is then available at http://localhost:8080.

Before committing, run:

make check   # fmt, vet, lint, test

Alternative: Using Devbox

This project also supports devbox for reproducible development environments:

# Install devbox
curl -fsSL https://get.jetpack.io/devbox | bash

# Enter devbox shell
devbox shell

# Follow the Quick Start steps above

Development Commands

Building

go build ./...                                    # Build all packages
go build -o ./bin/server ./cmd/server            # Build server executable

Testing

go test ./...                                     # Run all tests
go test -v ./internal/database/ -run TestName    # Run specific test

Code Quality

go fmt ./...           # Format code
go vet ./...           # Vet code for errors
golangci-lint run      # Run linter

Protocol Buffers

buf generate           # Generate Go code from .proto files
buf lint               # Lint protocol buffer definitions

Environment Variables

Variable	Default	Description
DB_HOST	localhost	PostgreSQL host
DB_PORT	5432	PostgreSQL port
DB_USER	postgres	Database user
DB_PASSWORD	(empty)	Database password
DB_NAME	Eagraí Clainne	Database name
DB_SSLMODE	disable	SSL mode for database connection

API Services

The following Connect RPC services are available:

• UserService: User registration, login, profile management
• EventService: Event creation, updates, user participation
• ItemService: Item tracking, user assignment, deadline management
• RewardService: Reward creation, claiming, user reward tracking
• ApiKeyService: Admin-managed machine credentials (API keys)

MCP Endpoint

The server speaks the Model Context Protocol at /mcp (streamable HTTP), so Claude and other MCP clients can work the family data with the tools list_items, add_item, complete_item, list_events and add_event. Authenticate with an API key (mint one in the web Admin → Keys panel, or with eagraiclainne apikey create):

claude mcp add eagraiclainne --transport http http://localhost:8080/mcp \
  --header "Authorization: Bearer <api-key-token>"

A personal key acts as one member. A standalone key (for a shared device such as Home Assistant) names who actually acted per call via acting_user, honoured only against its admin-set allowlist. See ADR-0016.

Authentication & Authorization

The service implements JWT-based authentication with RBAC:

• Users authenticate via the Login RPC
• JWT tokens are required for most operations (via Authorization header)
• Roles determine access permissions (Admin, Member, Guest)
• Admin-managed API keys serve machine clients; the key record is the authority (per-key revocation, acting-user allowlists) — see ADR-0016
• See ADR-0007, ADR-0008, and ADR-0009 for details

ADR Process

For significant changes, we record Architecture Decision Records (ADRs). ADRs document design decisions and their rationale for:

• New authentication/authorization systems
• Database schema changes
• New API services or significant endpoint additions
• Major refactoring affecting multiple packages
• Changes to core architecture or design patterns

ADRs are stored in docs/adr/<nnnn>-<topic>.md and should include sections for context, decision, consequences, and alternatives considered. Existing ADRs are in docs/adr/.

Database Schema

The database schema is defined in internal/database/schema.sql and includes tables for:

• Users and authentication
• Events and event participants
• Items and item assignments
• Rewards and reward claims

The database layer provides generic, type-safe operations using Go generics.

Contributing

1. Follow Go best practices and project conventions
2. Write tests for new functionality
3. Record an ADR for significant architectural changes
4. Ensure all tests pass and linting is clean before submitting

License

See LICENSE file for details.