System Requirements Document for bhagavad-gita-chatbot

1. Introduction

bhagavad-gita-chatbot is a retrieval-augmented generation (RAG) chatbot that helps people work through real-life problems by delivering Gita gyan — guidance grounded in the Bhagavad Gita rather than free-form advice. A person describes their situation in natural language; the system retrieves relevant Bhagavad Gita content from an application-owned scripture corpus and returns an answer that is anchored in that retrieved material.

The product serves two audiences:

• Seekers — people facing a real-life problem who want relevant, understandable, scripture-grounded guidance they can apply.
• Knowledge Curators — the people responsible for supplying and maintaining the Bhagavad Gita source corpus that grounds every answer.

The defining constraint of the product is grounding: the chatbot's guidance must be drawn from the Bhagavad Gita through retrieval, not invented as generic counsel. The corpus is therefore a first-class, application-owned asset with its own management surface, and the conversational surface is only as trustworthy as the corpus behind it.

2. System Overview

The current delivery is a first-party web application with custom UI and application-owned identity. It comprises five destinations:

Actors. Two accepted human personas: the Seeker, who asks about a real-life problem and reads the returned Gita-grounded answer, and the Knowledge Curator, who supplies and maintains the scripture corpus. The retrieval pipeline, the vector store, and the language model are non-persona system actors; they execute work but are not human participants.

Accepted behavior. A Seeker opens the Chat surface, describes a real-life problem in natural language, and receives an answer grounded in retrieved Bhagavad Gita content. A Knowledge Curator establishes identity on first use, verifies it on return, and manages the corpus on the Knowledge surface — supplying and updating the Gita text that retrieval draws on. The corpus must be supplied before retrieval-grounded answers can be produced.

Ownership. All five destinations are application-owned custom pages. Identity is application-owned and self-service (Sign Up for first use, Login for return); no provisioning or invitation boundary is established in the source. The Knowledge surface is role-restricted to the Knowledge Curator; the Chat surface is open to any visitor.

Narrow exclusions. The product does not deliver free-form advice detached from the Bhagavad Gita. It does not present itself as a general-purpose assistant, a mental-health service, or a religious authority. No adjacent account-management capabilities (password reset flows, profile editing, social sign-in, multi-role administration) are part of current scope. No future-horizon requirements were stated by the user.

2a. Product Interpretation and Delivery Boundary

The user's request is to build a RAG-based Bhagavad Gita chatbot that solves people's real-life problems by delivering Gita gyan, together with the code and project structure for it. That request defines both the product behavior and the delivery shape.

Delivery ownership. The application owns the conversational surface, the corpus-management surface, and the identity that binds corpus work to the correct curator. The retrieval pipeline, embedding store, and language model are backend execution owned by the application but not surfaced as separate destinations — they are the machinery behind the Chat answer. No third-party provider surface is exposed to either persona; no external destination is required for any accepted journey.

Access boundary. The Landing surface is anonymous and explains what the product does. The Chat surface is open — a Seeker is not required to hold an account to ask a question and receive guidance. The Knowledge surface is protected and role-restricted: because corpus changes alter what every Seeker's answer is grounded in, the commitment must remain bound to the correct curator, so identity is established at Sign Up on first use and verified at Login on return. Sign Up and Login are anonymously reachable entry surfaces; they cannot themselves require the identity they establish.

Current vs. future. Everything described in this document is current. The user stated no future-horizon capabilities, and none are invented here. The code and project structure the user asked for are delivered as the technology and structure described in Sections 9 and 10.

2b. Source Content Inventory

Not applicable. No reference directive in this request declares content_source authority, so no source content inventory is produced. The Bhagavad Gita corpus is user-supplied product data managed through the Knowledge surface, not pre-verified reference content.

2c. Page Content and Component Coverage

Landing

• Information and state. Anonymous, no session required. Presents the product's purpose: help with real-life problems through Bhagavad Gita-based, retrieval-grounded guidance. No personalized or persisted state.
• Primary action. "Ask your question" — a single tomato-red pill button that carries the visitor into the Chat surface.
• Supporting actions. Navigate to Login and Sign Up for visitors who are Knowledge Curators; navigate to Chat directly.
• Domain entities. None persisted. Reads only static product copy and the curated verse excerpts shown in the wisdom ribbon.
• Component responsibilities.
  • Hero — asymmetric two-column composition: left column holds the oversized headline "Find clarity in the Gita's timeless wisdom" in Jost, a short Lora subtext, and the single accent button; right column holds an abstract organic-shape composition in mustard, teal, and walnut that bleeds off the right edge.
  • Wisdom ribbon — a horizontal marquee of short Gita verses in Lora italic, moving slowly right to left, pausing on hover.
  • Feature band — three offset-shadow cards describing what the product does: ask about a real-life problem, receive scripture-grounded guidance, and rely on a curated Gita corpus.
  • Top navigation — hand-drawn style logo mark, links to Login and Sign Up, and a pill-shaped "Chat" button that expands into a full-width drawer on mobile.
