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

It serves a bundled web frontend and a native Android client, and also speaks the Model Context Protocol for assistant clients.

The service is built using:

• Connect RPC (gRPC-compatible protocol)
• Protocol Buffers for API definitions
• SQLite by default, PostgreSQL optional for data persistence, selected by EAG_DB_DRIVER (see ADR-0021)
• 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, and web/android i18n checks

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

Configuration is read via viper with the EAG_ prefix, so a db-driver flag maps to the EAG_DB_DRIVER environment variable. The database ones:

Variable	Default	Description
EAG_DB_DRIVER	sqlite	Storage engine (sqlite or postgres)
EAG_DB_PATH	eagraiclainne.db	SQLite database file (driver sqlite)
EAG_DB_HOST	localhost	Database host (driver postgres)
EAG_DB_PORT	5432	Database port (driver postgres)
EAG_DB_USER	postgres	Database user (driver postgres)
EAG_DB_PASSWORD	(empty)	Database password (driver postgres)
EAG_DB_NAME	eagraiclainne	Database name (driver postgres)
EAG_DB_SSLMODE	disable	SSL mode (driver postgres)

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
• ItemListService: Grouping of items into lists
• RewardService: Reward creation, claiming, user reward tracking
• MealService / MealRotaService: Meal planning and the cooking rota
• ApiKeyService: Admin-managed machine credentials (API keys)
• SystemService: Data export, import and restore
• WebhookService: Outbound signed event deliveries

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, Child, 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 (PostgreSQL) and internal/database/schema_sqlite.sql (SQLite), applied on boot, 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

See CONTRIBUTING.md for how to get access, build, commit, and submit a change. In short: follow the project conventions, write tests for new functionality, record an ADR for significant architectural changes, and make sure make check passes before submitting.

License

See LICENSE file for details.