bodanlabs/deepagents-showcase

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.