orion/docs/proposals/plan-perms.md

Plan: Flexible Role & Permission Management with Platform Controls

Status: READY FOR APPROVAL

Summary

Design a flexible role/permission management system that:

1. Modules define permissions - Each module declares its available permissions
2. Platforms control availability - Platforms can restrict which permissions stores can use
3. Stores customize roles - Stores create custom roles within platform constraints
4. Multi-tier hierarchy - Platform → Store → User permission inheritance

---

Current State Analysis

What Exists Today

Component	Location	Description
Role Model	app/modules/tenancy/models/store.py	store_id, name, permissions (JSON array)
StoreUser Model	Same file	Links user → store with role_id
PermissionDiscoveryService	app/modules/tenancy/services/permission_discovery_service.py	Discovers permissions from modules
StoreTeamService	app/modules/tenancy/services/store_team_service.py	Manages team invitations, role assignment
Role Presets	In discovery service code	Hardcoded ROLE_PRESETS dict
Platform Model	models/database/platform.py	Multi-platform support
PlatformModule	models/database/platform_module.py	Controls which modules are enabled per platform
StorePlatform	models/database/store_platform.py	Store-platform relationship with tier_id

Current Gaps

1. No platform-level permission control - Platforms cannot restrict which permissions stores can assign
2. No custom role CRUD API - Roles are created implicitly when inviting team members
3. Presets are code-only - Cannot customize role templates per platform
4. No role templates table - Platform admins cannot define default roles for their stores

---

Proposed Architecture

Tier 1: Module-Defined Permissions (Exists)

Each module declares permissions in definition.py:

permissions=[
    PermissionDefinition(
        id="products.view",
        label_key="catalog.permissions.products_view",
        category="products",
    ),
    PermissionDefinition(
        id="products.create",
        label_key="catalog.permissions.products_create",
        category="products",
    ),
]

Discovery Service aggregates all permissions at runtime.

Tier 2: Platform Permission Control (New)

New PlatformPermissionConfig model to control:

• Which permissions are available to stores on this platform
• Default role templates for store onboarding
• Permission bundles based on subscription tier

┌─────────────────────────────────────────────────────────────────┐
│                         PLATFORM                                │
│  ┌─────────────────────────────────────────────────────────┐   │
│  │ PlatformPermissionConfig                                 │   │
│  │  - platform_id                                           │   │
│  │  - allowed_permissions: ["products.*", "orders.*"]       │   │
│  │  - blocked_permissions: ["team.manage"]                  │   │
│  │  - tier_restrictions: {free: [...], pro: [...]}          │   │
│  └─────────────────────────────────────────────────────────┘   │
│                                                                 │
│  ┌─────────────────────────────────────────────────────────┐   │
│  │ PlatformRoleTemplate                                     │   │
│  │  - platform_id                                           │   │
│  │  - name: "Manager", "Staff", etc.                        │   │
│  │  - permissions: [...]                                    │   │
│  │  - is_default: bool (create for new stores)             │   │
│  └─────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────┘

Tier 3: Store Role Customization (Enhanced)

Stores can:

• View roles available (from platform templates or custom)
• Create custom roles (within platform constraints)
• Edit role permissions (within allowed set)
• Assign roles to team members

┌─────────────────────────────────────────────────────────────────┐
│                          STORE                                 │
│  ┌─────────────────────────────────────────────────────────┐   │
│  │ Role (existing model, enhanced)                          │   │
│  │  - store_id                                             │   │
│  │  - name                                                  │   │
│  │  - permissions: [...] (validated against platform)       │   │
│  │  - is_from_template: bool                                │   │
│  │  - source_template_id: FK (nullable)                     │   │
│  └─────────────────────────────────────────────────────────┘   │
│                                                                 │
│  ┌─────────────────────────────────────────────────────────┐   │
│  │ StoreUser (existing, unchanged)                         │   │
│  │  - user_id                                               │   │
│  │  - store_id                                             │   │
│  │  - role_id                                               │   │
│  └─────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────┘

