Skip to content

CLAUDE.md

Latest commit

 

History

History
84 lines (60 loc) · 3.21 KB

CLAUDE.md

File metadata and controls

84 lines (60 loc) · 3.21 KB
Raw

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Development Commands

Use the Makefile for all development tasks:

  • make dev - Start development server with Air live reload
  • make run - Run the main application directly
  • make test - Run all tests
  • make test-cover - Run tests with coverage report
  • make lint - Run golangci-lint for code quality
  • make fmt - Format code with gofmt
  • make vet - Run go vet
  • make check - Run all code quality checks (fmt, vet, lint)
  • make build - Build the application to ./bin/
  • make generate-ent - Generate Ent ORM code from schema

For testing configuration: go run cmd/test-config/main.go

Architecture Overview

MarketStream is a free self-hosted real-time stock data platform that provides REST API access to TradingView's WebSocket data feeds.

Core Components

  1. Configuration Layer (internal/config/) - Viper-based config with YAML, env vars, and CLI flags
  2. HTTP Layer (internal/handler/) - Fiber-based REST API handlers
  3. Service Layer (internal/service/) - Business logic for TradingView integration
  4. Database Layer (ent/) - PostgreSQL with Ent ORM for data persistence
  5. WebSocket Client - Uses github.com/iiiyu/tradingview-ws-client for real-time data

Data Flow

  1. HTTP API receives symbol subscription requests
  2. Service layer manages TradingView WebSocket connections
  3. Real-time quotes cached in Ristretto cache
  4. Historical candle data persisted to PostgreSQL
  5. Technical indicators calculated and stored for analysis

Database Schema (Ent)

  • Symbol: Exchange metadata and symbol information
  • Candle: OHLCV historical data with multiple timeframes
  • ActiveSession: Tracks active WebSocket subscriptions
  • StudySession: Groups technical indicators for analysis
  • Indicator: Individual technical analysis indicators
  • IndicatorData: Time-series calculated values

Configuration

Required environment variables:

  • TRADINGVIEW_DEVICE_TOKEN - TradingView device token
  • TRADINGVIEW_SESSION_ID - TradingView session ID
  • TRADINGVIEW_SESSION_SIGN - TradingView session signature
  • DB_HOST, DB_USER, DB_PASSWORD, DB_NAME - PostgreSQL connection

Configuration hierarchy: CLI flags → env vars → config.yaml → defaults

Code Conventions

  • Structured logging: Use slog with JSON format
  • Error handling: Return errors with context, avoid panics
  • Database: Use Ent ORM with proper migrations
  • HTTP: Use Fiber framework with proper error handling middleware
  • Dependencies: All managed through go.mod, use make deps

Technical Indicators

The service supports 10+ technical indicators including RSI, MACD, Bollinger Bands, Moving Averages, and more. See docs/INDICATORS_API.md for complete API documentation.

Entry Points

  • cmd/app/main.go - Main HTTP service
  • cmd/example/main.go - Example WebSocket client usage
  • cmd/test-config/main.go - Configuration validation tool

Development Setup

  1. Copy config.example.yaml to config.yaml
  2. Set required environment variables
  3. Run make setup to install development tools
  4. Use make dev for development with live reload