GraphQL API & Code Generation

Relevant source files

The following files were used as context for generating this wiki page:

• frontend/codegen.yml
• frontend/src/graphql.ts
• frontend/graphql.schema.json
• frontend/package.json
• backend/package.json
• frontend/src/apollo.ts

The technical-analysis project utilizes a GraphQL-centric architecture to facilitate communication between the NestJS backend and React frontend. This system centralizes data fetching, real-time updates via subscriptions, and rigorous type safety through automated code generation.

The core of the system is a GraphQL schema defined on the backend, which the frontend consumes to generate TypeScript types and Apollo React hooks. This ensures that any change in the API structure is immediately reflected in the frontend's type system, preventing runtime errors related to data structures.

Sources: frontend/codegen.yml:1-12, backend/package.json:34-40

Architecture and Data Flow

The architecture employs a split-link strategy to handle standard requests and real-time data streams differently. HTTP links are used for Queries and Mutations, while WebSocket links handle Subscriptions.

The diagram shows the flow of data from React components through Apollo Client to the backend via specific network protocols based on operation type.
Sources: frontend/src/apollo.ts:6-33, frontend/src/graphql.ts:400-415

Code Generation Workflow

The project uses @graphql-codegen to synchronize the frontend with the backend schema. The configuration in frontend/codegen.yml defines how TypeScript files and introspection schemas are produced.

Configuration Details

The generation process is driven by the codegen script in the frontend.

Option	Value	Purpose
Schema	../backend/schema.gql	The source of truth for the API structure.
Plugins	typescript, typescript-operations, typescript-react-apollo	Generates types, operation interfaces, and Apollo hooks.
Config	federation: true	Support for Apollo Federation features.
Output	src/graphql.ts	The target file containing all generated code.

Sources: frontend/codegen.yml:1-12, frontend/package.json:31

Execution Logic

The generation process consumes the backend schema and frontend query definitions to produce type-safe hooks and a local JSON schema.
Sources: frontend/codegen.yml:1-12

API Definition

The GraphQL API is divided into Queries, Mutations, and Subscriptions to support a wide range of financial data analysis features.

Queries and Mutations

Queries allow fetching historical data, search results, and external market info. Mutations handle state changes such as managing indicators and drawing shapes on charts.

Category	Operation	Parameters	Return Type
Query	candles	figi, interval, to	[Candle!]!
Query	tipRanksInfo	ticker	TipRanksInfo!
Mutation	addIndicator	AddIndicatorInput	Indicator!
Mutation	watch	WatchInput	Instrument!

Sources: frontend/graphql.schema.json:442-535, frontend/src/graphql.ts:86-130

Real-time Subscriptions

The system supports live data updates using WebSockets, primarily for market data and algorithmic trade alerts.

The sequence diagram illustrates the lifecycle of a real-time candle subscription.
Sources: frontend/src/apollo.ts:6-12, frontend/src/graphql.ts:705-715

Data Models

Key data structures are defined as GraphQL types and reflected in the generated TypeScript definitions.

Instrument and Candle

These types represent the core entities for market analysis.

• Instrument: Contains identifying information like ticker and figi, along with current price.
• Candle: Represents a price bar with open, high, low, close, volume, and timestamp.

Technical Indicators and Shapes

• Indicator: Includes an id, name, and an array of settings (Float).
• Shape: Used for chart annotations, containing a list of ShapePoint objects (value, timestamp, and dataIndex).

Sources: frontend/graphql.schema.json:165-195, frontend/graphql.schema.json:540-580, frontend/src/graphql.ts:38-75

Apollo Client Configuration

The frontend initializes the ApolloClient in frontend/src/apollo.ts by splitting traffic between HTTP and WebSocket links.

// Example of the Split Link implementation
const link = split(
  ({ query }) => {
    const definition = getMainDefinition(query);
    return (
      definition.kind === "OperationDefinition" &&
      definition.operation === "subscription"
    );
  },
  wsLink, // WebSocketLink for subscriptions
  httpLink // HttpLink for queries/mutations
);

Sources: frontend/src/apollo.ts:16-33

Summary

The GraphQL API and Code Generation system provides a robust, type-safe backbone for the project. By automating the creation of TypeScript types and React hooks from a central GraphQL schema, the project ensures consistency between the NestJS backend and the Apollo-powered React frontend, enabling seamless integration of complex financial data and real-time market updates.