orion/docs/archive/SESSION_NOTE_2026-02-02_middleware-frontend-detection.md

# Middleware Frontend Detection - Problem Statement

**Date**: 2026-02-02
**Status**: Pending
**Priority**: Medium

---

## Context

During the fix for admin API authentication (where `/api/v1/admin/*` routes returned 401), we identified architectural issues in how the middleware detects frontend context (admin/store/storefront/platform).

The immediate authentication issue was fixed by making `FrontendType` mandatory in `require_module_access()`. However, the middleware still has design issues that should be addressed.

---

## Current State

### Middleware Files Involved
- `middleware/platform_context.py` - Detects platform from host/domain/path
- `middleware/store_context.py` - Detects store from subdomain/domain/path

### Current Detection Logic
```python
# In both PlatformContextManager and StoreContextManager
def is_admin_request(request: Request) -> bool:
    host = request.headers.get("host", "")
    path = request.url.path

    # Production: domain-based
    if host.startswith("admin."):
        return True

    # Development: path-based
    return path.startswith("/admin")
```

### Routing Modes

**Development (localhost, path-based)**:
```
localhost:9999/admin/*           → Admin pages
localhost:9999/api/v1/admin/*    → Admin API
localhost:9999/store/*          → Store pages
localhost:9999/api/v1/store/*   → Store API
localhost:9999/*                 → Platform/storefront
```

**Production (domain/subdomain-based)**:
```
admin.platform.com/*             → Admin (all paths)
store.platform.com/*            → Store portal
shop.mystore.com/*               → Store custom domain
api.platform.com/v1/*            → Shared API domain (?)
platform.com/*                   → Marketing/platform pages
```

---

## Problems Identified

### 1. Incomplete Path Detection for Development Mode

The middleware only checks `/admin` but not `/api/v1/admin/*`:
```python
return path.startswith("/admin")  # Misses /api/v1/admin/*
```

**Impact**: In development, API routes like `/api/v1/admin/messages/unread-count` are not recognized as admin requests, causing incorrect context detection.

**Note**: This doesn't break authentication anymore (fixed via `require_module_access`), but may affect context detection (store/platform context might be incorrectly applied to admin API routes).

### 2. Code Duplication

Same `is_admin_request` logic exists in 3 places:
- `PlatformContextManager.is_admin_request()` (static method)
- `PlatformContextMiddleware._is_admin_request()` (instance method)
- `StoreContextManager.is_admin_request()` (static method)

### 3. Hardcoded Paths

Path patterns are hardcoded in multiple locations:
- Middleware: `/admin`, `/store`
- Routes discovery: `/api/v1/admin`, `/api/v1/store` (in `app/modules/routes.py`)
- API main: `/v1/admin`, `/v1/store` (in `app/api/main.py`)

### 4. No Single Source of Truth

There's no centralized configuration that defines:
- What domains/subdomains map to which frontend
- What path patterns map to which frontend
- Whether we're in dev mode (path-based) or prod mode (domain-based)

### 5. Incomplete Frontend Coverage

Only `is_admin_request()` exists. No equivalent methods for:
- `is_store_request()`
- `is_storefront_request()`
- `is_platform_request()`

### 6. Not Using FrontendType Enum

Middleware returns `bool` instead of using the `FrontendType` enum that exists in `app/modules/enums.py`.

---

## Production Deployment Scenarios to Consider

### Scenario A: Subdomain per Frontend
```
admin.platform.com    → Admin
store.platform.com   → Store portal
*.platform.com        → Store shops (wildcard subdomain)
platform.com          → Marketing site
```

### Scenario B: Shared Domain with Path Routing
```
platform.com/admin/*        → Admin
platform.com/store/*       → Store
platform.com/api/v1/admin/* → Admin API
platform.com/*              → Marketing/storefront
```

### Scenario C: Separate API Domain
```
admin.platform.com/*        → Admin pages
api.platform.com/v1/admin/* → Admin API (different domain!)
```
**Issue**: Host is `api.platform.com`, path is `/v1/admin/*` (no `/api` prefix)

