Philippine Open Geodesy Framework (POGF) Monorepo

The Philippine Open Geodesy Framework (POGF) is a unified platform for the ingestion, processing, analysis, and distribution of geodetic data from the PHIVOLCS GNSS network. This monorepo consolidates disparate manual workflows into a cohesive, maintainable system.

🏗️ Project Structure

The project is organized as a monorepo containing shared packages, specialized services, and utility tools:

movefaults_clean/
├── packages/
│   ├── pogf-geodetic-suite/     # Core logic: transforms, RINEX QC, IGS downloader
│   └── CORS-dashboard/          # Legacy React/GraphQL dashboard (reference only)
├── services/
│   ├── vadase-rt-monitor/       # Real-time NMEA displacement monitoring
│   ├── ingestion-pipeline/      # Automated RINEX ingestion (Celery-based)
│   ├── bernese-workflow/        # Bernese GNSS Software (BPE) orchestrator
│   └── field-ops/               # Digital field logsheet PWA (FastAPI + React)
├── tools/
│   ├── drive-archaeologist/     # CLI for excavating legacy GNSS data
│   └── velocity-reviewer/       # Web UI for interactive time series outlier review
├── analysis/                    # Legacy research scripts (to be ported)
└── docs/                        # Project roadmap, tech specs, and ADRs

🛠️ Technical Implementation Details

🗄️ Database Architecture

• Engine: PostgreSQL 16+ with PostGIS (geospatial) and TimescaleDB (time-series) extensions.
• Schema Isolation:
  • public: Core geodetic metadata (stations, rinex_files, timeseries_data).
  • field_ops: Logsheets, equipment inventory, and staff records.
• Migrations: Managed via Alembic, ensuring versioned schema evolution across all environments.

📥 Unified Ingestion Pipeline (services/ingestion-pipeline)

• Stack: Python, Celery, Redis.
• Workflow:
  1. Standardization: Handles multiple compression formats (.gz, .zip, .Z) and Hatanaka decompression (.crx, .??d → .rnx, .??o) using crx2rnx.
  2. Validation: Multi-stage check including a fast header scan (RINEX version detection) and deep quality control via teqc.
  3. Metadata Extraction: Parses fixed-width RINEX headers to extract station codes, sampling intervals, receiver/antenna types, and observation windows.
  4. Persistence: Idempotent loading into PostgreSQL with MD5-based deduplication.

📡 VADASE Real-Time Monitor (services/vadase-rt-monitor)

• Architecture: Hexagonal (Ports & Adapters) for high testability and source/output flexibility.
• Core Logic:
  • Consumes NMEA 0183 streams (via TCP or File).
  • Parsers for $GNLVM (Velocity) and $GNLDM (Displacement) sentences.
  • Smart Integration: A "Leaky Integrator" (High-pass filter) that compensates for "Velocity-as-Displacement" artifacts found in some receiver firmwares.
  • Event Detection: Real-time thresholding on horizontal velocity magnitude (mm/s) to trigger seismic event alerts.

🗺️ Digital Field Operations (services/field-ops)

• Stack: FastAPI (Backend), React/Vite (Frontend PWA).
• Offline-First: Uses IndexedDB for local storage and Service Workers for background synchronization.
• Idempotency: Client-side UUID generation (client_uuid) ensures that logsheet submissions are idempotent even during flaky network conditions.
• Equipment Tracking: QR-code based inventory system to link physical hardware to geodetic site visits.

📈 Bernese Workflow Orchestrator (services/bernese-workflow)

• Target: Bernese GNSS Software v5.4 (Linux/Windows).
• Orchestration: Python wrapper for the Bernese Processing Engine (BPE).
• Templating: Uses Jinja2 to dynamically generate .INP (Input) and .PCF (Process Control) files based on PHIVOLCS-specific processing strategies.
• Automation: Interfaces with startBPE.pm for non-interactive execution of multi-step processing campaigns.

🔍 Velocity Reviewer (tools/velocity-reviewer)

• Stack: FastAPI, Uvicorn, Plotly.
• Logic: Browser-based replacement for legacy Matplotlib GUIs. Features interactive ENU (East-North-Up) time series plots with:
  • Automated Outlier Detection: Based on Interquartile Range (IQR).
  • Point-and-Click Selection: Human-in-the-loop outlier marking.
  • PLOT File Stripping: Direct export of cleaned data files for subsequent velocity estimation.

🚀 Getting Started

Prerequisites

• Python 3.11+
• uv (highly recommended for dependency management)
• Docker and Docker Compose (for database and services)

Installation

1. Clone the repository:

   git clone https://github.com/alfiepelicano/move-faults-monorepo.git
   cd move-faults-monorepo

2. Sync dependencies: Using uv (fastest):

   uv sync

3. Environment Setup: Copy the example environment files and adjust as necessary:

   cp tiger-cloud-pogf-db-credentials.env.example .env

4. Start Infrastructure:

   docker-compose up -d

🗺️ Roadmap

The project is currently in a phased implementation:

• Tier 1 (Foundational): Geodetic Database and Documentation Portal. ✅
• Tier 2 (Ingestion): Field Ops, RINEX QC, and IGS Downloader. 🔄
• Tier 3 (Processing): Automated Bernese Workflow. 🔄 (Research Complete)
• Tier 4 (Analysis): Post-Processing Suite and Public Data Portal. 🔄

For a detailed breakdown, see roadmap.md.

📄 License

MIT — see LICENSE.

Copyright is held by PHIVOLCS/DOST, not by an individual: this work was produced on institute hardware, in the course of employment, in service of PHIVOLCS research mandates.

The licence covers the software and documentation in this repository. It does not cover GNSS observation data (the file server is the system of record, release is governed by agency policy, and PAGENET is NAMRIA's under a separate MOU), nor the third-party tools this code invokes — Bernese, teqc, gfzrnx and RNXCMP each carry their own terms. NOTICE states the full scope.

✍️ Citing this work

See CITATION.cff, or use GitHub's Cite this repository button. Authorship and copyright are separate: the copyright holder is PHIVOLCS/DOST, the author credited for citation is below.

✍️ Authors

• Alfie Pelicano — Lead Developer, PHIVOLCS-DOST — alfieprojects.dev@gmail.com