Drawing Marks Persistence API
Relevant source files
The following files were used as context for generating this wiki page:
The Drawing Marks Persistence API facilitates the creation, retrieval, updates, and deletion of graphical overlays (shapes) on financial charts. This system bridges the gap between the frontend charting engine—built using klinecharts—and the backend data store via a GraphQL interface. It ensures that technical analysis drawings, such as trend lines or measurement boxes, remain persistent across user sessions and ticker changes.
The API is primarily consumed by the chart page component, which manages the lifecycle of shapes by responding to user interactions (drawing, dragging, or removing) and synchronizing those states with the remote database.
Sources: frontend/src/pages/chart/index.tsx:189-238, frontend/src/graphql.ts:88-124
Architecture and Data Flow
The persistence logic follows a reactive pattern where the UI state is synchronized with the backend via GraphQL mutations. When a user creates or modifies a shape on the klinechart canvas, the application triggers specific hooks that invoke GraphQL operations.
Component Interaction Flow
- Initialization: Upon mounting, the chart fetches existing shapes for the current ticker.
- Creation: When a drawing is completed (
onDrawEnd), a mutation is sent to save the new shape coordinates. - Manipulation: Moving a shape or its anchor points triggers a debounced update mutation to minimize network traffic.
- Removal: Deleting a shape from the UI triggers a removal mutation.
GraphQL Data Models
The persistence layer uses structured types to define shapes and their geometric points. A shape is tied to a specific ticker and contains an array of points, where each point defines a coordinate in time and price.
Shape Entities and Inputs
| Type | Field | Description |
|---|---|---|
| Shape | id | Unique identifier (Float) |
name | Type of drawing (e.g., "measure", "segment") | |
ticker | The financial instrument ticker | |
points | Array of ShapePoint objects | |
| ShapePoint | value | The price value at that coordinate |
timestamp | Unix timestamp for the x-axis | |
dataIndex | Optional index within the data list |
Sources: frontend/src/graphql.ts:153-172
API Operations
The system utilizes four primary GraphQL operations to manage persistence.
1. Retrieval (Query: shapes)
Fetches all drawings associated with a specific ticker.
- Parameter:
ticker: String! - Returns:
Array<Shape>
Sources: frontend/src/graphql.ts:133, frontend/src/graphql.ts:700-713
2. Creation (Mutation: addShape)
Persists a newly drawn shape. The application logic specifically removes the temporary shape ID generated by the charting library and replaces it with the persistent ID returned by the server.
- Input:
AddShapeInput(name, points, ticker)
Sources: frontend/src/pages/chart/index.tsx:327-340, frontend/src/graphql.ts:762-777
3. Update (Mutation: updateShape)
Updates the coordinates of an existing shape. This operation is debounced (100ms) in the frontend to optimize performance during "pressed move" events.
- Input:
UpdateShapeInput(id, points)
Sources: frontend/src/pages/chart/index.tsx:197-208, frontend/src/graphql.ts:747-752
4. Deletion (Mutation: removeShape)
Removes a shape from the database when the user triggers the removal event in the UI.
- Parameter:
id: Float!
Sources: frontend/src/pages/chart/index.tsx:191-193, frontend/src/graphql.ts:738-742
Shape Management Logic
The Shape class in the core charting library manages the internal state of drawing steps and coordinate transformations. It handles the transition from drawing steps (SHAPE_DRAW_STEP_START) to completion (SHAPE_DRAW_STEP_FINISHED).
Persistence Integration
The frontend chart component iterates through the fetched shapesData and populates the chart using chart?.createShape(). Each shape is configured with event handlers that link back to the persistence API:
onRemove: InvokesremoveShapemutation.onPressedMove: Invokes the debouncedonUpdateShapemutation.
Sources: frontend/src/klinechart/src/component/overlay/Shape.js:46-51, frontend/src/pages/chart/index.tsx:210-238
Conclusion
The Drawing Marks Persistence API provides a robust mechanism for maintaining technical analysis state. By leveraging GraphQL mutations and debounced updates, the system ensures that user annotations are saved efficiently and reliably across the application's lifecycle.