BuzzTrip Infrastructure Layer — High-Level Breakdown

[jacobsamo]

1. Overview of the Infrastructure Rewrite

BuzzTrip’s current architecture needs a foundational rewrite to support extensibility, plugin capabilities, data layers, Mapbox integration, and improved data handling. This new infrastructure layer spans both client and server, aligning data types, schemas, events, search, and map operations into one coherent system.

---

2. Mapbox Integration & API Abstraction

Mapbox Migration

• Transition BuzzTrip to use Mapbox as the primary map provider.
• Implement a “Mapbox Switch” to move existing map functionality to the new system.

API Wrapping Layer

• Create BuzzTrip-native APIs around Mapbox’s features.

• Ensure the ability to swap out Mapbox in the future by keeping abstractions clean.

• Include core APIs such as:

  • buzztrip.search(query)
  • Autocomplete utilities
  • Place details retrieval (buzztrip.getPlaceDetails)

---

3. Data Structures & Extensibility

Core Schema Redesign

• Rebuild internal data structures to be more extensible and future-proof.
• Update schemas to improve usability and integration across client and server.

Zod + Convex Improvements

• Make schemas compatible and flexible between Zod and Convex.
• Enhance type safety and ensure data types can be easily extended.

Custom Metadata Support

• Allow resources (markers, collections, layers, users, etc.) to include:

  • Custom fields
  • Plugin metadata
  • Third-party integrations

---

4. Markers, Places & Map Entities

Extended Marker System

• Keep current marker functionality but expand it with:

  • Custom marker types
  • Additional UI/UX configuration
  • Plugin-driven behaviours and metadata

Place Enhancements

• Extend the concept of “Places” to support:

  • Custom place searching
  • Richer place detail retrieval
  • Integration with external APIs

Collections, Data Layers & Map-Level Entities

• Support for:

  • Collections of markers/places
  • Data layers rendered on the map
  • Server-side and client-side management of layers

---

5. Event System & Map History

Event System Infrastructure

• Implement a system where all major actions emit events, e.g.:

  • Marker created
  • Place updated
  • Layer added

• Allow event tracking across both client and server.

Map History Tracking

• Maintain an audit log of actions, including:

  • Who made a change
  • What was changed
  • When and how it changed

• Ensure the history system is efficient, consistent, and secure.

---

6. Client–Server Synchronisation

End-to-End Event Processing

• Ensure that events generated on the client are mirrored and tracked on the server.
• Maintain synchronised, real-time updates through Convex.

Optimised Updates

• Implement intelligent update flows for:

  • Reduced network overhead
  • Faster UX
  • Minimal re-computation

---

7. Server Infrastructure & Convex Integration

Convex Schema & Component Overhaul

• Update Convex infrastructure to support:

  • New schemas
  • More flexible components
  • Plugin data
  • Additional metadata

Supported Convex Operations

• Fully utilise:

  • Queries
  • Mutations
  • Actions
  • HTTP actions

• Handle webhook-based requests for external integrations.

---

8. Search System & Autocomplete

Unified Search API

• Build a single entry point for search:
  buzztrip.search(query)

Autocomplete Integration

• Provide autocomplete suggestions while typing.

• Tie into:

  • Mapbox search
  • Custom BuzzTrip index
  • External data sources

---

9. Plugin Registry & Extensibility Model

• Start the first version of a plugin system where developers can:

  • Add metadata
  • Extend schemas
  • Modify markers, layers, or places
  • Add custom search handlers

• Provide clear APIs for plugin registration and runtime usage.

---

10. User Schema Enhancements

Expanded User Metadata

• Store additional user information such as:

  • Country of signup
  • Currency (derived from country, e.g. AUD for Australia)
  • Region/language preferences

Use Cases

• Improve user analytics
• Regionalise content or features
• Support future marketplace features

---

11. Analytics & Usage Tracking

• Track map usage metrics such as:

  • When a map is opened
  • What data is interacted with
  • Performance and behaviour analytics

• Store this in Convex and expose it through server APIs.

---

Summary

The rewrite of BuzzTrip’s infrastructure is a deep, full-stack upgrade involving map services, schemas, event systems, user metadata, plugins, and a unified search layer. This backbone will set up BuzzTrip to grow, scale, and support richer features — from custom plugins to external integrations and advanced map capabilities.