# Anvia Full-Stack Applications

> Curated implementation context for delivering an Anvia agent through Hono and `@anvia/server`, consuming its stream with `@anvia/react`, and rendering it with `@anvia/react-ui`.

Keep the agent, provider credentials, tools, memory, retrieval, and observers on the server. Send only a reviewed stream protocol to the browser. Hono owns HTTP routing and middleware; `@anvia/server` owns JSONL or SSE encoding; `@anvia/react` owns client transport and state; `@anvia/react-ui` owns composable presentation.

This guide is optimized for coding agents. Prefer the linked package documentation for complete APIs and current versions. Updated 2026-08-13.

## Architecture

```text
React UI components
        ↓ controller
@anvia/react useChat + fetch transport
        ↓ UIStreamRequest over JSONL
Hono POST /api/chat
        ↓ authentication, validation, authorization
server-side Anvia agent
        ↓ reviewed client-visible events
@anvia/server streaming Response
```

Responsibilities:

- Hono: routing, authentication middleware, request limits, CORS or same-origin policy, and HTTP error mapping.
- `@anvia/server`: convert an async event iterable into a Fetch-compatible streaming `Response`; optionally persist resumable envelopes.
- `@anvia/react`: own `UIMessage[]`, build requests, consume JSONL or SSE, reduce runtime events, cancel, resume, and model human-input state.
- `@anvia/react-ui`: render compound chat, message, composer, attachment, image, human-input, thread-list, and completion primitives from an existing controller.
- Application code: identity, session ownership, tool authorization, event projection, persistence, rate limits, observability, and deployment policy.

Do not put provider keys, service credentials, authorization rules, or agent execution in the browser.

## pnpm Workspace Structure

Use separate workspace applications so server dependencies and secrets cannot accidentally enter the frontend bundle:

```text
anvia-app/
  apps/
    api/
      src/
        agent.ts
        auth.ts
        validation.ts
        events.ts
        server.ts
      .env
      package.json
      tsconfig.json
    frontend/
      src/
        App.tsx
        main.tsx
      index.html
      package.json
      tsconfig.json
      vite.config.ts
  packages/
    contracts/                 # optional shared browser-safe protocol
      src/
        index.ts
      package.json
      tsconfig.json
  package.json
  pnpm-workspace.yaml
  tsconfig.base.json
```

`apps/api` owns the agent, provider SDKs, credentials, tools, persistence, retrieval, observers, and Hono server. `apps/frontend` owns React, the Anvia client controller, and UI components. Use `packages/contracts` only for browser-safe request, event, and error contracts shared by both applications; never export server configuration or service types from it.

Workspace definition:

```yaml
# pnpm-workspace.yaml
packages:
  - 'apps/*'
  - 'packages/*'
```

Keep root scripts orchestration-only:

```json
{
  "name": "anvia-app",
  "private": true,
  "scripts": {
    "dev": "pnpm --parallel --filter @app/api --filter @app/frontend dev",
    "build": "pnpm --filter @app/api build && pnpm --filter @app/frontend build",
    "typecheck": "pnpm --recursive typecheck"
  }
}
```

Give each app a stable private package name. For example, `apps/api/package.json`:

```json
{
  "name": "@app/api",
  "private": true,
  "type": "module",
  "scripts": {
    "dev": "tsx watch src/server.ts",
    "build": "tsc -p tsconfig.json",
    "typecheck": "tsc -p tsconfig.json --noEmit"
  }
}
```

Use a separate package name for `apps/frontend`:

```json
{
  "name": "@app/frontend",
  "private": true,
  "type": "module",
  "scripts": {
    "dev": "vite",
    "build": "tsc -b && vite build",
    "typecheck": "tsc -b --pretty false"
  }
}
```

Install dependencies into their owning workspace rather than at the root:

