From ca2a4e0f7f236502b44ad16f0aa452e6f14aede5 Mon Sep 17 00:00:00 2001 From: Kas-sim Date: Thu, 25 Dec 2025 21:01:48 +0500 Subject: [PATCH] Add CI Pipeline --- .github/workflows/maven.yml | 27 ++ .../Chapter 0 Overview of DevShelf.md | 61 --- .../Chapter 0_ Overview of DevShelf.md | 59 +++ ...er 1 Application Startup & Flow Control.md | 319 -------------- ...ter 1_ User Interface (UI) Presentation.md | 326 +++++++++++++++ ...).md => Chapter 2_ Book (Domain Model).md} | 130 +++--- .../Chapter 3 User Interface Presentation.md | 390 ------------------ .../Chapter 3_ Application Orchestration.md | 305 ++++++++++++++ .../Chapter 4 Search Index Management.md | 335 --------------- .../Chapter 4_ Core Search Engine.md | 316 ++++++++++++++ documentation/Chapter 5 Core Search Engine.md | 313 -------------- .../Chapter 5_ Text Preprocessing.md | 229 ++++++++++ .../Chapter 6_ Offline Search Indexing.md | 382 +++++++++++++++++ ...ter 7_ Intelligent Search Enhancements.md} | 183 ++++---- .../Chapter 8 Text Normalization Utilities.md | 224 ---------- ... => Chapter 8_ User Behavior Analytics.md} | 193 ++++----- 16 files changed, 1880 insertions(+), 1912 deletions(-) create mode 100644 .github/workflows/maven.yml delete mode 100644 documentation/Chapter 0 Overview of DevShelf.md create mode 100644 documentation/Chapter 0_ Overview of DevShelf.md delete mode 100644 documentation/Chapter 1 Application Startup & Flow Control.md create mode 100644 documentation/Chapter 1_ User Interface (UI) Presentation.md rename documentation/{Chapter 2 Book (Domain Model).md => Chapter 2_ Book (Domain Model).md} (60%) delete mode 100644 documentation/Chapter 3 User Interface Presentation.md create mode 100644 documentation/Chapter 3_ Application Orchestration.md delete mode 100644 documentation/Chapter 4 Search Index Management.md create mode 100644 documentation/Chapter 4_ Core Search Engine.md delete mode 100644 documentation/Chapter 5 Core Search Engine.md create mode 100644 documentation/Chapter 5_ Text Preprocessing.md create mode 100644 documentation/Chapter 6_ Offline Search Indexing.md rename documentation/{Chapter 7 Search Enhancement & Recommendations.md => Chapter 7_ Intelligent Search Enhancements.md} (50%) delete mode 100644 documentation/Chapter 8 Text Normalization Utilities.md rename documentation/{Chapter 6 User Interaction & Analytics.md => Chapter 8_ User Behavior Analytics.md} (57%) diff --git a/.github/workflows/maven.yml b/.github/workflows/maven.yml new file mode 100644 index 0000000..18b4c7e --- /dev/null +++ b/.github/workflows/maven.yml @@ -0,0 +1,27 @@ +name: DevShelf CI + +on: + push: + branches: [ "main" ] + pull_request: + branches: [ "main" ] + +jobs: + build: + runs-on: ubuntu-latest + + steps: + - uses: actions/checkout@v3 + + - name: Set up JDK 17 + uses: actions/setup-java@v3 + with: + java-version: '17' + distribution: 'temurin' + cache: maven + + - name: Build with Maven + run: mvn -B package --file pom.xml + + - name: Run Tests + run: mvn test \ No newline at end of file diff --git a/documentation/Chapter 0 Overview of DevShelf.md b/documentation/Chapter 0 Overview of DevShelf.md deleted file mode 100644 index 2426abf..0000000 --- a/documentation/Chapter 0 Overview of DevShelf.md +++ /dev/null @@ -1,61 +0,0 @@ - -# Tutorial: DevShelfGUI - -DevShelfGUI is a **digital library search engine** that helps users *discover and read programming books*. -It offers an intuitive interface (both command-line and graphical) to **search for books**, provides *intelligent recommendations*, -and allows users to *view book details and read PDFs*. The system also tracks user interactions to improve recommendations. - - -## Visual Overview - -```mermaid -flowchart TD - A0["Book (Domain Model) -"] - A1["Search Index Management -"] - A2["Core Search Engine -"] - A3["Search Enhancement & Recommendations -"] - A4["User Interaction & Analytics -"] - A5["Application Startup & Flow Control -"] - A6["User Interface Presentation -"] - A7["Text Normalization Utilities -"] - A5 -- "Loads Books" --> A0 - A5 -- "Loads Index" --> A1 - A5 -- "Loads Text Processors" --> A7 - A5 -- "Initializes Search" --> A2 - A5 -- "Initializes Enhancements" --> A3 - A5 -- "Initializes Analytics" --> A4 - A5 -- "Initializes UI" --> A6 - A1 -- "Indexes Books" --> A0 - A1 -- "Uses for Indexing" --> A7 - A2 -- "Uses Index Data" --> A1 - A2 -- "Processes Query" --> A7 - A2 -- "Delegates Refinement" --> A3 - A3 -- "Uses Book Data" --> A0 - A3 -- "Uses Popularity" --> A4 - A3 -- "Normalizes for Suggestions" --> A7 - A4 -- "Provides Popularity Data" --> A3 - A4 -- "Records Clicks" --> A0 - A6 -- "Requests Services" --> A5 - A6 -- "Displays Books" --> A0 -``` - -## Chapters - -1. [Application Startup & Flow Control](01_application_startup_flow_control.md) -2. [Book (Domain Model)](02_book_domain_model.md) -3. [User Interface Presentation](03_user_interface_presentation.md) -4. [Search Index Management](04_search_index_management.md) -5. [Core Search Engine](05_core_search_engine.md) -6. [User Interaction & Analytics](06_user_interaction_analytics.md) -7. [Search Enhancement & Recommendations](07_search_enhancement_recommendations.md) -8. [Text Normalization Utilities](08_text_normalization_utilities.md) - - \ No newline at end of file diff --git a/documentation/Chapter 0_ Overview of DevShelf.md b/documentation/Chapter 0_ Overview of DevShelf.md new file mode 100644 index 0000000..7f551e6 --- /dev/null +++ b/documentation/Chapter 0_ Overview of DevShelf.md @@ -0,0 +1,59 @@ +# Tutorial: DevShelf + +DevShelf is a **digital library search engine** that helps users *discover and read programming books*. +It intelligently **searches for books** using a pre-built index, provides "Did you mean?" suggestions, and offers +*personalized recommendations* based on book details and user popularity. The system also tracks user clicks +to continuously improve its search results and recommendations, presenting information through both command-line +and graphical interfaces. + + +## Visual Overview + +```mermaid +flowchart TD + A0["Book (Domain Model) +"] + A1["Application Orchestration +"] + A2["User Interface (UI) Presentation +"] + A3["Offline Search Indexing +"] + A4["Core Search Engine +"] + A5["User Behavior Analytics +"] + A6["Intelligent Search Enhancements +"] + A7["Text Preprocessing +"] + A1 -- "Loads" --> A0 + A1 -- "Loads Index Data for" --> A3 + A1 -- "Sets up" --> A2 + A1 -- "Initializes" --> A4 + A1 -- "Initializes" --> A5 + A1 -- "Initializes" --> A6 + A1 -- "Prepares tools for" --> A7 + A3 -- "Indexes" --> A0 + A3 -- "Uses" --> A7 + A3 -- "Provides Index Data to" --> A4 + A4 -- "Processes Queries with" --> A7 + A4 -- "Provides Initial Results to" --> A6 + A5 -- "Logs Clicks on" --> A0 + A5 -- "Provides Popularity to" --> A6 + A6 -- "Enhances" --> A2 + A2 -- "Sends Query to" --> A4 +``` + +## Chapters + +1. [User Interface (UI) Presentation](./Chapter%201:%20User%20Interface%20(UI)%20Presentation.md) +2. [Book (Domain Model)](./Chapter%202:%20Book%20(Domain%20Model).md) +3. [Application Orchestration](./Chapter%203:%20Application%20Orchestration.md) +4. [Core Search Engine](./Chapter%204:%20Core%20Search%20Engine.md) +5. [Text Preprocessing](./Chapter%205:%20Text%20Preprocessing.md) +6. [Offline Search Indexing](./Chapter%206:%20Offline%20Search%20Indexing.md) +7. [Intelligent Search Enhancements](./Chapter%207:%20Intelligent%20Search%20Enhancements.md) +8. [User Behavior Analytics](./Chapter%208:%20User%20Behavior%20Analytics.md) + + diff --git a/documentation/Chapter 1 Application Startup & Flow Control.md b/documentation/Chapter 1 Application Startup & Flow Control.md deleted file mode 100644 index 0ca7e7c..0000000 --- a/documentation/Chapter 1 Application Startup & Flow Control.md +++ /dev/null @@ -1,319 +0,0 @@ - - -Welcome to DevShelf! This tutorial will guide you through how our digital library application works, starting from the very beginning: how it wakes up and gets ready to serve you. - -### The Application's "Main Director" - -Imagine our DevShelf application as a grand play. For any play to begin, you need a **Main Director**. This director doesn't act in the play, but they are crucial for making sure everything is in place before the curtain rises. They: - -1. **Gather the Props:** Load all the books and the special "search index" (a magical guide that helps find books quickly). -2. **Assemble the Actors:** Bring together all the specialized "services" or "smart tools" like the `QueryProcessor` (who understands your search), the `ReRanker` (who makes sure the best books appear first), and the `Suggester` (who helps with typos). -3. **Set the Stage:** Prepare the user interface, whether it's a simple text-based command line (CLI) or a fancy graphical window (GUI). -4. **Signal the Start:** Once everything is ready, they tell the play to begin, allowing you, the user, to interact with the application. - -This "Main Director" role is exactly what "Application Startup & Flow Control" is all about in DevShelf. It's the brain that orchestrates the entire application, making sure it initializes correctly and manages the overall sequence of operations. - -### Your First Interaction: Starting DevShelf - -Before you can search for your favorite book, DevShelf needs to start. We offer two ways to use DevShelf: a Command Line Interface (CLI) where you type commands, and a Graphical User Interface (GUI) with buttons and windows. - -Let's see how you'd typically start each version: - -#### Starting the CLI Version - -To start the CLI version, you would run the `Main` class. - -**`src/main/java/core/Main.java` (Simplified)** -```java -package core; - -import storage.BookLoader; -import storage.IndexLoader; -import ui.cli.CliView; -// ... other imports - -public class Main { - public static void main(String[] args) { - System.out.println("πŸ“– Assembling DevShelf Engine..."); - - // 1. Load All Data (e.g., books and search index) - // BookLoader bookLoader = new BookLoader(...); - // List allBooks = bookLoader.loadBooks(); - // IndexLoader indexLoader = new IndexLoader(...); - // SearchIndexData loadedData = indexLoader.loadIndex(); - - // 2. Build All Services (our smart tools) - // QueryProcessor queryProcessor = new QueryProcessor(...); - // ReRanker reRanker = new ReRanker(...); - // Suggester suggester = new Suggester(...); - // ... and other services - - // 3. Build The UI (the CLI view) - CliView view = new CliView(); - - // 4. Assemble the Controller & Start - // BookSearchEngine engine = new BookSearchEngine(bookMap, queryProcessor, ...); - // engine.run(); // This starts the main loop! - System.out.println("...Assembly complete. Starting application."); - } -} -``` -When you run `Main.java`, it prints messages like "πŸ“– Assembling DevShelf Engine..." as it prepares everything. Then, it will present you with the command-line interface, ready for your search queries. - -#### Starting the GUI Version - -For the GUI version, we use a special `Launcher` class to make sure JavaFX (the GUI technology) starts correctly. - -**`src/main/java/core/Launcher.java`** -```java -package core; - -public class Launcher { - public static void main(String[] args) { - // We delegate to the real JavaFX class. - // This tricks the JVM into loading the classpath correctly first. - GuiMain.main(args); - } -} -``` -This `Launcher` simply calls `GuiMain.main(args)`. The `GuiMain` class then does the actual work of setting up the graphical window: - -**`src/main/java/core/GuiMain.java` (Simplified)** -```java -package core; - -import javafx.application.Application; -import javafx.fxml.FXMLLoader; -import javafx.scene.Scene; -import javafx.stage.Stage; -import ui.gui.controllers.MainViewController; -import ui.gui.services.DevShelfService; -// ... other imports - -public class GuiMain extends Application { // Extends Application for JavaFX - - @Override - public void start(Stage stage) throws Exception { - System.out.println("πŸš€ Starting DevShelf GUI..."); - - // 1. Load Backend Services (Same idea as CLI: books, index, etc.) - // BookLoader bookLoader = new BookLoader(...); - // Map bookMap = ...; - // QueryProcessor queryProcessor = ...; - // ... and other services - - // 2. Create the App Brain (a special service for the GUI) - // DevShelfService service = new DevShelfService(bookMap, queryProcessor, ...); - - // 3. Load the UI (from an FXML file, which describes the window layout) - // FXMLLoader loader = new FXMLLoader(getClass().getResource("/ui/gui/fxml/MainView.fxml")); - // Parent root = loader.load(); - - // 4. Inject the Brain into the Controller (connects UI to logic) - // MainViewController controller = loader.getController(); - // controller.setService(service); - - // 5. Show Window - // Scene scene = new Scene(root); - // stage.setScene(scene); - // stage.setTitle("DevShelf - Library Search Engine"); - // stage.show(); - - System.out.println("βœ… GUI Started successfully."); - } - - public static void main(String[] args) { - launch(args); // This calls the start method above - } -} -``` -When `GuiMain` runs, you'll see messages like "πŸš€ Starting DevShelf GUI..." and then a beautiful DevShelf window will pop up on your screen, ready for you to type in the search bar. - -### Under the Hood: The Startup Sequence - -Whether you launch the CLI or GUI, the core steps for getting DevShelf ready are very similar. Let's visualize this process like a coordinated dance: - -```mermaid -sequenceDiagram - participant You - participant Launcher/Main App - participant Storage Loaders - participant Core Services - participant User Interface - participant Search Engine - - You->>Launcher/Main App: "Start DevShelf!" - Launcher/Main App->>Storage Loaders: "Load all books & search index data" - Note over Storage Loaders: Reads data from `book.json` and `index_data.json` - Storage Loaders-->>Launcher/Main App: "Here's the data!" - Launcher/Main App->>Core Services: "Create smart tools (QueryProcessor, ReRanker, etc.)" - Note over Core Services: These tools understand queries, rank results, suggest typos - Core Services-->>Launcher/Main App: "Tools are ready!" - Launcher/Main App->>User Interface: "Prepare the display (CLI text or GUI window)" - User Interface-->>Launcher/Main App: "Display is ready!" - Launcher/Main App->>Search Engine: "Assemble the main 'engine' with data, tools, and UI" - Search Engine->>User Interface: "Show welcome message / main search screen" - User Interface-->>You: "DevShelf is ready to use!" - You->>User Interface: "Type a search query..." -``` - -This sequence shows how the "Application Startup & Flow Control" layer (`Launcher/Main App` and `Search Engine` in the diagram) brings together different parts of the system. - -### Comparing CLI and GUI Startup - -While the core steps are similar, there are some differences in how the CLI and GUI versions set things up: - -| Feature | CLI Version (`core/Main.java`) | GUI Version (`core/GuiMain.java`) | -| :------------------------ | :---------------------------------------------------------------- | :--------------------------------------------------------------- | -| **Main Entry Point** | `public static void main(String[] args)` directly in `Main.java` | `main` in `Launcher.java` calls `GuiMain.main(args)`, which uses `start()` method | -| **User Interface Class** | `CliView` ([User Interface Presentation](03_user_interface_presentation_.md)) | JavaFX FXML (`MainView.fxml`), managed by `MainViewController` ([User Interface Presentation](03_user_interface_presentation_.md)) | -| **Core Logic Controller** | `BookSearchEngine` ([Core Search Engine](05_core_search_engine_.md)) | `DevShelfService` (a dedicated service for the GUI) | -| **Interaction Flow** | `BookSearchEngine.run()` contains a `while(true)` loop for user input | UI events (e.g., button clicks) call methods in `DevShelfService` | - -Notice how both versions load the same underlying data (books, search index) and create the same smart tools (like `QueryProcessor` and `ReRanker`). The main difference is how they connect these tools to their specific user interface. - -#### The CLI's Main Loop - -Once the CLI version starts, its `BookSearchEngine` takes over. It enters a continuous loop, waiting for your commands: - -**`src/main/java/core/BookSearchEngine.java` (Simplified `run` method)** -```java -package core; - -import ui.cli.CliView; -// ... other imports - -public class BookSearchEngine { - private final CliView view; // Our CLI display tool - // ... other services and state - - public BookSearchEngine( /* ... services, CliView view */ ) { - this.view = view; - // ... initialize state - } - - public void run() { - view.showWelcomeMessage(bookMap.size()); // Greet the user - while (true) { // This loop keeps the application running - String query = view.getSearchQuery(); // Ask the user for a search - if (query.equalsIgnoreCase("exit")) { // User wants to quit - view.showExitMessage(); - break; // Exit the loop - } - if (query.isEmpty()) continue; // Skip empty queries - - processQuery(query); // Handle the search request - } - } - // ... other methods like processQuery, applyFilters, handleFilterMenu etc. -} -``` -This `run()` method is the heart of the CLI application's "flow control." It continuously: -1. **Gets Input:** `view.getSearchQuery()` asks you what you want to search for. -2. **Processes:** Calls `processQuery(query)` to handle the actual search. -3. **Repeats:** Goes back to step 1 until you type "exit." - -The `processQuery` method then orchestrates the search: - -**`src/main/java/core/BookSearchEngine.java` (Simplified `processQuery` method)** -```java -// Inside BookSearchEngine class -private void processQuery(String query) { - // 1. Search! Ask the QueryProcessor (our smart search tool) - // List tfIdfResults = queryProcessor.search(query); - - // 2. Re-rank results (make sure the best ones are on top) - // List rankedResults = reRanker.reRank(tfIdfResults, query); - - // 3. Prepare books for display - // final List initialBooks = rankedResults.stream()...; - - // This nested loop lets you filter/sort results for the *current* query - while (true) { - // A. Apply any filters or sorting you've set - // List filteredBooks = applyFilters(initialBooks); - // applySort(filteredBooks); - - // B. Display the results - // view.showResults(query, filteredBooks); - - // C. Get your next action (filter, sort, new search, etc.) - // String choice = view.getActionPrompt(); - // switch (choice) { - // case "f": handleFilterMenu(); break; - // case "n": return; // Go back to the main search loop - // // ... other actions - // } - } -} -``` -Inside `processQuery`, there's another loop that allows you to refine your search results (filter, sort) before going back to the main `run()` loop for a brand new search. This shows a clear flow of control, moving from getting a query to processing it, displaying results, and then asking for the next action. - -#### The GUI's Service Approach - -The GUI works a bit differently. Instead of a `while(true)` loop, the `DevShelfService` handles specific requests from the user interface. When you type in the search bar and press Enter, the GUI controller calls the `search` method of `DevShelfService`: - -**`src/main/java/ui/gui/services/DevShelfService.java` (Simplified `search` method)** -```java -package ui.gui.services; - -import domain.Book; -import domain.SearchResult; -import features.search.QueryProcessor; -import features.search.ReRanker; -import features.search.Suggester; -// ... other imports - -public class DevShelfService { - private final QueryProcessor queryProcessor; - private final ReRanker reRanker; - private final Suggester suggester; - // ... other services and bookMap - - public DevShelfService( /* ... services and bookMap */ ) { - this.queryProcessor = queryProcessor; - this.reRanker = reRanker; - this.suggester = suggester; - // ... initialize other services - } - - public SearchResponse search(String query) { - System.out.println("πŸ” GUI Processing Query: [" + query + "]"); - - // 1. Raw Search (using our smart QueryProcessor tool) - // List results = queryProcessor.search(query); - - // 2. Handle No Results / Typos (ask the Suggester if needed) - // if (results.isEmpty()) { - // String suggestion = suggester.suggestSimilar(query); - // if (suggestion != null) { /* ... search with suggestion ... */ } - // } - - // 3. Re-Rank (using our ReRanker tool to sort by popularity/relevance) - // List rankedResults = reRanker.reRank(results, usedQuery); - - // 4. Convert to Books (so the UI can display them nicely) - // List books = new ArrayList<>(); - // for (SearchResult res : rankedResults) { /* ... add book to list ... */ } - - // return new SearchResponse(books, isSuggestion, usedQuery); - return null; // Simplified return - } - // ... other methods like getRecommendationsFor, logClick etc. -} -``` -This `search` method is called each time you submit a query in the GUI. It performs the same core steps as `processQuery` in the CLI: search, re-rank, and handle suggestions. However, instead of looping for more actions, it returns a `SearchResponse` object containing the results directly to the GUI controller, which then updates the display. - -### Conclusion - -In this chapter, we learned that "Application Startup & Flow Control" is like the main director of our DevShelf application. It handles the critical tasks of: -* **Initialization:** Loading all essential data like books and the search index. -* **Service Assembly:** Creating and preparing all the specialized tools (like `QueryProcessor`, `ReRanker`, `Suggester`) that make DevShelf smart. -* **User Interface Setup:** Getting either the Command Line Interface (CLI) or the Graphical User Interface (GUI) ready for you. -* **Orchestration:** Managing the overall flow, whether it's a continuous command loop in the CLI or handling specific requests from the GUI. - -This entire process ensures that when you finally see DevShelf, everything is perfectly set up and ready for your search adventure! - -Next, we'll dive into the most important "prop" in our play: the `Book` itself, which is our core piece of data. - -[Next Chapter: Book (Domain Model)](02_book__domain_model__.md) \ No newline at end of file diff --git a/documentation/Chapter 1_ User Interface (UI) Presentation.md b/documentation/Chapter 1_ User Interface (UI) Presentation.md new file mode 100644 index 0000000..0825c70 --- /dev/null +++ b/documentation/Chapter 1_ User Interface (UI) Presentation.md @@ -0,0 +1,326 @@ +# Chapter 1: User Interface (UI) Presentation + +Welcome to the exciting world of DevShelf! This is where we begin our journey into understanding how this awesome digital library works. Think of DevShelf like a person you're meeting for the first time. The very first thing you notice is their face – how they look, how they smile, and how they react when you talk to them. + +In the world of software, this "face" is called the **User Interface (UI)**. + +### What is the "Face" of DevShelf? + +The User Interface (UI) Presentation is literally **everything you see and interact with** when you use DevShelf. It's how the application "talks" to you and how you "talk" back to it. + +Imagine DevShelf as a super-smart librarian. This librarian knows about thousands of books, but without a way to communicate, you'd never know what books they have! The UI is the librarian's ability to: + +1. **Show Information:** Display a list of books, tell you a book's title, author, and rating, or show a welcome message. +2. **Gather Input:** Understand when you type a search query, click a button, or choose an option. + +It takes all the complex information and powerful search logic happening "behind the scenes" and translates it into something simple, clear, and easy for you to use. + +#### The Problem Our UI Solves + +Let's consider a central task: **finding and viewing books**. + +You want to search for "Java" books. How do you type "Java"? And once DevShelf finds those books, how does it *show* them to you? Without a UI, DevShelf would be a brilliant system that couldn't interact with anyone! Our UI solves this by providing the visual elements and interaction points needed to make this simple. + +### Two Ways DevShelf Shows Its Face: CLI vs. GUI + +DevShelf actually has two different "faces," or types of UIs, to cater to different user preferences: + +1. **CLI (Command Line Interface):** This is a text-based interface. You type commands, and DevShelf responds with text. It's like talking to our librarian by writing notes and getting notes back. +2. **GUI (Graphical User Interface):** This is a visual interface with windows, buttons, pictures, and more. You use your mouse and keyboard to click, type, and navigate. It's like talking to our librarian face-to-face in a beautifully designed library. + +Both UIs achieve the same goal: letting you search for books and see the results. + +#### 1. The CLI's Face: Simple Text Commands + +In the CLI version, the `CliView` class is the main component for displaying text and reading your input. It’s straightforward: it prints messages, then waits for you to type something. + +**`src/main/java/ui/cli/CliView.java` (Simplified)** +```java +package ui.cli; + +import domain.Book; // Our book data structure from the next chapter +import java.util.List; +import java.util.Scanner; // Tool to read keyboard input + +public class CliView { + private final Scanner scanner = new Scanner(System.in); + + public void showResults(String query, List books) { + if (books.isEmpty()) { + System.out.println("❌ No results found for \"" + query + "\""); + return; + } + System.out.println("βœ… Showing results for \"" + query + "\":"); + for (int i = 0; i < books.size() && i < 3; i++) { // Show top 3 for brevity + Book book = books.get(i); + System.out.printf(" [%d] %s by %s (Rating: %.1f)\n", + i + 1, book.getTitle(), book.getAuthor(), book.getRating()); + } + } + + public String getSearchQuery() { + System.out.print("\nπŸ” Enter search query (or 'exit'): "); + return scanner.nextLine().trim(); // Reads what you type + } +} +``` +* `showResults`: This method takes a search query and a list of `Book` objects (which we'll learn more about in [Book (Domain Model)](02_book__domain_model__.md)). It then prints out the details of each book directly to your console. +* `getSearchQuery`: This method displays a prompt asking you to type your search query. It then waits until you press Enter, captures your typed text, and returns it. + +**Example CLI Interaction:** + +``` +πŸ” Enter search query (or 'exit'): Java + +βœ… Showing results for "Java": + [1] Clean Code by Robert C. Martin (Rating: 4.6) + [2] Effective Java by Joshua Bloch (Rating: 4.8) + [3] Head First Java by Kathy Sierra (Rating: 4.3) +``` +In this example, `getSearchQuery` printed the prompt, you typed "Java", and then `showResults` displayed the books found. + +#### 2. The GUI's Face: Windows, Buttons, and Images + +The GUI version of DevShelf uses a special framework called **JavaFX** to create visually rich interfaces. Instead of just printing text, it draws everything: windows, buttons, text boxes, and even book covers! + +Building a GUI with JavaFX often involves two main ingredients: + +1. **FXML Files (The Blueprints):** These are like architectural drawings for what your screens look like. They describe *where* each button, label, and image should be placed, and *how* they are organized. For DevShelf, we have blueprints like `MainView.fxml` (for the main search screen) and `BookCard.fxml` (for how a single book looks in the results list). +2. **Controller Classes (The Workers):** These are Java classes (like `.java` files in the `ui.gui.controllers` package) that are the "brains" behind the FXML blueprints. They handle *what happens* when you click something, *how to fill* a text field with data, and *how to react* to your actions. Each FXML blueprint usually has a dedicated worker (controller). + +Let's trace how these pieces work together when you search for a book in the GUI: + +```mermaid +sequenceDiagram + participant You + participant MainViewController + participant DevShelfService + participant BookCardController + participant GUI Window + + You->>MainViewController: Type "Python" in search bar, press Enter + MainViewController->>DevShelfService: search("Python") + Note over DevShelfService: Finds books (e.g., "Fluent Python", "Python Crash Course") + DevShelfService-->>MainViewController: Returns List + loop For each Book in the list + MainViewController->>MainViewController: Load BookCard.fxml blueprint + MainViewController->>BookCardController: new instance + MainViewController->>BookCardController: setData(a Book object) + Note over BookCardController: Fills labels, loads cover image for this book + BookCardController-->>MainViewController: Ready visual Book Card element + MainViewController->>GUI Window: Add Book Card to results list + end + MainViewController-->>GUI Window: Update status message + GUI Window-->>You: Displays list of visual Book Cards +``` +This diagram shows that when you type a query in the GUI, the `MainViewController` (the main screen's brain) asks a central `DevShelfService` (the application's core brain) for results. For each [Book (Domain Model)](02_book__domain_model__.md) it gets back, the `MainViewController` uses the `BookCard.fxml` blueprint and its `BookCardController` worker to create a visual "card" for that book, and then displays it in the window. + +### Displaying Search Results and Handling New Searches (Code Examples) + +Let's look at how the GUI code actually makes this happen. + +#### The Main Search Screen (`MainView.fxml` & `MainViewController.java`) + +The `MainView.fxml` is the blueprint for our main screen. It defines elements like the search box and where the results go. + +**`src/main/resources/ui/gui/fxml/MainView.fxml` (Snippet)** +```xml + + + +