Chubb - GenAI Knowledge Graph

KnowledgeGraph Visualizer Environment Overview

This page documents the Development and Production environment model for the Ontology Explorer web application, the Choreo API service, and Amazon Neptune integration.

Last updated: June 7, 2026

Application Ontology Explorer and Amazon Neptune Graph Explorer
Hosting Platform WSO2 Choreo Web App and REST Service
Graph Backend Amazon Neptune with SPARQL over IAM SigV4

Purpose

The KnowledgeGraph Visualizer provides a browser-based experience for browsing ontology classes, named individuals, policy concepts, validation output, governance queries, and Neptune-backed graph relationships. The application can load local cached Turtle files and can also query Amazon Neptune through the backend service.

Browser users do not connect directly to Neptune. All Neptune calls go through the Python service, which signs requests with AWS credentials or an IAM role.

Request Flow

  1. User opens the Choreo-hosted web application.
  2. The web application calls the Choreo API gateway at the configured service URL.
  3. The Choreo API gateway authenticates and forwards requests to the Python service.
  4. The Python service initializes a Neptune client from runtime environment variables.
  5. The service signs Neptune HTTP requests with AWS SigV4 and calls the Neptune SPARQL endpoint.
  6. Neptune returns graph data, search results, stats, or export data to the service.
  7. The browser renders ontology tables, graph views, search results, and governance reports.

Architecture Diagram

The application uses the same logical architecture in Development and Production. The main differences are the Choreo environment, web/API URLs, AWS credential model, Neptune endpoint, CORS allowlist, and production-only security restrictions.

Development Architecture Development

Internal User Browser Opens the Choreo non-production web app.
  • Ontology Explorer UI
  • Neptune Graph Explorer UI
  • Governance and validation views
->
Choreo Web App - Dev Static HTML, CSS, and JavaScript hosted by Choreo.
  • API_URL points to dev API
  • No direct Neptune access
  • No AWS credentials in browser
->
Choreo API Gateway - Dev Routes authenticated browser API calls to the service.
  • /genai/knowledgegraph-visualizer/v1.0
  • OAuth/API gateway auth
  • Gateway logs and correlation IDs
->
Python Service - Dev Containerized backend running on port 8000.
  • /api/ontology, /api/load
  • /api/neptune-status, search, stats
  • Reads Choreo service env/secrets
->
Amazon Neptune - Dev dev-neptune-w.chubb.com:8182
  • SPARQL endpoint over HTTPS
  • IAM SigV4 authentication
  • Development graph data
Choreo Dev Configs and Secrets
  • HOST_NAME=0.0.0.0
  • NEPTUNE_* variables
  • Temporary AWS credentials as secrets
  • Dev web app CORS origin
