Internal boundaries

Not every network edge in SREDSimplify is a stable public API. This page documents the important boundaries and who is expected to call them.

Boundary inventory

Boundary	Route surface	Authentication	Intended caller
Browser -> Next.js BFF	/api/bff/api/v1/*	browser bearer token plus server-side Cloudflare Access injection	frontend browser code
BFF -> Spring Boot	/api/v1/**	forwarded Authorization and Cloudflare service headers	Next.js server route
Spring Boot -> Python worker	/api/v1/task/process and /api/v1/health/*	X-Internal-Token	Java backend only
Stripe -> Spring Boot	/api/v1/billing/stripe/webhook	Stripe-Signature	Stripe webhook delivery

Browser to backend through the BFF

The browser does not call the backend origin directly. It calls the Next.js proxy at:

• /api/bff/api/v1/*

The BFF then:

• reads BACKEND_ORIGIN
• injects CF-Access-Client-Id
• injects CF-Access-Client-Secret
• forwards the upstream request
• strips hop-by-hop headers from the response

Important caveat:

• BFF-generated failures such as 500 Proxy misconfigured and 502 Upstream fetch failed are plain JSON error objects, not backend ApiResponse<T> payloads

Java backend to Python worker

The current internal worker contract is the FastAPI task gateway:

• POST /api/v1/task/process

It is protected with:

• X-Internal-Token

The worker is not a browser-facing API. It expects a task envelope from the Java backend and currently supports these task types:

• PRECHECK
• T661
• LOGBOOK

Operationally important companion endpoints:

• GET /api/v1/health/
• GET /api/v1/health/readiness
• GET /api/v1/health/liveness

The Python worker should be treated as an implementation detail of run execution, file indexing, and public screener requests, not as a directly supported client integration surface.

Stripe to backend webhook boundary

Stripe delivers inbound billing events to:

• POST /api/v1/billing/stripe/webhook

Important behavior:

• the route is hidden from public OpenAPI docs
• it requires the Stripe-Signature header
• the backend verifies the webhook signature before processing
• duplicate events are ignored based on persisted Stripe event IDs

This boundary is public on the network but it is not a browser-client API. It exists only for Stripe event delivery.

Reserved internal namespace

The backend configuration and generated docs reserve /internal/api/v1/** as an internal namespace, but there is no checked-in, browser-consumable controller set under that path today.

For current integration work, the boundaries that matter are:

• BFF proxying to /api/v1/**
• Java-to-Python task execution
• Stripe webhook delivery

Boundary ownership guidance

Use the right docs for the right edge:

• browser and frontend behavior: Frontend API layer
• bearer/JWT rules: Authentication
• Python worker health and failures: Python worker degraded
• Stripe delivery issues: Stripe webhook failures