• States.
  • Loading — static content; no blocking load. The wisdom ribbon renders its first frame immediately.
  • Empty — not applicable; the page has no user-owned data.
  • Success — the visitor reads the purpose and either enters Chat or moves to an identity surface.
  • Error — if the wisdom ribbon's verse source is unavailable, the ribbon renders a static single verse rather than an empty band.
  • Recovery — the primary "Ask your question" button remains available regardless of ribbon state.

Login

• Information and state. Anonymous entry surface for returning verification. Holds only the in-progress credential input; no protected state is readable before verification succeeds.
• Primary action. Submit credentials to verify a returning Knowledge Curator identity.
• Supporting actions. Navigate to Sign Up for first-use enrollment; return to Landing.
• Domain entities. Curator identity (email/identifier and credential).
• Component responsibilities.
  • Credential form — identifier and password fields with visible labels, inline validation, and a single submit control.
  • Cross-link — a clear path to Sign Up for visitors who have no identity yet.
  • Error region — a reserved area for verification failure messaging that does not shift the form.
• States.
  • Loading — submit control enters a pending state while verification is in flight; fields are locked.
  • Empty — fields render empty with labels and no pre-filled values.
  • Success — verification succeeds and the curator is carried to the Knowledge surface.
  • Error — invalid credentials produce an inline message; the form retains the entered identifier and clears the credential.
  • Recovery — the curator may retry immediately, or follow the Sign Up link if no identity exists.

Sign Up

• Information and state. Anonymous entry surface for first-use enrollment. Holds only the in-progress enrollment input.
• Primary action. Create a Knowledge Curator identity.
• Supporting actions. Navigate to Login for returning curators; return to Landing.
• Domain entities. Curator identity (identifier and credential).
• Component responsibilities.
  • Enrollment form — identifier and credential fields with visible labels and inline validation.
  • Cross-link — a clear path to Login for visitors who already hold an identity.
  • Error region — a reserved area for enrollment failure messaging.
• States.
  • Loading — submit control enters a pending state while enrollment is in flight; fields are locked.
  • Empty — fields render empty with labels.
  • Success — enrollment succeeds and the curator is carried to the Knowledge surface, where corpus work can begin.
  • Error — an already-registered identifier or invalid input produces an inline message with a path to Login.
  • Recovery — the curator may correct the input and resubmit, or switch to Login.

Chat

• Information and state. Open surface, no identity required. Holds the current conversation: the Seeker's described problem and the returned Gita-grounded answer. Conversation history is held in a fixed sidebar.
• Primary action. Submit a described real-life problem in natural language and receive a scripture-grounded answer.
• Supporting actions. Start a new conversation; select a prior conversation from the sidebar; collapse the sidebar on mobile.
• Domain entities. Conversation, message (Seeker message and bot message), retrieved Gita passage references attached to a bot message.
• Component responsibilities.
  • Conversation sidebar — fixed panel listing conversation history; collapsible on mobile.
  • Message stream — messages rendered as soft rounded cards with a subtle offset shadow, alternating cream and white backgrounds to distinguish Seeker and bot.
  • Composer — a rounded input field with a single send control, sized for multi-line problem descriptions.
  • Grounding display — the bot message surfaces the Gita passage(s) its answer was retrieved from, so the Seeker can see the guidance is scripture-anchored.
  • Pending indicator — a calm, non-bouncy state shown while retrieval and generation are in flight.
• States.
  • Loading — the submitted message appears immediately; a pending indicator occupies the bot's next message slot until the answer arrives.
  • Empty — a new conversation shows a short prompt inviting the Seeker to describe what they are facing.
  • Success — the bot message renders as a card with the grounded guidance and its retrieved passage references.
  • Error — if retrieval or generation fails, the bot slot shows a plain failure message with a retry control; the Seeker's original message is preserved.
  • Recovery — the Seeker can retry the same question, rephrase it, or continue the conversation; no message is lost.

Knowledge

• Information and state. Role-restricted to the Knowledge Curator. Holds the application-owned Bhagavad Gita source corpus: the set of source texts available to retrieval, each with its identifying metadata and processing status.
• Primary action. Upload new Gita text into the corpus.
• Supporting actions. Review the existing source cards; update or replace a source; remove a source; inspect a source's processing status.
• Domain entities. Source text (title, description, thumbnail illustration, processing status, ingestion timestamp), corpus (the collection of source texts).
• Component responsibilities.
  • Upload area — a prominent "Upload new text" control styled as a mid-century badge, with file selection and confirmation.
  • Source gallery — a gallery-like grid of source cards, each with a thumbnail illustration, title, and status.
  • Status indicator — per-source state showing whether the text is ingested and available to retrieval.
  • Empty-state guidance — when the corpus is empty, an explicit statement that retrieval-grounded answers cannot be produced until a source is supplied.
