Execution Plan: BluGuide OS Architecture¶
Goal Description¶
Transition from conceptual vision to execution by defining the canonical capability matrix, formalizing the subsystem audits, and outlining the vertical slice implementation for the Operating System for Outdoor Intelligence.
Phase 1: Capability Matrix¶
The following matrix defines the canonical capability inventory. Every capability gets exactly one owner. Nothing gets built unless it appears here.
| Capability | Upstream Owner | Bluefly Owner | Status |
|---|---|---|---|
| Identity | Keycloak / OpenID Connect | — | Adopt |
| Authorization | AuthZEN + OPA/Cedar | Policy Pack | Extend |
| Trust Federation | OpenID Federation | Contract Pack | Extend |
| Security Signals | Shared Signals (CAEP/RISC) | Context Engine | Extend |
| Offline Sync | PowerSync | — | ✅ Adopt (ADR) |
| Search | Orama | Knowledge Pack | Extend |
| Vector Search | Qdrant | Knowledge Pack | Extend |
| Mapping | MapLibre | — | Adopt |
| Vector Tiles | PMTiles | — | Adopt |
| Geospatial Analysis | Turf.js | Spatial Pack | Extend |
| Weather | Open-Meteo | Weather Pack | Extend |
| Marine Sensors | Signal K | Boat Pack | Extend |
| Voice | LiveKit | Context Engine | Extend |
| AI Models | OpenAI/Anthropic/Ollama | Context Engine | Extend |
| Notifications | Native OS | Context Engine | Extend |
Phase 2: Capability Audits (In Progress)¶
Before implementation, we will conduct formal audits of the foundational technologies. Each audit will follow this strict template to ensure direct comparability:
Capability Audit Template¶
- Problem Owned: Exactly what problem does this project solve?
- Upstream Ownership: What responsibilities does it own completely?
- Bluefly Ownership: What domain-specific responsibilities remain?
- Code Elimination: What existing Bluefly code can be removed?
- Integration Complexity: Low / Medium / High
- Operational Risk: Low / Medium / High
- Community Health: Activity, Release cadence, Governance, License, Adoption
- Decision: Adopt / Extend / Wrap / Reject
- Evidence: Links, benchmarks, prototype results, compatibility notes
Audit Priority List: 1. Offline Sync: ElectricSQL vs. PowerSync (requires minimal prototype of offline edits & conflicts) 2. Mapping: OpenMobileMaps vs. MapLibre vs. PMTiles integration 3. Knowledge: Orama vs. Qdrant architecture split 4. Voice: LiveKit integration 5. Marine: Signal K data ingestion
Phase 3: World Model Design¶
Define the core entity relationships and schemas (e.g., using TypeScript/Zod) that all capabilities consume and enrich:
- Location, WaterBody, River, Lake
- Species, Catch, Trip, Waypoint
- Boat, Sensor, WeatherObservation, RiverGauge, Forecast
- Regulation, StockingEvent, Photo, SonarRecording
- User, Device, KnowledgeArticle
Phase 3.5: Event Model¶
Define the canonical events before implementing reasoning. The Context Engine reacts to events rather than polling state.
Examples: LocationChanged, CatchLogged, RiverLevelChanged, WeatherUpdated, SensorReadingReceived, TripStarted, TripEnded, RecommendationGenerated.
Phase 4 & 5: Context Engine and Projections¶
- Context Engine: Build the reasoning layer that evaluates Knowledge, Live Signals, Personal History, Weather, Time, and Device State to output recommendations and alerts.
- Projection Layer: Implement the UI purely as projections (Map, Voice, Watch, Widgets) with zero business logic.
Phase 6 & 7: Pack Architecture and Vertical Slice¶
- Assemble capabilities into standalone Packs (Weather, Navigation, Species, etc.).
- Deliver the First Working Vertical Slice: A complete offline-capable workflow demonstrating map load, GPS update, weather overlay, Context Engine voice prompt, catch logging, and background NAS sync.