# c77_rbac Usage Guide - Part 1: Core Concepts and Basic Usage

This is Part 1 of the comprehensive c77_rbac usage guide. This part covers the fundamental concepts and basic usage patterns.

**Complete Guide Structure:**
- **Part 1: Core Concepts and Basic Usage** (this document)
- Part 2: Advanced Usage Scenarios and Time-Based Permissions
- Part 3: Framework Integration (Laravel, Django, Rails)
- Part 4: Real-World Examples and Performance Optimization
- Part 5: Security Best Practices and Troubleshooting

## Table of Contents

1. [Understanding c77_rbac Concepts](#understanding-c77_rbac-concepts)
2. [Basic Usage Patterns](#basic-usage-patterns)

## Understanding c77_rbac Concepts

### What is Database-Level Authorization?

Traditional application authorization happens in your code:

```php
// Traditional approach - authorization in application
if ($user->role === 'admin' || $user->department === $post->department) {
    return Post::all();  // Returns ALL posts, then filters in PHP
}
```

With c77_rbac, authorization happens at the database level:

```php
// c77_rbac approach - authorization in database
return Post::all();  // Database automatically returns only allowed posts
```

### Core Architecture

```
Application User (external_id: '123')
    ↓
Subject (database record linking external_id to internal ID)
    ↓
Subject_Roles (user has roles with specific scopes)
    ↓
Role_Features (roles have specific permissions/features)
    ↓
RLS Policies (database automatically filters data)
```

### Key Components Explained

#### 1. Subjects (Users)
```sql
-- Subjects link your application users to RBAC
INSERT INTO c77_rbac_subjects (external_id) VALUES ('user_123');

-- External ID should match your application's user identifier
-- Usually: Laravel User ID, Django user.id, Rails user.id, etc.
```

#### 2. Roles
```sql
-- Roles are named collections of permissions
-- Examples: 'admin', 'manager', 'employee', 'customer', 'guest'

-- Roles get meaning through the features they're granted
SELECT public.c77_rbac_grant_feature('manager', 'approve_requests');
SELECT public.c77_rbac_grant_feature('manager', 'view_team_reports');
```

#### 3. Features (Permissions)
```sql
-- Features are specific permissions that can be checked
-- Good naming convention: action_object
-- Examples:
SELECT public.c77_rbac_grant_feature('editor', 'view_posts');
SELECT public.c77_rbac_grant_feature('editor', 'create_posts');
SELECT public.c77_rbac_grant_feature('editor', 'edit_posts');
SELECT public.c77_rbac_grant_feature('moderator', 'delete_posts');
SELECT public.c77_rbac_grant_feature('admin', 'manage_users');
```

#### 4. Scopes (Context)
```sql
-- Scopes define WHERE a role applies
-- Format: scope_type/scope_id

-- Examples:
'global/all'                    -- Global access to everything
'department/engineering'        -- Only engineering department
'region/north_america'         -- Only North America region  
'project/apollo_mission'       -- Only Apollo project
'customer/enterprise_client'   -- Only enterprise client data
'tenant/company_abc'           -- Multi-tenant: only company ABC
```

#### 5. Row-Level Security Policies
```sql
-- Policies automatically filter database queries
-- Applied to tables to enforce permissions

-- Example: Users can only see posts in their department
SELECT public.c77_rbac_apply_policy(
    'posts',              -- table name
    'view_posts',         -- required feature
    'department',         -- scope type  
    'department_id'       -- column containing department ID
);
```

## Basic Usage Patterns

### Pattern 1: Simple Role-Based Access

Perfect for basic applications with clear role hierarchies.

```sql
-- Step 1: Define roles and their capabilities
SELECT public.c77_rbac_grant_feature('admin', 'manage_users');
SELECT public.c77_rbac_grant_feature('admin', 'view_all_data');
SELECT public.c77_rbac_grant_feature('admin', 'edit_all_data');

SELECT public.c77_rbac_grant_feature('manager', 'view_reports');
SELECT public.c77_rbac_grant_feature('manager', 'approve_requests');

SELECT public.c77_rbac_grant_feature('employee', 'view_own_data');
SELECT public.c77_rbac_grant_feature('employee', 'submit_requests');

-- Step 2: Assign users to roles
SELECT public.c77_rbac_assign_subject('1', 'admin', 'global', 'all');
SELECT public.c77_rbac_assign_subject('101', 'manager', 'global', 'all');
SELECT public.c77_rbac_assign_subject('201', 'employee', 'global', 'all');

-- Step 3: Apply policies to tables
SELECT public.c77_rbac_apply_policy(
    'user_profiles', 'view_own_data', 'user', 'user_id'
);

-- Step 4: Use in your application
-- Set user context
SET "c77_rbac.external_id" TO '201';

-- Query automatically filtered
SELECT * FROM user_profiles;  -- Only returns data for user 201
```

### Pattern 2: Department-Based Access

Common in organizations with department isolation.

```sql
-- Step 1: Create department-specific roles
SELECT public.c77_rbac_grant_feature('dept_admin', 'manage_dept_users');
SELECT public.c77_rbac_grant_feature('dept_admin', 'view_dept_data');
SELECT public.c77_rbac_grant_feature('dept_admin', 'edit_dept_data');

SELECT public.c77_rbac_grant_feature('dept_member', 'view_dept_data');
SELECT public.c77_rbac_grant_feature('dept_member', 'create_requests');

-- Step 2: Assign users to departments
SELECT public.c77_rbac_assign_subject('101', 'dept_admin', 'department', 'engineering');
SELECT public.c77_rbac_assign_subject('102', 'dept_member', 'department', 'engineering');
SELECT public.c77_rbac_assign_subject('201', 'dept_admin', 'department', 'marketing');

-- Step 3: Apply department-based policies
SELECT public.c77_rbac_apply_policy(
    'projects', 'view_dept_data', 'department', 'owning_department'
);

SELECT public.c77_rbac_apply_policy(
    'expenses', 'view_dept_data', 'department', 'department_code'
);

-- Step 4: Test department isolation
SET "c77_rbac.external_id" TO '102';  -- Engineering member
SELECT * FROM projects;  -- Only engineering projects
SELECT * FROM expenses;  -- Only engineering expenses
```

### Pattern 3: Multi-Tenant Applications

Perfect for SaaS applications serving multiple clients.

```sql
-- Step 1: Define tenant-scoped roles
SELECT public.c77_rbac_grant_feature('tenant_admin', 'manage_tenant_users');
SELECT public.c77_rbac_grant_feature('tenant_admin', 'view_tenant_data');
SELECT public.c77_rbac_grant_feature('tenant_admin', 'configure_tenant');

SELECT public.c77_rbac_grant_feature('tenant_user', 'view_tenant_data');
SELECT public.c77_rbac_grant_feature('tenant_user', 'edit_own_data');

-- Step 2: Assign users to tenants
SELECT public.c77_rbac_assign_subject('1001', 'tenant_admin', 'tenant', 'company_a');
SELECT public.c77_rbac_assign_subject('1002', 'tenant_user', 'tenant', 'company_a');
SELECT public.c77_rbac_assign_subject('2001', 'tenant_admin', 'tenant', 'company_b');

-- Step 3: Apply tenant isolation policies
SELECT public.c77_rbac_apply_policy(
    'accounts', 'view_tenant_data', 'tenant', 'tenant_id'
);

SELECT public.c77_rbac_apply_policy(
    'invoices', 'view_tenant_data', 'tenant', 'tenant_id'
);

SELECT public.c77_rbac_apply_policy(
    'users', 'view_tenant_data', 'tenant', 'tenant_id'
);

-- Step 4: Perfect tenant isolation
SET "c77_rbac.external_id" TO '1002';  -- Company A user
SELECT * FROM accounts;  -- Only Company A accounts
SELECT * FROM invoices;  -- Only Company A invoices
```

### Pattern 4: Hierarchical Organizations

For complex organizational structures with multiple levels.

```sql
-- Step 1: Define hierarchical roles
-- Global level
SELECT public.c77_rbac_grant_feature('global_admin', 'manage_everything');
SELECT public.c77_rbac_grant_feature('global_admin', 'view_all_regions');

-- Regional level  
SELECT public.c77_rbac_grant_feature('regional_manager', 'manage_region');
SELECT public.c77_rbac_grant_feature('regional_manager', 'view_region_data');

-- Branch level
SELECT public.c77_rbac_grant_feature('branch_manager', 'manage_branch');
SELECT public.c77_rbac_grant_feature('branch_manager', 'view_branch_data');

-- Store level
SELECT public.c77_rbac_grant_feature('store_manager', 'manage_store');
SELECT public.c77_rbac_grant_feature('store_manager', 'view_store_data');

-- Step 2: Assign users to hierarchy levels
SELECT public.c77_rbac_assign_subject('1', 'global_admin', 'global', 'all');
SELECT public.c77_rbac_assign_subject('101', 'regional_manager', 'region', 'west_coast');
SELECT public.c77_rbac_assign_subject('201', 'branch_manager', 'branch', 'west_coast_sf');
SELECT public.c77_rbac_assign_subject('301', 'store_manager', 'store', 'sf_downtown');

-- Step 3: Apply hierarchical policies
SELECT public.c77_rbac_apply_policy(
    'sales_data', 'view_store_data', 'store', 'store_code'
);

SELECT public.c77_rbac_apply_policy(
    'inventory', 'view_branch_data', 'branch', 'branch_code'
);

-- Step 4: Each level sees appropriate data
SET "c77_rbac.external_id" TO '301';  -- Store manager
SELECT * FROM sales_data;  -- Only their store's data
```

---

**Continue to [Part 2: Advanced Usage Scenarios](USAGE-Part2.md)** for time-based permissions, conditional permissions, dynamic role assignment, and bulk operations.