Permissions

CharleOS uses a flexible permission system based on access levels and work types. All permission logic is centralized in lib/permissions.ts.

Permission Model

Two-Tier System

CharleOS combines two concepts for access control:

Access Level

System-wide permission tier

Admin: Full access (Luke)
Manager: Management features (Simon, Andre, Ben, Nic)
Staff: Standard access (everyone else)

Work Type

Role-based feature access

development/design/qa: IC features
pm: Project management features
csm: Client success features
sdr: Limited features

Combined Logic

The permission system uses both factors:

// Example: Can view manager dashboard?
function canViewManagerDashboard(user) {
  return user.accessLevel === "admin" || user.accessLevel === "manager";
}

// Example: Can view IC dashboard?
function canViewICDashboard(user) {
  const isIC = ["development", "design", "qa"].includes(user.workType);
  return isIC && user.accessLevel === "staff";
}

Result: A developer with manager access level sees the Manager Dashboard, not the IC Dashboard.

Permission Functions

All permission checks are in lib/permissions.ts:

Access Level Checks

import { isAdmin, isAdminOrManager, hasManagerAccess } from "@/lib/permissions";

// Check if user is admin
if (isAdmin(user)) {
  // Show admin-only features
}

// Check if user is admin or manager
if (isAdminOrManager(user)) {
  // Show management features
}

// Alias for isAdminOrManager
if (hasManagerAccess(user)) {
  // Show management features
}

Work Type Checks

import { isIC, isPM, isCSM } from "@/lib/permissions";

// Check if user is an Individual Contributor (dev/design/qa)
if (isIC(user)) {
  // Show IC-specific features
}

// Check if user is a PM
if (isPM(user)) {
  // Show PM features
}

// Check if user is a CSM
if (isCSM(user)) {
  // Show CSM features
}

Dashboard Access

Dashboard Types

CharleOS has 5 dashboard types based on role:

Dashboard	Who Sees It	Permission Check
Manager Dashboard	Admin/Manager access level	`canViewManagerDashboard()`
PM Dashboard	PMs (staff level)	`canViewPMDashboard()`
CSM Dashboard	CSMs (staff level)	`canViewCSMDashboard()`
IC Dashboard	Developers/Designers/QA (staff level)	`canViewICDashboard()`
Executive Dashboard	Users with `hasExecutiveAccess` flag	`canViewCommercialsDashboard()`

Code:

import {
  canViewManagerDashboard,
  canViewPMDashboard,
  canViewCSMDashboard,
  canViewICDashboard,
} from "@/lib/permissions";

function getDashboardForUser(user) {
  if (canViewManagerDashboard(user)) return "/dashboard/manager";
  if (canViewPMDashboard(user)) return "/dashboard/pm";
  if (canViewCSMDashboard(user)) return "/dashboard/csm";
  if (canViewICDashboard(user)) return "/dashboard/ic";
  return "/dashboard";  // Fallback
}

Sidebar items are shown/hidden based on permissions:

import {
  canViewClients,
  canViewTasks,
  canViewSchedule,
  canViewMyTasks,
  canViewMySchedule,
  canViewCapacity,
  canViewReports,
  canViewAdmin,
} from "@/lib/permissions";

// Example: Sidebar navigation
const sidebarItems = [
  {
    label: "My Tasks",
    href: "/my-tasks",
    visible: canViewMyTasks(user),  // ICs only
  },
  {
    label: "Clients",
    href: "/clients",
    visible: canViewClients(user),  // Admin/Manager/PM/CSM
  },
  {
    label: "Schedule",
    href: "/schedule",
    visible: canViewSchedule(user),  // Admin/Manager/PM
  },
  {
    label: "Reports",
    href: "/reports",
    visible: canViewReports(user),  // Admin/Manager only
  },
  {
    label: "Admin",
    href: "/admin",
    visible: canViewAdmin(user),  // Admin only
  },
];

Operational Permissions

Task Management

import {
  canCreateTasks,
  canEditTasks,
  canDeleteTasks,
  canAssignSubtasks,
} from "@/lib/permissions";

// Can create tasks? (Admin/Manager/CSM/PM)
if (canCreateTasks(user)) {
  return <CreateTaskButton />;
}

// Can edit tasks? (Admin/Manager/PM/CSM - edits task-level fields)
// Allows editing: title, description, estimatedTime, clientId, pmId
// Does NOT allow: creating/deleting tasks, assigning subtasks
// Note: ICs (developers, designers, QA) cannot edit task-level fields
if (canEditTasks(user)) {
  return <EditTaskButton />;
}

// Can delete tasks? (Admin/Manager only)
if (canDeleteTasks(user)) {
  return <DeleteTaskButton />;
}