### Scenario D: Multi-Platform (current architecture)
```
oms.platform.com/*          → OMS platform
loyalty.platform.com/*      → Loyalty platform
admin.platform.com/*        → Global admin for all platforms
```

---

## Proposed Solution Options

### Option A: Centralized FrontendDetector

Create a single utility class that handles all frontend detection:

```python
# app/core/frontend_detector.py
from app.core.config import settings
from app.modules.enums import FrontendType

class FrontendDetector:
    """Centralized frontend detection for both dev and prod modes."""

    # Configurable patterns
    ADMIN_SUBDOMAINS = ["admin"]
    STORE_SUBDOMAINS = ["store", "portal"]

    @classmethod
    def detect(cls, host: str, path: str) -> FrontendType | None:
        """
        Detect frontend type from request host and path.

        Priority:
        1. Domain/subdomain check (production)
        2. Path prefix check (development)
        """
        host_without_port = host.split(":")[0] if ":" in host else host

        # Production: subdomain-based
        subdomain = cls._get_subdomain(host_without_port)
        if subdomain:
            if subdomain in cls.ADMIN_SUBDOMAINS:
                return FrontendType.ADMIN
            if subdomain in cls.STORE_SUBDOMAINS:
                return FrontendType.STORE

        # Development: path-based
        return cls._detect_from_path(path)

    @classmethod
    def _detect_from_path(cls, path: str) -> FrontendType | None:
        # Check both page routes and API routes
        admin_patterns = ["/admin", f"{settings.API_PREFIX}/admin"]
        store_patterns = ["/store", f"{settings.API_PREFIX}/store"]
        storefront_patterns = [f"{settings.API_PREFIX}/storefront"]
        platform_patterns = [f"{settings.API_PREFIX}/platform"]

        for pattern in admin_patterns:
            if path.startswith(pattern):
                return FrontendType.ADMIN
        # ... etc
```

### Option B: Configuration-Driven Detection

Define all patterns in settings:

```python
# app/core/config.py
class Settings:
    API_PREFIX: str = "/api/v1"

    FRONTEND_DETECTION = {
        FrontendType.ADMIN: {
            "subdomains": ["admin"],
            "path_prefixes": ["/admin"],  # API prefix added automatically
        },
        FrontendType.STORE: {
            "subdomains": ["store", "portal"],
            "path_prefixes": ["/store"],
        },
        # ...
    }
```

### Option C: Route-Level State Setting

Have the router set `request.state.frontend_type` when the route matches, eliminating detection entirely:

```python
# In route discovery or middleware
@app.middleware("http")
async def set_frontend_type(request: Request, call_next):
    # Determine from matched route's tags or prefix
    if request.scope.get("route"):
        route = request.scope["route"]
        if "admin" in route.tags:
            request.state.frontend_type = FrontendType.ADMIN
    return await call_next(request)
```

---

## Questions to Answer Before Implementation

1. **What's the production deployment model?**
   - Subdomains per frontend?
   - Separate API domain?
   - Path-based on shared domain?

2. **Should detection be configurable?**
   - Environment-specific patterns?
   - Runtime configuration vs build-time?

3. **What does the middleware actually need?**
   - `PlatformContextMiddleware`: Needs to know "is this NOT a platform-specific request?"
   - `StoreContextMiddleware`: Needs to know "should I detect store context?"
   - Maybe they just need `is_global_admin_request()` not full frontend detection

4. **API domain considerations?**
   - Will API be on separate domain in production?
   - If so, what's the path structure (`/v1/admin` vs `/api/v1/admin`)?

---

## Files to Modify (when implementing)

- `app/core/config.py` - Add centralized path/domain configuration
- `app/core/frontend_detector.py` - New centralized detection utility
- `middleware/platform_context.py` - Use centralized detector
- `middleware/store_context.py` - Use centralized detector
- `app/modules/routes.py` - Use centralized path configuration

---

## Related Commits

- `9a0dd84` - fix: make FrontendType mandatory in require_module_access
- `01e7602` - fix: add missing db argument to get_admin_context calls

---

## Next Steps

1. Answer the deployment model questions above
2. Choose solution option (A, B, or C)
3. Implement centralized detection
4. Update middleware to use centralized detection
5. Add tests for both dev and prod modes