wip(cursor): craft cursor rules

.cursor/rules/project-structure.mdc

@@ -1,17 +1,109 @@
+---
+description: Comprehensive overview of the project architecture and organization. Apply when working with the codebase structure or integrating new components.
+globs: *.md
+alwaysApply: true
+---
+
 # Project Structure Guide
 
-- The main source code is in the [src/](mdc:src/) directory.
-- Trading logic is in [src/trading/](mdc:src/trading/), including [trader.py](mdc:src/trading/trader.py), [buyer.py](mdc:src/trading/buyer.py), and [seller.py](mdc:src/trading/seller.py).
-- Monitoring logic is in [src/monitoring/](mdc:src/monitoring/), with various listeners and event processors.
-- Utility functions are in [src/utils/](mdc:src/utils/).
-- Core abstractions and blockchain logic are in [src/core/](mdc:src/core/).
-- Cleanup logic is in [src/cleanup/](mdc:src/cleanup/).
-- Geyser-related code is in [src/geyser/](mdc:src/geyser/).
-- Bot configuration files are in [bots/](mdc:bots/).
-- Trade logs are in [trades/](mdc:trades/).
-- Interface definitions are in [idl/](mdc:idl/).
-- Tests are in [tests/](mdc:tests/).
-description:
-globs:
-alwaysApply: false
----
+## Overview
+
+The pump-bot system is organized into modular components with clear separation of concerns. This architecture facilitates maintainability, testing, and extension of functionality.
+
+## Directory Structure
+
+### Source Code
+
+The main codebase is organized as follows:
+
+- @src/: Root source directory
+  - @src/bot_runner.py: Entry point for bot execution
+  - @src/config_loader.py: Configuration loading and validation
+
+#### Core Components
+
+- @src/core/: Blockchain interaction and protocol abstractions
+  - @src/core/client.py: Solana client implementation
+  - @src/core/wallet.py: Wallet management and transaction signing
+  - @src/core/pubkeys.py: System and program addresses
+  - @src/core/curve.py: Bonding curve mathematics
+  - @src/core/priority_fee/: Priority fee optimization system
+
+#### Trading System
+
+- @src/trading/: Trading execution and strategy
+  - @src/trading/trader.py: Main trading coordination
+  - @src/trading/buyer.py: Token purchase implementation
+  - @src/trading/seller.py: Token sale implementation
+  - @src/trading/position.py: Position tracking and management
+  - @src/trading/base.py: Shared abstractions
+
+#### Monitoring System
+
+- @src/monitoring/: Event detection and processing
+  - @src/monitoring/geyser_listener.py: Geyser-based monitoring
+  - @src/monitoring/logs_listener.py: Log-based monitoring
+  - @src/monitoring/block_listener.py: Block-based monitoring
+  - @src/monitoring/pumpportal_listener.py: PumpPortal integration
+  - @src/monitoring/base_listener.py: Shared listener abstractions
+
+#### Resource Management
+
+- @src/cleanup/: Token account management
+  - @src/cleanup/manager.py: Account cleanup operations
+  - @src/cleanup/modes.py: Cleanup strategy implementation
+
+#### Utilities
+
+- @src/utils/: Shared utilities
+  - @src/utils/logger.py: Logging framework
+  - @src/utils/env.py: Environment configuration
+
+### Configuration
+
+- @bots/: Bot configuration files
+  - @bots/bot-sniper-1-geyser.yaml: Geyser-based sniper configuration
+  - @bots/bot-sniper-2-logs.yaml: Log-based sniper configuration
+  - @bots/bot-sniper-3-blocks.yaml: Block-based sniper configuration
+  - @bots/bot-sniper-4-pp.yaml: PumpPortal sniper configuration
+
+### Program Interfaces
+
+- @idl/: Interface definitions for on-chain programs
+  - @idl/pump_fun_idl.json: Pump.fun protocol interface
+  - @idl/pump_swap_idl.json: Swap interface definition
+  - @idl/raydium_amm_idl.json: Raydium AMM interface
+
+### Testing
+
+- @tests/: Test cases and validation
+  - @tests/compare_listeners.py: Listener comparison framework
+  - @tests/test_geyser_listener.py: Geyser listener tests
+  - @tests/test_logs_listener.py: Logs listener tests
+  - @tests/test_block_listener.py: Block listener tests
+
+### Operational Data
+
+- @logs/: Application logs
+- @trades/: Trading activity records
+
+## Development Flow
+
+1. Configure bot parameters in @bots/*.yaml
+2. Launch bot using @src/bot_runner.py
+3. Monitor execution in @logs/
+4. Review trade outcomes in @trades/trades.log
+
+## Architecture Principles
+
+1. **Modular Design**: Components have clear responsibilities and interfaces
+2. **Configurability**: External configuration for adjustable behavior
+3. **Extensibility**: Easy to add new listeners or trading strategies
+4. **Reliability**: Error handling and recovery throughout the system
+5. **Observability**: Comprehensive logging and monitoring
+
+## Related Documents
+
+- @README.md: Project overview and setup instructions
+- @MAINTAINERS.md: Maintenance guidelines and procedures
+- @CLAUDE.md: Integration with Claude AI for strategy development