Overview
What you're building against - a NestJS backend, a frozen OpenAPI seam, and a Next.js client that never holds a key.
Botanary's developer surface is two codebases talking through one frozen contract. A NestJS backend builds unsigned operations and never signs; a Next.js frontend generates a typed client straight from that contract, signs client-side, and relays what it signed. Everything in this section explains how those pieces fit together and how to build against them yourself.
The shape of it
- Architecture - how the backend is organized (one module per API surface, two global guards, one error envelope), and how the frontend is organized (a generated API client, a design system, feature surfaces).
- The API seam - the hand-authored OpenAPI contract that both sides build against, and the versioning discipline that keeps it a contract rather than a suggestion.
- Authentication and Sessions
- how a Privy auth token becomes a Botanary session, and what that session token actually is.
- Smart account - the ERC-7579 modules (OwnableValidator, AgentGuard, Smart Sessions) and the ERC-4337 UserOperation lifecycle that everything signs into.
- API client - the generated TypeScript client the frontend actually uses, and how to get it running against mocks in minutes.
- Integration - the notifications feed and the hash-chained activity log, if you're building something that reads what happened on an account.
- Guides - running the whole stack locally, frontend and backend.
Every state-changing action is a build, sign, relay flow. The API never signs - the owner (or an authorized device or session key) signs client-side, and the backend only ever relays what's already signed.
Who never holds a key
Nothing in this stack - not the backend, not the generated client, not the account's owner-facing API - ever receives, stores, or reconstructs a private key. Privy holds the signer; the backend holds an opaque session token that identifies a request, not a key that could act on your behalf. That split is load-bearing enough that it shows up in the OpenAPI contract itself, as a marker on every schema and endpoint whose payload the owner has to sign before it's usable - see The API seam and Authentication for exactly how.