# Architecture Deep Dive

### System Overview

ckBoost is designed as a modular, secure, and scalable protocol with clean separation of concerns.

{% @mermaid/diagram content="graph TB
subgraph "Internet Computer"
subgraph "ckBoost Protocol"
A\[Main Canister] --> B\[Ledger Module]
A --> C\[Validation Module]
A --> D\[Booster Account Module]
A --> E\[Minting Operations Module]
A --> F\[Boost Request Module]
A --> G\[State Management]
end

```
    subgraph "External IC Canisters"
        H[ckBTC Ledger]
        I[ckBTC Minter]
    end
end

subgraph "Bitcoin Network"
    J[Bitcoin Addresses]
    K[Bitcoin Transactions]
end

A --> H
A --> I
I --> J
K --> I
```

" %}

### Canister Architecture

#### Core Modules

**1. Main Canister (`main.mo`)**

**Purpose**: Orchestration layer and public API **Responsibilities**:

* Expose public functions defined in Candid interface
* Coordinate between modules
* Handle authentication and authorization
* Manage system state

**2. State Management (`state.mo`)**

**Purpose**: Centralized state storage with persistence **Responsibilities**:

* Store all boost requests
* Store all booster accounts
* Provide atomic updates
* Handle canister upgrades

**3. Ledger Operations (`ledger.mo`)**

**Purpose**: All ICRC-1 token operations **Responsibilities**:

* Handle ckBTC transfers
* Manage transaction fees
* Account balance queries
* Error handling and logging

**4. Validation Module (`validation.mo`)**

**Purpose**: Input validation and business rules **Responsibilities**:

* Validate amounts and fees
* Check business logic constraints
* Sanitize inputs

**5. Booster Account Management (`booster_account.mo`)**

**Purpose**: Liquidity provider operations **Responsibilities**:

* Register new boosters
* Manage deposits and withdrawals
* Track available balances
* Handle pool operations

**6. Minting Operations (`minting_operations.mo`)**

**Purpose**: Complex ckBTC minting workflows **Responsibilities**:

* Two-phase minting processes
* Cross-canister call management
* Error recovery and retry logic
* Fund reclamation flows

### Data Architecture

#### Type System

```motoko
// Core types with clear relationships
type BoostRequest = {
  id: Nat;
  owner: Principal;
  amount: Nat;                    // Amount in satoshis
  maxFeePercentage: Float;        // Maximum fee user will pay
  receivedBTC: Nat;               // Actually received Bitcoin
  btcAddress: ?Text;              // Generated Bitcoin address
  subaccount: Blob;               // Isolated subaccount
  status: BoostStatus;            // Current state
  matchedBooster: ?Principal;     // Which booster accepted
  createdAt: Int;                 // Timestamp
  updatedAt: Int;                 // Last modification
};

type BoosterAccount = {
  owner: Principal;
  feePercentage: Float;           // Fee this booster charges
  subaccount: Blob;               // Booster's isolated subaccount
  availableBalance: Nat;          // Available for new boosts
  totalDeposited: Nat;            // Lifetime deposits
  totalWithdrawn: Nat;            // Lifetime withdrawals
  totalBoosted: Nat;              // Volume provided
  totalFeesEarned: Nat;           // Fees earned
  createdAt: Int;
  updatedAt: Int;
};
```

#### State Transitions

{% @mermaid/diagram content="stateDiagram-v2
\[\*] --> pending : registerBoostRequest()

```
pending --> active : acceptBoostRequest()
pending --> minting : triggerMintingForMyBoostRequest()
pending --> cancelled : User cancels

active --> boosted : ckBTC transferred

boosted --> minting : triggerMintingForBoostReclaim()

minting --> completed : claimMintedFunds() / claimMintedCKBTC()

cancelled --> [*]
completed --> [*]" %}
```

### Security Architecture

#### Trust Boundaries

{% @mermaid/diagram content="graph TB
subgraph "Trusted Zone (ckBoost Canister)"
A\[Main Logic]
B\[State Storage]
C\[Subaccount Management]
end

```
subgraph "External Trust (IC System Canisters)"
    D[ckBTC Ledger]
    E[ckBTC Minter]
end

subgraph "Untrusted Zone"
    F[User Inputs]
    G[Bitcoin Network]
    H[External Calls]
end

F --> A
A --> D
A --> E
G --> E
H --> A" %}
```

#### Fund Isolation Strategy

Every operation uses isolated subaccounts to prevent fund mixing:

**Security Benefits:**

* Request funds cannot be mixed with other requests
* Booster funds cannot be mixed with user funds
* Clear audit trail for every satoshi
* Isolated failure domains

***

**Next**: API Reference →