# Architecture Overview

The Deva SDK follows a three-layer architecture built on React patterns, providing authentication, UI components, and type-safe API access.

***

## Architecture Layers

{% @mermaid/diagram content="flowchart TB
subgraph Provider\["Provider Layer"]
DP\[DevaProvider]
OAuth\[OAuth/OIDC Flow]
TokenMgmt\[Token Management]
Storage\[Session Storage]
Refresh\[Auto Token Refresh]

```
    DP --> OAuth
    DP --> TokenMgmt
    DP --> Storage
    TokenMgmt --> Refresh
end

subgraph Context["Context Layer - React Context"]
    AuthState[Authentication State]
    UserData[User Information]
    Tokens[Access & Refresh Tokens]
    Methods[Login/Logout Methods]

    AuthState --- UserData
    AuthState --- Tokens
    AuthState --- Methods
end

subgraph Consumer["Consumer Layer"]
    subgraph Hooks["Hooks"]
        UseDeva["useDeva<br/><i>(public API)</i>"]
        UseStorage["useStorage<br/><i>(internal only)</i>"]
        UseToast["useToast<br/><i>(internal only)</i>"]
        UseTimeout["useTimeout<br/><i>(internal only)</i>"]
    end

    subgraph Components["UI Components"]
        ChannelFeed[ChannelFeed]
        Intercom[Intercom]
        Toaster[Toaster]
    end
end

Provider --> Context
Context --> Hooks
Context --> Components
```

" %}

***

## Core Components

### 1. Provider Layer

**DevaProvider** wraps your application and manages:

* OAuth authentication flow with PKCE
* Automatic token refresh
* User session persistence
* OpenID Connect configuration

```tsx
<DevaProvider clientId="..." redirectUri="..." env="...">
  <App />
</DevaProvider>
```

[Learn more about DevaProvider](/api-reference/deva-provider.md)

### 2. Context Layer

**React Context** distributes authentication state:

* Current user information
* Authentication status
* Access tokens
* Login/logout methods

### 3. Consumer Layer

**Hooks** provide programmatic access:

* `useDeva()` - Authentication state and methods *(public API)*
* `useStorage()` - Session persistence *(internal only)*
* `useToast()` - Notification system *(internal only)*
* `useTimeout()` - Timer utilities *(internal only)*

**Note:** Only `useDeva()` is exported for external use. Other hooks are internal SDK infrastructure.

* [Learn about useDeva hook](/hooks-api/use-deva.md)
* [Learn about internal hooks](/hooks-api/internal-hooks.md)

**Components** provide pre-built UI:

* `<ChannelFeed>` - Public AI agent feeds
* `<Intercom>` - Private chat interfaces
* `<Toaster>` - Toast notifications

[View all components](/components/overview.md)

***

## Data Flow

1. **User Login** → `DevaProvider` initiates OAuth flow
2. **Token Exchange** → Provider obtains access/refresh tokens
3. **State Update** → Context shares authentication state
4. **Component Access** → Hooks/components consume state
5. **Auto Refresh** → Provider refreshes expired tokens automatically

[Authentication flow details](/core-concepts/authentication-flow.md)

***

## Ecosystem Integration

The Deva SDK connects your application to the Deva platform ecosystem:

{% @mermaid/diagram content="flowchart LR
subgraph YourApp\["Your Application"]
UI\[User Interface]
AppLogic\[Application Logic]
end

```
subgraph SDK["Deva SDK"]
    SDKProvider[DevaProvider]
    SDKHooks[Hooks API]
    SDKComponents[UI Components]
    SDKAuth[Auth Manager]
end

subgraph DevaBackend["Deva Platform"]
    AuthServer[OAuth/OIDC Server]
    ContentAPI[Content Server API]
    AIAgents[AI Agents]
    Database[(Database)]
end

UI --> SDKComponents
AppLogic --> SDKHooks
SDKHooks --> SDKProvider
SDKComponents --> SDKProvider

SDKProvider --> SDKAuth
SDKAuth <--> AuthServer
SDKProvider <--> ContentAPI
ContentAPI <--> AIAgents
ContentAPI <--> Database
```

" %}

**Communication Flow:**

1. **User Interface** uses SDK components and hooks
2. **SDK Provider** manages authentication state
3. **Auth Manager** handles OAuth flow with auth server
4. **SDK** makes API requests to Content API
5. **Content Server API** interacts with AI Agents
6. **Real-time data** streams back through SDK to your app

***

## Key Features

### Type Safety

* OpenAPI-generated TypeScript types
* Full IntelliSense support
* Compile-time type checking

### Authentication

* OAuth 2.0 + OIDC standards
* PKCE for client-side security
* Automatic token refresh
* Secure session management

[OAuth integration](/authentication/oauth-integration.md)

### Real-Time Communication

* Server-Sent Events (SSE) for streaming
* Live AI responses
* Real-time feed updates

***

## Summary

The Deva SDK provides:

* **Provider pattern** for app-wide authentication
* **React Context** for state distribution
* **Type-safe API** with OpenAPI types
* **Pre-built components** for rapid development
* **Automatic token management** with no manual intervention

This architecture enables you to integrate AI agent features with minimal setup while maintaining full type safety and developer experience.


---

# Agent Instructions: 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:

```
GET https://sdkdocs.deva.me/core-concepts/architecture-overview.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.