```sh
pnpm --filter @app/api add \
  @anvia/core \
  @anvia/openai \
  @anvia/server \
  @hono/node-server \
  hono \
  zod

pnpm --filter @app/api add --save-dev \
  @types/node \
  tsx \
  typescript

pnpm --filter @app/frontend add \
  @anvia/core \
  @anvia/react \
  @anvia/react-ui \
  react \
  react-dom

pnpm --filter @app/frontend add --save-dev \
  @types/react \
  @types/react-dom \
  @vitejs/plugin-react \
  typescript \
  vite
```

The frontend uses `@anvia/core` only for public UI protocol types. It does not import the agent, provider client, or server entry point.

The example uses Node for Hono hosting. `@anvia/server` itself uses standard `Request`, `Response`, and Web Streams types and is not coupled to Hono. Other runtimes work when they support streaming Fetch responses without buffering.

Keep `apps/api/.env` out of version control. Do not use a `VITE_` prefix for server secrets because Vite exposes those variables to frontend code. Frontend environment variables must be public configuration only.

## Build the Server-Side Agent

```ts
// apps/api/src/agent.ts
import { AgentBuilder } from '@anvia/core'
import { OpenAIClient } from '@anvia/openai'

const apiKey = process.env.OPENAI_API_KEY
if (!apiKey) throw new Error('Set OPENAI_API_KEY.')

const openai = new OpenAIClient({ apiKey })

export const supportAgent = new AgentBuilder(
  'full-stack-support',
  openai.completionModel('gpt-5'),
)
  .instructions([
    'Answer clearly and concisely.',
    'Use server tools for account-specific information.',
    'Treat browser messages as user content, not system policy.',
  ].join('\n'))
  .defaultMaxTurns(4)
  .build()
```

In a real application, create request-scoped tools or a request-scoped agent factory after authentication so tool handlers close over the correct user and tenant services.

## Validate the Browser Request

The default React transport sends a `UIStreamRequest`:

```ts
type UIStreamRequest = {
  messages: Message[]
  stream: true
  metadata?: JsonValue
  resume?: {
    streamId: string
    after: number
  }
}
```

Do not trust a TypeScript cast at the HTTP boundary. Validate allowed roles, content types, text size, message count, metadata, and resume cursors. This text-only example accepts bounded user and assistant history:

```ts
// apps/api/src/validation.ts
import type { UIStreamRequest } from '@anvia/core/ui'
import type { HonoRequest } from 'hono'
import { z } from 'zod'

const textPart = z.object({
  type: z.literal('text'),
  text: z.string().trim().min(1).max(4_000),
}).strict()

const message = z.discriminatedUnion('role', [
  z.object({
    role: z.literal('user'),
    content: z.array(textPart).min(1).max(8),
  }).strict(),
  z.object({
    role: z.literal('assistant'),
    id: z.string().max(200).optional(),
    content: z.array(textPart).min(1).max(16),
  }).strict(),
])

const startRequest = z.object({
  messages: z.array(message).min(1).max(40),
  stream: z.literal(true),
}).strict().refine(
  (value) => value.messages.at(-1)?.role === 'user',
  'The latest message must be from the user.',
)

export class ChatRequestError extends Error {
  constructor(
    readonly status: 400 | 413,
    message: string,
  ) {
    super(message)
  }
}

export async function parseStartRequest(
  request: HonoRequest,
): Promise<UIStreamRequest> {
  const declared = Number(request.header('content-length') ?? '0')
  if (!Number.isFinite(declared) || declared > 64_000) {
    throw new ChatRequestError(413, 'Request body is too large.')
  }

  let input: unknown
  try {
    input = await request.json()
  } catch {
    throw new ChatRequestError(400, 'Invalid JSON.')
  }

  if (new TextEncoder().encode(JSON.stringify(input)).byteLength > 64_000) {
    throw new ChatRequestError(413, 'Request body is too large.')
  }

  const parsed = startRequest.safeParse(input)
  if (!parsed.success) {
    throw new ChatRequestError(400, 'Invalid chat request.')
  }

  return parsed.data as UIStreamRequest
}
```

