1 /Users/admin/Desktop/cloudbox99_helpdesk/
2 ├───.DS_Store # macOS system file for folder display settings.
3 ├───package-lock.json # Locks exact versions of frontend (npm) dependencies.
4 ├───todo.md # Project roadmap and task list, outlining development
phases and features.
5│
6 ├───.conda/ # Conda virtual environment for Python, managing
isolated Python packages.
7 │ ├───.gitignore # Specifies files/folders to ignore in Git for the
.conda environment.
8 │ ├───bin/ # Executables for the Conda environment (e.g., python,
pip).
9 │ ├───conda-meta/ # Metadata for Conda packages installed in this
environment.
10 │ ├───etc/ # Configuration files for the Conda environment.
11 │ ├───include/ # C/C++ header files for packages in the Conda
environment.
12 │ ├───lib/ # Libraries for packages in the Conda environment.
13 │ ├───man/ # Manual pages for commands in the Conda environment.
14 │ ├───share/ # Shared data for packages in the Conda environment.
15 │ └───ssl/ # SSL certificates for the Conda environment.
16 │
17 ├───.venv/ # Python virtual environment (often created by `python
-m venv`), similar to .conda but typically lighter.
18 │ ├───.gitignore # Specifies files/folders to ignore in Git for the
.venv environment.
19 │ ├───pyvenv.cfg # Configuration file for the Python virtual
environment.
20 │ ├───bin/ # Executables for the .venv environment (e.g., python,
pip).
21 │ ├───include/ # C/C++ header files for packages in the .venv
environment.
22 │ └───lib/ # Libraries for packages in the .venv environment.
23 │
24 ├───backend/ # Contains the Flask-based API server.
25 │ ├───.DS_Store # macOS system file.
26 │ ├───populate_kb.py # Script to initialize and populate the SQLite
knowledge base database with solutions.
27 │ ├───requirements.txt # Lists all Python dependencies required for the
backend.
28 │ ├───.git/ # Git repository for the backend (if it's a separate
repo).
29 │ ├───.venv/ # Dedicated Python virtual environment for the backend.
30 │ └───src/ # Backend Python source code.
31 │ ├───__init__.py # Marks `src` as a Python package.
32 │ ├───.DS_Store # macOS system file.
33 │ ├───database.py # Defines the SQLAlchemy database models (e.g.,
Solution, Feedback) and initializes the database.
34 │ ├───main.py # The main Flask application entry point; sets up the
app, registers blueprints, and runs the server.
35 │ ├───__pycache__/ # Directory for Python compiled bytecode.
36 │ ├───database/ # Contains the SQLite database file (`app.db`).
37 │ ├───models/ # Defines individual SQLAlchemy models (e.g.,
`Solution` for KB entries, `Feedback` for user feedback).
38 │ ├───routes/ # Defines Flask Blueprints for API endpoints.
39 │ │ ├───user.py # (Potentially) User-related API routes, though not
heavily used in the helpdesk core.
40 │ │ └───helpdesk.py # Core helpdesk API routes: `analyze` (for query
processing), `feedback` (for submission), and `serve_pdf`.
41 │ └───static/ # Static files served directly by the Flask backend.
42 │ └───pdfs/ # Stores the PDF documents that form the knowledge
base.
43 │
44 └───frontend/ # Contains the React-based user interface.
45 ├───.gitignore # Specifies files/folders to ignore in Git for the
frontend.
46 ├───components.json # Configuration for UI components (e.g., Shadcn UI,
defining component properties).
47 ├───eslint.config.js # ESLint configuration for linting (code quality and
style checking) React/JavaScript code.
48 ├───index.html # The main HTML file that serves as the entry point for
the React application.
49 ├───jsconfig.json # JavaScript configuration file, primarily for VS Code
to understand path aliases (e.g., `@/`).
50 ├───package-lock.json # Locks exact versions of frontend (npm) dependencies.
51 ├───package.json # Defines frontend project metadata, scripts (e.g.,
`dev`, `build`), and dependencies.
52 ├───pnpm-lock.yaml # Lock file for pnpm package manager (if used instead
of npm).
53 ├───vite.config.js # Configuration file for Vite, the build tool used for
the React application.
54 ├───.git/ # Git repository for the frontend (if it's a separate
repo).
55 ├───dist/ # Output directory for the production-ready built
frontend assets.
56 ├───node_modules/ # Directory containing all installed JavaScript
dependencies for the frontend.
57 ├───public/ # Static assets that are served directly (e.g.,
favicon, images).
58 └───src/ # Frontend React source code.
59 ├───assets/ # Stores static assets like images or fonts used by the
frontend.
60 ├───components/ # Reusable React components.
61 │ ├───SecurePDFViewer.jsx # Component responsible for securely displaying
PDF documents on a canvas.
62 │ └───ui/ # Contains UI components (e.g., Button, Textarea, Card,
Badge) likely from a UI library like Shadcn UI.
63 ├───hooks/ # Custom React Hooks for encapsulating reusable
stateful logic.
64 ├───lib/ # Utility functions or helper libraries.
65 ├───App.css # Application-specific CSS styles.
66 ├───App.jsx # The main React application component, orchestrating
the UI and handling user interactions.
67 ├───index.css # Global CSS styles applied to the entire application.
68 └───main.jsx # The main entry point for the React application, where
the App component is rendered into the DOM.
Top-Level Files:
* package-lock.json:
* Role: This file is automatically generated by npm (Node Package Manager) and records
the
exact version of every dependency (and its sub-dependencies) that was installed for the
frontend project.
* Workflow Contribution: Ensures that anyone else setting up the project (or you on a
different machine) gets the exact same set of frontend dependencies, preventing "it
works
on my machine" issues due to version discrepancies.
* todo.md:
* Role: A markdown file serving as a project management document. It outlines the
planned
phases, features, and tasks for the helpdesk application's development.
* Workflow Contribution: Provides a high-level overview of the project's scope and
progress,
guiding development efforts and serving as a reference for stakeholders.
Python Virtual Environments:
* .conda/ and .venv/:
* Role: Both are Python virtual environments. They create isolated environments for
Python
projects, meaning that dependencies installed for one project don't interfere with
others.
.conda is managed by Anaconda/Miniconda, while .venv is a standard Python module.
In this
project, .venv within the backend/ directory is the primary one used for the backend
application.
* Workflow Contribution: Ensures that the backend application runs with its specific
Python
version and library dependencies without conflicts from other Python projects on the
system.
* bin/: Contains executable scripts (like python, pip) specific to this virtual environment.
* conda-meta/ (for .conda): Stores metadata about packages installed via Conda.
* lib/: Contains the Python libraries installed within this specific environment.
backend/ Directory:
This directory houses the Flask-based API server, which is the brain of the helpdesk system.
It
handles query analysis, solution retrieval, and feedback processing.
* populate_kb.py:
* Role: A standalone Python script used to initialize and populate the SQLite database
(app.db) with initial knowledge base entries (solutions). It defines a
KNOWLEDGE_BASE_DATA
dictionary containing metadata for each solution, including keywords, title, content,
and
the path to its associated PDF.
* Workflow Contribution: This script is run once (or whenever the knowledge base needs
a full
refresh/update) to set up the core data that the helpdesk system will use to find
solutions.
It's crucial for setting up the initial state of the knowledge base.
* requirements.txt:
* Role: Lists all the Python packages and their versions that the backend application
depends
on (e.g., Flask, SQLAlchemy, spaCy).
* Workflow Contribution: Used by pip install -r requirements.txt to ensure all necessary
libraries are installed in the backend's virtual environment, making the application
runnable.
* .venv/:
* Role: The dedicated Python virtual environment for the backend application, ensuring
its
dependencies are isolated.
* Workflow Contribution: Provides the runtime environment for the Flask server and its
scripts.
* src/:
* This is the core source code directory for the backend.
* database.py:
* Role: Defines the database schema using SQLAlchemy (an Object Relational
Mapper). It
sets up the SQLite database connection and defines the Solution model (for
knowledge
base entries) and the Feedback model (for user feedback).
* Workflow Contribution: Establishes the structure for storing and retrieving all
persistent data for the helpdesk system.
* main.py:
* Role: The main entry point for the Flask application. It initializes the Flask app,
configures CORS (Cross-Origin Resource Sharing) for frontend communication,
connects to
the database, registers the API blueprints, and defines routes for serving static files
(including index.html for the frontend and PDFs).
* Workflow Contribution: This is the central orchestrator of the backend. When the
backend
server starts, main.py sets up everything needed for the API to function and listen for
requests.
* routes/:
* This directory contains Flask Blueprints, which are modular components for
organizing
API routes.
* helpdesk.py:
* Role: Contains the core logic for the helpdesk API.
* @helpdesk_bp.route("/analyze", methods=["POST"]): This is the primary
endpoint. It
receives the user's problem text from the frontend.
* extract_keywords(): Analyzes the input text to pull out important terms (using
spaCy or a simpler regex fallback).
* needs_disambiguation(): Determines if the query is ambiguous (e.g., a technical
question without an explicit OS) and requires clarification from the user.
* find_matching_solution(): Searches the database for the best-matching solution
based on extracted keywords.
* @helpdesk_bp.route("/feedback", methods=["POST"]): Handles submission of
user
feedback on solutions.
* @helpdesk_bp.route("/pdf/<filename>"): Securely serves PDF files from the
knowledge
base, preventing direct downloads.
* Workflow Contribution: This file is critical for processing user queries, deciding if
clarification is needed, finding solutions, and handling feedback. It's where the
"intelligence" of the helpdesk resides.
* static/:
* Role: A directory for static files that the Flask server can serve directly.
* pdfs/:
* Role: This subdirectory is the physical storage location for all the PDF documents
that constitute the knowledge base. Each PDF here corresponds to an entry in the
database.
* Workflow Contribution: When a solution is found, the serve_pdf endpoint
retrieves
the relevant PDF from this folder and streams it to the frontend for secure viewing.
frontend/ Directory:
This directory contains the React-based user interface that users interact with.
* package.json:
* Role: Defines the frontend project's metadata (name, version), scripts for development
and
building (e.g., npm run dev, npm run build), and lists all direct dependencies (e.g.,
react,
react-dom, vite, tailwindcss).
* Workflow Contribution: Essential for managing frontend dependencies and defining
common
development tasks.
* vite.config.js:
* Role: Configuration file for Vite, a fast build tool for modern web projects. It specifies
how the React application should be built, including plugins (like @vitejs/plugin-react
for
React support and @tailwindcss/vite for Tailwind CSS integration) and path aliases (like
@
for src/).
* Workflow Contribution: Controls the development server (hot module reloading) and
the
production build process for the frontend.
* jsconfig.json:
* Role: A configuration file for JavaScript projects, primarily used by IDEs (like VS Code)
to
understand project structure, especially path aliases (e.g., @/* mapping to src/*).
* Workflow Contribution: Improves developer experience by enabling correct auto-
completion and
navigation for aliased imports.
* public/:
* Role: Contains static assets that are copied directly to the build output (dist/) without
being processed by Vite. This often includes index.html, favicon.ico, or other static
images.
* Workflow Contribution: Provides direct access to assets that don't require bundling or
transformation.
* dist/:
* Role: The output directory where the optimized and bundled production-ready
frontend assets
(HTML, CSS, JavaScript) are placed after running npm run build.
* Workflow Contribution: This is the deployable version of the frontend application.
* node_modules/:
* Role: Contains all the installed npm packages (JavaScript libraries and frameworks) that
the
frontend project depends on.
* Workflow Contribution: Provides all the necessary code for the React application to
run.
* src/:
* This is the core source code directory for the frontend.
* main.jsx:
* Role: The main entry point for the React application. It imports the root App
component
and renders it into the HTML document's root element.
* Workflow Contribution: This is the first piece of JavaScript code that runs when the
frontend loads, bootstrapping the entire React application.
* App.jsx:
* Role: The main React component that orchestrates the entire user interface. It
manages
the application's state (e.g., problemText, result, isAnalyzing), handles user input,
makes API calls to the backend, and renders different UI elements based on the
application's state (input form, solution display, clarification questions, feedback
form, PDF viewer).
* Workflow Contribution: This file defines the user experience and interaction flow. It's
where the frontend communicates with the backend and dynamically updates the UI.
* components/:
* Role: A directory for reusable React components.
* SecurePDFViewer.jsx:
* Role: A custom React component responsible for securely displaying PDF
documents. It
uses pdfjs-dist to render PDF pages onto an HTML <canvas> element, preventing
direct
download, text selection, and copying. It also includes navigation for multiple
pages.
* Workflow Contribution: Provides the secure and interactive PDF viewing
experience,
which is a core feature of the helpdesk system.
* ui/:
* Role: Likely contains UI components from a component library (e.g., Shadcn UI).
These
are pre-built, styled, and accessible UI elements like Button, Textarea, Card,
Badge, DropdownMenu, etc.
* Workflow Contribution: Speeds up UI development and ensures a consistent and
attractive design across the application.
* App.css and index.css:
* Role: CSS files for styling the React application. index.css typically contains global
styles, while App.css might have styles specific to the App component or other main
layouts.
* Workflow Contribution: Defines the visual appearance and layout of the frontend.
This detailed breakdown should provide a comprehensive understanding of each
component's role
and how they work together to form the cloudbox99 helpdesk application.
Work flow
Detailed Workflow: Cloudbox99 Helpdesk Application
This workflow describes the journey of a user's query through the system, from initial input
to receiving a solution or clarification.
Phase 1: Initial Query Submission
1. User Action (Frontend - `App.jsx`):
* The user navigates to http://localhost:5173.
* They type their technical issue (e.g., "How to configure a web server?") into the
"Describe your issue" Textarea component.
* They click the "Analyze My Issue" Button.
2. Frontend Processing (Frontend - `App.jsx`):
* The handleAnalyzeIssue function is triggered.
* It retrieves the problemText from the state.
* It sets isAnalyzing state to true (disabling the button and showing "Analyzing...").
* It initiates an asynchronous fetch request
3. API Request (Frontend to Backend):
* An HTTP POST request is sent to http://127.0.0.1:5001/api/helpdesk/analyze.
* The request body contains a JSON object: {"problem_text": "How to configure a web
server?"}.
Phase 2: Backend Analysis and Disambiguation
4. Backend Receives Request (Backend - `main.py` -> `src/routes/helpdesk.py`):
* The Flask application (main.py) routes the request to the analyze_issue() function
within the helpdesk_bp blueprint (src/routes/helpdesk.py).
* It extracts the problem_text from the incoming JSON request.
5. Keyword Extraction (Backend - `src/routes/helpdesk.py`):
* The extract_keywords(problem_text) function is called.
* If spaCy is available (`SPACY_AVAILABLE` is `True`): extract_keywords_spacy() uses NLP
to identify nouns, verbs, adjectives, and proper nouns, filtering out stop words and
punctuation.
* If spaCy is not available: extract_keywords_simple() uses a regex and a predefined list
Of stop words to extract basic keywords.
* The extracted keywords list (e.g., ["configure", "web", "server"]) is returned.
6. Disambiguation Check (Backend - `src/routes/helpdesk.py`):
* The needs_disambiguation(keywords, problem_text) function is called.
* It checks two conditions:
* is_technical_query: Is len(keywords) > 0? (i.e., were any technical terms found?)
* has_os: Does the original problem_text (case-insensitive) contain any of ["windows",
"linux", "ubuntu", "centos"]?
* Decision Point:
* If `is_technical_query` is `True` AND `has_os` is `False`: The function returns True,
indicating a need for clarification.
* Otherwise: The function returns False.
7. Backend Response (Disambiguation) (Backend - `src/routes/helpdesk.py`):
* If `needs_disambiguation` returned `True`:
* The analyze_issue function constructs a JSON response with type: "clarification".
* message: "I see you're asking about a server. To give you the right solution, please
select the server type:"
* options: ["Windows", "Linux"]
* This JSON response is sent back to the frontend.
Phase 3: User Clarification (if needed)
8. Frontend Displays Clarification (Frontend - `App.jsx`):
* The frontend receives the clarification response.
* It updates the result state, which triggers a re-render of the "Dynamic Results Area".
* The Badge shows "Need More Info", the message is displayed, and two Button
Components ("Windows", "Linux") are rendered.
9. User Action (Frontend - `App.jsx`):
* The user clicks one of the clarification buttons (e.g., "Windows").
10. Frontend Re-analysis (Frontend - `App.jsx`):
* The handleClarificationChoice function is triggered.
* It appends the chosen option to the original problemText (e.g., "How to configure a
Web server? (Windows)").
* It then re-initiates the fetch request to /api/helpdesk/analyze with the clarified
problem_text.
* The workflow returns to Step 4.
Phase 4: Solution Matching and Delivery
11. Backend Solution Matching (Backend - `src/routes/helpdesk.py`):
* (This step occurs if needs_disambiguation returned False, or after a clarification has
Been provided and re-analyzed).
* The find_matching_solution(keywords) function is called.
* It queries the Database (`src/database.py` -> `app.db`) for Solution entries.
* For each Solution in the database:
* It splits the solution.keywords string into a list.
* It calculates a score based on how many extracted keywords from the user's query
Match the solution_keywords.
* It applies OS-specific boosting/penalties if OS keywords are present in the query and
solution.
* It identifies the best_match (solution with the highest score).
* Decision Point:
* If `best_score >= 1` (or configured threshold): The function returns a dictionary
containing the title, content, and pdf_url of the best_match.
* Otherwise: The function returns None.
12. Backend Response (Solution or Logged) (Backend - `src/routes/helpdesk.py`):
* If a `solution` was found:
* The analyze_issue function constructs a JSON response with type: "solution",
Including the solution's title, content, and pdf_url.
* This JSON response is sent back to the frontend.
* If `solution` was `None` (no match found):
* The problem_text and keywords are added to the LOGGED_QUERIES list (a mock in-
Memory storage for now).
* A JSON response with type: "logged" and a message indicating the query has been
Logged is sent back to the frontend.
Phase 5: Frontend Display and Interaction
13. Frontend Displays Result (Frontend - `App.jsx`):
* The frontend receives the solution or logged response.
* It updates the result state, triggering a re-render.
* If `type: "solution"`:
* Displays the solution title and content.
* Renders a "View Solution PDF" Button.
* Renders the "Was this solution helpful?" feedback form.
* If `type: "logged"`:
* Displays the "Query Logged" Badge and the corresponding message.
14. PDF Viewing (Frontend - `App.jsx` -> `SecurePDFViewer.jsx`):
* If `type: "solution"` and user clicks "View Solution PDF":
* The handleViewPdf function is called, setting showPdf to true and pdfUrl to the
solution's pdf_url.
* The SecurePDFViewer component is rendered.
* SecurePDFViewer uses pdfjs-dist to load the PDF from the backend's
/api/helpdesk/pdf/<filename> endpoint.
* It renders the PDF pages onto an HTML <canvas> element, preventing text selection,
copying, and right-click context menus.
* Users can navigate pages using "Previous" and "Next" buttons.
15. Feedback Submission (Frontend - `App.jsx`):
* If `type: "solution"`:
* The user can click "Yes" or "No" for feedback.
* Optionally, they can type comments into a Textarea.
* Clicking "Submit Feedback" triggers the submitFeedback function.
* An HTTP POST request is sent to http://127.0.0.1:5001/api/helpdesk/feedback with
helpful, comment, and solution_id.
16. Backend Feedback Processing (Backend - `src/routes/helpdesk.py`):
* The submit_feedback() function receives the feedback data.
* It creates a new Feedback entry in the Database (`src/database.py` -> `app.db`).
* It commits the changes to the database.
* A success message is returned to the frontend.
1 +-----------------------------------+ +-----------------------------------+
+-----------------------------------+
2| FRONTEND | | BACKEND |
| DATABASE |
3| (App.jsx, SecurePDFViewer) | | (main.py, helpdesk.py, database.py)|
| (app.db) |
4 +-----------------------------------+ +-----------------------------------+
+-----------------------------------+
5 | |
6 | |
7 | <User Input: Problem Text> |
8 | |
9 | [1. User Types & Clicks "Analyze"] |
10 | |
11 | HTTP POST /api/helpdesk/analyze |
12 |------------------------------------------>|
13 | <JSON: { "problem_text": "..." }> |
14 | |
15 | | [2. Receive Request & Extract
Keywords] |
16 | | (extract_keywords function)
17 | |
18 | | [3. Disambiguation Check]
|
19 | | (needs_disambiguation
function) |
20 | |
21 | | { Is Technical Query AND No OS
Mentioned? }|
22 | | / \
23 | | / \
24 | | YES NO
25 | | | |
26 | | | |
27 | <JSON: { type: "clarification", | | |
28 | message: "...", options: [...]}>|<-------| |
29 |<------------------------------------------| | |
30 | [4. Display Clarification Options] | | |
31 | | | |
32 | <User Selects Option> | | |
|
33 | | | |
34 | [5. Append Choice & Re-send Query] | | |
35 |------------------------------------------>| | |
36 | <JSON: { "problem_text": "...(choice)" }>| | |
37 | | | |
38 | | | |
39 | | | | [6.
Find Matching Solution] |
40 | | | |
(find_matching_solution function) |
41 | | | |
42 | | | | SELECT
* FROM Solutions WHERE keywords MATCH |
43 | | | |
------------------------------------------->|
44 | | | |<
-------------------------------------------|
45 | | | |
<Solution Data (title, content, pdf_url)>|
46 | | | |
|
47 | | | | {
Solution Found? } |
48 | | | | /
\ |
49 | | | | /
\ |
50 | | | | YES
NO |
51 | | | | |
| |
52 | | | | |
| |
53 | <JSON: { type: "solution", | | | |
| |
54 | title: "...", content: "...", |<-------| | |
| |
55 | pdf_url: "..." }> | | | |
| |
56 |<------------------------------------------| | | |
| |
57 | [7. Display Solution & "View PDF" Button]| | | |
| |
58 | | | | |
| |
59 | | | | |
| [8. Log Query] |
60 | | | | |
| (LOGGED_QUERIES in-memory) |
61 | | | | |
| |
62 | <JSON: { type: "logged", | | | |
| |
63 | message: "..." }> |<---------------------| |
| |
64 |<------------------------------------------| |
| |
65 | [9. Display "Query Logged" Message] | |
| |
66 | | |
| |
67 | | |
| |
68 | [10. User Clicks "View Solution PDF"] | |
| |
69 | | |
| |
70 | HTTP GET /api/helpdesk/pdf/<filename> | |
| |
71 |------------------------------------------>| |
| |
72 | | [11. Serve PDF Securely]
| |
73 | | (serve_pdf function)
| |
74 | |
| |
75 | <PDF Stream (rendered to Canvas)>
|<------------------------------------------| |
76 |<------------------------------------------|
| |
77 | [12. Render PDF on Canvas (SecureViewer)]|
| |
78 | |
| |
79 | |
| |
80 | [13. User Submits Feedback] |
| |
81 | |
| |
82 | HTTP POST /api/helpdesk/feedback |
| |
83 |------------------------------------------>|
| |
84 | <JSON: { helpful: true/false, |
| |
85 | comment: "...", solution_id: "..." }>|
| |
86 | | [14. Store Feedback]
| |
87 | | (submit_feedback function)
| |
88 | |
| INSERT INTO Feedback |
89 | |
|--------------------------->|
90 | |
|<---------------------------|
91 | |
| <Success/Error> |
92 | <JSON: { message: "..." }>
|<------------------------------------------| |
93 |<------------------------------------------|
| |
94 | [15. Display Feedback Confirmation] |
| |
95 +-----------------------------------+
+-----------------------------------+ +-----------------------------------+