• States.
  • Loading — the gallery shows placeholder cards while the corpus list is fetched.
  • Empty — no sources present; the upload area is the dominant element and the page states that answers cannot be grounded until a source is added.
  • Success — a newly uploaded source appears as a card and moves to an available state once ingested.
  • Error — an upload that fails to ingest shows a failed status on its card with a retry control; the rest of the corpus is unaffected.
  • Recovery — the curator can retry ingestion, replace the file, or remove the failed source.

3. Functional Requirements

FR-1 — Ask a real-life problem and receive Gita-grounded guidance (explicit) As a Seeker, I should describe a real-life problem in natural language on the Chat surface and receive an answer grounded in retrieved Bhagavad Gita content, so that I get Gita gyan I can apply to my situation.

• Trigger/input: the Seeker submits a natural-language description of their problem in the composer.
• Observable result: a bot message card appears containing guidance and the Gita passage reference(s) it was retrieved from.
• Access state: open; no identity required.
• Failure/recovery: if retrieval or generation fails, the bot slot shows a plain failure message with a retry control and the Seeker's original message is preserved.
• Continuation: the Seeker may ask a follow-up in the same conversation or start a new one.

FR-2 — Guidance is grounded in the Bhagavad Gita, not free-form advice (explicit) As a Seeker, I should receive guidance that is retrieved from the Bhagavad Gita corpus rather than generated as free-form advice, so that the counsel I act on is scripture-anchored and trustworthy.

• Trigger/input: every Seeker question submitted on Chat.
• Observable result: the returned answer is accompanied by the retrieved Gita passage reference(s) it was drawn from.
• Access state: open.
• Failure/recovery: when no relevant passage can be retrieved, the system states that it could not ground an answer rather than producing ungrounded advice.
• Continuation: the Seeker may rephrase the question to obtain a grounded answer.

FR-3 — Supply the Bhagavad Gita source corpus (required_inference) As a Knowledge Curator, I should upload Bhagavad Gita source text into the application-owned corpus on the Knowledge surface, so that retrieval has material to ground answers in.

• Trigger/input: the curator selects "Upload new text" and confirms a source file.
• Observable result: the source appears as a card in the source gallery and moves to an available state once ingested.
• Access state: role-restricted; requires a verified Knowledge Curator identity.
• Failure/recovery: a failed ingestion shows a failed status on the card with a retry control; the rest of the corpus is unaffected.
• Continuation: the curator may retry, replace the file, or remove the failed source.

FR-4 — Maintain the corpus over time (required_inference) As a Knowledge Curator, I should review, update, replace, and remove sources in the corpus, so that the material retrieval draws on stays the intended Gita content.

• Trigger/input: the curator acts on an existing source card in the Knowledge gallery.
• Observable result: the corpus reflects the change and subsequent retrieval draws on the updated material.
• Access state: role-restricted; requires a verified Knowledge Curator identity.
• Failure/recovery: a failed update or removal leaves the prior source state intact and reports the failure on the affected card.
• Continuation: the curator may retry the operation or leave the source as it was.

FR-5 — Corpus must exist before grounded answers can be produced (required_inference) As a Seeker, I should be told plainly when the corpus is empty, so that I understand why a grounded answer is not yet available rather than receiving ungrounded advice.

• Trigger/input: a Seeker question submitted while the corpus contains no available source.
• Observable result: the Chat surface states that no grounded answer can be produced yet; the Knowledge surface states that answers cannot be grounded until a source is supplied.
• Access state: open on Chat; role-restricted on Knowledge.
• Failure/recovery: once a curator supplies a source, subsequent questions are answered normally.
• Continuation: the Seeker may retry the question later.

FR-6 — First-use identity establishment for the Knowledge Curator (required_inference) As a Knowledge Curator, I should establish my identity on first use through Sign Up, so that my corpus work is bound to me and can be resumed.

• Trigger/input: an unenrolled curator selects the Sign Up path from Landing or Login and submits an identifier and credential.
• Observable result: the identity is created and the curator is carried to the Knowledge surface.
• Access state: anonymous entry; Sign Up does not require the identity it establishes.
• Failure/recovery: an already-registered identifier or invalid input produces an inline message with a path to Login.
• Continuation: the curator proceeds to corpus work, or switches to Login.

FR-7 — Returning verification for the Knowledge Curator (required_inference) As a Knowledge Curator, I should verify my identity on return through Login, so that I can reach the corpus-management capabilities that are restricted to me.

