संज्ञानात्मकसंशोधनमञ्चस्य कार्यात्मकानि आवश्यकतानि (saṁjñānātmakasaṁśōdhanamañcasya kāryātmakāni āvaśyakatāni - Functional requirements of a cognitive research platform)
IKS Cognitive Research Platform: BRD
Version: 1.0
Date: July 16, 2025
Project Sponsor: Shankar Santhamoorty
Project Owner: Shankar Santhamoorty
IKS Cognitive Research Platform: BRD
1.1. Business Problem & Opportunity
1.3. Key Business Goals & Success Metrics
4. Functional Use Cases & Requirements
Path A: Direct LLM Query (The "Else" block in the diagram)
Path B: RAG-Based Query (The "alt" block in the diagram, if the user chose "local_files")
The Final Steps (Common to Both Paths)
This is the standard "login dance" for secure, modern web applications.
● The user tries to access your application. Their browser sends a request to your server's address.
Step 3-4: The Redirect to the Identity Provider
Step 5-6: User Authentication at the Source of Truth
Step 7-8: The Callback with an Authorization Code
Step 9-10: The Back-Channel Token Exchange
● This is the most critical server-to-server step. The user's browser is no longer involved.
Step 13-15: Authenticated Access
5. Non-Functional Requirements (NFRs)
1. Executive Summary
1.1. Business Problem & Opportunity
Research in भारतीयज्ञानप्रणाली (bhāratīyajñānapraṇālī - Indian Knowledge Systems) (IKS) presents a unique challenge: knowledge is vast, multi-lingual, and highly fragmented across diverse sources. Scholars and students spend a disproportionate amount of time locating, accessing, and cross-referencing information from ancient texts (often stored in protected digital archives), modern academic papers (in shared drives), and the general body of knowledge from contemporary AI models. This manual process is slow, prone to oversight, and creates a significant barrier to performing deep, comparative analysis and discovering novel connections between disparate sources.
The opportunity exists to dramatically accelerate IKS research by providing a unified, intelligent platform that can interface with these varied knowledge sources simultaneously. By leveraging cutting-edge AI, we can empower researchers to move beyond simple information retrieval and engage in high-level analytical and comparative work.
1.2. Proposed Solution
भारतीयज्ञानप्रणालीनां कृते संज्ञानात्मकसंशोधनमञ्चः (bhāratīyajñānapraṇālīnāṁ kr̥tē saṁjñānātmakasaṁśōdhanamañcaḥ - Cognitive Research Platform for Indian Knowledge Systems) will be a secure, web-based conversational assistant designed specifically for the needs of IKS researchers. It will provide a single, intuitive chat interface to query multiple knowledge sources, including:
- Curated Local Archives: Digitized texts and manuscripts stored in a secure file system.
- Collaborative Research Drives: Modern papers, articles, and notes stored in a shared Google Drive.
- Foundational AI Models: Direct access to the general knowledge of multiple world-class LLMs like Google's Gemini, OpenAI's ChatGPT, and others.
Samanvaya's core innovation is its Concordance Engine, which will not only fetch information from these sources but also perform a comparative analysis, highlighting similarities, differences, and contradictions. The platform will support natural, conversational follow-ups and maintain a persistent history of research sessions, creating a powerful, long-term workspace for every scholar. Access will be secured via their existing institutional Google accounts, ensuring ease of use and robust security.
1.3. Key Business Goals & Success Metrics
Goal ID | Goal | Metric |
Goal 1 | Accelerate Research Cycles. | Reduce the time required for literature review and cross-referencing tasks by an estimated 40%, measured by user surveys and project timelines. |
Goal 2 | Deepen Analytical Insight. | Enable the discovery of novel connections between sources, measured by the number of research papers or theses citing Samanvaya's comparative analysis as a tool. |
Goal 3 | Enhance Research Accessibility. | Increase the engagement of students and junior researchers with primary and secondary source materials, measured by platform usage analytics. |
Goal 4 | Ensure Secure & Persistent Research | Achieve 100% user adoption of the secure login system and receive positive feedback on the value of persistent chat history. |
2. Actors in the system
# | Role Name | Role Type | Use Cases |
1 | IKS Researcher | End User | Login to Chatbot Chat with system using prompt engineering |
2 | System Admin | Admin | Manage the website |
3. Knowledge Sources
This section describes the specific knowledge sources for IKS Research
# | Knowledge Source Type | Knowledge Source | Description |
A1 | Personal Repository | Local File System | Documents from a specific directory and its sub directories |
A2 | Personal Repository | Google Drive | Documents from a specific directory and its sub directories |
B1 | Public LLM based GenAI platforms | Google’s Gemini AI | LLM |
B2 | Public LLM based GenAI platforms | Open AI’s ChatGPT | LLM |
B3 | Public LLM based GenAI platforms | DeepSeek | LLM |
B4 | Public LLM based GenAI platforms | Anthropic’s Claude | LLM |
.
4. Functional Use Cases & Requirements
This section describes the specific actions users can perform and the system's expected behavior from a functional perspective.
Use Case ID | Use Case Name | User Story | Functional Requirements | Priority |
UC-01 | Single Source Query | As an IKS Researcher, I want to select a single knowledge source (e.g., just the Local Archive, or just Gemini AI) to focus my query, so that I can get a targeted answer from a specific domain without noise from other sources. | <ul><li>The user shall be able to select one knowledge source from a provided list (Local Files, Google Drive, Gemini, ChatGPT, etc.).</li><li>The system shall route the user's query only to the selected source.</li><li>If a RAG source is chosen, the system shall retrieve context from it; if an LLM is chosen, the system shall query it directly.</li><li>The system shall display a concise answer based on the single selected source.</li></ul> | High |
UC-02 | Multi-Source Concordance Query | As an IKS Researcher, I want to ask a question across our Local Archive, Google Drive, and a general AI like Claude simultaneously, so that the system can provide a consolidated report comparing their perspectives on the topic. | <ul><li>The user shall be able to select more than one knowledge source from the list.</li><li>The system shall dispatch parallel jobs to all selected sources.</li><li>The system shall analyze the retrieved information from all sources for similarities, differences, and contradictions.</li><li>The final answer presented to the user must be a synthesized, comparative report (e.g., "Source A and B agree on X, but LLM C offers a different perspective Y...").</li></ul> | High |
UC-03 | Conversational Follow-up | As an IKS Researcher, after receiving a complex answer, I want to ask a simple follow-up question like "Can you elaborate on the second point?" without re-stating the entire context, so I can have a natural and efficient dialogue. | <ul><li>The system shall maintain the context of the current conversation session.</li><li>The user shall be able to ask clarifying, ambiguous, or pronoun-based questions that reference previous turns in the conversation.</li><li>The system's response to a follow-up question shall be relevant to the ongoing conversation history.</li></ul> | High |
UC-04 | View Chat History | As an IKS Researcher, I want to see my previous research session when I log back in, so I can resume my line of inquiry or reference findings from last week. | <ul><li>The system shall securely persist the conversation history for each authenticated user.</li><li>Upon a user logging in, the system shall automatically load and display the chat history from their previous sessions.</li></ul> | Medium |
UC-05 | Secure Access | As an IKS Researcher, I want to log in to the application using my existing institutional Google account, so I don't have to create and manage a new set of credentials. | <ul><li>The system shall require user authentication before granting any access to the application.</li><li>The system shall support login via trusted, pre-approved third-party Identity Providers (specifically Google).</li><li>The system shall maintain a secure user session and provide a clear method for logging out.</li></ul> | High |
UC-06 | Extensible Knowledge Base | As a system administrator, I want the ability to add a new knowledge source, like a database of Sanskrit manuscripts, in the future without requiring a full system redesign. | <ul><li>The system's backend architecture shall be modular (microservices), allowing for the addition of new data retrieval agents with minimal impact on the core Concordance Engine and other services.</li></ul> | Medium |
4,1 UC-01 Single Source Query:
User Story:
Use Case ID | UC-02 |
Use Case Name | Single Source Query |
User Story | As a IKS Researcher, I want to select a single knowledge source as per table listed in Section #3. Only files from this source should be used by the system for answering my questions. |
Functional Requirements | <ul><li>The user shall be able to submit a question via a text input field.</li><li>The system shall retrieve relevant information from the selected knowledge source. The system shall generate and display a concise answer based on the retrieved information.</li></ul> |
Actors | IKS Researcher |
Typical Inputs | Prompt questions relating to IKS |
Typical Outputs | GenAI reasoned out answers to the prompted questions |
Error Validation | none |
Priority | High |
Wireframe Diagram:
This wireframe shows the essential UI elements needed to fulfill the use case: a source selector, a chat display area, and a message input form. It's a clean and standard layout for a chat application.
Sample Screens
Process Flow Diagram
This diagram illustrates the specific request/response flow for UC-01, where the user has selected a single source. The key difference from our previous diagrams is that the Orchestrator's role is much simpler—it acts as a direct router instead of performing concordance.
This sequence describes the journey of a user's question from their browser through the entire system, showing how the application intelligently routes the request based on the selected knowledge source.
Actor: IKS Researcher (User)
System Components:
- Angular: The frontend application running in the user's browser.
- ApiSvc: The Node.js microservice responsible for handling user-facing API calls and state.
- ConcordanceSvc: The Python/LangChain microservice acting as the central "brain" or orchestrator.
- RagSourceSvc: Represents one of the specialized RAG retrieval agents (e.g., for Local Files or Google Drive).
- LLMAggregator: The logical component within the ConcordanceSvc that routes calls to different LLMs.
- ExternalLLM: Represents a third-party LLM API endpoint like OpenAI's ChatGPT.
The Workflow
Step 1: User Types Question & Selects a Source
- Action: The IKS Researcher interacts with the Angular Frontend. They type their question (e.g., "What is quantum entanglement?") into the input field. Crucially, they use the dropdown menu to select a specific knowledge source.
- Example Selection: "ChatGPT".
Step 2: User Clicks "Send"
- Action: The user submits the form. This triggers the JavaScript logic in the Angular application.
Step 3: Frontend Sends API Request
- Source: Angular Frontend
- Destination: API Service (ApiSvc)
- Action: The Angular application constructs a JSON payload containing both the user's question and their selected source. It sends this payload as an HTTP POST request to the backend's /api/query endpoint.
- Example Payload: { "query": "What is quantum entanglement?", "source": "chat_gpt" }
Step 4: API Service Forwards Request with MCP
- Source: API Service (ApiSvc)
- Destination: Concordance Orchestrator (ConcordanceSvc)
- Action: The ApiSvc receives the request. It performs its initial duties (like fetching chat history from MongoDB to build the full MCP object) and then forwards this enriched MCP object to the central brain, the ConcordanceSvc. The MCP now contains a key indicating the user's desired target_source.
Step 5: The Critical Decision Point
- Source: Concordance Orchestrator (ConcordanceSvc)
- Action: This is the most important new step. The ConcordanceSvc receives the MCP and inspects the target_source field. It executes a critical piece of routing logic:
- "Is the selected source a RAG source (like 'local_files' or 'google_drive')?"
- In our example, the source is "chat_gpt", so the answer is NO. The system proceeds down the "Direct LLM" path.
Path A: Direct LLM Query (The "Else" block in the diagram)
Step 6a: Route Query to LLM Aggregator
- Source: Concordance Orchestrator (ConcordanceSvc)
- Destination: LLM Aggregator (internal logic)
- Action: Since the user wants a direct answer from an LLM, the orchestrator's logic bypasses the entire RAG pipeline. It hands the user's raw query and the target LLM ("chat_gpt") to its internal LLMAggregator component.
Step 7a: Call Chosen LLM API
- Source: LLM Aggregator
- Destination: External LLM API (e.g., OpenAI's servers)
- Action: The LLMAggregator uses the appropriate SDK (e.g., the OpenAI Python library) and the corresponding API key (securely retrieved from Kubernetes Secrets) to make a direct API call over the internet to the specified external LLM. The prompt sent is simply the user's query, perhaps with a basic system instruction like "You are a helpful assistant."
Step 8a: Return Direct Response
- Source: External LLM API
- Destination: LLM Aggregator
- Action: The external LLM processes the query based on its own general knowledge and returns the answer.
Step 9a: Return Final Answer
- Source: LLM Aggregator
- Destination: Concordance Orchestrator (ConcordanceSvc)
- Action: The aggregator receives the response and passes it up as the final result of the operation.
Path B: RAG-Based Query (The "alt" block in the diagram, if the user chose "local_files")
Step 6b: Dispatch RAG Retrieval Job
- Source: Concordance Orchestrator (ConcordanceSvc)
- Destination: Specific RAG Retriever (RagSourceSvc)
- Action: If the user had selected "local_files", the orchestrator would have made an A2A (Agent-to-Agent) HTTP call to the rag-local-svc, asking it to retrieve relevant context for the query.
Step 7b: Return RAG Context + Answer
- Source: Specific RAG Retriever (RagSourceSvc)
- Destination: Concordance Orchestrator (ConcordanceSvc)
- Action: The RAG agent would perform its full retrieval and generation process (querying Vertex AI, etc.) and return a final, context-grounded answer.
The Final Steps (Common to Both Paths)
Step 10: Orchestrator Returns Final Answer
- Source: Concordance Orchestrator (ConcordanceSvc)
- Destination: API Service (ApiSvc)
- Action: Regardless of which path was taken, the ConcordanceSvc now has a final answer. It sends this answer back to the ApiSvc that made the initial request.
Step 11: API Service Returns Final Answer
- Source: API Service (ApiSvc)
- Destination: Angular Frontend
- Action: The ApiSvc (after saving the bot's response to MongoDB for history) sends the final answer back to the user's browser.
Step 12: Display Answer in Chat UI
- Source: Angular Frontend
- Destination: User
- Action: The Angular application receives the response and dynamically updates the chat window to display the bot's final answer, completing the request-response cycle.
4,2 UC-02 Multiple Source Query:
Use Case ID | UC-02 |
Use Case Name | Multi Source Query |
User Story | As a IKS Researcher, I want to select more than one knowledge source as per table listed in Section #3. A consolidated response should be provided by the system by aggregation and concordance of the responses from each individual source system. |
Functional Requirements | The system shall analyze the retrieved contexts for similarities, differences, and contradictions.</li><li>The final answer presented to the user must summarize the comparison (e.g., "Both sources agree that...", "Source A says X, while Source B says |
Actors | IKS Researcher |
Typical Inputs | Prompt questions relating to IKS |
Typical Outputs | GenAI reasoned out answers to the prompted questions |
Error Validation | none |
Priority | High |
Wireframe Diagram:
The key UI change is to move from a single-select dropdown to a multi-select mechanism. The most user-friendly way to do this is with a series of checkboxes, allowing the user to pick any combination of sources.
Sample Screens
Process Flow Diagram
This diagram illustrates the full "Concordance" workflow. It shows the orchestrator dispatching parallel jobs to multiple agents (both RAG and direct LLM agents), aggregating all the responses, and then performing the final comparison and synthesis step.
This sequence describes the journey of a user's question when they select multiple, potentially different types of knowledge sources, requiring the system to perform retrieval, direct queries, and final synthesis.
Actor: IKS Researcher (User)
System Components:
Angular: The frontend application in the user's browser.
ApiSvc: The primary Node.js backend API.
ConcordanceSvc: The Python/LangChain "brain" or orchestrator.
RAGAgents: Represents the pool of specialized RAG retrieval agents (for Local Files, Google Drive).
LLMAggregator: The logical routing component within the ConcordanceSvc.
ExternalLLMs: Represents the various external LLM API endpoints (Google's Gemini, OpenAI's ChatGPT, etc.).
The Workflow
Step 1: User Types Question & Selects Multiple Sources
Action: The IKS Researcher types their question into the chat input. They then use the checkboxes to select a combination of sources.
Example Selection: They check the boxes for "Local Files" (a RAG source) and "Gemini AI" (a direct LLM source).
Step 2: Frontend Sends API Request
Source: Angular Frontend
Destination: API Service (ApiSvc)
Action: The Angular app's JavaScript gathers the query string and collects the value of all checked boxes into an array. It sends this data in a single HTTP POST request.
Example Payload: { "query": "Compare the 'Aurora Project' specs with a general theoretical approach.", "sources": ["local_files", "gemini_ai"] }
Step 3: API Service Forwards Request with MCP
Source: API Service (ApiSvc)
Destination: Concordance Orchestrator (ConcordanceSvc)
Action: The ApiSvc receives the request. It builds the full MCP object (including chat history from MongoDB) and adds the sources array to it. This complete "mission briefing" is then forwarded via an internal HTTP call to the ConcordanceSvc.
Step 4: Orchestrator Initiates Parallel Jobs
Source: Concordance Orchestrator (ConcordanceSvc)
Action: This is the core of the orchestration. The ConcordanceSvc parses the incoming MCP and inspects the sources array. It sees that it needs to get information from both a RAG source and a direct LLM source. It then initiates these two workflows in parallel to save time.
The par Block: Parallel Execution
The par...and...end block in the diagram shows two workflows happening at the same time.
Workflow A: RAG Retrieval
Step 5a: Dispatch RAG Job: The Orchestrator sends an A2A (Agent-to-Agent) HTTP request to the rag-local-svc containing the user's query.
Step 6a: Return RAG Context: The rag-local-svc does its full job (embedding the query, searching Vertex AI) and returns a structured response containing the most relevant text chunks it found in the local files. This response is sent back to the Orchestrator.
Workflow B: Direct LLM Query
Step 5b: Route Query to LLM Aggregator: Simultaneously, the Orchestrator's internal logic passes the user's query to the LLMAggregator component, specifying "gemini_ai" as the target.
Step 6b: Call Gemini API: The LLMAggregator makes a direct API call over the internet to the Google Gemini endpoint.
Step 7b: Return Gemini Response: Gemini processes the query based on its general knowledge and sends an answer back.
Step 8b: Return Gemini Response: The LLMAggregator passes this raw response up to the main Orchestrator logic.
The Synthesis Phase
Step 9: Aggregate All Responses
Source: Concordance Orchestrator (ConcordanceSvc)
Action: The Orchestrator waits until both parallel workflows (A and B) have completed. It now holds all the necessary raw materials in its memory:
The retrieved text chunks from the "Local Files" RAG agent.
The direct answer from the "Gemini AI" LLM.
The original conversation history from the MCP.
Step 10: Perform Concordance
Source: Concordance Orchestrator (ConcordanceSvc)
Destination: LLM Aggregator (internal logic)
Action: This is the "concordance" step. The orchestrator's LangChain logic constructs a new, complex analytical prompt. This prompt includes all the aggregated materials from Step 9 and instructs a powerful reasoning model to perform the comparison.
Step 11-13: Generate and Return Synthesized Answer
Action:
(11) The LLMAggregator sends this complex analytical prompt to a powerful reasoning model (e.g., Gemini 1.5 Pro or GPT-4o).
(12) The model returns the final, structured "concordance report".
(13) The LLMAggregator passes this final report up to the main Orchestrator logic.
The Final Steps
Step 14-16: Return to User
Action: The process is now the same as the single-source flow.
(14) The ConcordanceSvc sends the final, formatted answer back to the ApiSvc.
(15) The ApiSvc saves the bot's response to MongoDB and sends it to the Angular frontend.
(16) The Angular app receives the structured response (which may contain HTML for formatting, like headings and lists) and renders it in the chat window for the user to see.
4,2 UC-03 Conversational Follow-up
Use Case ID | UC-03 |
Use Case Name | Conversational Follow-up |
User Story | As a IKS Researcher, I want to ask a follow-up question (e.g., "Why is that?") without re-stating my original query, so that I can have a natural, efficient conversation. |
Functional Requirements | The system shall maintain the context of the current conversation session. The user shall be able to ask clarifying questions that reference previous turns in the conversation. The system's response to a follow-up question shall be relevant to the ongoing conversation. |
Actors | IKS Researcher |
Typical Inputs | Prompt questions relating to IKS |
Typical Outputs | GenAI reasoned out answers to the prompted questions |
Error Validation | none |
Priority | High |
Wireframe Diagram:
There are no changes to the wireframe. The user interface for asking a follow-up question is identical to asking an initial question. The user simply types their new, shorter question into the same input box.
The "magic" happens entirely on the backend. Because the UI doesn't need to change, we can reuse the previous wireframe.
Sample Screens
Similarly, no changes are required for the GUI code. The existing index.html file already supports a conversational flow. The JavaScript logic simply takes whatever text is in the input box and sends it to the backend. It doesn't need to know whether the question is a new topic or a follow-up.
This demonstrates a key principle of good architecture: the frontend is "dumb" and handles presentation, while the backend is "smart" and handles context and logic.
Process Flow Diagram
This is where the power of our MCP-based architecture becomes clear. The process flow is almost identical to the previous multi-source query. The only difference is the content of the data being passed and how the LLM interprets it.
This flow highlights how the conversation history stored in MongoDB and passed via the MCP allows the system to understand ambiguous follow-up questions.
Initial State: The user has already asked a question, and the answer is on the screen. The chat history is saved in MongoDB.
- Previous User Turn: "Tell me about the Aurora Project specs."
- Previous Bot Turn: "The Aurora Project uses a hyper-lithium power core."
The Follow-up Workflow:
Step 1: User Asks Follow-up Question
- Action: The user types a short, context-dependent question like "Why is that?" and clicks send. The question is ambiguous on its own.
Step 2: Frontend Sends API Request
- Action: The Angular app sends the new, ambiguous query to the ApiSvc. It does not need to send the previous messages.
- Payload: { "query": "Why is that?", "sources": ["local_files"] }
Step 3 & 4: Fetch Conversation History
- Source: API Service (ApiSvc)
- Destination: MongoDB
- Action: This is the first critical step. The ApiSvc, upon receiving the request, immediately queries the MongoDB database to retrieve the recent chat history for the current user's session.
Step 5: Builds Rich MCP Object
- Source: API Service (ApiSvc)
- Action: The ApiSvc now assembles the MCP object. This is the key to solving the use case. The MCP now contains not only the new query but also the history that provides context.
- Example MCP Payload:
- Generated json
{
"query": "Why is that?",
"sources": ["local_files"],
"conversation_history": [
{ "role": "user", "content": "Tell me about the Aurora Project specs." },
{ "role": "model", "content": "The Aurora Project uses a hyper-lithium power core." }
]
- }
- Use code with caution.Json
Step 6: Sends Complete MCP to Orchestrator
- Action: The ApiSvc sends this rich, context-aware MCP object to the ConcordanceSvc.
Step 7: Orchestrator Dispatches Jobs
- Action: The ConcordanceSvc receives the MCP. Its process is identical to the previous use case: it looks at the sources array ("local_files") and dispatches a retrieval job to the appropriate RAG agent. The RAG agent retrieves context about "hyper-lithium power cores".
Step 8: Perform Synthesis with Full Context
- Source: Concordance Orchestrator (ConcordanceSvc) -> LLMAggregator
- Action: This is the second critical step. The final prompt sent to the LLM is now incredibly rich. The LangChain logic combines everything it has:
- The RAG Context: Chunks of text about power cores.
- The Conversation History: The previous Q&A turn.
- The Final Question: "Why is that?"
- The LLM now has everything it needs to understand that "that" refers to "using a hyper-lithium power core".
Step 9: Returns Context-Aware Answer
- Action: The LLM, with full context, generates a relevant answer like, "The hyper-lithium core was chosen for its high energy density and safety profile, as detailed in the project's engineering whitepaper."
Step 10-13: Return Flow and History Update
- Action: The process completes as normal: the answer is passed up the chain from ConcordanceSvc to ApiSvc to the Angular frontend.
- Crucially, in Step 11, the ApiSvc saves both the user's new question ("Why is that?") and the bot's new answer to the MongoDB history, preparing the system for the next follow-up question.
4.3 UC-04 Secure Access
Use Case ID | UC-04 |
Use Case Name | View Chat History |
User Story | As a IKS Researcher, I want to see my previous questions and answers when I open the application, so I can resume my work or reference past findings. |
Functional Requirements | The system shall persist the conversation history for each user session. Upon loading the application, the system shall display the chat history from the user's previous session. |
Actors | IKS Researcher |
Typical Inputs | Prompt questions relating to IKS |
Typical Outputs | GenAI reasoned out answers to the prompted questions |
Error Validation | none |
Priority | High |
Wireframe Diagram:
The wireframe for this use case doesn't show a new screen but rather the initial state of the chat application after a user has successfully logged in and the application has loaded. It will show the chat area pre-populated with messages from a previous session.
Sample Screens
The HTML and CSS are largely the same as our previous complete chat interface. The key change is in the JavaScript. The DOMContentLoaded event listener will now immediately trigger a function to fetch the chat history from the backend API and render it before the user takes any action.
Process Flow Diagram
This diagram illustrates the sequence of events that occurs when a user first loads the application after having been previously authenticated. It highlights the proactive fetching of data from the MongoDB database.
This workflow is simpler than a query flow, as it primarily involves retrieving and displaying data.
Initial State: The user has previously logged in and has a valid session cookie stored in their browser.
Step 1: User Navigates to Application
- Action: The user opens their browser and goes to the application's URL (e.g., https://iks-assistant.yourcompany.com).
Step 2 & 3: Authenticated Page Load
- Action: The browser sends a request for the main page, automatically including the session cookie. The Security Gateway intercepts this, validates the cookie, and allows the request to pass through to the Frontend Web-Service, which serves the core Angular application files (HTML, JS, CSS).
Step 4: Angular App Initializes
- Action: The downloaded JavaScript runs in the user's browser, and the Angular application starts its lifecycle.
Step 5: Frontend Requests History
- Source: Angular Frontend
- Destination: API Service (ApiSvc)
- Action: This is the key step for this use case. As part of its initialization process (specifically, in the ngOnInit lifecycle hook), the Angular component immediately makes an HTTP GET request to the /api/history endpoint to fetch the conversation data.
Step 6 & 7: API Service Fetches from Database
- Source: API Service (ApiSvc)
- Destination: MongoDB
- Action: The ApiSvc receives the /api/history request. It then executes a database query on the ChatMessages collection in MongoDB, finding all documents associated with the current user's ID or session ID. MongoDB returns an array of message documents.
Step 8: API Service Returns History
- Action: The ApiSvc takes the array of data from MongoDB, formats it into a clean JSON array, and sends it back as the response to the Angular frontend's request.
Step 9 & 10: Frontend Renders History
- Source: Angular Frontend
- Destination: User
- Action: The Angular app receives the JSON array of messages. It then dynamically loops through this array, creating the necessary HTML div elements for each user message and bot response and inserting them into the chat display area. Finally, the fully populated chat interface is visible to the user, allowing them to instantly resume their work.
4.4 UC-05 Secure Access
Use Case ID | UC-05 |
Use Case Name | Secure Access |
User Story | As a IKS Researcher, I want to log in to the application using my existing company Google account, so I don't have to manage another password. |
Functional Requirements | The system shall require user authentication before granting access to the chat interface. The system shall support login via trusted, pre-approved third-party Identity Providers (e.g., Google).</li><li>The system shall maintain a secure user session. |
Actors | IKS Researcher |
Typical Inputs | Prompt questions relating to IKS |
Typical Outputs | GenAI reasoned out answers to the prompted questions |
Error Validation | none |
Priority | High |
Wireframe Diagram:
The primary new UI component is the Login Screen. This is the first thing a new user will see. It's simple, clean, and provides a clear call to action. We will also show the "post-login" state of the main chat screen, which might include a "Logout" button.
Sample Screens
Similarly, no changes are required for the GUI code. The existing index.html file already supports a conversational flow. The JavaScript logic simply takes whatever text is in the input box and sends it to the backend. It doesn't need to know whether the question is a new topic or a follow-up.
This demonstrates a key principle of good architecture: the frontend is "dumb" and handles presentation, while the backend is "smart" and handles context and logic.
Process Flow Diagram
This is where the power of our MCP-based architecture becomes clear. The process flow is almost identical to the previous multi-source query. The only difference is the content of the data being passed and how the LLM interprets it.
This is the standard "login dance" for secure, modern web applications.
Step 1-2: Initial Request
The user tries to access your application. Their browser sends a request to your server's address.
Step 3-4: The Redirect to the Identity Provider
The Security Gateway at the edge of your GKE cluster intercepts this request. It sees that the user does not have a valid session cookie, so it knows they are not logged in.
Instead of serving the application, it sends back a redirect command, telling the user's browser to go to Google's login page instead. This redirect includes special parameters like your app's client_id and the scope of permissions you're requesting.
Step 5-6: User Authentication at the Source of Truth
The user is now interacting directly and only with Google. They enter their password and perform two-factor authentication on Google's trusted domain. Your application never sees or handles the user's password, which is a massive security benefit.
After logging in, Google shows the user a consent screen based on the scopes you requested (e.g., "This app wants to view your email address and basic profile info"). The user clicks "Allow."
Step 7-8: The Callback with an Authorization Code
Once the user consents, Google redirects the browser back to a special "callback URL" on your Security Gateway. This redirect URL now contains a temporary, single-use authorization code.
Step 9-10: The Back-Channel Token Exchange
This is the most critical server-to-server step. The user's browser is no longer involved.
The Security Gateway takes the temporary authorization code it just received and makes a direct, secure API call to Google's token endpoint. It authenticates itself with its client_id and client_secret.
Google validates the code and, if it's valid, returns the valuable ID Token (a JWT that proves who the user is) and an Access Token (which can be used to call other Google APIs, like Drive, on the user's behalf).
Step 11-12: Session Creation
The Gateway receives the tokens. It cryptographically validates the signature of the ID Token to ensure it hasn't been tampered with.
Now knowing the user is legitimately authenticated, the Gateway creates its own secure session for the user (e.g., a secure, encrypted cookie) and sends one final redirect back to the user's browser, telling it to load the main application page again.
Step 13-15: Authenticated Access
The browser now makes the request for the main page, but this time it includes the secure session cookie.
The Gateway sees the valid cookie, allows the request to pass through, and serves the full Angular application.
The user sees the logged-in chat interface, and their authenticated session has begun. All subsequent API calls from the Angular app will include this session cookie, which the Gateway will validate on every request.
5. Non-Functional Requirements (NFRs)
This section defines the quality attributes, operational standards, and constraints of the system.
Category | NFR ID | Requirement Description |
Performance | NFR-01 | Response Time: For standard queries, the system shall return a complete answer to the user within 5 seconds under normal load conditions. |
NFR-02 | Concurrency: The system must be able to handle at least 50 concurrent querying users without a significant degradation in performance. | |
Security | NFR-03 | Authentication: All access to the application's core functionalities must be authenticated via an approved OIDC provider. |
NFR-04 | Data Encryption: All data in transit (between the user, servers, and APIs) must be encrypted using TLS 1.2 or higher. Data at rest (chat history in MongoDB) should be encrypted. | |
NFR-05 | Principle of Least Privilege: Each microservice and cloud component must operate with the minimum permissions necessary to perform its function. | |
Scalability | NFR-06 | Stateless Services: The core application microservices (API, Concordance, Retrievers) shall be designed as stateless, allowing for horizontal scaling by adding more container instances. |
NFR-07 | Scalable AI Services: The system shall leverage managed, serverless AI services (Vertex AI) that scale automatically with demand. | |
Availability | NFR-08 | High Availability: The system shall be deployed in a high-availability configuration (e.g., across multiple GKE nodes) to ensure it is resilient to single-node failures. The target uptime is 99.5%. |
Usability | NFR-09 | Interface: The web interface shall be clean, intuitive, and responsive, working correctly on modern web browsers (Chrome, Firefox, Safari). |
Maintainability | NFR-10 | CI/CD: The entire build, test, and deployment process shall be automated through a DevSecOps pipeline to ensure consistent and reliable releases. |
NFR-11 | Monitoring & Logging: The system must produce structured logs and performance metrics for all microservices to facilitate debugging and monitoring. | |
Compliance | NFR-12 | Data Handling: The system must adhere to all internal company policies regarding data privacy and the handling of sensitive information found within the source documents. |
Shankar Santhamoorthy
