PROJECT_DETAILS.md

ReqBot: Detailed Project Breakdown

This document provides a comprehensive technical overview of the ReqBot application. It is intended to help developers (and students) understand the project's architecture, technology choices, and the logic behind its features.

1. Project Goal & Core Concept

ReqBot is an AI-powered web application designed to act as a Business Analyst. Its primary function is to help users define and document the requirements for a software project through a simple, conversational interface.

The core loop is:

1. Converse: The user talks to the AI, describing their project idea in natural language.
2. Extract: The AI analyzes the conversation and extracts structured requirements.
3. Report: The AI generates a formal, printable report from the extracted requirements, complete with diagrams and cost estimates.

---

2. Technology Stack & Rationale

This project uses a modern, React-based stack chosen for its efficiency, developer experience, and powerful features.

Technology	Role	Why it was chosen
Next.js (App Router)	Full-stack React Framework	Provides server-side rendering (SSR), file-based routing, and Server Components for performance and a great developer experience.
React	UI Library	The industry standard for building interactive and component-based user interfaces.
TypeScript	Language (superset of JavaScript)	Adds static typing to JavaScript, which reduces bugs, improves code quality, and makes the codebase easier to maintain.
Google AI & Genkit	Generative AI Backend	Manages all interactions with the Google Gemini large language model (LLM). Genkit makes it easy to define structured AI "flows".
ShadCN/UI	UI Component Library	A collection of beautifully designed and accessible components (Buttons, Cards, etc.) that can be easily customized.
Tailwind CSS	CSS Framework	A utility-first CSS framework for rapid UI development without writing custom CSS. Used for all styling.
Web Speech API	Browser API for Voice	A built-in browser feature used for the speech-to-text functionality (the microphone button).
Zod	Schema Validation	Used in the AI flows to define the exact shape (schema) of the data we expect from the AI, ensuring the output is reliable.
Mermaid.js	Diagramming Library	Used to render the Activity Diagram in the final report from a simple text-based syntax generated by the AI.

---

3. Project Structure (File by File)

Understanding the file structure is key to understanding how the application works.

/
├── src/
│   ├── app/
│   │   ├── page.tsx                # The main chat page component.
│   │   ├── report/page.tsx         # The report page component.
│   │   ├── actions.ts              # Server Actions: Functions that run securely on the server.
│   │   └── globals.css             # Global CSS styles and Tailwind/ShadCN theme configuration.
│   │
│   ├── components/
│   │   ├── chat/                   # Components specific to the chat interface (messages, input).
│   │   ├── layout/                 # Main layout components like the Header.
│   │   ├── report/                 # Components used only on the report page (e.g., Mermaid diagram).
│   │   └── ui/                     # All the base UI components from ShadCN (Button, Card, etc.).
│   │
│   ├── ai/
│   │   ├── flows/                  # **THE AI BRAIN**: Each file defines a specific AI task.
│   │   │   ├── generate-chat-response.ts
│   │   │   ├── extract-requirements-and-generate-json.ts
│   │   │   └── ... (other report generation flows)
│   │   └── genkit.ts               # Initializes and configures Genkit to use the Google AI plugin.
│   │
│   ├── hooks/
│   │   ├── use-record.ts           # Custom React hook to manage microphone recording via the Web Speech API.
│   │   └── use-toast.ts            # Custom hook for showing pop-up notifications (toasts).
│   │
│   └── lib/
│       ├── types.ts                # TypeScript type definitions for `Message` and `Requirement`.
│       └── utils.ts                # Utility functions, like `cn()` for merging Tailwind classes.
│
├── public/                     # Static assets (not used in this project, but a standard Next.js folder).
│
├── .env                        # Stores the secret GEMINI_API_KEY for local development.
├── next.config.ts              # Configuration file for Next.js.
├── package.json                # Lists all project dependencies (npm packages) and scripts.
├── README.md                   # The main project README for GitHub.
└── PROJECT_DETAILS.md          # This file.

---

4. Logic & Flow Explanation

Flow 1: The Chat Conversation (page.tsx)

1. Initial State: The ChatInterface component (@/components/chat/chat-interface.tsx) starts with an initial "Hello" message from the AI.
2. User Input: The user types a message in the Textarea.
3. Sending a Message:
   • When the user clicks "Send", the handleSendMessage function is called.
   • The user's message is added to the messages state array, which immediately updates the UI.
   • The getAiChatResponse Server Action from actions.ts is called. This is a secure boundary; the code inside actions.ts runs only on the server.
4. Getting an AI Response:
   • Inside getAiChatResponse, the generateChatResponseFlow from @/ai/flows/generate-chat-response.ts is executed.
   • This Genkit flow sends the entire conversation history to the Gemini model with a prompt instructing it to act as a business analyst.
   • The model generates a text response.
5. Displaying the AI Response:
   • The response from the Server Action is returned to the client.
   • A new AI message object is created and added to the messages state, updating the UI.

Flow 2: Extracting Requirements & Generating the Report

1. User Action: The user clicks the "Generate Report" button.
2. Triggering the Flow: The handleGenerateReport function in ChatInterface is called.
3. Server-Side Extraction:
   • It calls the extractRequirements Server Action.
   • This action, in turn, calls the extractRequirementsAndGenerateJsonFlow Genkit flow. This flow is specifically prompted to analyze the conversation and return a structured JSON object containing an array of requirements, now including the "Inverse" type.
4. Storing Data:
   • If the extraction is successful, the array of requirements and the conversation history are saved to the browser's localStorage. This is a simple way to pass data between pages on the client-side without a complex state management library.
5. Navigating to Report Page: The app navigates the user to the /report page.
6. Building the Report (report/page.tsx):
   • The ReportPage component loads the requirements and history from localStorage.
   • It then makes parallel calls to several different Server Actions (getExecutiveSummary, getActivityDiagram, etc.).
   • Each of these actions triggers a unique Genkit flow with a specialized prompt:
     • generateExecutiveSummary: Prompted to write a professional summary.
     • generateActivityDiagram: Prompted to create a diagram in Mermaid syntax.
     • generateCostEstimation: Prompted to create an HTML table with cost estimates.
     • generateReferences: Prompted to format the source conversation.
   • As each piece of content arrives from the server, the component's state is updated, and the content is rendered into the appropriate card on the page. The GeneratedSectionContent component handles showing a loading spinner while the data is being fetched.

Voice Input (use-record.ts)

• This hook is a wrapper around the browser's webkitSpeechRecognition API.
• startRecording(): Creates a new recognition instance and tells it to start listening. It provides results in real-time (interimResults).
• stopRecording(): Stops the recognition instance.
• The transcript state is updated on the onresult event, and the ChatInterface component watches this state to update the text area, allowing for hands-free input.

This detailed breakdown should give you a solid foundation for understanding and explaining every part of your ReqBot project. Good luck!