solorpower/AGENTS.md

# SolarPower Agents Guide

This document provides context, commands, and guidelines for AI agents working on the SolarPower codebase.

## 1. Project Overview
SolarPower is an integrated solar power monitoring system consisting of:
- **Crawler**: Python-based data collector running on Oracle Cloud (formerly Synology NAS). Uses Tailscale to route via NAS IP to avoid blocks.
- **API Server**: FastAPI backend on Oracle Cloud acting as a middleware.
- **App**: React Native (Expo) mobile/web application for monitoring.
- **Database**: Supabase (PostgreSQL) for data persistence.

## 2. Directory Structure
- `crawler/`: Python crawlers and scheduler.
  - `crawlers/`: Individual site crawler implementations.
  - `crawler_manager.py`: Smart scheduler using SQLite (`crawler_manager.db`).
- `api_server/`: FastAPI backend.
  - `app/routers/`: API endpoints (`plants`, `stats`, `upload`).
  - `app/core/`: Configuration and utilities.
- `app/`: React Native Expo frontend.
  - `components/`: Reusable UI components.
  - `screens/`: Application screens.

## 3. Development Commands

### 📱 Mobile App (`app/`)
- **Environment**: Node.js, Expo
- **Install**: `npm install`
- **Run (Dev)**: `npx expo start`
  - Press `w` for web, `a` for Android.
- **Build (Web)**: `npx expo export -p web`
  - Outputs to `dist/` directory.
  - Use this command for deployment builds.
- **Lint**: No strict ESLint config. Follow existing code patterns (functional components, hooks).
- **Test**:
  - **E2E**: Use `playwright` skill/tool to verify the web build running on a local server.
  - **Manual**: Run `npx expo start` and use Expo Go.

### ⚡ API Server (`api_server/`)
- **Environment**: Python 3.10+
- **Install**: `pip install -r requirements.txt`
- **Run (Dev)**: `uvicorn app.main:app --reload`
  - Runs on port 8000 by default.
- **Run (Prod)**: Managed via systemd: `sudo systemctl restart solar-api`
- **Docs**: Access Swagger UI at `http://localhost:8000/docs`
- **Test**:
  - No automated test suite (pytest) currently.
  - Verify endpoints manually using `curl` or Swagger UI.

### 🐍 Crawler (`crawler/`)
- **Environment**: Python 3.10+
- **Install**: Manual dependency installation (requests, python-dotenv, supabase).
- **Run (Manual)**: `python main.py`
  - Runs in `LEARNING` or `OPTIMIZED` mode based on `crawler_manager.db`.
- **Run (Force)**: `python main.py --force` (Ignores scheduler constraints)
- **GUI Tool**: `python crawler_gui.py` (For historical data recovery and log cleaning)
- **Testing**:
  - No standard test runner. Use standalone scripts in `tests/`.
  - **Run Single Test**: `python tests/debug_kremc.py` (or similar script for specific site).

## 4. Code Style & Standards

### 🐍 Python (Crawler & API)
- **Style**: Follow PEP 8 standards.
- **Indentation**: 4 spaces.
- **Typing**: Use type hints where possible (`def func(a: int) -> str:`).
- **Frameworks**:
  - **FastAPI**: Use Pydantic models for request/response schemas.
  - **Crawler**: Use `crawler_manager` for scheduling. Do not hardcode run times.
- **Imports**: Group standard lib, third-party, then local modules.
- **Error Handling**: 
  - API: Raise `HTTPException` with clear status codes.
  - Crawler: Catch exceptions per site to prevent one failure from stopping others.
- **Async**: API Server uses `async/await`. Crawler is synchronous (mostly).
- **Naming**: `snake_case` for functions/variables, `PascalCase` for classes.

### ⚛️ JavaScript/React Native (`app/`)
- **Style**: Functional Components with Hooks (`useState`, `useEffect`).
- **Indentation**: 2 spaces.
- **Quotes**: Single quotes `'` preferred for strings.
- **Semicolons**: Always use semicolons.
- **Naming**: `camelCase` for variables/functions, `PascalCase` for components.
- **Styling**: Use `StyleSheet.create({})`. Avoid inline style objects if possible.
- **Navigation**: Uses `@react-navigation`. Ensure strict typing for route params.
- **Libraries**:
  - Charts: `react-native-gifted-charts`
  - UI: `react-native-svg`, `expo-linear-gradient`
- **State**: Local state preferred. Keep components pure where possible.

## 5. Deployment Workflows

### 🚀 Web App Deployment
1. **Build**: Run `npx expo export -p web` locally to generate `dist/`.
2. **Upload**: Use SCP to transfer `dist/` to the server.
   - Example: `scp -r dist user@server:~/dist_temp`
3. **Deploy**: Move the uploaded folder to the web root (`/var/www/html/dist`).
   - Command: `ssh user@server "sudo rm -rf /var/www/html/dist && sudo mv ~/dist_temp /var/www/html/dist"`
4. **Refresh**: `sudo systemctl reload nginx` (optional, for cache clearing).

### ☁️ Server Deployment
1. **Push**: Commit and push changes to the remote Git repository.
2. **Pull**: SSH into the server and pull changes.
   - Command: `ssh user@server "cd ~/solorpower_server && git pull"`
3. **Restart**: Restart the API service.
   - Command: `sudo systemctl restart solar-api`

## 6. Architecture & Patterns

### 🧠 Crawler Scheduler (`crawler_manager.py`)
- **LEARNING Mode**: Runs every cycle to determine update patterns.
- **OPTIMIZED Mode**: Runs only during specific 10-minute windows around the learned update time.
- **Storage**: Uses local SQLite (`site_rules` table) to persist scheduling rules.

### 🌐 API Structure
- **Routers**:
  - `plants`: Basic plant info and real-time status.
  - `stats`: Aggregated statistics (daily, monthly, yearly).
  - `upload`: Excel file processing for manual data entry.
- **CORS**: Configured to allow all origins (`*`) in development.

## 7. Critical Rules for Agents
1.  **Timezones**: All internal logic should handle KST (UTC+9) correctly. Be careful with UTC conversions in DB interactions.
2.  **Data Integrity**: `crawler_manager` prevents duplicate runs. Respect `should_run` checks.
3.  **Error Recovery**: Crawlers must be robust against network failures (retry logic).
4.  **Secrets**: Never commit `.env` files. Use `python-dotenv`.
5.  **Testing**: Always verify changes locally before deploying.
    - **App**: Check UI changes on local web server.
    - **API**: Check endpoints response.
    - **Crawler**: Run debug scripts.
6.  **Networking**: When modifying crawlers, be aware that Oracle Cloud uses Tailscale to route traffic through the Synology NAS (Exit Node) to avoid IP blocks from monitoring sites. Ensure Tailscale is active on the host.