Integration Points¶

The web platform is an integration hub: it brokers identity, authorization, delivery, analytics, and realtime updates between the browser and a range of external systems. This page enumerates every external dependency and the environment variables that wire it up.

flowchart TB
    subgraph Platform["Grepsr Web Platform (Next.js)"]
        FE[Browser]
        API[app/api/*]
    end

    FE --> Auth0
    FE --> Flagsmith
    FE --> Amplitude
    FE <--> Socket[Socket.io server]

    API --> Cerbos
    API --> Grpc[gRPC microservices]
    API --> Redis[(Redis)]
    API --> S3[(AWS S3)]
    API --> Dropbox
    API --> Box
    API --> Prom[Prometheus]
    API --> K8s[Kubernetes API]

Identity & Authorization¶

System	Role	Transport	Key env vars
Auth0	Authentication / SSO (OIDC)	`@auth0/nextjs-auth0`	`AUTH0_SECRET`, `AUTH0_BASE_URL`, `AUTH0_ISSUER_BASE_URL`, `AUTH0_CLIENT_ID`, `AUTH0_CLIENT_SECRET`, `AUTH0_AUDIENCE`, `AUTH0_SCOPE`, `AUTH0_SIGNING_SECRET`
Cerbos	Server-side policy authorization	gRPC (prod) / HTTP (stage)	`CERBOS_URL`, `CERBOS_HOST`, `CERBOS_PORT`, `APP_RUNNING_ENV`

See Authentication & Authorization for the full flow.

Backend Microservices (gRPC)¶

The platform's primary integration is with the Grepsr backend microservices over gRPC. The client factory in utils/grpc.ts resolves cluster addresses and applies TLS:

Addressing: {service}.{env}.svc.grepsr.net:443 (ingress) — derived from the environment and the service registry in utils/microservices.ts.
TLS: controlled by CONFIG_SECURE_CONNECTION (createSsl vs createInsecure); test/beta environments target an in-cluster grepsr-app address insecurely.
Message size: raised to 30 MB to accommodate large report payloads.

See Data Flow and the proto catalogue.

Delivery Destinations¶

Dataset delivery integrates with several external storage providers (configured in the Data Delivery module):

Destination	SDK	Key env vars
AWS S3	`@aws-sdk/client-s3`, `s3-request-presigner`	`AMAZON_REGION`, `AMAZON_ACCESS_KEY`, `AMAZON_SECRET_ACCESS_KEY`
Dropbox	`dropbox`	`DROPBOX_CLIENT_ID`, `DROPBOX_CLIENT_SECRET`, `DROPBOX_REDIRECT_URL`
Box	`box-node-sdk`	`BOX_CLIENT_ID`, `BOX_CLIENT_SECRET`, `BOX_REDIRECT_URL`

Long-running uploads

S3 multipart uploads use an extended Axios timeout (up to 24h) configured per-endpoint in apis/index.ts, since large exports can take a long time to stream.

Realtime, Caching & Infrastructure¶

System	Role	Library / location
Socket.io	Realtime crawler-log streaming and activity feeds	`socket.io-client`, `hooks/useLogStream.hook.tsx`
Redis	Caching / session storage	`redis` singleton in `lib/clients/redis.ts` (`REDIS_URL`)
Kubernetes API	Cluster/pod visibility for admin tooling	`@kubernetes/client-node`
Prometheus	Metrics querying	`prometheus-query`

Product Analytics & Feature Flags¶

System	Role	Library
Amplitude	Usage analytics, engagement, session replay	`@amplitude/analytics-browser` (+ engagement, session-replay plugins) via `AnalyticsProvider`
Flagsmith	Feature flags / gradual rollouts	`flagsmith` via `FeatureFlagProvider` (`NEXT_PUBLIC_FLAGSMITH_ENV_ID`); defaults in `utils/defaultFlags.ts`

Usage example — feature gating:

import { useFeature } from "flagsmith/react";

function Panel() {
  const { enabled } = useFeature("new-ui-layout");
  return enabled ? <NewLayout /> : <OldLayout />;
}

Core Application Env Vars¶

Variable	Purpose
`NEXT_PUBLIC_API_URL`	Base URL for browser→server REST calls.
`NEXT_PUBLIC_BASE_URL`	App base URL.
`NEXT_PUBLIC_FLAGSMITH_ENV_ID`	Flagsmith environment id.
`CONFIG_SECURE_CONNECTION`, `CONFIG_SECURE_PATH`	gRPC TLS configuration.
`APP_RUNNING_ENV`	Selects Cerbos transport and environment-specific behaviour.
`FEED_URL`	Data feed endpoint.

Finding the authoritative list

Treat this table as a guide, not gospel — env usage evolves. Search the repo for process.env. to enumerate the variables actually referenced in the current main.