Where GraphJSON fits in your data architecture

GraphJSON is a fast analytical destination for timestamped JSON events. Send facts over HTTP, query them with ClickHouse SQL, and turn the results into visualizations, dashboards, alerts, exports, and embeds.

It is most useful between operational producers and the people or product surfaces that need answers:

applications, jobs, and providers
              ↓
      timestamped JSON facts
              ↓
           GraphJSON
       ├── exploration
       ├── saved SQL
       ├── dashboards
       ├── supported alerts
       ├── Data API
       └── embeds

GraphJSON should complement—not silently replace—the systems responsible for transactions, durable recovery, specialized telemetry, or governed enterprise-wide data processing.

Start with the workload#

GraphJSON is a strong fit when you need to:

• instrument a product without adopting a vendor-specific SDK
• inspect arbitrary structured JSON quickly
• analyze product, account, integration, billing, or workflow events
• use SQL for funnels, cohorts, retention, paths, and operational questions
• build internal dashboards from the same event stream
• embed scoped analytics in a customer-facing product
• create supported threshold alerts from collection visualizations
• combine provider events with application-owned facts

It is not enough that the data is JSON. The retention, access model, authority, volume, and recovery requirement must also fit.

Assign one authority to each fact#

An analytics result can inform a decision without becoming the operational authority. Do not grant access, settle money, ship an order, or enforce a quota solely from a GraphJSON query.

GraphJSON and an application database#

An application database is optimized for:

• transactional writes
• current mutable state
• integrity constraints
• serving user requests
• authorization checks
• record-level updates and deletion

GraphJSON is optimized for:

• append-oriented time-series facts
• analytical scans and aggregations
• historical behavior
• flexible JSON inspection
• dashboards and embedded reporting

Recommended boundary:

business transaction commits
          ↓
transactional outbox
          ↓
analytical event delivered to GraphJSON

The application reads current state from its database. Analysts and reporting surfaces read historical behavior from GraphJSON.

Use Database change data capture when the database is the source of changes.

GraphJSON and a data warehouse#

A data warehouse or lakehouse is usually the better authority for:

• large cross-company joins across many governed sources
• long-term raw history and rebuilds
• transformation dependency graphs
• scheduled tables and semantic models
• organization-wide catalog, lineage, and access policy
• finance or regulatory reporting pipelines
• data science training sets

GraphJSON is often the shorter path for a product team that already has well-defined JSON facts and needs interactive answers, dashboards, or embedded analytics.

They can work together:

durable source
  ├── GraphJSON → operational and product-facing analytics
  └── warehouse → broad modeling, governance, and long-term history

If a warehouse calculates a stable metric needed in GraphJSON, publish a versioned result through Derived events and scheduled rollups. Do not create an undocumented circular flow in which GraphJSON feeds a warehouse job that rewrites the same metric back into its source collection.

GraphJSON and observability systems#

GraphJSON can analyze compact operational facts:

• request outcomes
• job and queue lifecycle
• deployment versions
• provider latency and errors
• SLO window measurements
• webhook delivery operations

Use a specialized observability system for:

• distributed trace waterfalls
• high-volume raw logs
• infrastructure metrics and host telemetry
• continuous profiles
• incident paging, acknowledgment, and escalation
• tightly coupled service dependency diagnostics

A useful division:

telemetry backend → immediate diagnosis and paging
GraphJSON         → business context, trends, dashboards, and shared analysis

Do not make GraphJSON the only monitor for the pipeline that sends data to GraphJSON. Preserve an independent signal for delivery failure.

See Structured application logs and SLOs, error budgets, and alerts.

GraphJSON and product analytics suites#

GraphJSON provides flexible event ingestion, SQL, visualizations, dashboards, alerts, exports, and embedding without requiring a specialized client SDK.

Your application remains responsible for definitions that some product analytics suites infer or manage automatically:

• sessions
• identity merging
• user profiles
• attribution
• bot classification
• experiment assignment
• feature-flag evaluation
• event governance workflows

That explicitness is valuable when the definitions are product-specific, but it requires ownership. Use the corresponding guides rather than assuming a hidden default.

GraphJSON and customer-facing BI#

GraphJSON can power:

• shared read-only dashboards
• iframe visualizations
• password-protected shared assets
• server-generated personalized embeds
• a native frontend backed by the Data API

The application still owns:

• authentication and tenant authorization
• report entitlements
• filter derivation
• per-tenant cache boundaries
• export policy
• accessibility and fallback behavior
• customer-visible support commitments

Never place the workspace API key in browser or mobile code. Use Production embedded analytics before launching a customer-facing report.

Decide by requirement#

Hybrid architecture is normal. The goal is not to minimize the number of systems; it is to keep each promise in a system designed to uphold it.

Reference architecture: product analytics#

browser and mobile
      ↓ first-party collection endpoint
application services
      ↓ durable outbox
provider webhooks
      ↓ verified adapter
GraphJSON product_events and provider collections
      ↓
saved SQL → dashboards, embeds, and exports

Keep identity, consent, event time, and schema versions in the event contract. Use separate workspaces or collections for production and test data according to the required isolation.

Reference architecture: operational workflow#

queue or workflow engine
  ├── authoritative job state
  ├── monitoring backend
  └── compact lifecycle events → GraphJSON
                                  ↓
                       trends and investigation dashboard

GraphJSON explains which job types, releases, accounts, or dependencies are affected. The workflow engine remains responsible for retries and current job state.

Reference architecture: governed dual destination#

transactional outbox or durable event log
      ├── archive consumer → immutable governed storage
      ├── warehouse consumer → broad modeling
      └── GraphJSON consumer → interactive and embedded analytics

Each consumer has its own checkpoint, retry state, and reconciliation. One destination’s success does not prove another is complete.

Use Durable raw archive and dual-write for this pattern.

Recognize when the boundary has changed#

Revisit the architecture when:

• consumers require history beyond configured retention
• source data cannot be replayed after a mapping defect
• large joins dominate every query
• row-level authorization cannot be safely enforced at the reporting boundary
• manual transformations have become a dependency graph
• a dashboard is being treated as an accounting or compliance report
• alert delivery requires acknowledgment, escalation, or formal on-call policy
• an event stream contains raw payloads that belong in a more restricted store
• export and deletion requirements exceed current self-service capabilities

Do not hide these requirements inside increasingly complex SQL. Move the responsibility deliberately and preserve a stable analytical interface where useful.

Architecture review checklist#

• Every critical fact has one named authority.
• GraphJSON receives only fields needed for approved analytical uses.
• Operational writes never depend on an analytical query succeeding.
• Recovery requirements have a source outside process memory.
• Retention matches the longest decision window.
• Customer-facing reports enforce authorization on the server.
• Critical delivery and paging have an independent failure domain.
• Cross-system metrics use explicit completeness watermarks.
• Unsupported capabilities are not implied by a dashboard workflow.
• The boundary is reviewed when scale, sensitivity, or consumer promises change.