UV-37 - Document UI flows, roles, and audit logs

docs/security/audit-logs.md

@@ -0,0 +1,117 @@
+---
+id: audit-logs
+title: Audit Logs
+sidebar_position: 2
+---
+
+Audit logs provide visibility into security-relevant and administrative actions
+performed within Cube AI. They help administrators and operators monitor
+activity, investigate issues, and support compliance and accountability
+requirements.
+
+---
+
+## Audit Logs Overview
+
+Audit logs record important events that occur within the Cube AI system,
+particularly those related to:
+
+- User activity
+- Domain-level changes
+- Access control and security-sensitive operations
+
+Audit logging is **domain-scoped**, meaning events are associated with the domain
+in which they occurred.
+
+---
+
+## What Is Recorded
+
+Depending on configuration and permissions, audit logs may include events such as:
+
+- User login and logout activity
+- Domain creation or deletion
+- Changes to domain membership
+- Role assignments or updates
+- Administrative actions performed through the UI
+- Security-related configuration changes
+
+Each audit log entry typically captures:
+
+- The type of action performed
+- The user who performed the action
+- The affected resource or domain
+- A timestamp of when the action occurred
+
+---
+
+## Accessing Audit Logs
+
+Audit logs are accessible through the Cube AI UI to users with sufficient
+permissions.
+
+Access to audit logs is restricted to authorized roles to ensure sensitive
+information is not exposed to unauthorized users.
+
+---
+
+## Using Audit Logs
+
+Audit logs can be used to:
+
+- Review recent administrative activity
+- Investigate unexpected behavior or configuration changes
+- Track access-related events
+- Support security reviews and incident analysis
+
+Audit logs provide an immutable record of events and are intended for
+observability rather than real-time monitoring.
+
+---
+
+## Audit Logs and Roles
+
+Visibility into audit logs depends on the user’s role within a domain.
+
+Typically:
+
+- Administrative roles can view audit logs
+- Standard users may not have access to audit information
+
+For more details on role-based permissions, see:
+👉 **Security & Access → Roles and Access Control**
+
+---
+
+## Audit Logs and Domain Context
+
+All audit log entries are associated with a specific domain.
+
+When switching domains:
+
+- The visible audit logs change accordingly
+- Only events related to the active domain are shown
+
+This ensures isolation and clarity when managing multiple domains.
+
+---
+
+## Security and Compliance
+
+Audit logging is a key component of Cube AI’s security posture.
+
+By maintaining a record of critical actions, audit logs help:
+
+- Detect misuse or misconfiguration
+- Support forensic analysis
+- Demonstrate accountability and operational transparency
+
+---
+
+## Next Steps
+
+To understand how permissions affect access to audit information, review:
+👉 **Security & Access → Roles and Access Control**
+
+For domain-level workflows, see:
+👉 **UI → Domains**

docs/security/roles-and-access-control.md

@@ -0,0 +1,125 @@
+---
+id: roles-and-access-control
+title: Roles and Access Control
+sidebar_position: 1
+---
+
+Cube AI uses role-based access control (RBAC) to manage what users can see and do
+within a domain. Roles define permissions at the domain level and ensure that
+actions are performed only by authorized users.
+
+---
+
+## Role-Based Access Control Overview
+
+Access control in Cube AI is **domain-scoped**.
+
+This means that:
+
+- Users can belong to one or more domains
+- A user may have different roles in different domains
+- Permissions apply only within the currently active domain
+
+Roles determine which UI features and actions are available to a user.
+
+---
+
+## Roles in Cube AI
+
+Cube AI provides a set of predefined roles that control access to domain features.
+
+While the exact role names and permissions may vary depending on deployment and
+configuration, roles typically differentiate between:
+
+- **Administrative users** – users with elevated permissions
+- **Standard users** – users with access to core functionality
+- **Restricted users** – users with limited or read-only access
+
+---
+
+## Common Permissions
+
+Roles may control access to actions such as:
+
+- Creating or managing domains
+- Inviting or managing domain members
+- Assigning or changing user roles
+- Accessing administrative UI sections
+- Viewing or managing security-related information
+- Interacting with models and chat interfaces
+
+Not all users have access to all features. The UI dynamically reflects the
+permissions granted by the user’s role.
+
+---
+
+## Domain Membership
+
+Users must be members of a domain to access its resources.
+
+Within a domain:
+
+- Each user is assigned a specific role
+- Role assignments apply only to that domain
+- Removing a user from a domain immediately revokes domain access
+
+Domain membership and role assignments are managed through the Cube AI UI by users
+with sufficient permissions.
+
+---
+
+## UI Behavior Based on Roles
+
+The Cube AI UI adapts based on the active user’s role.
+
+Depending on permissions:
+
+- Certain navigation items may be hidden
+- Some actions may be disabled or unavailable
+- Administrative sections may only be visible to authorized users
+
+This ensures that users only interact with features they are allowed to access.
+
+---
+
+## Role Changes
+
+When a user’s role is updated:
+
+- The change takes effect immediately
+- UI visibility and available actions are updated accordingly
+- No page reload may be required, depending on the UI state
+
+Role changes affect only the selected domain.
+
+---
+
+## Access Control and Security
+
+Role-based access control helps enforce security boundaries by:
+
+- Limiting access to sensitive operations
+- Reducing the risk of accidental or unauthorized changes
+- Ensuring clear separation of responsibilities within a domain
+
+RBAC works together with other Cube AI security mechanisms, such as authentication
+and auditing, to provide a controlled and observable environment.
+
+---
+
+## Auditing and Role-Related Events
+
+Changes to domain membership and roles may be recorded as security-relevant events.
+
+For details on how such events are tracked, see:
+👉 **Security & Access → Audit Logs**
+
+---
+
+## Next Steps
+
+To understand how access-related actions are monitored, continue with:
+👉 **Security & Access → Audit Logs**
+
+For domain workflows, see:
+👉 **UI → Domains**

