Conventions

Code Style

TypeScript

• Use explicit types for function parameters and return values
• Define interfaces in src/types/index.ts
• Prefer interfaces over types for object shapes
• Use enums for fixed sets of values (e.g., 'LONG' | 'SHORT')

React Components

• Use functional components with hooks
• Props interfaces should be named {ComponentName}Props
• Export components as named exports, not default
• Keep components focused and single-responsibility
• Extract complex logic to custom hooks

Styling

• Use Tailwind utility classes exclusively
• Use the cn() utility from lib/utils.ts for conditional classes
• Follow this pattern: className={cn("base-classes", condition && "conditional-classes")}
• Color palette:
  • Background: gray-950, gray-900, gray-800
  • Text: gray-100, gray-400, gray-500
  • Success: green-500, green-400
  • Error: red-500, red-400
  • Warning: yellow-500, orange-500
  • Info: blue-500

Component Organization

import { } from 'react';
import { } from '../types';
import { } from '../lib/utils';
import { } from 'lucide-react';

interface ComponentProps {
  // props definition
}

export function Component({ prop1, prop2 }: ComponentProps) {
  // hooks
  // derived state
  // handlers

  return (
    // JSX
  );
}

// Helper components (if any)
function HelperComponent() {}

Naming Conventions

• Components: PascalCase (PositionCard, AlertBanner)
• Files: PascalCase for components (PositionCard.tsx)
• Utilities: camelCase (formatCurrency, calculateRiskLevel)
• Types/Interfaces: PascalCase (Position, Alert, RiskLevel)
• Constants: UPPER_SNAKE_CASE (API_BASE_URL)

Financial Calculations

Liquidation Price

• Long: entryPrice * (1 - 0.9 / leverage)
• Short: entryPrice * (1 + 0.9 / leverage)
• Use 0.9 factor to account for maintenance margin (~10%)

PnL Calculations

• Unrealized PnL: (currentPrice - entryPrice) * size * (side === 'LONG' ? 1 : -1)
• PnL Percentage: (unrealizedPnL / collateral) * 100

Risk Levels

• Distance to liquidation: |currentPrice - liquidationPrice| / currentPrice
• CRITICAL: < 2%
• HIGH: 2-5%
• MEDIUM: 5-10%
• LOW: > 10%

Data Flow

1. Mock data in development (services/mockData.ts)
2. Exchange APIs in production (to be implemented)
3. Real-time updates via polling or WebSocket
4. Position refresh every 10 seconds (configurable)

Security Considerations

• Never commit API keys
• Always check .env is in .gitignore
• Use read-only API permissions when possible
• Recommend testnet for development
• Validate all API responses
• Handle rate limiting gracefully
• Use IP whitelisting on exchanges

Error Handling

• Display user-friendly error messages
• Log errors to console for debugging
• Show fallback UI when data fails to load
• Handle network failures gracefully
• Validate data before calculations

Performance

• Memoize expensive calculations
• Debounce frequent updates
• Use lazy loading for charts
• Minimize re-renders with proper deps
• Consider virtualization for large position lists

Testing (to be implemented)

• Unit tests for calculations and utilities
• Component tests with React Testing Library
• E2E tests for critical flows
• Mock exchange APIs in tests