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

***


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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, and the optional `goal` query parameter:

```
GET https://docs.netauthpay.com/getting-started/architecture.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.