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

# Architecture

#### High-Level Flow

```
┌─────────────┐
│   Agents    │  (CLI, API clients, other services)
└──────┬──────┘
       │
       ▼
┌─────────────────┐
│  NetAuth API    │  (Express REST + optional CLI)
└──────┬──────────┘
       │
       ▼
┌─────────────────┐
│  Privacy Layer  │  (Payment records, visibility rules)
└──────┬──────────┘
       │
       ▼
┌─────────────────┐
│  x402 Protocol  │  (Privacy tokens, optional external service)
└──────┬──────────┘
       │
       ▼
┌─────────────────┐
│  Solana Network │  (Transactions, balances)
└─────────────────┘
```

#### Core Components

**1. Agent Service**

* Registers agents and maintains agent records.
* One agent ID per logical agent; optional existing Solana public key on registration.

**2. Wallet Service**

* Creates a Solana keypair per agent (or links an existing key).
* Encrypts private keys at rest, provides balance lookups and key material for signing (server-side only).

**3. Privacy Service**

* Creates and stores payment records.
* Assigns privacy tokens (via x402 when configured).
* Ensures only sender and recipient can see a payment’s details.
* Coordinates single and batch payment creation and processing.

**4. x402 Service**

* Integrates with the x402 protocol for privacy tokens.
* If no x402 endpoint is configured, uses a local fallback for token generation so the product still works.

**5. Payment Service**

* Builds and signs Solana transfer transactions.
* Submits transactions to the configured RPC and tracks confirmation.

**6. Encryption Service**

* Encrypts/decrypts sensitive data (e.g. wallet private keys) using AES-256-GCM.
* Required for any wallet creation or payment sending.

#### Payment Flow (Single Payment)

1. Client calls `POST /api/payments/send` (or CLI `payment send`).
2. Privacy Service creates a payment record with status `PENDING`.
3. x402 Service (or local fallback) issues a privacy token for the payment.
4. Payment Service builds a Solana transfer, signs with the sender’s key, and sends the transaction.
5. On confirmation, payment status is set to `COMPLETED` and the transaction signature is stored.
6. Only the sender and recipient can query this payment’s details (enforced by Privacy Service).

#### Data Storage

* Current implementation uses **in-memory** storage (Maps).
* For production, plan to replace with:
  * A database (e.g. PostgreSQL) for agents and payments.
  * An encrypted store for wallet data.
  * Optional cache (e.g. Redis) for sessions or rate limiting.

***
