managing-apps/CLAUDE.md

# CLAUDE.md

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

## Common Development Commands

### Backend (.NET)
```bash
# Build entire solution
dotnet build src/Managing.sln

# Run main API (port 80/443)
dotnet run --project src/Managing.Api/Managing.Api.csproj

# Run worker API (port 81/444)
dotnet run --project src/Managing.Api.Workers/Managing.Api.Workers.csproj

# Run tests
dotnet test src/Managing.Application.Tests/
dotnet test src/Managing.Infrastructure.Tests/

# Run specific test
dotnet test --filter "TestMethodName"

# Database migrations
dotnet ef database update --project src/Managing.Infrastructure.Database/Managing.Infrastructure.Databases.csproj --context ManagingDbContext
dotnet ef migrations add <MigrationName> --project src/Managing.Infrastructure.Database/Managing.Infrastructure.Databases.csproj --context ManagingDbContext

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

### Frontend (React/TypeScript)
```bash
cd src/Managing.WebApp

# Install dependencies
npm install

# Development server
npm run dev

# Build for production
npm run build

# Linting and type checking
npm run lint
npm run typecheck

# Tests
npm run test
```

### Full Stack Development
```bash
# Quick start with Docker
./scripts/build_and_run.sh

# Alternative using Aspire
cd src && ./run-aspire.sh
```

## Architecture Overview

### Clean Architecture Pattern
The codebase follows Clean Architecture with clear layer separation:
- **Domain** (`Managing.Domain`): Business entities and core rules
- **Application** (`Managing.Application*`): Use cases, commands, and business orchestration  
- **Infrastructure** (`Managing.Infrastructure.*`): External integrations (databases, Web3, messaging)
- **Presentation** (`Managing.Api*`): REST APIs and controllers

### Service Architecture
Multiple coordinated services handle different concerns:
- **Managing.Api**: Main trading operations, bot management, backtesting
- **Managing.Api.Workers**: Background workers for price data, genetic algorithms, statistics
- **Managing.Web3Proxy**: Node.js service for Web3/GMX blockchain interactions
- **Managing.WebApp**: React frontend with real-time SignalR updates

### Data Storage Strategy (Polyglot Persistence)
- **PostgreSQL**: Transactional data (users, bots, positions, scenarios, backtests)
- **InfluxDB**: Time-series data (OHLCV candles, agent balances, performance metrics)
- **MongoDB**: Document storage for certain data types

### Key Domain Concepts
- **Bot**: Abstract base with lifecycle management for trading automation
- **Position**: Trading positions with PnL tracking and trade history
- **Scenario**: Collections of technical indicators defining trading strategies
- **Indicator**: Technical analysis tools (RSI, MACD, EMA, SuperTrend, etc.)
- **MoneyManagement**: Risk parameters (stop loss, take profit, position sizing)
- **Account**: Multi-exchange trading accounts (CEX, GMX V2, Privy wallets)

## Development Patterns

### Adding New Features
1. **Domain First**: Create entities in `Managing.Domain`
2. **Application Layer**: Add services/command handlers in `Managing.Application`
3. **Infrastructure**: Implement repositories and external integrations
4. **API Layer**: Add controllers and endpoints
5. **Frontend**: Update React components and API client

### Bot Development
- Inherit from `Bot` base class in `Managing.Domain/Bots/`
- Implement `SaveBackup()` and `LoadBackup()` for persistence
- Use dependency injection pattern for services
- Follow worker pattern for background execution

### Adding Technical Indicators
1. Create indicator class implementing `IIndicator`
2. Add to `IndicatorType` enum in `Managing.Common`
3. Register in DI container via `ApiBootstrap`
4. Implement calculation logic in `TradingService`

### Database Changes
1. Update entities in domain layer
2. Modify `ManagingDbContext` with new DbSets
3. Generate EF Core migration
4. Update repository interfaces and implementations
5. Consider InfluxDB for time-series data

### Web3 Integration
- GMX V2 interactions go through `Managing.Web3Proxy` Node.js service
- Use `Managing.Infrastructure.Web3` for .NET integration
- Privy handles wallet management and authentication

## Configuration & Environment

### Key Configuration Files
- `src/Managing.Api/appsettings.*.json`: Main API configuration
- `src/Managing.Api.Workers/appsettings.*.json`: Worker configuration
- `src/Managing.WebApp/.env`: Frontend environment variables

### Environment-Specific Deployments
- Development: `appsettings.Development.json`
- Sandbox: `appsettings.Sandbox.json`
- Production: `appsettings.Production.json`
- Docker: `appsettings.Oda-docker.json`

## Important Development Guidelines

### Quantitative Finance Principles
- Use `decimal` for all monetary calculations (never `float` or `double`)
- Implement proper audit trails for financial operations
- Validate trading strategies with historical backtesting
- Optimize time-series processing for performance

### Code Architecture Rules
- Follow Controller → Application → Repository pattern (never inject repositories directly into controllers)
- Use CQRS pattern with command handlers for complex operations
- Implement proper error handling with user-friendly messages
- Maintain separation between domain logic and infrastructure concerns

### API Development
- Follow RESTful conventions
- Use attribute routing in controllers
- Return appropriate HTTP status codes
- Implement proper validation using Data Annotations

### Testing Strategy
- Unit tests focus on domain logic and indicators
- Integration tests for external service interactions
- Use data-driven testing with JSON fixtures for backtesting scenarios

## Real-time Features
- SignalR hubs provide live updates for trading data, bot status, and market information
- Frontend uses reactive patterns with real-time price feeds and position updates