Documentation

This directory contains comprehensive documentation for the Requests and Offers application.

Overview

• Quick Reference Guide - Essential commands, patterns, and workflows ⭐
• Project Overview - High-level introduction to the project
• Requirements - Project requirements and specifications
• Architecture - System architecture and design
• Technical Specifications - Detailed technical specifications
• Troubleshooting Guide - Common issues and solutions 🔧
• Work In Progress - Current development status
• Status - Project roadmap and milestone tracking

Technical Documentation

UI Architecture

• UI Structure - Overview of UI architecture
• Component Library - Component inventory and usage
• State Management - Svelte stores with Effect TS
• Services Layer - Backend communication
• UI Types and Schemas - Type system and validation
• Event Bus Pattern - Event-based communication

Backend Architecture

• Zome Details - Holochain zome implementation
• hREA Integration - Resource-Event-Agent integration

Development Guides

• Getting Started - First steps for new developers
• Installation - Setup instructions
• Contributing - Contribution guidelines

Project Overview

Introduction

The Requests and Offers project is a Holochain application (hApp) designed for the hAppenings.community. It facilitates connections within the Holochain ecosystem by providing a simplified bulletin board where users can:

• Post Requests for services, skills, or resources they need
• Create Offers to provide services, skills, or resources they can share
• Discover opportunities through search and tagging systems
• Connect directly through clearly displayed contact information

Key Features (Simplified MVP)

Service Types & Tag-Based Discovery System

• Dynamic Service Type Management: DHT-based service type entries with admin validation workflow
• Tag-Based Discovery: Comprehensive tagging system enabling efficient search across requests, offers, and service types
• Cross-Entity Discovery: Find related content through tag navigation (service types → requests/offers)
• Admin Moderation: Full approval/rejection workflow for user-suggested service types
• Autocomplete & Statistics: Real-time tag suggestions and usage analytics

Request Management

• Create detailed requests specifying what you need with service type integration
• Set preferences for communication, timing, and exchange type
• Link requests to service types for better categorization and discovery
• Tag-based filtering and search capabilities

Offer Management

• Create comprehensive offers detailing what you can provide with service type integration
• Specify availability, skills, and interaction preferences
• Connect offers to service types for improved discoverability
• Tag-based filtering and search capabilities

User & Organization Profiles

• Individual user profiles with skills and preferences
• Organization/project management with team coordination
• Multi-device access and profile synchronization

Listing Management

• Archive your own requests/offers when fulfilled or no longer relevant
• Delete your own requests/offers permanently
• View all your listings in a personal dashboard

Administrative Tools

• Admin interface for approving/rejecting service type suggestions
• User verification and role management
• Content moderation capabilities
• Tag analytics and management dashboards

Technology Stack

Backend (Holochain)

• Distributed Hash Table (DHT): Peer-to-peer data storage and retrieval
• Zome Architecture: Modular coordinator/integrity pattern
  • requests_coordinator: Request management and lifecycle
  • offers_coordinator: Offer management and lifecycle
  • service_types_coordinator: Service type management with tag indexing
  • users_organizations: Profile and organization management
  • administration: Admin roles and verification
• Cross-Zome Integration: Seamless data flow between different functional areas
• Tag-Based Indexing: Efficient path anchor system for discovery and search

Frontend (SvelteKit + Effect TS)

• SvelteKit: Modern web framework with server-side rendering
• Svelte 5 Runes: Reactive state management ($state, $derived, $effect)
• Effect TS: Functional programming patterns for robust async operations and error handling
• TailwindCSS + SkeletonUI: Modern, responsive design system

Development Environment

• Nix: Reproducible development environment (for DNA/zome development)
• Bun: Fast JavaScript runtime and package manager (for frontend)
• Sweettest: Holochain testing framework (backend tests, Rust in-process harness)
• Vitest: Modern testing framework (frontend tests)

Architecture Patterns

Effect Service Pattern

All zome interactions use Effect TS for:

• Type-safe error handling: Domain-specific error types with proper context
• Composable async operations: Clean composition of complex workflows
• Dependency injection: Clean separation of concerns through Context Tags
• Robust state management: Integration with Svelte stores for reactive UX

Reactive State Management

• Svelte Stores: Feature-specific stores using Svelte 5 Runes
• Entity Caching: In-memory caching with expiration and invalidation
• Event Bus: Cross-store communication for coordinated state updates
• Tag-Based Reactivity: Dynamic updates based on tag selections and filtering

Component Organization

• Feature-based structure: Components organized by domain (requests, offers, service-types, tags)
• Reusable components: Shared UI elements with consistent patterns
• Accessibility-first: WCAG-compliant interfaces with keyboard navigation
• Mobile-responsive: Adaptive design for all device sizes

User Experience (Simplified MVP)

For Regular Users

1. Browse and Discover: Use search and tag-based navigation to find relevant requests and offers
2. Create Content: Post requests or offers with service type categorization
3. Connect Directly: View contact information and communicate outside the platform
4. Manage Listings: Archive or delete your own requests/offers

For Administrators

1. Moderate Content: Review and approve/reject user-suggested service types
2. Manage Users: Verify accounts and manage roles
3. Analytics: View tag usage statistics and platform activity
4. System Health: Monitor performance and resolve issues

Current Implementation Status

Completed Features

• Service Types System: Complete implementation with validation workflow
• Tag-Based Discovery: Full cross-entity discovery and navigation
• Request/Offer Management: Complete CRUD operations with service type integration
• User/Organization Profiles: Basic profile management
• Admin Interface: Complete moderation and management tools
• Testing Infrastructure: Comprehensive test coverage (backend and frontend)

Simplified MVP Features (In Development)

• Archive/delete functionality for user listings
• Contact information display components
• Simplified navigation and user dashboard
• Documentation updates for simplified approach

Post-MVP Features (Planned)

• Exchange coordination system (proposals, agreements, reviews)
• In-app messaging system
• Advanced analytics and reporting
• Enhanced user dashboard features
• hREA economic resource integration
• Mobile application
• Advanced recommendation algorithms
• Reputation and rating systems

Getting Started

Prerequisites

• Nix (for Holochain development)
• Bun (for frontend development)
• Git

Quick Start

# Clone the repository
git clone https://github.com/hAppening-Community/requests-and-offers.git
cd requests-and-offers

# Enter Nix development environment (for backend)
nix develop

# Install frontend dependencies
cd ui && bun install

# Run development servers
bun run dev

Testing

# Run backend tests
bun run test:backend

# Run frontend tests
bun run test:unit
bun run test:integration

Contributing

We welcome contributions! Please see our contributing guidelines and feel free to:

• Report bugs and suggest features
• Contribute code improvements
• Help with documentation
• Test new features and provide feedback

Community

• GitHub: hAppening-Community/requests-and-offers
• Community: hAppenings.community
• Discord: Join our Discord

Architecture Overview

This document provides a high-level overview of the system architecture, including design patterns, key technical decisions, and component relationships.

Key Sections

• General Overview: System structure and design principles.
• hREA Integration: Details on integrating with the hREA framework.

🏆 Unified Effect TS Architecture

Domain-by-Domain Standardization Approach

The application follows a 7-Layer Standardization Pattern achieved through iterative, domain-driven refactoring. This architectural evolution represents a major milestone in creating a consistent, maintainable, and type-safe codebase.

Implementation Status:

1. ✅ Service Types Domain: FULLY COMPLETED (100%) - Complete pattern template established
2. ✅ Requests Domain: FULLY COMPLETED (100%) - Patterns successfully replicated
3. ✅ Offers Domain: FULLY COMPLETED (100%) - All 7 layers standardized
4. ✅ Users Domain: FULLY COMPLETED (100%) - Effect-TS standardization complete
5. ✅ Organizations Domain: FULLY COMPLETED (100%) - Effect-TS standardization complete
6. ✅ Administration Domain: FULLY COMPLETED (100%) - Effect-TS standardization complete
7. ✅ Exchanges Domain: FULLY COMPLETED (100%) - Complete Effect-TS implementation with all layers
8. ✅ Mediums of Exchange Domain: FULLY COMPLETED (100%) - Effect-TS standardized with store helpers

The 7-Layer Architecture Pattern

Each domain follows this standardized structure, ensuring consistency and maintainability across the entire application:

1. Service Layer (Effect-Native)

• Pattern: Pure Effect services with Context.Tag dependency injection
• Error Handling: Domain-specific tagged errors (DomainError)
• Schema Strategy: callZomeRawEffect for Holochain data, callZomeEffect for business logic
• Dependency Management: Clean separation through Effect Layer pattern
• Example: serviceTypes.service.ts (fully standardized template)

2. Store Layer (Svelte + Effect Integration)

• Pattern: Factory functions returning Effects with Svelte 5 Runes
• Structure: 9 standardized helper functions for massive code reduction:
  • createUIEntity() - Entity creation from Holochain records
  • mapRecordsToUIEntities() - Consistent record mapping
  • createCacheSyncHelper() - Cache-to-state synchronization
  • createEventEmitters() - Standardized event emission
  • createEntitiesFetcher() - Data fetching with state updates
  • withLoadingState() - Loading state management
  • createRecordCreationHelper() - Record creation patterns
  • createStatusTransitionHelper() - Status transitions
  • processMultipleRecordCollections() - Complex data processing
• State Management: $state, $derived, $effect with EntityCache integration
• Event Integration: Standardized EventBus patterns for cross-store communication

3. Schema Validation (Effect Schema)

• Strategy: Strategic validation boundaries (input validation, business logic, UI transformations)
• Types: Branded types for domain safety (ActionHash, ServiceTypeName)
• Classes: Schema.Class for complex entities (UIServiceType)
• Validation Points: Input forms, API boundaries, cross-service communication

4. Error Handling (Centralized Tagged Errors)

• Pattern: Domain-specific error hierarchies (Service → Store → Composable)
• Context: Meaningful error contexts and recovery patterns
• Export: Centralized through ui/src/lib/errors/index.ts
• User Experience: Consistent error messaging and fallback handling

5. Composables Layer (Component Logic Abstraction)

• Pattern: Extract complex component logic into reusable Effect-based functions
• Integration: Bridge Svelte components with Effect stores/services
• Interface: Standard state/actions separation with typed interfaces
• Benefits: Prevent infinite reactive loops, enhance testability

6. Components Layer (Svelte 5 + Accessibility)

• Integration: Use composables for business logic, focus on presentation
• Reactivity: Svelte 5 Runes with proper reactive patterns
• Accessibility: WCAG-compliant with keyboard navigation
• Performance: Optimized with $derived.by and proper effect management

7. Testing Layer (Comprehensive Effect TS Coverage)

• Backend: Sweettest multi-agent testing
• Unit: Effect TS testing utilities with service isolation
• Integration: End-to-end workflow validation
• Pattern: Domain-specific testing strategies for all layers

Core Data Flow

The application follows a refined data and control flow leveraging Effect TS patterns for maximum type safety and maintainability:

1. Rust Zomes (Holochain Backend): Execute core business logic and manage data persistence on the DHT.

2. Effect Services (ui/src/lib/services):

   • Pure Effect-native services with Context.Tag dependency injection
   • Strategic schema validation at business boundaries
   • Domain-specific error handling with tagged errors
   • Composable async operations with robust error propagation

3. Svelte Stores (ui/src/lib/stores):

   • Factory function pattern creating Effect-based stores
   • Standardized helper functions (9 core patterns) for code reduction
   • Reactive state management using Svelte 5 Runes ($state, $derived, $effect)
   • Event Bus integration for cross-store communication
   • EntityCache patterns for performance optimization

4. Composables (ui/src/lib/composables):

   • Component Logic Abstraction Layer extracting complex logic
   • Effect integration for all async operations
   • Standard interfaces with state/actions separation

5. Svelte UI Components (ui/src/lib/components):

   • Use composables for business logic and state management
   • Focus on presentation and user interaction
   • Svelte 5 patterns with proper reactive design

Architectural Benefits

• Type Safety: Comprehensive Effect dependency resolution and error handling
• Code Quality: Massive reduction in duplication through standardized patterns
• Maintainability: Consistent structure across all domains
• Performance: Optimized patterns with caching and lazy initialization
• Testing: Robust testing strategies for all layers
• Developer Experience: Clear patterns and comprehensive documentation
• Scalability: Template-based approach for new domain addition

Pattern Documentation

The architecture is supported by comprehensive pattern documentation:

• Service Effect Patterns: Complete Effect TS service implementation
• Store Effect Patterns: Standardized store structure with helpers
• Error Management Patterns: Centralized error handling
• Schema Patterns: Strategic validation strategies
• Testing Strategy: Comprehensive testing approach

Implementation Timeline

Completed ✅ - MAJOR MILESTONE ACHIEVED

• All 8 Domains Fully Standardized: Complete 7-layer Effect-TS architecture implementation
  • Service Types Domain: Template and foundation (100%)
  • Requests Domain: Complete standardization (100%)
  • Offers Domain: Complete standardization (100%)
  • Users Domain: Complete Effect-TS conversion (100%)
  • Organizations Domain: Complete Effect-TS conversion (100%)
  • Administration Domain: Complete Effect-TS conversion (100%)
  • Exchanges Domain: Complete implementation with all layers (100%)
  • Mediums of Exchange Domain: Complete Effect-TS standardization (100%)
• Pattern Documentation: Comprehensive rule files for consistent development
• Foundation Architecture: Complete Effect TS infrastructure and utilities
• Testing Infrastructure: All 343 unit tests passing across 20 test files with standardized mocks

Current Focus 🎯

• Documentation Enhancement: Updating all documentation to reflect completed architecture
• Pattern Refinement: Continuous improvement of established patterns
• Architecture Maintenance: Ensuring consistency across all domains

Future Enhancements 📋

• Performance Optimization: Leverage standardized patterns for enhanced performance
• Advanced Features: Exchange completion workflows and advanced hREA integration
• UI/UX Improvements: Standardize UI components and composables for consistency
• Holo deployment: Deploy to holo legacy network

This layered approach ensures separation of concerns, leverages Effect TS for robust service logic, and maintains Svelte Runes for efficient UI reactivity while providing a consistent, maintainable codebase across all domains.

Architecture Diagrams

1. 7-Layer Effect-TS Architecture Pattern

graph TD
    subgraph "HOLOCHAIN BACKEND"
        HC[Holochain Zomes<br/>Rust Backend<br/>DHT Storage]
    end

    subgraph "EFFECT TS ARCHITECTURE - 7 LAYER PATTERN"
        subgraph "LAYER 1: SERVICE LAYER"
            SL[Effect-Native Services<br/>Context.Tag Dependency Injection<br/>Domain-Specific Tagged Errors<br/>Strategic Schema Validation]
        end

        subgraph "LAYER 2: STORE LAYER"
            ST[Factory Function Pattern<br/>9 Standardized Helper Functions<br/>Svelte 5 Runes Integration<br/>EntityCache + EventBus]
        end

        subgraph "LAYER 3: SCHEMA VALIDATION"
            SC[Effect Schema<br/>Strategic Validation Boundaries<br/>Branded Types<br/>Schema.Class for Complex Entities]
        end

        subgraph "LAYER 4: ERROR HANDLING"
            EH[Centralized Tagged Errors<br/>Domain-Specific Hierarchies<br/>Meaningful Error Contexts<br/>Recovery Patterns]
        end

        subgraph "LAYER 5: COMPOSABLES"
            CO[Component Logic Abstraction<br/>Effect-Based Functions<br/>Bridge Components with Stores<br/>State/Actions Separation]
        end

        subgraph "LAYER 6: COMPONENTS"
            CM[Svelte 5 + Accessibility<br/>Use Composables for Logic<br/>Focus on Presentation<br/>WCAG Compliant]
        end

        subgraph "LAYER 7: TESTING"
            TE[Comprehensive Effect TS Coverage<br/>Backend Sweettest Testing<br/>Unit Testing with Isolation<br/>Integration Workflow Validation]
        end
    end

    %% Layer Flow Connections
    HC --> SL
    SL --> ST
    ST --> SC
    SC --> EH
    EH --> CO
    CO --> CM
    CM --> TE

2. Data Flow Architecture

graph TD
    subgraph "CORE DATA FLOW"
        DF1[Holochain Backend<br/>Business Logic + DHT Persistence]
        DF2[Effect Services<br/>Pure Effect-Native + Dependency Injection]
        DF3[Svelte Stores<br/>Factory Pattern + 9 Helper Functions]
        DF4[Composables<br/>Component Logic Abstraction]
        DF5[Svelte Components<br/>Presentation + User Interaction]
    end

    subgraph "PATTERN DOCUMENTATION SUPPORT"
        DOC1[Service Effect Patterns]
        DOC2[Store Effect Patterns]
        DOC3[Error Management Patterns]
        DOC4[Schema Patterns]
        DOC5[Testing Strategy]
    end

    %% Data Flow Chain
    DF1 --> DF2
    DF2 --> DF3
    DF3 --> DF4
    DF4 --> DF5

    %% Documentation Support
    DOC1 -.-> DF2
    DOC2 -.-> DF3
    DOC3 -.-> DF2
    DOC4 -.-> DF2
    DOC5 -.-> DF5

Project Status

This document reflects the current implementation state as of v0.5.2 (2026-04-30). For full change history, see CHANGELOG.md.

Current Phase: Alpha Testing — Core MVP features are live; active bug triage underway from alpha user feedback.

What's Working

Architecture — Unified Effect-TS (All 8 Domains)

All domains are fully standardized with the 7-layer Effect-TS architecture: Service Types, Requests, Offers, Users, Organizations, Administration, Exchanges, Mediums of Exchange

Pattern established: Context.Tag services → Effect-native stores → Schema.Class validation → Data.TaggedError error handling → composables → Svelte 5 components.

Core Infrastructure

Holochain Backend (Rust):

• All 7 coordinator + integrity zome pairs in place
• Progenitor pattern — secure designated network creator for trusted bootstrapping
• Action hash type safety — compile-time distinct types preventing hash kind confusion
• Active/Archived/Deleted listing status management across requests and offers
• Sweettest integration tests (37 tests, all passing — replaced Tryorama in v0.5.0)

Frontend (SvelteKit + Effect-TS):

• Svelte 5 Runes ($state, $derived, $effect) throughout
• All 8 domain stores fully Effect-TS based
• EntityCache pattern for in-memory caching
• Event Bus system (storeEvents.ts) for cross-store communication
• Weave/Moss integration — runs as a Weave Tool with hybrid profile display
• Markdown rendering for descriptions and bios
• Search and filtering across organizations, requests, and offers
• Active/Archived listing tabs with status management UI
• Contact information display components
• Organization contact person designation (coordinator with role/title)
• Navigation: Profile section with edit access
• Alt+A keybinding for contextual admin/public page navigation

Documentation:

• mdBook-based documentation site with GitHub Pages deployment
• Developer guide system: getting-started, development-workflow, effect-ts-primer, architectural-patterns, domain-implementation

Testing Infrastructure

Active Bugs

Bugs from alpha testing, ordered by priority. See the project board for live status.

P1 — Critical

P2 — High

In Progress

Ready for Development

Items prioritized and ready to implement:

Tests and Documentation Needed

Implemented but missing tests or documentation:

Remaining MVP Features

Large features deferred to upcoming milestones.

Post-MVP (Deferred)

