Semantic Graph Compiler

Now supports Node.js + Express + MySQL

The Semantic Graph Compiler (SGC) is a powerful developer tool for structurally defining, validating, and compiling complex backend architecture — with automatic graph visualization.

The compiled output is a set of plain-text prompts optimized for large language models (LLMs), such as ChatGPT, enabling them to generate precise, context-aware backend code.

Unlike drag-and-drop tools, SGC lets you build backend architecture through a structured editor — using buttons, forms, and guided input to generate valid semantic graph JSON.

Each semantic graph is stored as a single JSON file, following a simple and consistent schema.

How it works:
SGC takes a semantic graph—a single JSON file describing your application's structure—as input. This file contains two main arrays:

nodes: An array of node objects. Each object represents a component in your system. Components are distinguished by their type field, which indicates the role or category of each node.
edges: An array of edge objects. Each object describes a directed connection between nodes, expressing relationships such as function calls. These relationships are categorized using a variety of edge types, each representing a specific kind of interaction or dependency.

SGC performs validation during both visualization and compilation stages, and reports clear, detailed errors whenever issues are found. The compilation phase enforces stricter checks than visualization, catching deeper problems that may not be detected earlier.

        
{
  "nodes": [ ... ],  // array of node objects
  "edges": [ ... ]   // array of edge objects
}

Node Structure

Each node in the semantic graph must be a JSON object that accurately describes a component or entity in your system.
To ensure successful compilation, every node must include all required fields with correct data types.
Detailed explanations for each field are provided below.

name

The name you assign to this component/node.

type

The node type (see allowed types below for details).

placeType

Either Server or MySQL (case-insensitive). Indicates whether the node is located on the general server or the MySQL server.

filename

The filename where the node/component is defined. It is recommended to use the file path (either absolute or relative).

description

This field is important. You should document the logic and behavior of the node here. For function-type nodes, be sure to specify both the input and output clearly.

isRestricted

Determines whether this node is restricted in how it can interact with other nodes it is connected to.

If set to true, this node may only access explicitly permitted subcomponents of nodes to which it has outgoing edges.

When false, the node can freely access any subcomponent of the nodes it points to.

restrictedObjects

An array of JSON objects. Each object specifies a node (that this node has an outgoing edge to) and the list of subcomponents (members) it is allowed to access.

This field is only relevant when isRestricted is set to true.

Each object typically includes the target node's basic information, along with a allowedSubobjects array listing the allowed subcomponents.

Nodes that are not connected by an outgoing edge should not be referenced in this array.

id

The unique identifier for this node. Should be constructed as a combination of fields (e.g., filename, name, placeType, type) to ensure uniqueness. The editor automatically generates it for each node.

Each node must include all fields above with the correct type.
Example of a valid node:

    
    {
      "name": "post_unsendlike_handler",
      "type": "EndpointHandler",
      "placeType": "Server",
      "filename": "./application/index.js",
      "description": "Input:\n\n(req, res)\n\nReturn:\nAnything (flexible)\n\nLogic:\nFirst, extract username and token from req.cookies.\nThen, use sqldatacenter.Verify_LoginToken to verify the user's identity.\n\nIf authentication is successful:\n\nUse sqldatacenter.searchuserIDbyusername to retrieve the corresponding user_id.\n\nExtract post_id from req.body.\n\nCall sqldatacenter.unsendlike with user_id and post_id.\n\nIf everything succeeds, respond with:\n{ \"state\": \"success\" }\nIf any step fails (e.g., identity verification fails), respond with:\n{ \"state\": \"fail\" }",
      "isRestricted": true,
      "restrictedObjects": [
        {
          "id": "filename:./application/index.js|name:sqldatacenter|placeType:Server|type:GlobalVariable",
          "name": "sqldatacenter",
          "filename": "./application/index.js",
          "placeType": "Server",
          "type": "GlobalVariable",
          "allowedSubobjects": [
            "Verify_LoginToken",
            "searchuserIDbyusername",
            "unsendlike"
          ]
        }
      ],
      "id": "filename:./application/index.js|name:post_unsendlike_handler|placeType:Server|type:EndpointHandler"
    }

    
  

Node Types

Each node in the semantic graph has a specific type that determines its behavior. The following is a complete set of all node types currently supported by SGC:

Function

A general-purpose backend function node. Ideal for encapsulating logic, reusable operations, and utility methods.

EndpointHandler

