> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gizatech.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Architecture Overview

> System components, agent lifecycle, and data flow

## System Architecture

```mermaid theme={null}
graph TB
    subgraph "Partner Application"
        A[Your App]
    end

    subgraph "Giza Agent SDK"
        B[Giza Client]
        C[Agent Class]
        D[Optimizer]
    end

    subgraph "Giza Infrastructure"
        E[Backend API]
        F[Agent Service]
        G[Intelligence-as-a-Service]
    end

    subgraph "Blockchain"
        H[Smart Account]
        I[Session Keys]
        J[DeFi Protocols]
    end

    A --> B
    B --> C
    B --> D
    C --> E
    D --> G
    E --> F
    F --> H
    H --> I
    I --> J
```

## Components

### Giza Client

The entry point for all SDK interactions. Initialize once and reuse throughout your application.

```typescript theme={null}
import { Giza, Chain } from '@gizatech/agent-sdk';

const giza = new Giza({ chain: Chain.BASE });
```

### Agent Class

Manages a single user's smart account. Handles activation, monitoring, withdrawals, and protocol management.

### Optimizer

A stateless service that calculates optimal capital allocation across DeFi protocols. Used automatically by agents (Agentic approach) or called directly (IaaS approach). See [Optimizer](/developers/architecture/optimizer) for details.

### Smart Accounts

ERC-4337 smart contract wallets powered by ZeroDev. Each user gets a deterministic smart account address where they deposit funds. See [Smart Accounts](/developers/architecture/smart-accounts) for details.

## Agent Lifecycle

<Steps>
  <Step title="Inactive">
    Smart account exists but no agent is activated. User funds are not being managed.
  </Step>

  <Step title="Activating">
    Agent initialization in progress. Session keys being granted, initial deposits being allocated. Brief transition state.
  </Step>

  <Step title="Active">
    Agent is running and optimizing. Capital is deployed across protocols, automatic rebalancing occurs.
  </Step>

  <Step title="Deactivating">
    Withdrawal in progress. Agent pulling funds from all protocols, revoking permissions. Brief transition state.
  </Step>

  <Step title="Deactivated">
    Agent stopped, funds returned to user. No active management. Can be reactivated.
  </Step>

  <Step title="Activation Failed">
    Activation encountered an error. Funds remain safe in smart account. User can retry or withdraw.
  </Step>
</Steps>

## Optimization Cycle

Once active, the agent runs a continuous optimization loop:

1. **Monitor** -- Continuously monitors APRs across selected protocols
2. **Analyze** -- Calculates optimal allocation considering APRs, gas costs, slippage, protocol limits, and user constraints
3. **Execute** -- If rebalancing improves net returns (after gas), executes transactions
4. **Report** -- Updates performance metrics and portfolio data
5. **Repeat** -- Continues monitoring for next opportunity

## Data Flow

```mermaid theme={null}
sequenceDiagram
    participant App as Your App
    participant SDK as Giza SDK
    participant API as Giza API
    participant Agent as Agent Service
    participant SA as Smart Account
    participant Protocol as DeFi Protocol

    App->>SDK: createAgent(eoa)
    SDK->>API: POST /smart-accounts
    API-->>SDK: smartAccountAddress
    SDK-->>App: Agent handle

    Note over App: User deposits to smart account

    App->>SDK: agent.activate({owner, token, protocols, txHash})
    SDK->>API: POST /wallets (activate)
    API->>Agent: Initialize agent
    Agent->>SA: Setup session keys
    SA-->>Agent: Permissions granted
    Agent-->>API: Agent activated
    API-->>SDK: ActivateResponse
    SDK-->>App: Success

    loop Every optimization cycle
        Agent->>Protocol: Check APRs
        Protocol-->>Agent: Current rates
        Agent->>Agent: Calculate optimal allocation
        Agent->>SA: Execute rebalancing
        SA->>Protocol: Deposit/Withdraw
    end
```

## Session Keys

Session keys let agents execute specific functions on behalf of smart accounts without requiring user signatures each time.

1. User grants permissions to a session key when activating the agent
2. Session key has specific capabilities (approved contracts, functions, limits)
3. Agent uses session key to execute rebalancing transactions
4. User can revoke permissions at any time by deactivating

Session keys are time-bound, limited in scope, and revocable. See [Smart Accounts](/developers/architecture/smart-accounts) for the full security model.

## Next Steps

<CardGroup cols={2}>
  <Card title="Smart Accounts" icon="shield-halved" href="/developers/architecture/smart-accounts">
    Smart account architecture, ZeroDev, and session keys
  </Card>

  <Card title="Protocols" icon="layer-group" href="/developers/architecture/protocols">
    Supported protocols by chain
  </Card>

  <Card title="Optimizer" icon="chart-mixed" href="/developers/architecture/optimizer">
    How the optimization engine works
  </Card>

  <Card title="Constraints" icon="sliders" href="/developers/architecture/constraints">
    All constraint types for controlling agent behavior
  </Card>
</CardGroup>