# 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>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.soleer.xyz/soleerlabs/soleer-architecture/markdown.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.