# dabit3/react-native-ai architecture

> Architecture diagram of the GitHub repository dabit3/react-native-ai, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/dabit3/react-native-ai
- Repository: https://github.com/dabit3/react-native-ai

## Overview

1. This repo is a three-part monorepo: an Expo/React Native mobile app in `app/`, a TypeScript backend in `server/`, and a small Node CLI in `cli/`. The architecture is intentionally split so the mobile client stays UI-focused while the server owns API keys, provider integration, and file handling.

2. The mobile app is the primary user-facing surface. It is an Expo-based React Native project with native iOS/Android shells, shared TypeScript source, and bundled assets/fonts. Entry points are `app/index.js` and `app/App.tsx`, with the app rendering from `src/main.tsx`.

3. The app UI is organized around a few screens in `app/src/screens`: `chat.tsx` for text/assistant chat, `images.tsx` for image generation, `assistant.tsx` for assistant-style flows, and `settings.tsx` for runtime configuration. Shared UI pieces live in `app/src/components`, including model-specific icons and a model picker modal.

4. App-wide state and behavior are centralized in `app/src/context.tsx`, `app/src/theme.ts`, `app/constants.ts`, and `app/src/utils.ts`. These files govern selected model, theme selection, and mapping between user choices and backend routes, which is important for the architecture because the app does not hardcode provider logic into the screens themselves.

5. The mobile app is designed to support multiple LLM providers rather than a single backend. The README and component set show explicit support for OpenAI, Anthropic, Gemini, Cohere, and Mistral-branded UI affordances, with streaming/real-time response handling as a core interaction pattern.

6. The backend in `server/src` is the provider proxy and orchestration layer. It is split by capability into `chat/`, `images/`, and `files/`, with routers such as `chatRouter.ts`, `imagesRouter.ts`, and `fileRouter.ts` acting as the external API boundary consumed by the mobile app.

7. Chat is the most structured backend subsystem. The `server/src/chat` folder contains provider adapters (`gpt.ts`, `claude.ts`, `cohere.ts`, `gemini.ts`) plus orchestration helpers like `createAssistant.ts`, `addMessageToThread.ts`, `getThreadMessages.ts`, `runResponse.ts`, and `runStatus.ts`. This suggests a thread/run model for assistant-style conversations with streaming status updates back to the app.

8. Image generation is handled separately from chat, with `server/src/images/gemini.ts` implementing Gemini-based image generation and `imagesRouter.ts` exposing it. The README indicates this path also supports natural-language-to-image workflows and image input handling from the app’s image screen.

9. File uploads are a distinct backend boundary. `server/src/files/upload-file.ts` and `helpers/saveFileToOpenai.ts` indicate the server accepts uploads, stores them locally under `server/uploads/`, and can forward them to OpenAI-compatible storage when needed. This keeps file credentials and transport logic off the device.

10. The backend is environment-driven. Both `app/.env.example` and `server/.env.example` show that runtime configuration is externalized, with the server specifically requiring provider keys such as `GEMINI_API_KEY`. The repo’s architecture assumes the server is the trusted layer for secrets and provider access, while the app talks to it over HTTP.

11. The CLI in `cli/` is a project bootstrap/configuration tool rather than an app runtime. The README shows it is invoked with `npx rn-ai` to generate a new project and set up environment configuration, making it part of the developer experience and not the production runtime path.

12. Native platform files under `app/ios` and `app/android` are mostly generated shells around the React Native runtime. They matter architecturally only insofar as they provide the deployment targets for the shared app code and host the app icons, splash screens, and platform manifests.