• Trigger/input: a returning curator submits credentials on Login.
• Observable result: verification succeeds and the curator is carried to the Knowledge surface.
• Access state: anonymous entry; protected state remains unavailable until verification succeeds.
• Failure/recovery: invalid credentials produce an inline message; the identifier is retained and the credential cleared for retry.
• Continuation: the curator retries, or follows the Sign Up link if no identity exists.

FR-8 — Reach the chatbot from the public entry (required_inference) As a Seeker, I should understand from the Landing surface that this product helps with real-life problems through Bhagavad Gita-based guidance, and be able to enter the Chat surface from it, so that I can start without friction.

• Trigger/input: a visitor reads the Landing surface and activates "Ask your question".
• Observable result: the visitor arrives at the Chat surface ready to describe their problem.
• Access state: anonymous; no identity required.
• Failure/recovery: if the wisdom ribbon's verse source is unavailable, the ribbon renders a static verse and the entry button remains available.
• Continuation: the visitor describes their problem on Chat.

FR-9 — Conversation history and continuation (required_inference) As a Seeker, I should see my conversation history in the sidebar and be able to select a prior conversation or start a new one, so that I can continue working through a problem across turns.

• Trigger/input: the Seeker selects a conversation in the sidebar or starts a new conversation.
• Observable result: the selected conversation's messages render in the main chat area; a new conversation shows the empty-state prompt.
• Access state: open.
• Failure/recovery: if history cannot be loaded, the main area shows the empty-state prompt and the Seeker can still ask a question.
• Continuation: the Seeker continues the conversation or begins another.

4. User Personas

Seeker

Product context. The Seeker arrives with something concrete and often difficult happening in their life — a decision, a conflict, a loss, a doubt. They are not looking for a lecture on the Bhagavad Gita as a text; they are looking for counsel that speaks to their situation and that they can trust because it comes from the Gita rather than from an invented opinion. They may arrive from the Landing surface without any account and expect to ask immediately.

Primary goal. To describe their real-life problem in their own words and receive relevant, understandable Gita-grounded guidance they can actually apply.

Distinct accepted responsibilities. The Seeker is the only persona who initiates a question and the only one who consumes the answer. Their recurring work is: describe the problem in natural language, read the returned guidance, and judge whether it addresses what they asked. They also decide whether to continue the thread with a follow-up or start a new conversation.

Relevant inputs and decisions. The Seeker supplies the problem description — free-form, unconstrained, in their own phrasing. Their key decision is whether the returned guidance is relevant enough to act on, which drives whether they rephrase, follow up, or leave.

Interactions with other participants. The Seeker does not interact with the Knowledge Curator directly, but depends on them entirely: the quality and authenticity of the corpus the curator maintains determines whether the Seeker's answer is grounded in the intended Gita material. The Seeker's observable outcome — a scripture-anchored answer — is the downstream result of the curator's work.

Observable success. A bot message card appears with guidance and the Gita passage reference(s) it was retrieved from, and the Seeker recognizes their situation in it.

Knowledge Curator

Product context. The Knowledge Curator is the person accountable for what the chatbot is allowed to say. They hold the Bhagavad Gita source material and are responsible for putting it into the system and keeping it correct. Their work is not conversational — it is custodial. They understand that an empty or wrong corpus directly degrades every Seeker's answer, so their surface is a working tool, not a showcase.

Primary goal. To supply and maintain the Bhagavad Gita source corpus so that the chatbot's answers are grounded in the intended Gita material.

Distinct accepted responsibilities. The curator uploads new Gita text, reviews what is currently in the corpus, updates or replaces sources, removes sources that should not be drawn on, and monitors whether each source has been successfully ingested and is available to retrieval. They are also the only persona who must establish and verify an identity, because their changes alter shared product state that affects every Seeker.

Relevant inputs and decisions. The curator supplies source files and their identifying metadata. Their key decisions are which material belongs in the corpus, whether an existing source should be replaced or removed, and whether a failed ingestion should be retried or abandoned.

Interactions with other participants. The curator never speaks to a Seeker, but every Seeker answer is downstream of their corpus. When the corpus is empty, the curator is the only persona who can unblock the Seeker's grounded answers — the Chat surface tells the Seeker plainly that no grounded answer is possible yet, and the Knowledge surface tells the curator what to do about it.

Observable success. The corpus gallery shows the intended Gita sources in an available state, and subsequent Seeker questions return answers grounded in that material.

5. Core User Flows

Flow 1 — Seeker asks about a real-life problem and receives Gita-grounded guidance

