Gate 1 Complete: Foundations - Documentation, Backend Config, and CI

.github/workflows/visionos-build.yml

@@ -0,0 +1,170 @@
+name: VisionOS Build and Test
+
+on:
+  push:
+    branches: [ main, jade ]
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  build-visionos:
+    name: Build VisionOS App
+    runs-on: macos-14
+
+    steps:
+    - name: Checkout code
+      uses: actions/checkout@v4
+
+    - name: Setup Xcode
+      uses: maxim-lobanov/setup-xcode@v1
+      with:
+        xcode-version: '15.4'
+
+    - name: Cache Xcode derived data
+      uses: actions/cache@v4
+      with:
+        path: ~/Library/Developer/Xcode/DerivedData
+        key: ${{ runner.os }}-xcode-${{ hashFiles('**/project.pbxproj') }}
+        restore-keys: |
+          ${{ runner.os }}-xcode-
+
+    - name: Build VisionOS App
+      run: |
+        cd visionOS
+        xcodebuild clean build \
+          -project MempoolVisionOS.xcodeproj \
+          -scheme MempoolVisionOS \
+          -destination 'platform=visionOS Simulator,name=Apple Vision Pro' \
+          -configuration Debug \
+          CODE_SIGNING_ALLOWED=NO
+
+    - name: Run Swift Tests
+      run: |
+        cd visionOS
+        xcodebuild test \
+          -project MempoolVisionOS.xcodeproj \
+          -scheme MempoolVisionOS \
+          -destination 'platform=visionOS Simulator,name=Apple Vision Pro' \
+          CODE_SIGNING_ALLOWED=NO
+      continue-on-error: true
+
+    - name: Archive for Distribution
+      if: github.ref == 'refs/heads/main'
+      run: |
+        cd visionOS
+        xcodebuild archive \
+          -project MempoolVisionOS.xcodeproj \
+          -scheme MempoolVisionOS \
+          -destination 'generic/platform=visionOS' \
+          -archivePath build/MempoolVisionOS.xcarchive \
+          CODE_SIGNING_ALLOWED=NO
+
+    - name: Upload Build Artifacts
+      if: github.ref == 'refs/heads/main'
+      uses: actions/upload-artifact@v4
+      with:
+        name: visionos-archive
+        path: visionOS/build/MempoolVisionOS.xcarchive
+        retention-days: 30
+
+  test-backend:
+    name: Test Backend Configuration
+    runs-on: ubuntu-latest
+
+    steps:
+    - name: Checkout code
+      uses: actions/checkout@v4
+
+    - name: Setup Docker Buildx
+      uses: docker/setup-buildx-action@v3
+
+    - name: Test Backend Docker Compose
+      run: |
+        cd backend
+        # Validate compose file
+        docker compose -f compose.yml config
+
+        # Test that images can be pulled
+        docker compose -f compose.yml pull --ignore-pull-failures
+
+    - name: Validate Environment Configuration
+      run: |
+        cd backend
+        # Check that example env file has required variables
+        grep -q "BITCOIN_RPC_HOST" .env.example
+        grep -q "NETWORK" .env.example
+        grep -q "BACKEND_PORT" .env.example
+
+  lint-and-validate:
+    name: Lint and Validate
+    runs-on: ubuntu-latest
+
+    steps:
+    - name: Checkout code
+      uses: actions/checkout@v4
+
+    - name: Validate Documentation
+      run: |
+        # Check that all required docs exist
+        test -f docs/ARCHITECTURE.md
+        test -f docs/DECISIONS.md
+        test -f docs/OPERATIONS.md
+        test -f docs/ISSUE_LOG.md
+        test -f docs/WEEKLY_REPORT.md
+
+        # Check that README_SPEC.md quality gates are documented
+        grep -q "Foundations Gate" README_SPEC.md
+        grep -q "Interaction Gate" README_SPEC.md
+        grep -q "Completeness Gate" README_SPEC.md
+        grep -q "Polish Gate" README_SPEC.md
+
+    - name: Validate License Compliance
+      run: |
+        # Check AGPL-3.0 license exists
+        test -f LICENSE
+        grep -q "GNU Affero General Public License" LICENSE
+
+        # Check for proper attribution
+        grep -q "Mempool Open Source Project" LICENSE
+
+    - name: Check VisionOS Project Structure
+      run: |
+        # Validate Xcode project exists
+        test -f visionOS/MempoolVisionOS.xcodeproj/project.pbxproj
+
+        # Check key Swift files exist
+        test -f visionOS/MempoolVisionOS/MempoolVisionOSApp.swift
+        test -f visionOS/MempoolVisionOS/ContentView.swift
+        test -f visionOS/MempoolVisionOS/Services/MempoolService.swift
+        test -f visionOS/MempoolVisionOS/Models/Block.swift
+
+    - name: Validate Backend Configuration
+      run: |
+        # Check backend files exist
+        test -f backend/compose.yml
+        test -f backend/.env.example
+
+        # Validate Docker compose syntax
+        cd backend && docker compose -f compose.yml config > /dev/null
+
+  security-scan:
+    name: Security Scan
+    runs-on: ubuntu-latest
+
+    steps:
+    - name: Checkout code
+      uses: actions/checkout@v4
+
+    - name: Run Trivy vulnerability scanner
+      uses: aquasecurity/trivy-action@master
+      with:
+        scan-type: 'fs'
+        scan-ref: '.'
+        format: 'sarif'
+        output: 'trivy-results.sarif'
+
+    - name: Upload Trivy scan results
+      uses: github/codeql-action/upload-sarif@v2
+      if: always()
+      with:
+        sarif_file: 'trivy-results.sarif'