This validator intentionally omits attachments, tool messages, arbitrary metadata, system messages, and resume requests. Add only the protocol features the product needs and validate each separately.

## Project Client-Visible Events

Do not stream every raw runtime event automatically. Tool arguments, tool results, reasoning, sources, traces, provider metadata, and errors may contain private application data.

For the standard `@anvia/react` reducer, preserve reviewed Anvia event shapes. A narrow projector can allow text, final output, context usage, safe tool status, approvals, and sanitized errors while dropping private fields. When defining an entirely custom event union, configure `eventToUIEvent`, `eventToDelta`, or `eventToFinal` on `useChat` deliberately.

Conceptual projector:

```ts
// apps/api/src/events.ts
import type { AgentStreamEvent } from '@anvia/core'

export async function* publicChatEvents(
  events: AsyncIterable<AgentStreamEvent>,
) {
  try {
    for await (const event of events) {
      if (event.type === 'text_delta') {
        yield {
          type: 'text_delta',
          delta: event.delta,
        }
      } else if (event.type === 'final') {
        yield {
          type: 'final',
          output: event.output,
          contextUsage: event.contextUsage,
        }
      } else if (event.type === 'error') {
        yield {
          type: 'error',
          error: { message: 'The model request failed.' },
        }
      }
    }
  } catch {
    yield {
      type: 'error',
      error: { message: 'The model request failed.' },
    }
  }
}
```

Confirm exact event names against the Core version in the application. Prefer a typed shared protocol module and tests that prove forbidden event fields never reach the browser.

## Expose the Stream with Hono

Authenticate and authorize before starting model work. Return the `Response` from `createEventStream(...)` directly so Hono and the hosting platform do not consume or buffer its body.

```ts
// apps/api/src/server.ts
import { serve } from '@hono/node-server'
import { createEventStream } from '@anvia/server'
import { Hono } from 'hono'
import { supportAgent } from './agent.js'
import { publicChatEvents } from './events.js'
import {
  ChatRequestError,
  parseStartRequest,
} from './validation.js'

type AuthenticatedUser = {
  id: string
  tenantId: string
}

// Replace these declarations with application authentication and logging.
declare function authenticateRequest(
  request: Request,
): Promise<AuthenticatedUser | undefined>

declare function recordServerError(error: unknown): Promise<void>

const app = new Hono()

app.get('/api/health', (context) => context.json({ ok: true }))

app.post('/api/chat', async (context) => {
  const user = await authenticateRequest(context.req.raw)
  if (!user) {
    return context.json({ error: 'Unauthorized.' }, 401)
  }

  try {
    const body = await parseStartRequest(context.req)

    // Prefer a scoped factory here when tools, memory, or retrieval depend on user.
    const promptRequest = supportAgent.prompt(body.messages)
    const events = promptRequest.stream({
      includeToolCallDeltas: false,
    })

    return createEventStream(publicChatEvents(events), {
      format: 'jsonl',
      headers: {
        'content-security-policy': "default-src 'none'",
        'referrer-policy': 'no-referrer',
        'x-content-type-options': 'nosniff',
      },
    })
  } catch (error) {
    if (error instanceof ChatRequestError) {
      return context.json({ error: error.message }, error.status)
    }

    await recordServerError(error)
    return context.json({ error: 'The model request failed.' }, 502)
  }
})

serve({
  fetch: app.fetch,
  hostname: '127.0.0.1',
  port: 8787,
})
```

`authenticateRequest` and `recordServerError` are application-owned boundaries omitted from the snippet. Replace the shared agent with a scoped factory when tools, memory, or retrieval depend on the current request. Never accept a browser-supplied user or tenant ID as proof of identity.

JSONL is the default and matches `@anvia/react`. Use `{ format: 'sse' }` only when the client is configured for SSE or another consumer requires `text/event-stream`.

## Configure Vite Development Proxy

Proxy `/api` during local development so the browser uses a same-origin path:

