# Project Structure

## Directory Organization

```
shopify-price-updater/
├── src/                      # Main application source code
│   ├── config/               # Configuration management
│   │   └── environment.js    # Environment variable validation & loading
│   ├── services/             # Business logic services
│   │   ├── shopify.js        # Shopify API client & GraphQL operations
│   │   ├── product.js        # Product operations & price calculations
│   │   └── progress.js       # Progress tracking & logging service
│   ├── utils/                # Utility functions
│   │   ├── price.js          # Price calculation & validation utilities
│   │   └── logger.js         # Logging utilities & formatters
│   └── index.js              # Main application entry point
├── tests/                    # Test suites
│   ├── config/               # Configuration tests
│   ├── services/             # Service layer tests
│   ├── utils/                # Utility function tests
│   ├── integration/          # Integration tests
│   └── index.test.js         # Main application tests
├── backend/                  # Separate backend component (minimal)
│   └── .env                  # Backend-specific environment config
├── .env                      # Main environment configuration
├── .env.example              # Environment template
├── Progress.md               # Generated operation logs
├── debug-tags.js             # Standalone tag analysis script
└── test-*.js                 # Individual test scripts
```

## Code Organization Patterns

### Service Layer Structure

- **ShopifyService**: API client, authentication, retry logic
- **ProductService**: Product fetching, validation, price updates
- **ProgressService**: Logging, progress tracking, file operations

### Configuration Management

- Centralized in `src/config/environment.js`
- Validation at startup with clear error messages
- Environment-specific defaults and overrides

### Error Handling Strategy

- Service-level error categorization (rate limits, network, validation)
- Comprehensive retry logic with exponential backoff
- Detailed error logging with context preservation

### Testing Structure

- Unit tests for utilities and individual services
- Integration tests for complete workflows
- Mock-based testing for external API dependencies
- Separate test files for different operation modes

## File Naming Conventions

- **Services**: `[domain].js` (e.g., `shopify.js`, `product.js`)
- **Utilities**: `[function].js` (e.g., `price.js`, `logger.js`)
- **Tests**: `[module].test.js` or `test-[feature].js`
- **Configuration**: Descriptive names (e.g., `environment.js`)

## Entry Points

- **Main Application**: `src/index.js` - Complete price update workflow
- **Debug Tools**: `debug-tags.js` - Tag analysis and troubleshooting
- **Test Scripts**: `test-*.js` - Individual feature testing