---
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

## 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