// Can assign subtasks? (Admin/Manager/PM)
if (canAssignSubtasks(user)) {
  return <AssignSubtaskButton />;
}

Quote Management

import {
  canCreateQuotes,
  canDeleteQuotes,
  canEditQuote,
  canApproveQuote,
  canManageQuotes,
} from "@/lib/permissions";

// Can create quotes? (Admin/Manager/CSM)
if (canCreateQuotes(user)) {
  return <CreateQuoteButton />;
}

// Can delete quotes? (Admin/Manager/CSM)
if (canDeleteQuotes(user)) {
  return <DeleteQuoteButton />;
}

// Can edit quote details? (Admin/Manager only)
if (canEditQuote(user)) {
  return <EditQuoteDetailsForm />;
}

// Can approve quotes? (Admin/Manager/CSM)
if (canApproveQuote(user)) {
  return <ApproveQuoteButton />;
}

Client Management

import {
  canEditClients,
  canEditClientSchedule,
  canManageClientUsers,
} from "@/lib/permissions";

// Can edit client details? (Admin/Manager only)
if (canEditClients(user)) {
  return <EditClientForm />;
}

// Can edit client schedule/blocks? (Admin/Manager/PM/CSM)
if (canEditClientSchedule(user)) {
  return <ClientScheduleEditor />;
}

// Can manage client portal users? (Admin/Manager/CSM)
if (canManageClientUsers(user)) {
  return <ClientUserManagement />;
}

Project Management

import {
  canCreateProjects,
  canEditProjectBudget,
  canManageProjectTasks,
  canAddProjectPhases,
} from "@/lib/permissions";

// Can create projects? (Admin/Manager only)
if (canCreateProjects(user)) {
  return <CreateProjectButton />;
}

// Can edit project budget? (Admin/Manager only)
if (canEditProjectBudget(user)) {
  return <EditBudgetForm />;
}

// Can manage project tasks? (Admin/Manager/PM)
if (canManageProjectTasks(user)) {
  return <ProjectTaskManager />;
}

// Can add phases? (Admin/Manager/PM)
if (canAddProjectPhases(user)) {
  return <AddPhaseButton />;
}

Implementation Patterns

Protected Server Component

// app/(dashboard)/admin/page.tsx
import { auth } from "@/lib/auth";
import { headers } from "next/headers";
import { redirect } from "next/navigation";
import { canViewAdmin } from "@/lib/permissions";

export default async function AdminPage() {
  const { data: session } = await auth.api.getSession({
    headers: headers(),
  });

  if (!session) {
    redirect("/auth");
  }

  // Check permission
  if (!canViewAdmin(session.user)) {
    redirect("/dashboard");  // Redirect to safe page
  }

  return <AdminPanel />;
}

Protected API Route

// app/api/internal/users/route.ts
import { auth } from "@/lib/auth";
import { headers } from "next/headers";
import { canViewAdmin } from "@/lib/permissions";

export async function GET(req: Request) {
  const { data: session } = await auth.api.getSession({
    headers: headers(),
  });

  if (!session) {
    return Response.json({ error: "Unauthorized" }, { status: 401 });
  }

  if (!canViewAdmin(session.user)) {
    return Response.json({ error: "Forbidden" }, { status: 403 });
  }

  // Fetch admin data...
}

Conditional UI Rendering

"use client";

import { useSession } from "@/lib/auth-client";
import { canCreateTasks } from "@/lib/permissions";

export function TaskActions() {
  const { data: session } = useSession();

  if (!session) return null;

  return (
    <div>
      {canCreateTasks(session.user) && (
        <CreateTaskButton />
      )}
      
      {canEditTasks(session.user) && (
        <EditTaskButton />
      )}
      
      {canDeleteTasks(session.user) && (
        <DeleteTaskButton />
      )}
    </div>
  );
}

Complete Permission Reference

Dashboard Access

Function	Who Gets Access
`canViewManagerDashboard`	Admin, Manager
`canViewPMDashboard`	PM (staff level)
`canViewCSMDashboard`	CSM (staff level)
`canViewICDashboard`	Dev/Design/QA (staff level)
`canViewCommercialsDashboard`	Users with `hasExecutiveAccess` flag

Function	Who Gets Access
`canViewMyTasks`	ICs (dev/design/qa)
`canViewMySchedule`	ICs (dev/design/qa)
`canViewMyTimeTracking`	ICs (dev/design/qa)
`canViewClients`	Admin, Manager, PM, CSM
`canViewTasks`	Admin, Manager, PM, CSM, ICs
`canViewSchedule`	Admin, Manager, PM
`canViewQuotes`	Admin, Manager, PM, CSM, ICs
`canViewProjects`	Admin, Manager, PM, ICs
`canViewTimeTracking`	Admin, Manager
`canViewCapacity`	Admin, Manager
`canViewAnnualLeave`	Admin, Manager
`canViewReports`	Admin, Manager
`canViewAdmin`	Admin only
`canViewKnowledgeBase`	Everyone
`canViewRag`	Everyone
`canViewHelpDesk`	Admin, Manager, CSM

