---
title: "Web App Architecture and Data Flow | Agent Barn"
canonical: "https://agentbarn.dev/guides/web-app-architecture"
pubDate: "2026-08-25T00:00:00.000Z"
updatedDate: "2026-08-29T16:41:32.000Z"
author: Agent Barn
description: "Build App Router pages, provider boundaries, schemas, queries, mutations, loading states, and tests consistently."
tags: [Engineering guide, Frontend developers, Agent Barn]
categories: [Guides]
---

# Web App Architecture and Data Flow

Pages compose features; feature modules own behavior; shared infrastructure owns transport and query keys. Organization identity stays explicit in URLs and query-cache isolation is part of the tenancy contract.

## Guide details

- Reference: GD-11
- Type: Engineering guide
- Audience: Frontend developers

## Routing and providers

The root layout composes URL-state, query, tooltip, and application providers. Public authentication routes bypass protected context. Organization View uses `/dashboard/[orgId]`, while Platform View uses `/dashboard/platform` with no active Organization.

## API and query contracts

Use the shared API singleton, feature-local `Zod` schemas, and centralized query keys. The client sends cookies and transforms `snake_case` responses to `camelCase`. New Organization-scoped queries must include Organization identity in their key or join the provider eviction set used during a real Organization switch.

## Loading and errors

Use route loading and error files for page-blocking router work. Component-owned queries keep their initial loading, retry, search, pagination, and refetch states local. A hook error does not automatically reach an App Router error boundary.

## UI conventions

Prefer Server Components until client-owned behavior is required. Use branded `ConfirmationDialog` for confirmation flows and shared `shadcn` Select primitives for option selectors. Mutations invalidate affected list and detail families; avoid effect chains for user-triggered workflows.

## Streaming exception

Agent logs use a dedicated Next route handler that proxies server-sent events and a feature hook that owns reconnection. Keep this explicit exception separate from the normal API client.