feat: hooks first architecture

[jonybur]

Vault Architecture - Hooks-First Pattern

Core Principles

1. Business Logic in Hooks - All business logic, orchestration, and state management lives in custom hooks
2. Pure Service Functions - Services contain only pure functions for calculations and transformations
3. Presentational Components - Components are purely presentational with no business logic
4. Composable Patterns - Hooks can be composed to create complex behaviors from simple pieces

Architecture Layers

┌─────────────────────────────────────────────┐
│         Presentation Layer                   │
│  Components (Pure UI, no business logic)     │
└────────────────┬────────────────────────────┘
                 │
┌────────────────▼────────────────────────────┐
│         Business Logic Layer                 │
│  Hooks (Orchestration, State, Side Effects)  │
└────────────────┬────────────────────────────┘
                 │
┌────────────────▼────────────────────────────┐
│           Service Layer                      │
│  Pure Functions (Calculations, Validations)  │
└────────────────┬────────────────────────────┘
                 │
┌────────────────▼────────────────────────────┐
│             API Layer                        │
│  Data Fetching (React Query, API Clients)    │
└─────────────────────────────────────────────┘

Directory Structure

src/
├── components/           # Presentational components only
│   └── [feature]/       # Feature-specific components
│
├── hooks/               # Business logic hooks
│   ├── [feature]/      # Feature-specific hooks
│   │   ├── use[Feature]Flow.ts      # Main orchestration
│   │   ├── use[Feature]Form.ts      # Form logic
│   │   └── use[Feature]State.ts     # State management
│   └── shared/         # Shared hooks
│
├── services/           # Pure service functions
│   ├── [feature]/     # Feature-specific services
│   │   ├── calculations.ts
│   │   ├── validations.ts
│   │   └── transformers.ts
│   └── shared/        # Shared services
│
├── api/               # API layer
│   ├── queries/       # React Query queries
│   ├── mutations/     # React Query mutations
│   └── clients/       # Raw API clients
│
├── types/             # TypeScript definitions
├── utils/             # Utility functions
└── constants/         # Application constants

Benefits of This Architecture

1. Clear Separation - Business logic is clearly separated from UI
2. Testability - Each layer can be tested independently
3. Reusability - Hooks and services can be reused across components
4. Developer Experience - Familiar React patterns
5. Progressive Migration - Can migrate feature by feature

Migrated to New Architecture

Deposit Flow (Partial)

• DepositFormModal - Form entry and validation
• DepositSignModal - Transaction signing and submission
• DepositOverview - Deposit list and state management
• Overview - Global deposit state coordination

Status: Core deposit entry and signing migrated, but review and success modals still use old architecture

Not Yet Migrated (Old Architecture)

Deposit Flow (Remaining)

• DepositReviewModal - Transaction review before signing
• DepositSuccessModal - Success confirmation
• BroadcastSignModal - Bitcoin transaction broadcasting
• BroadcastSuccessModal - Broadcast success confirmation
• PayoutSignModal - Payout transaction signing

Redeem Flow (Complete)

• RedeemFormModal - Redeem request form
• RedeemReviewModal - Redeem transaction review
• RedeemSignModal - Redeem transaction signing
• RedeemSuccessModal - Redeem success confirmation

Position Management

• All position-related components still use old architecture

Market Operations

• All market-related components still use old architecture

Summary

Migrated: 4 components (deposit form, sign, overview, coordination)
Not Migrated: 16+ components (review modals, redeem flow, position, market)
Migration Progress: Approximately 20%

[Copilot]

Pull Request Overview

This PR introduces a hooks-first architecture to improve code organization in the vault service. The refactoring separates business logic (in hooks) from pure utility functions (in services) and presentational code (in components), following a React-centric approach for better maintainability.

Key Changes:

• Created a three-layer service architecture with calculations, validations, and transformers
• Implemented deposit flow orchestration using custom React hooks
• Added comprehensive architecture documentation with migration guides

Reviewed Changes

Copilot reviewed 14 out of 14 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
services/vault/src/services/deposit/validations.ts	Pure validation functions for deposit amounts, balances, UTXOs, providers, and BTC addresses
services/vault/src/services/deposit/transformers.ts	Data transformation functions for converting between formats and user-friendly displays
services/vault/src/services/deposit/calculations.ts	Pure calculation functions for fees, UTXO selection, and transaction sizing
services/vault/src/services/deposit/index.ts	Barrel export aggregating all deposit service functions
services/vault/src/hooks/deposit/useDepositValidation.ts	Hook for deposit validation logic integrating service functions
services/vault/src/hooks/deposit/useDepositTransaction.ts	Hook for transaction creation and submission
services/vault/src/hooks/deposit/useDepositFlow.ts	Main orchestration hook managing the complete deposit flow
services/vault/src/hooks/deposit/index.ts	Barrel export for deposit hooks and types
services/vault/MIGRATION_GUIDE.md	Comprehensive guide for migrating features to the new architecture
services/vault/ARCHITECTURE_OPTION_3.md	Detailed documentation of the hooks-first architecture pattern
services/vault/ARCHITECTURE_OPTION_2.md	Alternative feature-based modular architecture documentation
services/vault/ARCHITECTURE_OPTION_1.md	Alternative clean layered architecture documentation
services/vault/ARCHITECTURE_COMPARISON.md	Comparison of architecture options with recommendations
services/vault/ARCHITECTURE.md	Main architecture documentation for the chosen hooks-first pattern

Comments suppressed due to low confidence (1)

services/vault/MIGRATION_GUIDE.md:1

• Contains an unusual memory reference marker [[memory:10537065]] that appears to be an artifact or debug reference. This should be removed from the documentation.

# Migration Guide - Hooks-First Architecture

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[jonybur]

@copilot

[Copilot]

@jonybur I've opened a new pull request, #564, to work on those changes. Once the pull request is ready, I'll request review from you.

[gbarkhatov]

@jonybur approving
My suggestion for future is that we split such issues into multiple sub issues
I would review 3-5 PRs instead of such a big one, step by step - with tests being a part of another PR for sure
Code wise looks good, moving into a proper direction. As long as functionality is there, I think we are okay to merge it

[gbarkhatov]

Do we have a ticket for that? Let's resolve once ticket is there, point to this line of code (or PR comment)