A specialized function that handles incoming HTTP/HTTPS requests for a specific API route.
Although technically a function, an EndpointHandler is treated as a distinct node type because it serves as the boundary logic for an API route.

APICreatorFunction

A higher-order function that dynamically generates multiple API endpoints.
This type is still under active development — in the future, it will be able to point to a dedicated APIEndpointsGroup node that encapsulates the generated endpoints for better organization and visualization.

APIEndpoint[GET]

Represents a GET API endpoint. It defines the route path and method, while the actual request-handling logic is delegated to a connected EndpointHandler.

APIEndpoint[POST]

Represents a POST API endpoint. It defines the route path and method, while the actual request-handling logic is delegated to a connected EndpointHandler.

APIEndpoint[USE]

Represents an Express.js middleware registration using app.use(...). It defines a middleware layer that executes before route-specific handlers.

server_file

Represents an actual server-side code file. Other nodes can write to it or read from it.

GlobalVariable

Defines a global variable in a file.

Table

Represents a MySQL table that can be read from or written to using read / write edge types.

Edge Types

Edges connect nodes and describe their relationship. Each edge has a type that defines its role in the graph.

calls

Represents a direct invocation from the source node to the target node. Both nodes must be located within the same file — this is commonly used when one function calls another, or when accessing a shared GlobalVariable.
This edge type expresses local runtime dependencies rather than static imports.

owns

Represents a semantic ownership relationship, where the source node contains or groups other nodes as its members. Commonly used when a GlobalVariable wraps multiple Function nodes — for example, when functions are exposed as properties of an object. The source and target nodes must be located within the same file.
In this relationship, the source node is considered to own the target node as a subcomponent.

writes_server_file

Indicates that the source node writes content to the target server_file, such as generating an image, saving a JSON file.

reads_server_file

Indicates that the source node reads content from the target server_file, such as loading an HTML template, a JSON configuration file, or a static image. This edge type is used when server-side logic depends on the contents of an existing file.

reads_globalVar

Indicates that the source node accesses the value of the target GlobalVariable. This edge type represents a read-only dependency on shared constants or reusable objects.
The source and target nodes must be located within the same file.

writes_globalVar

Indicates that the source node modifies the target GlobalVariable.
The source and target nodes must be located within the same file.

reads_table

Indicates that the source node reads data from the target Table in the MySQL server. The operation is performed through a database connection, and the source node is usually a Function that executes a query.

writes_table

Indicates that the source node modifies the target Table in the MySQL server by performing a write operation, such as INSERT, UPDATE, or DELETE. The operation is carried out through a database connection, and the source node is usually a Function that handles data mutations.

handled_by

Indicates that the source node, typically an APIEndpoint[GET], [POST], or [USE], is handled by the target EndpointHandler node. This edge connects a route definition to the function that implements its logic. The source and target nodes must be located within the same file.

rate_limited_by

Indicates that the source node, typically an APIEndpoint, is protected by a rate-limiting mechanism implemented in the target node.The source and target nodes must be located within the same file.

imports

Indicates that the source node imports the target node using static import syntax, making it available within the local file context. This edge is used to represent cross-file references, and the source and target nodes must be located in different files.
Through this connection, the source node can access the logic and functionality defined in the target node. The source and target nodes must be located in different files.

Compilation Error Types

During compilation, the Semantic Graph Compiler (SGC) validates the semantic graph structure. If invalid inputs are detected, errors are returned in the following formats:

1. MissingField

Triggered when a node is missing a required field such as name or filename.
node: 'filename:./application/sqldatacenter.js|name:|placeType:Server|type:GlobalVariable' has empty or non-string field 'name'

2. DuplicateNodeId

Two or more nodes share the same id, which is not allowed.
Found duplicate node IDs: "./application/index.js|name:get_userlikepost_handler|placeType:Server|type:EndpointHandler"

3. CycleDetected

The graph has a cycle, making it impossible to resolve dependencies in a valid order. You may view the graph to find and resolve the cycle.

Below is a raw error example.

    
[CycleDetected Error]: Found cycle: "filename:./application/index.js|name:/userlikepost|placeType:Server|type:APIEndpoint[GET]" → "filename:./application/index.js|name:get_userlikepost_handler|placeType:Server|type:EndpointHandler" → "filename:./application/index.js|name:alpha|placeType:Server|type:Function"

4. IllegalEdge

The graph contains one or more illegal edges, meaning some connections between nodes violate structural rules. These errors usually indicate a configuration mistake or a misused connection type.

