# swamiabhishek45/openbook architecture

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

- Interactive diagram: https://gitdiagram.com/swamiabhishek45/openbook
- Repository: https://github.com/swamiabhishek45/openbook

## Overview

OpenBook is an AI research and study studio: users create workspaces, ingest research sources, then chat over them or generate study artifacts and interactive debate podcasts. The client presents workspace, source, chat, and learning flows; the Express API delegates domain work to services, with Inngest for background generation. The README documents RAG, integrations, subscriptions, and artifact types; sampled source confirms source and integration handling plus podcast interruption and audio delivery. Some subsystem wiring is based on README and tree evidence rather than inspected implementation.

Main entry points: [`server/src/services/artifact-generation.services.ts`](https://github.com/swamiabhishek45/openbook/blob/main/server/src/services/artifact-generation.services.ts) (Artifact generation), [`server/src/index.ts`](https://github.com/swamiabhishek45/openbook/blob/main/server/src/index.ts) (Express API), [`server/src/services/source.services.ts`](https://github.com/swamiabhishek45/openbook/blob/main/server/src/services/source.services.ts) (Source processing), [`client/lib/api-client.ts`](https://github.com/swamiabhishek45/openbook/blob/main/client/lib/api-client.ts) (API client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Workspace studio"]
  node_workspace_ui["Workspace UI<br/>[page.tsx]"]
  node_source_ui["Source library<br/>[sources-panel.tsx]"]
  node_chat_ui["Grounded chat<br/>[chat-panel.tsx]"]
  node_learn_ui["Learning studio<br/>[studio-panel.tsx]"]
  node_podcast_ui["Podcast viewer<br/>[podcast-viewer.tsx]"]
  node_api_client["API client<br/>[api-client.ts]"]
end

subgraph group_api["API and domain"]
  node_server["Express API<br/>[index.ts]"]
  node_source_routes["Source routes<br/>[source.routes.ts]"]
  node_source_controller["Source controller"]
  node_artifact_controller["Artifact controller"]
  node_chat_routes["Chat routes<br/>[chat.routes.ts]"]
  node_chat_service["Chat service<br/>[chat.services.ts]"]
end

subgraph group_knowledge["Source and retrieval"]
  node_source_service["Source processing<br/>[source.services.ts]"]
  node_ingestion["Ingestion adapters"]
  node_chunking["Chunking<br/>[chunking.ts]"]
  node_rag["RAG retrieval<br/>[retrieve.ts]"]
  node_source_store[("Source records")]
  node_vectors[("Vector index<br/>[pinecone.ts]")]
end

subgraph group_generation["Learning generation"]
  node_artifact_service["Artifact service"]
  node_generation_service["Artifact generation"]
  node_worker["Background workers<br/>[index.ts]"]
  node_artifact_store[("Artifact records")]
  node_interruption["Podcast interruption"]
end

subgraph group_platform["Accounts and services"]
  node_auth["Authentication<br/>[auth.ts]"]
  node_billing["Billing services"]
  node_integrations["Integration services"]
  node_postgres[("PostgreSQL<br/>[db.ts]")]
end

node_researcher(("Researcher"))
node_llm{{"AI models"}}
node_elevenlabs{{"ElevenLabs"}}
node_cloudinary[("Cloudinary")]
node_external_sources{{"External sources"}}
node_payments{{"Razorpay"}}

node_researcher -->|"uses"| node_workspace_ui
node_workspace_ui -->|"opens"| node_source_ui
node_source_ui -->|"submits sources"| node_api_client
node_chat_ui -->|"sends questions"| node_api_client
node_learn_ui -->|"requests artifacts"| node_api_client
node_podcast_ui -->|"asks interruption"| node_api_client
node_api_client -->|"HTTP requests"| node_server
node_server -->|"authenticates"| node_auth
node_server -->|"registers routes"| node_source_routes
node_source_routes -->|"dispatches"| node_source_controller
node_source_controller -->|"calls"| node_source_service
node_source_service -->|"fetches content"| node_ingestion
node_source_service -->|"chunks content"| node_chunking
node_source_service -->|"persists sources"| node_source_store
node_source_service -.->|"emits processing work"| node_worker
node_ingestion -.->|"imports from"| node_external_sources
node_chat_routes -->|"dispatches"| node_chat_service
node_chat_service -->|"retrieves context"| node_rag
node_rag -->|"searches vectors"| node_vectors
node_rag -->|"embeds and reranks"| node_llm
node_chat_service -->|"generates replies"| node_llm
node_artifact_controller -->|"calls"| node_artifact_service
node_artifact_service -->|"queues generation"| node_worker
node_worker -->|"runs generation"| node_generation_service
node_generation_service -->|"uses workspace sources"| node_source_store
node_generation_service -->|"generates artifacts"| node_llm
node_generation_service -.->|"synthesizes speech"| node_elevenlabs
node_generation_service -.->|"stores media"| node_cloudinary
node_generation_service -->|"persists artifacts"| node_artifact_store
node_artifact_controller -->|"processes questions"| node_interruption
node_interruption -->|"grounds replies"| node_rag
node_interruption -.->|"synthesizes response"| node_elevenlabs
node_artifact_controller -->|"reads podcast audio"| node_artifact_store
node_server -->|"serves integration API"| node_integrations
node_integrations -.->|"connects providers"| node_external_sources
node_server -->|"serves billing API"| node_billing
node_billing -.->|"handles subscriptions"| node_payments
node_billing -->|"updates plan state"| node_postgres

click node_workspace_ui "https://github.com/swamiabhishek45/openbook/blob/main/client/app/(protected)/workspace/%5BworkspaceId%5D/page.tsx"
click node_source_ui "https://github.com/swamiabhishek45/openbook/blob/main/client/features/sources/components/sources-panel.tsx"
click node_chat_ui "https://github.com/swamiabhishek45/openbook/blob/main/client/features/chat/components/chat-panel.tsx"
click node_learn_ui "https://github.com/swamiabhishek45/openbook/blob/main/client/features/learn/components/studio-panel.tsx"
click node_podcast_ui "https://github.com/swamiabhishek45/openbook/blob/main/client/features/learn/components/podcast-viewer.tsx"
click node_api_client "https://github.com/swamiabhishek45/openbook/blob/main/client/lib/api-client.ts"
click node_server "https://github.com/swamiabhishek45/openbook/blob/main/server/src/index.ts"
click node_source_routes "https://github.com/swamiabhishek45/openbook/blob/main/server/src/routes/source.routes.ts"
click node_source_controller "https://github.com/swamiabhishek45/openbook/blob/main/server/src/controllers/source.controller.ts"
click node_artifact_controller "https://github.com/swamiabhishek45/openbook/blob/main/server/src/controllers/artifact.controller.ts"
click node_chat_routes "https://github.com/swamiabhishek45/openbook/blob/main/server/src/routes/chat.routes.ts"
click node_chat_service "https://github.com/swamiabhishek45/openbook/blob/main/server/src/services/chat.services.ts"
click node_source_service "https://github.com/swamiabhishek45/openbook/blob/main/server/src/services/source.services.ts"
click node_ingestion "https://github.com/swamiabhishek45/openbook/tree/main/server/src/lib/sources"
click node_chunking "https://github.com/swamiabhishek45/openbook/blob/main/server/src/lib/chunking.ts"
click node_rag "https://github.com/swamiabhishek45/openbook/blob/main/server/src/lib/rag/retrieve.ts"
click node_source_store "https://github.com/swamiabhishek45/openbook/blob/main/server/src/repository/source.repository.ts"
click node_vectors "https://github.com/swamiabhishek45/openbook/blob/main/server/src/lib/pinecone.ts"
click node_artifact_service "https://github.com/swamiabhishek45/openbook/blob/main/server/src/services/artifact.services.ts"
click node_generation_service "https://github.com/swamiabhishek45/openbook/blob/main/server/src/services/artifact-generation.services.ts"
click node_worker "https://github.com/swamiabhishek45/openbook/blob/main/server/src/inngest/index.ts"
click node_artifact_store "https://github.com/swamiabhishek45/openbook/blob/main/server/src/repository/artifact.repository.ts"
click node_interruption "https://github.com/swamiabhishek45/openbook/blob/main/server/src/services/podcast-interruption.services.ts"
click node_auth "https://github.com/swamiabhishek45/openbook/blob/main/server/src/lib/auth.ts"
click node_billing "https://github.com/swamiabhishek45/openbook/blob/main/server/src/services/payment.services.ts"
click node_integrations "https://github.com/swamiabhishek45/openbook/blob/main/server/src/controllers/integration.controller.ts"
click node_postgres "https://github.com/swamiabhishek45/openbook/blob/main/server/src/lib/db.ts"

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_ui,node_source_ui,node_chat_ui,node_learn_ui,node_podcast_ui,node_api_client toneBlue
class node_server,node_source_routes,node_source_controller,node_artifact_controller,node_chat_routes,node_chat_service,node_cloudinary toneAmber
class node_source_service,node_ingestion,node_chunking,node_rag,node_source_store,node_vectors toneMint
class node_artifact_service,node_generation_service,node_worker,node_artifact_store,node_interruption toneRose
class node_auth,node_billing,node_integrations,node_postgres,node_researcher,node_llm,node_elevenlabs,node_external_sources,node_payments toneIndigo
```

## Components

### Workspace studio

- [Workspace UI](https://github.com/swamiabhishek45/openbook/blob/main/client/app/(protected)/workspace/%5BworkspaceId%5D/page.tsx): `client/app/(protected)/workspace/[workspaceId]/page.tsx`
- [Source library](https://github.com/swamiabhishek45/openbook/blob/main/client/features/sources/components/sources-panel.tsx): `client/features/sources/components/sources-panel.tsx`
- [Grounded chat](https://github.com/swamiabhishek45/openbook/blob/main/client/features/chat/components/chat-panel.tsx): `client/features/chat/components/chat-panel.tsx`
- [Learning studio](https://github.com/swamiabhishek45/openbook/blob/main/client/features/learn/components/studio-panel.tsx): `client/features/learn/components/studio-panel.tsx`
- [Podcast viewer](https://github.com/swamiabhishek45/openbook/blob/main/client/features/learn/components/podcast-viewer.tsx): `client/features/learn/components/podcast-viewer.tsx`
- [API client](https://github.com/swamiabhishek45/openbook/blob/main/client/lib/api-client.ts): `client/lib/api-client.ts`

### API and domain

- [Express API](https://github.com/swamiabhishek45/openbook/blob/main/server/src/index.ts): `server/src/index.ts`
- [Source routes](https://github.com/swamiabhishek45/openbook/blob/main/server/src/routes/source.routes.ts): `server/src/routes/source.routes.ts`
- [Source controller](https://github.com/swamiabhishek45/openbook/blob/main/server/src/controllers/source.controller.ts): `server/src/controllers/source.controller.ts`
- [Artifact controller](https://github.com/swamiabhishek45/openbook/blob/main/server/src/controllers/artifact.controller.ts): `server/src/controllers/artifact.controller.ts`
- [Chat routes](https://github.com/swamiabhishek45/openbook/blob/main/server/src/routes/chat.routes.ts): `server/src/routes/chat.routes.ts`
- [Chat service](https://github.com/swamiabhishek45/openbook/blob/main/server/src/services/chat.services.ts): `server/src/services/chat.services.ts`

### Source and retrieval

- [Source processing](https://github.com/swamiabhishek45/openbook/blob/main/server/src/services/source.services.ts): `server/src/services/source.services.ts`
- [Ingestion adapters](https://github.com/swamiabhishek45/openbook/tree/main/server/src/lib/sources): `server/src/lib/sources`
- [Chunking](https://github.com/swamiabhishek45/openbook/blob/main/server/src/lib/chunking.ts): `server/src/lib/chunking.ts`
- [RAG retrieval](https://github.com/swamiabhishek45/openbook/blob/main/server/src/lib/rag/retrieve.ts): `server/src/lib/rag/retrieve.ts`
- [Source records](https://github.com/swamiabhishek45/openbook/blob/main/server/src/repository/source.repository.ts): `server/src/repository/source.repository.ts`
- [Vector index](https://github.com/swamiabhishek45/openbook/blob/main/server/src/lib/pinecone.ts): `server/src/lib/pinecone.ts`

### Learning generation

- [Artifact service](https://github.com/swamiabhishek45/openbook/blob/main/server/src/services/artifact.services.ts): `server/src/services/artifact.services.ts`
- [Artifact generation](https://github.com/swamiabhishek45/openbook/blob/main/server/src/services/artifact-generation.services.ts): `server/src/services/artifact-generation.services.ts`
- [Background workers](https://github.com/swamiabhishek45/openbook/blob/main/server/src/inngest/index.ts): `server/src/inngest/index.ts`
- [Artifact records](https://github.com/swamiabhishek45/openbook/blob/main/server/src/repository/artifact.repository.ts): `server/src/repository/artifact.repository.ts`
- [Podcast interruption](https://github.com/swamiabhishek45/openbook/blob/main/server/src/services/podcast-interruption.services.ts): `server/src/services/podcast-interruption.services.ts`

### Accounts and services

- [Authentication](https://github.com/swamiabhishek45/openbook/blob/main/server/src/lib/auth.ts): `server/src/lib/auth.ts`
- [Billing services](https://github.com/swamiabhishek45/openbook/blob/main/server/src/services/payment.services.ts): `server/src/services/payment.services.ts`
- [Integration services](https://github.com/swamiabhishek45/openbook/blob/main/server/src/controllers/integration.controller.ts): `server/src/controllers/integration.controller.ts`
- [PostgreSQL](https://github.com/swamiabhishek45/openbook/blob/main/server/src/lib/db.ts): `server/src/lib/db.ts`

### Other components

- **Researcher**
- **AI models**
- **ElevenLabs**
- **Cloudinary**
- **External sources**
- **Razorpay**

## Connections

- Researcher → Workspace UI: uses
- Workspace UI → Source library: opens
- Source library → API client: submits sources
- Grounded chat → API client: sends questions
- Learning studio → API client: requests artifacts
- Podcast viewer → API client: asks interruption
- API client → Express API: HTTP requests
- Express API → Authentication: authenticates
- Express API → Source routes: registers routes
- Source routes → Source controller: dispatches
- Source controller → Source processing: calls
- Source processing → Ingestion adapters: fetches content
- Source processing → Chunking: chunks content
- Source processing → Source records: persists sources
- Source processing → Background workers: emits processing work
- Ingestion adapters → External sources: imports from
- Chat routes → Chat service: dispatches
- Chat service → RAG retrieval: retrieves context
- RAG retrieval → Vector index: searches vectors
- RAG retrieval → AI models: embeds and reranks
- Chat service → AI models: generates replies
- Artifact controller → Artifact service: calls
- Artifact service → Background workers: queues generation
- Background workers → Artifact generation: runs generation
- Artifact generation → Source records: uses workspace sources
- Artifact generation → AI models: generates artifacts
- Artifact generation → ElevenLabs: synthesizes speech
- Artifact generation → Cloudinary: stores media
- Artifact generation → Artifact records: persists artifacts
- Artifact controller → Podcast interruption: processes questions
- Podcast interruption → RAG retrieval: grounds replies
- Podcast interruption → ElevenLabs: synthesizes response
- Artifact controller → Artifact records: reads podcast audio
- Express API → Integration services: serves integration API
- Integration services → External sources: connects providers
- Express API → Billing services: serves billing API
- Billing services → Razorpay: handles subscriptions
- Billing services → PostgreSQL: updates plan state