# igortuchel/sfe-ai-coursework architecture

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

- Interactive diagram: https://gitdiagram.com/igortuchel/sfe-ai-coursework
- Repository: https://github.com/igortuchel/sfe-ai-coursework

## Overview

Historical Chatbot is a React/Express application for chatting with historically grounded character personas, managing accounts, and authoring characters and their RAG data. The main user flow runs from the chat interface through message submission to a backend handler that selects scripted or Gemini-backed responses, retrieves character context, and persists chat state. The README also documents authentication, session controls, character authoring, and image generation. Some backend route wiring and unsampled modules are represented only where the README or source index supports the relationship.

Main entry points: [`frontend/src/lib/api.js`](https://github.com/igortuchel/sfe-ai-coursework/blob/main/frontend/src/lib/api.js) (HTTP client), [`backend/src/handlers/handlerSendChatMessage.js`](https://github.com/igortuchel/sfe-ai-coursework/blob/main/backend/src/handlers/handlerSendChatMessage.js) (Message handler), [`frontend/src/App.jsx`](https://github.com/igortuchel/sfe-ai-coursework/blob/main/frontend/src/App.jsx) (Page router), [`backend/src/routes/userRoutes.js`](https://github.com/igortuchel/sfe-ai-coursework/blob/main/backend/src/routes/userRoutes.js) (User routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web experience"]
  node_app["Page router<br/>[App.jsx]"]
  node_chat_ui["Chat interface<br/>[ChatPage.jsx]"]
  node_chat_hook["Chat state<br/>[useChatMessages.js]"]
  node_character_ui["Character editor"]
  node_settings_ui["Account settings<br/>[UserSettings.jsx]"]
  node_auth_context["Auth state<br/>[AuthContext.jsx]"]
  node_web_api["HTTP client<br/>[api.js]"]
  node_chat_services["Chat API services"]
  node_character_services["Character API services"]
  node_settings_hook["Settings actions<br/>[useUserSettings.js]"]
end

subgraph group_api["API and identity"]
  node_user_routes["User routes<br/>[userRoutes.js]"]
  node_character_routes["Character routes<br/>[characterRoutes.js]"]
  node_auth_middleware["Auth and roles"]
  node_login_handler["Login and signup<br/>[handlerLogIn.js]"]
  node_session_handler["Session revocation"]
end

subgraph group_chat["Conversation intelligence"]
  node_chat_handler["Message handler"]
  node_json_engine["Script matcher<br/>[jsonEngine.js]"]
  node_context_manager["Conversation context<br/>[contextManager.js]"]
  node_rag_search["RAG retrieval"]
  node_gemini["Gemini services"]
end

subgraph group_characters["Character authoring"]
  node_character_cache["Character context cache"]
  node_character_handlers["Character management"]
  node_vector_handlers["Character RAG data"]
end

subgraph group_data["Persistence and integrations"]
  node_chat_store[("Chat records<br/>[chatModel.js]")]
  node_character_store[("Character records<br/>[characterModel.js]")]
  node_vector_store[("Vector records")]
  node_user_store[("User records<br/>[usersModel.js]")]
  node_context_store[("Context records")]
  node_redis[("Redis cache<br/>[redis.js]")]
  node_image_storage["Image storage<br/>[putObjectS3.js]"]
  node_email_service["Email delivery<br/>[sendEmail.js]"]
end

node_visitor(("Visitor or user"))
node_external_ai{{"Google Gemini"}}
node_external_storage{{"AWS S3"}}

node_visitor -->|"opens"| node_app
node_app -->|"routes to"| node_chat_ui
node_app -->|"routes to"| node_character_ui
node_app -->|"routes to"| node_settings_ui
node_chat_ui -->|"uses"| node_chat_hook
node_chat_hook -->|"calls"| node_chat_services
node_character_ui -->|"uses"| node_character_services
node_settings_ui -->|"uses"| node_settings_hook
node_settings_hook -->|"calls via"| node_web_api
node_auth_context -->|"checks session"| node_web_api
node_chat_services -->|"sends requests"| node_web_api
node_character_services -->|"sends requests"| node_web_api
node_web_api -.->|"calls API"| node_user_routes
node_web_api -.->|"calls API"| node_character_routes
node_user_routes -->|"guards routes"| node_auth_middleware
node_user_routes -->|"dispatches login"| node_login_handler
node_user_routes -->|"dispatches revocation"| node_session_handler
node_character_routes -->|"guards routes"| node_auth_middleware
node_character_routes -->|"dispatches"| node_character_handlers
node_character_routes -->|"dispatches"| node_vector_handlers
node_chat_handler -->|"matches scripts"| node_json_engine
node_chat_handler -->|"loads context"| node_context_manager
node_chat_handler -->|"retrieves grounding"| node_rag_search
node_chat_handler -->|"requests response"| node_gemini
node_context_manager -->|"reads and updates"| node_context_store
node_context_manager -->|"caches context"| node_redis
node_context_manager -->|"summarizes"| node_external_ai
node_rag_search -->|"searches"| node_vector_store
node_gemini -->|"uses"| node_external_ai
node_character_cache -->|"loads character"| node_character_store
node_character_cache -->|"caches character"| node_redis
node_character_handlers -->|"manages"| node_character_store
node_character_handlers -->|"uploads images"| node_image_storage
node_image_storage -->|"stores objects"| node_external_storage
node_vector_handlers -->|"manages data"| node_vector_store
node_login_handler -->|"checks account"| node_user_store
node_session_handler -.->|"revokes sessions"| node_user_store
node_login_handler -.->|"sends MFA code"| node_email_service
node_email_service -.->|"delivers email"| node_visitor
node_chat_handler -->|"persists messages"| node_chat_store

click node_app "https://github.com/igortuchel/sfe-ai-coursework/blob/main/frontend/src/App.jsx"
click node_chat_ui "https://github.com/igortuchel/sfe-ai-coursework/blob/main/frontend/src/pages/ChatPage.jsx"
click node_chat_hook "https://github.com/igortuchel/sfe-ai-coursework/blob/main/frontend/src/hooks/useChatMessages.js"
click node_character_ui "https://github.com/igortuchel/sfe-ai-coursework/blob/main/frontend/src/pages/CreateCharacterPage.jsx"
click node_settings_ui "https://github.com/igortuchel/sfe-ai-coursework/blob/main/frontend/src/pages/UserSettings.jsx"
click node_auth_context "https://github.com/igortuchel/sfe-ai-coursework/blob/main/frontend/src/context/AuthContext.jsx"
click node_web_api "https://github.com/igortuchel/sfe-ai-coursework/blob/main/frontend/src/lib/api.js"
click node_chat_services "https://github.com/igortuchel/sfe-ai-coursework/tree/main/frontend/src/services"
click node_character_services "https://github.com/igortuchel/sfe-ai-coursework/tree/main/frontend/src/services"
click node_settings_hook "https://github.com/igortuchel/sfe-ai-coursework/blob/main/frontend/src/hooks/useUserSettings.js"
click node_user_routes "https://github.com/igortuchel/sfe-ai-coursework/blob/main/backend/src/routes/userRoutes.js"
click node_character_routes "https://github.com/igortuchel/sfe-ai-coursework/blob/main/backend/src/routes/characterRoutes.js"
click node_auth_middleware "https://github.com/igortuchel/sfe-ai-coursework/blob/main/backend/src/middleware/authenticatedRouteMiddleware.js"
click node_login_handler "https://github.com/igortuchel/sfe-ai-coursework/blob/main/backend/src/handlers/handlerLogIn.js"
click node_session_handler "https://github.com/igortuchel/sfe-ai-coursework/blob/main/backend/src/handlers/handlerInvalidateOtherSessions.js"
click node_chat_handler "https://github.com/igortuchel/sfe-ai-coursework/blob/main/backend/src/handlers/handlerSendChatMessage.js"
click node_json_engine "https://github.com/igortuchel/sfe-ai-coursework/blob/main/backend/src/utils/jsonEngine.js"
click node_context_manager "https://github.com/igortuchel/sfe-ai-coursework/blob/main/backend/src/services/contextManager.js"
click node_rag_search "https://github.com/igortuchel/sfe-ai-coursework/blob/main/backend/src/services/mongoSearchQuery.js"
click node_gemini "https://github.com/igortuchel/sfe-ai-coursework/tree/main/backend/src/services"
click node_character_cache "https://github.com/igortuchel/sfe-ai-coursework/blob/main/backend/src/services/characterContextManager.js"
click node_character_handlers "https://github.com/igortuchel/sfe-ai-coursework/tree/main/backend/src/handlers"
click node_vector_handlers "https://github.com/igortuchel/sfe-ai-coursework/tree/main/backend/src/handlers"
click node_chat_store "https://github.com/igortuchel/sfe-ai-coursework/blob/main/backend/src/models/chatModel.js"
click node_character_store "https://github.com/igortuchel/sfe-ai-coursework/blob/main/backend/src/models/characterModel.js"
click node_vector_store "https://github.com/igortuchel/sfe-ai-coursework/blob/main/backend/src/models/characterVectorDataStore.js"
click node_user_store "https://github.com/igortuchel/sfe-ai-coursework/blob/main/backend/src/models/usersModel.js"
click node_context_store "https://github.com/igortuchel/sfe-ai-coursework/blob/main/backend/src/models/chatContextModel.js"
click node_redis "https://github.com/igortuchel/sfe-ai-coursework/blob/main/backend/src/config/redis.js"
click node_image_storage "https://github.com/igortuchel/sfe-ai-coursework/blob/main/backend/src/services/putObjectS3.js"
click node_email_service "https://github.com/igortuchel/sfe-ai-coursework/blob/main/backend/src/services/sendEmail.js"

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_app,node_chat_ui,node_chat_hook,node_character_ui,node_settings_ui,node_auth_context,node_web_api,node_chat_services,node_character_services,node_settings_hook,node_visitor toneBlue
class node_user_routes,node_character_routes,node_auth_middleware,node_login_handler,node_session_handler toneAmber
class node_chat_handler,node_json_engine,node_context_manager,node_rag_search,node_gemini toneMint
class node_character_cache,node_character_handlers,node_vector_handlers toneRose
class node_chat_store,node_character_store,node_vector_store,node_user_store,node_context_store,node_redis,node_image_storage,node_email_service,node_external_ai,node_external_storage toneIndigo
```

## Components

### Web experience

- [Page router](https://github.com/igortuchel/sfe-ai-coursework/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Chat interface](https://github.com/igortuchel/sfe-ai-coursework/blob/main/frontend/src/pages/ChatPage.jsx): `frontend/src/pages/ChatPage.jsx`
- [Chat state](https://github.com/igortuchel/sfe-ai-coursework/blob/main/frontend/src/hooks/useChatMessages.js): `frontend/src/hooks/useChatMessages.js`
- [Character editor](https://github.com/igortuchel/sfe-ai-coursework/blob/main/frontend/src/pages/CreateCharacterPage.jsx): `frontend/src/pages/CreateCharacterPage.jsx`
- [Account settings](https://github.com/igortuchel/sfe-ai-coursework/blob/main/frontend/src/pages/UserSettings.jsx): `frontend/src/pages/UserSettings.jsx`
- [Auth state](https://github.com/igortuchel/sfe-ai-coursework/blob/main/frontend/src/context/AuthContext.jsx): `frontend/src/context/AuthContext.jsx`
- [HTTP client](https://github.com/igortuchel/sfe-ai-coursework/blob/main/frontend/src/lib/api.js): `frontend/src/lib/api.js`
- [Chat API services](https://github.com/igortuchel/sfe-ai-coursework/tree/main/frontend/src/services): `frontend/src/services`
- [Character API services](https://github.com/igortuchel/sfe-ai-coursework/tree/main/frontend/src/services): `frontend/src/services`
- [Settings actions](https://github.com/igortuchel/sfe-ai-coursework/blob/main/frontend/src/hooks/useUserSettings.js): `frontend/src/hooks/useUserSettings.js`

### API and identity

- [User routes](https://github.com/igortuchel/sfe-ai-coursework/blob/main/backend/src/routes/userRoutes.js): `backend/src/routes/userRoutes.js`
- [Character routes](https://github.com/igortuchel/sfe-ai-coursework/blob/main/backend/src/routes/characterRoutes.js): `backend/src/routes/characterRoutes.js`
- [Auth and roles](https://github.com/igortuchel/sfe-ai-coursework/blob/main/backend/src/middleware/authenticatedRouteMiddleware.js): `backend/src/middleware/authenticatedRouteMiddleware.js`
- [Login and signup](https://github.com/igortuchel/sfe-ai-coursework/blob/main/backend/src/handlers/handlerLogIn.js): `backend/src/handlers/handlerLogIn.js`
- [Session revocation](https://github.com/igortuchel/sfe-ai-coursework/blob/main/backend/src/handlers/handlerInvalidateOtherSessions.js): `backend/src/handlers/handlerInvalidateOtherSessions.js`

### Conversation intelligence

- [Message handler](https://github.com/igortuchel/sfe-ai-coursework/blob/main/backend/src/handlers/handlerSendChatMessage.js): `backend/src/handlers/handlerSendChatMessage.js`
- [Script matcher](https://github.com/igortuchel/sfe-ai-coursework/blob/main/backend/src/utils/jsonEngine.js): `backend/src/utils/jsonEngine.js`
- [Conversation context](https://github.com/igortuchel/sfe-ai-coursework/blob/main/backend/src/services/contextManager.js): `backend/src/services/contextManager.js`
- [RAG retrieval](https://github.com/igortuchel/sfe-ai-coursework/blob/main/backend/src/services/mongoSearchQuery.js): `backend/src/services/mongoSearchQuery.js`
- [Gemini services](https://github.com/igortuchel/sfe-ai-coursework/tree/main/backend/src/services): `backend/src/services`

### Character authoring

- [Character context cache](https://github.com/igortuchel/sfe-ai-coursework/blob/main/backend/src/services/characterContextManager.js): `backend/src/services/characterContextManager.js`
- [Character management](https://github.com/igortuchel/sfe-ai-coursework/tree/main/backend/src/handlers): `backend/src/handlers`
- [Character RAG data](https://github.com/igortuchel/sfe-ai-coursework/tree/main/backend/src/handlers): `backend/src/handlers`

### Persistence and integrations

- [Chat records](https://github.com/igortuchel/sfe-ai-coursework/blob/main/backend/src/models/chatModel.js): `backend/src/models/chatModel.js`
- [Character records](https://github.com/igortuchel/sfe-ai-coursework/blob/main/backend/src/models/characterModel.js): `backend/src/models/characterModel.js`
- [Vector records](https://github.com/igortuchel/sfe-ai-coursework/blob/main/backend/src/models/characterVectorDataStore.js): `backend/src/models/characterVectorDataStore.js`
- [User records](https://github.com/igortuchel/sfe-ai-coursework/blob/main/backend/src/models/usersModel.js): `backend/src/models/usersModel.js`
- [Context records](https://github.com/igortuchel/sfe-ai-coursework/blob/main/backend/src/models/chatContextModel.js): `backend/src/models/chatContextModel.js`
- [Redis cache](https://github.com/igortuchel/sfe-ai-coursework/blob/main/backend/src/config/redis.js): `backend/src/config/redis.js`
- [Image storage](https://github.com/igortuchel/sfe-ai-coursework/blob/main/backend/src/services/putObjectS3.js): `backend/src/services/putObjectS3.js`
- [Email delivery](https://github.com/igortuchel/sfe-ai-coursework/blob/main/backend/src/services/sendEmail.js): `backend/src/services/sendEmail.js`

### Other components

- **Visitor or user**
- **Google Gemini**
- **AWS S3**

## Connections

- Visitor or user → Page router: opens
- Page router → Chat interface: routes to (evidence: `frontend/src/App.jsx`)
- Page router → Character editor: routes to (evidence: `frontend/src/App.jsx`)
- Page router → Account settings: routes to (evidence: `frontend/src/App.jsx`)
- Chat interface → Chat state: uses
- Chat state → Chat API services: calls (evidence: `frontend/src/hooks/useChatMessages.js`)
- Character editor → Character API services: uses
- Account settings → Settings actions: uses (evidence: `frontend/src/pages/UserSettings.jsx`)
- Settings actions → HTTP client: calls via
- Auth state → HTTP client: checks session (evidence: `frontend/src/context/AuthContext.jsx`)
- Chat API services → HTTP client: sends requests (evidence: `frontend/src/services/loginUserService.js`)
- Character API services → HTTP client: sends requests (evidence: `frontend/src/services/loginUserService.js`)
- HTTP client → User routes: calls API
- HTTP client → Character routes: calls API
- User routes → Auth and roles: guards routes (evidence: `backend/src/routes/userRoutes.js`)
- User routes → Login and signup: dispatches login (evidence: `backend/src/routes/userRoutes.js`)
- User routes → Session revocation: dispatches revocation (evidence: `backend/src/routes/userRoutes.js`)
- Character routes → Auth and roles: guards routes (evidence: `backend/src/routes/characterRoutes.js`)
- Character routes → Character management: dispatches (evidence: `backend/src/routes/characterRoutes.js`)
- Character routes → Character RAG data: dispatches (evidence: `backend/src/routes/characterRoutes.js`)
- Message handler → Script matcher: matches scripts (evidence: `backend/src/handlers/handlerSendChatMessage.js`)
- Message handler → Conversation context: loads context (evidence: `backend/src/handlers/handlerSendChatMessage.js`)
- Message handler → RAG retrieval: retrieves grounding (evidence: `backend/src/handlers/handlerSendChatMessage.js`)
- Message handler → Gemini services: requests response (evidence: `backend/src/handlers/handlerSendChatMessage.js`)
- Conversation context → Context records: reads and updates (evidence: `backend/src/services/contextManager.js`)
- Conversation context → Redis cache: caches context (evidence: `backend/src/services/contextManager.js`)
- Conversation context → Google Gemini: summarizes (evidence: `backend/src/services/contextManager.js`)
- RAG retrieval → Vector records: searches (evidence: `backend/src/services/mongoSearchQuery.js`)
- Gemini services → Google Gemini: uses
- Character context cache → Character records: loads character (evidence: `backend/src/services/characterContextManager.js`)
- Character context cache → Redis cache: caches character (evidence: `backend/src/services/characterContextManager.js`)
- Character management → Character records: manages (evidence: `backend/src/handlers/handlerUpdateCharacter.js`)
- Character management → Image storage: uploads images (evidence: `backend/src/handlers/handlerUpdateCharacter.js`)
- Image storage → AWS S3: stores objects
- Character RAG data → Vector records: manages data (evidence: `backend/src/handlers/handlerCreateVectorDataStore.js`)
- Login and signup → User records: checks account (evidence: `backend/src/handlers/handlerLogIn.js`)
- Session revocation → User records: revokes sessions
- Login and signup → Email delivery: sends MFA code
- Email delivery → Visitor or user: delivers email
- Message handler → Chat records: persists messages (evidence: `backend/src/handlers/handlerSendChatMessage.js`)