Below is a raw error example.
Tip: Scroll left/right to view the full content.

    
	[IllegalEdge Error]: Edge [filename:./application/sqldatacenter.js|name:sqlusername|placeType:Server|type:GlobalVariable---->filename:fhgj|name:fkhgj|placeType:Server|type:Function](type: calls) is illegal. Edges of this type can't span across different files.
[IllegalEdge Error]: Edge [filename:./application/sqldatacenter.js|name:sqlusername|placeType:Server|type:GlobalVariable---->filename:fhgj|name:fkhgj|placeType:Server|type:Function](type: calls) is illegal. Node "filename:fhgj|name:fkhgj|placeType:Server|type:Function" doesn't exist
[IllegalEdge Error]: Edge [filename:./application/sqldatacenter.js|name:fs|placeType:Server|type:GlobalVariable---->filename:dfhgj|name:gcnhv|placeType:Server|type:Function](type: imported) is illegal. Node "filename:dfhgj|name:gcnhv|placeType:Server|type:Function" doesn't exist

5. FormatError

The graph contains one or more formatting errors, such as edges referencing nodes that do not exist, or having invalid structure.
Below are raw error examples.
Tip: Scroll left/right if the message is too long.

    
FormatError: node "filename:./application/sqldatacenter.js|name:mysql|placeType:Server|type:GlobalVariable" has type 'undefined', which is not in the allowed type list.
FormatError: edge ["filename:./application/sqldatacenter.js|name:mysql|placeType:Server|type:GlobalVariable" ----> "filename:mysql2|name:module|placeType:Server|type:GlobalVariable"] field 'type' is different from node "filename:./application/sqldatacenter.js|name:mysql|placeType:Server|type:GlobalVariable".
FormatError: edge ["filename:./application/sqldatacenter.js|name:pool|placeType:Server|type:GlobalVariable" ----> "filename:./application/sqldatacenter.js|name:mysql|placeType:Server|type:GlobalVariable"] field 'type' is different from node "filename:./application/sqldatacenter.js|name:mysql|placeType:Server|type:GlobalVariable".

How To Use Semantic Graph Editor

We only support Backend Editor now

Backend Editor (Node.js+Express+MySQL)

The graph below is the initial screen of the editor. You can start by clicking the Upload JSON button on the right to load an existing semantic graph in JSON format.

After editing your components and connections, you can click Download JSON to export your graph. If you want to view the visual structure of current graph, click View Graph.

Finally, clicking Compile will validate and compile the current graph directly from the editor.

The editor is divided into two main zones: the Server zone and the MySQL zone. You can create and modify nodes and edges in both zones.

After clicking Add Component, a new node will appear as shown in the image below. (In this system, a component is equivalent to a node.)

You can then add an edge from this node by clicking Add Edge. This means you are creating an edge that starts from the node.

After clicking Add Edge, the interface will appear as shown below. You need to select the Edge Type, and specify the target node's name, filename, placeType (i.e. target place), and type to determine which node this edge should point to.

When you check Restrict subobject usage, the component’s isRestricted property will be set to true. As a result, a new section called Subobject Restriction Settings will appear, as shown below.

This section allows you to configure the restrictedObjects property mentioned earlier.

Clicking Add Restricted Object will add an element to the restrictedObjects array. You need to fill in the four fields above so the system knows which object’s usage should be restricted.

For each restricted object, you’ll see a section below labeled Allowed Subobject Name. This field lets you specify which subobject names are permitted when this object is used.

You can click Add Allowed Subobject to add more entries of this type.

How To Use Compiled Files

Once you’ve compiled your semantic graph using SGC at Semantic Graph Editor, the output will be a set of plain-text .txt files containing well-structured, AI-targeted prompts—one for every component in that file—ordered precisely according to the graph’s dependency edges.

You can manually copy each individual prompt into a language model such as ChatGPT or Claude, and paste the generated code back into the corresponding part of your codebase. Do not paste the entire file at once—each prompt is meant to be used separately for its specific component.

In the future, this copy-and-paste step may be automated by the server, allowing SGC to send prompts to the LLM and insert the generated code directly into the output structure.

Each compiled prompt file is named based on the filename you provided in the graph. To ensure file system compatibility, certain characters are transformed:

Every . in the filename will be replaced with DOT.
All / characters (i.e., folder separators) are replaced with double underscores __.
Other characters that are invalid in filenames (e.g.,\, :, *, ?, ", <, >, |) are replaced with underscores _.