# ahmed-ali-313/hackathon-i-physical-ai-humanoid-robotics-textbook architecture

> Architecture diagram of the GitHub repository ahmed-ali-313/hackathon-i-physical-ai-humanoid-robotics-textbook, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ahmed-ali-313/hackathon-i-physical-ai-humanoid-robotics-textbook
- Repository: https://github.com/ahmed-ali-313/hackathon-i-physical-ai-humanoid-robotics-textbook

## Overview

AI-Native Textbook combines chapter reading with contextual RAG assistance, Urdu translation, and personalized accounts. A learner reads the textbook, can select a passage or ask a question, and receives an attributed response; translation and account preferences form parallel learning-support workflows. The backend also handles conversation persistence and semantic retrieval. The README documents major integrations and capabilities, but several route and service implementations were not sampled, so uncertain internal calls are omitted.

Main entry points: [`backend/src/main.py`](https://github.com/ahmed-ali-313/hackathon-i-physical-ai-humanoid-robotics-textbook/blob/006-production-deployment/backend/src/main.py) (API application), [`backend/src/services/agent_service.py`](https://github.com/ahmed-ali-313/hackathon-i-physical-ai-humanoid-robotics-textbook/blob/006-production-deployment/backend/src/services/agent_service.py) (RAG agent), [`backend/src/api/chat.py`](https://github.com/ahmed-ali-313/hackathon-i-physical-ai-humanoid-robotics-textbook/blob/006-production-deployment/backend/src/api/chat.py) (Chat endpoints), [`backend/src/database.py`](https://github.com/ahmed-ali-313/hackathon-i-physical-ai-humanoid-robotics-textbook/blob/006-production-deployment/backend/src/database.py) (Application database)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_learning_ui["Textbook experience"]
  node_textbook["Textbook site<br/>[Root.tsx]"]
  node_chat_ui["Chat panel<br/>[index.tsx]"]
  node_selection["Passage selection"]
  node_translation_ui["Translation control<br/>[index.tsx]"]
  node_profile_ui["Profile settings<br/>[profile.tsx]"]
end

subgraph group_client_state["Frontend workflows"]
  node_chat_state["Chat workflow<br/>[useChat.ts]"]
  node_chat_api["Chat client<br/>[chatApi.ts]"]
  node_translation_state["Translation workflow<br/>[useTranslation.ts]"]
  node_translation_api["Translation client<br/>[translationApi.ts]"]
  node_auth_ui["Authentication UI<br/>[AuthContext.tsx]"]
  node_preference_api["Preferences client"]
end

subgraph group_api["Backend API"]
  node_app["API application<br/>[main.py]"]
  node_chat_routes["Chat endpoints<br/>[chat.py]"]
  node_content_routes["Content endpoints<br/>[content.py]"]
  node_translation_routes["Translation endpoints<br/>[translation.py]"]
  node_auth_routes["Auth endpoints<br/>[auth.py]"]
  node_preferences_routes["Preference endpoints<br/>[preferences.py]"]
  node_auth_service["Authentication service<br/>[auth_service.py]"]
end

subgraph group_ai["AI services"]
  node_chat_service["Chat service<br/>[chat_service.py]"]
  node_agent["RAG agent<br/>[agent_service.py]"]
  node_vector_tool["Vector search tool"]
  node_context_tool["Context formatting"]
  node_embedding["Embedding service"]
  node_translation_service["Translation service"]
end

subgraph group_persistence["Data and integrations"]
  node_database[("Application database<br/>[database.py]")]
  node_chat_models["Chat records<br/>[conversation.py]"]
  node_user_model["User records<br/>[user.py]"]
  node_translation_cache["Translation cache"]
  node_qdrant[("Qdrant vectors")]
  node_openai["OpenAI API"]
end

node_learner(("Learner"))

node_learner -->|"reads chapters"| node_textbook
node_learner -->|"asks questions"| node_chat_ui
node_textbook -->|"captures passage"| node_selection
node_selection -->|"supplies selection"| node_chat_state
node_chat_ui -->|"manages chat"| node_chat_state
node_chat_state -->|"requests chat data"| node_chat_api
node_chat_api -->|"calls chat API"| node_chat_routes
node_app -->|"registers router"| node_chat_routes
node_app -->|"registers routers"| node_translation_routes
node_app -->|"registers routers"| node_auth_routes
node_app -->|"registers routers"| node_preferences_routes
node_app -->|"registers routers"| node_content_routes
node_chat_routes -->|"handles chat"| node_chat_service
node_chat_service -->|"orchestrates responses"| node_agent
node_agent -->|"searches chunks"| node_vector_tool
node_agent -->|"formats results"| node_context_tool
node_vector_tool -->|"searches vectors"| node_qdrant
node_agent -->|"generates answers"| node_openai
node_embedding -->|"creates embeddings"| node_openai
node_context_tool -->|"formats sources"| node_chat_service
node_chat_routes -->|"persists conversations"| node_chat_models
node_chat_models -->|"stores records"| node_database
node_learner -->|"requests translation"| node_translation_ui
node_translation_ui -->|"toggles language"| node_translation_state
node_translation_state -->|"requests chapter"| node_translation_api
node_translation_api -->|"calls translation API"| node_translation_routes
node_translation_routes -->|"translates chapters"| node_translation_service
node_translation_service -->|"checks translation"| node_translation_cache
node_translation_cache -->|"stores translations"| node_database
node_learner -->|"manages account"| node_profile_ui
node_profile_ui -->|"uses account state"| node_auth_ui
node_auth_ui -->|"authenticates"| node_auth_routes
node_auth_routes -->|"verifies credentials"| node_auth_service
node_auth_service -->|"loads user"| node_user_model
node_user_model -->|"stores account"| node_database
node_profile_ui -->|"updates preferences"| node_preference_api
node_preference_api -->|"calls preferences API"| node_preferences_routes
node_preferences_routes -->|"persists preferences"| node_database

click node_textbook "https://github.com/ahmed-ali-313/hackathon-i-physical-ai-humanoid-robotics-textbook/blob/006-production-deployment/textbook/src/theme/Root.tsx"
click node_chat_ui "https://github.com/ahmed-ali-313/hackathon-i-physical-ai-humanoid-robotics-textbook/blob/006-production-deployment/textbook/src/components/ChatPanel/index.tsx"
click node_selection "https://github.com/ahmed-ali-313/hackathon-i-physical-ai-humanoid-robotics-textbook/blob/006-production-deployment/textbook/src/hooks/useTextSelection.ts"
click node_translation_ui "https://github.com/ahmed-ali-313/hackathon-i-physical-ai-humanoid-robotics-textbook/blob/006-production-deployment/textbook/src/components/TranslationControl/index.tsx"
click node_profile_ui "https://github.com/ahmed-ali-313/hackathon-i-physical-ai-humanoid-robotics-textbook/blob/006-production-deployment/textbook/src/pages/profile.tsx"
click node_chat_state "https://github.com/ahmed-ali-313/hackathon-i-physical-ai-humanoid-robotics-textbook/blob/006-production-deployment/textbook/src/hooks/useChat.ts"
click node_chat_api "https://github.com/ahmed-ali-313/hackathon-i-physical-ai-humanoid-robotics-textbook/blob/006-production-deployment/textbook/src/services/chatApi.ts"
click node_translation_state "https://github.com/ahmed-ali-313/hackathon-i-physical-ai-humanoid-robotics-textbook/blob/006-production-deployment/textbook/src/hooks/useTranslation.ts"
click node_translation_api "https://github.com/ahmed-ali-313/hackathon-i-physical-ai-humanoid-robotics-textbook/blob/006-production-deployment/textbook/src/services/translationApi.ts"
click node_auth_ui "https://github.com/ahmed-ali-313/hackathon-i-physical-ai-humanoid-robotics-textbook/blob/006-production-deployment/textbook/src/contexts/AuthContext.tsx"
click node_preference_api "https://github.com/ahmed-ali-313/hackathon-i-physical-ai-humanoid-robotics-textbook/blob/006-production-deployment/textbook/src/services/personalizationApi.ts"
click node_app "https://github.com/ahmed-ali-313/hackathon-i-physical-ai-humanoid-robotics-textbook/blob/006-production-deployment/backend/src/main.py"
click node_chat_routes "https://github.com/ahmed-ali-313/hackathon-i-physical-ai-humanoid-robotics-textbook/blob/006-production-deployment/backend/src/api/chat.py"
click node_content_routes "https://github.com/ahmed-ali-313/hackathon-i-physical-ai-humanoid-robotics-textbook/blob/006-production-deployment/backend/src/api/content.py"
click node_translation_routes "https://github.com/ahmed-ali-313/hackathon-i-physical-ai-humanoid-robotics-textbook/blob/006-production-deployment/backend/src/api/translation.py"
click node_auth_routes "https://github.com/ahmed-ali-313/hackathon-i-physical-ai-humanoid-robotics-textbook/blob/006-production-deployment/backend/src/api/auth.py"
click node_preferences_routes "https://github.com/ahmed-ali-313/hackathon-i-physical-ai-humanoid-robotics-textbook/blob/006-production-deployment/backend/src/api/preferences.py"
click node_chat_service "https://github.com/ahmed-ali-313/hackathon-i-physical-ai-humanoid-robotics-textbook/blob/006-production-deployment/backend/src/services/chat_service.py"
click node_agent "https://github.com/ahmed-ali-313/hackathon-i-physical-ai-humanoid-robotics-textbook/blob/006-production-deployment/backend/src/services/agent_service.py"
click node_vector_tool "https://github.com/ahmed-ali-313/hackathon-i-physical-ai-humanoid-robotics-textbook/blob/006-production-deployment/backend/src/tools/vector_search_tool.py"
click node_context_tool "https://github.com/ahmed-ali-313/hackathon-i-physical-ai-humanoid-robotics-textbook/blob/006-production-deployment/backend/src/tools/retrieve_context_tool.py"
click node_embedding "https://github.com/ahmed-ali-313/hackathon-i-physical-ai-humanoid-robotics-textbook/blob/006-production-deployment/backend/src/services/embedding_service.py"
click node_translation_service "https://github.com/ahmed-ali-313/hackathon-i-physical-ai-humanoid-robotics-textbook/blob/006-production-deployment/backend/src/services/translation_service.py"
click node_auth_service "https://github.com/ahmed-ali-313/hackathon-i-physical-ai-humanoid-robotics-textbook/blob/006-production-deployment/backend/src/services/auth_service.py"
click node_database "https://github.com/ahmed-ali-313/hackathon-i-physical-ai-humanoid-robotics-textbook/blob/006-production-deployment/backend/src/database.py"
click node_chat_models "https://github.com/ahmed-ali-313/hackathon-i-physical-ai-humanoid-robotics-textbook/blob/006-production-deployment/backend/src/models/conversation.py"
click node_user_model "https://github.com/ahmed-ali-313/hackathon-i-physical-ai-humanoid-robotics-textbook/blob/006-production-deployment/backend/src/models/user.py"
click node_translation_cache "https://github.com/ahmed-ali-313/hackathon-i-physical-ai-humanoid-robotics-textbook/blob/006-production-deployment/backend/src/services/translation_cache_service.py"

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_textbook,node_chat_ui,node_selection,node_translation_ui,node_profile_ui toneBlue
class node_chat_state,node_chat_api,node_translation_state,node_translation_api,node_auth_ui,node_preference_api toneAmber
class node_app,node_chat_routes,node_content_routes,node_translation_routes,node_auth_routes,node_preferences_routes,node_auth_service toneMint
class node_chat_service,node_agent,node_vector_tool,node_context_tool,node_embedding,node_translation_service toneRose
class node_database,node_chat_models,node_user_model,node_translation_cache,node_qdrant,node_openai,node_learner toneIndigo
```

## Components

### Textbook experience

- [Textbook site](https://github.com/ahmed-ali-313/hackathon-i-physical-ai-humanoid-robotics-textbook/blob/006-production-deployment/textbook/src/theme/Root.tsx): `textbook/src/theme/Root.tsx`
- [Chat panel](https://github.com/ahmed-ali-313/hackathon-i-physical-ai-humanoid-robotics-textbook/blob/006-production-deployment/textbook/src/components/ChatPanel/index.tsx): `textbook/src/components/ChatPanel/index.tsx`
- [Passage selection](https://github.com/ahmed-ali-313/hackathon-i-physical-ai-humanoid-robotics-textbook/blob/006-production-deployment/textbook/src/hooks/useTextSelection.ts): `textbook/src/hooks/useTextSelection.ts`
- [Translation control](https://github.com/ahmed-ali-313/hackathon-i-physical-ai-humanoid-robotics-textbook/blob/006-production-deployment/textbook/src/components/TranslationControl/index.tsx): `textbook/src/components/TranslationControl/index.tsx`
- [Profile settings](https://github.com/ahmed-ali-313/hackathon-i-physical-ai-humanoid-robotics-textbook/blob/006-production-deployment/textbook/src/pages/profile.tsx): `textbook/src/pages/profile.tsx`

### Frontend workflows

- [Chat workflow](https://github.com/ahmed-ali-313/hackathon-i-physical-ai-humanoid-robotics-textbook/blob/006-production-deployment/textbook/src/hooks/useChat.ts): `textbook/src/hooks/useChat.ts`
- [Chat client](https://github.com/ahmed-ali-313/hackathon-i-physical-ai-humanoid-robotics-textbook/blob/006-production-deployment/textbook/src/services/chatApi.ts): `textbook/src/services/chatApi.ts`
- [Translation workflow](https://github.com/ahmed-ali-313/hackathon-i-physical-ai-humanoid-robotics-textbook/blob/006-production-deployment/textbook/src/hooks/useTranslation.ts): `textbook/src/hooks/useTranslation.ts`
- [Translation client](https://github.com/ahmed-ali-313/hackathon-i-physical-ai-humanoid-robotics-textbook/blob/006-production-deployment/textbook/src/services/translationApi.ts): `textbook/src/services/translationApi.ts`
- [Authentication UI](https://github.com/ahmed-ali-313/hackathon-i-physical-ai-humanoid-robotics-textbook/blob/006-production-deployment/textbook/src/contexts/AuthContext.tsx): `textbook/src/contexts/AuthContext.tsx`
- [Preferences client](https://github.com/ahmed-ali-313/hackathon-i-physical-ai-humanoid-robotics-textbook/blob/006-production-deployment/textbook/src/services/personalizationApi.ts): `textbook/src/services/personalizationApi.ts`

### Backend API

- [API application](https://github.com/ahmed-ali-313/hackathon-i-physical-ai-humanoid-robotics-textbook/blob/006-production-deployment/backend/src/main.py): `backend/src/main.py`
- [Chat endpoints](https://github.com/ahmed-ali-313/hackathon-i-physical-ai-humanoid-robotics-textbook/blob/006-production-deployment/backend/src/api/chat.py): `backend/src/api/chat.py`
- [Content endpoints](https://github.com/ahmed-ali-313/hackathon-i-physical-ai-humanoid-robotics-textbook/blob/006-production-deployment/backend/src/api/content.py): `backend/src/api/content.py`
- [Translation endpoints](https://github.com/ahmed-ali-313/hackathon-i-physical-ai-humanoid-robotics-textbook/blob/006-production-deployment/backend/src/api/translation.py): `backend/src/api/translation.py`
- [Auth endpoints](https://github.com/ahmed-ali-313/hackathon-i-physical-ai-humanoid-robotics-textbook/blob/006-production-deployment/backend/src/api/auth.py): `backend/src/api/auth.py`
- [Preference endpoints](https://github.com/ahmed-ali-313/hackathon-i-physical-ai-humanoid-robotics-textbook/blob/006-production-deployment/backend/src/api/preferences.py): `backend/src/api/preferences.py`
- [Authentication service](https://github.com/ahmed-ali-313/hackathon-i-physical-ai-humanoid-robotics-textbook/blob/006-production-deployment/backend/src/services/auth_service.py): `backend/src/services/auth_service.py`

### AI services

- [Chat service](https://github.com/ahmed-ali-313/hackathon-i-physical-ai-humanoid-robotics-textbook/blob/006-production-deployment/backend/src/services/chat_service.py): `backend/src/services/chat_service.py`
- [RAG agent](https://github.com/ahmed-ali-313/hackathon-i-physical-ai-humanoid-robotics-textbook/blob/006-production-deployment/backend/src/services/agent_service.py): `backend/src/services/agent_service.py`
- [Vector search tool](https://github.com/ahmed-ali-313/hackathon-i-physical-ai-humanoid-robotics-textbook/blob/006-production-deployment/backend/src/tools/vector_search_tool.py): `backend/src/tools/vector_search_tool.py`
- [Context formatting](https://github.com/ahmed-ali-313/hackathon-i-physical-ai-humanoid-robotics-textbook/blob/006-production-deployment/backend/src/tools/retrieve_context_tool.py): `backend/src/tools/retrieve_context_tool.py`
- [Embedding service](https://github.com/ahmed-ali-313/hackathon-i-physical-ai-humanoid-robotics-textbook/blob/006-production-deployment/backend/src/services/embedding_service.py): `backend/src/services/embedding_service.py`
- [Translation service](https://github.com/ahmed-ali-313/hackathon-i-physical-ai-humanoid-robotics-textbook/blob/006-production-deployment/backend/src/services/translation_service.py): `backend/src/services/translation_service.py`

### Data and integrations

- [Application database](https://github.com/ahmed-ali-313/hackathon-i-physical-ai-humanoid-robotics-textbook/blob/006-production-deployment/backend/src/database.py): `backend/src/database.py`
- [Chat records](https://github.com/ahmed-ali-313/hackathon-i-physical-ai-humanoid-robotics-textbook/blob/006-production-deployment/backend/src/models/conversation.py): `backend/src/models/conversation.py`
- [User records](https://github.com/ahmed-ali-313/hackathon-i-physical-ai-humanoid-robotics-textbook/blob/006-production-deployment/backend/src/models/user.py): `backend/src/models/user.py`
- [Translation cache](https://github.com/ahmed-ali-313/hackathon-i-physical-ai-humanoid-robotics-textbook/blob/006-production-deployment/backend/src/services/translation_cache_service.py): `backend/src/services/translation_cache_service.py`
- **Qdrant vectors**
- **OpenAI API**

### Other components

- **Learner**

## Connections

- Learner → Textbook site: reads chapters
- Learner → Chat panel: asks questions
- Textbook site → Passage selection: captures passage
- Passage selection → Chat workflow: supplies selection
- Chat panel → Chat workflow: manages chat
- Chat workflow → Chat client: requests chat data
- Chat client → Chat endpoints: calls chat API
- API application → Chat endpoints: registers router
- API application → Translation endpoints: registers routers
- API application → Auth endpoints: registers routers
- API application → Preference endpoints: registers routers
- API application → Content endpoints: registers routers
- Chat endpoints → Chat service: handles chat
- Chat service → RAG agent: orchestrates responses
- RAG agent → Vector search tool: searches chunks
- RAG agent → Context formatting: formats results
- Vector search tool → Qdrant vectors: searches vectors
- RAG agent → OpenAI API: generates answers
- Embedding service → OpenAI API: creates embeddings
- Context formatting → Chat service: formats sources
- Chat endpoints → Chat records: persists conversations
- Chat records → Application database: stores records
- Learner → Translation control: requests translation
- Translation control → Translation workflow: toggles language
- Translation workflow → Translation client: requests chapter
- Translation client → Translation endpoints: calls translation API
- Translation endpoints → Translation service: translates chapters
- Translation service → Translation cache: checks translation
- Translation cache → Application database: stores translations
- Learner → Profile settings: manages account
- Profile settings → Authentication UI: uses account state
- Authentication UI → Auth endpoints: authenticates
- Auth endpoints → Authentication service: verifies credentials
- Authentication service → User records: loads user
- User records → Application database: stores account
- Profile settings → Preferences client: updates preferences
- Preferences client → Preference endpoints: calls preferences API
- Preference endpoints → Application database: persists preferences