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

Backend: Create coordinator & integrity zomes
Service: Implement Effect-TS service with Context.Tag
Store: Create store with 9 standardized helper functions
Composable: Extract business logic
Components: Build UI with accessibility focus
Errors: Define domain-specific tagged errors
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

Entity Creation Helper - Converts records to UI entities
Record Mapping Helper - Maps arrays with error recovery
Cache Sync Helper - Synchronizes cache with state arrays
Event Emission Helpers - Standardized event broadcasting
Data Fetching Helper - Higher-order fetching with loading states
Loading State Helper - Wraps operations with loading patterns
Record Creation Helper - Processes new records and updates cache
Status Transition Helper - Manages status changes atomically
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

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.

Requests & Offers Documentation