```ts
// apps/frontend/vite.config.ts
import react from '@vitejs/plugin-react'
import { defineConfig } from 'vite'

export default defineConfig({
  plugins: [react()],
  server: {
    host: '127.0.0.1',
    port: 5173,
    proxy: {
      '/api': 'http://127.0.0.1:8787',
    },
  },
})
```

In production, serve the web client and API behind one HTTPS origin when practical. Otherwise configure a narrow credentialed CORS policy and CSRF protection appropriate to the authentication mechanism.

## Connect the React Controller

The simplest client uses the endpoint shortcut:

```tsx
import { useChat } from '@anvia/react'

const chat = useChat({
  endpoint: '/api/chat',
})
```

Use an explicit transport when headers, dynamic endpoints, or custom request bodies are required:

```tsx
import type { UIStreamRequest } from '@anvia/core/ui'
import {
  createFetchTransport,
  useChat,
} from '@anvia/react'
import { useMemo } from 'react'

export function useApplicationChat(accessToken: string) {
  const transport = useMemo(
    () => createFetchTransport<UIStreamRequest>({
      endpoint: '/api/chat',
      format: 'jsonl',
      headers: {
        authorization: `Bearer ${accessToken}`,
      },
    }),
    [accessToken],
  )

  return useChat({ transport })
}
```

Prefer secure HTTP-only session cookies over keeping bearer credentials in browser state when the application architecture permits it. If using cookie authentication, add CSRF defenses and do not expose session tokens to JavaScript.

`useChat`:

- Optimistically appends local user messages.
- Converts `UIMessage[]` into Core messages.
- Sends the request and consumes JSONL or SSE events.
- Reduces text, tools, reasoning, attachments, errors, metadata, usage, approvals, and questions into UI state when those events are allowed.
- Exposes `sendMessage`, `regenerate`, `stop`, `reset`, `resume`, status, error, context usage, and human-input actions.

## Render with React UI

Import the optional structural stylesheet once, then provide the controller to `ChatProvider`:

```tsx
// apps/frontend/src/App.tsx
import { useChat } from '@anvia/react'
import {
  ChatProvider,
  Composer,
  HumanInput,
  Message,
  Thread,
} from '@anvia/react-ui'
import '@anvia/react-ui/styles.css'

export default function App() {
  const chat = useChat({ endpoint: '/api/chat' })

  return (
    <main>
      <ChatProvider controller={chat}>
        <Thread.Root>
          <Thread.Viewport>
            <Thread.Empty>
              Start a conversation.
            </Thread.Empty>

            <Thread.Messages>
              <Message.Root>
                <Message.Content>
                  <Message.Parts />
                </Message.Content>
              </Message.Root>
            </Thread.Messages>

            <HumanInput.Panel>
              <HumanInput.Approvals>
                <HumanInput.Approval>
                  <HumanInput.ApprovalReason />
                  <HumanInput.Approve>Approve</HumanInput.Approve>
                  <HumanInput.Reject>Reject</HumanInput.Reject>
                </HumanInput.Approval>
              </HumanInput.Approvals>
            </HumanInput.Panel>

            <Thread.Error />
            <Thread.ScrollToBottom />
          </Thread.Viewport>

          <Composer.Root>
            <Composer.Attachments />
            <Composer.Input placeholder="Send a message..." />
            <Composer.Stop>Stop</Composer.Stop>
            <Composer.Submit>Send</Composer.Submit>
          </Composer.Root>
        </Thread.Root>
      </ChatProvider>
    </main>
  )
}
```

`@anvia/react-ui` supplies behavior-oriented compound primitives, not a complete product theme. The application owns layout, colors, responsive design, navigation, Markdown link policy, attachment upload, thread persistence, and accessibility review.

`ChatProvider` does not create a transport. `@anvia/react-ui` does not execute an agent, authenticate users, persist server state, or authorize approval decisions. Human-input components call controller actions; the server must verify who may approve or answer.

## Add RAG, Tools, and Memory

The browser protocol does not need to change when the server agent gains retrieval, tools, or memory:

