📋 WeatherDash Architecture & Documentation Consolidation
1. Application Document Flow & Dependency Chain
To maintain stability across both the AJAX Single Page Application (SPA) wrapper and background CLI cron scripts, all components must adhere to a strict initialization and dependency order:
System Bootstrap & Environment (weather.env.php / weather.core.php): Loads configuration constants (such as WX_ROOT), environment variables, time helpers (wx_now, wx_utc), and JSON-lines logging facilities.
Database Layer (weather.db.php): Initializes PDO connections and provides safe query wrappers (wx_exec, wx_row, wx_all).
Location & Geocoding (weather.locations.php): Manages location hydration, ZIP-to-coordinate geocoding (wx_geocode_zip), and NWS grid resolution (wx_location_resolve_nws).
Ingestion Engine (weather.ingest.php): Polls active weather sources, handles observation/forecast storage, and manages cron file-locking (ingest.lock).
2. "Add Station" Module: Current State & Observation Gap
Status: Fully operational multi-step UI workflow. It performs ZIP code validation, queries Zippopotam for coordinates, retrieves NWS grid metadata via the Points API, and commits the record to wx_locations.
The Observation Challenge: When a station is newly added, its record exists in wx_locations, but the wx_observations and wx_forecasts tables remain empty until the first synchronization run.
Resolution: Background ingestion runs every 5 minutes via cron (*/5 * * * *). Direct single-station ingestion (wx_ingest_location) can be triggered, provided global file locks and core helper functions (wx_location_resolve_nws) are cleanly scoped to avoid re-declaration errors.
3. Updated FAQ & Testing Guide
Frequently Asked Questions
Q: Why do newly added stations occasionally show 404 errors on the dashboard?
A: The wx_observations table requires initial data ingestion. If instant synchronization is bypassed or locked, the dashboard awaits the next 5-minute cron execution tick.
Q: How do I test form endpoints from the command line?
A: Use curl with -k to bypass self-signed local SSL certificate warnings:
Bash
curl -k -d "action=lookup&zip=90210" -X POST https://localhost:8443/weatherdash/pages/add.station.php
4. Technical Lessons Learned
Modular Fragment Inclusion: AJAX-loaded pages (pages/*.php) execute within the context of an already initialized parent SPA frame. Requiring full application bootstraps blindly can trigger fatal PHP errors due to function or constant re-declarations. Always guard inclusions with function_exists() or defined().
Server Telemetry Visibility: Maintaining an on-screen execution log ($debugLog) inside admin and configuration forms provides immediate, real-time tracking of cURL responses, SQL execution, and payload states without needing to parse raw server error logs.
5. Prioritized Task Roadmap
UTC Timing & Iconography: Standardize all timestamp conversions to UTC and complete the migration from Lucide to FontAwesome across templates.
Layout & Scrolling UX: Decouple the sidebar scroll container from the main-content pane so navigation remains fixed while content scrolls independently.
Navbar Alerts & Station Selection: Implement dynamic cross-station alert checking and automatic UI state refresh (wsUI_updateStations()) when switching or adding locations.
Documentation & Manifest Hygiene: Organize documentation into structured categories (README.md, tasks.md, faq.md, lessons_learned.md) following administrative auditing standards (admin.Req.md).
Would you like to focus next on implementing independent sidebar scrolling or finalizing the automated observation sync trigger for newly added stations?