> For the complete documentation index, see [llms.txt](https://docs.soleer.xyz/soleerlabs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.soleer.xyz/soleerlabs/soleer-architecture/markdown.md).

# 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="/files/EQy2jjBkCwnsbrmiRTBs" 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="/files/y7vFTkxAM1kqBHI5d9d3" 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="/files/4PtBjY91FwsIwHsnhFct" 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="/files/XDEywyPTZDZam7FTOHA2" 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="/files/avLiKjE3xAiprQpHH7wf" alt=""><figcaption><p>Access Control Workflow</p></figcaption></figure>