# bodanlabs/deepagents-showcase architecture

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

- Interactive diagram: https://gitdiagram.com/bodanlabs/deepagents-showcase
- Repository: https://github.com/bodanlabs/deepagents-showcase

## Overview

1. **Repository shape**
   - This is a two-app monorepo: `apps/api` is the Python backend, and `apps/web` is the React frontend.
   - The root-level `pnpm` workspace and `docker-compose.yml` exist to coordinate local development and containerized runs across both apps.

2. **Backend boundary**
   - `apps/api` is a FastAPI service that owns all agent execution and conversation orchestration.
   - It exposes a chat API and a streaming chat endpoint, plus a lightweight health check for readiness/liveness.

3. **Agent runtime**
   - The backend’s core responsibility is to wrap a LangChain Deep Agents setup backed by OpenAI.
   - `app/services/agent.py` is the agent-facing layer; `app/services/chat_service.py` likely sits above it to convert HTTP chat requests into agent invocations and streaming events.

4. **API contract**
   - `app/schemas/chat.py` defines the request/response models that separate the frontend contract from internal agent logic.
   - This is the main boundary for the chat protocol: user messages go in, assistant/tool/reasoning events come back, with streaming as a first-class path.

5. **Backend configuration and observability**
   - `app/core/config.py` centralizes runtime settings such as OpenAI model selection, CORS, and log level.
   - `app/core/logging.py` handles service logging, which is important because streaming agent runs are otherwise hard to debug.

6. **Backend delivery model**
   - The important transport detail is Server-Sent Events: `/api/chat/stream` streams incremental agent output instead of waiting for a single response.
   - The non-streaming endpoint likely exists for simpler request/response usage or compatibility, while SSE is what powers the live UI experience.

7. **Frontend boundary**
   - `apps/web` is a Vite + React + TypeScript app that renders the chat experience.
   - It does not run the agent itself; its job is to connect to the backend stream, translate events into assistant-ui state, and render them interactively.

8. **Frontend runtime and streaming adapter**
   - `src/runtime/LocalRuntimeProvider.tsx` suggests the app uses assistant-ui’s local runtime abstraction rather than a remote SDK-specific runtime.
   - `src/lib/sse.ts` is the key integration point: it adapts the backend’s SSE stream into the event format the UI runtime expects.

9. **UI composition**
   - `src/components/assistant-ui/*` contains custom rendering for assistant messages, reasoning traces, tool-call cards/groups, and file previews.
   - These components indicate the backend emits structured agent metadata, not just plain text, and the frontend preserves that structure in the conversation view.

10. **Deployment and environment model**
   - The repo is designed to run either with local processes or with Docker Compose.
   - The backend depends on environment variables for OpenAI credentials and allowed CORS origins; the frontend can optionally override the API base URL through its own env file.

11. **Testing and validation**
   - `apps/api/tests` contains health and chat tests, which implies the backend is the main unit-tested surface.
   - There is no separate backend worker or database layer in this tree, so the architecture is intentionally stateless aside from request/session context and external OpenAI calls.

12. **What to draw in an architecture diagram**
   - Show one user-facing React UI, one FastAPI API, one streaming SSE channel between them, and one external dependency on OpenAI via the Deep Agents/LangChain stack.
   - The main flow is: user message in the web app → SSE request to FastAPI → agent execution in the API → streamed tool/reasoning/message events back to the UI.

