managing-apps/CLAUDE.md

Managing Apps - Claude Code Guidelines

Project Overview

This is a quantitative finance application with .NET backend and React TypeScript frontend, focusing on algorithmic trading, market indicators, and financial mathematics.

Core Architecture Principles

Quantitative Finance Requirements

• IMPORTANT: Use decimal for all monetary calculations (never double or float)
• Implement proven financial mathematics (Black-Scholes, Monte Carlo, etc.)
• Optimize time-series processing for tick data/OHLCV series
• Validate models with historical backtesting frameworks
• Maintain audit trails for all financial calculations
• Prioritize numerical precision in all calculations

Backend (.NET/C#) Guidelines

Code Style and Structure

• Write concise, idiomatic C# code following .NET conventions
• Use object-oriented and functional programming patterns appropriately
• Prefer LINQ and lambda expressions for collection operations
• Use descriptive variable and method names (e.g., IsUserSignedIn, CalculateTotal)
• Structure files according to .NET conventions (Controllers, Models, Services, etc.)

Naming Conventions

• PascalCase: Class names, method names, public members
• camelCase: Local variables, private fields
• UPPERCASE: Constants
• Prefix interfaces with "I": IUserService, IAccountRepository

C# and .NET Usage

• Use C# 10+ features (record types, pattern matching, null-coalescing assignment)
• Leverage built-in ASP.NET Core features and middleware
• Use var for implicit typing when type is obvious
• Use MongoDb and Influxdb for database operations

Architecture Layers (YOU MUST FOLLOW)

1. Controller → Application → Repository (NEVER inject repository in controllers)
2. Always implement methods you create
3. Check existing code before creating new objects/methods
4. Update all layers when necessary (database to frontend)

Error Handling and Validation

• Use exceptions for exceptional cases, not control flow
• Implement proper error logging with .NET logging
• Use Data Annotations or Fluent Validation for model validation
• Return appropriate HTTP status codes and consistent error responses
• Services in services/ directory must throw user-friendly errors for tanStackQuery

API Design

• Follow RESTful API design principles
• Use attribute routing in controllers
• Implement versioning for APIs
• Use Swagger/OpenAPI for documentation

Performance Optimization

• Use async/await for I/O-bound operations
• Implement caching strategies (IMemoryCache or distributed caching)
• Use efficient LINQ queries, avoid N+1 query problems
• Implement pagination for large datasets

Frontend (React/TypeScript) Guidelines

Component Structure

• Use functional components with TypeScript interfaces
• Use declarative JSX
• Use function, not const for components
• Use DaisyUI Tailwind Aria for components and styling
• Implement responsive design with Tailwind CSS (mobile-first approach)

File Organization

• Use lowercase with dashes for directories: components/auth-wizard
• Place static content and interfaces at file end
• Use content variables for static content outside render functions
• Favor named exports for components

State Management

• Minimize use client, useEffect, and setState
• Favor React Server Components (RSC)
• Wrap client components in Suspense with fallback
• Use dynamic loading for non-critical components
• Use useActionState with react-hook-form for form validation

Error Handling

• Model expected errors as return values (avoid try/catch for expected errors)
• Use error boundaries for unexpected errors (error.tsx, global-error.tsx)
• Use useActionState to manage errors and return them to client

Component Library

• DO NOT reference new React libraries if components exist in mollecules or atoms
• Check existing components before creating new ones

Development Workflow

Build and Run Commands

# Backend
dotnet build
dotnet run --project src/Managing.Api

# Frontend
npm run build
npm run dev

# Regenerate API client (after backend changes)
cd src/Managing.Nswag && dotnet build

API Client Generation

1. NEVER update ManagingApi.ts manually
2. After backend endpoint changes:
   • Run the Managing.Api project
   • Execute: cd src/Managing.Nswag && dotnet build
   • This regenerates ManagingApi.ts automatically

Testing

• Write unit tests using xUnit for backend
• Use Mock or NSubstitute for mocking dependencies
• Implement integration tests for API endpoints

Security Guidelines

• IMPORTANT: Handle sensitive data carefully (API keys, private keys, etc.)
• Implement proper authentication and authorization
• Use secure communication protocols
• Validate all user inputs

Database Guidelines

• Use PostgreSQL for relational data
• Use InfluxDB for time-series data (candles, metrics)
• Use MongoDB for document storage
• Implement proper migrations

Orleans Integration (Co-Hosting)

• Use IGrainFactory instead of IClusterClient for co-hosting scenarios
• Orleans automatically provides IGrainFactory when using UseOrleans()
• Avoid circular dependency issues by not manually registering IClusterClient
• Use Orleans grains for high-availability trading bots

Common Patterns

Backend Service Pattern

public class ExampleService : IExampleService
{
    private readonly IExampleRepository _repository;
    private readonly ILogger<ExampleService> _logger;

    public ExampleService(IExampleRepository repository, ILogger<ExampleService> logger)
    {
        _repository = repository;
        _logger = logger;
    }

    public async Task<Example> CreateExampleAsync(ExampleRequest request)
    {
        // Implementation
    }
}

Frontend Component Pattern

interface ComponentProps {
  isLoading: boolean;
  data: SomeType[];
}

function Component({ isLoading, data }: ComponentProps): JSX.Element {
  if (isLoading) return <Loader />;
  
  return (
    <div className="container mx-auto">
      {/* Component content */}
    </div>
  );
}

export default Component;

File Structure Conventions

src/
├── Managing.Api/          # API Controllers
├── Managing.Application/  # Business Logic
├── Managing.Domain/       # Domain Models
├── Managing.Infrastructure/ # Data Access
└── Managing.WebApp/       # React Frontend
    └── src/
        ├── components/
        │   ├── atoms/     # Basic components
        │   ├── mollecules/ # Composite components
        │   └── organism/  # Complex components
        └── services/      # API calls

Important Reminders

• Always implement methods you create
• Check existing code before creating new functionality
• Update multiple layers when necessary
• Build project after finishing edits
• Follow the controller → application → repository pattern
• Use existing components in mollecules/atoms before adding new libraries
• Use IGrainFactory for Orleans co-hosting (not IClusterClient)