# musabj1917-oss/verbose-ai architecture

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

- Interactive diagram: https://gitdiagram.com/musabj1917-oss/verbose-ai
- Repository: https://github.com/musabj1917-oss/verbose-ai

## Overview

Verbose AI is a book-reading and comprehension platform: readers ask questions or take book-derived quizzes, with answers grounded in retrieved passages and citations. Admins can curate books through the web console or CLI; embeddings enable semantic retrieval in pgvector. The PHP app also exposes an MCP interface for external clients. The graph follows documented capabilities and shown routing/import/call relationships; unsampled reader-to-API and provider details are left out where the excerpts do not establish wiring.

Main entry points: [`public/api.php`](https://github.com/musabj1917-oss/verbose-ai/blob/main/public/api.php) (Application API), [`src/Embedder.php`](https://github.com/musabj1917-oss/verbose-ai/blob/main/src/Embedder.php) (Text embeddings), [`src/Database.php`](https://github.com/musabj1917-oss/verbose-ai/blob/main/src/Database.php) (Database access), [`public/index.php`](https://github.com/musabj1917-oss/verbose-ai/blob/main/public/index.php) (Web router)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Reader and web app"]
  node_reader["Reading interface<br/>[reader.php]"]
  node_browser["Reader interactions<br/>[app.js]"]
  node_router["Web router<br/>[index.php]"]
  node_auth["Authentication page<br/>[auth.php]"]
  node_api["Application API<br/>[api.php]"]
end

subgraph group_knowledge["Book knowledge"]
  node_book["Book retrieval<br/>[BookService.php]"]
  node_embed["Text embeddings<br/>[Embedder.php]"]
  node_db["Database access<br/>[Database.php]"]
  node_store[("Neon Postgres")]
end

subgraph group_intelligence["Grounded AI"]
  node_ai["Grounded AI service<br/>[AIService.php]"]
  node_models["AI model providers"]
end

subgraph group_operations["Admin and integrations"]
  node_admin["Admin console<br/>[admin.php]"]
  node_ingest["CLI ingestion<br/>[ingest.php]"]
  node_mcp_http["MCP HTTP endpoint<br/>[mcp.php]"]
  node_mcp["MCP service<br/>[MCPService.php]"]
end

node_mcp_client(("MCP clients"))
node_reader_user(("Reader"))
node_admin_user(("Administrator"))

node_reader_user -->|"opens app"| node_router
node_router -->|"renders login"| node_auth
node_router -->|"renders reader"| node_reader
node_router -->|"routes API"| node_api
node_router -->|"routes MCP"| node_mcp_http
node_auth -->|"authenticates via"| node_api
node_admin_user -.->|"manages books"| node_admin
node_admin -->|"reads database"| node_db
node_admin -.->|"shows embedding status"| node_embed
node_api -->|"retrieves passages"| node_book
node_api -->|"requests answers"| node_ai
node_api -->|"embeds content"| node_embed
node_api -->|"accesses database"| node_db
node_book -->|"embeds queries"| node_embed
node_book -->|"queries chunks"| node_db
node_embed -->|"requests vectors"| node_models
node_db -->|"connects to"| node_store
node_ai -->|"generates responses"| node_models
node_ingest -->|"embeds chunks"| node_embed
node_ingest -->|"stores books"| node_db
node_mcp_client -->|"sends JSON-RPC"| node_mcp_http
node_mcp_http -->|"dispatches requests"| node_mcp
node_mcp -->|"uses retrieval"| node_book
node_mcp -->|"uses grounded AI"| node_ai
node_mcp -->|"backfills vectors"| node_embed
node_mcp -->|"accesses database"| node_db

click node_reader "https://github.com/musabj1917-oss/verbose-ai/blob/main/templates/reader.php"
click node_browser "https://github.com/musabj1917-oss/verbose-ai/blob/main/public/js/app.js"
click node_router "https://github.com/musabj1917-oss/verbose-ai/blob/main/public/index.php"
click node_auth "https://github.com/musabj1917-oss/verbose-ai/blob/main/templates/auth.php"
click node_api "https://github.com/musabj1917-oss/verbose-ai/blob/main/public/api.php"
click node_admin "https://github.com/musabj1917-oss/verbose-ai/blob/main/templates/admin.php"
click node_ingest "https://github.com/musabj1917-oss/verbose-ai/blob/main/bin/ingest.php"
click node_book "https://github.com/musabj1917-oss/verbose-ai/blob/main/src/BookService.php"
click node_embed "https://github.com/musabj1917-oss/verbose-ai/blob/main/src/Embedder.php"
click node_db "https://github.com/musabj1917-oss/verbose-ai/blob/main/src/Database.php"
click node_ai "https://github.com/musabj1917-oss/verbose-ai/blob/main/src/AIService.php"
click node_mcp_http "https://github.com/musabj1917-oss/verbose-ai/blob/main/public/mcp.php"
click node_mcp "https://github.com/musabj1917-oss/verbose-ai/blob/main/src/MCPService.php"

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_reader,node_browser,node_router,node_auth,node_api,node_mcp_client toneBlue
class node_book,node_embed,node_db,node_store toneAmber
class node_ai,node_models toneMint
class node_admin,node_ingest,node_mcp_http,node_mcp toneRose
class node_reader_user,node_admin_user toneIndigo
```

## Components

### Reader and web app

- [Reading interface](https://github.com/musabj1917-oss/verbose-ai/blob/main/templates/reader.php): `templates/reader.php`
- [Reader interactions](https://github.com/musabj1917-oss/verbose-ai/blob/main/public/js/app.js): `public/js/app.js`
- [Web router](https://github.com/musabj1917-oss/verbose-ai/blob/main/public/index.php): `public/index.php`
- [Authentication page](https://github.com/musabj1917-oss/verbose-ai/blob/main/templates/auth.php): `templates/auth.php`
- [Application API](https://github.com/musabj1917-oss/verbose-ai/blob/main/public/api.php): `public/api.php`

### Book knowledge

- [Book retrieval](https://github.com/musabj1917-oss/verbose-ai/blob/main/src/BookService.php): `src/BookService.php`
- [Text embeddings](https://github.com/musabj1917-oss/verbose-ai/blob/main/src/Embedder.php): `src/Embedder.php`
- [Database access](https://github.com/musabj1917-oss/verbose-ai/blob/main/src/Database.php): `src/Database.php`
- **Neon Postgres**

### Grounded AI

- [Grounded AI service](https://github.com/musabj1917-oss/verbose-ai/blob/main/src/AIService.php): `src/AIService.php`
- **AI model providers**

### Admin and integrations

- [Admin console](https://github.com/musabj1917-oss/verbose-ai/blob/main/templates/admin.php): `templates/admin.php`
- [CLI ingestion](https://github.com/musabj1917-oss/verbose-ai/blob/main/bin/ingest.php): `bin/ingest.php`
- [MCP HTTP endpoint](https://github.com/musabj1917-oss/verbose-ai/blob/main/public/mcp.php): `public/mcp.php`
- [MCP service](https://github.com/musabj1917-oss/verbose-ai/blob/main/src/MCPService.php): `src/MCPService.php`

### Other components

- **MCP clients**
- **Reader**
- **Administrator**

## Connections

- Reader → Web router: opens app (evidence: `public/index.php`)
- Web router → Authentication page: renders login (evidence: `public/index.php`)
- Web router → Reading interface: renders reader (evidence: `public/index.php`)
- Web router → Application API: routes API (evidence: `public/index.php`)
- Web router → MCP HTTP endpoint: routes MCP (evidence: `public/index.php`)
- Authentication page → Application API: authenticates via (evidence: `templates/auth.php`)
- Administrator → Admin console: manages books (evidence: `README.md`)
- Admin console → Database access: reads database (evidence: `templates/admin.php`)
- Admin console → Text embeddings: shows embedding status
- Application API → Book retrieval: retrieves passages (evidence: `public/api.php`)
- Application API → Grounded AI service: requests answers (evidence: `public/api.php`)
- Application API → Text embeddings: embeds content (evidence: `public/api.php`)
- Application API → Database access: accesses database (evidence: `public/api.php`)
- Book retrieval → Text embeddings: embeds queries (evidence: `src/BookService.php`)
- Book retrieval → Database access: queries chunks (evidence: `src/BookService.php`)
- Text embeddings → AI model providers: requests vectors (evidence: `src/Embedder.php`)
- Database access → Neon Postgres: connects to (evidence: `src/Database.php`)
- Grounded AI service → AI model providers: generates responses (evidence: `src/AIService.php`)
- CLI ingestion → Text embeddings: embeds chunks (evidence: `bin/ingest.php`)
- CLI ingestion → Database access: stores books (evidence: `bin/ingest.php`)
- MCP clients → MCP HTTP endpoint: sends JSON-RPC (evidence: `README.md`)
- MCP HTTP endpoint → MCP service: dispatches requests (evidence: `public/mcp.php`)
- MCP service → Book retrieval: uses retrieval (evidence: `src/MCPService.php`)
- MCP service → Grounded AI service: uses grounded AI (evidence: `src/MCPService.php`)
- MCP service → Text embeddings: backfills vectors (evidence: `src/MCPService.php`)
- MCP service → Database access: accesses database (evidence: `src/MCPService.php`)
