Access Control & User Management System

OverviewCopy Anchor Link

The Access Control & User Management System provides comprehensive role-based permissions and location-based data access for multi-location clinics. This system enables clinic owners to manage staff across multiple locations with granular control over data access and feature permissions.

Key FeaturesCopy Anchor Link

• Hierarchical Role System: Owner > Admin > Doctor/Consultant > Staff
• Location-Based Access: Assign users to specific locations or grant all-location access
• Shared Patient Records: Patients are shared across locations with access control
• Premium Features: Consolidated reporting and revenue sharing for multi-location clinics
• Security: Two-factor authentication, IP restrictions, and audit trails

User Roles & HierarchyCopy Anchor Link

Role DefinitionsCopy Anchor Link

1. OwnerCopy Anchor Link

• Description: Clinic owner with full system access
• Key Permissions:
  • Full access to all locations and data
  • Manage the Kulcare subscription — the owner alone holds this by default (view_subscription / manage_subscription, #2274)
  • Manage practice finance: commissions, revenue share, payouts
  • View consolidated reports (premium)
  • Create/manage all user types
  • Configure clinic settings
  • Access revenue sharing data (premium)

2. AdminCopy Anchor Link

• Description: Administrative staff with management capabilities
• Key Permissions:
  • Manage users (except owners)
  • Access patient bills and practice finance for assigned locations. Not the Kulcare subscription — changing or cancelling the plan is owner-only unless the tenant grants view_subscription / manage_subscription to the admin role explicitly (#2274)
  • View location-specific reports
  • Configure location settings
  • Full patient and appointment access

3. Doctor/ConsultantCopy Anchor Link

• Description: Medical practitioners (consultants are non-owner doctors)
• Key Permissions:
  • View/manage their own patients
  • Create appointments and prescriptions
  • View patient financial data (their patients only)
  • No access to other doctors' patients
  • No user management capabilities

4. StaffCopy Anchor Link

• Description: Non-medical support staff
• Key Permissions:
  • Basic patient registration and queue management
  • Appointment scheduling
  • No financial data access
  • No user management
  • No prescription access

Cross-Network RolesCopy Anchor Link

• Users can have different roles across different clinic networks
• Role assignments are network-specific
• Single sign-on with network selection

Location-Based Access ControlCopy Anchor Link

Access ModelsCopy Anchor Link

1. Single Location AccessCopy Anchor Link

• User assigned to specific location(s)
• Can only view/manage data for assigned locations
• Appointments and queue specific to location

2. All Locations AccessCopy Anchor Link

• Available for Owners and designated Admins
• View and manage data across all clinic locations
• Switch between location-specific and consolidated views

Data Visibility RulesCopy Anchor Link

Permission SystemCopy Anchor Link

Permission CategoriesCopy Anchor Link

1. Patient ManagementCopy Anchor Link

patient.view; // View patient records
patient.create; // Register new patients
patient.edit; // Update patient information
patient.delete; // Delete patient records
patient.export; // Export patient data

2. Appointment ManagementCopy Anchor Link

appointment.view; // View appointments
appointment.create; // Create new appointments
appointment.edit; // Modify appointments
appointment.cancel; // Cancel appointments
appointment.reports; // View appointment reports

3. Billing & FinancialCopy Anchor Link

These dotted names are illustrative and do not exist in the codebase. The real permissions are flat feature_name strings on reference.permissions, and billing is three separate families rather than one — see Permission management API for the authoritative list and Billing domain architecture for which family owns what. In short:

• patient bills: view_bills, add_bills, edit_bills
• practice finance: view_practice_finance, manage_practice_finance
• Kulcare subscription: view_subscription, manage_subscription (owner only)

billing.view; // View billing information
billing.create; // Create bills/invoices
billing.edit; // Modify billing records
billing.reports; // View financial reports
billing.consolidated; // View multi-location financials (premium)

4. Reports & AnalyticsCopy Anchor Link

reports.clinical; // Clinical reports
reports.financial; // Financial reports
reports.operational; // Operational metrics
reports.consolidated; // Multi-location reports (premium)

5. Settings & ConfigurationCopy Anchor Link

settings.clinic; // Clinic configuration
settings.users; // User management
settings.locations; // Location management
settings.billing; // Billing configuration

6. Marketing & CampaignsCopy Anchor Link

marketing.campaigns; // Create/manage campaigns
marketing.spend; // View/manage ad spend
marketing.analytics; // Marketing performance

Role-Permission MatrixCopy Anchor Link

User ManagementCopy Anchor Link

User LifecycleCopy Anchor Link

1. Invitation FlowCopy Anchor Link

Owner/Admin initiates invitation
    ↓
Email sent with invitation link
    ↓
User creates account with invitation code
    ↓
User assigned to role and location(s)
    ↓
User active in system

2. User StatesCopy Anchor Link

• Invited: Invitation sent, awaiting acceptance
• Active: User has accepted and can access system
• Suspended: Temporarily disabled, cannot login
• Deactivated: Permanently disabled, data retained

Invitation APICopy Anchor Link

POST /api/users/invite
{
  email: string
  role: "owner" | "admin" | "doctor" | "staff"
  locations: string[] | "all"
  permissions?: string[] // Optional custom permissions
  expiresIn?: number // Invitation expiry in days
}

User Management FeaturesCopy Anchor Link

• Bulk user import via CSV
• User activity tracking
• Last login timestamps
• Session management
• Force logout capability

Data Access PatternsCopy Anchor Link

Patient Data AccessCopy Anchor Link

• Shared across locations: Patients can visit any clinic location
• Access control: Based on user's location assignment and role
• Doctor-specific: Doctors only see patients they've treated
• Referral visibility: Referred patients visible to receiving doctor

Appointment AccessCopy Anchor Link

• Location-specific: Appointments tied to specific locations
• Cross-location booking: Available for authorized users
• Doctor schedules: Visible based on location assignment

Financial Data AccessCopy Anchor Link

• Location isolation: Financial data separated by location
• Consolidated view: Available to owners (premium feature)
• Doctor commissions: Track revenue sharing (premium)
• Patient-level: Doctors see financial data for their patients only

Security FeaturesCopy Anchor Link

Feature FlagsCopy Anchor Link

The following security features are controlled by feature flags:

• ENABLE_TWO_FACTOR_AUTH: Two-factor authentication system
• ENABLE_AUDIT_TRAIL: Audit trail tracking and viewing
• ENABLE_SESSION_MANAGEMENT: Session management and force logout
• ENABLE_IP_RESTRICTIONS: IP whitelisting/blacklisting (coming soon)

Authentication & AuthorizationCopy Anchor Link

Two-Factor Authentication (2FA)Copy Anchor Link

• SMS-based OTP
• Authenticator app support
• Backup codes
• Required for: Owners, Admins (configurable)

Session ManagementCopy Anchor Link

• Real-time Session Tracking: View all active sessions with device, browser, and location information
• Device Detection: Automatic detection of device type, browser, and operating system
• Force Logout: Terminate individual sessions or all sessions except current
• Session Status: Track active/idle sessions with last activity timestamps
• Current Session Identification: Visual indicator for the user's current session
• Session History: Complete login history with IP addresses and user agents
• Concurrent Login Support: Allow multiple devices with tracking
• Session Timeout Configuration: Customizable session expiration
• Activity Monitoring: Track user actions within each session

IP RestrictionsCopy Anchor Link

• Whitelist IP ranges by role
• Location-based IP restrictions
• VPN detection and policies
• Geo-blocking capabilities

Audit TrailCopy Anchor Link

Tracked EventsCopy Anchor Link

• User login/logout
• Data access (patient records, financial)
• Configuration changes
• User management actions
• Export operations

Audit Log StructureCopy Anchor Link

{
  userId: string
  action: string
  resource: string
  resourceId: string
  location: string
  ipAddress: string
  userAgent: string
  timestamp: Date
  changes?: Record<string, any>
}

Premium FeaturesCopy Anchor Link

Consolidated ReportingCopy Anchor Link

• Multi-location dashboards: Overview across all locations
• Comparative analytics: Compare location performance
• Financial consolidation: Combined P&L statements
• Trend analysis: Cross-location trends

Revenue Sharing & CommissionsCopy Anchor Link

• Doctor commission tracking: Percentage or fixed fee
• Automated calculations: Based on services rendered
• Payout management: Track pending and paid commissions
• Performance incentives: Bonus calculations

Advanced Access ControlCopy Anchor Link

• Custom roles: Create clinic-specific roles
• Granular permissions: Feature-level access control
• Approval workflows: Multi-step approval for sensitive actions
• Temporary access: Time-bound permission grants

Implementation ArchitectureCopy Anchor Link

Database Schema UpdatesCopy Anchor Link

Users Table ExtensionCopy Anchor Link

ALTER TABLE users ADD COLUMN (
  phone_verified BOOLEAN DEFAULT FALSE,
  two_factor_enabled BOOLEAN DEFAULT FALSE,
  two_factor_secret VARCHAR(255),
  last_login_at TIMESTAMP,
  suspended_at TIMESTAMP,
  suspended_reason TEXT,
  created_by_user_id UUID REFERENCES users(id),
  ip_whitelist JSONB DEFAULT '[]'
);

User Location AssignmentsCopy Anchor Link

CREATE TABLE user_location_assignments (
  id UUID PRIMARY KEY,
  user_id UUID REFERENCES users(id),
  location_id UUID REFERENCES locations(id),
  assigned_at TIMESTAMP DEFAULT NOW(),
  assigned_by UUID REFERENCES users(id),
  is_primary BOOLEAN DEFAULT FALSE,
  UNIQUE(user_id, location_id)
);

Custom PermissionsCopy Anchor Link

CREATE TABLE user_custom_permissions (
  id UUID PRIMARY KEY,
  user_id UUID REFERENCES users(id),
  permission VARCHAR(100),
  granted_by UUID REFERENCES users(id),
  granted_at TIMESTAMP DEFAULT NOW(),
  expires_at TIMESTAMP,
  UNIQUE(user_id, permission)
);

API EndpointsCopy Anchor Link

User ManagementCopy Anchor Link

// User CRUD
GET    /api/users                    // List users with filters
GET    /api/users/:id                // Get user details
POST   /api/users/invite             // Send invitation
PUT    /api/users/:id                // Update user
DELETE /api/users/:id                // Deactivate user

// User Status
PUT    /api/users/:id/suspend       // Suspend user
PUT    /api/users/:id/activate      // Activate user
POST   /api/users/:id/reset-password // Trigger password reset

// Location Assignment
GET    /api/users/:id/locations     // Get user's locations
PUT    /api/users/:id/locations     // Update location assignments

// Permissions
GET    /api/users/:id/permissions   // Get effective permissions
PUT    /api/users/:id/permissions   // Update custom permissions

// Audit
GET    /api/users/:id/activity      // User activity log
GET    /api/audit-logs              // System-wide audit logs
POST   /api/audit-logs/export       // Export audit logs (JSON/CSV)

// Session Management
GET    /api/users/:id/sessions      // Get user's active sessions
DELETE /api/users/:id/sessions/:sessionId // Force logout specific session
DELETE /api/users/:id/sessions      // Force logout all sessions
GET    /api/sessions/settings       // Get session configuration
PUT    /api/sessions/settings       // Update session configuration
GET    /api/sessions/:id/activity   // Get session activity details

State Management ExtensionCopy Anchor Link

interface UserManagementState {
  // Users
  users: User[];
  usersLoading: boolean;
  usersError: string | null;

  // Current user permissions
  permissions: string[];
  locationAccess: string[] | "all";

  // Actions
  fetchUsers: (filters?: UserFilters) => Promise<void>;
  inviteUser: (data: InviteUserData) => Promise<void>;
  updateUser: (id: string, data: UpdateUserData) => Promise<void>;
  suspendUser: (id: string, reason: string) => Promise<void>;
  updateLocationAssignments: (
    userId: string,
    locations: string[]
  ) => Promise<void>;
}

UI ComponentsCopy Anchor Link

User Management (packages/ui-kit/src/components/users/)Copy Anchor Link

UserTable.tsx; // List users with actions
UserInviteModal.tsx; // Invite new user form
UserEditModal.tsx; // Edit user details
UserLocationManagementModal.tsx; // Manage user location assignments
TwoFactorSetupModal.tsx; // Two-factor authentication setup wizard
TwoFactorManagement.tsx; // Manage 2FA settings
AuditTrailViewer.tsx; // System-wide audit trail with filtering and export
SessionManagement.tsx; // Active session management with force logout
PermissionMatrix.tsx; // View/edit permissions (coming soon)
UserActivityLog.tsx; // User activity timeline (coming soon)

Access Control (packages/ui-kit/src/components/access/)Copy Anchor Link

PermissionGate.tsx; // Component-level access control
LocationSelector.tsx; // Switch between locations
AccessDenied.tsx; // Unauthorized access page

Integration PointsCopy Anchor Link

Subscription System IntegrationCopy Anchor Link

• Location limits enforced based on subscription plan
• Premium features (consolidated reports, revenue sharing) gated by plan
• User invitation limits (if applicable)

Existing Auth SystemCopy Anchor Link

• Extend current User and Clinic interfaces
• Maintain backward compatibility
• Progressive enhancement approach

Mobile App ConsiderationsCopy Anchor Link

• Same permission model applies
• Location-based features in mobile
• Offline capability with sync

Migration StrategyCopy Anchor Link

Phase 1: Core User ManagementCopy Anchor Link

1. Extend user model with new fields
2. Implement invitation system
3. Basic role-based permissions

Phase 2: Location-Based AccessCopy Anchor Link

1. Create location assignment system
2. Implement data filtering by location
3. Location switching UI

Phase 3: Advanced Features (Completed)Copy Anchor Link

1. ✅ Two-factor authentication with TOTP and backup codes
2. ✅ Audit trail implementation with filtering and export
3. ✅ Session management with force logout capabilities
4. ⏳ IP restrictions (pending)

Phase 4: Premium FeaturesCopy Anchor Link

1. Consolidated reporting
2. Revenue sharing system
3. Custom roles and permissions

Security Best PracticesCopy Anchor Link

1. Principle of Least Privilege: Users get minimum required permissions
2. Regular Access Reviews: Periodic audit of user permissions
3. Secure Defaults: New users start with minimal access
4. Audit Everything: Comprehensive logging of sensitive actions
5. Data Encryption: Encrypt sensitive data at rest and in transit