Documentation

System Architecture

Interaction Clients

• User-facing and headless clients that interact with Tabmark data.
• Leverage Tabmark SDKs to interact with the data layer
• Responsibilities include:
  • Initiating page extraction and transformation flows.
  • Displaying and editing Tabmarks.
  • Triggering sync and export actions via SDK or API calls.
• UI only, no business logic.

Tabmark SDKs

• Serve as the bridge between clients and well-structured Tabmark APIs.
• Contains the core logic for:
  • Pulling raw data from the interaction client (scraping, etc.)
  • Constructing Tabmarks from the raw data.
• Interacts with the data layer via Tabmark APIs.

Tabmark APIs

• Expose authenticated, schema-consistent operations for:
  • Managing Tabmarks (CRUD).
  • Cloud sync and storage.
  • User and device metadata.
  • Export triggers and integration routing.
• Centered around the Tabmark type — a structured, extensible schema representing any saved web resource.
• Backed by a centralized data store designed for:
  • Cross-device availability.
  • Eventual consistency and conflict resolution.
  • Queryability and access control.
• APIs are defined contract-first, driven by core TypeScript types in packages/core, minimizing client/server drift.

Integration Layer

• Hosts pluggable adapters for interacting with external systems (e.g., Notion, Google Drive, GitHub).
• Enables support for things like:
  • Transforming Tabmarks (Tabmark → target schema).
  • Lifecycle hooks.
  • Authentication/session management.
  • API orchestration for writes/updates.
• Executed by the Integration Runtime — an orchestration layer designed for:
  • Dependency-injected integration code.
  • Deterministic, auditable side-effect execution.
  • Fault tolerance and retry strategies.

Design Philosophy & Future Directions

• Modularity: Each system component is isolated and replaceable, supporting rapid iteration and future platform targets (mobile, web, cloud).
• Extensibility: The data model and extraction logic are designed for easy extension to new page types, output formats, and integrations.
• User-Centric: Focus on clean, readable, and offline-accessible tabmarks, with robust parsing and formatting.
• Integration-Ready: The architecture anticipates cloud sync, mobile sharing, and third-party integrations, ensuring that tabmarks can flow seamlessly between devices and apps.
• Type Safety: TypeScript is used throughout for reliability and maintainability.

Data Model & Extensibility

At the heart of Tabmark is the canonical Tabmark data type — a structured, extensible representation of a saved web page. The system is designed with extensibility in mind; to create well-structured (and infinitly flexible) Tabmarks from anything on the web. This paves the way for advanced features like:

• Auto-discovery of page type (e.g., recipe, article, product)
• Arbitrary metadata and rendering logic anything on the internet can be a "page" with its own custom schema, parsing, transformation, rendering logic, integrations, etc.

Storage & Synchronization

• Current State: Uses local storage for persistence
• Future State: Persist the storage to a centralized location, enabling cross-device sync and integration with external services.

Future Plans

• Cloud sync and cross-device support
• Mobile and web clients
• Advanced extraction for more content types (recipes, articles, products, etc.)
• Third-party integrations (read-it-later, note-taking, etc.)
• Flexible output formats (Markdown, HTML, JSON)
• AI Integration to ask questions about your content
• Live updates Synchronize with the latest changes made since the Tabmark was created