```ts
export function createSupportAgent(scope: RequestScope) {
  const retrievalFilter = vectorFilter.and(
    vectorFilter.eq('tenantId', scope.tenantId),
    vectorFilter.eq('published', true),
  )

  return new AgentBuilder('full-stack-support', model)
    .instructions('Use verified documentation and scoped tools.')
    .dynamicContext(docsIndex, {
      topK: 4,
      threshold: 0.74,
      filter: retrievalFilter,
    })
    .tools([
      createGetAccountTool(scope),
      createTicketTool(scope),
    ])
    .memory(memoryStore, { savePolicy: 'turn' })
    .observe(tracing)
    .defaultMaxTurns(4)
    .build()
}
```

Authenticate the route, resolve `RequestScope` from trusted application state, authorize the conversation, then build or select the scoped agent. Browser history is context, not identity or session authorization.

Keep internal retrieval evidence and tool payloads off the public event stream unless the UI explicitly needs a reviewed projection. If citations are visible, expose a stable safe source identifier and validate outbound URLs.

## Cancellation

`chat.stop()` aborts the active browser transport. `useChat` also aborts on unmount and when a new request replaces the current one.

Canceling the HTTP stream calls `return()` on the source iterator when supported. Whether model or tool work actually stops depends on the complete event-source and hosting path. Test cancellation end to end.

Cancellation cannot undo completed side effects. Tool handlers must use their own deadlines, cancellation signals where supported, idempotency keys, and transaction or compensation policy.

## Resumable Streams

Use resumable streams when a response should continue after reload, navigation, or a temporary disconnect. Resuming replays missed events and follows the original run; it must not start a second agent.

Development server shape:

```ts
import type { UIStreamRequest } from '@anvia/core/ui'
import {
  createEventStream,
  createMemoryResumableStreamStore,
} from '@anvia/server'

const resumableStore = createMemoryResumableStreamStore()

async function chatResponse(body: UIStreamRequest, scope: RequestScope) {
  if (body.resume) {
    await authorizeStream(scope, body.resume.streamId)

    return createEventStream({
      format: 'jsonl',
      resume: {
        streamId: body.resume.streamId,
        after: body.resume.after,
        store: resumableStore,
      },
    })
  }

  const streamId = crypto.randomUUID()
  await registerStreamOwner(streamId, scope)

  const agent = createSupportAgent(scope)
  const events = publicChatEvents(
    agent.prompt(body.messages).stream(),
  )

  return createEventStream(events, {
    format: 'jsonl',
    resumable: {
      id: streamId,
      store: resumableStore,
    },
  })
}
```

Client:

```tsx
const chat = useChat({
  endpoint: `/api/threads/${threadId}/chat`,
  resume: {
    key: threadId,
    storage: 'sessionStorage',
    auto: true,
  },
})
```

`createMemoryResumableStreamStore()` is for tests and single-process development. Production requires a shared `ResumableStreamStore` over Redis, Postgres, or the workflow system that owns the job. It must allocate ordered event IDs, replay after a cursor, tail live records, persist terminal state, expire data, and work across replicas.

A stream ID or cursor is not proof of access. Authorize both start and resume paths against the current user, thread, and tenant. Apply short retention and redaction because stored events may contain sensitive content.

Resumable storage provides transport recovery. Agent memory provides future model context. They are separate systems.

## Human Approval and Questions

`useChat` can model tool approvals and structured questions, and `@anvia/react-ui/human-input` can render them. The UI decision endpoint remains application-owned.

Rules:

- Emit only the approval or question fields the browser needs.
- Bind every decision ID to the authenticated user, tenant, run, tool, and expiry.
- Re-authorize when the decision arrives; rendering a button is not permission.
- Make decisions one-time and auditable.
- Do not treat approval as the only tool authorization or business-policy check.
- Handle expired, already-decided, and canceled runs explicitly.

Use `humanInput` options on `useChat` when approval or question mutations use custom endpoints or event mappings. The default adapters recognize standard Anvia human-input events.