• Internationalization: Multi-language support
• Mobile App: Native mobile wrapper
• Advanced recommendation/matching algorithms
• Geographic Features (#54): Offline experience and local connections
• Holo Hosting Deployment (#14)
• Skeleton UI v3 / Tailwind CSS v4 upgrade (#35)
• Breaking-version migration system (#144)

Quick Reference Guide

Essential commands, patterns, and workflows for efficient development in the Requests and Offers project.

🚀 Getting Started

Initial Setup

# Clone with submodules and enter project
git clone --recurse-submodules https://github.com/happening-community/requests-and-offers.git
cd requests-and-offers

# Setup environment
nix develop                    # Enter Nix shell (required for zomes)
bun install                    # Install dependencies
git submodule update --init --recursive  # Initialize submodules
bun start                      # Start development (2 agents)

Development Commands

# Development servers
bun start                      # 2 agents (default)
AGENTS=3 bun start            # Custom number of agents
bun start:test                # Test mode (dev features, no mock buttons)
bun start:prod                # Production mode (all dev features disabled)

# Building
bun build:zomes               # Build Rust zomes
bun build:happ                # Build complete hApp
bun package                   # Package for distribution

# Testing
bun test                      # All tests
bun test:ui                   # Frontend tests only
bun test:unit                 # Unit tests (requires Nix)
nix develop --command bun test:unit  # Autonomous unit test execution
bun test:integration          # Integration tests
nix develop --command cargo test --manifest-path tests/sweettest/Cargo.toml  # Backend Sweettest tests

# Code quality
cd ui && bun run lint         # Lint frontend code
cd ui && bun run format       # Format frontend code
cd ui && bun run check        # TypeScript check

# Submodule management
git submodule update --remote kangaroo-electron    # Update desktop app
git submodule update --remote homebrew               # Update homebrew formula
cd deployment/kangaroo-electron && npm run tauri dev   # Desktop app development
cd deployment/kangaroo-electron && npm run tauri build  # Build desktop app

# Deployment automation
./deployment/scripts/deploy.sh deploy 0.1.X          # Full deployment
./deployment/scripts/deploy.sh status               # Check deployment status

🏗️ Architecture Quick Reference

7-Layer Effect-TS Architecture

1. Service Layer      → Effect-native services with Context.Tag DI
2. Store Layer        → Svelte 5 Runes + Effect integration
3. Schema Validation  → Effect Schema at business boundaries
4. Error Handling     → Domain-specific tagged errors
5. Composables        → Component logic abstraction
6. Components         → Svelte 5 + accessibility focus
7. Testing            → Comprehensive Effect-TS coverage

Project Structure

requests-and-offers/
├── dnas/requests_and_offers/     # Holochain DNA
│   └── zomes/                    # Coordinator & integrity zomes
├── ui/                           # SvelteKit frontend
│   ├── src/lib/
│   │   ├── components/           # Feature-organized components
│   │   ├── services/             # Effect-TS services
│   │   ├── stores/               # Svelte stores with Effect
│   │   ├── composables/          # Business logic abstraction
│   │   ├── schemas/              # Effect Schema validation
│   │   └── errors/               # Tagged error definitions
│   └── src/routes/               # SvelteKit pages
├── deployment/                   # Deployment repositories as submodules
│   ├── kangaroo-electron/        # Desktop app (Tauri) submodule
│   ├── homebrew/                 # Homebrew formula submodule
│   └── scripts/                  # Deployment automation scripts
├── tests/sweettest/              # Sweettest integration tests (Rust)
└── documentation/                # Comprehensive docs

💻 Development Patterns

Effect-TS Service Pattern

// Service definition with dependency injection
export const MyService = Context.GenericTag<MyService>("MyService");

export const makeMyService = Effect.gen(function* () {
  const client = yield* HolochainClientService;

  const createEntity = (input: CreateInput) =>
    Effect.gen(function* () {
      const validated = yield* Schema.decodeUnknown(InputSchema)(input);
      const result = yield* client.callZome({
        zome_name: "my_zome",
        fn_name: "create_entity",
        payload: validated,
      });
      return yield* Schema.decodeUnknown(EntitySchema)(result);
    }).pipe(Effect.mapError((error) => new MyDomainError({ cause: error })));

  return { createEntity };
});

Svelte Store Pattern

// Store factory with Svelte 5 Runes + Effect
export const createEntitiesStore = () => {
  let entities = $state<UIEntity[]>([]);
  let loading = $state(false);
  let error = $state<string | null>(null);

  const service = yield * MyService;

  const fetchAll = Effect.gen(function* () {
    loading = true;
    error = null;
    try {
      const records = yield* service.getAllEntities();
      entities = mapRecordsToUIEntities(records);
    } catch (err) {
      error = err.message;
    } finally {
      loading = false;
    }
  });

  return {
    entities: () => entities,
    loading: () => loading,
    fetchAll,
  };
};

Component Pattern

<script lang="ts">
  // Props with defaults
  const {
    data = [],
    loading = false,
    onAction = () => {}
  }: ComponentProps = $props();

  // Reactive state
  let localState = $state({ filter: '' });

  // Derived values
  const filteredData = $derived(
    data.filter(item => item.name.includes(localState.filter))
  );

  // Composable for business logic
  const entityManager = useEntityManager();
</script>

<div role="main" aria-label="Entity list">
  <!-- Accessible markup -->
</div>

🧪 Testing Patterns

Backend Testing (Sweettest)

#![allow(unused)]
fn main() {
#[tokio::test(flavor = "multi_thread")]
async fn test_entity_creation() {
    let (conductors, alice, bob) = setup_two_agents_with_alice_as_progenitor().await;

    conductors[0]
        .call::<_, Record>(&alice.zome("users_organizations"), "create_user", sample_user("Alice"))
        .await;

    await_consistency(15, [&alice, &bob]).await.unwrap();

    let record: Record = conductors[0]
        .call(&alice.zome("coordinator"), "create_entity", sample_entity("Test Entity"))
        .await;

    assert!(!record.signed_action.hashed.hash.get_raw_39().is_empty());
}
}

Frontend Testing (Vitest)

describe("EntityService", () => {
  it("should create entity successfully", async () => {
    const program = Effect.gen(function* () {
      const service = yield* EntityService;
      return yield* service.createEntity(testInput);
    });

    const result = await Effect.runPromise(
      program.pipe(Effect.provide(TestServiceLayer)),
    );

    expect(result.name).toBe("Test Entity");
  });
});

🔧 Common Workflows

Adding a New Domain

1. Backend: Create coordinator & integrity zomes
2. Service: Implement Effect-TS service with Context.Tag
3. Store: Create store with 9 standardized helper functions
4. Composable: Extract business logic
5. Components: Build UI with accessibility focus
6. Errors: Define domain-specific tagged errors
7. Tests: Add backend (Sweettest) + frontend (Vitest) tests

Domain Implementation Checklist

• Zome implemented (coordinator/integrity pattern)
• Service layer with Effect-TS and dependency injection
• Store layer with all 9 helper functions
• Composable layer for business logic abstraction
• Component layer using composables
• Error handling with domain-specific errors
• Tests covering all layers
• Documentation updated

The 9 Standardized Store Helper Functions

1. Entity Creation Helper - Converts records to UI entities
2. Record Mapping Helper - Maps arrays with error recovery
3. Cache Sync Helper - Synchronizes cache with state arrays
4. Event Emission Helpers - Standardized event broadcasting
5. Data Fetching Helper - Higher-order fetching with loading states
6. Loading State Helper - Wraps operations with loading patterns
7. Record Creation Helper - Processes new records and updates cache
8. Status Transition Helper - Manages status changes atomically
9. Collection Processor - Handles complex multi-collection responses

🖥️ Desktop Application Development

Kangaroo Desktop App Workflow

# Desktop app development (in submodule)
cd deployment/kangaroo-electron
npm run tauri dev                    # Start desktop app in dev mode

# Build desktop applications
npm run tauri build                  # Build for all platforms
npm run tauri build --target x64   # Build specific platform

# Update kangaroo submodule
git submodule update --remote kangaroo-electron
cd deployment/kangaroo-electron
npm install  # Install any new dependencies

Deployment Automation

# Full automated deployment (webapp + desktop + homebrew)
./deployment/scripts/deploy.sh deploy 0.1.0

# Dry run to preview actions
./deployment/scripts/deploy.sh deploy 0.1.0 --dry-run

# Check deployment status
./deployment/scripts/deploy.sh status

# Validate completed deployment
./deployment/scripts/deploy.sh validate 0.1.0

Platform-Specific Builds

The kangaroo desktop app supports:

• Windows: .exe installer with code signing
• macOS: DMG packages (Intel + Apple Silicon)
• Linux: AppImage and .deb packages

🔍 Troubleshooting

Common Issues

Unit tests failing with hREA errors:

nix develop --command bun test:unit  # Use autonomous execution

Port conflicts:

lsof -ti:8888 | xargs kill -9     # Kill process on port 8888
lsof -ti:4444 | xargs kill -9     # Kill process on port 4444

Nix environment issues:

nix develop --command which holochain  # Verify Nix tools
direnv allow                            # If using direnv

Zome build failures:

nix develop                    # Ensure in Nix shell
bun build:zomes               # Rebuild zomes

Development Features System

The project includes a comprehensive system for managing development-only features through atomic environment variable control:

Available Commands:

# Development Mode - Full Holochain app with atomic feature control
bun start              # Starts complete app (from project root)
AGENTS=3 bun start     # Custom number of agents

# UI Build Mode
cd ui && bun run build         # Production build

Atomic Feature Control:

// Service-based feature checking
import { DevFeaturesServiceTag } from '$lib/services/devFeatures.service';

const devFeatures = yield* DevFeaturesServiceTag;
if (devFeatures.mockButtonsEnabled) {
  // Show mock data button
}

// Convenience functions for components
import { shouldShowMockButtons } from '$lib/services/devFeatures.service';
{#if shouldShowMockButtons()}
  <button onclick={createMockData}>Create Mock Data</button>
{/if}

Environment Variables:

VITE_MOCK_BUTTONS_ENABLED=true|false          # Form mock buttons
VITE_PEERS_DISPLAY_ENABLED=true|false         # Network peers display

Benefits:

• Atomic Control: Each feature independently enabled/disabled
• Tree-Shaking: Development code completely removed from production builds
• Zero Overhead: Production builds contain no development features
• Runtime Configuration: Features controlled via .env file at runtime
• Developer Experience: Mock data buttons accelerate development workflow

See Development Features System for complete documentation.

📚 Key Documentation

Essential Reading

• 📋 Project Overview - Complete project introduction
• 🏗️ Architecture - System design and patterns
• 🔧 Developer Guide - Setup and workflow
• 📖 Full Documentation Index - Complete catalog

API References

• Frontend Services API
• Store Helpers API
• Backend Zome Functions
• Error Handling API

Development Guidelines

• Development Guidelines - Effect-TS and Svelte patterns
• Architecture Patterns - 7-layer architecture
• Testing Framework - Comprehensive testing strategy
• Domain Implementation - Domain patterns and utilities

🤝 Community

• Discord: Join our community
• Website: hAppenings.community
• Contributing: Contributing Guide
• Issues: GitHub Issues

💡 Pro Tip: Use Service Types domain as the implementation template - it's 100% complete and follows all established patterns.

⚠️ Important: Unit tests require Nix environment due to hREA integration. Always use nix develop --command bun test:unit for autonomous execution.

Comprehensive Codebase Documentation

Holochain Requests and Offers Project

📋 Executive Summary

The Holochain Requests and Offers project is a decentralized peer-to-peer platform built on Holochain technology, implementing a sophisticated 7-layer Effect-TS architecture with 100% standardized domain patterns. The application enables communities to manage service requests, offers, and economic exchanges using the hREA (Holochain Resource-Event-Agent) framework.

Key Architectural Achievements

• ✅ Service Types Domain: 100% standardized with 9 helper functions
• ✅ Requests Domain: 100% standardized Effect-TS implementation
• ✅ Offers Domain: 100% standardized with full helper function suite
• 🔄 Users/Organizations: In progress standardization
• 📊 343 Unit Tests: All passing across 20 test files with Effect-TS integration

🏗️ System Architecture Overview

Technology Stack

graph TB
    subgraph "Frontend Layer"
        A[SvelteKit 5 + Runes]
        B[TailwindCSS + SkeletonUI]
        C[Effect-TS Integration]
    end

    subgraph "Service Layer"
        D[7-Layer Effect Architecture]
        E[Context Dependency Injection]
        F[Schema Validation]
    end

    subgraph "Backend Layer"
        G[Holochain DNA]
        H[Rust Zomes]
        I[hREA Integration]
    end

    A --> D
    D --> G
    G --> I

Core Technologies

• Backend: Holochain v0.3+ with Rust zomes (coordinator/integrity pattern)
• Frontend: SvelteKit + Svelte 5 Runes + Effect-TS
• UI Framework: TailwindCSS + SkeletonUI
• State Management: Effect-TS + Svelte 5 Runes
• Runtime: Bun for TypeScript/JavaScript execution
• Economic Framework: hREA (Holochain Resource-Event-Agent)
• Desktop Apps: Tauri-based Kangaroo applications (Windows, macOS, Linux)
• Repository Management: Git submodules for unified development
• Development Environment: Nix shell (DNA/zome development only)

🎯 7-Layer Effect-TS Architecture

The codebase implements a revolutionary 7-layer architecture pattern using Effect-TS, providing unprecedented type safety, error handling, and maintainability.

Layer 1: Service Layer

// Effect-native services with Context.Tag dependency injection
export const ServiceTypeService =
  Context.GenericTag<ServiceTypeService>("ServiceTypeService");

export const makeServiceTypeService = Effect.gen(function* () {
  const client = yield* HolochainClientService;

  const createServiceType = (input: CreateServiceTypeInput) =>
    Effect.gen(function* () {
      // Business logic with comprehensive error handling
    });

  return { createServiceType };
});

Key Features:

• Context.Tag dependency injection
• Comprehensive error boundaries
• Automatic resource management
• Type-safe async operations

Layer 2: Store Layer

// Factory functions with Svelte 5 Runes + 9 standardized helper functions
export const createServiceTypesStore = () => {
  let entities = $state<UIServiceType[]>([]);

  const fetchEntities = Effect.gen(function* () {
    const records = yield* serviceTypeService.getAllServiceTypes();
    entities = mapRecordsToUIEntities(records); // Helper function #2
  });

  return { entities: () => entities, fetchEntities };
};

The 9 Standardized Helper Functions:

1. createUIEntity: Converts Holochain records to UI entities with error recovery
2. mapRecordsToUIEntities: Maps record arrays to UI entities with null safety
3. createCacheSyncHelper: Synchronizes cache with state arrays for CRUD operations
4. createEventEmitters: Standardized event broadcasting for domain operations
5. createEntityFetcher: Higher-order fetching with loading/error state management
6. withLoadingState: Wraps operations with consistent loading/error patterns
7. createRecordCreationHelper: Processes new records and updates cache atomically
8. createStatusTransitionHelper: Manages status changes with atomic updates
9. processMultipleRecordCollections: Handles complex responses with multiple collections

Layer 3: Schema Validation

// Effect Schema with strategic validation boundaries
export class ServiceTypeInDHT extends Schema.Class<ServiceTypeInDHT>(
  "ServiceTypeInDHT",
)({
  name: Schema.String.pipe(
    Schema.minLength(2),
    Schema.maxLength(100),
    Schema.annotations({
      title: "Service Type Name",
      description: "The name of the service type",
    }),
  ),
  description: Schema.String.pipe(Schema.minLength(10), Schema.maxLength(500)),
  tags: Schema.Array(
    Schema.String.pipe(Schema.minLength(1), Schema.maxLength(50)),
  ),
}) {}

Layer 4: Error Handling

// Domain-specific tagged errors with centralized management
export class ServiceTypeError extends Data.TaggedError("ServiceTypeError")<{
  readonly context: string;
  readonly message: string;
  readonly cause?: unknown;
}> {}

// Centralized error contexts
export const SERVICE_TYPE_CONTEXTS = {
  CREATE_SERVICE_TYPE: "Failed to create service type",
  GET_SERVICE_TYPE: "Failed to get service type",
  // ... comprehensive error scenarios
} as const;

Layer 5: Composables

// Component logic abstraction using Effect-based functions
export const useServiceTypeFormManagement = () => {
  const store = createServiceTypesStore();

  const handleSubmit = Effect.gen(function* () {
    // Abstract business logic from components
  });

  return { handleSubmit, isLoading, errors };
};

Layer 6: Components

<!-- Svelte 5 + accessibility focus, using composables for business logic -->
<script lang="ts">
  import { useServiceTypeFormManagement } from '$lib/composables';

  const { handleSubmit, isLoading } = useServiceTypeFormManagement();
</script>

Layer 7: Testing

// Comprehensive Effect-TS coverage across all layers
describe("ServiceTypesStore", () => {
  const mockService = createMockService();
  const layer = Layer.succeed(ServiceTypesServiceTag, mockService);

  it("should handle operations with Effect", async () => {
    const result = await runEffect(operation, layer);
    expect(result).toBeDefined();
  });
});

🔧 Backend Implementation: Holochain Zomes

DNA Structure

dnas/requests_and_offers/
├── zomes/
│   ├── coordinator/          # Business logic zomes
│   │   ├── administration/   # Admin roles and system management
│   │   ├── service_types/    # Service type management
│   │   ├── requests/         # Request management
│   │   ├── offers/           # Offer management
│   │   ├── users_organizations/ # User and organization management
│   │   └── mediums_of_exchange/ # Payment methods
│   └── integrity/            # Data validation zomes
│       ├── administration/   # Status validation
│       ├── service_types/    # Service type validation
│       ├── requests/         # Request validation
│       ├── offers/           # Offer validation
│       ├── users_organizations/ # User/org validation
│       └── mediums_of_exchange/ # Payment validation

Coordinator/Integrity Pattern

The backend follows Holochain's coordinator/integrity pattern:

Integrity Zomes (/integrity/):

#![allow(unused)]
fn main() {
// Data validation and entry definitions
#[hdk_entry_helper]
#[derive(Clone, PartialEq)]
pub struct ServiceType {
    pub name: String,
    pub description: String,
    pub tags: Vec<String>,
}

pub fn validate_create_service_type(
    _action: &SignedActionHashed,
    service_type: &ServiceType,
) -> ExternResult<ValidateCallbackResult> {
    if service_type.name.is_empty() {
        return Ok(ValidateCallbackResult::Invalid(
            "ServiceType name cannot be empty".to_string(),
        ));
    }
    Ok(ValidateCallbackResult::Valid)
}
}

Coordinator Zomes (/coordinator/):

#![allow(unused)]
fn main() {
// Business logic and external API
#[hdk_extern]
pub fn create_service_type(input: ServiceTypeInput) -> ExternResult<Record> {
    let is_admin = check_if_agent_is_administrator(agent_info()?.agent_initial_pubkey)?;
    if !is_admin {
        return Err(AdministrationError::Unauthorized.into());
    }

    let service_type_hash = create_entry(EntryTypes::ServiceType(input.service_type.clone()))?;
    // ... additional business logic
}
}

Key Zome Capabilities

Service Types Zome

• ✅ Admin Creation: Only administrators can create service types
• ✅ User Suggestions: Users can suggest new service types for approval
• ✅ Tag-Based Discovery: Advanced tag-based search and categorization
• ✅ Status Management: Pending → Approved/Rejected workflow
• ✅ Tag Statistics: Usage analytics and trending tags

Requests Zome

• ✅ CRUD Operations: Create, read, update, delete requests
• ✅ Status Transitions: Active → Fulfilled/Cancelled workflows
• ✅ Service Type Linking: Link requests to service types for discovery
• ✅ User Association: Track request creators and assignees

Offers Zome

• ✅ Offer Management: Create and manage service offers
• ✅ Request Matching: Link offers to specific requests
• ✅ Status Tracking: Active → Accepted/Completed workflows
• ✅ Multi-Entity Support: Support for individual and organization offers

Administration Zome

• ✅ Role Management: Administrator assignment and validation
• ✅ Status Workflows: Centralized status management across domains
• ✅ Access Control: Permission validation for sensitive operations
• ✅ System Monitoring: Track system-wide administrative actions

💻 Frontend Implementation: SvelteKit + Effect-TS

Project Structure

ui/src/
├── lib/
│   ├── components/          # UI components (organized by feature)
│   │   ├── service-types/   # Service type management UI
│   │   ├── requests/        # Request *management* UI
│   │   ├── offers/          # Offer management UI
│   │   ├── users/           # User management UI
│   │   ├── organizations/   # Organization management UI
│   │   └── shared/          # Reusable components (MarkdownRenderer, MarkdownToolbar, stripMarkdown)
│   ├── services/            # Service layer (Holochain, hREA)
│   │   ├── zomes/           # Zome-specific services
│   │   ├── holochainClient.service.ts
│   │   └── hrea.service.ts
│   ├── stores/              # Svelte stores (state management)
│   │   ├── serviceTypes.store.svelte.ts
│   │   ├── requests.store.svelte.ts
│   │   ├── offers.store.svelte.ts
│   │   └── users.store.svelte.ts
│   ├── composables/         # Component logic abstraction
│   │   ├── domain/          # Domain-specific composables
│   │   ├── search/          # Search functionality
│   │   └── ui/              # UI interaction composables
│   ├── schemas/             # Effect Schema validation
│   │   ├── service-types.schemas.ts
│   │   ├── requests.schemas.ts
│   │   └── common.schemas.ts
│   ├── errors/              # Centralized error handling
│   │   ├── service-types.errors.ts
│   │   ├── requests.errors.ts
│   │   └── error-contexts.ts
│   └── utils/               # Utility functions
│       ├── cache.svelte.ts
│       ├── effect.ts
│       └── validation.ts
└── routes/                  # SvelteKit routes/pages
    ├── (public)/            # Public application routes
    │   ├── service-types/   # Service type listing, suggestions, details
    │   │   ├── suggest/     # User service type suggestions
    │   │   └── [id]/        # Service type details
    │   ├── requests/        # Request management
    │   │   ├── create/      # Create new request
    │   │   ├── [id]/        # Request details
    │   │   └── [id]/edit/   # Edit request
    │   ├── offers/          # Offer management
    │   │   ├── create/      # Create new offer
    │   │   ├── [id]/        # Offer details
    │   │   └── [id]/edit/   # Edit offer
    │   ├── organizations/   # Organization management
    │   │   ├── create/      # Create organization
    │   │   ├── [id]/        # Organization details
    │   │   └── [id]/edit/   # Edit organization
    │   ├── users/           # User directory
    │   │   └── [id]/        # User profile details
    │   ├── user/            # Current user management
    │   │   ├── create/      # User registration
    │   │   └── edit/        # Edit user profile
    │   ├── projects/        # Project listings
    │   ├── mediums-of-exchange/ # Payment methods listing
    │   ├── tags/            # Tag-based discovery
    │   │   └── [tag]/       # Tag-filtered content
    │   └── test-status-history/ # Status history testing
    └── admin/               # Administrative interface
        ├── service-types/   # Admin service type management
        │   ├── create/      # Create service type
        │   ├── moderate/    # Moderate suggestions
        │   ├── [id]/        # Service type admin details
        │   └── [id]/edit/   # Edit service type
        ├── requests/        # Admin request oversight
        ├── offers/          # Admin offer oversight
        ├── organizations/   # Admin organization management
        │   └── status-history/ # Organization status history
        ├── users/           # Admin user management
        │   └── status-history/ # User status history
        ├── administrators/  # Administrator management
        ├── projects/        # Admin project management
        ├── mediums-of-exchange/ # Admin payment method management
        │   ├── create/      # Create payment method
        │   └── [id]/edit/   # Edit payment method
        └── hrea-test/       # hREA integration testing

Route Architecture & Navigation

The application implements a dual-interface routing system with clear separation between public and administrative functionality:

Public Routes ((public)/)

Purpose: User-facing features accessible to all community members

Key Route Groups:

• Service Types (/service-types/): Browse service categories, view details, submit suggestions
• Requests (/requests/): View and manage service requests with full CRUD operations
• Offers (/offers/): Browse available offers and create new ones
• Organizations (/organizations/): Organization directory and management
• Users (/users/, /user/): User directory and personal profile management
• Discovery (/tags/[tag]/): Tag-based content discovery and filtering
• Projects (/projects/): Project listings and collaboration
• Mediums of Exchange (/mediums-of-exchange/): Payment method options

Route Patterns:

// Standard CRUD pattern for entities
/entity/              # List view
/entity/create/       # Creation form
/entity/[id]/         # Detail view
/entity/[id]/edit/    # Edit form

// Discovery patterns
/tags/[tag]/          # Tag-filtered content
/users/[id]/          # User profile

Admin Routes (/admin/)

Purpose: Administrative oversight with enhanced permissions and system management

Key Features:

• Content Moderation: Service type suggestions, user content oversight
• System Administration: User management, administrator assignment
• Status Monitoring: Comprehensive status history tracking across domains
• Testing Tools: hREA integration testing and system diagnostics

Admin-Specific Routes:

• Moderation (/admin/service-types/moderate/): Review and approve user suggestions
• Status History (/admin/{domain}/status-history/): Track entity status changes
• Administrator Management (/admin/administrators/): Role assignment and permissions
• Testing Interface (/admin/hrea-test/): hREA integration validation

State Management Pattern

The frontend uses Svelte 5 Runes combined with Effect-TS for reactive state management:

// Store factory with Effect integration
export const createServiceTypesStore = () => {
  // Svelte 5 reactive state
  let entities = $state<UIServiceType[]>([]);
  let isLoading = $state(false);
  let error = $state<string | null>(null);

  // Effect-based operations
  const fetchEntities = Effect.gen(function* () {
    const serviceTypesService = yield* ServiceTypesServiceTag;
    const records = yield* serviceTypesService.getAllServiceTypes();
    entities = mapRecordsToUIEntities(records);
  });

  return {
    // Reactive getters
    entities: () => entities,
    isLoading: () => isLoading,
    error: () => error,

    // Effect operations
    fetchEntities,
    createEntity,
    updateEntity,
    deleteEntity,
  };
};

Component Architecture

Components follow clean separation of concerns:

<!-- ServiceTypeForm.svelte -->
<script lang="ts">
  import { useServiceTypeFormManagement } from '$lib/composables';
  import { ServiceTypeFormSchema } from '$lib/schemas';

  // Business logic in composable
  const { handleSubmit, isLoading, errors, form } = useServiceTypeFormManagement();

  // Component focuses on presentation
</script>

<form on:submit={handleSubmit} class="space-y-4">
  <input
    bind:value={form.name}
    class:error={errors.name}
    placeholder="Service Type Name"
  />

  <button
    type="submit"
    disabled={isLoading}
    class="btn variant-filled-primary"
  >
    {isLoading ? 'Creating...' : 'Create Service Type'}
  </button>
</form>

🖥️ Desktop Applications (Kangaroo)

Submodule Structure

The project includes desktop applications as git submodules for unified development:

requests-and-offers/
├── deployment/                   # Deployment repositories as git submodules
│   ├── kangaroo-electron/        # Desktop app repository (submodule)
│   │   ├── src/                 # Tauri application source code
│   │   ├── pouch/               # WebHapp packaging directory
│   │   ├── kangaroo.config.ts   # Desktop app configuration
│   │   └── dist/                # Built applications
│   ├── homebrew/                 # Homebrew formula repository (submodule)
│   └── scripts/                  # Deployment automation scripts
│       ├── deploy.sh            # Main deployment orchestrator
│       ├── config/              # Configuration files
│       └── lib/                 # Deployment utilities

Desktop App Architecture

The Kangaroo desktop applications are built using Tauri with the following architecture:

graph TB
    subgraph "Desktop Application Layer"
        A[Tauri Frontend]
        B[Rust Backend]
        C[WebHapp Integration]
    end

    subgraph "WebHapp Layer"
        D[SvelteKit Application]
        E[Holochain Client]
        F[hREA Framework]
    end

    subgraph "Platform Build System"
        G[Windows Build]
        H[macOS Build]
        I[Linux Build]
    end

    A --> D
    B --> E
    D --> E
    E --> F

    A --> G
    A --> H
    A --> I

Key Desktop Features

Cross-Platform Support

• Windows: Installer (.exe) with code signing
• macOS: DMG packages (Intel and Apple Silicon)
• Linux: AppImage and .deb packages

WebHapp Integration

• Automatic Updates: Seamless webhapp version synchronization
• Local Packaging: WebHapp embedded in desktop application
• Network Configuration: Production network settings for Holochain connectivity

Development Workflow

# Clone with submodules
git clone --recurse-submodules https://github.com/happenings-community/requests-and-offers.git

# Update submodules to latest
git submodule update --remote

# Desktop app development
cd deployment/kangaroo-electron
npm run tauri dev

# Build for production
npm run tauri build

Deployment Automation

The project includes comprehensive deployment automation:

# Full deployment (webapp + desktop + homebrew)
./deployment/scripts/deploy.sh deploy 0.1.X

# Desktop-specific deployment
./deployment/scripts/lib/kangaroo-deployer.sh deploy 0.1.X

# Homebrew formula updates
./deployment/scripts/lib/homebrew-updater.sh update 0.1.X

Automated Features:

• ✅ Environment Validation: Checks submodules, tools, and permissions
• ✅ WebApp Building: Automated hApp compilation and packaging
• ✅ Desktop Builds: Parallel builds across all platforms
• ✅ Asset Validation: Comprehensive asset verification
• ✅ Homebrew Updates: Automatic formula updates with checksums
• ✅ Rollback Capabilities: One-command rollback if issues occur

🔗 hREA Integration

The project integrates with hREA (Holochain Resource-Event-Agent) framework for economic coordination:

Domain Mappings

// Requests → hREA Intents
export const mapRequestToIntent = (request: UIRequest): Intent => ({
  action: IntentAction.WORK,
  resourceClassifiedAs: request.serviceTypeHashes,
  name: request.title,
  note: request.description,
});

// Offers → hREA Proposals
export const mapOfferToProposal = (offer: UIOffer): Proposal => ({
  name: offer.title,
  note: offer.description,
  unitBased: true,
});

// Service Types → ResourceSpecifications
export const mapServiceTypeToResourceSpec = (
  serviceType: UIServiceType,
): ResourceSpecification => ({
  name: serviceType.name,
  note: serviceType.description,
  resourceClassifiedAs: serviceType.tags,
});

Economic Workflows

sequenceDiagram
    participant User as User
    participant App as App
    participant hREA as hREA DNA

    User->>App: Create Request
    App->>hREA: Create Intent
    hREA-->>App: Intent Created

    User->>App: Create Offer
    App->>hREA: Create Proposal
    hREA-->>App: Proposal Created

    User->>App: Accept Offer
    App->>hREA: Create Agreement
    hREA-->>App: Agreement Created

🧪 Testing Strategy

Test Coverage Architecture

The project maintains comprehensive testing across all layers:

tests/
├── unit/                    # Unit tests (343 tests passing)
│   ├── services/            # Service layer tests
│   ├── stores/              # Store layer tests
│   ├── components/          # Component tests
│   └── fixtures/            # Test data fixtures
├── integration/             # Integration tests
│   ├── offers-requests-interaction.test.ts
│   ├── tag-discovery.test.ts
│   └── serviceTypes.test.ts
├── e2e/                     # End-to-end tests
│   ├── specs/
│   │   ├── user-journeys/   # Complete user workflows
│   │   ├── admin/           # Administrative workflows
│   │   └── advanced/        # Complex scenarios
│   └── fixtures/            # E2E test data
└── mocks/                   # Shared test mocks

Effect-TS Testing Pattern

describe("ServiceTypesService", () => {
  const mockClient = createMockHolochainClient();
  const testLayer = Layer.succeed(HolochainClientServiceTag, mockClient);

  it("should create service type successfully", async () => {
    const serviceType = createTestServiceType();
    const effect = serviceTypesService.createServiceType(serviceType);

    const result = await runEffect(effect, testLayer);
    expect(result).toBeDefined();
  });
});

Test Categories

Backend Tests (tests/sweettest/)

• Sweettest Integration: Multi-agent Holochain scenarios
• Zome Functionality: Individual zome operation testing
• Cross-Zome Integration: Inter-zome communication testing
• Status Workflows: State transition validation

Frontend Unit Tests (ui/tests/unit/)

• Service Layer: Effect-TS service testing with mocks
• Store Layer: Reactive state management testing
• Component Testing: UI component behavior validation
• Schema Validation: Effect Schema validation testing

Frontend Integration Tests (ui/tests/integration/)

• Store-Service Integration: End-to-end data flow testing
• Cross-Domain Workflows: Multi-domain operation testing
• Cache Management: Cache behavior and invalidation testing

E2E Tests (ui/tests/e2e/)

• User Journeys: Complete user workflow validation
• Admin Workflows: Administrative interface testing
• Cross-Browser: Multi-browser compatibility testing
• Performance: Load time and interaction performance

🚀 Development Workflow

Environment Setup

# Clone with submodules
git clone --recurse-submodules https://github.com/happenings-community/requests-and-offers.git

# Enter Nix development environment (required for zome development)
nix develop

# Install dependencies
bun install

# Initialize/update submodules if needed
git submodule update --init --recursive

# Download hREA DNA
bun run download-hrea

Development Commands

# Start application with 2 agents
bun start

# Start with custom agent count
AGENTS=3 bun start

# Build and test cycle
bun run build:zomes
bun run build:happ
bun test

# Frontend-only development
cd ui && bun run dev
cd ui && bun run test:unit

# Desktop app development
cd deployment/kangaroo-electron && npm run tauri dev

# Submodule management
git submodule update --remote kangaroo-electron
git submodule update --remote homebrew

Code Quality Pipeline

# TypeScript checking
cd ui && bun run check

# Linting and formatting
cd ui && bun run lint
cd ui && bun run format

# Comprehensive testing
bun test                    # Full test suite
bun test:ui                 # Frontend tests only
bun test:unit              # Unit tests (requires Nix)
bun test:integration       # Integration tests

📊 Current Implementation Status

✅ Completed Domains (100% Standardized)

Service Types Domain 🏆

• ✅ Service Layer: Complete Effect-TS implementation with dependency injection
• ✅ Store Layer: All 9 standardized helper functions implemented
• ✅ Component Layer: Tag-based discovery, suggestion workflows, admin moderation
• ✅ Testing: 100% unit test coverage with Effect-TS patterns
• ✅ Features: Creation, suggestion, approval/rejection, tag-based search, statistics
• 🎯 Template Status: Serves as architectural template for all new implementations

Requests Domain ✅

• ✅ Service Layer: Full CRUD operations with status management
• ✅ Store Layer: Standardized helper functions with cache synchronization
• ✅ Component Layer: Request forms, tables, detail modals, status transitions
• ✅ Testing: Comprehensive test coverage across all layers
• ✅ Features: Create, edit, fulfill, cancel requests with service type linking

Offers Domain ✅

• ✅ Service Layer: Complete offer management with request matching
• ✅ Store Layer: All standardized helper functions with event emission
• ✅ Component Layer: Offer creation, matching, acceptance workflows
• ✅ Testing: Full test suite with Effect-TS integration
• ✅ Features: Offer creation, request matching, status tracking, completion workflows

📈 Completed Standardization (All Major Domains)

Users Domain ✅

• ✅ Service Layer: Complete Effect-TS conversion with Context.Tag patterns
• ✅ Store Layer: All 9 standardized helper functions implemented
• ✅ Component Layer: User profiles, administration interface complete
• ✅ Testing: Full Effect-TS test coverage

Organizations Domain ✅

• ✅ Service Layer: Complete Effect-TS implementation with dependency injection
• ✅ Store Layer: All standardized helper functions with event emission
• ✅ Component Layer: Organization management UI complete (including contact person designation)
• ✅ Testing: Comprehensive test coverage

Administration Domain ✅

• ✅ Service Layer: Status management and role validation complete
• ✅ Store Layer: Complete standardization with all helper functions
• ✅ Component Layer: Admin interfaces and status workflows complete
• ✅ Testing: Full test coverage across all layers

📈 Metrics & Achievements

• 343 Unit Tests: All passing across 20 test files with Effect-TS integration
• 90%+ Code Coverage: Across service and store layers
• 8 Domains: Fully standardized with proven patterns (100% completion)
• 9 Helper Functions: Massive code reduction through standardization
• Zero Breaking Changes: During domain standardization process
• 100% Type Safety: Complete Effect-TS integration
• Documentation Overhaul: Consolidated from 25 AI rules to 6 focused guidelines
• Developer Experience: Quick Reference and Troubleshooting guides added

🔮 Future Roadmap

✅ Phase 1: Complete Standardization (COMPLETED)

• ✅ All Domains: Complete Effect-TS conversion and helper function implementation
• ✅ Architecture Maturity: 7-layer architecture fully implemented across all domains
• ✅ Documentation Enhancement: Consolidated and improved developer experience

Phase 2: Advanced Features (Current Focus)

• 🎯 Exchange Completion: hREA agreement and commitment workflows
• 🎯 Advanced Analytics: Usage statistics, trend analysis, reporting dashboards
• 🎯 Notification System: Real-time updates and user notifications
• 🎯 Advanced Search: Full-text search, filtering, recommendation engine
• 🎯 Visual Documentation: Architecture diagrams and system workflow visuals

Phase 3: Platform Enhancement (Upcoming)

• 🎯 Mobile Application: React Native or Flutter mobile app
• 🎯 Federation: Multi-community and cross-network coordination
• 🎯 AI Integration: Intelligent matching, recommendation systems
• 🎯 Performance Optimization: Advanced caching, lazy loading, bundle optimization

📚 Recent Documentation Revolution

The project underwent a major documentation overhaul to improve developer experience and reduce cognitive overhead:

Documentation Consolidation

• Before: 25 scattered AI development rule files creating cognitive overload
• After: 6 focused, coherent guideline files covering all development aspects
• Reduction: 76% decrease in documentation fragmentation

New Developer Resources

• Quick Reference Guide: Essential commands, patterns, and workflows for immediate productivity
• Troubleshooting Guide: Comprehensive solutions for common development issues
• Consolidated AI Rules: Streamlined development guidelines covering:
  • Development Guidelines (Effect-TS, Svelte 5, schemas, components)
  • Architecture Patterns (7-layer architecture, services, stores, event-driven communication)
  • Testing Framework (Backend Sweettest + Frontend Vitest strategies)
  • Domain Implementation (Administration, error management, guards, utilities)
  • Development Workflow (Continuation, cleanup, planning, changelog maintenance)
  • Environment Setup (Nix configuration, development environment, documentation standards)

Enhanced Navigation

• Streamlined README: Focused quick start with essential links
• Improved Documentation Index: Better categorization with visual indicators
• Cross-Reference Updates: All navigation reflects new structure

Impact Metrics

• Onboarding Time: Reduced from hours to minutes for new developers
• Cognitive Load: 76% reduction in scattered documentation files
• Developer Satisfaction: Improved discoverability and self-service support
• Maintenance Overhead: Significantly reduced through consolidation

🎯 Key Success Factors

Architectural Excellence

• 100% Type Safety: Complete Effect-TS integration eliminates runtime errors
• Standardized Patterns: 9 helper functions reduce code duplication by 60%
• Error Boundaries: Comprehensive error handling with domain-specific contexts
• Dependency Injection: Clean separation of concerns with testable architecture

Development Experience

• Hot Reloading: Instant feedback during development
• Comprehensive Testing: 343 tests across 20 files ensure reliability and prevent regressions
• Type-Driven Development: Schemas and validation catch errors at compile time
• Clear Patterns: Standardized approaches reduce cognitive load

User Experience

• Responsive Design: Mobile-first approach with TailwindCSS
• Accessibility: WCAG compliance and keyboard navigation support
• Markdown Support: Rich text descriptions and bios with MarkdownRenderer + MarkdownToolbar (using marked + DOMPurify)
• Progressive Enhancement: Works without JavaScript, enhanced with interactivity
• Performance: Optimized bundles and lazy loading for fast load times

Maintainability

• Clean Architecture: Clear separation between layers and domains
• Documentation: Comprehensive documentation and code comments
• Consistent Patterns: Standardized approaches across all domains
• Automated Testing: Prevents regressions and ensures quality

📝 Implementation Guidelines

For New Developers

1. Start with Documentation: Read project overview and technical specifications
2. Study Completed Domains: Service Types domain as reference implementation
3. Follow Patterns: Use established helper functions and architectural patterns
4. Test-Driven Development: Write tests first, then implement functionality
5. Effect-TS First: All new code must use Effect-TS patterns

For Domain Implementation

1. Service Layer: Implement Effect-TS service with Context.Tag injection
2. Store Layer: Use factory function with all 9 standardized helper functions
3. Schema Layer: Define Effect Schema classes with proper validation
4. Error Layer: Create domain-specific tagged errors with contexts
5. Component Layer: Use composables for business logic, components for presentation
6. Testing Layer: Comprehensive unit, integration, and E2E test coverage

For Maintenance

1. Follow Standards: Maintain consistency with established patterns
2. Update Tests: Ensure all changes include corresponding test updates
3. Documentation: Update documentation for any architectural changes
4. Performance: Monitor and optimize bundle sizes and load times
5. Security: Follow security best practices and validate all inputs

This comprehensive codebase documentation provides a complete overview of the Holochain Requests and Offers project's architecture, implementation patterns, and development practices. The 7-layer Effect-TS architecture represents a significant advancement in TypeScript application design, providing unprecedented type safety, error handling, and maintainability.

Moss/Weave Integration

This document describes how Requests & Offers integrates with the Weave/Moss ecosystem as a Moss Tool. It covers architecture, design decisions, and development setup.

Overview

R&O runs in two modes:

1. Standalone -- Direct connection via AppWebsocket
2. Moss Tool -- Integrated via WeaveClient within a Moss group

The app detects its context once at startup and adapts connection, profile handling, and admin detection accordingly. Weave-specific concerns are isolated in a dedicated WeaveService + weaveStore layer, keeping HolochainClientService focused on core Holochain connectivity.

1. Context Detection

Context detection uses a two-stage approach coordinated between +layout.svelte and the Weave layer.

Stage 1 -- Hot-reload setup and detection (+layout.svelte onMount):

// +layout.svelte — onMount
onMount(async () => {
  // Sets up window.__WEAVE_API__ which isWeaveContext() checks.
  // MUST run before Weave context detection.
  try {
    await initializeHotReload();
  } catch {
    // Expected to fail in non-Weave environments and production webhapps
  }

  // Detect Weave context AFTER hot-reload has set up the environment
  weaveStore.detectWeaveContext();
  // ...
});

Stage 2 -- Connection delegation (HolochainClientService.connectClient()):

// HolochainClientService.svelte.ts — connectClient()
if (weaveStore.isWeaveContext) {
  console.log('🧶 Detected Weave context, connecting via WeaveClient...');
  const result = await weaveStore.connect();
  client = result.appClient;
} else {
  console.log('📡 Standalone mode, connecting via AppWebsocket...');
  client = await AppWebsocket.connect();
}

The WeaveService lazily detects the Weave context by calling isWeaveContext() from @theweave/api. This lazy detection is necessary because in weave dev mode, initializeHotReload() must set up window.__WEAVE_API__ before isWeaveContext() can detect the environment.

Cross-group views (renderInfo.type !== 'applet-view') are not yet supported and result in a WeaveError.

Key files:

• ui/src/lib/stores/weave.store.svelte.ts
• ui/src/lib/services/weave.service.ts
• ui/src/lib/services/HolochainClientService.svelte.ts

2. Connection Management

Both modes share the same retry logic in HolochainClientService:

• Max retries: 3 attempts
• Backoff: Exponential -- 2s, 4s, 8s delays (Math.pow(2, retryCount) * 1000)
• State tracking: Reactive isConnected / isConnecting flags
• Concurrent guard: If a connection attempt is already in progress, callers wait via polling

In Weave context, HolochainClientService.connectClient() delegates to weaveStore.connect(), which internally runs WeaveService.connect() via Effect. This returns a WeaveConnectionResult containing the appClient, weaveClient, and profilesClient. In standalone mode, AppWebsocket.connect() is called directly. The retry/backoff/state-tracking logic remains in HolochainClientService for both paths.

Components can call waitForConnection() to block until the client is ready, or use verifyConnection() to test connectivity (attempts client.appInfo() as a health check).

On WebSocket or connection errors during callZome(), the service marks itself as disconnected and nulls the client, forcing reconnection on the next call.

3. Hybrid Profile System

In Moss, users already have a profile (nickname + avatar) managed by the group's ProfilesClient. R&O stores additional professional data (bio, email, skills, location). The weaveStore manages profile fetching, avatar conversion, and enrichment of R&O users with Moss identity data.

WeaveStore Profile Management

The weaveStore provides methods and reactive state for Moss profile handling:

Methods:

Reactive state:

After connection, the layout initializes the Weave store profile state:

// +layout.svelte — initialization orchestrator
if (weaveStore.isWeaveContext) {
  const appInfo = await hc.getAppInfo();
  if (appInfo?.agent_pub_key) {
    await weaveStore.initialize(appInfo.agent_pub_key as AgentPubKey);
  }
}

Enrichment behavior:

• Moss context: enrichWithMossProfile returns a UIUser with nickname and picture from Moss, all other fields from R&O, and identitySource: 'moss'
• Standalone: Returns the R&O user as-is with identitySource: 'standalone'
• If a Moss profile exists but no R&O user record yet (new user in Moss), a minimal UIUser is returned with Moss identity fields and empty R&O fields

Component Integration

Components import weaveStore directly to access Moss profile data. For example, UserForm.svelte uses the store to pre-fill the nickname and avatar when creating a new user in Moss context:

• weaveStore.mossNickname -- Pre-fills the nickname field
• weaveStore.hasMossNickname -- Controls whether nickname is editable
• weaveStore.hasMossAvatar -- Controls avatar display/editing
• weaveStore.mossAvatarBlob -- Provides the avatar for preview

Error Handling

WeaveError is a tagged error (Data.TaggedError('WeaveError')) with fields for message, cause, context, agentPubKey, and operation. Error contexts are defined in WEAVE_CONTEXTS:

• DETECT_CONTEXT -- Detecting Weave environment
• CONNECT -- Connecting to Weave
• GET_MOSS_PROFILE -- Fetching from Moss profilesClient
• ENRICH_WITH_MOSS_PROFILE -- Merging Moss data onto R&O profile
• CHECK_PROGENITOR -- Checking tool installer status
• AVATAR_CONVERSION -- Converting base64 avatar to binary

Key files:

• ui/src/lib/services/weave.service.ts
• ui/src/lib/stores/weave.store.svelte.ts
• ui/src/lib/errors/weave.errors.ts
• ui/src/lib/errors/error-contexts.ts
• ui/src/lib/types/ui.ts (identitySource field on UIUser)

4. Progenitor Detection (Admin)

In Moss, the group "progenitor" (the agent who installed the tool) gets admin rights automatically.

Working approach: toolInstaller() + pubkey comparison

The weaveStore.checkProgenitor(myPubKey) method handles progenitor detection:

// weave.store.svelte.ts — checkProgenitor()
async function checkProgenitor(myPubKey: AgentPubKey): Promise<boolean> {
  if (!isWeaveContext || !weaveClient) {
    isProgenitor = false;
    return false;
  }

  const renderInfo = weaveClient.renderInfo;
  if (renderInfo.type !== 'applet-view') {
    isProgenitor = false;
    return false;
  }

  const appletHash = renderInfo.appletHash;
  const installerPubKey = await weaveClient.toolInstaller(appletHash);
  if (!installerPubKey) {
    isProgenitor = false;
    return false;
  }

  const installerB64 = encodeHashToBase64(installerPubKey);
  const myB64 = encodeHashToBase64(myPubKey);
  isProgenitor = installerB64 === myB64;
  return isProgenitor;
}

toolInstaller(appletHash) returns the AgentPubKey of whoever installed the R&O tool in this Moss group. Comparing it with the current agent's pubkey gives cryptographic proof of installer identity. The result is stored as reactive isProgenitor state.

Failed approach: myAccountabilitiesPerGroup()

An earlier attempt used weaveClient.myAccountabilitiesPerGroup() to check for a "Progenitor" role. This doesn't work because the API returns group role definitions to all agents, not filtered by who holds them. Both the progenitor and regular members receive identical data showing "Progenitor role exists."

Standalone fallback

When not in Moss context, checkProgenitor() sets isProgenitor = false and returns immediately. The existing R&O admin system (explicit registerNetworkAdministrator / addNetworkAdministrator) handles admin rights.

Key file: ui/src/lib/stores/weave.store.svelte.ts

5. Auto-Admin Registration

The +layout.svelte initialization orchestrator runs autoRegisterProgenitorAdminStep after connection, hREA init, network verification, Weave store initialization, and user data loading:

1. Check weaveStore.isWeaveContext -- skip if standalone
2. Get agent pubkey from hc.getAppInfo()
3. Call weaveStore.checkProgenitor(agentPubKey) -- skip if not progenitor
4. Call administrationStore.hasAnyAdministrators() -- skip if admins already exist
5. Check usersStore.currentUser exists with an original_action_hash
6. Call administrationStore.registerNetworkAdministrator(userHash, [pubKey])

This is wrapped in E.catchAll so failures are non-critical -- the app continues normally.

In standalone mode, first-admin registration is triggered via Ctrl+Shift+A keyboard shortcut, which shows a confirmation modal. This shortcut is blocked in Weave context since progenitor auto-admin handles it.

Key files:

• ui/src/routes/+layout.svelte
• ui/src/lib/stores/weave.store.svelte.ts

6. Network Peer Discovery

getNetworkPeers() queries the conductor for connected peers:

1. Checks client instanceof AppWebsocket (method not available on the generic AppClient interface used in Moss)
2. Calls client.agentInfo({ dna_hashes: null })
3. Handles multiple response formats (object with agent_pub_key, JSON strings, nested agentInfo.agent)
4. Returns a deduplicated array of agent public key strings

Similarly, getPeerMetaInfo() collects metadata from peers by calling client.peerMetaInfo() for each discovered agent URL.

Limitation: In Weave context, the client is an AppClient (not AppWebsocket), so agentInfo / peerMetaInfo are not available. These methods return empty results. A future upstream PR to @holochain/client could add these to the AppClient interface.

Key file: ui/src/lib/services/HolochainClientService.svelte.ts

7. Data Flow

User opens R&O
       │
       ▼
 +layout.svelte (onMount)
       │
       ├──► initializeHotReload()
       │
       ▼
 weaveStore.detectWeaveContext()
       │
       ▼
 connectToHolochain()
       │
       ├── Weave? → weaveStore.connect() → WeaveService.connect() → WeaveClient
       │                                          │
       └── Standalone? → AppWebsocket.connect()   │
                │                                  │
                ▼                                  ▼
       Store client reference ◄────────────────────┘
       │
       ▼
 Initialize hREA, verify network, load user data
       │
       ▼
 weaveStore.initialize(agentPubKey)  (Weave only — fetch Moss profile)
       │
       ▼
 autoRegisterProgenitorAdminStep
       │    └── weaveStore.checkProgenitor(pubKey)
       │
       ▼
 App renders
       │
       ├──► Profile display → weaveStore → Moss or R&O profiles
       │
       ├──► Admin checks → weaveStore.isProgenitor → Moss group data or R&O admin system
       │
       └──► Zome calls → HolochainClientService → Holochain conductor

8. Development Setup

Directory structure

weave/
├── applet-dev.sh           # Multi-agent launch script
├── curations-0.15.json     # Tool curation metadata for Moss registry
├── tool-list-0.15.json     # Tool registry (versions, hashes, download URLs)
└── weave.dev.config.json   # Dev sandbox config (groups, agents, applets)

Running in Weave dev mode

bun run applet-dev          # Launches with 2 agents by default
AGENTS=3 bun run applet-dev # Custom number of agents (1-10)

The applet-dev.sh script:

1. Starts the UI dev server on port 8888
2. Launches agent 1 with weave --agent-idx 1 --dev-config ./weave/weave.dev.config.json
3. Launches additional agents with staggered delays (5s between each) and --sync-time 20000
4. Uses concurrently to run all processes

Dev sandbox config (weave.dev.config.json)

Defines a test group ("R&O Dev Group") with:

• networkSeed: "ro-dev-test-2026" for isolated test networks
• Agent 1 as the creating agent (becomes progenitor)
• The requests_and_offers applet sourced from localhost (hApp from ./workdir/requests_and_offers.happ, UI from port 8888)

Tool registry (tool-list-0.15.json)

Contains the developer collective metadata and tool versions for the Moss tool directory:

• Developer: hAppenings Community CIC
• Tool ID: requests-and-offers
• Version branch: 0.3.x
• Includes hApp, WebHapp, and UI SHA256 hashes for integrity verification

Curations (curations-0.15.json)

Points Moss to the tool list URL for discovery in the Moss tool directory.

9. Weave API Reference

Key methods used from @theweave/api:

10. Version Compatibility

11. Files Reference

12. Testing Checklist

• App loads in Moss group without errors
• Profile displays correctly (nickname + avatar from Moss)
• User creation form pre-fills with Moss profile data
• Group progenitor is auto-registered as admin
• Non-progenitor agents do not get auto-admin
• Admin features available to progenitor
• Network peers visible in standalone mode
• Standalone mode still works (regression test)
• DHT propagation between multiple agents in Weave dev mode
• Ctrl+Shift+A blocked in Weave context

13. Future Considerations

1. Deeper Moss permissions -- Currently only progenitor status is checked. Moss may offer richer permission models that could map to R&O roles.

2. Profile sync -- Profiles are read-only from Moss. Bidirectional sync could be explored if R&O has fields that should flow back to Moss.

3. Cross-group views -- Currently unsupported (renderInfo.type !== 'applet-view' returns a WeaveError). Could enable multi-group visibility in future.

4. AppClient interface -- Upstream PR to @holochain/client to add agentInfo / peerMetaInfo to AppClient would allow peer discovery in Moss context.

Requirements Overview

This document outlines the project's requirements, covering user needs, features, and goals.

Key Sections

• Features: Detailed description of system features.
• MVP: Minimum Viable Product scope and requirements.
• Roles: Definition of user roles and their capabilities.
• Use Cases: Description of user workflows and interactions.

Roles and Permissions Specifications

1. User Roles

1.1 Advocate

• Onboarded/Approved: Advocates are individuals passionate about the Holochain technology, looking to support projects within the ecosystem. They are onboarded and approved to participate in the network by the network's administrators.
• User Profile: Advocates must file out their user profiles, including essential information and their areas of expertise.
• Offers: Advocates can offer their skills, talents, or resources to the network. This includes mentorship, brainstorming sessions, or any other form of support they wish to provide.
• Reporting: Advocates have access to reporting features, allowing them to view their exchanges and a general report of total exchanges for the month.

1.2 Creator

• Onboarded/Approved: Creators are individuals or groups actively involved in creating or developing projects within the Holochain ecosystem. They are onboarded and approved to participate in the network by the network's administrators.
• User Profile: Creators can file out their user profiles, including their skills, location, type, etc.
• Offers: Creators can make offers, including the skills and talents they wish to offer.
• Requests: Creators can make requests for themselves, such as mentoring, brainstorming time, or testing in the early days of their projects.
• Reporting: Creators can access reports on their exchanges and a general report of total exchanges for the month.

1.3 Projects and Organizations Coordinators

• Onboarded/Approved: Projects and organizations coordinators are individuals or groups designated to represent a project or organization within the network. They are onboarded and approved to participate in the network.
• Project Profile: Projects and organizations coordinators can file out the project profile, including the skills involved, location, type, etc.
• Offers: Projects and organizations coordinators can make offers for themselves and on behalf of their projects or organizations, such as:
  • Development resources (e.g., reusable Holochain zomes, UI components)
  • Testing environments or infrastructure
  • Documentation support or translation services
  • Community building and engagement resources
  • Training or workshop sessions about their project
  • Collaborative development opportunities
  • Beta testing participation opportunities
• Contact Person: Coordinators can be designated as the organization's public-facing contact person with a role/title (e.g. Director, President)
• Requests: Projects and organizations coordinators can make requests for themselves and on behalf of their projects or organizations, such as:
  • Technical expertise (Rust/Holochain development, UI/UX)
  • Code review and architecture feedback
  • Testing and quality assurance
  • Documentation assistance
  • Translation services
  • Community outreach support

1.4 Matchmaker (Future Role)

• Description: A role that could be added in future versions to facilitate the matching of requests and offers more efficiently.

2. Administrative Roles

2.1 Administrator

• Access: Full access to Administration Zome and UI
• Responsibilities:
  • User and Organization verification
  • Project verification
  • Administrator management
  • Suspension management
  • System configuration
  • Full reporting access

2.2 Moderator

• Access: Limited access to Administration Zome and UI
• Responsibilities:
  • Content moderation
  • User support
  • Report handling
  • Cannot manage administrators

3. Role Management

3.1 Role Assignment

• Progenitor Pattern:
  • The progenitor is the agent whose public key is embedded in DNA properties (progenitor_pubkey) at network creation time — not simply the first agent to register
  • The progenitor's pubkey is set by the Kangaroo (Electron) app, which reads the creator's agent pubkey from the conductor admin API before installing the hApp
  • Upon user profile creation, the progenitor is automatically registered as the first network administrator (see #5)
  • The progenitor is a regular revocable administrator — no permanent super-admin power
  • Establishes initial administrative control
  • Other agents join the network by installing the same DNA instance (identified by its hash); they receive no admin role automatically
  • See also: #95 (Network Creation & Joining UX)
• Administrator Assignment: By existing administrators
• Moderator Assignment: By administrators
• Role Verification: Through anchor system

3.2 Access Control

Administrators

• AdministratorsUser: Link from administrators anchor to user
• Full System Access: Complete control over all system aspects

Moderators

• ModeratorsUser: Link from moderators anchor to user
• Limited Access: All admin functions except administrator management

3.3 Suspension System

• Temporary Suspension: Time-limited account restrictions
• Indefinite Suspension: Permanent account restrictions
• Suspension Management:
  • Reason documentation
  • History tracking
  • Notification system:
    • Initial suspension notification with reason
    • Duration notification for temporary suspensions
    • End of suspension notification
    • Appeal process updates
  • Unsuspension process

3.4 Communication Channels

• Administrative Inbox: Direct communication channel with administrators
• Moderation Queue: For handling reported content and issues
• Support System: For handling user inquiries and appeals
• Notification System: For administrative updates and actions

3.5 Flagging System

• User Flagging Rights: Users can flag organizations, projects, requests, and offers
• Review Process: Flagged content undergoes administrative review
• Action Types:
  • Content review
  • User warnings
  • Content removal
  • Account suspension
• Tracking: Maintain history of flags and resolutions

Use Cases Specifications

1. User Management

1.1 User Registration and Profile

• Use Case: Users can register and create user profile
• Benefit: Facilitates the creation of a user-centric community, enabling personalized experiences and targeted interactions

1.2 User Recovery

• Use Case: Users can recover their user profile, including their skills, projects, organizations, requests and offers
• Benefit: Enables multi-device access and profile recovery, ensuring continuity of user experience and data preservation

2. Project Management

2.1 Project Creation

• Use Case: Users can create projects, specifying the skills needed and the scope of the project
• Benefit: Allows for the organization and management of projects, ensuring that the right skills are matched with the right projects

2.2 Project Coordination

• Use Case: Project coordinators can manage team members, track progress, and update project requirements
• Benefit: Enables effective project management and team coordination

3. Request and Offer Management

3.1 Request Creation

• Use Case: Users can create requests for specific skills or resources needed for their projects
• Details: Requests can be linked to:
  • Specific projects
  • Organizations
  • Skills
  • Team members
• Benefit: Provides a structured way for users to express their needs, ensuring that the right offers are matched with their requests

3.2 Offer Creation

• Use Case: Users with relevant skills can create offers to contribute to projects
• Details: Users can specify:
  • Skills they are offering
  • Intended contribution method
  • Availability
  • Terms of assistance
• Benefit: Enables direct matching of skills with project needs, facilitating efficient collaboration

3.3 Exchange Management

• Use Case: Users can manage their requests and offers, including accepting offers from other users
• Features:
  • Offer acceptance/rejection
  • Request fulfillment tracking
  • Exchange completion verification
  • Feedback system
• Benefit: Provides a structured way for users to engage with each other, ensuring that interactions are organized and manageable

4. Search and Discovery

4.1 Basic Search Functionality

• Use Case: Users can search across multiple categories
• Search Categories:
  • Requests
  • Offers
  • Projects
  • Organizations
  • Users
• Search Criteria:
  • Name
  • Skills
  • Categories
  • Organizations
  • Projects
• Benefit: Enhances the discoverability of resources within the community, promoting collaboration and innovation

4.2 Advanced Filtering

• Use Case: Users can apply multiple filters to refine search results
• Filter Options:
  • Status
  • Location
  • Time frame
  • Skill level
  • Project type
• Benefit: Enables precise matching of resources and needs

5. Communication

5.1 Direct Messaging

• Use Case: Users can communicate directly about requests and offers
• Features:
  • Real-time messaging
  • Message history
  • File sharing
• Benefit: Facilitates detailed discussions and negotiations

5.2 Administrative Communication

• Use Case: Users can communicate with administrators for support
• Features:
  • Support tickets
  • Issue reporting
  • Feedback submission
• Benefit: Ensures effective support and issue resolution

6. Reporting

6.1 User Reports

• Use Case: Users can view their activity and exchange history
• Report Types:
  • Personal exchanges
  • Monthly summaries
  • Project contributions
• Benefit: Provides transparency and accountability

6.2 Administrative Reports

• Use Case: Administrators can access system-wide reports
• Report Types:
  • User activity
  • Exchange metrics
  • System usage
  • Moderation actions
• Benefit: Enables effective system monitoring and management

Detailed Feature Specifications

1. User Management

1.1 User Profile

• Creation and authentication of user profiles
• Profile categorization as "advocate" or "creator"
• Multi-device profile access using credentials
• Integration with hREA agents
• Custom Holochain zome for profile management

1.2 Profile Links

Users can be linked to:

• Agents
• Organizations
• Requests
• Offers
• Projects
• Service Types

1.3 User Entry Structure

The User entry represents profiles within hAppenings.community, supporting:

• Single user profiles
• Multi-device profile sharing
• Personalized experiences
• Community interactions

User Entry Structure (Current Implementation)

#![allow(unused)]
fn main() {
pub struct User {
  /// User's display name
  pub name: String,
  /// User's chosen nickname/handle
  pub nickname: String,
  /// Brief biographical description
  pub bio: String,
  /// Optional profile picture (serialized bytes)
  pub picture: Option<SerializedBytes>,
  /// User classification: 'advocate' or 'creator'
  pub user_type: String,
  /// Contact email address
  pub email: String,
  /// Optional phone number
  pub phone: Option<String>,
  /// User's time zone
  pub time_zone: String,
  /// Geographic location
  pub location: String,
}
}

User Fields Description

• name: User's full display name for the platform
• nickname: Chosen handle or shorter identifier
• bio: (String, max 1000 chars) Personal description, skills, interests, and background (supports markdown)
• picture: Optional profile image stored as serialized bytes
• user_type: Either "advocate" (community supporter) or "creator" (service provider)
• email: Primary contact email for notifications and communications
• phone: Optional phone number for alternative contact
• time_zone: User's time zone for scheduling and coordination
• location: Geographic location for local coordination and meetups

Links

• UserUpdates: User create header → update headers
• UserAgents: User → agent (index of associated agents)
• AllUsers: Link to users anchor (global user index)
• MyUser: Current agent → user
• UserRequests: User → requests (index)
• UserOffers: User → offers (index)
• UserProjects: User → projects (index)
• UserOrganizations: User → organizations (index)
• UserServiceTypes: User → service types (index)

2. Projects and Organizations

2.1 Projects

Projects are organizations classifiedAs Project in hREA.

Project Features

• Creation by organizations or users
• Specific requirements and status tracking
• Team member management
• Category classification

Project Status Flow

Project Types

Project Links

• AllProjects: Link to projects anchor
• ProjectCoordinators: Project → coordinators
• ProjectContributors: Project → contributors
• ProjectCategories: Project → categories
• ProjectRequests: Project → requests
• ProjectOffers: Project → offers

2.2 Organizations

Organizations are agents classifiedAs Organization in hREA.

Organization Entry Structure (Current Implementation)

#![allow(unused)]
fn main() {
pub struct Organization {
  /// Organization's official name
  pub name: String,
  /// Detailed description of the organization
  pub description: String,
  /// Optional organization logo/image
  pub picture: Option<SerializedBytes>,
  /// Organization's contact email
  pub email: String,
  /// Optional phone number
  pub phone: Option<String>,
  /// Website URL
  pub website: String,
  /// Geographic location
  pub location: String,
}
}

Organization Fields Description

• name: Official organization name
• description: (String, max 1000 chars) Detailed description of the organization's mission, activities, and focus (supports markdown)
• picture: Optional organization logo or representative image
• email: Primary contact email for the organization
• phone: Optional phone number for contact
• website: Organization's website URL
• location: Geographic location or area of operation

Organization Features

• User-created entities
• Project management capabilities
• Member management
• Category classification

Organization Links

• AllOrganizations: Link to organizations anchor
• OrganizationCoordinators: Organization → coordinators
• OrganizationMembers: Organization → members
• OrganizationContacts: Organization → contact person (tag = role)
• OrganizationProjects: Organization → projects
• OrganizationCategories: Organization → categories
• OrganizationRequests: Organization → requests
• OrganizationOffers: Organization → offers

2.4 Contact Person Designation

Organizations can designate a single coordinator as their public-facing contact person.

Features

• Single contact per organization: Setting a new contact replaces the previous one
• Coordinator-only: Only coordinators can be designated as the contact person
• Role/title: Free-text field for the contact's role (e.g. Director, President)
• Auto-cleanup: Contact links removed automatically when the contact leaves, is removed, or the organization is deleted
• Optional during creation: Creator can set themselves as contact during organization creation

Contact Functions

• set_organization_contact: Set or replace the contact person with a role
• remove_organization_contact: Remove the current contact person
• get_organization_contact: Retrieve the contact person and their role
• is_organization_contact: Check if a user is the contact person

2.3 Coordinator Management

Responsibilities

• Project/Organization representation
• Organization/Project profile management
• Member invitation and approval
• Request/Offer management on behalf of the organization/project

Features

• Network administrator approval required
• Organization/Project profile customization (description, type, skills needed, etc.)
• Request/Offer creation capabilities for the organization/project
• Member invitation and approval management

3. Requests and Offers

3.1 Core Functionality

• hREA integration for economic activities
• Request creation linked to projects/organizations/service types
• Offer creation linked to requests/projects
• Implementation as hREA intents and proposals

3.2 Request System

Request Entry Structure (Current Implementation)

#![allow(unused)]
fn main() {
pub struct Request {
  /// The title of the request
  pub title: String,
  /// A detailed description of the request
  pub description: String,
  /// The contact preference for the request
  pub contact_preference: ContactPreference,
  /// The date range for the request
  pub date_range: Option<DateRange>,
  /// The estimated time in hours to complete the request
  pub time_estimate_hours: Option<f32>,
  /// The preferred time of day for the request
  pub time_preference: TimePreference,
  /// The time zone for the request
  pub time_zone: Option<TimeZone>,
  /// The exchange preference for the request
  pub exchange_preference: ExchangePreference,
  /// The interaction type for the request
  pub interaction_type: InteractionType,
  /// Generic links related to the request
  pub links: Vec<String>,
}
}

Supporting Enums and Types

#![allow(unused)]
fn main() {
pub enum ContactPreference {
  Email,
  Phone,
  Other(String),
}

pub enum ExchangePreference {
  Exchange,
  Arranged,
  PayItForward,
  Open(),
}

pub enum InteractionType {
  Virtual,
  InPerson,
}

pub enum TimePreference {
  Morning,
  Afternoon,
  Evening,
  NoPreference,
  Other(String),
}

pub struct DateRange {
  pub start: Option<Timestamp>,
  pub end: Option<Timestamp>,
}

pub type TimeZone = String;
}

Note: Service Types integration is handled through separate linking mechanisms rather than direct embedding in the Request structure. The Service Types system provides tag-based discovery and categorization.

Request Features

• Creation: By individual users or organizations
• Validation: Title and description are required; description limited to 1000 characters
• Lifecycle: Full status tracking, update, and deletion capabilities
• Service Type Integration: Linked through separate mechanisms for flexible categorization

Current Field Descriptions:

• title: (String) The title of the request - required field
• description: (String, max 1000 chars) A detailed description of the request (supports markdown) - required field
• contact_preference: (ContactPreference enum) How the requester prefers to be contacted (Email, Phone, Other)
• date_range: (Optional DateRange) Timeframe when the service is needed with start/end timestamps
• time_estimate_hours: (Optional f32) Estimated time in hours to complete the request
• time_preference: (TimePreference enum) Preferred time of day (Morning, Afternoon, Evening, NoPreference, Other)
• time_zone: (Optional String) Requester's time zone
• exchange_preference: (ExchangePreference enum) How the requester prefers to reciprocate (Exchange, Arranged, PayItForward, Open)
• interaction_type: (InteractionType enum) Whether virtual or in-person interaction
• links: (Vec) Generic links for extensibility and integration

Service Types Integration: Service types are linked to requests through separate linking mechanisms rather than direct embedding, enabling flexible categorization and tag-based discovery.

Request Links

• AllRequests: Links to requests anchor (global request index)
• UserRequests: User → requests created by that user
• OrganizationRequests: Organization → requests associated with it
• RequestCreator: Request → its creator user profile
• RequestOrganization: Request → its associated organization (if any)
• RequestUpdates: Original request action → update actions
• RequestServiceTypes: Request → linked approved service types

3.3 Offer System

Offer Entry Structure (Current Implementation)

#![allow(unused)]
fn main() {
pub struct Offer {
  /// The title of the offer
  pub title: String,
  /// A detailed description of the offer
  pub description: String,
  /// The preferred time of day for the offer
  pub time_preference: TimePreference,
  /// The time zone for the offer
  pub time_zone: Option<TimeZone>,
  /// The exchange preference for the offer
  pub exchange_preference: ExchangePreference,
  /// The interaction type for the offer
  pub interaction_type: InteractionType,
  /// Generic links related to the offer
  pub links: Vec<String>,
}
}

Note: Service Types integration is handled through separate linking mechanisms rather than direct embedding in the Offer structure. The Service Types system provides tag-based discovery and categorization. Offers use the same supporting enums and types as Requests (see above).

Offer Features

• Creation: By individual users or organizations
• Validation: Title and description are required; description limited to 1000 characters
• Lifecycle: Full status tracking, update, and deletion capabilities
• Service Type Integration: Linked through separate mechanisms for flexible categorization

Current Field Descriptions

• title: (String) The title of the offer - required field
• description: (String, max 1000 chars) A detailed description of the offer (supports markdown) - required field
• time_preference: (TimePreference enum) Preferred time of day (Morning, Afternoon, Evening, NoPreference, Other)
• time_zone: (Optional String) Offerer's time zone
• exchange_preference: (ExchangePreference enum) How the offerer prefers to reciprocate (Exchange, Arranged, PayItForward, Open)
• interaction_type: (InteractionType enum) Whether virtual or in-person interaction
• links: (Vec) Generic links for extensibility and integration

Service Types Integration: Service types are linked to offers through separate linking mechanisms rather than direct embedding, enabling flexible categorization and tag-based discovery.

Offer Links

• AllOffers: Links to offers anchor (global offer index)
• UserOffers: User → offers created by that user
• OrganizationOffers: Organization → offers associated with it
• OfferCreator: Offer → its creator user profile
• OfferOrganization: Offer → its associated organization (if any)
• OfferUpdates: Original offer action → update actions
• OfferServiceTypes: Offer → linked approved service types
• OfferRequests: Offer → requests it responds to (future enhancement)

3.4 Request-Offer Matching

Matching Process

• Manual matching in initial implementation
• Service Type-based discovery and matching:
  • Direct service type alignment between requests and offers
  • Tag-based discovery for related content
  • Cross-entity navigation through shared service types
• Future algorithmic matching based on:
  • Service type compatibility scoring
  • Tag similarity analysis
  • Availability/urgency compatibility
  • User/organization preferences

Proposal Formation

• When a request and offer are matched, a proposal is formed
• Proposal represents the potential agreement between parties
• Both parties must confirm to create an agreement
• Agreement leads to commitments and economic events

Matching Links

• RequestOffers: Request → offers submitted to it
• OfferRequests: Offer → requests it's submitted to
• ProposalRequest: Proposal → originating request
• ProposalOffer: Proposal → originating offer

3.5 Exchange Completion & Feedback-Driven Fulfillment

POST-MVP FEATURE: The exchange completion and feedback system described below has been moved to post-MVP development. This functionality will be implemented after the simplified MVP has been validated with users.

Based on the hREA mapping and exchange process clarifications, the completion process implements a feedback-driven economic flow:

Feedback Process Workflow

1. Work Completion: Service provider completes the committed work
2. Feedback Request: Provider can request feedback from the recipient
3. Feedback Provision: The agent who initiated the request (or accepted the offer) provides feedback
4. Conditional Fulfillment: Economic events are created only if feedback is positive
5. Resolution Process: Negative feedback triggers mediation before fulfillment

Feedback Rights and Responsibilities

• Feedback Providers:
  • Agent who initiates a request (provides feedback on received service)
  • Agent who accepts an offer (provides feedback on delivered outcome)
• Feedback Requesters:
  • Agent performing work on a request
  • Agent providing service from an offer
• Quality Assurance: Feedback acts as a quality gate for commitment fulfillment

Feedback Data Structure

interface FeedbackProcess {
  id: string;
  commitmentId: string;
  requesterId: AgentId; // Who can request feedback
  providerId: AgentId; // Who provides feedback
  status: "pending" | "requested" | "completed";
  feedback?: FeedbackEntry;
}

interface FeedbackEntry {
  rating: "positive" | "negative";
  comments: string;
  timestamp: Date;
  providedBy: AgentId;
}

Economic Event Creation

• Conditional Events: Economic events fulfill commitments only after positive feedback
• Quality Assurance: Negative feedback triggers resolution processes
• hREA Integration: Economic events properly fulfill hREA commitments and affect resources
• Dispute Resolution: Mediation mechanisms for negative feedback resolution

3.6 Types of Support Requested

4. Service Types and Tag-Based Discovery

4.1 Service Types System

Service Types are implemented as Resource Specifications in hREA, providing a comprehensive moderation workflow and tag-based discovery system for categorizing and organizing services, skills, and resources across the platform.

Core Features

• User Suggestions: Any authenticated user can suggest new service types via suggest_service_type()
• Admin Moderation: Complete workflow with pending, approved, and rejected states managed through dedicated admin functions
• Tag-Based Discovery: Comprehensive tagging system with path anchor indexing for efficient search and cross-entity discovery
• Cross-Entity Integration: Full integration with requests, offers, and discovery workflows through cross-zome linking
• Quality Assurance: Only approved service types can be used in new requests and offers, enforced at the zome level

Service Type Structure (Current Implementation)

#![allow(unused)]
fn main() {
pub struct ServiceType {
    pub name: String,        // E.g., "Web Development", "Graphic Design", "Childcare"
    pub description: String, // Detailed explanation of the service type (max 500 chars)
    pub tags: Vec<String>,   // Keywords for searchability, e.g., ["svelte", "rust", "holochain"]
}
}

Validation Rules

• name: Required, non-empty, maximum 100 characters
• description: Required, non-empty, maximum 500 characters (supports markdown)
• tags: Optional vector, individual tags normalized (lowercase, trimmed), no empty strings or duplicates

Status Management Workflow

Service Types follow a three-state validation workflow managed through path anchors:

• Pending (service_types.status.pending): User-suggested service types awaiting admin review
• Approved (service_types.status.approved): Admin-approved service types available for use in requests/offers
• Rejected (service_types.status.rejected): Admin-rejected service types with optional reasoning

Admin Functions

• create_service_type(): Direct creation and immediate approval by administrators
• approve_service_type(): Approve pending service types, creates tag anchor links
• reject_service_type(): Reject service types, triggers cross-zome cleanup
• update_service_type(): Update existing service types with tag link management
• delete_service_type(): Delete service types with comprehensive cleanup

4.2 Tag-Based Discovery System

Path Anchor Architecture

• Tag Anchors: Dynamic paths (service_types.tags.{url_encoded_tag_string}) linking approved service types to specific tags
• All Tags Anchor: Static path (service_types.all_tags) maintaining unique tag registry
• Cross-Zome Integration: Tag-based discovery extends to requests and offers through linking mechanisms

Discovery Functions

• get_service_types_by_tag(): Retrieve approved service types for a specific tag
• get_service_types_by_tags(): AND logic search across multiple tags
• get_all_unique_tags(): List all tags currently associated with approved service types
• search_tags_by_prefix(): Real-time tag suggestions with prefix matching for autocomplete

Tag Management Features

• Dynamic Tag Creation: Tags are created when service types are approved, automatically indexed
• Automatic Cleanup: Tag links removed when service types are rejected or deleted
• Orphan Detection: Automatic removal of tags no longer associated with any approved service types
• Cross-Entity Discovery: Find requests and offers through service type tag relationships
• Tag Statistics: Usage analytics and popularity metrics for tag cloud weighting

4.3 User Workflow

For General Users

1. Suggest Service Types: Submit suggestions with name, description, and tags
2. Browse Approved Types: View and search approved service types
3. Tag-Based Discovery: Explore content through tag navigation
4. Use in Requests/Offers: Select approved service types when creating content

For Administrators

1. Review Suggestions: Access dedicated moderation interface for pending items
2. Approve/Reject: Make decisions with optional reasoning
3. Direct Creation: Create and immediately approve service types
4. Bulk Operations: Manage multiple service types efficiently
5. Analytics Dashboard: View usage statistics and system health metrics

4.4 UI Components and Pages

Public Interface Pages

• Service Types Listing (/service-types): Browse and search approved service types with tag-based filtering
• Service Type Details (/service-types/[id]): Individual service type information with related requests/offers
• Suggestion Form (/service-types/suggest): User-facing suggestion interface with validation
• Tag Discovery (/tags/[tag]): Tag-based content discovery showing related requests, offers, and service types

Admin Interface Pages

• Admin Dashboard (/admin/service-types): Complete management interface with statistics and bulk operations
• Moderation Queue (/admin/service-types/moderate): Dedicated pending suggestions review interface
• Direct Creation (/admin/service-types/create): Admin service type creation with immediate approval
• Detail Management (/admin/service-types/[id]): Individual item management with moderation actions

Core UI Components

• ServiceTypeCard.svelte: Display component with status indicators, tags, and navigation actions
• ServiceTypeSelector.svelte: Multi-select component for forms with search and filtering capabilities
• ServiceTypeSuggestionForm.svelte: Complete form for user suggestions with validation (500 char limits)
• ServiceTypeList.svelte: Filterable lists with status-based organization

Tag-Based Discovery Components

• TagAutocomplete.svelte: Real-time tag suggestion with debounced search and prefix matching
• TagCloud.svelte: Visual tag cloud weighted by popularity statistics
• TagDetailsView.svelte: Comprehensive view showing all content associated with a specific tag
• TagNavigationBar.svelte: Navigation component for tag-based browsing with breadcrumbs

Admin Interface Components

• ServiceTypeAdminDashboard.svelte: Complete dashboard for moderators with statistics and bulk operations
• ServiceTypeModerationCard.svelte: Specialized card for admin review workflow with approve/reject actions

4.5 Integration with Requests and Offers

Request Integration

• Service Selection: Choose from approved service types when creating requests
• Tag Discovery: Find related requests through service type tags
• Requirement Specification: Link requests to specific service type requirements

Offer Integration

• Capability Declaration: Specify offered services using approved service types
• Skill Matching: Match offers to requests based on service type alignment
• Tag-Based Promotion: Discover offers through service type tag navigation

4.6 Technical Implementation

Backend (Holochain Zomes)

• service_types_integrity: Entry definitions, validation rules, and link types
• service_types_coordinator: Business logic, moderation workflow, and external functions
• Cross-Zome Integration: Validation and cleanup coordination with requests/offers zomes

Frontend (SvelteKit + Effect TS)

• Service Layer: Effect TS-based service with dependency injection
• Store Management: Reactive Svelte stores with caching and event bus integration
• Component Library: Comprehensive UI components for all user interactions
• Type Safety: Complete TypeScript integration with Effect TS error handling

Performance Optimizations

• Path Anchor Indexing: Efficient tag-based queries and discovery
• Caching Strategy: Service and store-level caching with intelligent invalidation
• Lazy Loading: On-demand loading of large datasets with pagination support
• Event-Driven Updates: Real-time state synchronization across components

4.5 Reporting Features

User Reports

• Personal exchange history
• Monthly activity summaries
• Project contribution tracking
• Service Types utilization metrics

Administrative Reports

• Network activity metrics
• User verification status
• Project status tracking
• Exchange completion rates
• Moderation action logs

5. Search Functionality

5.1 Search Capabilities

Each major section includes search functionality:

User Search

• Name
• Service types (through associated requests/offers)
• Tags (from service type associations)
• Location
• Organizations
• Projects

Project Search

• Name
• Organization
• Status
• Service types (through associated requests/offers)
• Tags (from service type associations)

Organization Search

• Name
• Members
• Projects
• Service types (through associated requests/offers)
• Tags (from service type associations)

Request/Offer Search

• Service types (approved only)
• Tags (from associated service types)
• Status
• Associated project/organization
• Tag-based discovery and navigation
• Cross-entity search through service type relationships

6. Network Administration

6.0 Network Creation & Joining (Kangaroo)

The following UX is implemented in the Kangaroo (Electron) host app, not in the Svelte UI. It runs before the hApp is installed.

References: #5 (progenitor backend), #45 (integrity validation), #95 (full UX spec)

Splash Screen (first launch)

On first launch (no network installed), Kangaroo shows three options:

• Create Network — for community founders who want to start a new requests-and-offers network
• Join Network — for members who received an invite (DNA hash / QR code) from a founder
• Join Holochain Pilot — joins the pre-bundled community pilot network; no invite needed

Create Network Flow

1. Kangaroo reads the agent pubkey from the conductor admin WebSocket API
2. Installs the hApp with DNA properties: { progenitor_pubkey: <agent_pubkey> }
3. Reads the resulting DNA hash from the conductor
4. Displays the DNA hash as:
   • A copyable string
   • A QR code
5. The founder shares this hash/QR with their community

The progenitor's pubkey is now cryptographically bound to the network. No one else can become progenitor (see integrity validation in #45).

Join Network Flow

1. Member pastes the DNA hash or scans the QR code
2. Kangaroo installs the hApp targeting that exact DNA hash
3. Member is on the same DHT network as the founder
4. Member creates a profile → standard pending user (no admin role)

Membership Model

• Open network: anyone with the correct DNA hash can join — no membrane proof required
• Admin role is controlled by explicit administrator delegation, not by joining order

Multi-Network Support

• A user may join multiple networks (e.g., their own community + the pilot)
• Kangaroo provides a network switcher (sidebar or header dropdown) listing all installed networks
• Switching networks changes the active DNA context without restarting the conductor

Pre-loaded Networks

6.1 Core Administrative Features

• User and Organization verification
• Project verification
• Service Types Moderation: Complete workflow for reviewing, approving, and rejecting user-suggested service types
• Moderator role management
• Suspension system
• Flagging system
• Administrative inbox

6.2 User Interface

• Administration Dashboard
• User management interface
• Project/Organization management
• Service Types Moderation Interface: Dedicated tools for reviewing pending suggestions, bulk operations, and analytics
• Request/Offer moderation
• Tag-Based Discovery Tools: Administrative insights into tag usage, statistics, and content organization
• Search and reporting tools

7. Communication and Negotiation

7.1 Messaging System

POST-MVP FEATURE: The messaging system described below has been moved to post-MVP development. This functionality will be implemented after the simplified MVP has been validated with users.

• User-to-User Messaging: Allows users to communicate directly with one another, facilitating negotiations and discussions related to requests and offers.
• Administrative Communication: Provides a channel for users to send messages to network administrators through an inbox within the administration panel.
• Features:
  • Direct messaging between users
  • Negotiation support for requests/offers
  • Administrative communication channel
  • Message history tracking
  • Agreement finalization support

7.2 Notification System

• Suspension Notifications: Users receive notifications about account suspension status and reasons
• Exchange Updates: Notifications for request/offer matches and updates
• Administrative Alerts: Important system and moderation notifications
• Recovery Notifications: Updates about account recovery process

Simplified MVP Specifications

1. Introduction

The Requests & Offers - Simplified MVP project aims to develop a Holochain application designed to facilitate a simple bulletin board for requests and offers within the hAppenings.community. This document outlines the core requirements and objectives for the minimum viable product.

2. Objective

The primary objective is to create a simple, open-source Holochain application that enables Creators, Projects, and Developers to post requests for support and Advocates to post offers of support. The application will function as a bulletin board with direct contact facilitation.

3. Target Audience

• Holochain Creators/Projects/Developers: Individuals or groups actively developing projects within the Holochain ecosystem
• Holochain Advocates: Individuals passionate about supporting Holochain projects
• HoloHosts: Organizations or individuals hosting Holochain nodes

4. Core MVP Requirements

4.1 User Management

• Basic user registration and authentication
• User profile creation and management
• Role-based access control (Advocate, Creator, Administrator)
• Multi-device profile access

4.2 Request/Offer System

• Request creation and management
• Offer creation and management
• Simple browsing and search functionality
• Contact information display for direct communication

4.3 User Listing Management

• Archive own requests/offers
• Delete own requests/offers
• View personal listings dashboard

4.4 Administration

• User verification
• Basic moderation tools
• System configuration
• Essential reporting

4.5 Search and Discovery

• Basic search functionality
• Simple filtering options
• Category-based browsing

5. MVP Scope

5.1 Included Features

• Essential user management
• Core request/offer posting functionality
• Simple browsing and search capabilities
• Contact information display
• Archive/delete functionality for users
• Fundamental administrative tools

5.2 Excluded Features (Post-MVP)

• Exchange coordination system
• Proposal and agreement workflows
• In-app messaging
• Review and reputation systems
• Advanced matching algorithms
• Mutual Credit Currency components

6. Success Criteria

6.1 Functional Requirements

• Successful user registration and authentication
• Working request/offer creation and browsing
• Contact information clearly displayed
• Archive/delete functionality for users
• Essential administrative controls
• Simple search and discovery features

6.2 Performance Requirements

• Response time under 2 seconds for basic operations
• Support for multiple concurrent users
• Basic error handling and recovery
• Multi-device compatibility

6.3 User Experience Requirements

• Intuitive navigation
• Clear user feedback
• Basic responsive design
• Essential accessibility features

7. Conclusion

This simplified MVP specification focuses on the core value proposition: a bulletin board where users can post requests and offers with clear contact information for direct communication. By removing the complex exchange process, we can deliver value to users faster while gathering feedback for future enhancements.

The MVP prioritizes:

• Essential user management and authentication
• Core request and offer posting functionality
• Simple browsing and search capabilities
• Contact information display for direct communication
• Basic listing management (archive/delete)

Post-MVP versions will add the exchange coordination system, proposal workflows, in-app messaging, and other advanced features based on user feedback and community needs.

MVP Features

This document outlines the features included in the MVP version of the Requests and Offers application.

Core Features (Delivered)

1. Request Management

• Create new requests with title, description, tags
• View request details
• Archive own requests
• Delete own requests

2. Offer Management

• Create new offers with title, description, tags
• View offer details
• Archive own offers
• Delete own offers

3. Public Listing Views

• Browse all active requests
• Browse all active offers
• Search listings by keyword
• Filter listings by tags

4. Contact Information Display

• View contact information for request creators
• View contact information for offer providers
• Contact methods include email and phone (if provided)
• Organization contact information (if applicable)
• View designated organization contact person with role/title

5. User Dashboard

• View all own requests and offers
• Quick actions to archive/delete listings
• Simple status indicators (active/archived)

Upcoming MVP Features

6. hREA Completion & Real-time Signals

Milestone: MVP: hREA Completion & Real-time Signals

• Complete hREA entity mapping end-to-end (#1)
• Real-time signal integration throughout the application (#12)
• Action hash type safety improvements (#25)

7. Chat System

Milestone: MVP: Chat System

• 1-to-1 conversations initiated from request/offer listings (#91)
• Real-time messaging via Holochain signals
• Global notification system (#51)
• "Propose a Deal" action within conversation threads
• System messages for proposal lifecycle events

8. Exchange Process & Reputation

Milestone: MVP: Exchange Process & Reputation

• hREA Agreement/Commitment/EconomicEvent lifecycle (#90)
• Conversation-embedded proposals and negotiation
• Review and reputation system (star ratings, on-time/as-agreed flags)
• Administrator inbox and task management (#52)
• Administrator audit trail (#53)
• Feedback-conditional fulfillment gate

Future Features (Post-MVP)

These features will be implemented after the MVP:

• Advanced matching algorithms

MVP User Stories

This document describes the primary user journeys for the simplified MVP version.

Primary User Roles

Requester

A user who needs help or services from others in the community.

Provider

A user who offers help or services to others in the community.

User Stories

As a Requester

1. Create a Request

   • I want to post a request describing what I need
   • So that potential providers can see what I'm looking for

2. View My Requests

   • I want to see a list of my own requests
   • So that I can manage them

3. Archive a Request

   • I want to archive a request that's been fulfilled
   • So that it's no longer visible to the public but I can still reference it

4. Delete a Request

   • I want to permanently delete a request I no longer need
   • So that it's completely removed from the system

5. Browse Offers

   • I want to browse all active offers from providers
   • So that I can find someone who can help me

6. Contact a Provider

   • I want to see contact information for providers
   • So that I can reach out to them directly

As a Provider

1. Create an Offer

   • I want to post an offer describing what services I can provide
   • So that potential requesters can see what I'm offering

2. View My Offers

   • I want to see a list of my own offers
   • So that I can manage them

3. Archive an Offer

   • I want to archive an offer that's no longer available
   • So that it's no longer visible to the public but I can still reference it

4. Delete an Offer

   • I want to permanently delete an offer I no longer want to provide
   • So that it's completely removed from the system

5. Browse Requests

   • I want to browse all active requests from requesters
   • So that I can find someone I can help

6. Contact a Requester

   • I want to see contact information for requesters
   • So that I can reach out to them directly

Secondary User Stories

As Any User

1. Search Listings

   • I want to search requests and offers by keywords
   • So that I can quickly find relevant listings

2. Filter by Tags

   • I want to filter listings by tags/categories
   • So that I can narrow down to my areas of interest

3. View Contact Information

   • I want to see clear contact information for listings
   • So that I know how to get in touch

Contact Information Display

This document describes how contact information is displayed in the MVP version.

Purpose

The MVP focuses on facilitating direct communication between users by clearly displaying contact information. This removes the need for complex in-app messaging systems while still enabling connections.

Contact Information Fields

Required Information

• Username/display name
• Profile picture (if available)

Optional Information

• Email address
• Phone number
• Preferred contact method
• Organization name (if applicable)
• Organization contact info (if applicable)

Display Locations

Request Detail View

Contact information for the requester is displayed at the bottom of the request details page.

Offer Detail View

Contact information for the provider is displayed at the bottom of the offer details page.

Privacy Considerations

User Control

• Users can choose which contact methods to display
• Users can hide contact information entirely (though this reduces utility)
• All contact information is opt-in

Data Handling

• Contact information is only visible to logged-in users
• No public scraping of contact information is allowed
• Users can update their contact information at any time

UI Implementation

Contact Display Component

A standardized component displays contact information consistently:

• Clear visual separation from listing content
• Prominent "Contact" heading
• Standardized formatting for each contact method
• Links/buttons for easy contact initiation

Responsive Design

• Mobile-friendly contact display
• Appropriate sizing for different screen widths
• Accessible for users with disabilities

Post-MVP Features Overview

This directory contains documentation for features planned beyond the current MVP scope.

Re-scoped to MVP

The following features were originally post-MVP but have been re-scoped into the MVP based on project priorities:

1. Exchange Process - Conversation-first exchange coordination system (#90) — Milestone: MVP: Exchange Process & Reputation
2. Chat System - Conversation-first messaging with exchange integration (#91) — Milestone: MVP: Chat System
3. Reputation System - Review and rating mechanisms — Milestone: MVP: Exchange Process & Reputation

Note: Documentation remains in this directory for organizational continuity. These features are now actively targeted for MVP delivery.

Remaining Post-MVP Features

1. Matching System - Algorithmic matching of requests with offers

Implementation Approach

Post-MVP features will be implemented after the MVP has been validated with users:

• Gather feedback on core functionality
• Iterate on user experience
• Gradually add advanced features
• Maintain backward compatibility

Exchange Process Feature

Status: Re-scoped to MVP. Targeted for MVP: Exchange Process & Reputation milestone. See #90.

Overview

The Exchange Process is the core value exchange mechanism of the Requests and Offers application. This feature transforms static requests and offers into dynamic, managed transactions between community members, providing the economic coordination layer that enables actual value exchange within the peer-to-peer marketplace.

Architecture Strategy: hREA-First

Rather than building custom exchange zomes from scratch, this feature leverages the hREA (Holochain Resource-Event-Agent) DNA that is already integrated into the application. The hREA DNA provides built-in zomes for Agreement, Commitment, EconomicEvent, and Fulfillment -- covering the core economic coordination flow. Only the review/reputation system requires a lightweight custom zome, since subjective quality ratings are outside the ValueFlows ontology.

This approach:

• Minimizes custom Rust code by reusing battle-tested hREA zomes
• Aligns with ValueFlows -- the open vocabulary for distributed economic coordination
• Builds on existing infrastructure -- Proposals and Intents are already mapped via the hREA service and GraphQL layer
• Reduces maintenance burden -- hREA upstream improvements benefit the project automatically

Vision

The Exchange Process will evolve the platform from a simple bulletin board into a sophisticated economic coordination system enabling:

• Conversation-Driven Exchanges: Natural chat-first flow that progressively formalizes into hREA entities
• Structured Negotiations: Formal proposal and agreement workflows via hREA, triggered from within conversations
• Trust Building: Review and reputation systems (custom zome)
• Economic Coordination: Complete lifecycle management from conversation to completion

Core Value Proposition

• For Users: Simple, natural workflow — chat first, formalize when ready
• For Community: Trust-building through structured feedback and reputation
• For Platform: Foundation for economic activity and user engagement

Design Philosophy

Conversation-First Model (Simbi-Inspired)

Inspired by Simbi's skills exchange platform, the exchange process follows a conversation-first, proposal-second model. Rather than starting with formal hREA entities, users begin by chatting — discussing details, negotiating terms, and building trust — then optionally formalize their agreement through a "Propose a Deal" action within the conversation.

Core Principles

1. Chat Before Contract: Every exchange begins as a conversation, not a form submission
2. Optional Formalization: The hREA lifecycle (Proposal → Agreement → Commitment → EconomicEvent) is triggered from within conversations, not as a standalone flow
3. Context Preservation: The full conversation history accompanies every formal agreement
4. Human-Centered Flow: Technology adapts to how people naturally negotiate, not the other way around
5. Progressive Formalization: Informal chat → optional proposal → formal agreement → tracked fulfillment

User Action → hREA Entity Mapping

User Journey & Workflow

graph TD
    A[User Sees Request/Offer] --> B[Start Conversation]
    B --> C[Chat Freely - Discuss Details & Terms]
    C --> D{Ready to Formalize?}

    D -->|Yes| E[Click 'Propose a Deal' in Chat]
    D -->|Keep Chatting| C

    E --> F[Fill Proposal Details]
    F --> G[hREA Proposal Created - Status: Pending]

    G --> H[Other Party Reviews Proposal in Chat]
    H --> I{Decision}

    I -->|Accept| J[hREA Agreement Created with Commitments]
    I -->|Counter| K[Counter-Proposal Created in Chat]
    I -->|Decline| L[Continue Chatting or End]

    K --> H

    J --> M[Both Parties Work on Exchange]
    M --> N[Provider Records EconomicEvent]
    N --> O[Receiver Confirms Fulfillment]

    O --> P{Both Commitments Fulfilled?}
    P -->|Yes| Q[Exchange Complete - Review Phase]
    P -->|No| R[Wait for Other Party]
    R --> P

    Q --> S[Both Parties Submit Reviews]
    S --> T[Exchange Fully Closed]

    L --> U[End - No Deal Made]

Key User Actions

1. Conversing: Users start a conversation from a request/offer listing (#91)
2. Proposing: Either party creates a Proposal (hREA) from within the conversation via "Propose a Deal"
3. Negotiating: Accept, counter, or decline proposals — all within the chat thread
4. Agreeing: Acceptance creates an hREA Agreement bundling Commitments from both parties
5. Working: Both parties collaborate on the actual service/exchange
6. Completing: Each party records an EconomicEvent fulfilling their Commitment
7. Reviewing: Mutual feedback via the custom reviews system

Core Workflow Principles

• Conversation First: Exchange begins with human interaction, not form filling
• Creator Control: Request/offer creators choose their collaboration partners
• Progressive Formalization: Chat → Proposal → Agreement → Fulfillment
• Mutual Completion: Both parties must record fulfillment independently
• Quality Feedback: Review system as a conditional gate for economic events
• Comprehensive Dashboard: Clear overview of all exchange activities

hREA Mapping

How Exchange Concepts Map to ValueFlows

Data Linking Model

Cross-Entity Link Architecture

The conversation-first model creates bidirectional relationships between the chat layer (conversations zome) and the hREA economic layer. These links enable navigating from a conversation to the resulting agreement and back.

Conversation → Agreement Linking

When a counter-proposal is accepted and an Agreement is created:

1. The conversationId is stored in the Agreement's note field — giving the Agreement a permanent, human-readable reference to its originating conversation.
2. A ConversationToAgreement link is created in the requests_and_offers DNA, using the ActionHash of both entities as anchor and target. This link enables efficient bidirectional lookup without scanning all entries.

// conversationId flows from CounterProposalInput into Agreement creation
// Agreement.note stores the conversationId for human-readable reference
// ConversationToAgreement link in requests_and_offers DNA enables fast lookup

Cross-Reference Table

Lookup Functions

Two zome functions enable bidirectional navigation:

• get_conversation_for_agreement(agreement_id: ActionHash) → returns the conversationId from the Agreement's note field
• get_agreement_for_conversation(conversation_id: ActionHash) → traverses the ConversationToAgreement link to return the Agreement ActionHash

Economic Flow (hREA)

graph TD
    A[Alice - Agent] -- creates --> RP[Request Proposal + Intents]
    B[Bob - Agent] -- starts conversation about --> RP

    subgraph Conversation Thread
        CHAT[Chat: Discuss details & terms]
        PROPOSE[Bob clicks 'Propose a Deal']
        CHAT --> PROPOSE
        PROPOSE --> CP[Counter-Proposal + Intents]
    end

    B --> CHAT
    CP -- linked to --> RP

    CP -- approved, creates --> AG[Agreement]
    AG -- bundles --> C1[Commitment: Bob provides service]
    AG -- bundles --> C2[Commitment: Alice provides payment/exchange]

    C1 -- fulfilled by --> EE1[EconomicEvent: Service delivered]
    C2 -- fulfilled by --> EE2[EconomicEvent: Payment/exchange completed]

    EE1 --> F1[Fulfillment link]
    EE2 --> F2[Fulfillment link]

    F1 --> DONE[Agreement Complete]
    F2 --> DONE

    DONE --> REV[Review Phase - Custom Zome]
    REV -- conditional gate --> CLOSED[Exchange Closed]

Feedback-Conditional Fulfillment

As documented in the hREA Integration Specification, the feedback mechanism acts as a quality gate:

1. Work Completion: Provider completes committed work and records an EconomicEvent
2. Feedback Request: Provider can request feedback from recipient
3. Feedback Evaluation: Recipient provides positive/negative feedback via the custom reviews zome
4. Conditional Fulfillment: Full economic fulfillment is confirmed only with positive feedback
5. Resolution Process: Negative feedback triggers a resolution pathway before final fulfillment

Core Feature Set

1. Conversation-Based Proposal System (hREA Proposals)

Responses to listings are modeled as hREA Proposals with linked Intents, created from within conversation threads (#91). This uses the same GraphQL API already in place for request/offer creation.

// A counter-proposal is a new Proposal whose Intents reference
// the same ResourceSpecifications as the original listing.
// Created via "Propose a Deal" action within a conversation.

interface CounterProposalInput {
  originalProposalId: string;       // hREA ID of the request/offer
  conversationId: string;           // Conversation where the proposal was made
  description: string;
  timeEstimate?: number;
  mediumOfExchange?: string;        // ResourceSpecification ID
  customTerms?: string;
}

Capabilities:

• "Propose a Deal" action within conversation threads (relies on #91)
• Intents reference the same ResourceSpecifications as the original
• Track all proposals in unified dashboard
• Withdraw proposals before approval (delete hREA Proposal)
• Creator control over collaboration partner selection
• Status derived from hREA Proposal state
• Full conversation context preserved with every proposal

2. Agreement & Commitment System (hREA)

When a counter-proposal is approved, an hREA Agreement is created that bundles Commitments from both parties.

// Uses hREA Agreement GraphQL mutations (to be added)
// Agreement bundles Commitments via Satisfaction links to Intents

interface AgreementCreation {
  counterProposalId: string;        // The approved counter-proposal
  originalProposalId: string;       // The original request/offer
  conversationId: string;           // Stored in Agreement.note + creates ConversationToAgreement link
  // Commitments are auto-created from the Intents of both Proposals
}

Capabilities:

• Automatic Agreement creation upon counter-proposal approval
• Commitments derived from both parties' Intents
• Progress tracked via Fulfillment links (Commitment → EconomicEvent)
• Timeline tracking through EconomicEvent timestamps
• Full request/offer context preserved via Proposal references

3. Completion Tracking (hREA EconomicEvents)

Each party records an EconomicEvent when they fulfill their Commitment.

// Uses hREA EconomicEvent GraphQL mutations (to be added)

interface CompletionRecord {
  commitmentId: string;             // Which Commitment is being fulfilled
  note?: string;                    // Optional completion notes
  // Creates an EconomicEvent + Fulfillment link
}

Capabilities:

• Independent completion confirmation from both parties
• EconomicEvent records what actually happened
• Fulfillment links connect Events to Commitments
• Status derived from fulfillment state of all Commitments in the Agreement

4. Review & Feedback (Custom Zome)

This is the only custom Rust zome needed, since hREA/ValueFlows has no concept of subjective quality ratings. Reviews are triggered after both parties fulfill their Commitments, and act as a conditional gate for final economic fulfillment confirmation.

• Both parties submit a review after exchange completion
• Star ratings (1-5), "on time" and "as agreed" flags, optional comments
• Positive feedback confirms fulfillment; negative feedback triggers resolution

For the full review data model, reputation scoring, moderation, privacy considerations, and technical architecture, see the dedicated Reputation System document.

5. Exchange Dashboard

• Tabbed Interface: Conversations | Proposals | Active | Completed | Reviews
• Status Filtering: Real-time status-based filtering and display
• Search Capabilities: Find specific exchanges quickly
• User Statistics: Total exchanges, average rating, reputation metrics

┌───────────────────────────────────────────────────────┐
│  My Exchanges                                         │
├───────────────────────────────────────────────────────┤
│ ┌─────────────┬──────────┬────────┬──────────┬──────┐ │
│ │Conversations│Proposals │Active  │Completed │Reviews│ │
│ └─────────────┴──────────┴────────┴──────────┴──────┘ │
│                                                       │
│ [Exchange List/Grid View]                             │
│                                                       │
│ ┌─────────────────────────────────────────────────┐   │
│ │ Reputation Score: 4.8 ⭐                        │   │
│ │ Total Exchanges: 47                             │   │
│ │ Completion Rate: 96%                            │   │
│ └─────────────────────────────────────────────────┘   │
└───────────────────────────────────────────────────────┘

6. Communication System (Prerequisite)

The communication system is now a prerequisite for the exchange process, not a future feature. Conversations are the entry point for all exchanges.

See Chat System and Issue #91 for the full technical specification, including:

• 1-to-1 conversations initiated from request/offer listings
• "Propose a Deal" action within conversation threads
• System messages for proposal actions (accepted, countered, declined)
• Organization chat channels
• Real-time message delivery via Holochain signals

Advanced Features (Future)

7. Advanced Matching Algorithm

interface MatchingAlgorithm {
  serviceTypeAlignment: number;     // ResourceSpecification compatibility
  timeCompatibility: number;
  locationScore: number;
  trustCompatibility: number;       // Based on review reputation data
  preferenceMatch: number;
  calculateScore(): number;
}

• AI-powered suggestions
• Preference learning
• Compatibility scoring based on ResourceSpecifications
• Reputation-weighted matching via review data

8. Mutual Credit System

Could potentially leverage hREA's EconomicEvent and Resource tracking for credit flows.

interface MutualCreditAccount {
  holder: AgentPubKey;
  balance: number;
  creditLimit: number;
  transactions: CreditTransaction[];
  trustNetwork: TrustRelationship[];
}

interface CreditTransaction {
  id: ActionHash;
  from: AgentPubKey;
  to: AgentPubKey;
  amount: number;
  agreementId: string;              // hREA Agreement ID
  timestamp: Timestamp;
  status: TransactionStatus;
}

• Zero-sum credit creation
• Trust-based credit limits
• Transaction history via hREA EconomicEvents
• Balance management
• Network visualization

Future: Unyt Smart Agreements

Unyt is a Holochain-based decentralized accounting platform that provides Smart Agreements called RAVEs (Recorded Agreement, Verifiably Executed). RAVEs are similar to blockchain smart contracts but designed for Holochain's agent-centric architecture, using Rhai scripting for programmable business logic.

Potential Integration Points

• Agreement Enforcement: When an hREA Agreement is created, a RAVE could enforce its conditions programmatically (deadlines, quality gates, automatic fulfillment)
• Automated Fulfillment: RAVEs could auto-create EconomicEvents when both parties confirm completion
• Mutual Credit Bridge: Unyt already supports community currencies — potential backend for our medium-of-exchange system
• Dispute Resolution: Rhai scripts could automate timeout-based dispute triggers

RAVE Three-Layer Architecture

1. Reusable Code Templates — Pre-built Rhai scripts for common exchange patterns
2. Configured Agreements — Specific rules per exchange (inputs, logic, outputs)
3. SAVEDs (execution records) — Cryptographically signed, tamper-proof records of execution

See Issue #92 for the dedicated exploration and research tasks.

Technical Architecture

Backend: Hybrid hREA + Custom Zome

The exchange process uses a hybrid architecture: hREA handles the economic coordination flow, while a single custom zome handles reviews.

┌──────────────────────────────────────────────────┐
│ hREA DNA (existing, bundled)                     │
│                                                  │
│  ┌──────────┐  ┌────────────┐  ┌──────────────┐  │
│  │ Proposal │  │ Agreement  │  │ EconomicEvent│  │
│  │ + Intent │  │+Commitment │  │ +Fulfillment │  │
│  └──────────┘  └────────────┘  └──────────────┘  │
│  ┌─────────────────────┐  ┌───────────────┐      │
│  │ResourceSpecification│  │ Satisfaction  │      │
│  └─────────────────────┘  └───────────────┘      │
└──────────────────────────────────────────────────┘

┌──────────────────────────────────────────────────┐
│ requests_and_offers DNA (existing custom zomes)  │
│                                                  │
│  ┌──────────┐  ┌────────┐  ┌───────────────┐     │
│  │ requests │  │ offers │  │ service_types │     │
│  └──────────┘  └────────┘  └───────────────┘     │
│  ┌────────┐  ┌────────────────┐  ┌───────────┐   │
│  │ users  │  │ organizations  │  │   admin   │   │
│  └────────┘  └────────────────┘  └───────────┘   │
│  ┌─────────────────────┐  ┌─────────────────┐    │
│  │ mediums_of_exchange │  │    reviews      │    │
│  └─────────────────────┘  │  (NEW - custom) │    │
│                           └─────────────────┘    │
│  ┌─────────────────────┐                         │
│  │   conversations     │                         │
│  │  (NEW - #91)        │                         │
│  └─────────────────────┘                         │
└──────────────────────────────────────────────────┘

New custom zome: reviews

dnas/requests_and_offers/zomes/
├── integrity/reviews/
│   └── src/lib.rs          # ExchangeReview entry, validation, link types
└── coordinator/reviews/
    └── src/lib.rs          # CRUD handlers, reputation aggregation

hREA GraphQL operations to add (frontend only):

• Agreement: create, update, query
• Commitment: create, query
• EconomicEvent: create, query
• Fulfillment: create, query
• Satisfaction: create, query

Frontend (SvelteKit + Effect-TS 7-Layer Architecture)

Service Layer:

The exchange service orchestrates calls to both the hREA GraphQL API and the custom reviews zome.

export const ExchangeService = Context.GenericTag<ExchangeService>("ExchangeService");

export const makeExchangeService = Effect.gen(function* () {
  const hrea = yield* HREAService;          // Existing hREA GraphQL service
  const client = yield* HolochainClientService; // For custom reviews zome

  // hREA operations (via GraphQL)
  const createCounterProposal = (input: CounterProposalInput) => ...
  const approveProposal = (id: string) => ...     // Creates Agreement + Commitments
  const rejectProposal = (id: string) => ...      // Withdraws/deletes Proposal
  const getAgreement = (id: string) => ...
  const recordCompletion = (commitmentId: string) => ... // Creates EconomicEvent
  const getExchangeStatus = (agreementId: string) => ... // Checks Fulfillment state

  // Custom reviews zome operations (see reputation-system.md for details)
  const submitReview = (input: CreateReviewInput) => ...
  const getReviews = (agreementId: ActionHash) => ...
  const getReputation = (agentPubKey: AgentPubKey) => ...

  return { createCounterProposal, approveProposal, rejectProposal,
           getAgreement, recordCompletion, getExchangeStatus,
           submitReview, getReviews, getReputation };
});

Store Layer:

• Svelte 5 Runes reactive state management
• All 9 standardized helper functions implemented
• Cache management with TTL and sync helpers
• Status-aware event emission system
• Combines hREA data (agreements, fulfillments) with custom data (reviews)

Component Library:

components/exchanges/
├── proposals/
│   ├── CounterProposalForm.svelte
│   ├── ProposalCard.svelte
│   └── ProposalManager.svelte
├── agreements/
│   ├── AgreementDashboard.svelte
│   ├── AgreementTimeline.svelte
│   └── CompletionConfirm.svelte
├── reviews/                       (see reputation-system.md)
│   ├── ReviewForm.svelte
│   ├── StarRating.svelte
│   └── ReputationDisplay.svelte
└── credit/                        (future)
    ├── BalanceDisplay.svelte
    ├── TransactionHistory.svelte
    └── CreditNetwork.svelte

Performance Optimizations:

• Cache strategy with module-level cache (5 minutes default TTL)
• Comprehensive loading/error state management
• Sub-2-second dashboard load times
• Responsive design for mobile and desktop

Integration Points

• Chat System (#91): Conversations are the entry point — proposals created from within chat threads
• hREA DNA: Agreement, Commitment, EconomicEvent, Fulfillment via GraphQL
• Request/Offer Domains: Proposals linked via hREA Intent references
• User/Organization System: Agents mapped to hREA Agents (already implemented)
• Service Types / MoE: Mapped to hREA ResourceSpecifications (already implemented)
• Administration: Platform-level moderation only (user approval, service type management) — administrators do NOT have access to private exchange data (see Privacy Model)
• Navigation: "My Exchanges" in primary nav, deep linking, breadcrumbs, URL state

Current Status

• hREA DNA: Bundled and integrated with Proposal, Intent, Agent, ResourceSpecification operations working
• hREA GraphQL: Agreement, Commitment, EconomicEvent, Fulfillment, Satisfaction operations not yet added
• Custom reviews zome: Not yet implemented
• Chat system (#91): Not yet implemented — prerequisite for conversation-first flow
• Exchange UI: Removed -- ready for fresh rebuild

Next Steps

1. Implement the chat system (#91) — prerequisite for conversation-first exchange flow
2. Add GraphQL mutations/queries/fragments for Agreement, Commitment, EconomicEvent, Fulfillment, Satisfaction
3. Extend the hREA service (hrea.service.ts) with the new operations
4. Implement the lightweight reviews custom zome (integrity + coordinator)
5. Build the ExchangeService orchestrating hREA + reviews
6. Create the exchange store with Svelte 5 Runes
7. Design and build UI components (integrated with conversation threads)
8. Implement routing and navigation
9. Add comprehensive testing

Implementation Roadmap

Phase 0: Chat System (Prerequisite)

Issue #91 must be substantially complete before exchange features can be built. The conversation system provides:

• 1-to-1 conversations initiated from request/offer listings
• "Propose a Deal" action within conversation threads
• System messages for proposal lifecycle events
• Real-time message delivery

Phase 1: hREA Exchange Foundation

• Add Agreement, Commitment, EconomicEvent GraphQL operations
• Extend hREA service and store
• Build "Propose a Deal" flow within conversation threads (relies on #91)
• Implement approval → Agreement creation workflow (triggered from chat acceptance)
• Build completion tracking via EconomicEvent + Fulfillment

Phase 2: Reviews & Reputation (Custom Zome)

• Implement reviews integrity + coordinator zome
• Add review service and store (Effect-TS)
• Build review UI components (StarRating, ReviewForm, ReputationDisplay)
• Integrate feedback-conditional fulfillment gate
• Exchange dashboard UI

Phase 3: Advanced Features

• Matching algorithm (leveraging ResourceSpecification compatibility + reputation data)
• Advanced search and discovery
• Analytics dashboard

Phase 4: Future Explorations

• Unyt Smart Agreements: Programmatic agreement enforcement via RAVEs (see #92)
• Mutual Credit System: Potentially via hREA EconomicEvent tracking or Unyt community currencies
• AI-Powered Matching: Intelligent pairing based on conversation history and reputation

Success Metrics

User Engagement

• Conversation-to-proposal conversion rate
• Agreement completion rate
• Review submission rate
• User retention

Quality Metrics

• Average review score
• Dispute rate
• Time to completion
• Match success rate

Economic Metrics

• Total value exchanged
• Credit velocity
• Network growth rate
• Active user ratio

Technical Considerations

Performance

• Lazy loading for large datasets
• Pagination for exchange history
• Caching strategy for reputation scores
• GraphQL query optimization for hREA operations

Security

• hREA validation rules enforce economic integrity
• Custom zome validation prevents review tampering
• Feedback-conditional fulfillment as quality gate
• Dispute resolution process

Privacy Model (Critical)

All exchange data is private to the two exchange parties only. This is a fundamental design requirement enforced at the zome level, not a frontend concern.

What is private:

• Conversations (all messages, proposal actions, negotiation history)
• Counter-proposals and their terms
• Agreements and all associated data
• Commitments (what each party is obligated to deliver)
• Economic Events (records of actual fulfillment)
• Fulfillment links and completion records
• Reviews tied to a specific exchange

Administrator exclusion — by design:

• The Administration role covers platform-level moderation only: user approval/suspension, service type management, organization oversight
• Administrators have NO ACCESS to exchange data — this is enforced at the zome level, not the frontend
• No get_agreement, get_commitment, or get_economic_event zome functions are accessible to admin capability tokens
• This design is intentional: peer-to-peer exchanges are private contracts between two consenting parties

Enforcement mechanism:

• Private Holochain entries restricted to exchange participants via capability tokens
• get_* zome functions for exchange entities validate the calling agent is a named participant
• The conversations zome restricts message/conversation access to participants only
• ConversationToAgreement links are only traversable by the conversation participants

Scalability

• DHT sharding strategy (inherited from hREA)
• Cross-DNA indexing for hREA ↔ custom zome references
• Query performance tuning
• State management efficiency

Dependencies

Technical:

• hREA DNA with Agreement, Commitment, EconomicEvent zomes
• @valueflows/vf-graphql-holochain GraphQL layer
• Effect-TS error handling
• SvelteKit frontend

Feature:

• Chat/Conversation system (#91) — prerequisite for conversation-first flow
• User authentication system (existing)
• Request/Offer foundation (existing)
• Service types → ResourceSpecifications mapping (existing)
• hREA Agent mapping (existing)

References:

• hREA GitHub
• ValueFlows Ontology
• hREA Integration Specification
• Simbi — conversation-first UX inspiration
• Unyt Accounting — Smart Agreements exploration (#92)

Matching System

This document describes the algorithmic matching system planned for post-MVP implementation.

Overview

The matching system will automatically suggest relevant connections between requests and offers based on:

• Semantic content analysis
• User preferences and history
• Geographic proximity
• Reputation scores

Matching Algorithms

Content-Based Matching

• Keyword analysis
• Tag similarity
• Category matching
• Semantic understanding

Collaborative Filtering

• User behavior patterns
• Similar user preferences
• Historical matching success
• Community trends

Contextual Matching

• Time sensitivity
• Geographic relevance
• Availability windows
• Resource constraints

Implementation Phases

Phase 1: Basic Tag Matching

• Simple tag-based suggestions
• Category filtering
• Manual feedback incorporation

Phase 2: Semantic Analysis

• Natural language processing
• Intent recognition
• Context understanding

Phase 3: Machine Learning

• Predictive matching
• Personalization algorithms
• Continuous improvement

User Interface

Matching Dashboard

• Suggested connections
• Matching confidence scores
• Quick action buttons
• Feedback mechanisms

Notification System

• Match alerts
• Preference updates
• Performance reports

Privacy Considerations

Data Usage

• Transparent matching criteria
• User-controlled preferences
• Opt-out mechanisms
• Data minimization

Consent

• Explicit matching consent
• Preference management
• Feedback control

Related Issues

• #90 — hREA Exchange Process (matching feeds into proposal discovery)
• #91 — Chat System (matched users start conversations)
• #92 — Unyt Smart Agreements Exploration (future)

Chat System: Conversation-First Messaging

Status: Re-scoped to MVP. Targeted for MVP: Chat System milestone. See #91.

Overview

The chat system provides conversation-first messaging that serves as the entry point for all exchanges. Inspired by Simbi's model where conversations precede proposals, this system enables users to discuss, negotiate, and build trust before optionally formalizing exchanges through hREA.

Core principle: Conversations are the primary unit. Proposals (hREA) are optional actions embedded within chat threads, not standalone entities.

User finds Request/Offer → Starts Conversation → Chat freely →
  Optionally Propose Deal → Accept/Counter/Decline → Complete Exchange

See Issue #91 for the full technical specification, architecture design, and implementation phases.

Design Philosophy

• Chat Before Contract: Every exchange begins as a conversation, not a form
• Optional Formalization: hREA proposals are created from within chat, not as standalone flows
• Context Preservation: Full conversation history accompanies every formal agreement
• Human-Centered: Technology adapts to natural negotiation patterns

Core Features

Real-time Communication

• Instant messaging with Holochain signal-based delivery
• Typing indicators (ephemeral signals, ZipZap pattern)
• Message status (sent/received/read)
• Online presence

Rich Content

• Markdown support in messages
• File attachments (via holochain-open-dev/file-storage)
• System messages for proposal actions ("User proposed a deal", "Proposal accepted")
• Reply-to threading within conversations

Conversation Management

• Conversations linked to specific requests/offers
• Organization chat channels (Simbi-inspired public walls)
• Searchable message history
• Notification controls

Conversation-Exchange Integration

graph LR
    A[Conversation Created] --> B[Users Chat Freely]
    B --> C{Propose a Deal?}
    C -->|Yes| D[hREA Proposal Created]
    C -->|Not Yet| B
    D --> E[System Message Posted]
    E --> F{Accept / Counter / Decline}
    F -->|Accept| G[Agreement + Commitments Created]
    F -->|Counter| D
    F -->|Decline| B
    G --> H[Exchange Tracked via hREA]

Security and Privacy

End-to-End Encryption

• Message encryption via Holochain's agent-centric security model
• Cryptographic signing of all messages
• Conversation access restricted to participants

Access Controls

• Only participants can read/write messages
• Organization channel moderation by coordinators/admins
• User blocking capabilities
• Message retention policies

Implementation Reference

The full technical specification lives in Issue #91, including:

• Backend architecture (integrity + coordinator zomes)
• Volla Messages patterns (time-bucketed indexing, signal lifecycle)
• ZipZap patterns (ephemeral signals for typing indicators)
• Vines patterns (bead-thread model for rich message types)
• Frontend 7-layer Effect-TS implementation
• 10-phase implementation roadmap

Key References

• Volla Messages: https://github.com/holochain-apps/volla-messages (primary Holochain chat reference)
• Vines: https://github.com/lightningrodlabs/vines (bead-thread conceptual model)
• ZipZap: https://github.com/lightningrodlabs/zipzap (ephemeral signal pattern)
• Simbi: https://simbi.com (conversation-first UX inspiration)

Related Issues

• #90 — hREA Exchange Process (proposals and agreements triggered from conversations)
• #91 — Chat System implementation (full technical specification)
• #92 — Unyt Smart Agreements exploration (future agreement enforcement)

Review & Reputation System

Status: Re-scoped to MVP. Part of MVP: Exchange Process & Reputation milestone. See #90.

Overview

The Review & Reputation System provides trust signals for users based on exchange outcomes. It is the only custom Rust zome required for the exchange process, since hREA/ValueFlows covers the economic coordination flow but has no concept of subjective quality ratings.

This system is tightly coupled with the Exchange Process: reviews are triggered after both parties fulfill their Commitments in an hREA Agreement, and positive feedback acts as a conditional gate for final economic fulfillment confirmation.

Scope

• Exchange Reviews: Post-completion feedback between exchange parties (core)
• Reputation Scoring: Aggregated trust metrics derived from review data
• Moderation: Quality control, spam prevention, dispute handling
• Privacy & Fairness: Bias prevention and data protection

Review System

Data Model

Backend (Custom Zome)

#![allow(unused)]
fn main() {
// Integrity zome: reviews_integrity

#[hdk_entry_helper]
struct ExchangeReview {
    agreement_id: ActionHash,       // References the hREA Agreement
    reviewer: AgentPubKey,
    reviewed: AgentPubKey,
    rating: u8,                     // 1-5 stars
    on_time: bool,
    as_agreed: bool,
    comments: Option<String>,       // Max 200 chars
}

// Link types:
// - AgreementToReview: find reviews for a given exchange
// - AgentToReview: find all reviews for a given user (reputation queries)
}

Frontend Types

interface ExchangeReview {
  id: ActionHash;
  agreementId: string;              // hREA Agreement ID
  reviewer: AgentPubKey;
  reviewed: AgentPubKey;
  rating: number;                   // 1-5 stars
  feedback: {
    onTime: boolean;
    asAgreed: boolean;
    comments?: string;              // Max 200 chars
  };
  createdAt: Timestamp;
}

Rating Structure

• Star Rating: 1-5 scale for overall service quality
• On Time: Boolean -- was the exchange completed within the agreed timeframe?
• As Agreed: Boolean -- did the outcome match what was committed?
• Comments: Optional free-text feedback (max 200 characters)

Review Criteria

Review Workflow

1. Both parties fulfill their Commitments (EconomicEvents recorded in hREA)
2. Exchange enters "Review Phase" -- both parties are prompted to submit reviews
3. Reviews are submitted independently (mutual review requirement)
4. Positive feedback confirms final economic fulfillment
5. Negative feedback triggers the resolution process before fulfillment is confirmed
6. Ratings are aggregated into the user's reputation score

Feedback-Conditional Fulfillment

As documented in the hREA Integration Specification:

• Positive feedback confirms that the EconomicEvent truly fulfills the Commitment
• Negative feedback triggers a resolution pathway -- the exchange is not considered fully closed until resolved
• This creates a quality assurance layer within the hREA economic flow

Reputation Metrics

Individual Metrics

interface UserReputation {
  userId: AgentPubKey;
  totalExchanges: number;
  averageRating: number;            // Weighted average of all star ratings
  completionRate: number;           // Percentage of agreements fulfilled
  onTimeRate: number;               // Percentage of exchanges completed on time
  asAgreedRate: number;             // Percentage of exchanges completed as agreed
  badges: ReputationBadge[];
  trustScore: number;               // Composite calculated metric
}

Community Metrics (Future)

• Peer endorsements
• Community contributions
• Leadership roles in organizations
• Mentorship activities

Achievement Badges

Technical Architecture

Custom Zome Structure

dnas/requests_and_offers/zomes/
├── integrity/reviews/
│   └── src/lib.rs
│       ├── ExchangeReview entry definition
│       ├── Validation rules:
│       │   ├── Reviewer must be a party to the Agreement
│       │   ├── Rating must be 1-5
│       │   ├── Comments max 200 chars
│       │   ├── One review per reviewer per Agreement
│       │   └── Agreement must have fulfilled Commitments
│       └── Link types: AgreementToReview, AgentToReview
│
└── coordinator/reviews/
    └── src/lib.rs
        ├── create_review(input) -> ExchangeReview
        ├── get_reviews_for_agreement(agreement_id) -> Vec<ExchangeReview>
        ├── get_reviews_for_agent(agent_pub_key) -> Vec<ExchangeReview>
        └── get_reputation(agent_pub_key) -> UserReputation

Frontend Service (Effect-TS)

export const ReviewService = Context.GenericTag<ReviewService>("ReviewService");

export const makeReviewService = Effect.gen(function* () {
  const client = yield* HolochainClientService;

  const submitReview = (input: CreateReviewInput) =>
    client.callZome({
      zome_name: "reviews",
      fn_name: "create_review",
      payload: input,
    }).pipe(
      Effect.mapError((error) => new ReviewError({ cause: error }))
    );

  const getReviewsForAgreement = (agreementId: ActionHash) =>
    client.callZome({
      zome_name: "reviews",
      fn_name: "get_reviews_for_agreement",
      payload: agreementId,
    });

  const getReviewsForAgent = (agentPubKey: AgentPubKey) =>
    client.callZome({
      zome_name: "reviews",
      fn_name: "get_reviews_for_agent",
      payload: agentPubKey,
    });

  const getReputation = (agentPubKey: AgentPubKey) =>
    client.callZome({
      zome_name: "reviews",
      fn_name: "get_reputation",
      payload: agentPubKey,
    });

  return { submitReview, getReviewsForAgreement, getReviewsForAgent, getReputation };
});

Frontend Components

components/exchanges/reviews/
├── ReviewForm.svelte           # Star rating + feedback form
├── StarRating.svelte           # Reusable 1-5 star input/display
├── ReputationDisplay.svelte    # User reputation card with metrics
└── ReviewCard.svelte           # Individual review display

Cross-DNA References

The reviews zome lives in the requests_and_offers DNA but references hREA Agreement IDs (which live in the hrea DNA). This cross-DNA reference is handled by storing the Agreement's ActionHash as a field in the ExchangeReview entry. Queries go through the frontend service layer, which orchestrates calls to both DNAs.

Moderation

Review Quality

• Validation at zome level: Reviewer must be a party to the Agreement; one review per party per Agreement
• Rating bounds: Enforced 1-5 range in integrity zome validation
• Comment length: Enforced 200-char max in integrity zome validation
• Spam prevention: Cannot review an Agreement you're not part of

Dispute Resolution

• Negative feedback pathway: Triggers resolution process before economic fulfillment is confirmed
• Appeal process: Disputed reviews can be flagged for admin moderation (integrates with existing administration zome)
• Statistical outlier detection: Reviews significantly deviating from a user's average can be flagged

Privacy & Fairness

Bias Prevention

• Mutual review requirement: Both parties must submit reviews, reducing retaliation bias
• Statistical outlier detection: Identifies potential review manipulation
• Recalibration mechanisms: Reputation scores account for review volume (low sample size = lower confidence)

Data Protection

• Aggregation: Reputation scores are computed aggregates, not exposing individual review details unnecessarily
• Individual privacy: Reviews are linked to Agreements, not publicly browsable outside exchange context
• Data portability: Reputation data is stored on the user's source chain, portable by design (Holochain architecture)

Implementation Priority

This system is part of Phase 2 of the exchange process implementation roadmap (see Exchange Process):

1. Implement reviews integrity + coordinator zome
2. Add ReviewService (Effect-TS) and review store (Svelte 5 Runes)
3. Build review UI components (ReviewForm, StarRating, ReputationDisplay)
4. Integrate feedback-conditional fulfillment gate with hREA flow
5. Add reputation aggregation and display

Dependencies

• hREA Agreement system must be operational (Phase 1 of exchange process)
• Existing administration zome for moderation integration
• Existing user/organization system for agent identity

Related Issues

• #90 — hREA Exchange Process (reviews are Phase 2 of exchange roadmap)
• #91 — Chat System (exchange context for reviews originates from conversations)
• #92 — Unyt Smart Agreements Exploration (future automated fulfillment gates)

Enhanced Dispute Resolution System

Post-Alpha 6 Feature Proposal

Status: Post-MVP Enhancement
Priority: High for Production Scale
Target Audience: Open Value Networks, Commons-Based Peer Production
Strategic Alignment: Sensorica Governance Principles, Nondominium Architecture

Executive Summary

This proposal outlines a comprehensive dispute resolution system for the Requests and Offers platform, designed to handle conflicts professionally while maintaining alignment with Open Value Network (OVN) principles and agent-centric governance models established in Sensorica and Nondominium projects.

Key Features

• Agent-Centric Investigation: Evidence collection from individual agent perspectives
• Progressive Resolution: Multiple escalation levels with community transparency
• Capture-Resistant Design: Distributed authority preventing admin overreach
• System Learning: Dispute pattern analysis for continuous improvement
• OVN Compliance: Full compatibility with Open Value Network governance principles

Strategic Context & Alignment

Sensorica Governance Integration

This system directly supports Sensorica's core principles:

Agent-Centric Design

• All dispute data flows from individual agent perspectives
• Evidence collection respects agent autonomy and narrative
• Resolution outcomes document each stakeholder's experience

Capture-Resistant Governance

• Transparent documentation prevents administrative capture
• Multiple resolution pathways avoid binary win/lose scenarios
• Community learning mechanisms prevent systemic exploitation
• Appeal processes maintain distributed authority

Commons-Based Coordination

• Progressive trust model: self-resolution → mediation → formal arbitration
• Community transparency with privacy protections
• Collective learning improves governance over time

Nondominium Architecture Synergy

Shared Technical Patterns:

• Effect-TS integration for robust error handling
• Agent-centric zome structure for distributed validation
• Governance logic embedded in business workflows
• Progressive trust mechanisms for stakeholder relationships

Resource Management Integration:

• Dispute resolution as governance primitive for Nondominium resources
• hREA/ValueFlows compatibility for economic coordination conflicts
• Organization-agnostic design supporting multiple value networks

Technical Architecture

Data Model

Enhanced Dispute Resolution Entity

#![allow(unused)]
fn main() {
pub struct DisputeResolution {
    pub dispute_type: DisputeType,
    pub resolution_type: DisputeResolutionType,
    pub admin_notes: String,
    pub evidence_reviewed: Vec<EvidenceItem>,
    pub stakeholder_interviews: Vec<InterviewSummary>,
    pub compensation_notes: Option<String>,
    pub lessons_learned: Option<String>,
    pub follow_up_required: bool,
    pub resolution_timestamp: Timestamp,
    pub admin_agent: ActionHash,
    pub appeal_window: Duration,
    pub community_feedback: Vec<CommunityInput>,
}

pub enum DisputeType {
    QualityIssues,          // Unsatisfactory completion
    ComplexDispute,         // Multi-faceted conflicts
    BadFaithRefusal,        // Unjustified completion refusal
    ProcessViolation,       // Platform rule violations
    ResourceConflict,       // Nondominium resource disputes
}

pub enum DisputeResolutionType {
    ProviderFavored,        // Quality standards met
    ReceiverFavored,        // Legitimate quality concerns
    SplitDecision,          // Shared responsibility
    MutualAgreementReached, // Admin-mediated resolution
    AppealGranted,          // Resolution overturned
    SystemicIssueIdentified, // Platform improvement required
}

pub struct EvidenceItem {
    pub evidence_type: EvidenceType,
    pub submitted_by: ActionHash,
    pub content_hash: String,
    pub description: String,
    pub timestamp: Timestamp,
    pub verification_status: VerificationStatus,
}

pub enum EvidenceType {
    Communication,          // Messages, emails, chat logs
    Deliverable,           // Files, screenshots, work product
    Timeline,              // Chronological documentation
    RequirementComparison, // Original specs vs delivery
    ThirdPartyAttestation, // External validation
}

pub struct InterviewSummary {
    pub interviewee: ActionHash,
    pub interviewer: ActionHash,
    pub key_points: Vec<String>,
    pub timestamp: Timestamp,
    pub follow_up_actions: Vec<String>,
}
}

Progressive Resolution Workflow States

#![allow(unused)]
fn main() {
pub enum ResolutionStage {
    // Self-Resolution Attempts
    QualityAssessment,      // Provider responds to quality concerns
    RemediationNegotiation, // Parties negotiate fixes

    // Administrative Investigation
    EvidenceCollection,     // Gathering all relevant materials
    StakeholderInterviews,  // Individual agent perspectives
    ContextAnalysis,        // System and relationship factors

    // Resolution Implementation
    DecisionFormulation,    // Admin team consensus building
    OutcomeDocumentation,   // Comprehensive resolution record
    CommunityNotification,  // Privacy-protected transparency

    // Post-Resolution
    AppealPeriod,          // Time for appeal requests
    LessonsLearned,        // System improvement identification
    FollowUpMonitoring,    // Ensure resolution compliance
}
}

Process Flow Diagram

graph TD
    A[Completion Validation Failure] --> B{Dispute Type Classification}

    B -->|Quality Issues| C[Quality Assessment Process]
    B -->|Complex Multi-Party| D[Complex Dispute Escalation]
    B -->|Bad Faith Refusal| E[Bad Faith Investigation]
    B -->|Process Violation| F[Rule Violation Review]

    C --> G[Evidence Collection Phase]
    G --> H[Provider Response Window - 48 Hours]
    H --> I{Provider Response Analysis}

    I -->|Acknowledge + Remediation| J[Remediation Plan Review]
    I -->|Dispute Quality Claims| K[Escalate to Full Investigation]
    I -->|No Response| L[Default Process Initiation]

    J --> M{Receiver Accepts Remediation?}
    M -->|Yes| N[Return to Service Delivery]
    M -->|No| O[Escalate to Administrative Review]

    D --> P[Administrative Investigation Process]
    E --> P
    F --> P
    K --> P
    O --> P
    L --> P

    P --> Q[Comprehensive Evidence Review]
    Q --> R[Multi-Stakeholder Interviews]
    R --> S[Context & Relationship Analysis]
    S --> T[Administrative Team Deliberation]

    T --> U{Resolution Decision Matrix}

    U -->|Provider Favored| V[Quality Standards Validated]
    U -->|Receiver Favored| W[Legitimate Concerns Confirmed]
    U -->|Split Decision| X[Shared Responsibility Determination]
    U -->|Mediated Agreement| Y[Facilitated Mutual Resolution]
    U -->|Systemic Issue| Z[Platform Improvement Required]

    V --> AA[Comprehensive Documentation]
    W --> AA
    X --> AA
    Y --> AA
    Z --> AA

    AA --> BB[Resolution Implementation]
    BB --> CC[Community Transparency Report]
    CC --> DD[Appeal Window Opening]
    DD --> EE[Lessons Learned Analysis]
    EE --> FF[System Improvement Integration]

    FF --> GG[Case Closure - Professional Resolution]
    N --> HH[Return to Main Exchange Flow]

    DD --> II{Appeal Submitted?}
    II -->|Yes| JJ[Appeal Review Process]
    II -->|No| GG
    JJ --> KK{Appeal Validity}
    KK -->|Valid| T
    KK -->|Invalid| GG

Implementation Features

Investigation Tools

Evidence Collection System

• Automated Timeline Construction: Chronological reconstruction of all exchange communications and events
• Multi-Format Evidence Support: Text, images, files, video recordings, screen captures
• Evidence Integrity Verification: Cryptographic hashing and timestamp validation
• Privacy-Preserving Collection: Redaction tools for sensitive information
• Cross-Platform Integration: Import from email, chat systems, project management tools

Stakeholder Interview Framework

• Structured Interview Templates: Standardized questions ensuring comprehensive coverage
• Individual Perspective Capture: Separate interviews preventing groupthink
• Cultural Sensitivity Protocols: Adaptation for different communication styles and backgrounds
• Documentation Standards: Consistent summary formats with key point extraction
• Follow-Up Action Tracking: Commitments and next steps from each interview

Context Analysis Tools

• Relationship Mapping: Historical interactions between disputing parties
• System Pattern Recognition: Identification of recurring conflict themes
• Resource Dependency Analysis: Understanding of shared resources and constraints
• Communication Pattern Assessment: Quality and frequency of project communication
• External Factor Evaluation: Market conditions, technical constraints, force majeure events

Resolution Mechanisms

Multi-Dimensional Decision Framework

• Quality Standards Assessment: Objective evaluation against defined criteria
• Process Compliance Review: Adherence to agreed-upon workflows and timelines
• Communication Effectiveness Analysis: Quality of stakeholder coordination
• Resource Utilization Evaluation: Efficient use of shared resources and capabilities
• Community Impact Consideration: Effects on broader network relationships

Compensation Calculation Engine

• Time Investment Tracking: Documentation of effort and time committed by each party
• Resource Utilization Assessment: Evaluation of materials, tools, and infrastructure used
• Opportunity Cost Calculation: Consideration of alternative activities foregone
• Market Rate Benchmarking: Comparison with industry standard rates for similar work
• Proportional Responsibility Assignment: Fair allocation based on contributing factors

Mediation Support Tools

• Real-Time Collaboration Platforms: Secure spaces for guided discussion
• Proposal Generation Assistance: Templates and prompts for solution development
• Agreement Documentation: Formal recording of mutually accepted terms
• Implementation Timeline Creation: Structured plans for resolution execution
• Progress Monitoring Dashboard: Tracking of agreed-upon actions and deliverables

Documentation System

Comprehensive Case Records

• Complete Dispute Timeline: Chronological documentation of all events and decisions
• Evidence Repository: Secure storage with access controls and audit trails
• Decision Rationale Documentation: Detailed explanation of resolution reasoning
• Stakeholder Impact Assessment: Analysis of outcomes for all affected parties
• Precedent Value Identification: Recognition of decisions useful for future cases

Community Learning Integration

• Anonymized Case Studies: Privacy-protected examples for educational purposes
• Pattern Recognition Reports: Identification of systemic issues requiring attention
• Best Practice Extraction: Successful resolution strategies for community adoption
• Training Material Development: Educational content for dispute prevention
• Policy Recommendation Generation: Suggestions for platform governance improvements

Privacy Protection Framework

• Selective Disclosure Controls: Granular privacy settings for different information types
• Identity Anonymization: Protection of stakeholder identities in public summaries
• Sensitive Information Redaction: Automatic removal of personal or confidential details
• Consent Management: Clear opt-in/opt-out mechanisms for information sharing
• Data Retention Policies: Time-limited storage with secure deletion procedures

Quality Metrics & KPIs

Resolution Performance Indicators

• Investigation Completion Time: Target 72 hours from escalation to decision
• Decision Implementation Time: Target 24 hours from decision to action initiation
• Stakeholder Satisfaction Rates: Post-resolution surveys from all involved parties
• Resolution Sustainability: Tracking of recurring conflicts between same parties
• Community Trust Metrics: Periodic surveys on dispute resolution system confidence

System Health Monitoring

• Case Volume Trends: Tracking dispute frequency and type patterns over time
• Resolution Type Distribution: Analysis of decision outcomes and their effectiveness
• Appeal Rate Analysis: Frequency and success rate of appeal requests
• Administrative Load Assessment: Resource requirements for dispute resolution operations
• System Improvement Implementation: Rate of policy changes based on lessons learned

Community Impact Assessment

• Platform Usage Confidence: User willingness to engage in exchanges post-dispute exposure
• Network Relationship Health: Quality of ongoing relationships after dispute resolution
• Knowledge Transfer Effectiveness: Community adoption of best practices from case studies
• Preventive Measure Success: Reduction in similar disputes following system improvements
• Ecosystem Trust Building: Overall network resilience and collaboration quality

Integration with Existing Systems

hREA/ValueFlows Compatibility

• Economic Events Modeling: Dispute resolution outcomes as trackable economic events
• Resource Impact Tracking: Effects of disputes on shared resources and commitments
• Agent Relationship Management: Integration with existing trust and reputation systems
• Planning Process Enhancement: Incorporating dispute risk into future planning workflows
• Value Network Optimization: Using dispute data to improve network coordination

Nondominium Resource Governance

• Shared Resource Conflict Resolution: Specialized workflows for commons-based resources
• Access Rights Arbitration: Resolution of conflicting claims to nondominium resources
• Governance Primitive Integration: Dispute resolution as foundational governance capability
• Progressive Trust Enhancement: Dispute resolution outcomes informing trust progression
• Community Stewardship Support: Tools for collective resource management decisions

Platform Administration Integration

• Role-Based Access Control: Integration with existing admin privilege systems
• Audit Trail Connectivity: Linking dispute decisions with broader system audit logs
• Policy Enforcement Coordination: Alignment with existing community guidelines and terms of service
• Escalation Path Clarity: Clear handoff procedures between different administrative functions
• System Health Monitoring: Integration with broader platform health and performance metrics

Implementation Phases

Phase 1: Foundation (Post-Alpha 6)

Timeline: 3-4 months
Focus: Core dispute investigation and resolution capabilities

Infrastructure Development

• Dispute Entity Design: Implementation of comprehensive dispute data model
• Evidence Collection System: Basic file upload and evidence management
• Administrative Interface: Dashboard for dispute management and resolution
• Stakeholder Communication: Secure messaging system for dispute participants
• Basic Documentation: Resolution outcome recording and participant notification

Process Implementation

• Quality Assessment Workflow: Structured process for service delivery evaluation
• Evidence Review Procedures: Standardized methods for information analysis
• Decision Framework: Clear criteria and processes for resolution determination
• Basic Transparency: Simple reporting of resolution outcomes to community
• Appeal Mechanism: Initial version of decision review and appeal process

Phase 2: Enhancement (6 months post-Alpha 6)

Timeline: 4-5 months
Focus: Advanced investigation tools and community integration

Advanced Capabilities

• Automated Timeline Construction: Smart chronological reconstruction of dispute events
• Multi-Format Evidence Support: Enhanced media support and integrity verification
• Stakeholder Interview Tools: Structured interview templates and documentation
• Context Analysis Engine: Pattern recognition and relationship mapping
• Compensation Calculation: Sophisticated algorithms for fair outcome determination

Community Integration

• Privacy-Protected Learning: Anonymized case studies for community education
• Pattern Recognition Reporting: System-wide dispute trend analysis and reporting
• Preventive Measure Integration: Proactive conflict identification and early intervention
• Training Material Development: Educational content for dispute prevention
• Community Feedback Integration: Stakeholder input on system effectiveness

Phase 3: Ecosystem Integration (12 months post-Alpha 6)

Timeline: 3-4 months
Focus: Full Sensorica/OVN alignment and cross-platform compatibility

Governance Ecosystem Integration

• hREA/ValueFlows Full Integration: Complete economic event modeling for disputes
• Nondominium Resource Governance: Specialized workflows for commons-based conflicts
• OVN License Compliance: Full alignment with Open Value Network principles
• Progressive Trust Integration: Dispute outcomes informing broader trust systems
• Cross-Network Compatibility: Integration with other OVN platforms and tools

Advanced Analytics & Learning

• Machine Learning Integration: Pattern recognition for dispute prediction and prevention
• Cross-Platform Data Exchange: Interoperability with other governance systems
• Advanced Metrics Dashboard: Comprehensive system health and effectiveness monitoring
• Research Integration: Connection with academic research on digital governance
• Policy Recommendation Engine: Automated suggestions for governance improvements

Business Value & Impact

For Individual Users

• Fair Conflict Resolution: Professional handling of disputes with transparent processes
• Reputation Protection: Evidence-based decisions protecting against false claims
• Learning Opportunities: Access to best practices and conflict prevention education
• Trust Building: Increased confidence in platform fairness and reliability
• Skill Development: Enhanced collaboration and communication capabilities

For Communities & Networks

• Governance Infrastructure: Foundational capability for commons-based coordination
• Trust Network Strengthening: Improved relationships through fair conflict resolution
• Knowledge Accumulation: Collective learning from dispute patterns and resolutions
• Cultural Evolution: Development of mature collaboration norms and practices
• Ecosystem Resilience: Enhanced ability to handle conflicts without network fragmentation

For Platform & Ecosystem

• Scalability Enablement: Professional dispute handling supporting platform growth
• Compliance & Legal Protection: Robust processes reducing platform liability
• Quality Assurance: System-wide improvement through dispute feedback integration
• Competitive Advantage: Professional dispute resolution as platform differentiator
• Research Contribution: Advancing understanding of digital governance and coordination

Risk Assessment & Mitigation

Technical Risks

• Complexity Management: Risk of over-engineering dispute resolution processes
  • Mitigation: Phased implementation with user feedback integration at each stage
• Privacy Balance: Difficulty balancing transparency with stakeholder privacy
  • Mitigation: Sophisticated privacy controls and community input on disclosure policies
• Performance Impact: Dispute system potentially affecting platform performance
  • Mitigation: Efficient system design with appropriate resource allocation and monitoring

Social & Governance Risks

• Administrative Capture: Risk of dispute resolution system becoming centralized control mechanism
  • Mitigation: Built-in transparency, appeal processes, and community oversight mechanisms
• Cultural Resistance: Community rejection of formal dispute resolution processes
  • Mitigation: Gradual introduction with extensive community input and cultural adaptation
• Bias Introduction: Risk of systematic bias in dispute resolution decisions
  • Mitigation: Diverse administrative teams, regular bias audits, and transparent decision criteria

Implementation Risks

• Resource Requirements: High time and skill investment for comprehensive system
  • Mitigation: Phased approach with clear resource planning and stakeholder commitment
• Adoption Challenges: Low uptake of dispute resolution services by community
  • Mitigation: Education campaigns, success story sharing, and gradual trust building
• Integration Complexity: Difficulty integrating with existing platform systems
  • Mitigation: Careful architecture planning and extensive testing with existing systems

Success Criteria

Short-Term (6 months post-implementation)

• System Operational: Dispute resolution system handling cases within target timeframes
• User Satisfaction: >80% satisfaction rate from dispute participants
• Case Volume Management: Successfully handling 10-15 disputes per month
• Documentation Quality: Comprehensive case documentation meeting transparency standards
• Community Acceptance: >70% community confidence in dispute resolution fairness

Medium-Term (12 months post-implementation)

• Pattern Recognition: Identification and prevention of recurring dispute types
• Process Optimization: <72-hour resolution time for standard disputes
• Learning Integration: Community adoption of best practices from resolved cases
• System Reliability: 99%+ uptime for dispute resolution infrastructure
• Ecosystem Integration: Full compatibility with hREA/ValueFlows and Nondominium systems

Long-Term (24 months post-implementation)

• Dispute Prevention: 30% reduction in dispute frequency through preventive measures
• Network Effect: Adoption by other OVN platforms and commons-based projects
• Research Contribution: Published studies on digital governance based on system data
• Cultural Evolution: Measurable improvement in collaboration quality across platform
• Scalability Proof: Successful handling of disputes in networks with 1000+ active participants

Conclusion

This Enhanced Dispute Resolution System represents a strategic investment in the long-term sustainability and scalability of commons-based peer production platforms. By aligning with Sensorica's governance principles and the broader Open Value Network ecosystem, it positions the Requests and Offers platform as foundational infrastructure for the next generation of collaborative economic coordination.

The system's agent-centric design, capture-resistant architecture, and commitment to community learning make it a natural evolution of the governance patterns already established in the Nondominium and True Commons projects. Its implementation will not only serve the immediate needs of the Requests and Offers platform but contribute to the broader research and development of decentralized governance systems.

Strategic Recommendation: Begin Phase 1 implementation 6 months post-Alpha 6 launch, allowing for community growth and the identification of actual dispute patterns to inform system design priorities.

Technical Specifications Overview

This document outlines the technical foundation of the project, including technologies used, development setup, dependencies, and specific implementation details.

Key Sections

• General Specs: Overall technical requirements and constraints.
• UI Structure: Frontend architecture, components, and state management details.
• Development Features System: Centralized development tools, mock data, and environment management.
• Medium of Exchanges: Technical implementation of currency and payment method system.
• Event Bus Pattern: Event-based communication using Effect TS.
• Zome Details: Detailed documentation for each Holochain zome.

Implementation Patterns

• Services (ui/src/lib/services): All services are implemented as Effect Services. They define a service interface, a Context.Tag, and provide the implementation via an Effect Layer. This pattern facilitates dependency injection and composition within Effect workflows across all domains.
• Stores (ui/src/lib/stores): All stores are implemented using Svelte Factory Functions. These factories use Svelte 5 Runes ($state, $derived, etc.) internally to manage reactive UI state. Store methods orchestrate actions by creating and running Effect pipelines, which consume the Effect Services.

Technical Specifications

1. Infrastructure

1.1 Holo Hosting

• Holo Hosting Overview: Leverages HoloHosts for robust and scalable infrastructure, contributing to the network's infrastructure and enhancing performance and reliability.
• Hosting Requirements: Requires a distributed network of HoloHosts for high availability and redundancy. The Holo Network can supply multiple HoloHosts for redundancy.
• Hosting Benefits: Fosters a decentralized and resilient infrastructure, aligning with Holochain ecosystem principles.

2. Technologies

2.1 Core Technologies

• Holochain: Core technology for building the application, ensuring local-first and peer-to-peer network capabilities.
• SvelteKit: Utilized for the guest/front-end, providing a modern and efficient framework for web development.
  • Version: Using Svelte 5.19.2 with SvelteKit 2.16.1
  • Svelte 5 Runes: Advanced reactivity system with $state, $derived, and $effect for fine-grained reactivity
  • Skeleton UI: A component library for building user interfaces with SvelteKit and Tailwind (using @skeletonlabs/skeleton 2.7.0).
• Effect TS: Functional programming library for TypeScript (effect 3.14.18) providing robust error handling, dependency management, and asynchronous control flow.
  • 7-Layer Architecture: Standardized implementation pattern across all domains
  • Service Layer: Effect-native services with Context.Tag dependency injection
  • Store Layer: Factory functions with Svelte 5 Runes + 9 standardized helper functions
  • Schema Validation: Effect Schema with strategic validation boundaries
  • Error Handling: Domain-specific tagged errors with centralized management
• TailwindCSS: Utility-first CSS framework (v3.4.17) for rapid UI development.
• GraphQL: Using Apollo Client (3.13.8) for data fetching and state management.
• hREA: hREA (Holochain Resource-Event-Agent) is an implementation of the Valueflows specification. It enables a transparent and trusted account of resource and information flows between decentralized and independent agents, across and within ecosystems.
  • Version: @valueflows/vf-graphql 0.9.0-alpha.10 and @valueflows/vf-graphql-holochain 0.0.3-alpha.10
  • For detailed hREA integration specifications, see hREA Integration

2.2 Communication Systems

Messaging System

• User-to-User Messaging
• Administrator Communication Channel
• Notification System for Suspensions

Real-time Features

• Direct messaging capabilities
• Negotiation support
• Agreement finalization
• Status updates
• Exchange notifications

2.3 Security Features

• User Authentication: Agent-centric authentication using Holochain's cryptographic keys.
• Profile Recovery System: Secure identity recovery mechanisms with multi-agent verification.
• Administrator Access Controls: Role-based access control system with granular permissions.
• Suspension Management: Sophisticated system for handling user violations while maintaining decentralized principles.
• Data Validation: Comprehensive input validation using Effect TS Schema validation.
• Error Handling: Centralized tagged error system ensuring robust error recovery.
• Secure Communications: End-to-end encrypted messaging between users.
• Audit Logging: Comprehensive activity logging for security monitoring.

2.4 Data Management

Link Types

• User Links: Profile updates, agent associations, requests/offers
• Project Links: Coordinators, contributors, categories
• Organization Links: Members, projects, categories
• Skill Links: Users, projects, requests/offers
• Category Links: Projects, offers, organizations

Anchor System

• Administrators Anchor: Index of network administrators
• Moderators Anchor: Index of network moderators
• Users Anchor: Global user index
• Projects Anchor: Global project index
• Organizations Anchor: Global organization index

3. User Interface

3.1 Design System

Color palette:

3.2 Key Interfaces

• User Dashboard
• Project Management Interface
• Request/Offer Management
• Administration Dashboard
• Search Interface
• Messaging Interface

3.3 Administrative Interface

• User Management
• Project Verification
• Organization Management
• Request/Offer Moderation
• Reporting Tools

4. System Architecture

The system architecture is documented using the C4 model, which provides different levels of abstraction to understand the system structure.

4.1 System Context

The following diagram shows the high-level system context and key user roles:

C4Context
    title System Context diagram for Requests and Offers System

    Person(advocate, "Advocate", "Individual supporting Holochain projects")
    Person(creator, "Creator", "Individual or group developing projects")
    Person(admin, "Administrator", "System administrator")

    System(requestsAndOffers, "Requests and Offers hApp", "A decentralized application for creating, managing, and responding to requests and offers")

    System_Ext(holoHost, "Holo Host", "Decentralized hosting infrastructure")
    System_Ext(hrea, "hREA", "Resource-Event-Agent implementation")

    Rel(advocate, requestsAndOffers, "Creates offers, responds to requests")
    Rel(creator, requestsAndOffers, "Creates requests, manages projects")
    Rel(admin, requestsAndOffers, "Manages users and system")

    Rel(requestsAndOffers, holoHost, "Hosted on")
    Rel(requestsAndOffers, hrea, "Uses for resource management")

4.2 Container Structure

The container diagram shows the high-level technical building blocks:

C4Container
    title Container diagram for Requests and Offers System

    Person(advocate, "Advocate", "Individual supporting Holochain projects")
    Person(creator, "Creator", "Individual or group developing projects")
    Person(admin, "Administrator", "System administrator")

    System_Boundary(c1, "Requests and Offers hApp") {
        Container(frontend, "Frontend UI", "SvelteKit + Skeleton UI", "Provides user interface for interacting with the system")
        Container(backend, "DNA", "Rust Holochain Zome", "Core business logic and data validation")
        Container(storage, "DHT", "Holochain Distributed Hash Table", "Decentralized data storage")
        Container(messaging, "Messaging System", "Rust Holochain Zome", "Handles user-to-user communication")
    }

    System_Ext(holoHost, "Holo Host", "Decentralized hosting infrastructure")
    System_Ext(hrea, "hREA", "Resource-Event-Agent implementation")

    Rel(advocate, frontend, "Interacts with")
    Rel(creator, frontend, "Interacts with")
    Rel(admin, frontend, "Manages through")

    Rel(frontend, backend, "Calls zome functions")
    Rel(frontend, messaging, "Sends/receives messages")

    Rel(backend, storage, "Stores and retrieves data")
    Rel(backend, hrea, "Manages resources and events")
    Rel(messaging, storage, "Stores messages")

    Rel(backend, holoHost, "Hosted on")
    Rel(messaging, holoHost, "Hosted on")

4.3 Component Structure

The component diagram details the internal structure of each container:

C4Component
    title Component diagram for Requests and Offers System

    Container_Boundary(frontend, "Frontend") {
        Component(ui, "UI Components", "Skeleton UI", "User interface elements")
        Component(auth, "Auth Manager", "SvelteKit", "Handles authentication")
        Component(state, "State Manager", "SvelteKit Store", "Manages application state")
    }

    Container_Boundary(backend, "Backend DNA") {
        Component(userMgmt, "User Management", "Holochain Zome", "Handles user profiles and roles")
        Component(projectMgmt, "Project Management", "Holochain Zome", "Manages projects and teams")
        Component(requestOffer, "Request/Offer System", "Holochain Zome", "Handles requests and offers")
        Component(admin, "Admin Tools", "Holochain Zome", "System administration features")
        Component(search, "Search Engine", "Holochain Zome", "Search and discovery")
    }

    Container_Boundary(messaging, "Messaging DNA") {
        Component(direct, "Direct Messaging", "Holochain Zome", "User-to-user messaging")
        Component(notifications, "Notifications", "Holochain Zome", "System notifications")
    }

    Rel(ui, auth, "Uses")
    Rel(ui, state, "Updates/reads")

    Rel(auth, userMgmt, "Authenticates")
    Rel(state, userMgmt, "Syncs user data")
    Rel(state, projectMgmt, "Syncs project data")
    Rel(state, requestOffer, "Syncs requests/offers")
    Rel(state, direct, "Syncs messages")
    Rel(state, notifications, "Syncs notifications")

    Rel(userMgmt, projectMgmt, "Associates users")
    Rel(projectMgmt, requestOffer, "Links projects")
    Rel(admin, userMgmt, "Manages users")
    Rel(search, requestOffer, "Indexes")
    Rel(search, projectMgmt, "Indexes")

4.4 Code Structure

The code structure diagram shows the organization of the codebase:

C4Component
    title Requests and Offers Code Structure Diagram

    Container_Boundary(ui, "UI (Svelte)") {
        Component(routes, "+page.svelte", "Route components")
        Component(components, "Components", "Reusable UI components")
        Component(stores, "Stores", "State management")
        Component(services, "Services", "API communication")
    }

    Container_Boundary(dna, "DNA (Rust)") {
        Component(entries, "Entries", "Data structures")
        Component(zomes, "Zomes", "Business logic")
        Component(links, "Links", "Relationships")
        Component(validation, "Validation", "Data validation rules")
    }

    Rel(routes, components, "Uses")
    Rel(routes, stores, "Uses")
    Rel(components, stores, "Uses")
    Rel(services, stores, "Updates")

    Rel(services, zomes, "Calls")
    Rel(zomes, entries, "Creates/Updates")
    Rel(zomes, links, "Manages")
    Rel(entries, validation, "Validates against")

4.5 7-Layer Effect-TS Architecture

The application follows a standardized 7-layer architecture pattern ensuring consistency and maintainability across all domains:

7. Testing Layer     ← Comprehensive coverage across all layers
6. Component Layer   ← Svelte 5 components using composables
5. Composable Layer  ← Business logic abstraction
4. Error Layer       ← Domain-specific error handling
3. Schema Layer      ← Effect Schema validation
2. Store Layer       ← Svelte 5 Runes + Effect-TS integration
1. Service Layer     ← Effect-native services with dependency injection

Implementation Status

All domains have been fully standardized with this pattern:

• Service Types (Reference Implementation - 100% complete)
• Requests (100% complete)
• Offers (100% complete)
• Users (100% complete)
• Organizations (100% complete)
• Administration (100% complete)

Key Features

• 9 Standardized Helper Functions: Each store implements consistent helper functions for entity creation, mapping, caching, events, fetching, loading states, record creation, status transitions, and collection processing
• Effect-TS Dependency Injection: Services use Context.Tag for clean dependency management
• Tagged Error System: Domain-specific errors with comprehensive context
• Event Bus Communication: Cross-domain communication through standardized events
• Module-Level Caching: TTL-based caching with cache synchronization

4.6 Architecture Principles

1. Decentralization: The system leverages Holochain's peer-to-peer architecture to ensure:

   • Data sovereignty
   • Resilient infrastructure
   • No single point of failure

2. Modularity: The system is built with clear separation of concerns:

   • Frontend (SvelteKit + Skeleton UI + 7-layer architecture)
   • Backend DNA (Holochain Zomes)
   • Messaging DNA
   • Data storage (DHT)

3. Consistency: Standardized patterns across all domains:

   • Same 7-layer structure for every domain
   • Identical helper function implementations
   • Consistent error handling and state management
   • Unified testing approaches

4. Security: Built-in security features:

   • User authentication
   • Role-based access control
   • Data validation
   • Secure messaging

5. Scalability: The system is designed to scale through:

   • Distributed hosting
   • Efficient data structures
   • Modular components
   • Standardized optimization patterns

4.7 Testing Framework

1. Frontend Testing:

   • Unit Tests: Using Vitest (0.28.4) with @effect/vitest (0.21.1) for Effect-specific testing
   • Store Testing: All 9 helper functions tested for every domain store
   • Service Testing: Effect-TS services tested with mock dependencies
   • Component Tests: Testing UI components in isolation
   • Integration Tests: End-to-end testing with Playwright (1.50.0)
   • Status: All 343 unit tests passing across 20 test files with no unhandled Effect errors

2. Backend Testing:

   • Zome Unit Tests: Testing individual zome functions with Rust testing framework
   • Multi-Agent Tests: Testing peer-to-peer interactions with Sweettest
   • Domain-Specific Tests: Comprehensive tests for each domain (service-types, requests, offers, users, organizations, administration)
   • Performance Benchmarks: Ensuring system efficiency under load

3. Testing Architecture Integration:

   • Layer-Specific Testing: Each layer of the 7-layer architecture tested independently
   • Effect-TS Testing Patterns: Standardized testing approach for Effect-based services and stores
   • Mock Implementations: Consistent mocking strategies across all domains
   • Error Boundary Testing: Comprehensive testing of tagged error handling

4. Testing Principles:

   • Comprehensive Coverage: All critical paths tested across all 7 layers
   • Isolated Components: Pure unit testing with dependency injection
   • Real-World Scenarios: Integration tests reflecting actual usage patterns
   • Effect-TS Integration: Proper testing of Effect operations with dependency injection
   • Automated CI/CD: Tests run on every commit through GitHub Actions

Action Hash Type Safety

Compile-time distinct types for OriginalActionHash and PreviousActionHash to prevent accidental hash swapping between original entity identifiers and update-chain head pointers.

Problem

Holochain's CRUD model uses two different action hashes for updates:

• Original action hash: The hash of the initial Create action — serves as the immutable entity identity throughout its lifecycle.
• Previous action hash: The hash of the most recent action in the update chain — needed by update() to append to the chain correctly.

Both are ActionHash at the type level. Swapping them compiles but produces silent data corruption: updates target the wrong chain entry or create orphaned forks.

Rust Newtypes

File: dnas/requests_and_offers/utils/src/types.rs

#![allow(unused)]
fn main() {
/// The ActionHash of the original Create action — immutable entity identifier.
#[derive(Clone, Debug, Serialize, Deserialize, PartialEq, Eq, Hash)]
#[serde(transparent)]
pub struct OriginalActionHash(pub ActionHash);

/// The ActionHash of the most recent action in the update chain.
#[derive(Clone, Debug, Serialize, Deserialize, PartialEq, Eq, Hash)]
#[serde(transparent)]
pub struct PreviousActionHash(pub ActionHash);
}

Key properties

• #[serde(transparent)]: Wire format is identical to a plain ActionHash. No migration needed for existing data.
• From trait implementations: Both types implement From<T> for ActionHash, From<T> for AnyDhtHash, and From<T> for AnyLinkableHash for seamless HDK 0.6 interop.
• Direct access: Use .0 to access the inner ActionHash when needed.
• Wrapping: Use OriginalActionHash(hash) or PreviousActionHash(hash) to wrap a plain ActionHash.
• Conversion: Use .into() when passing to HDK functions that expect ActionHash, AnyDhtHash, or AnyLinkableHash.

Usage in update inputs

All update input structs use the distinct types:

#![allow(unused)]
fn main() {
pub struct UpdateServiceTypeInput {
    pub original_action_hash: OriginalActionHash,
    pub previous_action_hash: PreviousActionHash,
    pub updated_service_type: ServiceType,
}
}

TypeScript Branded Types

File: ui/src/lib/schemas/holochain.schemas.ts

// Branded action hash types for compile-time type safety.
// serde(transparent) on the Rust side means wire format is identical to ActionHash.
export type OriginalActionHash = ActionHash & { readonly __brand: 'OriginalActionHash' };
export type PreviousActionHash = ActionHash & { readonly __brand: 'PreviousActionHash' };

/** Cast an ActionHash as an OriginalActionHash (zero-cost, compile-time only) */
export const asOriginalActionHash = (hash: ActionHash): OriginalActionHash =>
  hash as OriginalActionHash;

/** Cast an ActionHash as a PreviousActionHash (zero-cost, compile-time only) */
export const asPreviousActionHash = (hash: ActionHash): PreviousActionHash =>
  hash as PreviousActionHash;

Key properties

• Intersection types: ActionHash & { readonly __brand: ... } — the brand field exists only at compile time, not at runtime.
• Zero-cost: No runtime overhead. The helper functions are simple type casts (as).
• Narrowing helpers: asOriginalActionHash() and asPreviousActionHash() provide readable call sites instead of inline as casts.

Entity Identity Model

original_action_hash is the canonical identity for all non-exchange entity types in the UI layer.

UI entity types (ui/src/lib/types/ui.ts)

Every core UI type declares both hash fields as required:

export type UIUser = UserInDHT & {
  original_action_hash: ActionHash;
  previous_action_hash: ActionHash;
  // ... other fields
};

export type UIServiceType = ServiceTypeInDHT & {
  original_action_hash: ActionHash;
  previous_action_hash: ActionHash;
  // ... other fields
};

The same pattern applies to UIStatus, UIOrganization, UIRequest, and UIOffer.

CacheableEntity (ui/src/lib/types/store-helpers.ts)

The cache interface keeps original_action_hash optional for hREA compatibility (hREA entities use a different identity scheme):

export interface CacheableEntity {
  readonly original_action_hash?: ActionHash;
  readonly [key: string]: unknown;
}

Exchange types

Exchange types (UIExchangeResponse, UIExchangeAgreement, UIExchangeReview) use actionHash instead of original_action_hash because exchanges are not updated via the standard CRUD chain — they follow a proposal/agreement lifecycle.

Key Files Reference

Component Library Documentation

This document provides a comprehensive inventory of the reusable UI components in the Requests and Offers application.

Component Organization

Components are organized by domain with a feature-based approach, located in ui/src/lib/components:

/components/
├── service-types/     # Service type related components
├── requests/         # Request management components
├── offers/           # Offer management components
├── users/            # User profile components
├── organizations/    # Organization management components
├── tags/             # Tag related components
├── shared/           # Shared utility components
├── hrea/             # hREA integration components
├── moe/              # Medium of Exchange components
└── mediums-of-exchange/ # Medium of Exchange components

Core Components

Service Types Components

ServiceTypeCard.svelte

Purpose: Displays a service type with its metadata in a card format.

Props:

• serviceType: ServiceTypeOutput - The service type to display
• showActions: boolean - Whether to show action buttons (edit, delete)
• compact: boolean - Whether to show a compact version of the card

Events:

• edit: When edit button is clicked
• delete: When delete button is clicked
• select: When the card is selected

ServiceTypeSelector.svelte

Purpose: Multi-select component for choosing service types with search capability.

Props:

• selectedServiceTypes: ServiceTypeOutput[] - Currently selected service types
• multiple: boolean - Whether multiple selection is allowed
• required: boolean - Whether selection is required
• disabled: boolean - Whether the component is disabled

Events:

• selection: When selection changes, emits array of selected service types
• search: When search text changes

Requests/Offers Components

RequestForm.svelte / OfferForm.svelte

Purpose: Form for creating or editing a request/offer.

Props:

• request/offer: Optional - Existing request/offer for editing
• serviceTypes: ServiceTypeOutput[] - Available service types
• organizations: OrganizationOutput[] - User's organizations

Events:

• submit: When form is submitted successfully
• cancel: When form is cancelled
• error: When form submission fails

Users Components

UserName.svelte

Purpose: Renders a user's display name with the mononym sentinel stripped via formatUserName. Use wherever user.name would otherwise be interpolated directly.

Props:

• user: UIUser | UserInDHT | { name?: string } | null | undefined - The user, or any object carrying a name
• fallback: string - Text shown when no name is available (default: "User")
• class: string - Optional CSS class applied to the wrapping <span>

Shared Components

TagAutocomplete.svelte

Purpose: Tag input with autocomplete suggestions.

Props:

• selectedTags: string[] - Currently selected tags
• suggestTags: boolean - Whether to show tag suggestions
• maxTags: number - Maximum number of tags allowed

Events:

• update: When selected tags change

LoadingSpinner.svelte

Purpose: Consistent loading indicator for async operations.

Props:

• size: 'small' | 'medium' | 'large' - Size of the spinner
• message: string - Optional loading message

ErrorDisplay.svelte

Purpose: Standardized error display component.

Props:

• error: any - Error object to display
• retry: () => void - Optional retry function

Styling and Theming

The application uses a combination of TailwindCSS and SkeletonUI for styling, with a custom theme defined in src/happening_theme.ts.

Custom Theme Configuration

The Happening theme extends the base Skeleton theme with:

1. Custom Colors: Brand-specific color palette with primary, secondary, and accent colors
2. Typography: Custom font family and size scale
3. Component Styling: Customized appearance for buttons, cards, and form elements

Using the Theme

Theme values should be accessed through Skeleton's theme system rather than hard-coding colors:

<!-- Recommended -->
<button class="btn variant-filled-primary">Submit</button>

<!-- Avoid -->
<button class="bg-blue-500 hover:bg-blue-600">Submit</button>

Custom Utility Classes

In addition to Tailwind's utility classes, the application defines several custom utilities for consistent styling:

• .card-hover: Standard hover effects for cards
• .form-input-wrapper: Consistent styling for form inputs
• .tag-pill: Styling for tag elements

Best Practices

1. Component Composition: Prefer composition over complex, monolithic components
2. Props Typing: Always define proper TypeScript interfaces for component props
3. Error Handling: Use ErrorDisplay component for consistent error presentation
4. Loading States: Use LoadingSpinner for all asynchronous operations
5. Accessibility: Ensure all components meet WCAG AA standards

Component Development Guidelines

1. New Components: Place in appropriate domain folder
2. Testing: Create component tests in corresponding test file
3. Documentation: Update this document when adding new components
4. Composition: Extract reusable logic to composables when appropriate

Development Features System

A centralized system for managing development-only features and mock data in the requests-and-offers application.

Overview

The Development Features System provides a unified approach to controlling development tools, mock data, and debugging features across different deployment environments. It ensures production builds are clean while enhancing the developer experience during development and testing.

Architecture

7-Layer Effect-TS Integration

The system follows the established 7-layer Effect-TS architecture pattern:

1. Service Layer: DevFeaturesService with Context.Tag dependency injection
2. Environment Configuration: Vite environment variables for build-time optimization
3. Component Integration: Conditional rendering using shouldShowMockButtons()
4. Build-Time Tree-Shaking: Automatic removal of dev features in production
5. Mock Data Layer: Enhanced mock utilities for realistic testing data
6. Testing Strategy: Different modes for development, testing, and production
7. Documentation: Comprehensive usage guidelines and examples

Core Components

DevFeaturesService

Location: ui/src/lib/services/devFeatures.service.ts

export class DevFeaturesServiceTag extends Context.Tag("DevFeaturesService")<
  DevFeaturesServiceTag,
  DevFeaturesService
>() {}

export const shouldShowMockButtons = (): boolean => {
  return import.meta.env.VITE_MOCK_BUTTONS_ENABLED === "true";
};

Key Features:

• Effect-TS Context.Tag pattern for dependency injection
• Build-time evaluation using Vite environment variables
• Tree-shaking optimization for production builds
• Type-safe feature flag management

Environment Configuration

Development Environment (.env):

# Atomic feature control - each independently managed
VITE_MOCK_BUTTONS_ENABLED=true      # Show mock data buttons in forms
VITE_PEERS_DISPLAY_ENABLED=true     # Show network peers for testing

Usage

Component Integration

All form components use the service for conditional mock button rendering:

<script lang="ts">
  import { shouldShowMockButtons } from '$lib/services/devFeatures.service';
  // ... other imports
</script>

<!-- Form content -->

{#if mode === 'create' && shouldShowMockButtons()}
  <button
    type="button"
    class="variant-soft-secondary btn"
    onclick={handleMockSubmit}
    disabled={isSubmitting}
  >
    Create Mock Data
  </button>
{/if}

Enhanced Mock Functions

Location: ui/src/lib/utils/mocks.ts

New mock functions for comprehensive testing:

// Medium of Exchange mocks
export const createMockedMediumOfExchange = (): MediumOfExchangeInDHT => ({
  code: faker.finance.currencyCode(),
  name: faker.finance.currencyName(),
  description: faker.lorem.sentence(),
  resource_spec_hrea_id: faker.string.uuid(),
});

export const createSuggestedMockedMediumOfExchange =
  (): MediumOfExchangeInDHT => ({
    code: `${faker.finance.currencyCode()}_SUGGESTED`,
    name: `${faker.finance.currencyName()} (Suggested)`,
    description: faker.lorem.sentence(),
    resource_spec_hrea_id: faker.string.uuid(),
  });

Deployment Modes

Development Mode

• Purpose: Full development experience with atomic feature control
• Features: Mock buttons, network peers display, development utilities
• Command: bun start (from project root)
• Environment: Features controlled via .env file

Build Mode

• Production Build: cd ui && bun run build
• Features: Atomic feature control with production optimizations

Build Scripts

UI Scripts (ui/package.json)

{
  "scripts": {
    "build": "bun run check && vite build"
  }
}

Root Scripts (package.json)

{
  "scripts": {
    "start": "AGENTS=${AGENTS:-2} BOOTSTRAP_PORT=$(get-port) bun run network"
  }
}

Tree-Shaking Verification

The system implements build-time optimization that completely removes development features from production builds:

Development Build:

const shouldShowMockButtons = () => true;

Production Build:

const shouldShowMockButtons = () => false; // or minified as ()=>!1

Verification Command:

bun run build && grep -r "shouldShowMockButtons" .svelte-kit/output/client/

Integrated Forms

The following forms have been integrated with the development features system:

1. RequestForm.svelte - Request creation with mock data
2. OfferForm.svelte - Offer creation with mock data
3. OrganizationForm.svelte - Organization creation with mock data
4. UserForm.svelte - User creation with mock data
5. ServiceTypeForm.svelte - Service type creation with mock data
6. ServiceTypeSuggestionForm.svelte - Service type suggestions
7. MediumOfExchangeForm.svelte - Currency/payment method creation
8. MediumOfExchangeSuggestionForm.svelte - Currency suggestions

Benefits

Developer Experience

• Rapid Prototyping: Instant mock data generation for testing workflows
• Consistent Testing: Realistic data across all forms and components
• Flexible Development: Easy switching between development modes
• Debugging Support: Development-only features for troubleshooting

Production Safety

• Zero Overhead: Complete removal of dev code in production builds
• Security: No development utilities exposed in production
• Performance: Optimized builds without development features
• Clean Deployment: Professional appearance without debug tools

Testing Efficiency

• Multi-Environment: Test different deployment scenarios
• Alpha Testing: Test mode simulates production with dev features
• Integration Testing: Verify tree-shaking and build optimization
• Quality Assurance: Consistent testing data across environments

Implementation Guidelines

Adding New Development Features

1. Environment Variable: Add feature flag to environment files
2. Service Integration: Extend DevFeaturesService with new feature checks
3. Component Usage: Use service functions for conditional rendering
4. Testing: Verify tree-shaking removes feature in production builds

Best Practices

• Build-Time Evaluation: Use import.meta.env for compile-time optimization
• Conditional Rendering: Wrap dev features in conditional blocks
• Descriptive Naming: Use clear, descriptive variable names
• Documentation: Document all new dev features and their purpose
• Testing: Always test production builds to verify clean removal

Troubleshooting

Common Issues

Mock Buttons Not Appearing:

• Check VITE_MOCK_BUTTONS_ENABLED=true in .env file for mock button visibility
• Ensure running in development or test mode

Production Build Contains Dev Code:

• Verify environment variables are not set in .env.production
• Check Vite build mode is set to production
• Test tree-shaking with build verification commands

Environment Not Loading:

• Ensure .env file is in project root (same level as package.json)
• Verify environment variables are properly set in .env
• Check Vite configuration (envDir: '../' points to project root)

Future Enhancements

Planned Features

• Feature Toggles: Runtime feature toggling for specific development tools
• Debug Panels: Development-only debug information displays
• Performance Monitoring: Development-mode performance metrics
• Test Data Management: Advanced mock data scenarios and fixtures

Architecture Improvements

• Service Extensions: Additional dev services for specific domains
• Configuration Management: Centralized configuration for complex dev features
• Plugin System: Modular development feature plugins
• Integration Testing: Automated testing of tree-shaking effectiveness

Related Documentation

• Architecture Overview
• Effect-TS Guidelines
• Testing Strategy
• Build System

Event Bus Pattern

This document details the Event Bus pattern implemented using Effect TS in the Requests and Offers application.

Overview

The Event Bus pattern provides a pub/sub mechanism for communication between different parts of the application, particularly between stores. This helps decouple components and enables real-time updates.

In our implementation, we use Effect TS to handle asynchronous operations and error management, providing a robust, type-safe event system.

Architecture

The Event Bus system is implemented using Effect TS's event handling capabilities, with a central store event bus that manages domain-specific events.

Core Implementation

The core of our Event Bus is defined in ui/src/lib/stores/storeEvents.ts:

import { EventTag } from "effect";

// Event tags with typed payloads
export const ServiceTypeCreatedEvent = EventTag<{
  type: "service_type_created";
  payload: {
    serviceType: any; // ServiceTypeOutput in actual implementation
  };
}>();

export const ServiceTypeApprovedEvent = EventTag<{
  type: "service_type_approved";
  payload: {
    serviceType: any; // ServiceTypeOutput in actual implementation
  };
}>();

// Other domain-specific events...

// Generic domain events
export const EntityCreatedEvent = EventTag<{
  type: "entity_created";
  payload: {
    domain: "service_types" | "requests" | "offers" | "users" | "organizations";
    entity: any;
  };
}>();

export const EntityUpdatedEvent = EventTag<{
  type: "entity_updated";
  payload: {
    domain: "service_types" | "requests" | "offers" | "users" | "organizations";
    entity: any;
  };
}>();

// Create an event emitter interface
export interface StoreEvents {
  emit<E>(eventTag: EventTag<E>, event: E): void;
}

// Concrete event bus implementation
export const storeEventBus: StoreEvents = {
  emit: (eventTag, event) => {
    // Actual implementation with Effect EventEmitter
  },
};

Event Types

The system uses two types of events:

1. Domain-Specific Events: Focused on specific entity operations (e.g., ServiceTypeCreatedEvent)
2. Generic Domain Events: Cross-cutting events with domain identifiers (e.g., EntityCreatedEvent)

Common Event Categories

Usage Patterns

Publishing Events

Stores emit events when significant state changes occur:

// Inside a store method
const createServiceType = (
  input: ServiceTypeInput,
): E.Effect<ServiceTypeOutput, StoreError> =>
  pipe(
    serviceTypeService.createServiceType(input),
    E.map((record) => {
      const serviceType = createUIServiceType(record);

      // Emit domain-specific event
      storeEventBus.emit(ServiceTypeCreatedEvent, {
        type: "service_type_created",
        payload: { serviceType },
      });

      // Emit generic domain event
      storeEventBus.emit(EntityCreatedEvent, {
        type: "entity_created",
        payload: {
          domain: "service_types",
          entity: serviceType,
        },
      });

      return serviceType;
    }),
    // Error handling...
  );

Subscribing to Events

Stores and components can subscribe to events using Effect's Stream API:

// In a store or component
$effect(() => {
  const subscription = pipe(
    EventBus.subscribe(ServiceTypeCreatedEvent),
    S.tap((event) => {
      // Handle the event
      console.log("Service type created:", event.payload.serviceType);
      // Update local state as needed
    }),
    S.runDrain,
  );

  // Cleanup subscription when component is destroyed
  return () => subscription.interrupt();
});

Cross-Store Communication

The Event Bus enables communication between stores without direct dependencies:

// In offers.store.svelte.ts
$effect(() => {
  const subscription = pipe(
    EventBus.subscribe(ServiceTypeApprovedEvent),
    S.tap((event) => {
      // Update offers that use this service type
      const serviceTypeId = event.payload.serviceType.id;
      // Refresh related offers...
    }),
    S.runDrain,
  );

  return () => subscription.interrupt();
});

Standardized Event Helpers

The 9-Helper Function Pattern includes createEventEmitters() to standardize event emission:

const createEventEmitters = () => {
  return {
    emitServiceTypeCreated: (serviceType: UIServiceType): void => {
      try {
        storeEventBus.emit(ServiceTypeCreatedEvent, {
          type: "service_type_created",
          payload: { serviceType },
        });

        storeEventBus.emit(EntityCreatedEvent, {
          type: "entity_created",
          payload: {
            domain: "service_types",
            entity: serviceType,
          },
        });
      } catch (error) {
        console.error("Failed to emit service_type:created event:", error);
      }
    },
    // Other event emitters...
  };
};

Benefits

1. Decoupling: Stores and components can communicate without direct dependencies
2. Reactivity: UI can respond to backend changes in real-time
3. Testability: Event handling can be easily tested in isolation
4. Type Safety: Event payloads are fully typed with Effect's EventTag system
5. Consistency: Standardized event naming and payload structure

Best Practices

1. Event Granularity: Create specific events for important state changes
2. Error Handling: Always wrap event emission in try/catch blocks
3. Cleanup: Always return interrupt functions from subscriptions
4. Naming Conventions: Use consistent naming patterns across all events
5. Documentation: Document all events in this document
6. Payload Design: Keep payloads minimal but complete for consumers

Implementation Status

Core Implementation

The event bus is implemented in ui/src/lib/utils/eventBus.effect.ts as a generic, reusable system with the following key features:

• Type-safe: Uses TypeScript generics to ensure events and payloads are type-checked.
• Effect-based: Leverages Effect TS for error handling and asynchronous operations.
• Layered design: Follows the Context/Layer pattern from Effect TS for dependency injection.

Key Components

1. EventBusService: The core interface that defines the operations available on an event bus:

   • on: Subscribe to events
   • emit: Publish events
   • off: Unsubscribe from events

2. Context Tag: Created with createEventBusTag<T>() for dependency injection.

3. Layer Implementation: Created with createEventBusLiveLayer() to provide the actual implementation.

4. Error Handling: Custom EventBusError class with standardized error handling and utility functions.

Usage Pattern

1. Define Event Map

First, define the events and their payload types:

// storeEvents.ts
export type StoreEvents = {
  "request:created": { request: UIRequest };
  "request:updated": { request: UIRequest };
  "request:deleted": { requestHash: ActionHash };
  "offer:created": { offer: UIOffer };
  "offer:updated": { offer: UIOffer };
  "offer:deleted": { offerHash: ActionHash };
};

2. Create Tag and Layer

// storeEvents.ts
const Tag = createEventBusTag<StoreEvents>("StoreEventBus");
const Live = createEventBusLiveLayer(Tag);

export { Tag as StoreEventBusTag, Live as StoreEventBusLive };

3. Use in Stores or Components

// Example from a store
import { StoreEventBusTag, StoreEventBusLive } from "$lib/stores/storeEvents";

// To emit an event
E.gen(function* () {
  const eventBus = yield* StoreEventBusTag;
  yield* eventBus.emit("request:created", { request: newRequest });
});

// Provide the layer
E.provide(StoreEventBusLive);

Integration with Stores

The event bus is used for communication between stores, particularly for CRUD operations:

1. Create operations: Emit events when new entities are created
2. Update operations: Notify other stores when entities are updated
3. Delete operations: Alert subscribers when entities are removed

Implementation in Store Methods

Each store method that modifies data emits appropriate events:

const createRequest = (
  request: RequestInDHT,
): E.Effect<Record, RequestStoreError, EventBusService<StoreEvents>> =>
  pipe(
    // Create the request
    requestsService.createRequest(request),

    // Map and cache the result
    E.map((record) => {
      const newRequest = mapRecordToUIRequest(record);
      cache.set(newRequest);
      return { record, newRequest };
    }),

    // Emit the event
    E.tap(({ newRequest }) =>
      newRequest
        ? E.gen(function* () {
            const eventBus = yield* StoreEventBusTag;
            yield* eventBus.emit("request:created", { request: newRequest });
          })
        : E.asVoid,
    ),

    // Final transformation and error handling
    E.map(({ record }) => record),
    E.catchAll(handleError),

    // Provide the layer
    E.provide(StoreEventBusLive),
  );

Best Practices

1. Define clear event types: Create a well-defined event map with descriptive event names and payload types.
2. Use consistent naming conventions: Follow patterns like entity:action (e.g., request:created).
3. Proper error handling: Always catch and handle errors from event bus operations.
4. Event isolation: Keep event payloads focused and minimal, containing only what subscribers need.
5. Type safety: Leverage TypeScript to ensure type correctness across the event system.

Performance Considerations

• The event bus implementation uses an efficient data structure (HashSet) to store and manage event handlers.
• Events are processed concurrently using Effect's parallel processing capabilities.
• Error handling is isolated per handler to prevent one failing handler from affecting others.

Cross-Store Communication Example

In our application, the event bus facilitates communication between different stores:

1. requestsStore.createRequest() emits a request:created event
2. offersStore can subscribe to this event to update its state based on new requests
3. This decouples the stores while maintaining synchronized state

This pattern ensures that stores remain independent but can react to changes in related data, improving maintainability and robustness.

History/Revision Feature Documentation

Overview

The history/revision feature in the requests-and-offers application tracks and displays status changes for users and organizations over time. This feature provides administrators with a complete audit trail of all status changes, including who was affected, when changes occurred, and the reasons for status modifications.

Architecture

Data Flow

graph TD
    A[Administrator Action] --> B[Status Update]
    B --> C[Holochain DNA]
    C --> D[Status Record Created]
    D --> E[Link to Entity]
    E --> F[Frontend Fetch]
    F --> G[Store Update]
    G --> H[UI Display]

    I[Event Bus] --> J[Real-time Updates]
    J --> F

Components

Backend (Holochain DNA)

Status Management (administration/src/status.rs):

• Creates new status records with timestamp
• Links status to entities (users/organizations)
• Maintains revision chain through links
• Provides get_all_revisions_for_status function for history retrieval

Key Functions:

• create_status: Creates initial pending status
• update_entity_status: Updates status with new revision
• get_all_revisions_for_status: Retrieves complete history chain

Frontend Components

UI Components:

1. StatusHistoryModal (lib/components/shared/status/StatusHistoryModal.svelte)

   • Modal dialog for displaying status history
   • Uses StatusTable for consistent rendering

2. StatusTable (lib/components/shared/status/StatusTable.svelte)

   • Reusable table component for status history display
   • Responsive design with mobile card view
   • Color-coded status indicators
   • Timestamp formatting and duration display

Store Layer (lib/stores/administration.store.svelte.ts):

• fetchAllUsersStatusHistory: Aggregates status history for all users
• fetchAllOrganizationsStatusHistory: Aggregates status history for organizations
• getEntityStatusHistory: Retrieves history for individual entity
• Real-time updates via event bus integration

Route Pages:

• /admin/users/status-history: Displays all user status changes
• /admin/organizations/status-history: Displays all organization status changes
• /test-status-history: Development tool for testing status history

Data Types

Core Types

// Revision type represents a single status change
export type Revision = {
  status: UIStatus; // The status details
  timestamp: number; // When the change occurred
  entity: UIUser | UIOrganization; // Who was affected
};

// UIStatus contains the actual status information
export type UIStatus = {
  status_type: StatusType;
  reason?: string;
  duration?: number;
  original_action_hash?: ActionHash;
  previous_action_hash?: ActionHash;
  created_at?: number;
  updated_at?: number;
};

// StatusType enum
type StatusType =
  | "pending"
  | "accepted"
  | "rejected"
  | "suspended temporarily"
  | "suspended indefinitely";

Features

Status Tracking

The system tracks five distinct status types:

1. Pending (yellow) - Initial state for new users/organizations
2. Accepted (green) - Approved entities
3. Rejected (red) - Denied access
4. Suspended Temporarily (orange) - Time-limited suspension
5. Suspended Indefinitely (red) - Permanent suspension

Real-time Updates

Status changes trigger events through the event bus:

• user:status:updated - User status change
• organization:status:updated - Organization status change

These events automatically refresh the status history displays.

History Collection

The system collects history by:

1. Fetching all entities (users/organizations)
2. For each entity, retrieving their complete status revision chain
3. Aggregating all revisions into a chronological list
4. Sorting by timestamp for proper display order

UI Features

• Responsive Design: Desktop table view, mobile card view
• Color Coding: Visual status indicators
• Timestamp Display: Human-readable date/time formatting
• Duration Display: Shows suspension duration in days
• Search/Filter: (Planned) Filter by entity, status type, date range

Implementation Details

Frontend Workarounds

Due to backend limitations in revision ordering, the frontend implements:

• Client-side timestamp sorting
• Aggregation of individual entity histories
• Reactive updates through event subscriptions
• Svelte 5 state proxy handling with array spreading

Performance Considerations

• Batch fetching of entity histories
• Effect-TS for efficient async operations
• Caching at service layer (5-minute TTL)
• Loading states during data fetching

Event-Driven Architecture

// Status update triggers cascade
updateUserStatus()
  -> emitUserStatusUpdated()
  -> Event: 'user:status:updated'
  -> Listeners refresh history
  -> UI updates automatically

Usage Examples

Viewing Status History

1. Navigate to Admin panel
2. Go to Users or Organizations section
3. Click "Status History" button
4. View chronological list of all status changes

Individual Entity History

// Get history for specific user
const history = await getAllRevisionsForStatus(user);

// Display in modal
modalStore.trigger({
  type: "component",
  component: "statusHistoryModal",
  meta: {
    statusHistory: history,
    title: `Status History for ${user.name}`,
  },
});

Testing

Test Page (/test-status-history)

Development tool that:

• Simulates status history data
• Validates logging patterns
• Tests UI rendering
• Confirms data flow

Integration Tests

• Backend Sweettest tests verify revision creation
• Frontend tests validate history display
• E2E tests check complete workflow

Future Enhancements

Planned Features

1. Advanced Filtering

   • Filter by date range
   • Filter by status type
   • Search by entity name

2. Export Functionality

   • CSV export of history
   • PDF report generation

3. Analytics Dashboard

   • Status change trends
   • Administrator activity tracking
   • Suspension duration analysis

4. Audit Improvements

   • Record which admin made changes
   • Add change justification field
   • Version control for bulk operations

Technical Improvements

1. Backend Optimization

   • Native revision ordering in Holochain
   • Pagination for large histories
   • Indexed queries for performance

2. Frontend Enhancements

   • Virtual scrolling for large datasets
   • Real-time collaborative updates
   • Offline support with sync

Troubleshooting

Common Issues

1. Empty History Display

   • Ensure entities have status changes
   • Check network connectivity
   • Verify administrator permissions

2. Incorrect Timestamps

   • Frontend converts microseconds to milliseconds
   • Check timezone settings
   • Validate Holochain timestamp format

3. Missing Updates

   • Verify event bus subscriptions
   • Check for errors in console
   • Ensure proper Effect-TS error handling

Debug Tools

• TDD test page for isolated testing
• Console logging with 🔄 prefix for history operations
• Effect-TS error contexts for debugging

Related Documentation

• Administration System
• Status Management
• Event Bus Architecture
• Effect-TS Patterns

Medium of Exchanges Feature Documentation

Holochain Requests and Offers Project

📋 Executive Summary

The Medium of Exchanges (MoE) feature enables communities to define and manage various payment methods and value exchange mechanisms within the requests and offers ecosystem. This feature supports both traditional currencies (USD, EUR) and alternative exchange systems (Pay It Forward, Local Exchange Trading Systems, Time Banking, etc.).

Key Capabilities

• ✅ Multi-Currency Support: Traditional and alternative currencies
• ✅ Admin Approval Workflow: Suggestion → Approval/Rejection → Activation
• ✅ hREA Integration: Maps to ResourceSpecification entries for economic coordination
• ✅ Entity Linking: Associate mediums of exchange with requests and offers
• ✅ Status Management: Comprehensive status tracking throughout lifecycle

🏗️ Architecture Overview

System Components

graph TB
    subgraph "Frontend Layer"
        A[MoE Components]
        B[MoE Store]
        C[MoE Service]
    end

    subgraph "Backend Layer"
        D[MoE Coordinator Zome]
        E[MoE Integrity Zome]
        F[Administration Zome]
    end

    subgraph "External Integration"
        G[hREA ResourceSpec]
        H[Request/Offer Linking]
    end

    A --> B
    B --> C
    C --> D
    D --> E
    D --> F
    D --> G
    D --> H

Data Flow Architecture

1. User Suggestion: Users suggest new mediums of exchange
2. Admin Review: Administrators review and approve/reject suggestions
3. hREA Integration: Approved mediums create ResourceSpecification entries
4. Entity Association: Link mediums to requests and offers
5. Status Tracking: Monitor lifecycle from suggestion to activation

🔧 Backend Implementation

Data Structure

Core Medium of Exchange Entry

#![allow(unused)]
fn main() {
#[hdk_entry_helper]
#[derive(Clone, PartialEq)]
pub struct MediumOfExchange {
    /// Unique identifier (e.g., 'EUR', 'USD', 'TIME', 'LOCAL')
    pub code: String,
    /// Human-readable name (e.g., 'Euro', 'US Dollar', 'Time Banking', 'Local Currency')
    pub name: String,
    /// Detailed description of the medium of exchange
    pub description: Option<String>,
    /// Exchange type: "base" (foundational categories) or "currency" (specific monetary units)
    pub exchange_type: String,
    /// ID of corresponding hREA ResourceSpecification (only for approved)
    pub resource_spec_hrea_id: Option<String>,
}
}

Input Structures

#![allow(unused)]
fn main() {
// Suggestion/Creation input
pub struct MediumOfExchangeInput {
    pub medium_of_exchange: MediumOfExchange,
}

// Linking input for requests/offers
pub struct MediumOfExchangeLinkInput {
    pub medium_of_exchange_hash: ActionHash,
    pub action_hash: ActionHash,
    pub entity: String, // "request" or "offer"
}

// Update links for entity
pub struct UpdateMediumOfExchangeLinksInput {
    pub action_hash: ActionHash,
    pub entity: String,
    pub new_medium_of_exchange_hashes: Vec<ActionHash>,
}
}

Status Management System

The system uses path-based status tracking with three primary states:

Status Paths

#![allow(unused)]
fn main() {
const PENDING_MEDIUMS_OF_EXCHANGE_PATH: &str = "mediums_of_exchange.status.pending";
const APPROVED_MEDIUMS_OF_EXCHANGE_PATH: &str = "mediums_of_exchange.status.approved";
const REJECTED_MEDIUMS_OF_EXCHANGE_PATH: &str = "mediums_of_exchange.status.rejected";
}

Status Transition Workflow

stateDiagram-v2
    [*] --> Pending: suggest_medium_of_exchange()
    Pending --> Approved: approve_medium_of_exchange()
    Pending --> Rejected: reject_medium_of_exchange()
    Approved --> [*]: Active for linking
    Rejected --> [*]: Cannot be used

Core API Functions

User Operations

#![allow(unused)]
fn main() {
// Suggest new medium of exchange (accepted users + administrators)
#[hdk_extern]
pub fn suggest_medium_of_exchange(input: MediumOfExchangeInput) -> ExternResult<Record>

// Get medium of exchange details
#[hdk_extern]
pub fn get_medium_of_exchange(medium_of_exchange_hash: ActionHash) -> ExternResult<Option<Record>>

// Get latest version of medium
#[hdk_extern]
pub fn get_latest_medium_of_exchange_record(original_action_hash: ActionHash) -> ExternResult<Option<Record>>

// Get all approved mediums (public access)
#[hdk_extern]
pub fn get_approved_mediums_of_exchange(_: ()) -> ExternResult<Vec<Record>>
}

Administrative Operations

#![allow(unused)]
fn main() {
// Approve medium and create hREA ResourceSpec (admin only)
#[hdk_extern]
pub fn approve_medium_of_exchange(medium_of_exchange_hash: ActionHash) -> ExternResult<()>

// Reject medium (admin only)
#[hdk_extern]
pub fn reject_medium_of_exchange(medium_of_exchange_hash: ActionHash) -> ExternResult<()>

// Update medium details (admin only)
#[hdk_extern]
pub fn update_medium_of_exchange(input: UpdateMediumOfExchangeInput) -> ExternResult<Record>

// Delete medium (admin only)
#[hdk_extern]
pub fn delete_medium_of_exchange(medium_of_exchange_hash: ActionHash) -> ExternResult<()>

// Get pending mediums for review (admin only)
#[hdk_extern]
pub fn get_pending_mediums_of_exchange(_: ()) -> ExternResult<Vec<Record>>
}

Entity Linking Operations

#![allow(unused)]
fn main() {
// Create bidirectional links between medium and request/offer
#[hdk_extern]
pub fn link_to_medium_of_exchange(input: MediumOfExchangeLinkInput) -> ExternResult<()>

// Remove bidirectional links
#[hdk_extern]
pub fn unlink_from_medium_of_exchange(input: MediumOfExchangeLinkInput) -> ExternResult<()>

// Update all medium links for entity
#[hdk_extern]
pub fn update_medium_of_exchange_links(input: UpdateMediumOfExchangeLinksInput) -> ExternResult<()>

// Get all mediums linked to entity
#[hdk_extern]
pub fn get_mediums_of_exchange_for_entity(input: GetMediumOfExchangeForEntityInput) -> ExternResult<Vec<ActionHash>>
}

Access Control & Permissions

Permission Matrix

Validation Rules

#![allow(unused)]
fn main() {
// Entry validation
pub fn validate_create_medium_of_exchange(
    _action: &SignedActionHashed,
    medium_of_exchange: &MediumOfExchange,
) -> ExternResult<ValidateCallbackResult> {
    if medium_of_exchange.code.is_empty() {
        return Ok(ValidateCallbackResult::Invalid(
            "MediumOfExchange code cannot be empty".to_string(),
        ));
    }
    if medium_of_exchange.name.is_empty() {
        return Ok(ValidateCallbackResult::Invalid(
            "MediumOfExchange name cannot be empty".to_string(),
        ));
    }
    Ok(ValidateCallbackResult::Valid)
}

// Author verification for updates/deletes
pub fn validate_update_medium_of_exchange(
    action: &SignedActionHashed,
    // ... parameters
) -> ExternResult<ValidateCallbackResult> {
    // Verify author matches original creator
    if action.action().author() != original_create_action.author() {
        return Ok(ValidateCallbackResult::Invalid(
            "Only the original author can update the MediumOfExchange.".to_string(),
        ));
    }
    Ok(ValidateCallbackResult::Valid)
}
}

💻 Frontend Implementation

Type System & Schemas

Core Types

// DHT representation (backend)
export interface MediumOfExchangeInDHT {
  code: string;
  name: string;
  description?: string | null;
  exchange_type: string; // "base" | "currency"
  resource_spec_hrea_id?: string | null;
}

// UI representation (frontend)
export interface UIMediumOfExchange {
  actionHash: ActionHash;
  original_action_hash?: ActionHash;
  code: string;
  name: string;
  description?: string | null;
  exchangeType: "base" | "currency";
  resourceSpecHreaId?: string | null;
  status: "pending" | "approved" | "rejected";
  createdAt: Date;
  updatedAt?: Date;
}

Effect Schema Validation

export const MediumOfExchangeInDHTSchema = Schema.Struct({
  code: Schema.String,
  name: Schema.String,
  description: Schema.optional(Schema.Union(Schema.String, Schema.Null)),
  exchange_type: Schema.Union(
    Schema.Literal("base"),
    Schema.Literal("currency"),
  ),
  resource_spec_hrea_id: Schema.optional(
    Schema.Union(Schema.String, Schema.Null),
  ),
});

export const UIMediumOfExchangeSchema = Schema.Class<UIMediumOfExchange>(
  "UIMediumOfExchange",
)({
  actionHash: Schema.Unknown,
  code: Schema.String,
  name: Schema.String,
  description: Schema.optional(Schema.Union(Schema.String, Schema.Null)),
  exchangeType: Schema.Union(
    Schema.Literal("base"),
    Schema.Literal("currency"),
  ),
  resourceSpecHreaId: Schema.optional(Schema.Union(Schema.String, Schema.Null)),
  status: Schema.Literal("pending", "approved", "rejected"),
  createdAt: Schema.Date,
  updatedAt: Schema.optional(Schema.Date),
});

Service Layer (Effect-TS)

Service Interface

export interface MediumsOfExchangeService {
  readonly suggestMediumOfExchange: (
    mediumOfExchange: MediumOfExchangeInDHT,
  ) => E.Effect<Record, MediumOfExchangeError>;

  readonly getMediumOfExchange: (
    mediumOfExchangeHash: ActionHash,
  ) => E.Effect<Record | null, MediumOfExchangeError>;

  readonly getAllMediumsOfExchange: () => E.Effect<
    Record[],
    MediumOfExchangeError
  >;

  readonly getPendingMediumsOfExchange: () => E.Effect<
    Record[],
    MediumOfExchangeError
  >;

  readonly getApprovedMediumsOfExchange: () => E.Effect<
    Record[],
    MediumOfExchangeError
  >;

  readonly approveMediumOfExchange: (
    mediumOfExchangeHash: ActionHash,
  ) => E.Effect<void, MediumOfExchangeError>;

  readonly rejectMediumOfExchange: (
    mediumOfExchangeHash: ActionHash,
  ) => E.Effect<void, MediumOfExchangeError>;

  // Entity linking operations
  readonly linkToMediumOfExchange: (input: {
    mediumOfExchangeHash: ActionHash;
    actionHash: ActionHash;
    entity: string;
  }) => E.Effect<void, MediumOfExchangeError>;

  readonly updateMediumOfExchangeLinks: (input: {
    actionHash: ActionHash;
    entity: string;
    newMediumOfExchangeHashes: ActionHash[];
  }) => E.Effect<void, MediumOfExchangeError>;
}

Service Implementation Pattern

export const makeMediumsOfExchangeService = E.gen(function* () {
  const client = yield* HolochainClientServiceTag;

  const suggestMediumOfExchange = (mediumOfExchange: MediumOfExchangeInDHT) =>
    E.gen(function* () {
      const result = yield* client.callZome(
        "mediums_of_exchange",
        "suggest_medium_of_exchange",
        { medium_of_exchange: mediumOfExchange },
      );
      return yield* Schema.decodeUnknown(MediumOfExchangeRecordSchema)(result);
    }).pipe(
      E.catchAll((error) =>
        E.fail(
          MediumOfExchangeError({
            context: MEDIUM_OF_EXCHANGE_CONTEXTS.SUGGEST_MEDIUM_OF_EXCHANGE,
            message: "Failed to suggest medium of exchange",
            cause: error,
          }),
        ),
      ),
    );

  return { suggestMediumOfExchange /* ... other methods */ };
});

Store Layer (Svelte 5 + Effect-TS)

Store Factory Pattern

export const createMediumsOfExchangeStore = () => {
  // Reactive state with Svelte 5 Runes
  let entities = $state<UIMediumOfExchange[]>([]);
  let pendingEntities = $state<UIMediumOfExchange[]>([]);
  let approvedEntities = $state<UIMediumOfExchange[]>([]);
  let isLoading = $state(false);
  let error = $state<string | null>(null);

  // Effect-TS operations
  const fetchAllMediumsOfExchange = E.gen(function* () {
    yield* withLoadingState(() =>
      E.gen(function* () {
        const service = yield* MediumsOfExchangeServiceTag;
        const records = yield* service.getAllMediumsOfExchange();
        entities = mapRecordsToUIEntities(records);
      }),
    );
  });

  const suggestMediumOfExchange = (mediumOfExchange: MediumOfExchangeInDHT) =>
    E.gen(function* () {
      const service = yield* MediumsOfExchangeServiceTag;
      const record = yield* service.suggestMediumOfExchange(mediumOfExchange);
      const uiEntity = createUIEntity(record);

      // Update local state
      entities = [...entities, uiEntity];
      pendingEntities = [...pendingEntities, uiEntity];

      // Emit event
      yield* emitMediumOfExchangeSuggested(uiEntity);
      return uiEntity;
    });

  return {
    // Reactive getters
    entities: () => entities,
    pendingEntities: () => pendingEntities,
    approvedEntities: () => approvedEntities,
    isLoading: () => isLoading,
    error: () => error,

    // Operations
    fetchAllMediumsOfExchange,
    suggestMediumOfExchange,
    approveMediumOfExchange,
    rejectMediumOfExchange,
  };
};

Component Layer

MediumOfExchangeForm Component

<script lang="ts">
  import type { UIMediumOfExchange, MediumOfExchangeInDHT } from '$lib/schemas/mediums-of-exchange.schemas';
  import mediumsOfExchangeStore from '$lib/stores/mediums_of_exchange.store.svelte';
  import { runEffect } from '$lib/utils/effect';

  type Props = {
    mediumOfExchange?: UIMediumOfExchange | null;
    mode?: 'create' | 'suggest' | 'edit';
    onSubmitSuccess?: (result: UIMediumOfExchange) => void;
    onCancel?: () => void;
  };

  let { mediumOfExchange = null, mode = 'create', onSubmitSuccess, onCancel }: Props = $props();

  // Form state
  let code = $state(mediumOfExchange?.code ?? '');
  let name = $state(mediumOfExchange?.name ?? '');
  let description = $state(mediumOfExchange?.description ?? '');
  let isSubmitting = $state(false);
  let errors = $state({} as Record<string, string>);

  const isValid = $derived(
    code.trim() !== '' && name.trim() !== '' && Object.keys(errors).length === 0
  );

  const handleSubmit = async (event: Event) => {
    event.preventDefault();
    if (!isValid || isSubmitting) return;

    isSubmitting = true;

    const mediumOfExchange: MediumOfExchangeInDHT = {
      code: code.trim(),
      name: name.trim(),
      description: description.trim() || null
    };

    const effect = mediumsOfExchangeStore.suggestMediumOfExchange(mediumOfExchange);

    try {
      const result = await runEffect(effect);
      onSubmitSuccess?.(result);
    } catch (error) {
      errors = { submit: 'Failed to suggest medium of exchange' };
    } finally {
      isSubmitting = false;
    }
  };
</script>

<form on:submit={handleSubmit} class="space-y-4">
  <label class="label">
    <span>Code (e.g., USD, EUR, TIME)</span>
    <input
      bind:value={code}
      class="input"
      placeholder="Enter unique code"
      required
    />
  </label>

  <label class="label">
    <span>Name</span>
    <input
      bind:value={name}
      class="input"
      placeholder="Enter display name"
      required
    />
  </label>

  <label class="label">
    <span>Description (optional)</span>
    <textarea
      bind:value={description}
      class="textarea"
      placeholder="Describe this medium of exchange"
    ></textarea>
  </label>

  <div class="flex gap-2">
    <button
      type="submit"
      disabled={!isValid || isSubmitting}
      class="btn variant-filled-primary"
    >
      {isSubmitting ? 'Suggesting...' : 'Suggest Medium'}
    </button>

    <button
      type="button"
      on:click={onCancel}
      class="btn variant-ghost"
    >
      Cancel
    </button>
  </div>
</form>

MediumOfExchangeSelector Component

<script lang="ts">
  import type { UIMediumOfExchange } from '$lib/schemas/mediums-of-exchange.schemas';
  import mediumsOfExchangeStore from '$lib/stores/mediums_of_exchange.store.svelte';
  import MediumOfExchangeSuggestionForm from './MediumOfExchangeSuggestionForm.svelte';
  import { onMount } from 'svelte';
  import { runEffect } from '$lib/utils/effect';

  type Props = {
    selectedMediums?: UIMediumOfExchange[];
    onSelectionChange?: (mediums: UIMediumOfExchange[]) => void;
    multiple?: boolean;
    showSuggestionButton?: boolean;
  };

  let { selectedMediums = [], onSelectionChange, multiple = true, showSuggestionButton = true }: Props = $props();

  const approvedMediums = mediumsOfExchangeStore.approvedEntities;
  const isLoading = mediumsOfExchangeStore.isLoading;

  let showSuggestionForm = $state(false);

  // Categorize mediums for enhanced UX
  const baseCategoryMediums = $derived(
    approvedMediums().filter(m => ['PAY_IT_FORWARD', 'LETS', 'TIME'].includes(m.code))
  );

  const currencyMediums = $derived(
    approvedMediums().filter(m => !['PAY_IT_FORWARD', 'LETS', 'TIME'].includes(m.code))
  );

  onMount(async () => {
    const effect = mediumsOfExchangeStore.fetchApprovedMediumsOfExchange();
    await runEffect(effect);
  });

  const handleSelectionChange = (medium: UIMediumOfExchange, selected: boolean) => {
    let newSelection: UIMediumOfExchange[];

    if (multiple) {
      newSelection = selected
        ? [...selectedMediums, medium]
        : selectedMediums.filter(m => m.actionHash !== medium.actionHash);
    } else {
      newSelection = selected ? [medium] : [];
    }

    onSelectionChange?.(newSelection);
  };

  const handleSuggestionSuccess = () => {
    showSuggestionForm = false;
    // Refresh the list to show new suggestion (if approved)
    runEffect(mediumsOfExchangeStore.fetchApprovedMediumsOfExchange());
  };
</script>

<div class="space-y-4">
  <div class="flex justify-between items-center">
    <h4 class="h4">Select Payment Methods</h4>
    {#if showSuggestionButton}
      <button
        class="btn btn-sm variant-outline-primary"
        on:click={() => showSuggestionForm = true}
      >
        Suggest New Medium
      </button>
    {/if}
  </div>

  {#if isLoading()}
    <div class="placeholder animate-pulse">Loading payment methods...</div>
  {:else}
    <!-- Base Categories Section -->
    <div class="space-y-3">
      <div class="flex items-center gap-2">
        <span class="text-lg">📂</span>
        <h5 class="h5">Base Categories</h5>
      </div>
      <div class="grid grid-cols-1 md:grid-cols-2 gap-2">
        {#each baseCategoryMediums as medium}
          {@const isSelected = selectedMediums.some(m => m.actionHash === medium.actionHash)}

          <label class="flex items-center space-x-2 p-3 border rounded-lg cursor-pointer hover:bg-surface-100-800-token">
            <input
              type={multiple ? 'checkbox' : 'radio'}
              checked={isSelected}
              on:change={(e) => handleSelectionChange(medium, e.currentTarget.checked)}
              class="checkbox"
            />
            <div class="flex-1">
              <div class="font-semibold">{medium.name}</div>
              <div class="text-sm opacity-75">{medium.code}</div>
              {#if medium.description}
                <div class="text-xs opacity-60">{medium.description}</div>
              {/if}
            </div>
          </label>
        {/each}
      </div>
    </div>

    <!-- Currencies Section -->
    {#if currencyMediums.length > 0}
      <div class="space-y-3">
        <div class="flex items-center gap-2">
          <span class="text-lg">💰</span>
          <h5 class="h5">Currencies</h5>
        </div>
        <div class="grid grid-cols-1 md:grid-cols-3 gap-2">
          {#each currencyMediums as medium}
            {@const isSelected = selectedMediums.some(m => m.actionHash === medium.actionHash)}

            <label class="flex items-center space-x-2 p-2 border rounded cursor-pointer hover:bg-surface-100-800-token">
              <input
                type="checkbox"
                checked={isSelected}
                on:change={(e) => handleSelectionChange(medium, e.currentTarget.checked)}
                class="checkbox"
              />
              <div class="flex-1">
                <div class="font-medium text-sm">{medium.name}</div>
                <div class="text-xs opacity-75">{medium.code}</div>
              </div>
            </label>
          {/each}
        </div>
      </div>
    {/if}
  {/if}

  <!-- Suggestion Form Modal -->
  {#if showSuggestionForm}
    <div class="card p-4 bg-surface-200-700-token">
      <div class="flex justify-between items-center mb-4">
        <h5 class="h5">Suggest New Medium of Exchange</h5>
        <button
          class="btn btn-sm variant-ghost"
          on:click={() => showSuggestionForm = false}
        >
          ✕
        </button>
      </div>
      <MediumOfExchangeSuggestionForm
        onSubmitSuccess={handleSuggestionSuccess}
        onCancel={() => showSuggestionForm = false}
      />
    </div>
  {/if}
</div>

🔗 hREA Integration

Economic Framework Mapping

The Medium of Exchanges feature integrates with hREA (Holochain Resource-Event-Agent) framework to enable economic coordination:

ResourceSpecification Mapping

// Medium of Exchange → hREA ResourceSpecification
export const mapMediumToResourceSpec = (
  medium: UIMediumOfExchange,
): ResourceSpecification => ({
  name: medium.name,
  note: medium.description || undefined,
  resourceClassifiedAs: [medium.code],
  defaultUnitOfResource: medium.code === "TIME" ? "hours" : "units",
});

Integration Workflow

sequenceDiagram
    participant User as User
    participant App as MoE System
    participant hREA as hREA DNA

    User->>App: Suggest Medium (e.g., "TIME")
    App->>App: Create Entry (status: pending)

    User->>App: Admin Approves Medium
    App->>hREA: Create ResourceSpecification
    hREA-->>App: ResourceSpec ID
    App->>App: Update Entry (add hREA ID, status: approved)

    User->>App: Link Medium to Request
    App->>App: Verify Medium is Approved
    App->>App: Create Bidirectional Links

Approval Process Enhancement

#![allow(unused)]
fn main() {
// When approving medium, create hREA ResourceSpecification
#[hdk_extern]
pub fn approve_medium_of_exchange(medium_of_exchange_hash: ActionHash) -> ExternResult<()> {
    // ... admin permission check ...

    // TODO: Create hREA ResourceSpecification here
    // For now, placeholder ID - will be implemented with full hREA integration
    let resource_spec_id = format!("hrea_resource_spec_{}", entry.code);

    // Update entry with hREA ResourceSpecification ID
    let updated_entry = MediumOfExchange {
        code: entry.code,
        name: entry.name,
        description: entry.description,
        resource_spec_hrea_id: Some(resource_spec_id), // Link to hREA
    };

    // ... update entry and status links ...
}
}

🧪 Testing Strategy

Backend Testing (Sweettest)

Multi-Agent Test Scenarios

test("basic MediumOfExchange suggestion and approval workflow", async () => {
  await runScenarioWithTwoAgents(
    async (_scenario: Scenario, alice: PlayerApp, bob: PlayerApp) => {
      // Setup: Create users and admin
      const aliceUser = sampleUser({ name: "Alice" });
      const aliceUserRecord = await createUser(alice.cells[0], aliceUser);

      const bobUser = sampleUser({ name: "Bob" });
      const bobUserRecord = await createUser(bob.cells[0], bobUser);

      // Register Alice as network administrator
      await registerNetworkAdministrator(
        alice.cells[0],
        aliceUserRecord.signed_action.hashed.hash,
      );

      // Test: Bob suggests a medium of exchange
      const sampleMedium = sampleMediumOfExchange({
        code: "TIME",
        name: "Time Banking Hours",
      });

      const suggestedRecord = await suggestMediumOfExchange(bob.cells[0], {
        medium_of_exchange: sampleMedium,
      });

      // Verify: Medium is created and pending
      assert.ok(suggestedRecord);

      // Test: Alice (admin) approves the medium
      await approveMediumOfExchange(
        alice.cells[0],
        suggestedRecord.signed_action.hashed.hash,
      );

      // Verify: Medium is now approved and has hREA ID
      const approvedMediums = await getApprovedMediumsOfExchange(
        alice.cells[0],
      );
      expect(approvedMediums).toHaveLength(1);

      const approvedMedium = decode(
        approvedMediums[0].entry,
      ) as MediumOfExchange;
      expect(approvedMedium.resource_spec_hrea_id).toBeTruthy();
    },
  );
});

Permission Testing

test("unauthorized users cannot suggest mediums of exchange", async () => {
  await runScenarioWithTwoAgents(
    async (_scenario: Scenario, alice: PlayerApp, bob: PlayerApp) => {
      // Bob tries to suggest without being an accepted user
      const medium = sampleMediumOfExchange();

      try {
        await suggestMediumOfExchange(bob.cells[0], {
          medium_of_exchange: medium,
        });
        expect.fail("Should have thrown unauthorized error");
      } catch (error) {
        expect(error.message).toContain("Unauthorized");
      }
    },
  );
});

Entity Linking Tests

test("link medium of exchange to request", async () => {
  // ... setup approved medium and request ...

  // Link medium to request
  await linkToMediumOfExchange(alice.cells[0], {
    medium_of_exchange_hash: mediumHash,
    action_hash: requestHash,
    entity: "request",
  });

  // Verify bidirectional links
  const linkedRequests = await getRequestsForMediumOfExchange(
    alice.cells[0],
    mediumHash,
  );
  expect(linkedRequests).toHaveLength(1);

  const linkedMediums = await getMediumsOfExchangeForEntity(alice.cells[0], {
    original_action_hash: requestHash,
    entity: "request",
  });
  expect(linkedMediums).toHaveLength(1);
});

Frontend Testing

Store Testing (Effect-TS)

describe("MediumsOfExchangeStore", () => {
  let store: MediumsOfExchangeStore;
  let mockService: MediumsOfExchangeService;

  beforeEach(() => {
    mockService = createMockMediumsOfExchangeService();
    store = createMediumsOfExchangeStore();
  });

  it("should suggest medium of exchange successfully", async () => {
    const medium: MediumOfExchangeInDHT = {
      code: "TIME",
      name: "Time Banking",
      description: "Hour-based time banking system",
    };

    const effect = store.suggestMediumOfExchange(medium);
    const layer = Layer.succeed(MediumsOfExchangeServiceTag, mockService);

    const result = await runEffect(effect, layer);

    expect(result.code).toBe("TIME");
    expect(store.entities()).toHaveLength(1);
    expect(store.pendingEntities()).toHaveLength(1);
  });

  it("should handle approval workflow", async () => {
    // Setup pending medium
    const pendingMedium = createMockUIMediumOfExchange({ status: "pending" });
    store.entities = [pendingMedium];
    store.pendingEntities = [pendingMedium];

    // Approve medium
    const effect = store.approveMediumOfExchange(pendingMedium.actionHash);
    await runEffect(effect, layer);

    // Verify state changes
    expect(store.pendingEntities()).toHaveLength(0);
    expect(store.approvedEntities()).toHaveLength(1);
    expect(store.approvedEntities()[0].status).toBe("approved");
  });
});

Component Testing

describe("MediumOfExchangeSelector", () => {
  it("should display approved mediums for selection", () => {
    const approvedMediums = [
      createMockUIMediumOfExchange({
        code: "USD",
        name: "US Dollar",
        status: "approved",
      }),
      createMockUIMediumOfExchange({
        code: "TIME",
        name: "Time Banking",
        status: "approved",
      }),
    ];

    const { container } = render(MediumOfExchangeSelector, {
      props: { approvedMediums },
    });

    expect(container.querySelectorAll('input[type="checkbox"]')).toHaveLength(
      2,
    );
    expect(container.textContent).toContain("US Dollar");
    expect(container.textContent).toContain("Time Banking");
  });

  it("should handle selection changes correctly", async () => {
    const onSelectionChange = vi.fn();
    const mediums = [createMockUIMediumOfExchange()];

    const { container } = render(MediumOfExchangeSelector, {
      props: { approvedMediums: mediums, onSelectionChange },
    });

    const checkbox = container.querySelector(
      'input[type="checkbox"]',
    ) as HTMLInputElement;
    await fireEvent.click(checkbox);

    expect(onSelectionChange).toHaveBeenCalledWith([mediums[0]]);
  });
});

🎯 Use Cases & Examples

Traditional Currency Support

// Example: USD medium of exchange
const usdMedium: MediumOfExchangeInDHT = {
  code: "USD",
  name: "US Dollar",
  description: "United States Dollar - traditional fiat currency",
};

// Usage in request
const request: RequestInDHT = {
  title: "Website Development",
  description: "Need a business website built",
  // ... other fields
};

// Link USD as accepted payment method
await linkToMediumOfExchange({
  mediumOfExchangeHash: usdMediumHash,
  actionHash: requestHash,
  entity: "request",
});

Alternative Exchange Systems

Time Banking

const timeBankingMedium: MediumOfExchangeInDHT = {
  code: "TIME",
  name: "Time Banking Hours",
  description:
    "Hour-for-hour time exchange system where all hours are valued equally",
};

Local Exchange Trading System (LETS)

const letsMedium: MediumOfExchangeInDHT = {
  code: "LETS_COMMUNITY",
  name: "Community LETS Points",
  description:
    "Local Exchange Trading System points for community resource sharing",
};

Pay It Forward

const payItForwardMedium: MediumOfExchangeInDHT = {
  code: "PAY_IT_FORWARD",
  name: "Pay It Forward",
  description:
    "No direct payment - recipient commits to helping others in the community",
};

Multi-Medium Requests

// Request accepting multiple payment methods
const flexibleRequest: RequestInDHT = {
  title: "Garden Maintenance",
  description: "Weekly garden care and maintenance",
  // ... other fields
};

// Link multiple mediums
const acceptedMediums = [
  usdMediumHash,
  timeBankingMediumHash,
  payItForwardMediumHash,
];

await updateMediumOfExchangeLinks({
  actionHash: requestHash,
  entity: "request",
  newMediumOfExchangeHashes: acceptedMediums,
});

🚀 Administrative Interface

Admin Dashboard Features

Pending Approvals

<!-- Admin dashboard showing pending mediums -->
<script lang="ts">
  import mediumsOfExchangeStore from '$lib/stores/mediums_of_exchange.store.svelte';

  const pendingMediums = mediumsOfExchangeStore.pendingEntities;

  const handleApprove = async (medium: UIMediumOfExchange) => {
    const effect = mediumsOfExchangeStore.approveMediumOfExchange(medium.actionHash);
    await runEffect(effect);
  };

  const handleReject = async (medium: UIMediumOfExchange) => {
    const effect = mediumsOfExchangeStore.rejectMediumOfExchange(medium.actionHash);
    await runEffect(effect);
  };
</script>

<div class="admin-dashboard">
  <h3>Pending Medium of Exchange Approvals</h3>

  {#each pendingMediums() as medium}
    <div class="card p-4 mb-4">
      <div class="flex justify-between items-start">
        <div>
          <h4 class="h4">{medium.name} ({medium.code})</h4>
          {#if medium.description}
            <p class="text-sm opacity-75">{medium.description}</p>
          {/if}
          <p class="text-xs opacity-60">Suggested: {medium.createdAt.toLocaleDateString()}</p>
        </div>

        <div class="flex gap-2">
          <button
            class="btn btn-sm variant-filled-success"
            on:click={() => handleApprove(medium)}
          >
            Approve
          </button>
          <button
            class="btn btn-sm variant-filled-error"
            on:click={() => handleReject(medium)}
          >
            Reject
          </button>
        </div>
      </div>
    </div>
  {/each}
</div>

System Statistics

// Admin analytics for medium usage
interface MediumUsageStats {
  medium: UIMediumOfExchange;
  requestCount: number;
  offerCount: number;
  popularityScore: number;
}

const calculateMediumUsageStats = async (): Promise<MediumUsageStats[]> => {
  const approvedMediums = await getAllApprovedMediums();
  const stats: MediumUsageStats[] = [];

  for (const medium of approvedMediums) {
    const requests = await getRequestsForMediumOfExchange(medium.actionHash);
    const offers = await getOffersForMediumOfExchange(medium.actionHash);

    stats.push({
      medium,
      requestCount: requests.length,
      offerCount: offers.length,
      popularityScore: requests.length + offers.length,
    });
  }

  return stats.sort((a, b) => b.popularityScore - a.popularityScore);
};

🔮 Future Enhancements

Phase 1: Enhanced hREA Integration

• Complete ResourceSpecification Creation: Full integration with hREA DNA
• Economic Event Tracking: Track actual exchanges using approved mediums
• Agreement Templates: Pre-defined exchange agreements for common mediums

Phase 2: Advanced Features

• Exchange Rate Management: Support for conversion rates between different mediums
• Geographic Scope: Regional availability and restrictions for mediums
• Verification System: Community verification for alternative currency systems

Phase 3: Analytics & Intelligence

• Usage Analytics: Detailed statistics on medium popularity and usage patterns
• Recommendation Engine: Suggest appropriate mediums based on request/offer characteristics
• Trend Analysis: Track adoption of alternative currencies within the community

Phase 4: Integration Expansion

• External Currency APIs: Real-time exchange rates for traditional currencies
• Blockchain Integration: Support for cryptocurrency mediums
• Banking Integration: Direct integration with payment processors for traditional currencies

📊 Current Implementation Status

✅ Completed Features

• Backend Implementation: Complete Rust zome with all core functions
• Status Management: Full approval workflow with path-based tracking
• Entity Linking: Bidirectional linking with requests and offers
• Access Control: Comprehensive permission system
• Frontend Service Layer: Effect-TS service with error handling
• Store Implementation: Svelte 5 + Effect-TS reactive store with all 9 standardized helper functions
• Enhanced UI Components: Complete form and selector components with categorization
• Testing Infrastructure: Sweettest tests and frontend unit tests (all 343 tests passing across 20 files)
• UI/UX Enhancements: Generic vs specific MoE distinction, suggestion functionality
• Form Integration: Seamless integration across requests and offers forms

🎉 Major Achievements

• Visual Distinction: Clear separation between "Base Categories" (📂) and "Currencies" (💰)
• Interactive Checkbox Interface: Enhanced user experience with dynamic currency selection
• Suggestion System: MediumOfExchangeSuggestionForm.svelte component for user contributions
• Navigation Cleanup: Removed unnecessary public page and fixed all broken links
• Complete Architecture: Full 7-layer Effect-TS implementation with domain-specific tagged errors

🔄 In Progress (5% Remaining)

• Final Verification: Comprehensive testing across all scenarios
• UI/UX Polish: Minor adjustments based on real-world usage testing
• Cross-Browser Validation: Ensuring compatibility across different browsers

📋 Future Enhancements

• Analytics Dashboard: Usage statistics and trend analysis
• Enhanced hREA Integration: Full ResourceSpecification creation workflow
• Advanced Features: Exchange rate management, geographic scope, verification systems

This comprehensive documentation provides complete technical coverage of the Medium of Exchanges feature, from backend Rust implementation through frontend TypeScript/Svelte integration, including testing strategies and future enhancement roadmap.

Organization Contact Person

Overview

Each organization can designate a single contact person — a coordinator who serves as the public-facing representative. The contact person is stored as an OrganizationContacts link with the role/title encoded in the link tag.

Key Concepts

• Single contact per organization: Setting a new contact automatically replaces the previous one
• Coordinator-only: Only organization coordinators can be designated as contact person
• Role/title: A free-text field (e.g. "Director", "President", "Contact Person") stored in the link tag
• Auto-cleanup: Contact links are automatically removed when the contact person leaves, is removed from the organization, or the organization is deleted

Backend API

Link Type

#![allow(unused)]
fn main() {
// In dnas/requests_and_offers/zomes/integrity/users_organizations/src/lib.rs
pub enum LinkTypes {
    // ... existing link types ...
    OrganizationContacts,  // Organization → User (tag = role string)
}
}

The OrganizationContacts link connects an organization's ActionHash to a user's ActionHash, with the role/title encoded as the link tag bytes.