1. The Seeker arrives at the Landing surface with no identity and no session.
2. The Seeker reads the headline "Find clarity in the Gita's timeless wisdom" and the subtext explaining that the product helps with real-life problems through Bhagavad Gita-based guidance. The wisdom ribbon scrolls short Gita verses slowly right to left; if the Seeker hovers, it pauses.
3. The Seeker activates the tomato-red pill button "Ask your question".
4. The Seeker arrives at the Chat surface. Because this is a new conversation, the main area shows the empty-state prompt inviting them to describe what they are facing, and the sidebar shows no prior conversations.
5. The Seeker types a description of their real-life problem into the composer in their own words and sends it.
6. The Seeker's message appears immediately as a soft rounded card in the message stream. A calm pending indicator occupies the bot's next message slot while retrieval and generation run.
7. The system retrieves relevant Bhagavad Gita content from the application-owned corpus and produces an answer grounded in that retrieved material.
8. The bot message renders as a card with the grounded guidance and the Gita passage reference(s) it was retrieved from. The Seeker can see that the guidance is scripture-anchored rather than free-form.
9. Failure path: if retrieval or generation fails, the bot slot shows a plain failure message with a retry control. The Seeker's original message is preserved. The Seeker activates retry, or rephrases the question and sends it again. No message is lost.
10. Continuation: the Seeker asks a follow-up in the same conversation, or starts a new conversation from the sidebar. The prior conversation remains selectable in the sidebar and can be reopened later.

Flow 2 — Seeker is told the corpus is empty

1. The Seeker arrives at the Chat surface and describes their problem.
2. The system finds no available source in the corpus and cannot ground an answer.
3. The Chat surface states plainly that no grounded answer can be produced yet, rather than returning ungrounded advice.
4. The Seeker understands the limitation and may retry the question later, once a Knowledge Curator has supplied a source.

Flow 3 — Knowledge Curator establishes identity on first use

1. The Knowledge Curator arrives at the Landing surface and follows the Sign Up path from the top navigation.
2. The Sign Up surface renders an empty enrollment form with visible labels for identifier and credential.
3. The curator enters an identifier and credential and submits. The submit control enters a pending state and the fields lock while enrollment is in flight.
4. Success: the identity is created and the curator is carried to the Knowledge surface, where corpus work can begin.
5. Failure path: if the identifier is already registered or the input is invalid, an inline message appears in the reserved error region with a path to Login. The curator corrects the input and resubmits, or switches to Login.

Flow 4 — Knowledge Curator verifies identity on return

1. The Knowledge Curator arrives at the Login surface from the Landing navigation or from the Sign Up cross-link.
2. The curator enters their identifier and credential and submits. The submit control enters a pending state and the fields lock while verification is in flight.
3. Success: verification succeeds and the curator is carried to the Knowledge surface. Protected corpus state was not readable before this point.
4. Failure path: invalid credentials produce an inline message; the form retains the entered identifier and clears the credential. The curator retries immediately, or follows the Sign Up link if no identity exists.

Flow 5 — Knowledge Curator supplies the Gita corpus

1. The Knowledge Curator is on the Knowledge surface with a verified identity.
2. The corpus is empty. The gallery shows no source cards, the upload area is the dominant element, and the page states explicitly that retrieval-grounded answers cannot be produced until a source is supplied.
3. The curator activates "Upload new text", styled as a mid-century badge, selects a Bhagavad Gita source file, and confirms.
4. The source appears as a card in the gallery with its thumbnail illustration, title, and a processing status.
5. Success: ingestion completes and the card moves to an available state, meaning retrieval can now draw on it. Subsequent Seeker questions return answers grounded in this material.
6. Failure path: if ingestion fails, the card shows a failed status with a retry control, and the rest of the corpus is unaffected. The curator retries ingestion, replaces the file, or removes the failed source.

Flow 6 — Knowledge Curator maintains the corpus over time

1. The Knowledge Curator is on the Knowledge surface with a verified identity. The gallery shows the current source cards.
2. The curator reviews the sources and decides that one should be updated, replaced, or removed.
3. The curator acts on the affected source card. The corpus reflects the change, and subsequent retrieval draws on the updated material.
4. Failure path: if the update or removal fails, the prior source state remains intact and the failure is reported on the affected card. The curator retries the operation or leaves the source as it was.
5. Continuation: the curator returns to the gallery and continues reviewing the remaining sources.

6. Visuals, Colors and Theme

The creative direction is authoritative for this section: warm mid-century modernism for timeless wisdom, with Charles & Ray Eames as the muse. The register is contemplative, humane, and timeless — wisdom that feels ancient and approachable, never cold or dogmatic. The generic indigo/blue-on-white SaaS template is forbidden for this project.

Headline. Warm mid-century modernism for timeless wisdom.

Color tokens — light mode

Dark mode is not the default and is not part of current scope.

Typography

