# datawaearth — User Guide

datawaearth is a satellite-intelligence platform that connects observable changes on Earth to investment signals. It monitors commodity and mining assets (lithium, copper, aluminium, rare earths, nickel, manganese, cobalt, iron ore) and global crop conditions (maize, soybean, wheat, coffee) using satellite data (Sentinel-2, MODIS), and turns them into decision-grade signals.

## Getting started

- **Home (dashboard)**: open https://datawaearth.live — no login required. You will see the commodity dashboard: a market ticker band on top and cards for each commodity category.
- **Sign in / Sign up**: click the key icon (Sign in) at the bottom of the left rail. You can register with email + password or with a Google account. On first login you must agree to the Terms of Service.
- **Free vs Pro**: free accounts can open one asset per commodity; other assets are locked. To request Pro access, use the upgrade prompt in the asset list (a request is sent to the administrator, who approves it in the admin panel).
- **Left rail**: the icon column on the left. Top button (🛰️) returns to the dashboard. Each commodity icon (Li, Cu, Al, RE, Ni, Mn, Co, Fe, Maize, Soybean, Wheat, Coffee) opens that commodity page. Admins also see an Admin button. The bottom button signs you in or out.
- **Back navigation**: the browser Back button returns from a commodity page to the dashboard.

## Dashboard (landing page)

- **Ticker band**: live market prices for related instruments (futures, ETFs, equities). Prices come from a market data feed and refresh periodically.
- **Commodity cards**: each card shows representative assets of a commodity. Click a card (or a rail icon) to enter the commodity page. Signing in is required to enter.

## Commodity pages (mining: lithium, copper, etc.)

Layout from left to right: **asset list → asset detail → map**.

- **Asset list**: searchable list of monitored assets (mines/plants). Filter by grade, country, state, or sort by name. Grades are shown as colored dots on each card thumbnail.
- **Asset detail**: opens when you click an asset. Shows facility type, operator, status, tickers (futures/ETF/equity codes), satellite-signal description, and a Related news timeline collected automatically for that asset. Admins can Edit asset fields or add/delete assets.
- **Map**: satellite basemap with asset markers (● mine, +plant / ▲ plant only; marker color = grade). Click a marker to open its detail. Use the Satellite / Map buttons in the header to switch the basemap.
- **Satellite timelapse**: with an asset selected, the timeline bar at the bottom of the map plays satellite imagery over time (2017 → today). Major mining assets play pre-rendered frames instantly; other locations use live Sentinel-2 tiles (zoom in if prompted — live tiles need zoom level 10+). Login is required.
- **AI analysis (chat)**: the 🤖 panel docks next to the detail panel. Ask questions about the selected asset; answers are grounded in our asset registry, collected news, and satellite signals. See "AI chat" below.
- **Narrow windows**: if the window is too narrow to show all panels, a horizontal scrollbar appears at the bottom — scroll sideways to reach hidden panels. Panels (NDVI chart, AI chat) can also be closed with their ✕ button, and the chart panel width can be dragged.

## Crop pages (maize, soybean, wheat, coffee)

Crop pages show a **crop condition signal** per producing country.

