Skip to content

BACKEND.md

Latest commit

 

History

History
288 lines (261 loc) · 6.06 KB

BACKEND.md

File metadata and controls

288 lines (261 loc) · 6.06 KB

Backend Documentation

Overview

The backend is built using Express.js with TypeScript and uses SQLite as the database. It provides a RESTful API for managing nodes and edges in the codebase visualization tool.

Technology Stack

  • Framework: Express.js with TypeScript
  • Database: SQLite3
  • Port: 3001
  • CORS: Enabled for frontend communication
  • Max Payload Size: 50MB for JSON and URL-encoded data

Database Schema

Nodes Table

CREATE TABLE nodes (
  id TEXT PRIMARY KEY,
  type TEXT NOT NULL,
  label TEXT,
  position_x REAL,
  position_y REAL,
  description TEXT,
  interface TEXT,
  data TEXT
)

Edges Table

CREATE TABLE edges (
  id TEXT PRIMARY KEY,
  source TEXT NOT NULL,
  target TEXT NOT NULL,
  type TEXT,
  label TEXT,
  FOREIGN KEY (source) REFERENCES nodes(id),
  FOREIGN KEY (target) REFERENCES nodes(id)
)

API Endpoints

Nodes

GET /api/nodes

Retrieves all nodes from the database.

  • Method: GET
  • Response: Array of node objects
  • Example Response:
{
  "success": true,
  "data": [
    {
      "id": "node-1",
      "type": "Component",
      "label": "MyComponent",
      "position_x": 100,
      "position_y": 200,
      "description": "Component description",
      "interface": "interface Props {...}"
    }
  ],
  "message": "Successfully retrieved X nodes"
}

POST /api/nodes

Creates a new node.

  • Method: POST
  • Required Fields: id, type, label, position
  • Optional Fields: description, interface, data
  • Example Request:
{
  "id": "node-1",
  "type": "Component",
  "label": "MyComponent",
  "position": { "x": 100, "y": 200 },
  "description": "Component description",
  "interface": "interface Props {...}"
}

PUT /api/nodes/:id

Updates an existing node.

  • Method: PUT
  • Required Fields: type, label, position
  • Optional Fields: description, interface, data
  • URL Parameter: id (node identifier)

DELETE /api/nodes/:id

Deletes a node.

  • Method: DELETE
  • URL Parameter: id (node identifier)

POST /api/nodes/bulk

Creates multiple nodes in a single request.

  • Method: POST
  • Body: Array of node objects
  • Required Fields per Node: id, type, label, position
  • Optional Fields per Node: description, interface, data
  • Example Request:
[
  {
    "id": "node-1",
    "type": "Component",
    "label": "MyComponent",
    "position": { "x": 100, "y": 200 },
    "description": "Component description",
    "interface": "interface Props {...}"
  },
  {
    "id": "node-2",
    "type": "Service",
    "label": "MyService",
    "position": { "x": 300, "y": 400 }
  }
]
  • Example Response:
{
  "success": true,
  "data": [
    {
      "id": "node-1",
      "type": "Component",
      "label": "MyComponent",
      "position": { "x": 100, "y": 200 },
      "description": "Component description",
      "interface": "interface Props {...}"
    },
    {
      "id": "node-2",
      "type": "Service",
      "label": "MyService",
      "position": { "x": 300, "y": 400 }
    }
  ],
  "message": "Successfully created 2 nodes"
}
  • Note: Invalid nodes in the array will be skipped, and only valid nodes will be created.

Edges

GET /api/edges

Retrieves all edges from the database.

  • Method: GET
  • Response: Array of edge objects

POST /api/edges

Creates a new edge.

  • Method: POST
  • Required Fields: id, source, target, type
  • Optional Fields: label
  • Example Request:
{
  "id": "edge-1",
  "source": "node-1",
  "target": "node-2",
  "type": "Uses",
  "label": "Uses"
}

PUT /api/edges/:id

Updates an existing edge.

  • Method: PUT
  • Required Fields: type
  • Optional Fields: label
  • URL Parameter: id (edge identifier)

DELETE /api/edges/:id

Deletes an edge.

  • Method: DELETE
  • URL Parameter: id (edge identifier)

POST /api/edges/bulk

Creates multiple edges in a single request.

  • Method: POST
  • Body: Array of edge objects
  • Required Fields per Edge: id, source, target, type
  • Optional Fields per Edge: label
  • Example Request:
[
  {
    "id": "edge-1",
    "source": "node-1",
    "target": "node-2",
    "type": "Uses"
  },
  {
    "id": "edge-2",
    "source": "node-2",
    "target": "node-3",
    "type": "Extends",
    "label": "Custom Label"
  }
]
  • Example Response:
{
  "success": true,
  "data": [
    {
      "id": "edge-1",
      "source": "node-1",
      "target": "node-2",
      "type": "Uses",
      "label": "Uses"
    },
    {
      "id": "edge-2",
      "source": "node-2",
      "target": "node-3",
      "type": "Extends",
      "label": "Custom Label"
    }
  ],
  "message": "Successfully created 2 edges"
}
  • Note: Invalid edges in the array will be skipped, and only valid edges will be created.

Database Management

POST /api/clear-database

Clears all data from the database.

  • Method: POST
  • Effect: Deletes all nodes and edges

POST /api/layout

Saves the current layout of nodes and edges.

  • Method: POST
  • Body: Complete nodes and edges arrays

Data Types

Node Type

interface Node {
  id: string;
  type: 'Component' | 'Service' | 'Widget' | 'SDK' | 'Other' | 'Condition';
  label: string;
  position: { x: number; y: number };
  description?: string;
  interface?: string;
  data?: any;
}

Edge Type

interface Edge {
  id: string;
  source: string;
  target: string;
  type: 'Extends' | 'Uses' | 'Condition' | 'Injects';
  label: string;
}

Error Handling

The backend implements a consistent error handling pattern:

  • All errors are caught and processed through the handleError helper function
  • Responses include a success boolean flag
  • Error responses include an error message and appropriate HTTP status code
  • Database errors are logged to the console

Setup and Installation

  1. Navigate to the backend directory
  2. Install dependencies: 
    npm install
  3. Start the server: 
    npm start

The server will automatically create the database and required tables on first run.