Step-by-Step Data Interaction

Understanding Data Flow

This section provides a detailed walkthrough of the data flow within the system when a user performs common actions. We'll use the example of adding a new node (item or category) to illustrate the process.

Data Interaction Steps

1. User Initiates Action

• Action: The user decides to add a new node.
• Interaction: Clicks on the plus (+) icon and fills out the form with the new node's details.
• Data Captured:
  • Node Title: The name of the new item or category.
  • Current Location ID: The unique identifier of the current node where the new node will be added.

2. Front End Processes Input

• Validation: Checks that the node title is not empty and meets any client-side validation rules.
• Preparation: Constructs a GraphQL mutation with the input data.

3. Front End Sends Request to API

GraphQL Mutation Example:

mutation CreateNode($title: String!, $parentId: ID!) {
  createNode(title: $title, parentId: $parentId) {
    id
    title
    parentId
  }
}

 Variables:

{
  "title": "New Node",
  "parentId": "1234"
}

Communication: Sends the mutation to the API endpoint (http://127.0.0.1/api) via an HTTP POST request.

4. API Receives and Validates Request

• Authentication: Verifies the user's session token or cookie to ensure they are authenticated.
• Authorization: Checks if the user has permission to add nodes.
• Data Validation: Ensures the title and parentId are valid and that the parent node exists.

5. API Interacts with Database

Insert Node:

INSERT INTO nodes (title)
VALUES ('New Node')
RETURNING id;

Establish Relationship:

INSERT INTO node_relations (parent_id, child_id)
VALUES ('1234', 'newly_generated_id');

Database Response: Returns the new node's unique identifier (id).

6. API Sends Response to Front End

Success Response Example:

{
  "data": {
    "createNode": {
      "id": "5678",
      "title": "New Node",
      "parentId": "1234"
    }
  }
}

Error Handling: If an error occurs, the API sends an error response with details.

7. Front End Updates UI

8. Real-Time Updates to Other Users

Data Flow Diagram

sequenceDiagram
    participant User
    participant FrontEnd
    participant API
    participant Database

    User->>FrontEnd: Clicks "Add Node" and submits form
    FrontEnd->>API: Sends GraphQL mutation (createNode)
    API->>API: Authenticates and validates data
    API->>Database: Inserts new node and relationship
    Database-->>API: Returns new node ID
    API-->>FrontEnd: Sends success response
    FrontEnd-->>User: Updates UI with new node
    API-->>FrontEnd: Sends subscription update to other clients
    FrontEnd-->>User: Other clients' UIs update in real-time

Key Considerations