docs/ui/domains.md

@@ -0,0 +1,129 @@
+---
+id: domains
+title: Domains
+sidebar_position: 2
+---
+
+Domains are a core organizational concept in Cube AI. A domain represents an
+isolated workspace where users interact with models, manage access, and perform
+LLM-powered operations.
+
+Domains provide logical isolation between different teams or workloads while
+sharing the same Cube AI deployment.
+
+---
+
+## What is a Domain?
+
+A **domain** acts as an isolated environment that groups:
+
+- Users and their roles
+- Models and backend configurations
+- Chat and inference activity
+
+All interactions in Cube AI happen **within the context of a selected domain**.
+This ensures clear separation between different teams, projects, or use cases.
+
+---
+
+## Accessing Domains
+
+After logging in, users are presented with the Cube AI dashboard, where available
+domains are listed.
+
+From the dashboard, users can:
+
+- Open an existing domain
+- Create a new domain (if permitted)
+
+The currently active domain defines the scope of all actions in the UI.
+
+For a step-by-step onboarding flow, see:
+👉 **Getting Started**
+
+---
+
+## Creating a Domain
+
+To create a new domain:
+
+1. Log in to the Cube AI UI.
+2. From the dashboard, click **Create Domain**.
+3. Enter a **Name** and **Route** for the domain.
+4. Click **Create**.
+5. When the domain appears in the list, click **Open Domain**.
+
+Once opened, you are redirected into the domain workspace.
+
+![Create domain screen](/img/getting-started-create-domain.png)
+
+---
+
+## Domain Workspace
+
+After opening a domain, the UI switches into the domain context.
+
+Inside a domain, users can:
+
+- Access the chat interface
+- Select and interact with available models
+- Perform domain-scoped operations
+
+Navigation within the domain is handled through the left-side menu.
+
+![Chat interface](/img/getting-started-chat.png)
+
+---
+
+## Domain Context
+
+The active domain determines:
+
+- Which users and roles apply
+- Which models are available
+- Which resources and actions are visible in the UI
+
+Switching domains changes this context entirely, ensuring isolation between
+different environments.
+
+:::note
+Switching domains updates the entire UI context, including available models,
+users, and permissions.
+:::
+
+---
+
+## Domain Membership and Roles
+
+Users belong to one or more domains and may have different roles in each domain.
+Roles define what actions a user is allowed to perform within that domain.
+
+Details about roles and permissions are documented in:
+
+👉 **Security & Access → Roles and Access Control**
+
+---
+
+## Typical Domain Workflow
+
+A common user flow in Cube AI looks like this:
+
+1. Log in to the Cube AI UI
+2. Select or create a domain
+3. Enter the domain workspace
+4. Interact with models and services within that domain
+5. Switch domains as needed
+
+---
+
+## Next Steps
+
+After creating and entering a domain, you can explore:
+
+- User actions and profile management
+- Role-based access control
+- Audit logs and security events
+- API access scoped to domains
+
+For first-time users, see:
+👉 **UI → User Actions**