Browser Analytics

Zynnode analytics currently uses browser-side event collection as its analytics baseline. This page explains the current architecture, why Zynnode is using a browser-first model, how it works under the hood, and what is supported today.

This page is intended for:

• technical users
• founders
• backend engineers
• frontend engineers
• docs readers who want to understand the system, not just the UI

Executive Summary

Zynnode analytics currently uses browser-side event collection as its analytics baseline.

That means:

• analytics is designed for browser-facing web applications
• analytics is provider-agnostic
• analytics works whether traffic reaches the app through:
  • a Zynnode subdomain
  • a custom domain
  • a provider-native URL
  • a direct origin URL

This is intentional.

Zynnode is not using ingress-only analytics as its primary strategy yet, because ingress attribution would miss traffic that bypasses Zynnode-managed routing.

Why Browser Analytics First

Browser analytics is the correct baseline for Zynnode right now because it:

• works across AWS, Google Cloud, Azure, and Cloudflare
• does not require Zynnode to own request routing
• does not depend on provider-native logging exports
• does not require a wildcard ingress architecture first
• captures the traffic most users expect from analytics

Examples of what browser analytics is good for:

• page views
• unique visitors
• top pages
• referrers
• browsers
• countries
• traffic trends

What Browser Analytics Is Not

Browser analytics is not:

• backend request observability
• infrastructure observability
• CPU metrics
• memory metrics
• server traces
• function logs
• API-only traffic visibility

Those belong to a separate observability layer.

Why Not Rely Only on Provider Logs or Proxy Ingress

There are two reasons.

1. Provider logs are inconsistent across deployment targets

Zynnode supports multiple deployment targets:

• EC2
• ECS
• Cloud Run
• Compute Engine
• App Engine
• Azure VM
• S3 static hosting
• Cloudflare Pages / Workers

Each of these has a different runtime model and different logging and metrics surfaces.

Trying to make raw request logging the primary analytics foundation would create inconsistent behavior across providers.

2. Ingress-only analytics misses direct-origin traffic

If a user visits:

• a Cloud Run native URL
• an EC2 IP
• a provider-assigned endpoint
• a direct custom domain that bypasses Zynnode routing

then Zynnode edge ingress cannot see that request.

Browser analytics still can.

That is why browser analytics is the correct baseline even if Zynnode later adds ingress-based analytics or richer observability.

Current Architecture

Zynnode currently separates these concepts:

1. Analytics

Traffic analytics for browser-facing apps.

Current collection method:

• browser event collection

2. Analytics diagnostics

Technical visibility into whether analytics is provisioned and whether the backend is receiving events.

Examples:

• auto-configured vs manual setup required
• last ingest time
• latest error
• accepted and rejected event counters

3. Project health

Deployment reachability and latency checks.

Examples:

• is the deployment reachable
• response latency
• deployment health state

This is intentionally separate from analytics.

How Browser Analytics Works in Zynnode

At a high level:

1. a project is deployed or redeployed
2. backend decides whether browser analytics can be configured automatically for that deployment
3. if safe and supported, backend injects the analytics client into the deployable HTML output
4. the deployed site sends browser page-view events to the analytics ingest endpoint
5. backend validates and stores the events
6. analytics endpoints aggregate and return the data

Safe Automatic Provisioning Model

Zynnode only auto-configures browser analytics when it can do so safely by modifying deployable output artifacts that are clearly browser-facing HTML.

Today, that means:

• static S3 deployments with index.html
• standard Cloudflare Pages static deployments with index.html

If that HTML entrypoint is not available, Zynnode does not silently pretend analytics is installed.

Instead, it records:

• browser analytics is still the supported model
• automatic setup is not available yet for that deployment path

This is important for correctness and user trust.

Deployment Provisioning States

Each project now exposes analytics provisioning metadata:

• analytics_mode
• analytics_status
• analytics_message
• analytics_provisioned_at

analytics_mode

Current value:

• BROWSER

analytics_status

Current values:

• PENDING
  • no deployment decision has been recorded yet
• AUTO_CONFIGURED
  • browser analytics was automatically provisioned
• MANUAL_SETUP_REQUIRED
  • browser analytics is still the supported model, but Zynnode cannot auto-configure this deployment path yet
• ERROR
  • automatic browser analytics setup was attempted and failed

This makes the current state explicit instead of leaving frontend or users to guess.

