Skip to content

Developer Documentation

Jump to bottom
Shaheem Azmal M MD edited this page Jul 11, 2025 · 1 revision

👋 Welcome to the LicenseDb-UI Wiki developer Documentation page! This wiki provides a step-by-step guide on how to quick-start the development of the application.

Table of Contents

Connecting to the Backend

To connect to the backend, follow these steps:

  1. Setup a Linux VM:
    • Install VMWare Workstation (or any other virtualization tool of your choice).
    • Create and configure a Linux virtual machine.
  2. Backend Setup Instructions:
    • Refer to the LicenseDb Backend repository.
    • Follow the step-by-step instructions provided in the README file to set up the environment.
  3. Verify Setup with Swagger:
  4. Backend Requirement for UI:
    • Ensure that the backend service is running and accessible.
    • The UI relies on the backend to connect to the API endpoints.

Overview of APIs on the Backend

The APIs are grouped into collections, making them easy to navigate. Below is a summary:

  • Authentication API:
    • At the top of the Swagger page, there’s a GET API called /apiCollection.
    • It provides a list of APIs categorized based on whether they require admin privileges or are available for regular users.
    • This is particularly useful for new developers to understand the scope of available APIs.
    • Hit the "Authorize" button and provide credentials before trying out the admin APIs.
    • Swagger: swagger

Collections of APIs

  1. Audits:
    APIs related to audits, such as fetching audit logs, fetch logs by a single user etc.
  2. Licenses:
    APIs for managing licenses, including creating, reading, updating, and deleting license data.
  3. Obligations:
    • APIs to manage obligations, such as retrieving obligation lists and adding new obligations.
    • Obligation settings Apis (obligations/classifications & obligations/types) for creating, updating or deleting new classifications and types for obligations.
  4. Users:
    User management APIs, including registration, login, and role management.

Important Notes

  • Some APIs require authorization or admin privileges.
    • For example, APIs related to sensitive operations (like user role updates or creating and updating licenses) can only be accessed by registered users with appropriate permissions.
  • APIs are largely self-explanatory, with clear descriptions provided in Swagger.

Create License Page

  • Features:
    • Create new licenses.
    • Dynamic External Reference Fields: Configured via externalRef.yaml (editable and dynamic).
    • External fields require updates to:
      1. externalRef.yaml (located at the project root).
      2. componentPathMap.js (located in the utils folder, for new input types only).

Example Configuration for a Textarea:

name: "ack_text"
type: "string"
struct_field_name: "AcknowledgementText"
label: "Acknowledgement Text"
formComponentPath: "../components/dynamic/textArea"
componentType: "textarea"

Important Notes

  1. Update externalRef.yaml and provide it to the backend for the changes to take effect.
  2. Currently available input types: input, checkbox, textarea
  3. For new input types:
    • Create the component in components/dynamic/.
    • Update componentPathMap.js with the path to the new component.

Coding Guidelines & Tips

  • Framework: Created using create-react-app.
  • API Handling: Uses tanstack react query. All API calls are listed in a single file api.js and called as needed in different components or pages.
  • Naming conventions:
    • We follow the camelCase convention while creating a new .js or .css file (also largely for creating new variables).
    • Function and Class are created following the PascalCase convention.
  • Styling:
    • Bootstrap is used for styling, but some parts use pure CSS instead of Bootstrap classes or elements.
    • Dropdowns: react-select is used instead of HTML <select> for dropdowns. Additionally, a customColorSelect component is available for select boxes with color options.
  • Reusable Functions:
    • handleChange: A reusable onChange function for forms.
    • toastMessage: Reusable react-toastify component which can be called whereever needed throughout the application.
    • Custom Hook: A custom hook for API call handling is under development and will be reusable across the app.
  • License Comments: Each file (except .css) includes license text at the top. Ensure new files include this license text.
  • Semicolon Usage: Semicolons (;) are not used at the end of lines for consistency.
  • Styling Practices:
    • Use Bootstrap grid styles and custom class names.
    • Prefer Flexbox for efficient layouts.
    • Minimal inline styles; styles are kept in separate .css files.
  • Error Handling:
    • Uses react-toastify for displaying errors, with some exceptions (e.g., in the operations page).
    • An error toast should contain no autoClose function (so that the user has to manually close the error toast message)
    • The dark theme is used for theming, so new toasts should also follow this for consistency.
  • Forms:
    • Normal <Form> elements are used. External libraries like Formik or Bootstrap forms are not utilized.
  • Buttons:
    • Bootstrap buttons are used consistently throughout the application.
  • For more detailed coding styles follow this link - Fossology Coding Styles
Clone this wiki locally