PriceUpdaterAppv2/.kiro/steering/structure.md

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