# System Architecture

The Soleer software architecture combines on-chain and off-chain components to optimize for both decentralization and performance. The on-chain components ensure trust and transparency for critical operations, while the off-chain components allow for faster data retrieval and complex computations that would be inefficient or expensive to perform entirely on-chain.

<figure><img src="https://1080040105-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0SHqY1UQUyLj1RVrobCJ%2Fuploads%2F55Cym18M2Mjn1WCAH2XF%2Fmermaid-diagram-2024-10-29-125246.png?alt=media&#x26;token=297df591-2dc0-4ccd-bf05-70ae5480f8f3" alt=""><figcaption><p>Soleer Highlevel Architecture</p></figcaption></figure>

The hybrid approach allows Soleer to leverage the benefits of blockchain technology while maintaining the responsiveness and flexibility expected in modern web applications. This architecture can scale to handle a large number of users and transactions while keeping costs low and ensuring a smooth user experience.

<figure><img src="https://1080040105-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0SHqY1UQUyLj1RVrobCJ%2Fuploads%2FBY7BWOYkopacKYkdmcOH%2Fmermaid-diagram-2024-10-29-125413.png?alt=media&#x26;token=b95abbb3-dc79-4780-ae40-b9d48e617b72" alt=""><figcaption><p>Component Interaction</p></figcaption></figure>

### System Architecture

#### 2.1 State Definitions

The global state Σ of Soleer at time t is defined as:`Σ`

`t = (L, E, R, T)`

* **L**: Set of active service listings
* **E**: Set of active escrow contracts
* **R**: Mapping of reputation scores
* **T**: Set of completed transactions

#### 2.2 Service Listing Model

A service listing l ∈ L is defined as:

`l = (id, s, μ, ρ, τ, α)`

* **id**: Unique identifier
* **s ∈ S**: Service provider
* **μ**: Service metadata (skills, certifications, description)
* **ρ**: Price in USD-equivalent, payable in supported tokens
* **τ**: Service duration
* **α**: Boolean activation status

Listings are stored off-chain (e.g., IPFS, Arweave) with on-chain hashes for verification, balancing scalability and decentralization.

#### 2.3 Transaction and Escrow Process

1. Client locks funds in the Escrow Contract, quoted in USD-equivalent and settled in tokens (e.g., SOL, $SLR, USDC).
2. Service provider delivers the service.
3. Client approves work, triggering fund release.
4. Both parties’ reputation scores are updated on-chain.

## 2. Smart Contract Infrastructure

#### Program Architecture

Soleer platform consists of three main program modules:

1. **Listing Program**
   * Manages service listings
   * Handles search and discovery
   * Updates listing status
2. **Escrow Program**
   * Controls transaction flow
   * Manages fund locks and releases
   * Handles dispute resolution
3. **Reputation Program**
   * Calculates user scores
   * Processes reviews
   * Updates reputation metrics

<figure><img src="https://1080040105-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0SHqY1UQUyLj1RVrobCJ%2Fuploads%2FZhSjSduQeYYVMmUA11M6%2Fmermaid-diagram-2024-10-29-125757.png?alt=media&#x26;token=484252eb-efd0-4816-8c84-5a0623b6c2b2" alt=""><figcaption><p>Core Contract Interations</p></figcaption></figure>

## 3. Core Processes

#### Service Listing Process

1. **Listing Creation**

   ```typescript
   typescriptCopyasync function createListing(
     provider: PublicKey,
     details: ListingDetails
   ): Promise<PublicKey>
   ```

   * Validates provider credentials
   * Creates on-chain listing record
   * Stores extended metadata in IPFS
   * Returns listing public key
2. **Listing Discovery**
   * Implements indexed search
   * Filters by category, price, reputation
   * Integrates with AI recommendations

<figure><img src="https://1080040105-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0SHqY1UQUyLj1RVrobCJ%2Fuploads%2FOcJnADNzb7j0eCYzTmZv%2Fmermaid-diagram-2024-10-29-130043.png?alt=media&#x26;token=b9c07fdf-4a13-42df-b00c-c707e65f2d13" alt=""><figcaption><p>Transaction Flow</p></figcaption></figure>

## 4. Data Models

#### Service Listing Structure

```typescript
typescriptCopyinterface ServiceListing {
    id: PublicKey;
    provider: PublicKey;
    title: string;
    description: string;
    category: string;
    basePrice: BN;
    acceptedTokens: PublicKey[];
    reputation: number;
    status: ListingStatus;
    metadata: string;
}
```

#### Escrow Account Structure

```typescript
typescriptCopyinterface EscrowAccount {
    id: PublicKey;
    listing: PublicKey;
    client: PublicKey;
    provider: PublicKey;
    amount: BN;
    token: PublicKey;
    status: EscrowStatus;
    deliveryDeadline: BN;
    disputeResolver: PublicKey | null;
}
```

## 5. Security Considerations

#### Transaction Security

1. **Multi-signature Requirements**
   * Client approval for fund release
   * Provider confirmation of service delivery
   * Arbitrator signatures for dispute resolution
2. **Time Locks**
   * Minimum escrow duration: 24 hours
   * Maximum escrow duration: 30 days
   * Dispute resolution window: 7 days

#### Access Control

<figure><img src="https://1080040105-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0SHqY1UQUyLj1RVrobCJ%2Fuploads%2FwBNqxWsmquLaKJpZxmUq%2Fmermaid-diagram-2024-10-29-130427.png?alt=media&#x26;token=7316db01-b3ce-47a7-9e03-38c9d4ac326b" alt=""><figcaption><p>Access Control Workflow</p></figcaption></figure>