# Project Structure

This is a monorepo-style project with separate backend and frontend applications.

## Expected Organization

```
/
├── backend/                 # TypeScript backend server
│   ├── src/
│   │   ├── scrapers/       # Playwright scraping modules
│   │   ├── api/            # REST endpoints
│   │   ├── websocket/      # WebSocket handlers
│   │   ├── database/       # Prisma/Drizzle schema & migrations
│   │   ├── services/       # Business logic (price index calculation)
│   │   └── utils/          # Shared utilities
│   ├── tests/
│   ├── Dockerfile
│   └── package.json
│
├── electron-app/           # Electron + React frontend
│   ├── src/
│   │   ├── main/          # Electron main process
│   │   ├── renderer/      # React UI components
│   │   │   ├── components/
│   │   │   ├── pages/
│   │   │   ├── hooks/
│   │   │   └── store/     # Zustand/Recoil state
│   │   └── shared/        # IPC types & shared code
│   ├── tests/
│   └── package.json
│
├── shared/                 # Shared TypeScript types/interfaces
│   └── types/
│
├── .kiro/                  # Kiro AI assistant configuration
│   └── steering/           # Project guidance documents
│
├── PRD.md                  # Product Requirements Document
└── README.md
```

## Architecture Patterns

- **Backend**: Modular service-oriented architecture
  - Scrapers are isolated, containerized services
  - API layer is stateless for horizontal scaling
  - TimescaleDB handles time-series data efficiently

- **Frontend**: Component-based React architecture
  - Sandboxed renderer process for security
  - Secure IPC messaging between main and renderer
  - Client-side alert evaluation logic

- **Database Schema**: Three main tables
  - `raw_vendor_prices`: Individual vendor listings
  - `price_index`: Computed median index values
  - `scrape_log`: Monitoring and debugging

## Key Conventions

- All code in TypeScript with strict type checking
- Scrapers include retry logic (3 attempts) and error handling
- WebSocket auto-reconnect logic in Electron app
- Signed binaries for all platform distributions
- No remote code evaluation in Electron (security)