• Headings — Jost. Medium weight. All-caps for section labels with generous tracking (0.05em). Large display sizes for hero and page titles. Tight leading (1.1) so headlines feel monumental yet friendly.
• Body — Lora. A warm serif at a comfortable reading size with ample line-height (1.6) for long-form guidance and chat messages.
• Scale. 1.25 modular scale: 48 / 38 / 30 / 24 / 19 / 16 / 13.
• Hero headline. Clamps from 56px at 375px to 120px at 1280px.
• Section headings. 32–40px.
• Body. 16–18px.

Shape language

Organic-modern geometry. Softly rounded rectangles (12–16px radius) for cards and input fields, with occasional pill-shaped buttons. Section dividers use gentle curves or simple horizontal rules. Icons are hand-drawn style with a consistent stroke weight, echoing mid-century pictograms. No sharp corners except for thin accent lines.

Layout

Modular, gallery-like sequences with generous whitespace. The Landing page uses an asymmetric two-column hero: left column holds the large headline and subtext, right column features a warm illustration or abstract composition. Below, a horizontal band of three feature cards with offset shadows. The Chat interface is a two-panel layout: a fixed sidebar for conversation history (collapsible on mobile) and a main chat area with messages as soft cards. The Knowledge page uses a clean table with alternating row colors and a prominent upload area.

Imagery

Warm, hand-drawn illustrations in the Eames style: abstract geometric shapes, stylized figures in conversation, and subtle patterns inspired by mid-century textiles. Photography, if used, is warm-toned and documentary — close-ups of textured paper, natural light, or hands holding a book. Stock photography of people is avoided; custom spot illustrations convey wisdom and dialogue instead. Overly decorative or ornate religious iconography is avoided.

Readability constraint

Readable text and controls stay whole at every viewport. Headlines, wordmarks, labels, numbers, and cards' text and controls stay entirely inside the viewport and their container at 375px, 768px, and 1280px, wrapping or scaling (for example font-size: clamp(...) with its mobile size) to fit, and no other element covers any part of them. Imagery, decoration, and motion may be cropped, bled off an edge, rotated, overlapped, or cut exactly as the direction asks, as long as they cover no readable text or control. Moving and scrollable content — the wisdom ribbon, any horizontally scrollable row — may cross the viewport or container edge by design and is judged by whether it actually moves or scrolls and whether every item becomes fully readable as it passes. With prefers-reduced-motion, the wisdom ribbon provides a usable static arrangement: items wrap into rows or the ribbon becomes horizontally scrollable so each verse can be brought fully into view.

7. Signature Design Concept

The Wisdom Ribbon and the Open Book.

