rmtPocketWatcher/.kiro/steering/structure.md

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)