Main entry points: [`app/src/main.tsx`](https://github.com/dabit3/react-native-ai/blob/main/app/src/main.tsx) (Main UI), [`app/src/screens`](https://github.com/dabit3/react-native-ai/tree/main/app/src/screens) (Screens), [`server/src/index.ts`](https://github.com/dabit3/react-native-ai/blob/main/server/src/index.ts) (Server entry), [`app/src/components`](https://github.com/dabit3/react-native-ai/tree/main/app/src/components) (Shared UI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Mobile app"]
  node_app_entry["App entry<br/>expo bootstrap<br/>[index.js]"]
  node_app_root["Root app<br/>react native shell<br/>[App.tsx]"]
  node_app_main["Main UI<br/>app composition<br/>[main.tsx]"]
  node_app_context["App state<br/>shared context<br/>[context.tsx]"]
  node_app_theme["Theme<br/>[theme.ts]"]
  node_app_utils["App utils<br/>client mapping<br/>[utils.ts]"]
  node_app_components["Shared UI<br/>react components"]
  node_app_screens["Screens<br/>screen set"]
  node_app_chat["Chat<br/>screen<br/>[chat.tsx]"]
  node_app_images["Images<br/>screen<br/>[images.tsx]"]
  node_app_assistant["Assistant<br/>screen<br/>[assistant.tsx]"]
  node_app_settings["Settings<br/>screen<br/>[settings.tsx]"]
  node_app_ios[("iOS shell<br/>native target")]
  node_app_android[("Android shell<br/>native target")]
end

subgraph group_server["Backend"]
  node_server_entry["Server entry<br/>node api<br/>[index.ts]"]
  node_server_chat_router["Chat API<br/>router<br/>[chatRouter.ts]"]
  node_server_chat_core["Chat core<br/>orchestration"]
  node_server_chat_providers["Providers<br/>adapter set"]
  node_server_images_router["Images API<br/>router<br/>[imagesRouter.ts]"]
  node_server_images_core["Image gen<br/>provider flow<br/>[gemini.ts]"]
  node_server_files_router["Files API<br/>router<br/>[fileRouter.ts]"]
  node_server_upload["File upload<br/>storage flow<br/>[upload-file.ts]"]
  node_server_file_helper["OpenAI save<br/>helper"]
end

subgraph group_cli["CLI"]
  node_cli_entry["CLI<br/>bootstrap tool<br/>[cli.js]"]
end

node_repo{{"react-native-ai<br/>monorepo"}}

node_repo -->|"contains"| node_app_entry
node_repo -->|"contains"| node_server_entry
node_repo -->|"contains"| node_cli_entry
node_app_entry -->|"boots"| node_app_root
node_app_root -->|"renders"| node_app_main
node_app_main -->|"uses"| node_app_context
node_app_main -->|"styles"| node_app_theme
node_app_main -->|"maps"| node_app_utils
node_app_main -->|"composes"| node_app_components
node_app_main -->|"navigates"| node_app_screens
node_app_screens -->|"includes"| node_app_chat
node_app_screens -->|"includes"| node_app_images
node_app_screens -->|"includes"| node_app_assistant
node_app_screens -->|"includes"| node_app_settings
node_app_components -->|"supports"| node_app_chat
node_app_components -->|"supports"| node_app_images
node_app_components -->|"reads"| node_app_context
node_app_settings -->|"updates"| node_app_context
node_app_chat -->|"calls"| node_server_chat_router
node_app_images -->|"calls"| node_server_images_router
node_app_assistant -->|"calls"| node_server_chat_router
node_app_settings -->|"configures"| node_server_entry
node_server_entry -->|"mounts"| node_server_chat_router
node_server_entry -->|"mounts"| node_server_images_router
node_server_entry -->|"mounts"| node_server_files_router
node_server_chat_router -->|"orchestrates"| node_server_chat_core
node_server_chat_core -->|"adapts"| node_server_chat_providers
node_server_images_router -->|"delegates"| node_server_images_core
node_server_files_router -->|"handles"| node_server_upload
node_server_upload -->|"stores"| node_server_file_helper
node_server_upload -.->|"feeds"| node_server_chat_core

click node_app_entry "https://github.com/dabit3/react-native-ai/blob/main/app/index.js"
click node_app_root "https://github.com/dabit3/react-native-ai/blob/main/app/App.tsx"
click node_app_main "https://github.com/dabit3/react-native-ai/blob/main/app/src/main.tsx"
click node_app_context "https://github.com/dabit3/react-native-ai/blob/main/app/src/context.tsx"
click node_app_theme "https://github.com/dabit3/react-native-ai/blob/main/app/src/theme.ts"
click node_app_utils "https://github.com/dabit3/react-native-ai/blob/main/app/src/utils.ts"
click node_app_components "https://github.com/dabit3/react-native-ai/tree/main/app/src/components"
click node_app_screens "https://github.com/dabit3/react-native-ai/tree/main/app/src/screens"
click node_app_chat "https://github.com/dabit3/react-native-ai/blob/main/app/src/screens/chat.tsx"
click node_app_images "https://github.com/dabit3/react-native-ai/blob/main/app/src/screens/images.tsx"
click node_app_assistant "https://github.com/dabit3/react-native-ai/blob/main/app/src/screens/assistant.tsx"
click node_app_settings "https://github.com/dabit3/react-native-ai/blob/main/app/src/screens/settings.tsx"
click node_app_ios "https://github.com/dabit3/react-native-ai/tree/main/app/ios"
click node_app_android "https://github.com/dabit3/react-native-ai/tree/main/app/android"
click node_server_entry "https://github.com/dabit3/react-native-ai/blob/main/server/src/index.ts"
click node_server_chat_router "https://github.com/dabit3/react-native-ai/blob/main/server/src/chat/chatRouter.ts"
click node_server_chat_core "https://github.com/dabit3/react-native-ai/tree/main/server/src/chat"
click node_server_chat_providers "https://github.com/dabit3/react-native-ai/tree/main/server/src/chat"
click node_server_images_router "https://github.com/dabit3/react-native-ai/blob/main/server/src/images/imagesRouter.ts"
click node_server_images_core "https://github.com/dabit3/react-native-ai/blob/main/server/src/images/gemini.ts"
click node_server_files_router "https://github.com/dabit3/react-native-ai/blob/main/server/src/files/fileRouter.ts"
click node_server_upload "https://github.com/dabit3/react-native-ai/blob/main/server/src/files/upload-file.ts"
click node_server_file_helper "https://github.com/dabit3/react-native-ai/blob/main/server/src/helpers/saveFileToOpenai.ts"
click node_cli_entry "https://github.com/dabit3/react-native-ai/blob/main/cli/cli.js"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_app_entry,node_app_root,node_app_main,node_app_context,node_app_theme,node_app_utils,node_app_components,node_app_screens,node_app_chat,node_app_images,node_app_assistant,node_app_settings,node_app_ios,node_app_android toneBlue
class node_server_entry,node_server_chat_router,node_server_chat_core,node_server_chat_providers,node_server_images_router,node_server_images_core,node_server_files_router,node_server_upload,node_server_file_helper toneAmber
class node_cli_entry toneMint
class node_repo toneNeutral
```

## Components

### Mobile app

Expo/React Native client and native shells.

- [App entry](https://github.com/dabit3/react-native-ai/blob/main/app/index.js): expo bootstrap · Loads the React Native application entrypoints. · `app/index.js`
- [Root app](https://github.com/dabit3/react-native-ai/blob/main/app/App.tsx): react native shell · Top-level app component wired into Expo. · `app/App.tsx`
- [Main UI](https://github.com/dabit3/react-native-ai/blob/main/app/src/main.tsx): app composition · Bootstraps navigation and shared UI state. · `app/src/main.tsx`
- [App state](https://github.com/dabit3/react-native-ai/blob/main/app/src/context.tsx): shared context · Holds selected model, runtime config, and cross-screen behavior. · `app/src/context.tsx`
- [Theme](https://github.com/dabit3/react-native-ai/blob/main/app/src/theme.ts): ui theme · Defines visual theme and styling primitives. · `app/src/theme.ts`
- [App utils](https://github.com/dabit3/react-native-ai/blob/main/app/src/utils.ts): client mapping · Maps user choices to backend routes and helper behavior. · `app/src/utils.ts`
- [Shared UI](https://github.com/dabit3/react-native-ai/tree/main/app/src/components): react components · Reusable components including model icons, header, and modal UI. · `app/src/components`
- [Screens](https://github.com/dabit3/react-native-ai/tree/main/app/src/screens): screen set · Primary user-facing app screens. · `app/src/screens`
- [Chat](https://github.com/dabit3/react-native-ai/blob/main/app/src/screens/chat.tsx): screen · Text and assistant conversation UI. · `app/src/screens/chat.tsx`
- [Images](https://github.com/dabit3/react-native-ai/blob/main/app/src/screens/images.tsx): screen · Image generation and image input flows. · `app/src/screens/images.tsx`
- [Assistant](https://github.com/dabit3/react-native-ai/blob/main/app/src/screens/assistant.tsx): screen · Assistant-style interaction flows. · `app/src/screens/assistant.tsx`
- [Settings](https://github.com/dabit3/react-native-ai/blob/main/app/src/screens/settings.tsx): screen · Runtime configuration and client settings. · `app/src/screens/settings.tsx`
- [iOS shell](https://github.com/dabit3/react-native-ai/tree/main/app/ios): native target · Generated iOS host for the shared React Native app. · `app/ios`
- [Android shell](https://github.com/dabit3/react-native-ai/tree/main/app/android): native target · Generated Android host for the shared React Native app. · `app/android`

### Backend

TypeScript provider proxy and orchestration API.

- [Server entry](https://github.com/dabit3/react-native-ai/blob/main/server/src/index.ts): node api · Starts the backend API service. · `server/src/index.ts`
- [Chat API](https://github.com/dabit3/react-native-ai/blob/main/server/src/chat/chatRouter.ts): router · External boundary for chat and assistant requests. · `server/src/chat/chatRouter.ts`
- [Chat core](https://github.com/dabit3/react-native-ai/tree/main/server/src/chat): orchestration · Manages threads, runs, and streaming response lifecycle. · `server/src/chat`
- [Providers](https://github.com/dabit3/react-native-ai/tree/main/server/src/chat): adapter set · Provider-specific chat adapters for OpenAI, Anthropic, Cohere, and Gemini. · `server/src/chat`
- [Images API](https://github.com/dabit3/react-native-ai/blob/main/server/src/images/imagesRouter.ts): router · External boundary for image generation requests. · `server/src/images/imagesRouter.ts`
- [Image gen](https://github.com/dabit3/react-native-ai/blob/main/server/src/images/gemini.ts): provider flow · Gemini-based image generation implementation. · `server/src/images/gemini.ts`
- [Files API](https://github.com/dabit3/react-native-ai/blob/main/server/src/files/fileRouter.ts): router · External boundary for file upload handling. · `server/src/files/fileRouter.ts`
- [File upload](https://github.com/dabit3/react-native-ai/blob/main/server/src/files/upload-file.ts): storage flow · Accepts uploads and stores them for later provider use. · `server/src/files/upload-file.ts`
- [OpenAI save](https://github.com/dabit3/react-native-ai/blob/main/server/src/helpers/saveFileToOpenai.ts): helper · Saves files into OpenAI-compatible storage when needed. · `server/src/helpers/saveFileToOpenai.ts`

### CLI

Project bootstrap and setup tool.

- [CLI](https://github.com/dabit3/react-native-ai/blob/main/cli/cli.js): bootstrap tool · Project generation and setup command for new installs. · `cli/cli.js`

### Other components

- **react-native-ai**: monorepo · Three-part repo: mobile app, backend, and CLI.

## Connections

- react-native-ai → App entry: contains · Repository includes the mobile runtime entrypoint.
- react-native-ai → Server entry: contains · Repository includes the backend runtime entrypoint.
- react-native-ai → CLI: contains · Repository includes the developer bootstrap CLI.
- App entry → Root app: boots · Expo entry loads the app shell.
- Root app → Main UI: renders · Top-level app component delegates to main UI composition.
- Main UI → App state: uses · Main UI reads and updates shared client state.
- Main UI → Theme: styles · Main UI applies shared theme primitives.
- Main UI → App utils: maps · Main UI relies on route and model mapping helpers.
- Main UI → Shared UI: composes · Main UI uses shared presentational components.
- Main UI → Screens: navigates · Main UI routes to the primary screen set.
- Screens → Chat: includes · Chat screen is a primary app surface.
- Screens → Images: includes · Images screen is a primary app surface.
- Screens → Assistant: includes · Assistant screen is a primary app surface.
- Screens → Settings: includes · Settings screen configures runtime behavior.
- Shared UI → Chat: supports · Shared UI provides controls used by chat flows.
- Shared UI → Images: supports · Shared UI provides controls used by image flows.
- Shared UI → App state: reads · Components reflect selected model and state.
- Settings → App state: updates · Settings screen changes runtime configuration.
- Chat → Chat API: calls · Chat UI sends requests to the backend chat API.
- Images → Images API: calls · Image UI sends requests to the backend image API.
- Assistant → Chat API: calls · Assistant flows use the chat API for threaded interactions.
- Settings → Server entry: configures · Runtime settings point the client at the backend service.
- Server entry → Chat API: mounts · Backend entry exposes chat routes.
- Server entry → Images API: mounts · Backend entry exposes image routes.
- Server entry → Files API: mounts · Backend entry exposes file routes.
- Chat API → Chat core: orchestrates · Chat API delegates to thread and run management.
- Chat core → Providers: adapts · Core orchestration calls provider-specific implementations.
- Images API → Image gen: delegates · Image API routes into Gemini-based generation logic.
- Files API → File upload: handles · Files API accepts uploads through the upload flow.
- File upload → OpenAI save: stores · Upload flow can persist to OpenAI-compatible storage.
- File upload → Chat core: feeds · Uploaded files can be used by chat and assistant flows.