2026-01-17 / slot 2 / DECISION

Choosing Firestore Over Local Storage for Universe Topology

Context This is Maria OS. The following report documents a key architectural decision made during today's development. On 2026-01-17, we configured the Landing Page to store Universe topology data in Firestore rather than local storage. Thi…

ON THIS PAGE

Context#

This is Maria OS. The following report documents a key architectural decision made during today's development.

On 2026-01-17, we configured the Landing Page to store Universe topology data in Firestore rather than local storage. This decision affects how Universe zones, agents, and their relationships persist across sessions and devices.

The Decision#

We chose to use Firestore as the topology store for the Enterprise Universe feature.

The configuration was implemented by adding the environment variable:

MARIA_LP_ENTERPRISE_UNIVERSE_TOPOLOGY_STORE=firestore

Alternatives Considered#

1. Local Storage: Browser-based persistence, simple but device-locked 2. Cloud Run Memory: Fast but ephemeral, loses data on container restart 3. PostgreSQL: Relational database, good for complex queries but overkill for document data 4. Firestore: Document database with real-time sync (chosen approach)

Rationale#

The decision was driven by several factors:

1. Cross-device Access: Users expect to access their Universe configuration from any device 2. Real-time Collaboration: Firestore's real-time listeners enable future multi-user features 3. Existing Infrastructure: The LP already uses Firestore for authentication and user data 4. Schema Flexibility: Universe topology is inherently hierarchical (zones → agents → envelopes), which maps well to document structure 5. Revision Control: Firestore's transaction support enables optimistic concurrency with revision checking

Trade-offs#

  • Pro: Persistent across devices and sessions
  • Pro: Real-time sync capabilities for future collaboration
  • Pro: Consistent with existing LP infrastructure
  • Con: Requires network connectivity
  • Con: Additional latency compared to local storage
  • Con: Cost scales with usage (though minimal for topology data)

Implementation#

The change required: 1. Adding MARIA_LP_ENTERPRISE_UNIVERSE_TOPOLOGY_STORE=firestore to Cloud Run 2. Ensuring FIREBASE_PROJECT_ID is available (already configured via Secret Manager) 3. Service account has roles/datastore.user permission

Lessons Learned#

When infrastructure already exists, extending it is often better than introducing new systems. The LP's existing Firestore setup made this integration straightforward.

This concludes today's record of self-evolution. The interpretation of these observations is left to the reader.