# Project Structure & Architecture

## Directory Organization

```
├── src/                          # Source code
│   ├── content.jsx              # Main entry point & content script
│   ├── StaggeredMenu.jsx        # React menu component
│   ├── StaggeredMenu.css        # Menu styles
│   ├── *Manager.js              # Manager classes (storage, panels, etc.)
│   ├── *Extractor.js            # Data extraction utilities
│   ├── *Service.js              # External service integrations
│   ├── Enhanced*.js             # Enhanced feature implementations
│   ├── *.css                    # Component-specific styles
│   └── __tests__/               # Test files
├── dist/                        # Build output (generated)
├── .kiro/                       # Kiro configuration
│   ├── steering/                # Project steering rules
│   └── specs/                   # Feature specifications
├── test-*.html                  # Manual testing pages
└── manifest.json                # Chrome extension manifest
```

## Architecture Patterns

### Manager Pattern
- **Purpose**: Encapsulate complex functionality into focused managers
- **Examples**: `EnhancedStorageManager`, `ItemsPanelManager`, `BlacklistPanelManager`
- **Responsibilities**: State management, UI coordination, data persistence

### Event-Driven Communication
- **Global Event Bus**: `window.amazonExtEventBus` for cross-component communication
- **Event Types**: `product:saved`, `blacklist:updated`, `enhanced:item:saved`
- **Pattern**: Emit events for state changes, listen for updates

### Error Handling Strategy
- **Centralized**: `ErrorHandler` class with retry logic and fallbacks
- **User-Friendly**: Localized error messages (German/English)
- **Graceful Degradation**: Fallback data when services fail

## File Naming Conventions

- **Managers**: `*Manager.js` (e.g., `EnhancedStorageManager.js`)
- **Services**: `*Service.js` (e.g., `MistralAIService.js`)
- **Extractors**: `*Extractor.js` (e.g., `ProductExtractor.js`)
- **Components**: PascalCase for React components (e.g., `StaggeredMenu.jsx`)
- **Tests**: `*.test.js` in `__tests__/` directory
- **Styles**: Component-specific CSS files matching component names

## Code Organization Principles

### Class-Based Architecture
- ES6 classes for managers and services
- Constructor dependency injection
- Public/private method distinction with JSDoc

### React Integration
- Functional components with hooks
- React only for UI components (menu, panels)
- DOM manipulation handled by vanilla JS managers

### Storage Strategy
- **localStorage**: Primary storage for extension data
- **Keys**: Prefixed with `amazon-ext-` or `amazon_ext_`
- **Cross-tab sync**: Storage event listeners for real-time updates

### Testing Structure
- **Unit tests**: Individual component testing
- **Integration tests**: Manager interaction testing
- **Property-based tests**: Using fast-check for robust validation
- **Mocks**: localStorage, DOM APIs, external services