---

Data Model Changes

New Models

1. PlatformPermissionConfig

# app/modules/tenancy/models/platform_permission_config.py

class PlatformPermissionConfig(Base):
    """Platform-level permission configuration"""
    __tablename__ = "platform_permission_configs"

    id: Mapped[int] = mapped_column(primary_key=True)
    platform_id: Mapped[int] = mapped_column(ForeignKey("platforms.id"), unique=True)

    # Permissions this platform allows stores to use
    # Empty = all discovered permissions allowed
    allowed_permissions: Mapped[list[str]] = mapped_column(JSON, default=list)

    # Explicit blocklist (takes precedence over allowed)
    blocked_permissions: Mapped[list[str]] = mapped_column(JSON, default=list)

    # Tier-based restrictions: {"free": ["products.view"], "pro": ["products.*"]}
    tier_permissions: Mapped[dict] = mapped_column(JSON, default=dict)

    created_at: Mapped[datetime] = mapped_column(default=func.now())
    updated_at: Mapped[datetime] = mapped_column(onupdate=func.now())

    # Relationships
    platform: Mapped["Platform"] = relationship(back_populates="permission_config")

2. PlatformRoleTemplate

# app/modules/tenancy/models/platform_role_template.py

class PlatformRoleTemplate(Base):
    """Role templates defined at platform level"""
    __tablename__ = "platform_role_templates"

    id: Mapped[int] = mapped_column(primary_key=True)
    platform_id: Mapped[int] = mapped_column(ForeignKey("platforms.id"))

    name: Mapped[str] = mapped_column(String(50))  # "Manager", "Staff", etc.
    display_name: Mapped[str] = mapped_column(String(100))  # i18n key or display name
    description: Mapped[str | None] = mapped_column(String(255))

    # Permissions for this template
    permissions: Mapped[list[str]] = mapped_column(JSON, default=list)

    # Configuration
    is_default: Mapped[bool] = mapped_column(default=False)  # Auto-create for new stores
    is_system: Mapped[bool] = mapped_column(default=False)  # Cannot be deleted
    order: Mapped[int] = mapped_column(default=100)  # Display order

    created_at: Mapped[datetime] = mapped_column(default=func.now())
    updated_at: Mapped[datetime] = mapped_column(onupdate=func.now())

    # Relationships
    platform: Mapped["Platform"] = relationship(back_populates="role_templates")

    __table_args__ = (
        UniqueConstraint("platform_id", "name", name="uq_platform_role_template"),
    )

Enhanced Existing Models

Role Model Enhancement

# Add to existing Role model in app/modules/tenancy/models/store.py

class Role(Base):
    # ... existing fields ...

    # NEW: Track template origin
    source_template_id: Mapped[int | None] = mapped_column(
        ForeignKey("platform_role_templates.id"),
        nullable=True
    )
    is_custom: Mapped[bool] = mapped_column(default=False)  # Store-created custom role

    # Relationship
    source_template: Mapped["PlatformRoleTemplate"] = relationship()

---

Service Layer Changes

1. PlatformPermissionService (New)

# app/modules/tenancy/services/platform_permission_service.py

class PlatformPermissionService:
    """Manages platform-level permission configuration"""

    def get_allowed_permissions(
        self,
        db: Session,
        platform_id: int,
        tier_id: int | None = None
    ) -> set[str]:
        """
        Get permissions allowed for a platform/tier combination.

        1. Start with all discovered permissions
        2. Filter by platform's allowed_permissions (if set)
        3. Remove blocked_permissions
        4. Apply tier restrictions (if tier_id provided)
        """
        pass

    def validate_permissions(
        self,
        db: Session,
        platform_id: int,
        tier_id: int | None,
        permissions: list[str]
    ) -> tuple[list[str], list[str]]:
        """
        Validate permissions against platform constraints.
        Returns (valid_permissions, invalid_permissions)
        """
        pass

    def update_platform_config(
        self,
        db: Session,
        platform_id: int,
        allowed_permissions: list[str] | None = None,
        blocked_permissions: list[str] | None = None,
        tier_permissions: dict | None = None
    ) -> PlatformPermissionConfig:
        """Update platform permission configuration"""
        pass

