Architecture

System Overview

┌─────────────────────────────────────────────────┐
│                   Clients                        │
│   Console (Next.js)  │  SDK  │  CLI  │  Direct  │
└────────────┬─────────┴───┬───┴───┬───┴────┬─────┘
             │             │       │        │
             ▼             ▼       ▼        ▼
┌─────────────────────────────────────────────────┐
│              Payre API (Fastify)                 │
│                                                  │
│  /register  /resolve  /grant  /invoke  /stats   │
│                                                  │
│  ┌──────────┐ ┌──────────┐ ┌──────────────┐    │
│  │ Passport │ │  Grant   │ │   Invoke     │    │
│  │  Store   │ │  Store   │ │   Engine     │    │
│  └──────────┘ └──────────┘ └──────┬───────┘    │
│                                    │             │
│                    ┌───────────────┼──────┐      │
│                    │               │      │      │
│                    ▼               ▼      ▼      │
│              ┌──────────┐  ┌──────┐ ┌──────┐    │
│              │   REST   │  │ MCP  │ │ Mock │    │
│              │ Adapter  │  │Adapt.│ │Adapt.│    │
│              └──────────┘  └──────┘ └──────┘    │
└─────────────────────────────────────────────────┘
             │
             ▼
┌─────────────────────────┐
│     PostgreSQL + Prisma  │
│  (InMemory fallback)     │
└─────────────────────────┘

Monorepo Structure

project-payre/
├── apps/
│   ├── api/          — Fastify API server
│   ├── console/      — Next.js Provider Console
│   ├── docs/         — VitePress documentation
│   └── web/          — Landing page
├── packages/
│   ├── contracts/    — Core types, stores, engines
│   ├── sdk/          — TypeScript SDK (@payre/sdk)
│   └── cli/          — CLI tool (@payre/cli)
└── docs/             — Internal specs

Data Flow

1. Registration: Agent provider registers a passport via POST /register or Console
2. Discovery: Caller queries with natural language via POST /resolve
3. Authorization: Caller requests a grant via POST /grant
4. Execution: Caller invokes agent via POST /invoke with grant ID
5. Audit: Receipt is created and stored for every invocation

Storage

Payre supports two storage backends:

• InMemory — Default for development and testing
• PostgreSQL + Prisma — For production (set DATABASE_URL)

The store interfaces (PassportStore, GrantStore, InvokeStore) abstract the backend, allowing seamless switching.

Authentication

API requests are authenticated via the X-Payre-Key header with keys in pyr_sk_ + 32 hex chars format. Keys are managed through the /api-keys endpoints.

Set PAYRE_AUTH_DISABLED=true to bypass auth in development.