Local Cached Data
  • input/neptune/*.ttl
  • Cached ontology loads can work without Neptune
  • Fetch to Local writes refreshed TTL files
Optional S3 Bulk Load
  • S3_PREFIX for source files
  • IAM_ROLE_ARN for Neptune load jobs
  • Admin-only operation
Operations and Diagnostics
  • Choreo runtime logs
  • /api/health
  • /api/neptune-connection-check
  • Neptune request IDs on failures

Development may use temporary AWS credentials for testing. A 403 AccessDeniedException from Neptune means the service reached Neptune, but the AWS signing identity was rejected.

Production Architecture Production

Approved Business Users Access through the approved production URL.
  • Enterprise identity and access controls
  • Read-only graph exploration by default
  • Admin actions require separate approval
->
Choreo Web App - Prod Static UI with non-secret runtime config.
  • API_URL=<production-service-api-url>
  • No browser-side client secret
  • No browser-side AWS credentials
->
Choreo API Gateway - Prod Authenticated API entry point for all backend calls.
  • Managed auth or OAuth with PKCE
  • Rate limits and quotas
  • Audit-friendly correlation IDs
->
Python Service - Prod Controlled backend boundary for Neptune access.
  • Strict CORS allowlist
  • Read-only default feature flags
  • Admin endpoints disabled or restricted
->
Amazon Neptune - Prod <production-neptune-endpoint>:8182
  • IAM-authenticated SPARQL
  • Least-privilege neptune-db permissions
  • Production knowledge graph data
Identity and Authorization
  • Managed web app authentication or PKCE
  • Role-based backend authorization
  • Separate read and admin access
AWS Identity
  • Prefer IAM role or workload identity
  • No manually pasted session tokens
  • Rotate any temporary emergency secrets
Production Controls
  • NEPTUNE_READ_ONLY=true
  • ENABLE_NEPTUNE_WRITES=false
  • ENABLE_DESTRUCTIVE_ENDPOINTS=false
Monitoring and Audit
  • Choreo gateway and service logs
  • Neptune request IDs
  • Health and status smoke tests
  • Secret rotation history

Production should use a server-side trust boundary: the browser calls Choreo, Choreo calls the service, and only the service signs requests to Neptune.

Environment Summary

Development Active

Item Value
Choreo environment Development
Web app URL https://4853778d-7996-4b2c-a621-a8c018a03696.nonprod-webapps.bt.choreoapps.dev
Service API base URL https://dev.nonprod.bt.choreoapis.dev/genai/knowledgegraph-visualizer/v1.0
Neptune endpoint dev-neptune-w.chubb.com:8182
AWS region us-east-1
Use case Feature testing, integration validation, Neptune connectivity checks, and data exploration.

Development uses non-production Choreo URLs and can be interrupted by temporary AWS credential rotation. The Neptune status badge in the UI is the source of truth for live Neptune connectivity.

Production Planned

Item Value
Choreo environment Production
Web app URL <production-web-app-url>
Service API base URL <production-service-api-url>
Neptune endpoint <production-neptune-endpoint>:8182
AWS region us-east-1, unless a production architecture decision changes it.
Use case Controlled business access to approved ontology and graph exploration workflows.

Production should use managed identity or IAM role federation for AWS access. Browser-side secrets and manually pasted AWS session tokens are not production acceptable.

Runtime Configuration

Web App Component

The web app should only receive non-secret browser configuration.

Variable Development Production Notes
API_URL https://dev.nonprod.bt.choreoapis.dev/genai/knowledgegraph-visualizer/v1.0 <production-service-api-url> Allowed in browser config. This is the only required public runtime URL.
CONSUMER_KEY Use only if required by current Choreo connection model. Avoid exposing in browser if possible. Prefer managed web app authentication or Authorization Code with PKCE for production.
CONSUMER_SECRET Do not expose in committed files. Do not expose in browser. Client secrets are not safe in static browser applications.
CHOREO_API_KEY Do not expose in committed files. Do not expose in browser. Use gateway-managed auth for production instead of browser API keys.

Service Component

Backend environment variables and secrets must be configured on the Choreo Service component.

Variable Development Production Notes
HOST_NAME 0.0.0.0 0.0.0.0 Required so the Python service binds inside the container.
NEPTUNE_ENDPOINT dev-neptune-w.chubb.com <production-neptune-endpoint> Hostname only. Port is configured separately.
NEPTUNE_PORT 8182 8182 Default Neptune HTTPS port.
NEPTUNE_IAM_AUTH true true Required when Neptune IAM authentication is enabled.
NEPTUNE_REGION us-east-1 us-east-1 Used for SigV4 signing.
AWS_DEFAULT_REGION us-east-1 us-east-1 Fallback region used by boto3.
CORS_ALLOW_ORIGINS Development web app origin only. Production web app origin only. Do not use * in production.
AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_SESSION_TOKEN Choreo secrets only, for temporary non-production access. Prefer IAM role or workload identity instead of static secrets. Never place AWS credentials in web app config, source control, wiki pages, screenshots, or logs.

Production Security Controls

Production must not expose Choreo client secrets, API keys, AWS access keys, AWS secret keys, or AWS session tokens to the browser.
Control Area Production Requirement
Browser authentication Use Choreo managed authentication or OAuth Authorization Code with PKCE. Avoid browser-side client secrets.
API gateway Require authentication on the Choreo API. Apply rate limits and quotas appropriate for business use.
Backend authorization Separate read-only users from admin users. Enforce role checks before write, delete, sync, or bulk-load endpoints.
AWS access Use IAM role federation or workload identity. If secrets are temporarily required, store them only as Choreo secrets and rotate them.
Neptune IAM policy Grant least privilege. Read-only workflows should use neptune-db:ReadDataViaQuery. Write workflows require explicit additional actions.
CORS Allow only the production web app origin. Do not allow wildcard origins in production.
SPARQL workbench Restrict to SELECT-only or disable for general users. Admin query access should be separately approved.
Destructive operations Disable drop, delete, bulk load, and sync endpoints unless an admin-only workflow is explicitly approved.
Logging Log request IDs, status codes, endpoint health, and provider metadata. Never log secrets, access tokens, or session tokens.

Recommended Production Feature Flags

APP_ENV=production
NEPTUNE_READ_ONLY=true
ENABLE_NEPTUNE_WRITES=false
ENABLE_DESTRUCTIVE_ENDPOINTS=false
ENABLE_SPARQL_WORKBENCH=false

Operational Checks

Use these checks after each deployment or secret rotation.

Check Expected Result Meaning
GET /api/health HTTP 200 Service is reachable through Choreo.
GET /api/neptune-status configured: true and connected: true Neptune endpoint, network path, IAM auth, and SigV4 signing are working.
GET /api/neptune-stats Triples, classes, individuals, and named graph counts return successfully. Neptune SPARQL SELECT queries are working.
GET /api/neptune-search?q=Policy Search results return without HTTP 403 or 500 errors. Application-level Neptune query flow is working.
If Neptune returns AccessDeniedException with "security token included in the request is invalid", the service is reaching Neptune but AWS credentials or role assumptions are not valid for signing the request.

Deployment Checklist

Development

Production

Reference Links

Owner: GenAI Knowledge Graph Team. Update this page whenever Choreo URLs, Neptune endpoints, authentication patterns, or production feature flags change.