Operational Permissions

Function	Who Gets Access	What It Allows
`canCreateTasks`	Admin, Manager, CSM, PM	Create new tasks
`canEditTasks`	Admin, Manager, PM, CSM	Edit task title, description, estimatedTime, clientId, pmId
`canDeleteTasks`	Admin, Manager	Delete tasks
`canAssignSubtasks`	Admin, Manager, PM
`canCreateQuotes`	Admin, Manager, CSM
`canDeleteQuotes`	Admin, Manager, CSM
`canEditQuote`	Admin, Manager
`canApproveQuote`	Admin, Manager, CSM
`canManageQuotes`	Admin, Manager, PM, CSM
`canEditClients`	Admin, Manager
`canEditClientSchedule`	Admin, Manager, PM, CSM
`canManageClientUsers`	Admin, Manager, CSM
`canCreateProjects`	Admin, Manager
`canEditProjectBudget`	Admin, Manager
`canManageProjectTasks`	Admin, Manager, PM
`canAddProjectPhases`	Admin, Manager, PM
`canEditRag`	Admin, Manager
`canViewActivityLog`	Admin, Manager

Adding New Permissions

Add Permission Function

Add to lib/permissions.ts:

export function canExportData(user: UserPermissionContext): boolean {
  return isAdmin(user);
}

Use in Components

import { canExportData } from "@/lib/permissions";

if (canExportData(user)) {
  return <ExportButton />;
}

Protect Routes

if (!canExportData(session.user)) {
  return Response.json({ error: "Forbidden" }, { status: 403 });
}

Best Practices

Always Check Permissions Server-Side

Client-side checks are for UI only. Always verify on the server:

// ✅ Good: Check on server
export async function GET(req: Request) {
  const { data: session } = await auth.api.getSession({ headers: headers() });
  if (!canViewAdmin(session.user)) {
    return Response.json({ error: "Forbidden" }, { status: 403 });
  }
  // ... return data
}

// ❌ Bad: Only checking client-side
"use client";
function AdminPanel() {
  if (!canViewAdmin(user)) return null;
  // ... fetch admin data (anyone can call the API!)
}

Use Specific Permission Functions

Don’t check accessLevel or workType directly:

// ✅ Good: Use specific function
if (canCreateTasks(user)) { ... }

// ❌ Bad: Direct check
if (user.accessLevel === "admin" || user.workType === "csm") { ... }

Redirect, Don't Hide

For pages, redirect unauthorized users:

// ✅ Good: Redirect
if (!canViewAdmin(user)) {
  redirect("/dashboard");
}

// ❌ Bad: Return null (shows blank page)
if (!canViewAdmin(user)) {
  return null;
}

Authentication

Auth architecture overview

Better Auth

Auth configuration details

Sessions

Session management

Getting Started

Database

Authentication

Testing

Deployment

Permission Model

Two-Tier System

Access Level

Work Type

Combined Logic

Permission Functions

Access Level Checks

Work Type Checks

Dashboard Access

Dashboard Types

Sidebar Visibility

Operational Permissions

Task Management

Quote Management

Client Management

Project Management

Implementation Patterns

Protected Server Component

Protected API Route

Conditional UI Rendering

Complete Permission Reference

Dashboard Access

Sidebar Visibility

Operational Permissions

Adding New Permissions

Best Practices

Authentication

Better Auth

Sessions

​Permission Model

​Two-Tier System

Access Level

Work Type

​Combined Logic

​Permission Functions

​Access Level Checks

​Work Type Checks

​Dashboard Access

​Dashboard Types

​Sidebar Visibility

​Operational Permissions

​Task Management

​Quote Management

​Client Management

​Project Management

​Implementation Patterns

​Protected Server Component

​Protected API Route

​Conditional UI Rendering

​Complete Permission Reference

​Dashboard Access

​Sidebar Visibility

​Operational Permissions

​Adding New Permissions

​Best Practices

​Related Documentation

Authentication

Better Auth

Sessions

Permission Model

Two-Tier System

Combined Logic

Permission Functions

Access Level Checks

Work Type Checks

Dashboard Access

Dashboard Types

Sidebar Visibility

Operational Permissions

Task Management

Quote Management

Client Management

Project Management

Implementation Patterns

Protected Server Component

Protected API Route

Conditional UI Rendering

Complete Permission Reference

Dashboard Access

Sidebar Visibility

Operational Permissions

Adding New Permissions

Best Practices

Related Documentation