Tinkoff Data Typings
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
The Tinkoff Data Typings system provides a robust set of TypeScript interfaces, classes, and Enums designed to standardize financial data retrieved from the Tinkoff Invest API. This module acts as the data backbone for both the backend services and the frontend GraphQL layer, ensuring consistency in how market data—specifically candles and instrument information—is processed, validated, and displayed.
The primary purpose of these typings is to map raw data from the @tinkoff/invest-openapi-js-sdk into internal formats used for Algorithm Testing and technical indicator calculations. This ensures that the system can handle both historical batch data and real-time streaming data through a unified interface.
Sources: backend/src/modules/tinkoff/tinkoff.service.ts:1-15, frontend/src/graphql.ts:1-50
Core Data Structures
Candle Representation
The Candle structure is the fundamental unit of market data in the application. It maps the OHLCV (Open, High, Low, Close, Volume) data from the Tinkoff API to a format compatible with the project's technical indicators and charting libraries.
| Field | Type | Description |
|---|---|---|
time | String | ISO string representation of the candle time. |
timestamp | Float/Number | Unix timestamp in milliseconds. |
open | Float/Number | Opening price of the period. |
close | Float/Number | Closing price of the period. |
high | Float/Number | Highest price during the period. |
low | Float/Number | Lowest price during the period. |
volume | Float/Number | Trading volume during the period. |
Sources: backend/src/modules/tinkoff/tinkoff.service.ts:170-180, frontend/src/graphql.ts:40-49
Time Intervals and Resolutions
The system defines a specific set of intervals for data fetching, ranging from minute-level granularity to monthly aggregations. These are shared between the GraphQL schema and the backend service logic.
The diagram shows how time intervals are categorized for different processing logic in the service layer.
Sources: frontend/src/graphql.ts:65-77, backend/src/modules/tinkoff/tinkoff.service.ts:80-90
Data Flow and Mapping
Internal Mapping Logic
The TinkoffService utilizes a mapToCandle method to convert raw TinkoffCandle objects or CandleStreaming objects into the project's internal Candle type. This abstraction allows the rest of the system to remain agnostic of the specific SDK data formats.
The diagram illustrates the transformation of external SDK data into the internal data model.
Sources: backend/src/modules/tinkoff/tinkoff.service.ts:170-179, backend/src/modules/algorithmTesting/algorithmTesting.resolver.ts:60-65
Real-time Subscription Data
For real-time updates, the system uses the CandleSubscriptionData type, which couples a Candle with its parent Instrument. This is used primarily in GraphQL Subscriptions to update charts and trigger algorithm checks.
export type CandleSubscriptionData = {
__typename?: 'CandleSubscriptionData';
candle: Candle;
instrument: Instrument;
};
Sources: frontend/src/graphql.ts:51-55, backend/src/modules/tinkoff/tinkoff.resolver.ts:24-30
Service Integration
The TinkoffService implements complex logic to handle the retrieval of candles across different sub-periods. This is necessary because the Tinkoff API limits the amount of data returned in a single request depending on the interval.
Interval Logic Table
| Interval | Sub-Period Length Unit | Logic |
|---|---|---|
hour | Weeks | Fetches data in 1-week chunks. |
day, week, month | Years | Fetches data in 1-year chunks. |
1min to 30min | Days | Recursive fetching of 1-day chunks until subPeriodLength is met. |
Sources: backend/src/modules/tinkoff/tinkoff.service.ts:79-115
Instrument Search and Identification
Instruments are identified via their figi (Financial Instrument Global Identifier) and ticker. The search functionality returns an array of Instrument objects, which are then used to subscribe to specific market data streams.
The sequence diagram demonstrates the flow of instrument discovery using Tinkoff data typings.
Sources: backend/src/modules/tinkoff/tinkoff.resolver.ts:54-68, frontend/src/graphql.ts:400-410
Conclusion
The Tinkoff Data Typings system ensures that the application operates on a clean, predictable data model regardless of the underlying API's complexities. By centralizing the mapping logic and enforcing strict TypeScript interfaces, the system maintains high data integrity for both the Algorithm Testing engine and the frontend visualization components. Over 5 key source files collaborate to maintain this structure across the full stack.