What Happens During Deployment

Static S3 Deploys

Zynnode:

• builds the site
• finds index.html
• injects the analytics client before upload
• uploads the modified static output
• marks analytics as AUTO_CONFIGURED

Static Cloudflare Pages Deploys

Zynnode:

• builds the site
• resolves the deployable output directory
• attempts to inject the analytics client into index.html
• deploys that output
• marks analytics accordingly

Runtime Deployments

For deployment targets like:

• Cloud Run
• App Engine
• Compute Engine
• EC2
• ECS
• Azure VM
• Cloudflare Workers / OpenNext runtime

Zynnode currently does not auto-configure browser analytics yet.

Instead it marks:

• analytics_mode = BROWSER
• analytics_status = MANUAL_SETUP_REQUIRED

This is deliberate.

It is better to tell the truth than to silently ship brittle or invasive instrumentation.

Analytics Ingest Model

The analytics ingest endpoint is:

POST /api/v1/analytics/ingest

It accepts batched browser events and validates them with a project-scoped token.

Current ingestion behavior:

• request contains:
  • project_id
  • path
  • referrer
  • user_agent
  • session_id
  • event_type
  • ts
• request includes X-Project-Token
• backend validates the token against the project secret
• backend normalizes the event and stores it

The analytics backend also records diagnostics metadata such as:

• last ingest time
• last success
• last error
• source
• received, accepted, and rejected counters

Privacy Model

Zynnode does not store raw IP addresses in the analytics event model.

Instead:

• IP-like identity is hashed with a rotating salt
• session identity is browser-side and anonymous

This supports basic visitor analytics while keeping the model more privacy-conscious than raw IP storage.

What Works Across Providers

Browser analytics works across providers when the deployed application is browser-facing.

This includes user-facing apps deployed to:

• EC2
• ECS
• Cloud Run
• Compute Engine
• App Engine
• Azure VM
• S3
• Cloudflare Pages / Workers frontends

The important qualifier is:

browser analytics works for browser-facing applications, not backend-only services.

What Does Not Work Yet Automatically

Automatic provisioning does not yet work for every deployment target.

Current gaps are primarily runtime-heavy deployments where Zynnode does not safely own a static HTML entrypoint during deploy time.

That includes:

• container and server runtimes
• VM-served apps
• SSR runtimes without safe static artifact mutation

This is why provisioning status exists.

Why Zynnode Is Not Using Proxy Ingress as the Primary Analytics Foundation Yet

Long term, a platform-controlled wildcard ingress layer could support richer attribution.

But making that the foundation now would introduce major platform requirements:

• wildcard DNS
• wildcard TLS
• highly reliable subdomain routing
• proxy availability guarantees
• request-path ownership across all projects

It would also still miss traffic that bypasses Zynnode-managed routing.

That is why browser analytics is the better baseline now.

Relationship to Observability

Analytics and observability are different products.

Analytics

Answers:

• who visited
• which pages were viewed
• where traffic came from

Observability

Answers:

• is the deployment healthy
• how fast is it responding
• is CPU or memory high
• are requests failing
• how is the runtime behaving

Today, Zynnode's project health endpoint is the first step for observability:

GET /api/v1/projects/:id/health

That endpoint is intentionally separate from analytics.

Current Limitations

Zynnode browser analytics currently does not provide:

• backend and API traffic analytics
• raw server request observability
• runtime CPU and memory metrics
• provider-native traces
• full ingress attribution

Those are future observability and platform capabilities, not part of the browser analytics baseline.

Recommended User-Facing Explanation

If you need concise product wording:

Zynnode Analytics currently uses browser-side event collection for web applications. This gives consistent traffic analytics across deployment providers and domains. Advanced runtime observability and deeper provider-native telemetry are separate capabilities that will expand over time.

Recommended Frontend Interpretation

Frontend should use:

• project analytics fields for provisioning truth
• analytics diagnostics endpoint for technical state
• project health endpoint for reachability and latency

Frontend should not:

• fake CPU values
• imply runtime observability from browser analytics
• assume automatic setup is available for every deployment target today

Future Direction

The likely long-term architecture is:

1. browser analytics remains the universal baseline
2. project health remains separate
3. richer provider-native observability is added per cloud and provider
4. ingress-based attribution may be added later when Zynnode has a reliable wildcard routing layer

That sequencing keeps the system honest and scalable.