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.