# 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
│
├── flutter_app/            # Flutter cross-platform app
│   ├── lib/
│   │   ├── models/        # Data models (PriceData, PriceAlert)
│   │   ├── providers/     # State management (Provider)
│   │   ├── services/      # API, WebSocket, Storage services
│   │   ├── screens/       # UI screens (HomeScreen)
│   │   ├── widgets/       # Reusable UI components
│   │   └── main.dart      # App entry point
│   ├── assets/            # Images, fonts, etc.
│   ├── .env               # Environment configuration
│   └── pubspec.yaml       # Dependencies
│
├── electron-app/          # Legacy Electron app (deprecated)
│   └── ...                # Kept for reference
│
├── 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**: Flutter widget-based architecture
  - Provider pattern for state management
  - Service layer for API/WebSocket communication
  - Client-side alert evaluation logic
  - Cross-platform: Windows, macOS, Linux, Android, iOS

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

## Key Conventions

- Backend: TypeScript with strict type checking
- Frontend: Dart with null safety
- Scrapers include retry logic (3 attempts) and error handling
- WebSocket auto-reconnect logic in Flutter app
- Signed binaries for all platform distributions
- Flutter: No eval or dynamic code execution (security)