2. PlatformRoleTemplateService (New)

# app/modules/tenancy/services/platform_role_template_service.py

class PlatformRoleTemplateService:
    """Manages platform role templates"""

    def get_templates(self, db: Session, platform_id: int) -> list[PlatformRoleTemplate]:
        """Get all role templates for a platform"""
        pass

    def create_template(
        self,
        db: Session,
        platform_id: int,
        name: str,
        permissions: list[str],
        is_default: bool = False
    ) -> PlatformRoleTemplate:
        """Create a new role template (validates permissions)"""
        pass

    def create_default_roles_for_store(
        self,
        db: Session,
        store: Store
    ) -> list[Role]:
        """
        Create store roles from platform's default templates.
        Called during store onboarding.
        """
        pass

    def seed_default_templates(self, db: Session, platform_id: int):
        """Seed platform with standard role templates (Manager, Staff, etc.)"""
        pass

3. Enhanced StoreTeamService

# Updates to app/modules/tenancy/services/store_team_service.py

class StoreTeamService:

    def get_available_permissions(
        self,
        db: Session,
        store: Store
    ) -> list[PermissionDefinition]:
        """
        Get permissions available to this store based on:
        1. Platform constraints
        2. Store's subscription tier
        """
        platform_perm_service = PlatformPermissionService()
        store_platform = db.query(StorePlatform).filter(...).first()

        allowed = platform_perm_service.get_allowed_permissions(
            db,
            store_platform.platform_id,
            store_platform.tier_id
        )

        # Return PermissionDefinitions filtered to allowed set
        all_perms = permission_discovery_service.get_all_permissions()
        return [p for p in all_perms if p.id in allowed]

    def create_custom_role(
        self,
        db: Session,
        store: Store,
        name: str,
        permissions: list[str]
    ) -> Role:
        """
        Create a custom role for the store.
        Validates permissions against platform constraints.
        """
        # Validate permissions
        valid, invalid = self.platform_permission_service.validate_permissions(
            db, store.platform_id, store.tier_id, permissions
        )
        if invalid:
            raise InvalidPermissionsException(invalid)

        role = Role(
            store_id=store.id,
            name=name,
            permissions=valid,
            is_custom=True
        )
        db.add(role)
        return role

    def update_role(
        self,
        db: Session,
        store: Store,
        role_id: int,
        name: str | None = None,
        permissions: list[str] | None = None
    ) -> Role:
        """Update an existing role (validates permissions)"""
        pass

    def delete_role(
        self,
        db: Session,
        store: Store,
        role_id: int
    ) -> bool:
        """Delete a custom role (cannot delete if in use)"""
        pass

---

API Endpoints

Platform Admin Endpoints (Admin Panel)

# app/modules/tenancy/routes/admin/platform_permissions.py

@router.get("/platforms/{platform_id}/permissions")
def get_platform_permission_config(platform_id: int):
    """Get platform permission configuration"""

@router.put("/platforms/{platform_id}/permissions")
def update_platform_permission_config(platform_id: int, config: PermissionConfigUpdate):
    """Update platform permission configuration"""

@router.get("/platforms/{platform_id}/role-templates")
def list_role_templates(platform_id: int):
    """List role templates for a platform"""

@router.post("/platforms/{platform_id}/role-templates")
def create_role_template(platform_id: int, template: RoleTemplateCreate):
    """Create a new role template"""

