# 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.