Diagrams

Big-ACL provides several diagram types to help you visualize your authorization model and understand relationships between entities, principals, resources, and actions.

Available Diagram Types

Diagram	Purpose	Access
Entity Diagram	Visualize your data model with entity relationships	Entities > Diagram view
Cedar Schema Diagram	Visualize the authorization model (principals, resources, actions)	Diagrams > Cedar
Context Canvas	Interactive diagram for mapping business relationships	Diagrams > Canvas

---

Entity Diagram

The Entity Diagram provides a visual representation of your complete data model.

What It Shows

• All entity types defined in your system
• Entity attributes/fields with their names and types
• Primary keys (highlighted with a key icon)
• Relationships between entities with cardinality labels
• Permissions associated with each entity

Accessing the Diagram

1. Navigate to Entities
2. Click the Diagram toggle button (schema icon)

Alternatively, access it from Diagrams > Schema.

Node Display

Each entity is represented as a card containing:

Section	Content
Header	Entity name
Fields	List of properties with type badges
Primary Key	Marked with a key icon, displayed first
Permissions	Purple badges showing available actions

Field Type Colors

Color	Type
Green	String
Blue	Numeric (number, integer, long)
Orange	Boolean
Purple	Date / DateTime
Gray	Entity reference

Relationships

• Arrows connect entities that have relationships
• Labels on arrows indicate the relationship name or cardinality
• Supports one-to-many and many-to-many relationships

---

Cedar Schema Diagram

The Cedar Schema Diagram visualizes your authorization structure based on the Cedar policy language model.

What It Shows

• Principals (blue): Entities that can perform actions (subjects/actors)
• Resources (orange): Entities that can be accessed
• Actions: Operations that principals can perform on resources
• Arrows showing which principals can act on which resources

Accessing the Diagram

Navigate to Diagrams > Cedar.

Node Types

Node Color	Role	Description
Light blue	Principal	Who can perform actions (e.g., User, Admin)
Light orange	Resource	What can be accessed (e.g., Document, Project)
Light gray	Both	Entity used as both principal and resource

Node Content

Each node displays:

• Entity name in the header
• Attributes with their types in the middle section
• Actions (for resources) as gray badges at the bottom

Understanding Arrows

Arrows represent authorization relationships:

• Source: Principal entity (who)
• Target: Resource entity (what)
• Label: Action name(s) that can be performed

Example: An arrow from User to Document labeled read, write means users can read and write documents.

Legend

A legend is displayed at the bottom-left corner:

• Blue square = Principal (Subject)
• Orange square = Resource
• Arrow = Action relationship

---

Context Canvas

The Context Canvas is an interactive diagram for mapping people, applications, data, and organizational relationships.

What It Shows

• Business actors and their roles
• Applications in your ecosystem
• Data assets
• Organizational structures
• Semantic relationships between all these elements

Accessing the Canvas

Navigate to Diagrams > Canvas.

Entity Types

Type	Color	Icon	Description
Profile/Role	Blue	Person	Users, roles, or personas
Data	Green	Database	Data assets or datasets
Application	Purple	App	Software applications
Organization	Orange	Building	Organizational units

Adding Entities

1. Click the corresponding button in the left sidebar:
   • Profile/Role for people or roles
   • Data for data assets
   • Application for applications
   • Organization for organizational units
2. A new node appears on the canvas
3. Drag it to the desired position

Editing Entities

1. Click on a node to select it
2. The properties panel appears on the right sidebar
3. Edit the Name field
4. For Data nodes: toggle available actions (Read, Update, Validate, Delete)
5. Changes are saved automatically

Creating Connections

1. Drag from one node’s connection handle to another node
2. A popup appears with relationship type options
3. Select the appropriate relationship
4. The connection is created and saved automatically

Relationship Types

Relationship options are context-aware based on the connected entity types:

Connection	Example Relationships
Application → Data	Reads, Creates, Updates, Deletes, Exports, Imports
Person → Organization	Belongs to, Manages, Leads, Reports to
Person → Application	Uses, Administers, Supports
Application → Application	Integrates with, Calls, Depends on

Deleting Elements

1. Click on a node or edge to select it
2. Press the Delete key
3. The element is removed and changes are saved automatically

Persistence

• All changes are automatically saved to browser storage
• Diagram state persists across sessions
• Data is stored per tenant

---

Navigation Controls

All diagrams share common navigation controls powered by ReactFlow.

Toolbar Buttons

Button	Action
+	Zoom in
−	Zoom out
Fit	Fit all nodes in view with padding
Lock	Toggle interaction lock

Mouse Controls

Action	Result
Scroll wheel	Zoom in/out
Click + drag background	Pan the viewport
Click node	Select node (Context Canvas shows properties)

Mini-Map

• Located in the bottom-right corner
• Shows a miniature overview of the entire diagram
• Drag the viewport indicator to navigate
• Useful for large diagrams with many entities

---

Layout

Automatic Layout (Entity & Cedar Diagrams)

Both the Entity Diagram and Cedar Schema Diagram use automatic layout:

• Direction: Left-to-right (LR)
• Algorithm: Dagre (directed graph layout)
• Node spacing: Automatically calculated to avoid overlaps
• Entities are positioned based on their relationships

Manual Layout (Context Canvas)

The Context Canvas uses manual positioning:

• Drag nodes to position them
• Positions are saved automatically
• New nodes appear in a grid pattern

---

Best Practices

Reading the Entity Diagram

1. Start with your main entities (usually principals like User)
2. Follow arrows to see what resources they relate to
3. Check field types to understand data structure
4. Look for primary keys to identify unique identifiers
5. Review permissions to see available actions

Reading the Cedar Schema Diagram

1. Identify your principals (blue nodes) - these are your actors
2. Identify your resources (orange nodes) - these are your protected assets
3. Follow arrows to understand “who can do what to what”
4. Read action labels to see specific permissions
5. Use this view to validate your authorization model

Using the Context Canvas

1. Start by adding your main business actors (people/roles)
2. Add the applications they interact with
3. Add the data assets managed by those applications
4. Connect elements with meaningful relationships
5. Use the canvas to document and communicate your architecture