Back to catalog

Effect-TS Architecture

This skill should be used when implementing 7-layer Effect-TS architecture patterns, creating standardized services and stores, implementing domain-specific error handling, or validating architectural consistency across Holochain hApp domains

• Category: discovered
• Tags: github, community
• Version: 1.0.0
• Author: walid
• Downloads: 0
• GitHub stars: 11
• Updated: 2025-12-22

• Source: happenings-community/requests-and-offers

Download the latest version (v1.0.0) from this page.

SKILL.md

---
name: Effect-TS Architecture
description: This skill should be used when implementing 7-layer Effect-TS architecture patterns, creating standardized services and stores, implementing domain-specific error handling, or validating architectural consistency across Holochain hApp domains
---

# Effect-TS 7-Layer Architecture Skill

This skill provides the complete 7-layer Effect-TS architecture pattern used successfully across 8 domains in production Holochain applications.

## Capabilities

Implement robust Holochain hApps with:
- **7-Layer Architecture**: Service Layer, Store Layer, Schema Validation, Error Handling, Composables, Components, Testing
- **Standardized Patterns**: Consistent implementation across all domains with 9 helper functions
- **Effect-Native Services**: Context.Tag dependency injection with composable error handling
- **Reactive Stores**: Svelte 5 Runes with Effect integration and comprehensive state management
- **Type Safety**: End-to-end TypeScript safety with Effect Schema validation

## How to Use

1. **Domain Implementation**: Create new domains following the 7-layer pattern
2. **Architecture Validation**: Ensure consistency with automated validation tools
3. **Template Generation**: Use proven templates for rapid development
4. **Best Practices**: Apply established patterns for maintainable code

## Quick Implementation

**For New Domain:**
```typescript
// Service Layer (Layer 1)
export const MyDomainService = Context.GenericTag<MyDomainService>("MyDomainService");

// Store Layer (Layer 2) with 9 helper functions
export const createMyDomainStore = Effect.gen(function* () {
  // Implements: createUIEntity, mapRecordsToUIEntities, createCacheSyncHelper,
  // createStatusAwareEventEmitters, createEntitiesFetcher, withLoadingState,
  // createRecordCreationHelper, createStatusTransitionHelper, processMultipleRecordCollections
});

// Schema Layer (Layer 3)
export const CreateMyDomainSchema = Schema.Struct({
  name: Schema.String,
  // ... other fields
});
```

## Example Usage

**Concrete Examples of Skill Application:**

- **Domain Implementation**: "Create a new Reviews domain following our 7-layer architecture pattern"
  - *Expected outcome*: Complete domain with all 7 layers properly implemented
  - *Validation*: Architecture validator scores 95+ and passes consistency checks

- **Service Layer Generation**: "Generate the service layer for a ResourceManagement domain with proper error handling"
  - *Expected outcome*: Effect-TS service with Context.Tag pattern and domain-specific errors
  - *Validation*: Service compiles and integrates properly with Holochain client

- **Architecture Validation**: "Validate that our new domain follows all 7 architectural layers correctly"
  - *Expected outcome*: Detailed compliance report with specific improvement recommendations
  - *Validation*: All missing components identified and architectural score provided

- **Store Implementation**: "Create a store with all 9 standardized helper functions for the Notifications domain"
  - *Expected outcome*: Complete reactive store with Svelte 5 runes integration
  - *Validation*: Store functions work correctly and maintain proper state management

## Scripts

- `architecture-check.ts`: Validates 7-layer implementation with scoring system
- `service.template.ts`: Service layer template with Context.Tag pattern
- `store.template.ts`: Store template with 9 helper functions

## Best Practices

1. **Use Context.Tag** for service dependency injection
2. **Implement all 9 helper functions** in every store for consistency
3. **Use Effect Schema** at service boundaries for validation
4. **Create domain-specific tagged errors** with meaningful contexts
5. **Test with Tryorama** for multi-agent scenarios

## Reference Implementation

The Service Types domain provides the complete reference implementation:
- All 7 architectural layers fully implemented
- 9 standardized helper functions with comprehensive documentation
- Status management workflows (pending/approved/rejected)
- Complete test coverage with property-based testing

## Validation Results

The architecture validator provides:
- Score from 0-100 for implementation completeness
- Specific error messages for missing components
- Recommendations for improvements
- Consistency checks across all layers

## Progressive Loading

This skill uses progressive disclosure:
- **Level 1**: Metadata (~100 tokens) - Always loaded
- **Level 2**: Instructions (<5k tokens) - Loaded when triggered
- **Level 3**: Templates and examples - Loaded as needed

## File Structure

```
effect-ts-7layer-architecture/
├── SKILL.md                    # Main documentation (this file)
├── templates/                  # Code templates
│   ├── service.template.ts     # Service layer template
│   └── store.template.ts       # Store layer with 9 helpers
└── validation/                 # Architecture validation
    └── architecture-check.ts   # Implementation validator
```

## Integration

Works seamlessly with:
- **Holochain Development Skill**: For zome and DNA implementation
- **Effect-TS**: Native integration for composable effects
- **Svelte 5**: Runes and reactive state management
- **Tryorama**: Multi-agent testing scenarios

## Proven Results

This architecture has been battle-tested in production:
- **8 fully implemented domains** with 100% consistency
- **268 passing unit tests** with comprehensive coverage
- **40-60% faster development** through pattern reuse
- **90% reduction in architectural drift** across domains