Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/tutosrive/avl_tree_car/llms.txt

Use this file to discover all available pages before exploring further.

The backend uses a small, focused set of Python models for domain objects (Obstacle, Node, Car) and response wrappers (BaseFlaskResponse, ReturnModels, ResponseSocket). Understanding these shapes makes it straightforward to parse API responses and interpret Socket.IO payloads.

​
BaseFlaskResponse

Used as the envelope for every HTTP REST response. All fields are serialized by to_dict().
​
status
int
HTTP status code. 200 on success, 400 on validation or not-found errors, 500 on server exceptions.
​
ok
bool
true when the operation succeeded, false on any error.
​
message
string
Human-readable description of the result.
​
data
dict | array | string | null
The operation payload. For node add this is the inserted obstacle ID string; for bulk configs it is an array of IDs; otherwise an empty object {}.
​
error
any | null
Error details when ok is false. null on success.
Serialized shape: 
{
  "status": 200,
  "ok": true,
  "message": "The node with coordinates (100, 20) has been added successfully!",
  "data": "0A2B4C6D",
  "error": null
}

​
ReturnModels

Internal return type produced by AVLTree methods such as insert, delete, search, and the traversals. Not sent directly over the wire — controllers extract fields from it to build a BaseFlaskResponse.
​
message
string
Describes the outcome, e.g. "Node found, see data!" or "Tree is empty!".
​
ok
bool
true when the operation succeeded.
​
data
any | null
The result payload. For insert this is the new obstacle’s id string; for search it is the Node object; for traversals it is a list of Obstacle objects.
​
error
any | null
Error details on failure, null otherwise.
{
  "ok": true,
  "message": "The node with coordinates (100, 20) has been added successfully!",
  "data": "0A2B4C6D",
  "error": null
}

​
ResponseSocket

Used for all Socket.IO event emissions. The data field is auto-serialized if the value has a to_dict() method.
​
ok
bool
true when the event was handled successfully.
​
received
any
The raw message received from the client — echoed back for debugging.
​
message
string
Human-readable status message (default "OK").
​
data
dict | string | null
Payload for the event. For tree events this is the serialized tree dict; for traversal stream events it is a single obstacle ID string emitted per step.
​
error
any | null
Error details if ok is false, otherwise null.
If data is an object with a to_dict() method, it is called automatically before serialization. String values (such as obstacle IDs) are returned as-is.
{
  "ok": true,
  "received": null,
  "message": "This is the tree by moment!",
  "data": {
    "id": "0A2B4C6D",
    "children": [
      { "id": "1X3Y5Z7W" },
      { "id": "2P4Q6R8S", "children": [{ "id": "3M5N7O9P" }] }
    ]
  },
  "error": null
}

​
Obstacle

The core value stored in every AVL tree node. Represents a road hazard at a specific (x, y) position.
​
id
string
Auto-generated 8-character random string. Even-indexed positions are digits, odd-indexed positions are capital letters (e.g. "0A2B4C6D"). Generated by RandomsUtils.random_id(8, 2).
​
x
float
Horizontal position on the road. Used as the primary sort key in the AVL tree.
​
y
float
Vertical position / height of the obstacle on the road.
​
type_id
int
Numeric obstacle type. Maps to one of 10 types defined in obstacles_types.json (1 = Cone, 2 = Rock, … 10 = Chair).
{
  "id": "0A2B4C6D",
  "x": 100.0,
  "y": 20.0,
  "type_id": 2
}
Two obstacles with the same (x, y) coordinates are considered duplicates. The AVL tree will reject the second insert with a 400 error.

​
Node

Wraps an Obstacle as an AVL tree node, adding structural pointers and a height counter used for balancing.
​
value
Obstacle
The obstacle stored at this node position.
​
left
Node | null
Left child node (contains obstacles with smaller x than this node).
​
right
Node | null
Right child node (contains obstacles with larger x than this node).
​
height
int
Height of this node in the tree. Leaf nodes have height 1. Updated after every insert and delete.
Node also carries a parent reference (Node | null) used internally during rotations and rebalancing. This field is not included in the to_dict() output — it exists only on the Python object.
Node.to_dict() recursively serializes the subtree into value, left, right, and height only: 
{
  "value": { "id": "0A2B4C6D", "x": 100.0, "y": 20.0, "type_id": 2 },
  "left": {
    "value": { "id": "1X3Y5Z7W", "x": 50.0, "y": 10.0, "type_id": 1 },
    "left": null,
    "right": null,
    "height": 1
  },
  "right": null,
  "height": 2
}

​
Car

A lightweight backend model representing the car entity. Primary simulation logic runs in the frontend; the backend Car class is a stub.
​
velocity
float
Car speed in units per tick. Default 5.
​
battery
int
Current battery level. Default 0.
​
collition_with_obstacle
bool
Whether the car is currently colliding with an obstacle. Default false. Note: the source spells this field collition_with_obstacle (without the second s).
​
pos_x
int
Horizontal position of the car. Default 100.
​
pos_y
int
Vertical position of the car. Initialized to road_size[1] // 2.
The Car class on the backend does not implement movement logic — run(), up(), and down() are stubs. All animation and collision detection are handled by the ATC Frontend.

​
AVLTree serialization

Calling AVLTree.to_dict() produces a compact nested structure using only obstacle id values and a children array. This is the format emitted by Socket.IO tree events (avl_tree_balanced, avl_reseted). 
{
  "id": "0A2B4C6D",
  "children": [
    { "id": "1X3Y5Z7W" },
    {
      "id": "2P4Q6R8S",
      "children": [
        { "id": "3M5N7O9P" }
      ]
    }
  ]
}
Leaf nodes omit the children key entirely. Root is null when the tree is empty (after reset_avl).

Build docs developers (and LLMs) love

Get started for freeTalk to us