diff --git a/examples/RBAC/rbac-ui-spec.md b/examples/RBAC/rbac-ui-spec.md new file mode 100644 index 00000000..44ae74e4 --- /dev/null +++ b/examples/RBAC/rbac-ui-spec.md @@ -0,0 +1,321 @@ +# RBAC Management UI — Design Specification + +## Overview + +This document describes the Monitor RBAC management interface: its layout, navigation, entity model, visual conventions, badge/chip meanings, and inheritance behaviour. It is intended as a handoff reference for developers implementing the production version. + +--- + +## Application layout + +The app is a two-column shell with a fixed top bar. + +``` +┌─────────────────────────────────────────────────┐ +│ Top bar (brand + environment badge + avatar) │ +├──────────────┬──────────────────────────────────┤ +│ │ │ +│ Sidebar │ Main panel │ +│ (200px) │ (fills remaining width) │ +│ │ │ +└──────────────┴──────────────────────────────────┘ +``` + +### Top bar + +| Element | Purpose | +|---|---| +| Brand dot (green) | Indicates a live/healthy connection to the monitoring backend | +| `Monitor RBAC` wordmark | App name | +| Environment badge (`production`, `staging`, etc.) | Reminds operators which environment they are modifying — destructive changes in production are intentional | +| User avatar circle | Current operator identity; initials derived from name | + +### Sidebar + +Three navigation sections: + +- **Overview** — `Dashboard` (system summary + inheritance model diagram) +- **Identity** — `Users`, `Groups`, `Roles` (the three core entity types) +- **Audit** — `Audit log` (change history, out of scope for this spec) + +Each identity nav item shows a **count badge** (e.g. `8`, `5`, `6`) reflecting the total number of entities of that type. The active item is indicated by a green left border accent and bold label. + +--- + +## Panels + +### Dashboard (Overview) + +Displays three **stat cards** at the top: + +| Card | Content | +|---|---| +| Users | Total user count + active sub-count | +| Groups | Total group count + max nesting depth | +| Roles | Total role count + note about direct vs inherited | + +Below the stat cards is an **inheritance model diagram** — a three-column schematic showing how Groups → Roles on groups → Users form the inheritance chain. This is a read-only orientation aid, not interactive. + +A note block (green left border) explains the inheritance rule in plain language. + +--- + +### Users panel + +Split into a **list pane** (left, ~52% width) and a **detail pane** (right). + +#### List pane + +Each row is a user card containing: + +| Element | Description | +|---|---| +| Avatar circle | Two-letter initials; background colour varies by user for visual distinction | +| Name | Full display name | +| Meta line | Email address · primary group path (e.g. `Engineering → Backend`) | +| Tag row | Compact role and group badges (see Badge reference below) | +| Status dot | Green = active, grey = inactive/suspended | + +A search input at the top filters rows by any visible text (name, email, group, role). + +Clicking a row selects it (blue tint) and loads the detail pane. + +#### Detail pane — user + +Shows full user information organised into sections: + +| Section | Contents | +|---|---| +| Header | Avatar, full name, email address | +| Fields | Status, internal ID (truncated), created date | +| Group membership | Chips for every group the user directly belongs to. Sub-groups are also shown if membership was inherited via a parent group, with a small `via GroupName` annotation. | +| Effective roles | All roles the user holds — both direct assignments and roles inherited through group membership (see Role chips below) | +| Group tree | A visual indented tree showing the ancestry path of the user's groups | + +--- + +### Groups panel + +Same split layout as Users. + +#### List pane — group cards + +| Element | Description | +|---|---| +| Avatar square (rounded) | Two-letter abbreviation; colour indicates domain (green = engineering, amber = ops, red = admin) | +| Name | Group display name | +| Meta line | Parent group (if nested) · member count | +| Tag row | Roles assigned directly to this group; inherited roles shown with italic/faded styling | + +#### Detail pane — group + +| Section | Contents | +|---|---| +| Header | Avatar, group name, hierarchy level label | +| Fields | Internal ID | +| Members (direct) | Name chips for users who are direct members of this group | +| Child groups | Chips for any groups nested inside this one | +| Assigned roles | Roles directly assigned to this group — what all members will inherit | +| Inheritance note | Plain-language explanation of how roles propagate to children | +| Group hierarchy | Indented tree showing parent → this group → children | + +--- + +### Roles panel + +Same split layout. + +#### List pane — role cards + +| Element | Description | +|---|---| +| Avatar square | Two-letter abbreviation of the role name | +| Name | Role identifier (lowercase slug) | +| Meta line | Short description of access level · assignment count | +| Tag row | Groups and/or users the role is directly assigned to | + +#### Detail pane — role + +| Section | Contents | +|---|---| +| Header | Avatar, role name, description | +| Fields | Internal ID, scope | +| Assigned to groups | Group chips where this role is directly configured | +| Assigned to users (direct) | User chips that hold this role outside of any group | +| Effective principals | All principals (users) who effectively have this role, whether directly or via group inheritance | +| Inheritance note | Explains direct vs inherited assignments | + +--- + +## Badge and chip reference + +### Role tags (amber / orange) + +Appear on user and group list rows to show which roles apply. + +| Style | Meaning | +|---|---| +| Solid amber background, normal text | **Direct assignment** — the role is explicitly assigned to this entity | +| Faded / italic text, dashed border | **Inherited role** — the role flows from a parent group, not assigned directly | + +In the detail pane, inherited role chips include a small `↑ GroupName` annotation identifying the source group. + +### Group tags (green) + +Appear on user list rows and role detail panes. + +| Style | Meaning | +|---|---| +| Solid green background | The entity belongs to or is assigned to this group directly | + +### Status dot + +| Colour | Meaning | +|---|---| +| Green (filled) | User account is active | +| Grey (filled) | User account is inactive or suspended | + +### Environment badge (top bar) + +| Value | Meaning | +|---|---| +| `production` | Live system — changes are immediate and real | +| `staging` | Pre-production — safe for testing | + +### Count badge (sidebar nav) + +Small pill next to each nav label showing the total number of entities of that type. Updates to reflect search/filter state when implemented. + +--- + +## Inheritance model + +The RBAC system implements **two inheritance axes**: + +### 1. Group → child group + +Groups can be nested to any depth. A child group inherits all roles assigned to its parent group. This is transitive — a role on `Engineering` propagates to `Backend` and `Frontend`, and would continue to any groups nested inside those. + +``` +Engineering (role: viewer) +├── Backend (role: editor, inherits: viewer) +└── Frontend (role: editor, inherits: viewer) +``` + +### 2. Group → member users + +All roles effective on a group (direct + inherited from parent groups) are inherited by every user who is a member of that group. + +``` +User: Alice + Direct member of: Engineering, Backend + Effective roles: + - admin (direct on Alice) + - viewer (inherited via Engineering) + - editor (inherited via Backend) +``` + +### Role resolution + +When checking if a user has a given role, the system should: + +1. Check direct role assignments on the user. +2. For each group the user belongs to (directly or transitively), check all roles on that group. +3. Union the full set — **no role negation** in the base model (roles only grant, never deny). + +This makes effective role computation a union of all reachable role sets across the user's group membership graph. + +--- + +## Visual conventions + +| Convention | Meaning | +|---|---| +| Dashed chip border | Inherited / transitive — not directly configured here | +| `↑ GroupName` annotation | Points to the source of an inherited permission | +| Green left border on nav item | Currently active section | +| Indented tree with corner connector | Shows parent–child group hierarchy | +| Green note block (left border) | Contextual explanation of inheritance behaviour — appears wherever inherited permissions could be confusing | +| Blue tint on selected list row | Currently selected entity; detail pane reflects this entity | + +--- + +## Entity data model (for implementation reference) + +### User + +```ts +interface User { + id: string; // e.g. "usr_01HX…4AF" + name: string; + email: string; + status: "active" | "inactive"; + createdAt: string; // ISO date + directGroups: string[]; // group IDs — direct membership only + directRoles: string[]; // role IDs — assigned directly to this user + // Computed at read time: + effectiveGroups: string[]; // all groups including transitive + effectiveRoles: string[]; // all roles including inherited +} +``` + +### Group + +```ts +interface Group { + id: string; // e.g. "grp_02KX…9BC" + name: string; + parentGroupId?: string; // null for top-level groups + directRoles: string[]; // role IDs assigned to this group + // Computed at read time: + effectiveRoles: string[]; // direct + inherited from parent chain + memberUserIds: string[]; // direct members only + childGroupIds: string[]; // direct children only +} +``` + +### Role + +```ts +interface Role { + id: string; // e.g. "rol_00AA…1F2" + name: string; // slug, e.g. "admin", "viewer" + description: string; + scope: string; // e.g. "system-wide", "monitoring:read" + // Computed at read time: + directGroupIds: string[]; // groups this role is assigned to + directUserIds: string[]; // users this role is assigned to directly + effectivePrincipalIds: string[]; // all users who hold this role +} +``` + +--- + +## Recommended API surface + +| Method | Path | Description | +|---|---|---| +| `GET` | `/users` | List all users with effectiveRoles and effectiveGroups | +| `GET` | `/users/:id` | Single user detail | +| `POST` | `/users/:id/roles` | Assign a role directly to a user | +| `DELETE` | `/users/:id/roles/:roleId` | Remove a direct role from a user | +| `POST` | `/users/:id/groups` | Add user to a group | +| `DELETE` | `/users/:id/groups/:groupId` | Remove user from a group | +| `GET` | `/groups` | List all groups with hierarchy | +| `GET` | `/groups/:id` | Single group detail | +| `POST` | `/groups/:id/roles` | Assign a role to a group | +| `POST` | `/groups/:id/children` | Nest a child group | +| `GET` | `/roles` | List all roles with effective principals | +| `GET` | `/roles/:id` | Single role detail | + +--- + +## Handoff notes for Claude Code + +When implementing this in a production stack: + +- **State management** — effective roles and groups should be computed server-side and returned in API responses. Do not compute inheritance chains in the frontend. +- **Component split** — `EntityListPane`, `UserDetail`, `GroupDetail`, `RoleDetail`, `InheritanceChip`, `GroupTree` are the natural component boundaries. +- **CSS tokens** — all colours use CSS variables (`--color-background-primary`, `--color-border-tertiary`, etc.) that map to the design system. Replace with your own token layer (Tailwind, CSS Modules, etc.). +- **Search** — currently client-side string matching. For large deployments, wire to a server-side search endpoint. +- **Inheritance note blocks** — always render these wherever inherited permissions are displayed. They prevent operator confusion when a user has a role they didn't expect. diff --git a/examples/RBAC/rbac_management_ui.html b/examples/RBAC/rbac_management_ui.html new file mode 100644 index 00000000..8f10a2b1 --- /dev/null +++ b/examples/RBAC/rbac_management_ui.html @@ -0,0 +1,566 @@ + + + +
+ +
+
+
+ Monitor RBAC +
+
+ production +
A
+
+
+ + + + + +
+ + +
+
+
RBAC overview
Inheritance model and system summary
+
+
+
Users
8
6 active
+
Groups
5
Nested up to 3 levels
+
Roles
6
Direct + inherited
+
+
+
Inheritance model
+
+
+
Groups
+
Engineering
+
→ Backend
+
→ Frontend
+
Ops
+
Admins
+
+
→
+
+
Roles on groups
+
viewer
+
editor
+
deployer
+
admin
+
+
→
+
+
Users inherit
+
alice
+
bob
+
carol
+
+ 5 more…
+
+
+
+ Users inherit all roles from every group they belong to — and transitively from parent groups. Roles can also be assigned directly to users, overriding or extending inherited permissions. +
+
+
+ + +
+
+
Users
Manage identities, group membership and direct roles
+ +
+
+
+
+
+
+
AL
+
+
Alice Lang
+
alice@corp.io · Engineering → Backend
+
adminviewerBackend
+
+
+
+
+
BK
+
+
Bob Kim
+
bob@corp.io · Engineering → Frontend
+
editorFrontend
+
+
+
+
+
CS
+
+
Carol Sanz
+
carol@corp.io · Ops
+
deployerviewerOps
+
+
+
+
+
DM
+
+
Dan Müller
+
dan@corp.io · Admins
+
adminAdmins
+
+
+
+
+
EP
+
+
Eve Park
+
eve@corp.io · Engineering → Backend
+
editorBackend
+
+
+
+
+
FR
+
+
Frank Rossi
+
frank@corp.io · (no groups)
+
viewer
+
+
+
+
+
+
+ +
AL
+
Alice Lang
+ +
Status● Active
+
IDusr_01HX…4AF
+
Created2024-03-12
+
+
+
Group membership direct only
+ + + Engineering + + + + Backend + via Engineering + +
+
+
Effective roles direct + inherited
+ admin + + viewer + ↑ Engineering + + + editor + ↑ Backend + +
Dashed roles are inherited transitively through group membership.
+
+
+
Group tree
+
Engineering
+
Backend child group
+
+
+
+
+ + +
+
+
Groups
Organise users in nested hierarchies; roles propagate to all members
+ +
+
+
+
+
+
+
EN
+
+
Engineering
+
Top-level · 2 child groups · 5 members
+
viewer
+
+
+
+
BE
+
+
Backend
+
Child of Engineering · 3 members
+
editorviewer
+
+
+
+
FE
+
+
Frontend
+
Child of Engineering · 2 members
+
editorviewer
+
+
+
+
OP
+
+
Ops
+
Top-level · 2 members
+
deployerviewer
+
+
+
+
AD
+
+
Admins
+
Top-level · 1 member
+
admin
+
+
+
+
+
+
EN
+
Engineering
+ +
IDgrp_02KX…9BC
+
+
+
Members direct
+ Alice LangEve ParkBob Kim +
+ all members of Backend, Frontend
+
+
+
Child groups
+ Backend + Frontend +
+
+
Assigned roles on this group
+ viewer +
Child groups Backend and Frontend inherit viewer, and additionally carry their own editor role.
+
+
+
Group hierarchy
+
Engineering
+
Backend
+
Frontend
+
+
+
+
+ + +
+
+
Roles
Define permission scopes; assign to users or groups
+ +
+
+
+
+
+
+
AD
+
+
admin
+
Full access · 2 direct assignments
+
AdminsAlice
+
+
+
+
ED
+
+
editor
+
Read + write · 2 group assignments
+
BackendFrontend
+
+
+
+
DE
+
+
deployer
+
Deploy access · 1 assignment
+
Ops
+
+
+
+
VI
+
+
viewer
+
Read-only · 1 group assignment
+
Engineering
+
+
+
+
AU
+
+
auditor
+
Audit log access · 0 assignments
+
+
+
+
+
+
AD
+
admin
+ +
IDrol_00AA…1F2
+
Scopesystem-wide
+
+
+
Assigned to groups
+ Admins +
+
+
Assigned to users (direct)
+ Alice Lang +
+
+
Effective principals via inheritance
+ Alice Lang + Dan Müller + …via Admins group +
Dan inherits admin through the Admins group. Alice holds it directly.
+
+
+
+
+ +
+
+ +