📘 Control Map Guide

The Control Map is the operational topology canvas in Control Core. It helps teams understand and navigate how subjects, bouncers, active policies, PIPs (data sources), action integrations, and resources connect in the currently selected environment.

📌 What Control Map Shows

Environment-scoped topology: Map data is scoped to the environment selected in the Control Plane header.
Active policy view: The map includes only policies that are activated for the selected environment.
Left-to-right flow: Subject -> Bouncer -> Policy/Policy Group -> PIP/Action Integrations -> Resource.
AI-protected resources: Resources identified as AI/LLM/MCP/Agent-protected are tagged as AI Protected.
Deep-link navigation: Every node can open its related management page.

🛡️ Subject Classification (PBAC Runtime)

Control Map does not render one node per identity at large scale. Instead, it groups runtime principals into Subject Cohorts so the topology stays readable in enterprise traffic conditions.

Supported Subject Cohorts

End Users
AI Agents
Groups / Cohorts
Service Accounts
Workloads / Jobs
Devices / IoT
Partners / Vendors
Privileged Users
API Clients
Services
Anonymous / Unattributed

How subjects are derived

Subject cohorts are derived from runtime bouncer events (ACCESS_GRANTED, ACCESS_DENIED) in audit logs.
Cohort classification uses principal and request context fields (for example: user, resource, event_type, http_method, user_agent, reason).
Control Plane identities such as ccadmin / PAP are excluded from runtime subject cohorts to avoid cross-plane confusion.
Numeric principals are normalized to readable identifiers (for example: subject-id-1) instead of raw 1, 2, 3.

What a Subject Cohort node shows

Identity group type (cohort name)
Unique subject count
Request/allow/deny counts
Example principals
Top routes/resources
Bouncer reference and last-seen timestamp

Selecting a node and clicking Open Related Page deep-links to the relevant target:

Bouncer -> /settings/peps?bouncer_id=...
Resource -> /settings/resources?resource_id=...
Policy -> /policies?policy_id=...
PIP -> /pips?connection=...
Action Integration -> /settings/action-destinations?destination_ref=...
Subject -> /audit?user=...

📌 Canvas Controls

Search: Locate nodes quickly by label, id, or metadata.
Type Filter: Focus on one node type (e.g., only bouncers, only resources).
Zoom: Zoom in/out using controls or mouse wheel.
Reset View: Restore baseline view and filter state.
Recenter: Re-center current zoom level in the viewport.
Full Screen / Exit Full Screen: Expand map canvas for focused analysis.

🛡️ Policy Grouping and See More

When a resource has many active policies:

The map creates a Policy Group node.
The side panel initially shows the first 5 policies.
Use See More (+5) to load additional policies in increments of five.
Use search/type filter to narrow and find specific policies faster.

📌 Licensing Alignment Note

Control Map includes a warning when a single bouncer is linked to multiple resources.

Target deployment model for this MVP is 1 bouncer : 1 resource.
Use this warning to identify and clean up legacy 1:n link patterns.

🛠️ Troubleshooting

Control Map is missing expected nodes

Confirm you are in the expected environment (Sandbox/Production).
Only active policies in that environment are included.
Clear filters and search terms, then click Reset View.
Hard refresh browser cache after frontend updates (Cmd+Shift+R).

Full screen is not entering or exiting

Verify browser allows full screen API for your tab.
Click once on the page and retry the Full Screen button.
Use browser Esc to exit if needed.

Deep link opens generic page instead of specific item

Ensure the URL includes the expected query parameter (bouncer_id, resource_id, policy_id, connection, etc.).
If needed, refresh the destination page and re-open from map.