- **Header**: grade summary — Healthy / Normal / Watch / Alert / Unrated with counts. Each country asset is graded from satellite vegetation health.
- **Country list**: one card per producing country, ordered by **annual production volume** (USDA estimate; million tonnes for grains, million 60kg bags for coffee) by default — the biggest producers first. Filter by grade or country, or re-sort by name. The production figure is shown in the country's detail panel.
- **Map**: sample points are drawn as colored dots (color = that sample's status) inside cultivation belts, with country labels. Selecting a country zooms to it.
- **NDVI chart panel**: opens for a selected country. It shows:
  - **Baseline band**: multi-year median and interquartile range of NDVI over the season.
  - **Year lines**: individual years; toggle All / Current / Baseline or specific years with checkboxes.
  - **Smoothing**: Off / 5d / 10d / 20d moving average.
  - **Indicators**: Base score (0–100, vs baseline), Stall (growth stagnation), Level-Low, Critical flags, and the overall grade badge. A "Today" marker shows the current day of year.
- **Grades meaning**: Healthy = vegetation at or above baseline; Normal = near baseline; Watch = mild deficit or stall; Alert = significant deficit; Unrated = not enough data.
- **Data source**: MODIS daily NDVI at sample points across each country's growing region, updated automatically every day.

## Monitoring regions (My Regions)

Register any area on Earth and have it monitored daily from satellite after admin approval.

- **Register**: right-click anywhere on a commodity page map and choose "이 지역 모니터링 요청". Give the region a name, an optional note, and pick the area radius (2 / 5 / 10 km around the point). Login required.
- **Approval**: an administrator reviews the request (pending → approved or rejected). Once approved, the area is measured **daily** — the satellite area-mean vegetation index (MODIS NDVI, 10-day composite) is recorded, and Δ shows the change versus the average of recent measurements. |Δ| ≥ 0.08 is flagged (possible clearing, flooding or construction — check the area's timelapse).
- **Favorites (★)**: every asset card in a commodity list has a star — click it to bookmark the asset. Favorited assets appear in **My Regions** under "★ Favorite assets" (with a dot on the map in the commodity's color); from there you can jump back to the asset's commodity page (↗) or remove the favorite (✕).
- **My Regions**: the 📍 button in the left rail opens a page laid out like the commodity pages — a card list of your regions on the left (with status: Awaiting approval / Monitoring / Rejected), a detail panel for the selected region (status explanation, latest NDVI, Δ, measurement history, admin note), and a satellite map on the right where each region is drawn as a colored rectangle (amber = awaiting, green = monitoring, red = rejected). Click a card or a rectangle to zoom to it.
- **Limits (plan-based; this will be part of the paid offering)**: Free — 1 active region, up to 100 km². Pro — 5 regions, up to 1,000 km² each. Up to 5 new requests per day.

## AI chat

- Available on commodity/crop pages (🤖 panel) and in the admin panel (floating 🤖 button, bottom-right).
- The assistant is grounded in: the selected asset's profile, our collected news, satellite signal descriptions, and this user guide — so you can also ask "how do I …" questions about using the site.
- It replies in the language you ask in (Korean, English, ...).
- If it responds with "AI unavailable" (503), the server has no LLM key configured — contact the administrator.

## Help page

- Click the ❓ Help button in the left rail (or the Help button in the admin top bar) to open this guide at any time.

## Admin panel (/admin)

Visible only to accounts whose role has admin menus. Navigation works like the main app: a **left rail of categories** — Collection (📡), Manage (🗂️), Validate (✅), Members (👥), Roles (🔑), Others (⚙️) — and the selected category's **features as a row of buttons at the top**. Category → features:

- **Collection** → Crops, Timelapse · **Manage** → Samples, Seasons · **Validate** → Quality · **Members** → Users, Monitoring, Pro Requests · **Roles** → Roles & Permissions · **Others** → Dashboard Publishing, News.

Feature reference:

- **Crops**: crop NDVI collection operations.
  - *Daily schedule* card: toggle automatic daily collection and set its run time (KST, default 03:10). What it does: every day at the set time it collects current-year MODIS NDVI for all sample points of active crop assets, merging only new observations (assets already completed today are skipped); results feed the country charts and grades. Time changes apply within ~10 minutes (no restart needed). Recent auto runs are listed on the card.
  - *Run collection* card: run a manual sweep for a crop asset and year range; progress appears in the Jobs table (cancel supported).
  - *CSV upload* card: upload sample points as CSV (headers: lon, lat, name optional). Running an upload creates the asset if needed and backfills a 10-year baseline.
- **Samples**: search / edit / delete sample points (filters: commodity, country, sample id). Deleting a sample also removes its NDVI rows safely. Bulk delete with checkboxes (two-step confirm).
- **Quality**: peak-DOY outlier scan. Set a threshold (days) and Scan; suspicious samples appear on the left. Click a row to inspect — mini satellite map with the point marker and a multi-year NDVI chart with peak/cluster reference lines — then Delete if it is a bad sample (e.g., wrong land cover).
- **Seasons**: growing-season detection per asset (SOS / Peak / EOS, auto v2). Recompute runs synchronously and updates the table.
- **Users** (Members): user list — activate/deactivate, delete, plan Free/Pro toggle.
- **Roles & Permissions** (Roles): role management — which menus each role can access (AI, collection/crops management, user management).
- **Dashboard Publishing**: curate dashboard cards (hotspots) — create from candidates or monitoring requests, edit title/description, generate or upload thumbnails, publish/unpublish, reorder.
- **News**: automatic news collection status per asset — collected counts, last run, collection interval (hours), run-once per asset, enable/disable.
- **Monitoring** (Members): user-requested monitoring regions. Shows requester email and plan (Free/Pro), region name/coordinates/area, status dropdown (pending / reviewing / approved / rejected / done), latest NDVI and Δ, last check time, and an admin note field. Approving starts daily satellite monitoring immediately (first measurement runs right away; then daily at 04:40 KST). "Check now" measures once on demand. Plan limits are enforced automatically (Free: 1 region ≤ 100 km²; Pro: 5 regions ≤ 1,000 km²).
- **Pro Requests**: approve or reject users' Pro access requests.
- **Timelapse**: pre-rendered timelapse frame status per asset — rebuild frames, adjust the area half-width (km), pagination.
- **Admin AI chat**: the floating 🤖 button (bottom-right) answers questions about admin workflows using this guide.

## Accounts, roles and permissions

- The first registered account automatically becomes the administrator.
- Roles define menu permissions: **AI** (chat/analysis), **collection management** (admin Crops/Samples/Quality/Seasons), **user management** (admin Users & Roles and other admin sections).
- Regular users get the AI menu by default. Satellite timelapse and imagery require only login.

## Troubleshooting / FAQ

- **"Login required" on timelapse or imagery**: sign in first — satellite imagery endpoints require an account.
- **"Zoom in (zoom 10+)"**: live Sentinel-2 tiles are only requested at zoom level 10 or higher; zoom into the area.
- **Asset is locked (🔒)**: free plan shows one asset per commodity. Request Pro access from the prompt in the asset list.
- **AI chat says unavailable (503)**: no LLM provider key is configured on the server; contact the administrator.
- **Timelapse shows "building"**: frames for that asset are being generated in the background; try again in a few minutes.
- **A panel is cut off on a small screen**: use the horizontal scrollbar at the bottom of the page body, or close/resize panels.
- **Crop chart shows no data**: the country may have too few samples or collection may not have run yet — check admin Crops jobs.