igny8/master-docs/40-product/PERMISSION-MATRIX.md

Permission Matrix

Purpose

Define which roles can perform which actions across major modules, based on backend permission classes and role checks, so feature teams know the enforced access patterns.

Code Locations (exact paths)

• Roles: backend/igny8_core/auth/models.py (User.role)
• Permission classes: backend/igny8_core/auth/permissions.py (IsOwnerOrAdmin, IsEditorOrAbove, IsViewerOrAbove, AccountPermission)
• Base viewsets: backend/igny8_core/api/base.py (Account/Site/Sector scoping; unified responses)
• Middleware: backend/igny8_core/auth/middleware.py (ensures account context and plan status)
• Frontend guards: frontend/src/App.tsx (ProtectedRoute, ModuleGuard), frontend/src/store/authStore.ts (role in state)

Roles

• developer
• owner
• admin
• editor
• viewer
• system_bot

High-Level Rules (backend)

• Owner/Admin: full CRUD on account resources; pass IsOwnerOrAdmin.
• Editor: edit/create content within account; passes IsEditorOrAbove.
• Viewer: read-only access; passes IsViewerOrAbove.
• AccountPermission: checks authenticated user and role presence; used as base for many endpoints.
• SiteUserAccess: for non-admins, site membership governs visibility in SiteViewSet list.

Module Access (derived from permission classes)

• Auth/Account: team management/settings via owner/admin; viewers can read limited data.
• Planner (keywords/clusters/ideas): editor+ for write; viewer for read (via IsEditorOrAbove on actions).
• Writer (tasks/content/images): editor+ for write (generate/update/delete); viewer for read.
• Automation: editor+ to configure/run/pause/resume; viewer can read status/history where permitted.
• Integration: editor+ to connect/test/sync; viewer can typically read integration status.
• Billing: owner/admin for invoices/payments/payment methods/plan changes; others read balance/usage where exposed.
• System settings: owner/admin for global/account settings; viewer may read select public prompts/strategies if exposed by viewset permissions.

Tenancy Enforcement

• Middleware sets request.account; base viewsets filter by account/site/sector; permissions applied after scoping.
• API key auth (WordPress) sets account from Site.wp_api_key, bypassing user roles for plugin calls but still scoped to site/account.

Execution Flow

• Request → JWT/API key auth → AccountContextMiddleware (account + plan validation) → DRF permission class → queryset filtering by base viewset → action logic.

Error Handling

• Permission denials return unified error response via DRF handler; 403 for insufficient role; 401 for unauthenticated.

Cross-Module Interactions

• Role checks consistent via shared permission classes; modules rely on same IsEditorOrAbove/IsOwnerOrAdmin.
• Frontend ModuleGuard mirrors backend by restricting route access based on authStore.user.role and allowedModules.

How Developers Should Work With This Module

• When adding endpoints, choose the strictest applicable permission (IsOwnerOrAdmin > IsEditorOrAbove > IsViewerOrAbove).
• Keep AccountPermission (auth required) on all tenant resources; avoid anonymous access except intentional public endpoints (e.g., site slug read).
• If creating module-specific roles, extend permission classes centrally to avoid drift between modules.