Main entry points: [`apps/api/app/main.py`](https://github.com/bodanlabs/deepagents-showcase/blob/main/apps/api/app/main.py) (API app), [`apps/web/src/main.tsx`](https://github.com/bodanlabs/deepagents-showcase/blob/main/apps/web/src/main.tsx) (Web app), [`apps/api/app/services/chat_service.py`](https://github.com/bodanlabs/deepagents-showcase/blob/main/apps/api/app/services/chat_service.py) (Chat service), [`docker-compose.yml`](https://github.com/bodanlabs/deepagents-showcase/blob/main/docker-compose.yml) (Compose)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_repo["Monorepo"]
  node_workspace["pnpm workspace"]
  node_compose["Compose<br/>deployment<br/>[docker-compose.yml]"]
end

subgraph group_api["Backend"]
  node_api_main["API app<br/>fastapi entrypoint<br/>[main.py]"]
  node_api_config["Settings<br/>config<br/>[config.py]"]
  node_api_logging["Logging<br/>observability<br/>[logging.py]"]
  node_chat_schema["Chat schema<br/>contract<br/>[chat.py]"]
  node_chat_service["Chat service<br/>orchestration<br/>[chat_service.py]"]
  node_agent_service["Agent runtime<br/>langchain agent<br/>[agent.py]"]
  node_health_api(("Health check<br/>endpoint<br/>[main.py]"))
  node_chat_api(("Chat API<br/>endpoint<br/>[main.py]"))
  node_stream_api(("SSE stream<br/>endpoint<br/>[main.py]"))
  node_api_tests["API tests<br/>[test_chat.py]"]
end

subgraph group_web["Frontend"]
  node_web_main["Web app<br/>vite react entrypoint<br/>[main.tsx]"]
  node_runtime["Local runtime<br/>assistant-ui runtime"]
  node_sse_adapter["SSE adapter<br/>stream adapter<br/>[sse.ts]"]
  node_ui_components["UI components<br/>presentation"]
  node_web_app["Chat UI<br/>react app<br/>[App.tsx]"]
end

node_openai[("OpenAI<br/>external ai api")]

node_workspace -->|"coordinates"| node_compose
node_compose -->|"starts"| node_api_main
node_compose -->|"starts"| node_web_main
node_api_main -->|"loads"| node_api_config
node_api_main -->|"initializes"| node_api_logging
node_api_main -->|"exposes"| node_chat_api
node_api_main -->|"exposes"| node_stream_api
node_api_main -->|"exposes"| node_health_api
node_chat_api -->|"delegates"| node_chat_service
node_stream_api -->|"delegates"| node_chat_service
node_chat_service -->|"validates"| node_chat_schema
node_chat_service -->|"invokes"| node_agent_service
node_agent_service -->|"calls"| node_openai
node_api_tests -.->|"covers"| node_health_api
node_api_tests -.->|"covers"| node_chat_api
node_web_main -->|"uses"| node_runtime
node_runtime -->|"streams via"| node_sse_adapter
node_sse_adapter -->|"connects to"| node_stream_api
node_web_main -->|"renders with"| node_ui_components
node_web_main -.->|"fallbacks to"| node_chat_api
node_ui_components -->|"displays"| node_runtime

click node_workspace "https://github.com/bodanlabs/deepagents-showcase/blob/main/pnpm-workspace.yaml"
click node_compose "https://github.com/bodanlabs/deepagents-showcase/blob/main/docker-compose.yml"
click node_api_main "https://github.com/bodanlabs/deepagents-showcase/blob/main/apps/api/app/main.py"
click node_api_config "https://github.com/bodanlabs/deepagents-showcase/blob/main/apps/api/app/core/config.py"
click node_api_logging "https://github.com/bodanlabs/deepagents-showcase/blob/main/apps/api/app/core/logging.py"
click node_chat_schema "https://github.com/bodanlabs/deepagents-showcase/blob/main/apps/api/app/schemas/chat.py"
click node_chat_service "https://github.com/bodanlabs/deepagents-showcase/blob/main/apps/api/app/services/chat_service.py"
click node_agent_service "https://github.com/bodanlabs/deepagents-showcase/blob/main/apps/api/app/services/agent.py"
click node_health_api "https://github.com/bodanlabs/deepagents-showcase/blob/main/apps/api/app/main.py"
click node_chat_api "https://github.com/bodanlabs/deepagents-showcase/blob/main/apps/api/app/main.py"
click node_stream_api "https://github.com/bodanlabs/deepagents-showcase/blob/main/apps/api/app/main.py"
click node_api_tests "https://github.com/bodanlabs/deepagents-showcase/blob/main/apps/api/tests/test_chat.py"
click node_web_main "https://github.com/bodanlabs/deepagents-showcase/blob/main/apps/web/src/main.tsx"
click node_runtime "https://github.com/bodanlabs/deepagents-showcase/blob/main/apps/web/src/runtime/LocalRuntimeProvider.tsx"
click node_sse_adapter "https://github.com/bodanlabs/deepagents-showcase/blob/main/apps/web/src/lib/sse.ts"
click node_ui_components "https://github.com/bodanlabs/deepagents-showcase/blob/main/apps/web/src/components/assistant-ui/assistant-message.tsx"
click node_web_app "https://github.com/bodanlabs/deepagents-showcase/blob/main/apps/web/src/App.tsx"

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_workspace,node_compose toneBlue
class node_api_main,node_api_config,node_api_logging,node_chat_schema,node_chat_service,node_agent_service,node_health_api,node_chat_api,node_stream_api,node_api_tests toneAmber
class node_web_main,node_runtime,node_sse_adapter,node_ui_components,node_web_app toneMint
class node_openai toneNeutral
```

## Components

### Monorepo

Workspace and deployment glue for both apps

- [pnpm workspace](https://github.com/bodanlabs/deepagents-showcase/blob/main/pnpm-workspace.yaml): workspace · Root package management and shared dev orchestration · `pnpm-workspace.yaml`
- [Compose](https://github.com/bodanlabs/deepagents-showcase/blob/main/docker-compose.yml): deployment · Local multi-service runtime for API and web · `docker-compose.yml`

### Backend

FastAPI service that runs the agent and chat API

- [API app](https://github.com/bodanlabs/deepagents-showcase/blob/main/apps/api/app/main.py): fastapi entrypoint · Bootstraps the FastAPI service and routes · `apps/api/app/main.py`
- [Settings](https://github.com/bodanlabs/deepagents-showcase/blob/main/apps/api/app/core/config.py): config · Runtime configuration for model, CORS, and logging · `apps/api/app/core/config.py`
- [Logging](https://github.com/bodanlabs/deepagents-showcase/blob/main/apps/api/app/core/logging.py): observability · Service logging for agent and request runs · `apps/api/app/core/logging.py`
- [Chat schema](https://github.com/bodanlabs/deepagents-showcase/blob/main/apps/api/app/schemas/chat.py): contract · Request and response models for the chat protocol · `apps/api/app/schemas/chat.py`
- [Chat service](https://github.com/bodanlabs/deepagents-showcase/blob/main/apps/api/app/services/chat_service.py): orchestration · Converts HTTP chat calls into agent execution and stream events · `apps/api/app/services/chat_service.py`
- [Agent runtime](https://github.com/bodanlabs/deepagents-showcase/blob/main/apps/api/app/services/agent.py): langchain agent · Deep Agents and OpenAI-backed agent execution layer · `apps/api/app/services/agent.py`
- [Health check](https://github.com/bodanlabs/deepagents-showcase/blob/main/apps/api/app/main.py): endpoint · Lightweight readiness and liveness surface · `apps/api/app/main.py`
- [Chat API](https://github.com/bodanlabs/deepagents-showcase/blob/main/apps/api/app/main.py): endpoint · Non-streaming chat request-response endpoint · `apps/api/app/main.py`
- [SSE stream](https://github.com/bodanlabs/deepagents-showcase/blob/main/apps/api/app/main.py): endpoint · Streaming chat endpoint that emits incremental events · `apps/api/app/main.py`
- [API tests](https://github.com/bodanlabs/deepagents-showcase/blob/main/apps/api/tests/test_chat.py): tests · Health and chat validation coverage · `apps/api/tests/test_chat.py`

### Frontend

React chat UI that consumes the streaming API

- [Web app](https://github.com/bodanlabs/deepagents-showcase/blob/main/apps/web/src/main.tsx): vite react entrypoint · Bootstraps the React chat experience · `apps/web/src/main.tsx`
- [Local runtime](https://github.com/bodanlabs/deepagents-showcase/blob/main/apps/web/src/runtime/LocalRuntimeProvider.tsx): assistant-ui runtime · Assistant UI local runtime wrapper for the conversation · `apps/web/src/runtime/LocalRuntimeProvider.tsx`
- [SSE adapter](https://github.com/bodanlabs/deepagents-showcase/blob/main/apps/web/src/lib/sse.ts): stream adapter · Maps backend SSE events into UI runtime events · `apps/web/src/lib/sse.ts`
- [UI components](https://github.com/bodanlabs/deepagents-showcase/blob/main/apps/web/src/components/assistant-ui/assistant-message.tsx): presentation · Custom rendering for messages, reasoning, tools, and files · `apps/web/src/components/assistant-ui/assistant-message.tsx`
- [Chat UI](https://github.com/bodanlabs/deepagents-showcase/blob/main/apps/web/src/App.tsx): react app · Conversation interface for sending messages and rendering streamed assistant output · `apps/web/src/App.tsx`

### Other components

- **OpenAI**: external ai api · External model and tool execution backend used by the agent

## Connections

- pnpm workspace → Compose: coordinates · Workspace and compose config orchestrate local runs
- Compose → API app: starts · Compose launches the backend service
- Compose → Web app: starts · Compose launches the frontend service
- API app → Settings: loads · API entrypoint reads runtime settings
- API app → Logging: initializes · Service boot sets up logging
- API app → Chat API: exposes · Non-streaming chat route
- API app → SSE stream: exposes · Streaming SSE chat route
- API app → Health check: exposes · Health/readiness route
- Chat API → Chat service: delegates · Chat requests are handed to orchestration layer
- SSE stream → Chat service: delegates · SSE requests are converted into agent streams
- Chat service → Chat schema: validates · HTTP boundary uses chat request/response models
- Chat service → Agent runtime: invokes · Orchestrates agent execution
- Agent runtime → OpenAI: calls · Agent runtime depends on external model API
- API tests → Health check: covers · Health behavior is tested
- API tests → Chat API: covers · Chat behavior is tested
- Web app → Local runtime: uses · React app is wrapped in the assistant runtime
- Local runtime → SSE adapter: streams via · Runtime receives backend events through SSE adapter
- SSE adapter → SSE stream: connects to · Frontend opens the backend SSE chat endpoint
- Web app → UI components: renders with · Conversation UI uses custom assistant message components
- Web app → Chat API: fallbacks to · Frontend can also use non-streaming chat path
- UI components → Local runtime: displays · Structured agent events are rendered into UI state