@router.put("/platforms/{platform_id}/role-templates/{template_id}")
def update_role_template(platform_id: int, template_id: int, template: RoleTemplateUpdate):
    """Update a role template"""

@router.delete("/platforms/{platform_id}/role-templates/{template_id}")
def delete_role_template(platform_id: int, template_id: int):
    """Delete a role template"""

Store Dashboard Endpoints

# app/modules/tenancy/routes/api/store_roles.py

@router.get("/roles")
def list_store_roles():
    """List all roles for current store"""

@router.post("/roles")
def create_custom_role(role: RoleCreate):
    """Create a custom role (validates permissions against platform)"""

@router.put("/roles/{role_id}")
def update_role(role_id: int, role: RoleUpdate):
    """Update a role"""

@router.delete("/roles/{role_id}")
def delete_role(role_id: int):
    """Delete a custom role"""

@router.get("/available-permissions")
def get_available_permissions():
    """Get permissions available to this store (filtered by platform/tier)"""

---

Permission Flow Diagram

┌─────────────────────────────────────────────────────────────────────────────┐
│                           PERMISSION FLOW                                    │
└─────────────────────────────────────────────────────────────────────────────┘

1. MODULE DEFINES PERMISSIONS
   ┌──────────────┐
   │ catalog      │ → products.view, products.create, products.edit, ...
   │ orders       │ → orders.view, orders.manage, orders.refund, ...
   │ team         │ → team.view, team.manage, team.invite, ...
   └──────────────┘
           ↓

2. DISCOVERY SERVICE AGGREGATES
   ┌────────────────────────────────────────────────┐
   │ PermissionDiscoveryService                      │
   │  get_all_permissions() → 50+ permissions       │
   └────────────────────────────────────────────────┘
           ↓

3. PLATFORM FILTERS PERMISSIONS
   ┌────────────────────────────────────────────────┐
   │ PlatformPermissionConfig                        │
   │  allowed: ["products.*", "orders.view"]        │
   │  blocked: ["orders.refund"]                    │
   │  tier_permissions:                              │
   │    free: ["products.view", "orders.view"]      │
   │    pro: ["products.*", "orders.*"]             │
   └────────────────────────────────────────────────┘
           ↓

4. STORE CREATES/USES ROLES
   ┌────────────────────────────────────────────────┐
   │ Role (store-specific)                          │
   │  Manager: [products.*, orders.view]            │
   │  Staff:   [products.view, orders.view]         │
   └────────────────────────────────────────────────┘
           ↓

5. USER GETS PERMISSIONS VIA ROLE
   ┌────────────────────────────────────────────────┐
   │ StoreUser                                      │
   │  user_id: 123                                  │
   │  role_id: 5 (Staff)                            │
   │  → permissions: [products.view, orders.view]  │
   └────────────────────────────────────────────────┘

---

Database Migrations

Migration 1: Add Platform Permission Config

CREATE TABLE platform_permission_configs (
    id SERIAL PRIMARY KEY,
    platform_id INTEGER NOT NULL UNIQUE REFERENCES platforms(id),
    allowed_permissions JSONB DEFAULT '[]',
    blocked_permissions JSONB DEFAULT '[]',
    tier_permissions JSONB DEFAULT '{}',
    created_at TIMESTAMP DEFAULT NOW(),
    updated_at TIMESTAMP
);

Migration 2: Add Platform Role Templates

CREATE TABLE platform_role_templates (
    id SERIAL PRIMARY KEY,
    platform_id INTEGER NOT NULL REFERENCES platforms(id),
    name VARCHAR(50) NOT NULL,
    display_name VARCHAR(100) NOT NULL,
    description VARCHAR(255),
    permissions JSONB DEFAULT '[]',
    is_default BOOLEAN DEFAULT FALSE,
    is_system BOOLEAN DEFAULT FALSE,
    "order" INTEGER DEFAULT 100,
    created_at TIMESTAMP DEFAULT NOW(),
    updated_at TIMESTAMP,
    UNIQUE (platform_id, name)
);

