PROJECT OVERVIEW:
The application, tentatively named 'Proje Bilgi Sohbeti' (Project Knowledge Chat), is a SaaS platform designed to empower engineers and technical teams by enabling them to interact with vast historical project data using natural language. It addresses the challenge of quickly retrieving specific information from unstructured and semi-structured data sources (e.g., technical documentation, reports, analyses, regulations, code files, CSVs) accumulated over years within a company. Unlike traditional search engines, this tool leverages a local Large Language Model (LLM) combined with Retrieval-Augmented Generation (RAG) to provide fast, contextually relevant answers with direct references to the source documents. The core value proposition is to significantly reduce the time engineers spend searching for information, improve decision-making by providing accurate and accessible knowledge, and enhance internal knowledge sharing, especially in complex domains like offshore engineering where tools like OrcaFlex are critical.
TECH STACK:
- Frontend: React (using Vite for fast development server)
- Styling: Tailwind CSS for rapid UI development and utility-first styling.
- State Management: Zustand for efficient and simple global state management.
- Routing: React Router DOM for client-side routing.
- API Calls: Axios for making HTTP requests to a potential backend or local service.
- Local LLM/RAG Backend (Conceptual - will be simulated or integrated with a local Ollama setup): This will involve Python libraries like LangChain, LlamaIndex, sentence-transformers, and potentially a vector database like ChromaDB or FAISS. For this prompt, we will simulate the RAG response.
- UI Components: Utilize libraries like Headless UI for accessible and unstyled components, and potentially a charting library like Recharts if data visualization is added later.
CORE FEATURES:
1. **Secure Local LLM Integration (Ollama-based):
* User Flow:
* On initial setup or via settings, the user (or admin) configures the connection to a local Ollama instance or specifies a local model path.
* The application sends prompts to the local LLM via a defined API endpoint (simulated in MVP).
* Details: The MVP will simulate the LLM interaction. Future iterations would involve actual API calls to Ollama.
2. **RAG System for Data Ingestion and Retrieval:
* User Flow:
* Admin Interface (future): Uploads or points to data directories (PDF, TXT, CSV, code files).
* Background Process: Data is chunked, embedded, and stored in a vector index (simulated in MVP).
* User Query: When a user asks a question, the system searches the vector index for relevant document chunks.
* Augmented Prompt: The retrieved chunks are combined with the user's original question to form an augmented prompt.
* LLM Generation: The augmented prompt is sent to the local LLM to generate a concise answer grounded in the retrieved context.
* Details: MVP will simulate the retrieval and generation steps. Assume data is pre-processed and available in a mock format.
3. **Natural Language Query Interface:
* User Flow:
* A prominent chat input field is displayed. Users type their questions naturally (e.g., "What were the main findings of Project X's OrcaFlex analysis?", "List all regulations related to subsea pipelines.").
* User submits the query.
* Details: Input validation will ensure the query is not empty.
4. **Contextual Answers with Source Referencing:
* User Flow:
* After the LLM generates the answer, the system identifies the source documents or chunks used.
* The answer is displayed in the chat interface, followed by a list of clickable references (e.g., "Source: ProjectX_Report_Final.pdf - Page 15", "Source: OrcaFlex_Analysis_Notes.txt").
* Details: Mock references will be generated based on the sample data.
5. **Project-Specific and General Information Retrieval:
* User Flow:
* Users can frame questions broadly (e.g., "Tell me about the company's biggest projects") or specifically (e.g., "Summarize the technical challenges in the "Deep Sea Explorer" project.").
* The RAG system's retrieval mechanism, potentially enhanced by metadata filtering (e.g., project name), handles the scope.
* Details: MVP assumes queries can be implicitly or explicitly scoped.
6. **User-Friendly Chat Interface & History:
* User Flow:
* A clean, intuitive chat interface displays the conversation history.
* Users can scroll through past messages and answers.
* A sidebar or menu allows access to a history of past conversations/queries.
* Details: Implemented using React components and state management.
UI/UX DESIGN:
- Layout: Single Page Application (SPA) structure. A main content area for the chat interface. A collapsible sidebar for conversation history and potentially settings. Header for branding and global actions.
- Color Palette: Primary: Deep Blue (#1E3A8A), Secondary: Light Gray (#F3F4F6), Accent: Teal (#14B8A6), Text: Dark Gray (#1F2937). Use contrasting colors for accessibility.
- Typography: Use a clean, readable sans-serif font like Inter or Roboto. Headings: Bold, larger sizes. Body text: Regular weight, appropriate line-height.
- Responsive Design: Mobile-first approach. Use Tailwind CSS's responsive prefixes (sm:, md:, lg:). Ensure usability on screens from 320px to large desktops. Sidebar collapses into a menu on smaller screens.
- Components: Chat bubbles for user and AI messages, input area with send button, reference links, loading indicators, sidebar navigation items.
COMPONENT BREAKDOWN:
- `App.jsx`: Main application component, sets up routing and global layout.
- `ChatPage.jsx`: Renders the main chat interface, including `ChatWindow` and `MessageInput`.
- `ChatWindow.jsx`: Displays the conversation history. Maps over `messages` state and renders `MessageBubble` for each.
- Props: `messages` (array of message objects).
- `MessageBubble.jsx`: Renders a single chat message (either user or AI).
- Props: `message` (object with text, sender, timestamp, references), `isUser` (boolean).
- `MessageInput.jsx`: The text input field and send button for users to type queries.
- Props: `onSendMessage` (function), `isLoading` (boolean).
- `Sidebar.jsx`: Collapsible sidebar for conversation history and navigation.
- Props: `conversations` (array), `onSelectConversation` (function).
- `HistoryItem.jsx`: Renders a single item in the conversation history list.
- Props: `conversation` (object), `onClick` (function).
- `LoadingIndicator.jsx`: Displays a visual cue when the AI is processing.
- `ReferenceLink.jsx`: Renders a clickable link to a document reference.
- Props: `reference` (string).
DATA MODEL:
- `messages` state (Zustand store):
```javascript
{
id: string,
text: string,
sender: 'user' | 'ai',
timestamp: Date,
references?: Array<{ text: string, url?: string }> // url is conceptual for MVP
}
```
- `conversations` state (Zustand store):
```javascript
{
id: string,
title: string, // Auto-generated or user-set
messages: Array<MessageObject>,
lastUpdated: Date
}
```
- Mock Data Format (for RAG simulation):
```javascript
[
{
"id": "doc1",
"source": "ProjectX_Report_Final.pdf",
"page": 15,
"content": "The OrcaFlex analysis indicated a 15% higher stress factor under extreme wave conditions than initially predicted. Mitigation strategy involves reinforcing the main support structure."
},
{
"id": "doc2",
"source": "OrcaFlex_Analysis_Notes.txt",
"content": "Key parameters set: wave height=8m, period=10s, current=1.5m/s. Simulation ran for 1 hour virtual time. Results show significant heave motion."
},
{
"id": "doc3",
"source": "Regulations_Subsea_Pipelines.pdf",
"section": "Section 3.2",
"content": "All subsea pipelines must comply with ISO 19906 standards, ensuring a minimum safety factor of 3.0 for operational loads."
}
// ... more documents
]
```
ANIMATIONS & INTERACTIONS:
- Message Sending: Subtle fade-in animation for the user's message bubble after sending.
- AI Response: AI message bubbles can animate in sequence as they are 'generated' (simulated).
- Loading State: A pulsating dot animation or a subtle shimmer effect on the input area or a dedicated indicator when the AI is 'processing' the request.
- Hover Effects: Subtle background color change or slight scale-up on interactive elements like reference links or sidebar items.
- Transitions: Smooth transitions for sidebar opening/closing and potential route changes (though less relevant for a single-page chat app).
EDGE CASES:
- Empty State: When no conversations exist, display a welcoming message and instructions. When a conversation is empty, show a prompt to start chatting.
- Error Handling:
* API Errors: Display user-friendly messages if the (simulated) LLM backend is unreachable or returns an error.
* RAG Errors: If document retrieval fails or returns no relevant context, inform the user that the query could not be answered based on available data.
- Input Validation: Prevent sending empty messages. Basic sanitization to prevent XSS.
- No Results Found: If the RAG search yields no relevant chunks, the AI response should state that clearly, rather than hallucinating.
- Accessibility (a11y): Ensure proper ARIA attributes, keyboard navigation, sufficient color contrast, and semantic HTML structure.
SAMPLE DATA:
```json
[
{
"id": "projA_report",
"source": "ProjectA_FinalReport.pdf",
"page": 42,
"content": "The fatigue analysis for the main riser in Project Alpha revealed potential weaknesses under cyclical loading, necessitating a design modification to the joint."
},
{
"id": "projA_design",
"source": "ProjectA_DesignSpec.docx",
"section": "3.1.2",
"content": "The modification involves adding a secondary support bracket made of high-tensile steel (grade S355) to reinforce the connection point."
},
{
"id": "projB_orcaflex",
"source": "ProjectB_OrcaFlex_Sim.log",
"content": "Simulation parameters for Project B included wave spectrum Pierson-Moskowitz, significant wave height Hs = 5.5m, and peak period Tp = 8.2s. Results are attached in findings.csv."
},
{
"id": "projB_findings",
"source": "ProjectB_Findings.csv",
"content": "Max tension observed: 1500 kN. Max displacement: 12.5m. Fatigue life estimate: 25 years. This meets regulatory requirements."
},
{
"id": "reg_iso19906",
"source": "ISO_19906_Standard.pdf",
"section": "Clause 7",
"content": "Floating structures and subsea installations shall be designed to withstand environmental loads including waves, currents, and wind, with appropriate safety factors defined."
},
{
"id": "projC_meetingnotes",
"source": "ProjectC_Kickoff_Notes.txt",
"content": "Project C aims to develop a new sensor array for deep-sea monitoring. Initial budget allocated: $2M. Key stakeholder: Dr. Anya Sharma."
}
]
```
DEPLOYMENT NOTES:
- Build Tool: Vite is recommended for its speed. `npm run build` will generate optimized static assets.
- Environment Variables: Use `.env` files (e.g., `.env.local`) for managing API endpoints (if a real backend is used) or feature flags. `VITE_API_URL` could be an example.
- Performance Optimizations: Code splitting with React.lazy, image optimization (if any), memoization (React.memo, useMemo, useCallback) for expensive computations or frequently re-rendered components. Bundle analysis to identify potential bloats.
- Local RAG/LLM Setup: Instruct users on how to install and run Ollama locally and ensure the application can connect to the specified local endpoint (e.g., `http://localhost:11434`). For MVP, this can be mocked entirely in the frontend state.