## Observability

Attach Lens, OpenTelemetry, Langfuse, or a logger to the server-side agent. Use `.withTrace(...)` for stable request context:

```ts
const promptRequest = agent
  .prompt(body.messages)
  .withTrace({
    name: 'web-chat',
    userId: scope.userId,
    sessionId: scope.threadId,
    metadata: {
      tenantId: scope.tenantId,
      channel: 'react',
    },
  })
```

Use opaque application IDs rather than email addresses. Keep private prompt, response, tool, and retrieval bodies out of telemetry unless capture and retention have been reviewed. Correlate HTTP request IDs with trace IDs in server logs without sending server credentials or private trace data to the client.

## JSONL or SSE

Both formats carry JSON event values with different framing:

- JSONL: default; compact; `application/x-ndjson`; directly matches the default Anvia React transport.
- SSE: `text/event-stream`; useful for existing SSE infrastructure or consumers; configure `format: 'sse'` on both server and React client.

`@anvia/server` does not emit heartbeat comments. Add a heartbeat at the application event-source layer when a proxy requires idle traffic. Verify that reverse proxies and hosting platforms do not buffer streams and that their idle and maximum-request timeouts fit the product.

## Production Checklist

- Keep provider and service credentials server-side.
- Authenticate before constructing request-scoped agents or starting model work.
- Authorize thread, session, tool, retrieval, approval, and resume access independently.
- Validate the actual JSON body; do not trust browser TypeScript types.
- Bound request bytes, message count, part count, text size, duration, concurrency, and rate.
- Treat browser history as untrusted content, not identity or system instruction.
- Project an allow-listed public event protocol and sanitize errors.
- Avoid exposing reasoning, tool inputs, tool outputs, provider payloads, secrets, or private trace metadata.
- Use HTTPS and a narrow same-origin or credentialed CORS policy.
- Test streaming and cancellation through the real proxy and hosting runtime.
- Make side-effect tools idempotent and auditable.
- Use shared durable storage for resumable streams across replicas.
- Apply retention and deletion to memory, resumable events, uploads, and telemetry separately.
- Test authentication failures cause zero model and tool calls.
- Test malformed requests, unauthorized sessions, cross-tenant IDs, projection leaks, provider errors, aborts, reconnects, duplicate decisions, and deployment buffering.

## Canonical Documentation

- [Build applications](https://docs.anvia.dev/use-cases/build-applications): Minimal server and React integration.
- [Secure streaming React chat](https://docs.anvia.dev/examples/applications/streaming-react-chat): Complete Hono and React application example.
- [`@anvia/server`](https://docs.anvia.dev/packages/server/): Response helpers, formats, resumable streams, and deployment.
- [Server transports](https://docs.anvia.dev/packages/server/transports): JSONL and SSE framing.
- [Server streaming](https://docs.anvia.dev/packages/server/streaming): Backpressure, cancellation, errors, and resumption.
- [`@anvia/react`](https://docs.anvia.dev/packages/react/): Client controllers, transport, state, cancellation, resumption, and human input.
- [React API reference](https://docs.anvia.dev/packages/react/api-reference): `useChat`, `useCompletion`, and transport contracts.
- [`@anvia/react-ui`](https://docs.anvia.dev/packages/react-ui/): Composable interface primitives and boundaries.
- [React UI components and theming](https://docs.anvia.dev/packages/react-ui/components-and-theming): Styling and composition guidance.
- [Resumable streams](https://docs.anvia.dev/sdk/streaming/resumable-streams): End-to-end server and client resume protocol.
- [Agents, tools, and MCP](https://docs.anvia.dev/llms-agents.txt): Server-side agent and tool construction.
- [RAG, knowledge, and retrieval](https://docs.anvia.dev/llms-rag.txt): Add permission-aware retrieval to the server agent.
- [Evaluations and observability](https://docs.anvia.dev/llms-evals.txt): Trace and evaluate the delivered application.