# ishurana001/vox-tome-ai architecture

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

- Interactive diagram: https://gitdiagram.com/ishurana001/vox-tome-ai
- Repository: https://github.com/ishurana001/vox-tome-ai

## Overview

Vox Tome AI turns uploaded PDFs into a searchable book library and live voice conversations grounded in book content. The main journey is upload, library discovery, book selection, contextual search during a Vapi conversation, and session-limit tracking under tiered subscriptions. The README also describes intelligent PDF parsing, but the sampled code does not expose its implementation path, so it is not drawn as a separate component. Several page and book-action implementations were not sampled; their uncertain wiring is omitted.

Main entry points: [`app/api/upload/route.ts`](https://github.com/ishurana001/vox-tome-ai/blob/main/app/api/upload/route.ts) (Upload authorization), [`hooks/useVapi.ts`](https://github.com/ishurana001/vox-tome-ai/blob/main/hooks/useVapi.ts) (Voice session hook), [`lib/actions/session.actions.ts`](https://github.com/ishurana001/vox-tome-ai/blob/main/lib/actions/session.actions.ts) (Session actions), [`app/(root)/page.tsx`](https://github.com/ishurana001/vox-tome-ai/blob/main/app/(root)/page.tsx) (Book library)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Reader experience"]
  node_library["Book library<br/>[page.tsx]"]
  node_search["Library search<br/>[Search.tsx]"]
  node_bookpage["Book workspace<br/>[page.tsx]"]
  node_subscriptions["Plan page<br/>[page.tsx]"]
end

subgraph group_ingestion["Book ingestion"]
  node_uploadui["Upload form<br/>[page.tsx]"]
  node_uploadapi["Upload authorization<br/>[route.ts]"]
end

subgraph group_conversation["Voice conversation"]
  node_vapihook["Voice session hook<br/>[useVapi.ts]"]
  node_voiceui["Voice controls<br/>[VapiControls.tsx]"]
  node_transcript["Conversation transcript<br/>[Transcript.tsx]"]
  node_searchapi["Book search tool<br/>[route.ts]"]
end

subgraph group_domain["Domain services"]
  node_bookactions["Book actions<br/>[book.actions.ts]"]
  node_sessionactions["Session actions<br/>[session.actions.ts]"]
  node_subscriptionhook["Plan limits<br/>[useSubscription.ts]"]
  node_sessionmodel[("Voice sessions")]
  node_segmentmodel[("Book segments")]
  node_bookmodel[("Books<br/>[book.model.ts]")]
end

subgraph group_platform["Identity and storage"]
end

node_reader(("Reader"))
node_blob[("Vercel Blob")]
node_vapi["Vapi AI"]
node_clerk["Clerk identity"]
node_mongodb[("MongoDB")]

node_reader -->|"browses"| node_library
node_reader -->|"uploads"| node_uploadui
node_reader -->|"opens"| node_bookpage
node_reader -->|"manages plan"| node_subscriptions
node_library -->|"offers search"| node_search
node_uploadui -->|"requests upload"| node_uploadapi
node_uploadapi -->|"checks identity"| node_clerk
node_uploadapi -->|"authorizes upload"| node_blob
node_voiceui -->|"controls"| node_vapihook
node_vapihook -->|"starts call"| node_vapi
node_vapi -.->|"calls tool"| node_searchapi
node_searchapi -->|"searches segments"| node_bookactions
node_bookactions -->|"queries"| node_segmentmodel
node_vapihook -->|"tracks session"| node_sessionactions
node_sessionactions -->|"checks limits"| node_subscriptionhook
node_sessionactions -->|"creates and updates"| node_sessionmodel
node_sessionmodel -->|"persists"| node_mongodb
node_segmentmodel -->|"persists"| node_mongodb
node_bookmodel -->|"persists"| node_mongodb

click node_library "https://github.com/ishurana001/vox-tome-ai/blob/main/app/(root)/page.tsx"
click node_search "https://github.com/ishurana001/vox-tome-ai/blob/main/components/Search.tsx"
click node_bookpage "https://github.com/ishurana001/vox-tome-ai/blob/main/app/books/%5Bslug%5D/page.tsx"
click node_subscriptions "https://github.com/ishurana001/vox-tome-ai/blob/main/app/(root)/subscriptions/page.tsx"
click node_uploadui "https://github.com/ishurana001/vox-tome-ai/blob/main/app/(root)/books/new/page.tsx"
click node_uploadapi "https://github.com/ishurana001/vox-tome-ai/blob/main/app/api/upload/route.ts"
click node_vapihook "https://github.com/ishurana001/vox-tome-ai/blob/main/hooks/useVapi.ts"
click node_voiceui "https://github.com/ishurana001/vox-tome-ai/blob/main/components/VapiControls.tsx"
click node_transcript "https://github.com/ishurana001/vox-tome-ai/blob/main/components/Transcript.tsx"
click node_searchapi "https://github.com/ishurana001/vox-tome-ai/blob/main/app/api/vapi/search-book/route.ts"
click node_bookactions "https://github.com/ishurana001/vox-tome-ai/blob/main/lib/actions/book.actions.ts"
click node_sessionactions "https://github.com/ishurana001/vox-tome-ai/blob/main/lib/actions/session.actions.ts"
click node_subscriptionhook "https://github.com/ishurana001/vox-tome-ai/blob/main/hooks/useSubscription.ts"
click node_sessionmodel "https://github.com/ishurana001/vox-tome-ai/blob/main/database/models/voice-session.model.ts"
click node_segmentmodel "https://github.com/ishurana001/vox-tome-ai/blob/main/database/models/book-segment.model.ts"
click node_bookmodel "https://github.com/ishurana001/vox-tome-ai/blob/main/database/models/book.model.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_library,node_search,node_bookpage,node_subscriptions toneBlue
class node_uploadui,node_uploadapi,node_blob,node_mongodb toneAmber
class node_vapihook,node_voiceui,node_transcript,node_searchapi,node_vapi toneMint
class node_bookactions,node_sessionactions,node_subscriptionhook,node_sessionmodel,node_segmentmodel,node_bookmodel toneRose
class node_reader,node_clerk toneIndigo
```

## Components

### Reader experience

- [Book library](https://github.com/ishurana001/vox-tome-ai/blob/main/app/(root)/page.tsx): `app/(root)/page.tsx`
- [Library search](https://github.com/ishurana001/vox-tome-ai/blob/main/components/Search.tsx): `components/Search.tsx`
- [Book workspace](https://github.com/ishurana001/vox-tome-ai/blob/main/app/books/%5Bslug%5D/page.tsx): `app/books/[slug]/page.tsx`
- [Plan page](https://github.com/ishurana001/vox-tome-ai/blob/main/app/(root)/subscriptions/page.tsx): `app/(root)/subscriptions/page.tsx`

### Book ingestion

- [Upload form](https://github.com/ishurana001/vox-tome-ai/blob/main/app/(root)/books/new/page.tsx): `app/(root)/books/new/page.tsx`
- [Upload authorization](https://github.com/ishurana001/vox-tome-ai/blob/main/app/api/upload/route.ts): `app/api/upload/route.ts`

### Voice conversation

- [Voice session hook](https://github.com/ishurana001/vox-tome-ai/blob/main/hooks/useVapi.ts): `hooks/useVapi.ts`
- [Voice controls](https://github.com/ishurana001/vox-tome-ai/blob/main/components/VapiControls.tsx): `components/VapiControls.tsx`
- [Conversation transcript](https://github.com/ishurana001/vox-tome-ai/blob/main/components/Transcript.tsx): `components/Transcript.tsx`
- [Book search tool](https://github.com/ishurana001/vox-tome-ai/blob/main/app/api/vapi/search-book/route.ts): `app/api/vapi/search-book/route.ts`

### Domain services

- [Book actions](https://github.com/ishurana001/vox-tome-ai/blob/main/lib/actions/book.actions.ts): `lib/actions/book.actions.ts`
- [Session actions](https://github.com/ishurana001/vox-tome-ai/blob/main/lib/actions/session.actions.ts): `lib/actions/session.actions.ts`
- [Plan limits](https://github.com/ishurana001/vox-tome-ai/blob/main/hooks/useSubscription.ts): `hooks/useSubscription.ts`
- [Voice sessions](https://github.com/ishurana001/vox-tome-ai/blob/main/database/models/voice-session.model.ts): `database/models/voice-session.model.ts`
- [Book segments](https://github.com/ishurana001/vox-tome-ai/blob/main/database/models/book-segment.model.ts): `database/models/book-segment.model.ts`
- [Books](https://github.com/ishurana001/vox-tome-ai/blob/main/database/models/book.model.ts): `database/models/book.model.ts`

### Other components

- **Reader**
- **Vercel Blob**
- **Vapi AI**
- **Clerk identity**
- **MongoDB**

## Connections

- Reader → Book library: browses
- Reader → Upload form: uploads
- Reader → Book workspace: opens
- Reader → Plan page: manages plan
- Book library → Library search: offers search
- Upload form → Upload authorization: requests upload
- Upload authorization → Clerk identity: checks identity
- Upload authorization → Vercel Blob: authorizes upload
- Voice controls → Voice session hook: controls
- Voice session hook → Vapi AI: starts call
- Vapi AI → Book search tool: calls tool
- Book search tool → Book actions: searches segments
- Book actions → Book segments: queries
- Voice session hook → Session actions: tracks session
- Session actions → Plan limits: checks limits
- Session actions → Voice sessions: creates and updates
- Voice sessions → MongoDB: persists
- Book segments → MongoDB: persists
- Books → MongoDB: persists