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

# Architecture Overview

> High-level overview of SHIELD's system architecture

# Architecture Overview

SHIELD uses a hybrid architecture combining client-side encryption, decentralized storage, and on-chain access control to provide trustless secure file sharing.

## System Architecture

```
┌─────────────────────────────────────────────────────────────────────┐
│                          USER BROWSER                                │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐ │
│  │   Encrypt   │  │   SIWE      │  │  Contract   │  │  Decrypt    │ │
│  │  (Web Crypto)│ │   Sign      │  │   Calls     │  │  (Web Crypto)│ │
│  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘ │
└─────────┼────────────────┼────────────────┼────────────────┼──────┘
          │                │                │                │
          ▼                │                │                ▼
┌─────────────────┐       │                │       ┌─────────────────┐
│      IPFS       │◀──────┘                └──────▶│      IPFS       │
│   (Pinata)      │                                │   (Pinata)      │
└─────────────────┘                                └─────────────────┘
          ▲                                                │
          │                                                │
          │                                                ▼
          │                              ┌─────────────────────────────┐
          │                              │         SHIELD API           │
          │                              │  ┌──────────┐ ┌──────────┐ │
          └──────────────────────────────│  │  Policy  │ │  Access  │ │
                                         │  │   Store  │ │   Logs   │ │
                                         │  └──────────┘ └──────────┘ │
                                         └──────────┬─────────────────┘
                                                    │
                                                    ▼
                                         ┌─────────────────────────────┐
                                         │     BASE BLOCKCHAIN         │
                                         │  ┌─────────────────────┐   │
                                         │  │   Shield Contract   │   │
                                         │  │  ┌───────────────┐  │   │
                                         │  │  │ AccessPolicy  │  │   │
                                         │  │  │   Mapping     │  │   │
                                         │  │  └───────────────┘  │   │
                                         │  └─────────────────────┘   │
                                         └─────────────────────────────┘
```

## Components

### Client-Side Encryption

All encryption happens in the browser using the Web Crypto API:

* **Algorithm**: AES-GCM 256-bit
* **Key Generation**: Crypto.getRandomValues (CSPRNG)
* **IV**: 96-bit random nonce
* **Authentication**: Built-in GCM tag

```javascript theme={null}
// Simplified encryption flow
const key = await crypto.subtle.generateKey(
  { name: 'AES-GCM', length: 256 },
  true,
  ['encrypt', 'decrypt']
);

const encrypted = await crypto.subtle.encrypt(
  { name: 'AES-GCM', iv },
  key,
  fileData
);
```

### IPFS Storage

Encrypted content is stored on IPFS via Pinata:

* **Gateway**: `https://gateway.pinata.cloud/ipfs/{cid}`
* **Persistence**: Pinned via Pinata API
* **Content Addressing**: CID uniquely identifies encrypted content
* **Decentralization**: Content available through any IPFS node

### Smart Contracts

The Shield contract on Base manages access policies:

| Network      | Contract Address                             |
| ------------ | -------------------------------------------- |
| Base Mainnet | `0x4b8F46e5E3d95D78f30F80F1280fE7e5F92c8ce8` |

**Key Functions**:

* `createPolicy()` - Store access conditions on-chain
* `logAttempt()` - Record access attempts
* `isPolicyValid()` - Check policy status

### Backend API

Node.js/Next.js API for off-chain operations:

* **Policy Metadata**: Maps policy ID to IPFS CID
* **Authentication**: SIWE signature verification
* **Rate Limiting**: Sliding window per IP/address
* **Session Management**: JWT with 1-hour expiry

## Data Flow

### Creating a Link

<Steps>
  <Step title="Generate Key">
    Browser generates AES-256 key using Web Crypto API
  </Step>

  <Step title="Encrypt Content">
    File/message encrypted locally, never leaves browser unencrypted
  </Step>

  <Step title="Upload to IPFS">
    Encrypted blob uploaded to Pinata, returns CID
  </Step>

  <Step title="Create Policy">
    User signs transaction to store access policy on Base
  </Step>

  <Step title="Store Metadata">
    Backend stores policy ID → CID mapping in PostgreSQL
  </Step>

  <Step title="Generate Link">
    URL created with policyId and secretKey (fragment)
  </Step>
</Steps>

### Accessing Content

<Steps>
  <Step title="Verify SIWE">
    Recipient signs message proving wallet ownership
  </Step>

  <Step title="Check Policy">
    Backend queries contract: valid? expired? attempts?
  </Step>

  <Step title="Log Access">
    Recipient signs transaction calling logAttempt()
  </Step>

  <Step title="Fetch Content">
    Browser fetches encrypted blob from IPFS
  </Step>

  <Step title="Decrypt">
    Secret key from URL fragment decrypts content locally
  </Step>
</Steps>

## Security Boundaries

| Component      | Trust Level | Data Access            |
| -------------- | ----------- | ---------------------- |
| Browser        | Trusted     | Unencrypted content    |
| IPFS           | Untrusted   | Encrypted content only |
| Smart Contract | Trustless   | Policy metadata only   |
| Backend API    | Trusted     | Non-sensitive metadata |
| Sender         | Trusted     | Original content       |
| Recipient      | Verified    | Decrypted content      |

## Technology Stack

| Layer     | Technology                                     |
| --------- | ---------------------------------------------- |
| Frontend  | Next.js 16, React 19, TypeScript, Tailwind CSS |
| State     | React Query, Wagmi, Viem                       |
| Wallet    | RainbowKit, WalletConnect                      |
| Crypto    | Web Crypto API (AES-GCM 256)                   |
| Contracts | Solidity 0.8.24, Hardhat                       |
| Network   | Base (Ethereum L2)                             |
| Storage   | IPFS via Pinata                                |
| Database  | PostgreSQL (Neon)                              |
| Hosting   | Vercel                                         |