Skip to main content

📋 Permission System Documentation

Overview​

The Venture Orient AOS uses a role-based permission system to control access to documentation. This ensures sensitive information is only accessible to appropriate team members.

How It Works​

1. User Roles​

The system supports five user roles:

RoleLevelAccess
Owner100Full system access, can manage permissions
CEO90Executive access, most documentation
PM70Project manager access, operational docs
Designer50Design-related content and tools
Funnel Builder40Templates and basic tools

2. Permission Storage​

Permissions are stored in two locations:

  • Primary: Cloudflare KV Worker (for production)
  • Fallback: Static /permissions.json file

3. Sidebar Filtering​

The sidebar automatically filters content based on the current user's role:

  • Items the user can access are shown
  • Items the user cannot access are hidden
  • Parent folders remain visible if they contain any accessible items

Setting Your Role​

For Development​

Use the Permission Test Page at /docs/tools/permission-test to:

  • View your current role
  • Switch between roles for testing
  • See which items are visible/hidden

For Production​

Roles are set through the authentication system (Clerk) based on user profiles.

Default Behavior​

If permissions cannot be loaded:

  • All content is shown by default (fail-open approach)
  • This ensures the documentation remains accessible even if the permission system fails
  • Owner role always sees everything regardless of permission configuration

Permission Configuration​

File Structure​

{
  "content": {
    "folder-name": {
      "allowedRoles": ["owner", "ceo", "pm"]
    },
    "folder/subfolder": {
      "allowedRoles": ["owner"]
    }
  }
}

Inheritance​

  • Permissions are inherited from parent folders
  • More specific paths override parent permissions
  • Individual documents can have custom permissions

Troubleshooting​

Nothing Shows in Sidebar​

  • Check console for [SIDEBAR v9] logs
  • Verify role is set: localStorage.getItem('userRole')
  • Check if permissions are loading

Everything Shows (No Filtering)​

  • This is the default fail-open behavior
  • Check if permissions.json exists in /static/
  • Verify Cloudflare Worker is responding

Wrong Items Hidden/Shown​

  • Clear localStorage: localStorage.clear()
  • Reload the page
  • Check permission configuration in permissions.json

Technical Implementation​

Components​

  1. DocSidebar/index.js - Main filtering logic (v9)
  2. permissions.json - Permission configuration
  3. RoleSwitcher - Development role switcher
  4. Permission Test Page - Testing interface

Version History​

  • v1-v5: Initial attempts with Clerk integration
  • v6-v7: Hide-by-default approach (caused blank sidebar)
  • v8: Fixed to show-by-default
  • v9: Added static file fallback (current)

Best Practices​

  1. Always test permission changes with multiple roles
  2. Use the test page to verify filtering works correctly
  3. Document which roles should access new content
  4. Default to showing content when uncertain
  5. Keep permissions simple - avoid complex nested rules