README_SPEC.md

@@ -0,0 +1,95 @@
+# Spatial Mempool — VisionOS 2 (Fork of mempool.space)
+
+**Mission**  
+Build a polished, fully-functional **VisionOS 2 app** that reimagines [mempool.space](https://mempool.space) as an interactive 3D experience. Optimize for elegance, design quality, and *wow factor* suitable for a VP review. Work autonomously; present a finished package only after passing each quality gate.
+
+---
+
+## Objectives
+- VisionOS 2 (RealityKit + SwiftUI) app visualizing the Bitcoin mempool + recent blocks in 3D.  
+- Live data via mempool backend (REST + WebSocket). Public or self-hosted node support.  
+- Executive-quality design and documentation (VP-ready deck).  
+- Strict AGPL-3.0 compliance.
+
+### Non-Goals (this phase)
+- Lightning topology, ordinals, multi-chain, or custom indexers.  
+- Advanced analytics beyond fee projections and backlog visuals.
+
+---
+
+## Quality Gates
+
+### 1. Foundations Gate — “Ready to Build”
+- Decide: keep/restructure/restart repo; justify in `docs/DECISIONS.md`.  
+- VisionOS 2 skeleton compiles on CI (Xcode 16).  
+- Dockerized mempool backend with config for public vs. self-hosted node; Tor proxy optional.  
+- Data adapters: REST bootstrap + WS streaming for blocks/tx/fee data.  
+- AGPL-3.0 license + attribution in place.  
+- Basic telemetry/logging; feature flags for heavy visuals.  
+
+**Artifacts:** CI badge/screens, `backend/compose.yml`, `docs/ARCHITECTURE.md`.
+
+---
+
+### 2. Interaction Gate — “It Feels Great”
+- **Scenes:**  
+  - Mempool View: stacked fee strata; live inflow; density conveys backlog.  
+  - Blocks View: floating slabs for recent blocks; immersive entry to inspect txs.  
+- Gaze/hand interactions reliable and performant.  
+- Smooth frame rate; back-pressure handling for WS bursts.  
+- Design system (type, color, motion rules) codified; 2–3 explorations compared in `docs/DESIGN_EXPLORATIONS.pdf`.  
+
+**Artifacts:** short demo capture (≤30s), perf notes, `docs/DESIGN_TOKENS.md`.
+
+---
+
+### 3. Completeness Gate — “Fully Functional”
+- Features: tx/address search, fee recommendations, error/empty states.  
+- Self-host toggle (public vs. private node) with setup docs, including Tor option.  
+- Unit tests for parsers/formatters; UI snapshot tests; resiliency tests.  
+- Fresh setup <30 minutes (excluding Xcode install).  
+
+**Artifacts:** `docs/OPERATIONS.md`, test coverage summary, updated captures.
+
+---
+
+### 4. Polish Gate — “VP-Ready”
+- VP deck: `docs/DESIGN_REVIEW.pdf` with narrative, rationale, screens, motion refs.  
+- Signed archive/TestFlight-ready `.ipa` (or unsigned archive + signing steps).  
+- First-run UX, hints/tooltips, iconography, accessibility basics.  
+- PRs squash-merged, conventional commits, CI green, screenshots in PRs.  
+
+**Artifacts:** final deck, release notes, demo capture (≤60s).
+
+---
+
+## Deliverables
+- PRs into `main`, CI green.  
+- `/app-visionos` Xcode project; `/backend` Dockerized mempool; `/docs` filled out.  
+- Docs required:  
+  - `ARCHITECTURE.md` — data flow, scene graph, threading, error handling.  
+  - `DECISIONS.md` — repo/restart, rendering choices, perf tradeoffs.  
+  - `DESIGN_TOKENS.md` — type scale, color, motion rules.  
+  - `OPERATIONS.md` — run against public/self-host node; Tor config.  
+  - `DESIGN_REVIEW.pdf` — VP-ready deck.  
+  - `ISSUE_LOG.md` + `WEEKLY_REPORT.md`.
+
+---
+
+## Working Rules
+- Full autonomy: restructure or restart for best results.  
+- No interim code dumps; only present when a gate is passed.  
+- If a gate isn’t passed, iterate until it is — don’t advance early.  
+- Keep `ISSUE_LOG.md` and `WEEKLY_REPORT.md` up to date.  
+
+---
+
+## Definition of Done
+- All four gates passed.  
+- Repo contains PRs, docs, build artifacts, and VP deck.  
+- App connects to mempool, renders immersive 3D UX, and feels “senior-level polished.”  
+- AGPL-3.0 license compliance maintained.
+
+---
+
+## Repo & CI Structure

backend/.env.example

@@ -0,0 +1,67 @@
+# Mempool Backend Environment Configuration
+# Copy this file to .env and customize for your setup
+
+# =============================================================================
+# DEPLOYMENT MODE
+# =============================================================================
+# Choose your deployment mode:
+# - "public": Use public mempool.space API (no local backend needed)
+# - "self-hosted": Run your own mempool backend with Bitcoin node
+DEPLOYMENT_MODE=self-hosted
+
+# =============================================================================
+# BITCOIN NODE CONFIGURATION (for self-hosted mode)
+# =============================================================================
+# Bitcoin Core RPC settings
+BITCOIN_RPC_HOST=127.0.0.1
+BITCOIN_RPC_PORT=8332
+BITCOIN_RPC_USER=mempool
+BITCOIN_RPC_PASSWORD=your_rpc_password_here
+
+# Network (mainnet, testnet, signet, regtest)
+NETWORK=mainnet
+
+# =============================================================================
+# ELECTRUM SERVER CONFIGURATION (alternative to Bitcoin Core RPC)
+# =============================================================================
+ELECTRUM_HOST=127.0.0.1
+ELECTRUM_PORT=50002
+ELECTRUM_TLS=true
+
+# =============================================================================
+# DATABASE CONFIGURATION
+# =============================================================================
+DATABASE_PASSWORD=secure_db_password_here
+DATABASE_ROOT_PASSWORD=secure_root_password_here
+
+# =============================================================================
+# SERVICE PORTS
+# =============================================================================
+# Backend API port (VisionOS app will connect to this)
+BACKEND_PORT=8999
+
+# Frontend web interface port (optional)
+FRONTEND_PORT=8080
+
+# =============================================================================
+# TOR CONFIGURATION (optional - for privacy)
+# =============================================================================
+# Enable Tor proxy for enhanced privacy
+TOR_ENABLED=false
+TOR_HOST=127.0.0.1
+TOR_PORT=9050
+TOR_SOCKS_PORT=9050
+TOR_CONTROL_PORT=9051
+
+# =============================================================================
+# LOGGING AND DEBUGGING
+# =============================================================================
+LOG_LEVEL=info
+
+# =============================================================================
+# UMBREL/START9/RASPIBLITZ INTEGRATION
+# =============================================================================
+# If running on a Bitcoin node distribution, these may be auto-configured:
+# UMBREL_ROOT=/umbrel
+# START9_ROOT=/embassy
+# RASPIBLITZ_ROOT=/mnt/hdd/mynode