Migration 3: Enhance Roles Table

ALTER TABLE roles
ADD COLUMN source_template_id INTEGER REFERENCES platform_role_templates(id),
ADD COLUMN is_custom BOOLEAN DEFAULT FALSE;

---

Implementation Phases

Phase 1: Data Models (Foundation)

Files to create:

• app/modules/tenancy/models/platform_permission_config.py
• app/modules/tenancy/models/platform_role_template.py
• migrations/versions/xxx_add_platform_permission_tables.py
• migrations/versions/xxx_enhance_roles_table.py

Files to modify:

• app/modules/tenancy/models/__init__.py - Export new models
• app/modules/tenancy/models/store.py - Add Role enhancement

Phase 2: Service Layer

Files to create:

• app/modules/tenancy/services/platform_permission_service.py
• app/modules/tenancy/services/platform_role_template_service.py

Files to modify:

• app/modules/tenancy/services/store_team_service.py - Add role CRUD, permission validation

Phase 3: API Endpoints

Files to create:

• app/modules/tenancy/routes/admin/platform_permissions.py
• app/modules/tenancy/routes/api/store_roles.py
• app/modules/tenancy/schemas/platform_permissions.py
• app/modules/tenancy/schemas/roles.py

Files to modify:

• app/modules/tenancy/routes/__init__.py - Register new routers

Phase 4: Store Onboarding Integration

Files to modify:

• app/modules/tenancy/services/store_service.py - Create default roles from templates during store creation

Phase 5: Admin UI (Optional, Future)

Files to create/modify:

• Admin panel for platform permission configuration
• Admin panel for role template management
• Store dashboard for custom role management

---

Verification

1. App loads: python -c "from main import app; print('OK')"

2. Migrations run: make migrate-up

3. Architecture validation: python scripts/validate/validate_architecture.py -v

4. Unit tests: Test permission filtering logic

   • Platform with no config → all permissions allowed
   • Platform with allowed list → only those permissions
   • Platform with blocked list → all except blocked
   • Tier restrictions → correct subset per tier

5. Integration tests:

   • Create store → gets default roles from platform templates
   • Create custom role → validates against platform constraints
   • Assign role → user gets correct permissions
   • Change tier → available permissions update

6. API tests:

   • Platform admin can configure permissions
   • Store owner can create/edit custom roles
   • Invalid permissions are rejected

---

Files Summary

New Files (9)

File	Purpose
app/modules/tenancy/models/platform_permission_config.py	Platform permission config model
app/modules/tenancy/models/platform_role_template.py	Platform role template model
app/modules/tenancy/services/platform_permission_service.py	Platform permission logic
app/modules/tenancy/services/platform_role_template_service.py	Role template logic
app/modules/tenancy/routes/admin/platform_permissions.py	Admin API endpoints
app/modules/tenancy/routes/api/store_roles.py	Store API endpoints
app/modules/tenancy/schemas/platform_permissions.py	Pydantic schemas
app/modules/tenancy/schemas/roles.py	Role schemas
migrations/versions/xxx_platform_permission_tables.py	Database migration

Modified Files (5)

File	Changes
app/modules/tenancy/models/__init__.py	Export new models
app/modules/tenancy/models/store.py	Enhance Role model
app/modules/tenancy/services/store_team_service.py	Add role CRUD, validation
app/modules/tenancy/services/store_service.py	Create default roles on store creation
app/modules/tenancy/routes/__init__.py	Register new routers

---

Key Design Decisions

1. Wildcard support in permissions - products.* matches products.view, products.create, etc.

2. Tier inheritance - Higher tiers include all permissions of lower tiers

3. Template-based store roles - Default roles created from platform templates, but store can customize

4. Soft validation - Invalid permissions in existing roles are not automatically removed (audit trail)

5. Backward compatible - Existing roles without source_template_id continue to work