The public entry is a full-width warm cream canvas (#F9F5EF) built as an asymmetric two-column hero, not a centered stack.

Left column (8 columns). An oversized Jost headline — "Find clarity in the Gita's timeless wisdom" — spans the column and wraps to three lines at desktop, scaling down gracefully on mobile via clamp(56px, …, 120px) with tight 1.1 leading. Beneath it, a short subtext in Lora at 16–18px with 1.6 line-height. Beneath that, a single tomato-red (#E07A5F) pill button reading "Ask your question" — the only accent on the screen, used sparingly as the direction requires.

Right column. A large abstract composition of overlapping organic shapes in mustard (#E9C46A), teal (#2A9D8F), and walnut (#5C4033), suggesting a dialogue between ancient text and modern life. The composition bleeds off the right edge, creating a sense of expansiveness. It is decoration only — it never covers the headline, subtext, or button.

Below the hero. A horizontal band of three feature cards with offset shadows, each on a white surface with 12–16px radius, describing what the product does: ask about a real-life problem, receive scripture-grounded guidance, and rely on a curated Gita corpus.

The wisdom ribbon. A horizontal marquee of short Gita verses set in Lora italic, moving slowly from right to left and pausing on hover. It is the signature move that ties the page to the product's substance: the verses are the same kind of material the chatbot retrieves, so the entry surface shows the Seeker what grounds their answer before they ask anything.

Navigation. A top bar with a hand-drawn style logo mark and a pill-shaped "Chat" button that expands into a full-width drawer on mobile.

No centered text, no gradient blobs, no neon glows, no identical hover-lift card grid.

8. Interaction Model & Motion Direction

Interaction Model: Animated Motion Tempo: restrained Hero Dimensionality: layered_2d

Landing Hero Motion Brief

• Focal subject. The abstract organic-shape composition in mustard, teal, and walnut occupying the right column, bleeding off the right edge — a visual dialogue between ancient text and modern life.
• Input → transformation → outcome thesis. As the visitor scrolls, the layered shape composition pans slowly and its layers separate at slightly different rates, so the composition reads as depth rather than a flat graphic; the headline and subtext fade in on first paint and settle. The outcome is a calm, deliberate arrival that makes the product feel timeless and considered — never bouncy, never aggressive.
• Motion vocabulary. Gentle, film-like transitions: slow pans across imagery, soft fade-ins on scroll for content blocks, and a subtle parallax effect on the hero illustration. Hover states on buttons and cards lift them slightly with a soft shadow expansion. Chat messages slide in with a slight upward motion and fade.
• Composed first frame. Cream canvas at rest. Headline fully legible in Jost on the left, subtext beneath it, tomato-red pill button beneath that. The shape composition sits in its resting position on the right, partially off-edge. The wisdom ribbon is already in motion at its slow right-to-left pace. Nothing is mid-transition; the first frame is a complete, readable composition.
• Reduced-motion state. With prefers-reduced-motion, the parallax and scroll-linked pans are removed and the hero renders as a static layered composition. The wisdom ribbon stops moving and becomes a horizontally scrollable row (or wraps into rows) so every verse can be brought fully into view. All content remains readable and every control remains operable.

9. Non-Functional Requirements

NFR-1 — Retrieval grounding integrity (explicit) Every answer returned on the Chat surface must be produced from content retrieved out of the application-owned Bhagavad Gita corpus. When no relevant passage can be retrieved, the system must state that it cannot ground an answer rather than emitting ungrounded advice. Rationale: the user's explicit constraint that guidance be Gita-grounded, not free-form.

NFR-2 — Corpus availability gates grounded answers (required_inference) The system must not produce retrieval-grounded answers while the corpus contains no available source, and must communicate this state plainly on both the Chat and Knowledge surfaces. Rationale: required to make the accepted grounding constraint truthful.

NFR-3 — Identity continuity for corpus changes (required_inference) Corpus-management operations must be bound to a verified Knowledge Curator identity, because those operations change shared state that affects every Seeker's answer. Rationale: required to keep the commitment bound to the correct participant.

NFR-4 — Anonymous access to guidance (required_inference) A Seeker must be able to reach the Chat surface and receive grounded guidance without establishing an identity. Rationale: the accepted Seeker journey begins anonymously from the Landing surface; no identity requirement is stated for asking a question.

NFR-5 — Readable text and controls at every viewport (explicit, from creative direction) Headlines, wordmarks, labels, numbers, and cards' text and controls must stay entirely inside the viewport and their container at 375px, 768px, and 1280px, wrapping or scaling to fit, with no other element covering any part of them. Rationale: explicit readability constraint in the creative direction.

NFR-6 — Reduced-motion usability (explicit, from creative direction) With prefers-reduced-motion, the wisdom ribbon must provide a usable static arrangement — wrapped rows or horizontal scrolling — so each verse can be brought fully into view, and all scroll-linked motion must be removed. Rationale: explicit accessibility constraint in the creative direction.

NFR-7 — Calm motion discipline (explicit, from creative direction) Motion must remain gentle and film-like. Bouncy or playful animations are excluded. Rationale: explicit exclusion in the creative direction.

10. Tech Stack

The user asked for the code and the project structure for a RAG-based Bhagavad Gita chatbot. The stack below is the concrete delivery of that request.

Frontend

• React with a component-based structure for the five surfaces: Landing, Login, Sign Up, Chat, Knowledge.
• Vite as the build tool and dev server.
• React Router for the five routes.
• Tailwind CSS with the design tokens from Section 6 configured as theme values (cream #F9F5EF, surface #FFFFFF, text #2B2B2B, primary #5C4033, accent #E07A5F, muted #A8A39D, mustard #E9C46A, teal #2A9D8F, sage #A3B18A), plus Jost and Lora loaded as web fonts.
• Framer Motion for the restrained, film-like transitions described in Section 8.

Backend

• Python with FastAPI for the API layer.
• LangChain for the RAG pipeline: document loading, chunking, embedding, retrieval, and answer synthesis.
• Sentence-Transformers for embeddings.
• FAISS as the vector store for the Bhagavad Gita corpus.
• Pydantic for request and response schemas.
• SQLAlchemy with SQLite for application-owned identity (Knowledge Curator accounts) and conversation history.

LLM

• A configurable language model provider behind a single interface, so the answer-synthesis model can be swapped without changing the retrieval pipeline.

Deployment

• Docker and docker-compose to run the frontend, backend, and vector store together.
• Kubernetes is not required for this deployment and is not included.

Project structure

bhagavad-gita-chatbot/
├── frontend/
│   ├── src/
│   │   ├── pages/
│   │   │   ├── Landing.jsx
│   │   │   ├── Login.jsx
│   │   │   ├── SignUp.jsx
│   │   │   ├── Chat.jsx
│   │   │  \x20\xe2\x94\x94── Knowledge.jsx
│   │   ├── components/
│   │   │   ├── Hero.jsx
│   │   │   ├── WisdomRibbon.jsx
│   │   │   ├── FeatureBand.jsx
│   │   │   ├── TopNav.jsx
│   │   │   ├── ConversationSidebar.jsx
│   │   │   ├── MessageCard.jsx
│   │   │   ├── Composer.jsx
│   │   │   ├── SourceGallery.jsx
│   │   │  \x20\xe2\x94\x94── UploadBadge.jsx
│   │   ├── api/
│   │   │  \x20\xe2\x94\x94── client.js
│   │   ├── styles/
│   │   │  \x20\xe2\x94\x94── tokens.css
│   │   ├── App.jsx
│   │  \x20\xe2\x94\x94── main.jsx
│   ├── index.html
│   ├── tailwind.config.js
│  \x20\xe2\x94\x94── package.json
├── backend/
│   ├── app/
│   │   ├── main.py
│   │   ├── routers/
│   │   │   ├── auth.py
│   │   │   ├── chat.py
│   │   │  \x20\xe2\x94\x94── knowledge.py
│   │   ├── rag/
│   │   │   ├── loader.py
│   │   │   ├── chunker.py
│   │   │   ├── embedder.py
│   │   │   ├── retriever.py
│   │   │  \x20\xe2\x94\x94── chain.py
│   │   ├── models/
│   │   │   ├── user.py
│   │   │   ├── conversation.py
│   │   │  \x20\xe2\x94\x94── source.py
│   │   ├── schemas/
│   │   ├── db.py
│   │  \x20\xe2\x94\x94── config.py
│   ├── data/
│   │   ├── corpus/
│   │  \x20\xe2\x94\x94── vectorstore/
│   ├── requirements.txt
│  \x20\xe2\x94\x94── Dockerfile
├── docker-compose.yml
\xe2\x94\x94── README.md

11. Assumptions and Constraints

Assumptions

• A-1 (required_inference) The Bhagavad Gita source corpus is supplied by the Knowledge Curator through the Knowledge surface. The product does not ship a pre-verified scripture corpus, and no reference directive supplies one.
• A-2 (required_inference) Identity is application-owned and self-service. Sign Up establishes a first-use identity and Login verifies a returning one, because no provisioning or invitation boundary is established in the source.
• A-3 (required_inference) The Knowledge surface is restricted to the Knowledge Curator because corpus changes alter shared state that affects every Seeker's answer. The Chat surface is open and requires no identity.
• A-4 (required_inference) Conversation history is held per conversation on the Chat surface so a Seeker can continue working through a problem across turns.
• A-5 (basic_default) The language model provider behind answer synthesis is configurable and not fixed by the source.

Constraints

• C-1 (explicit) The chatbot's guidance must be grounded in the Bhagavad Gita through retrieval, not free-form advice.
• C-2 (explicit) The product must solve people's real-life problems by delivering Gita gyan.
• C-3 (explicit) The delivery must include the code and the project structure.
• C-4 (explicit, from creative direction) The generic indigo/blue-on-white SaaS template is forbidden for this project.
• C-5 (explicit, from creative direction) Dark mode is not the default.
• C-6 (explicit, from creative direction) Stock photography of people and overly decorative or ornate religious iconography are excluded.
• C-7 (explicit, from creative direction) Bouncy or playful animations are excluded.

Out of scope for current delivery

• Free-form advice detached from the Bhagavad Gita.
• General-purpose assistant behavior, mental-health services, or claims of religious authority.
• Adjacent account-management capabilities: password reset, profile editing, social sign-in, multi-role administration.
• Any future-horizon capability; the user stated none.

12. Glossary

• Bhagavad Gita — the scripture that is the sole grounding source for the chatbot's guidance.
• Gita gyan — the Bhagavad Gita-based guidance the product delivers to a Seeker in response to their described problem.
• RAG (Retrieval-Augmented Generation) — the technique by which the system retrieves relevant Bhagavad Gita content from the corpus and produces an answer grounded in that retrieved material, rather than generating free-form advice.
• Corpus — the application-owned collection of Bhagavad Gita source texts that retrieval draws on, managed by the Knowledge Curator on the Knowledge surface.
• Source text — a single uploaded Bhagavad Gita text within the corpus, with its title, description, thumbnail illustration, processing status, and ingestion timestamp.
• Ingestion — the processing step that makes an uploaded source text available to retrieval.
• Grounded answer — a bot message whose guidance is drawn from retrieved corpus content and which surfaces the Gita passage reference(s) it was retrieved from.
• Seeker — the persona who describes a real-life problem and receives Gita-grounded guidance.
• Knowledge Curator — the persona responsible for supplying and maintaining the Bhagavad Gita source corpus.
• Conversation — a single thread of Seeker messages and bot messages on the Chat surface, selectable from the sidebar.
• Wisdom ribbon — the horizontal marquee of short Gita verses on the Landing surface, moving slowly right to left and pausing on hover.