Add generic plugin architecture and watch-directory feature

Introduces a manifest contract so feature containers self-describe their
settings (JSON Schema + access rules). Backend and frontend gain generic
plugin proxy and dynamic Extensions UI with zero feature-specific code.

Doc-service is the first plugin consumer: exposes /plugin/manifest and
/plugin/settings, adds a watchdog-based file watcher that auto-ingests
PDFs from a mounted directory, maps subfolders to categories, supports
AI-suggested folder/filename (user-confirmed), and enforces a no-remove
policy. Access is gated by is_superuser or doc-service-admin group.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

backend/app/deps.py

@@ -43,3 +43,44 @@ async def get_current_admin(
             detail="Not found",
         )
     return current_user
+
+
+async def check_plugin_access(
+    plugin_id: str,
+    current_user: User,
+    db: AsyncSession,
+) -> bool:
+    """
+    Return True if the user may access the given plugin's settings.
+
+    Access is granted when any of these conditions holds:
+      1. The user is a superuser AND the manifest allows superuser access.
+      2. The user is a member of one of the groups listed in manifest.access.required_groups.
+
+    Returns False (not raises) so callers can decide how to respond.
+    """
+    from app.models.group import Group, GroupMembership
+    from app.services.service_health import get_cached_manifest
+
+    manifest = get_cached_manifest(plugin_id)
+    if manifest is None:
+        return False
+
+    access = manifest.get("access", {})
+
+    if current_user.is_superuser and access.get("allow_superuser", True):
+        return True
+
+    for group_name in access.get("required_groups", []):
+        result = await db.execute(
+            select(GroupMembership)
+            .join(Group, Group.id == GroupMembership.group_id)
+            .where(
+                Group.name == group_name,
+                GroupMembership.user_id == current_user.id,
+            )
+        )
+        if result.scalar_one_or_none() is not None:
+            return True
+
+    return False

backend/app/main.py

@@ -6,7 +6,7 @@ from fastapi.middleware.cors import CORSMiddleware
 
 from app.core.app_config import seed_builtin_themes
 from app.core.config import settings
-from app.routers import admin, auth, categories_proxy, documents_proxy, groups, profile, services, users
+from app.routers import admin, auth, categories_proxy, documents_proxy, groups, plugins, profile, services, users
 from app.routers import settings as settings_router
 from app.services.service_health import check_all, health_check_loop, register_services
 
@@ -46,6 +46,7 @@ app.include_router(admin.router, prefix="/api/admin", tags=["admin"])
 app.include_router(groups.router, prefix="/api/admin/groups", tags=["admin"])
 app.include_router(settings_router.router, prefix="/api/settings", tags=["settings"])
 app.include_router(services.router, prefix="/api/services", tags=["services"])
+app.include_router(plugins.router, prefix="/api/plugins", tags=["plugins"])
 # categories_proxy MUST be registered before documents_proxy —
 # otherwise /api/documents/{path:path} swallows /api/documents/categories/*
 app.include_router(

backend/app/routers/plugins.py

@@ -0,0 +1,125 @@
+"""
+Generic plugin proxy.
+
+Feature containers advertise themselves via GET /plugin/manifest.  The backend
+health-poller caches those manifests.  This router exposes them to the browser
+through auth-gated endpoints so the frontend never needs to know about specific
+features.
+
+Routes:
+  GET  /api/plugins                    → list accessible plugins for current user
+  GET  /api/plugins/{id}/manifest      → cached manifest (404 if not accessible)
+  GET  /api/plugins/{id}/settings      → proxy to feature /plugin/settings
+  PATCH /api/plugins/{id}/settings     → proxy to feature /plugin/settings
+"""
+import httpx
+from fastapi import APIRouter, Depends, HTTPException, Request
+from fastapi.responses import Response
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.database import get_db
+from app.deps import check_plugin_access, get_current_user
+from app.models.user import User
+from app.services.service_health import _REGISTRY, get_cached_manifest, get_service_url
+
+router = APIRouter()
+
+_HOP_BY_HOP = frozenset([
+    "connection",
+    "keep-alive",
+    "proxy-authenticate",
+    "proxy-authorization",
+    "te",
+    "trailers",
+    "transfer-encoding",
+    "upgrade",
+    "host",
+    "accept-encoding",
+])
+_STRIP_RESPONSE = frozenset([*_HOP_BY_HOP, "content-length", "content-type"])
+
+
+async def _proxy(plugin_id: str, method: str, path: str, body: bytes | None,
+                 content_type: str | None = None) -> Response:
+    """Forward a request to the feature container's plugin endpoint."""
+    url = get_service_url(plugin_id)
+    if url is None:
+        raise HTTPException(status_code=404, detail="Not found")
+
+    headers: dict[str, str] = {}
+    if content_type:
+        headers["content-type"] = content_type
+
+    try:
+        async with httpx.AsyncClient(base_url=url, timeout=30.0) as client:
+            resp = await client.request(method, path, content=body, headers=headers)
+    except httpx.RequestError as exc:
+        raise HTTPException(status_code=502, detail=f"Plugin service unreachable: {exc}")
+
+    resp_headers = {k: v for k, v in resp.headers.items() if k.lower() not in _STRIP_RESPONSE}
+    return Response(
+        content=resp.content,
+        status_code=resp.status_code,
+        headers=resp_headers,
+        media_type=resp.headers.get("content-type", "application/json"),
+    )
+
+
+@router.get("")
+async def list_plugins(
+    current_user: User = Depends(get_current_user),
+    db: AsyncSession = Depends(get_db),
+) -> list[dict]:
+    """Return the list of plugins the current user may access."""
+    accessible = []
+    for svc in _REGISTRY:
+        manifest = get_cached_manifest(svc.id)
+        if manifest is None:
+            continue
+        if await check_plugin_access(svc.id, current_user, db):
+            accessible.append({
+                "id": manifest["id"],
+                "name": manifest["name"],
+                "icon": manifest.get("icon", "package"),
+                "version": manifest.get("version", ""),
+            })
+    return accessible
+
+
+@router.get("/{plugin_id}/manifest")
+async def get_plugin_manifest(
+    plugin_id: str,
+    current_user: User = Depends(get_current_user),
+    db: AsyncSession = Depends(get_db),
+) -> dict:
+    if not await check_plugin_access(plugin_id, current_user, db):
+        raise HTTPException(status_code=404, detail="Not found")
+    manifest = get_cached_manifest(plugin_id)
+    if manifest is None:
+        raise HTTPException(status_code=404, detail="Not found")
+    return manifest
+
+
+@router.get("/{plugin_id}/settings")
+async def get_plugin_settings(
+    plugin_id: str,
+    current_user: User = Depends(get_current_user),
+    db: AsyncSession = Depends(get_db),
+) -> Response:
+    if not await check_plugin_access(plugin_id, current_user, db):
+        raise HTTPException(status_code=404, detail="Not found")
+    return await _proxy(plugin_id, "GET", "/plugin/settings", None)
+
+
+@router.patch("/{plugin_id}/settings")
+async def update_plugin_settings(
+    plugin_id: str,
+    request: Request,
+    current_user: User = Depends(get_current_user),
+    db: AsyncSession = Depends(get_db),
+) -> Response:
+    if not await check_plugin_access(plugin_id, current_user, db):
+        raise HTTPException(status_code=404, detail="Not found")
+    body = await request.body()
+    content_type = request.headers.get("content-type", "application/json")
+    return await _proxy(plugin_id, "PATCH", "/plugin/settings", body, content_type)

backend/app/services/service_health.py

@@ -2,8 +2,9 @@
 Background health-checker for registered feature services.
 
 Polls each service's /health endpoint every POLL_INTERVAL seconds and stores
-the result in an in-memory dict.  The REST layer reads from that dict — no DB,
-no blocking calls on the request path.
+the result in an in-memory dict.  Also fetches /plugin/manifest when available
+and caches it so the plugin proxy can serve it without per-request network calls.
+The REST layer reads from that dict — no DB, no blocking calls on the request path.
 """
 import asyncio
 import logging
@@ -35,10 +36,13 @@ _REGISTRY: list[ServiceDefinition] = []
 # id → True/False/None (None = not yet checked)
 _health: dict[str, bool | None] = {}
 
+# id → plugin manifest dict, or None if the service has no plugin manifest
+_manifests: dict[str, dict | None] = {}
+
 
 def register_services(doc_service_url: str, ai_service_url: str) -> None:
     """Called once during app startup to populate the registry from config."""
-    global _REGISTRY, _health
+    global _REGISTRY, _health, _manifests
 
     _REGISTRY = [
         ServiceDefinition(
@@ -62,6 +66,7 @@ def register_services(doc_service_url: str, ai_service_url: str) -> None:
     ]
 
     _health = {svc.id: None for svc in _REGISTRY}
+    _manifests = {svc.id: None for svc in _REGISTRY}
     logger.info("Service registry initialised with %d services", len(_REGISTRY))
 
 
@@ -88,6 +93,25 @@ async def _check_service(svc: ServiceDefinition) -> None:
         else:
             logger.warning("Service %s is now UNHEALTHY", svc.id)
 
+    # Opportunistically fetch plugin manifest when the service is healthy
+    if healthy:
+        await _fetch_manifest(svc)
+
+
+async def _fetch_manifest(svc: ServiceDefinition) -> None:
+    """Try to GET /plugin/manifest from the service; cache result (or None)."""
+    url = f"{svc.internal_url}/plugin/manifest"
+    try:
+        async with httpx.AsyncClient(timeout=5.0) as client:
+            resp = await client.get(url)
+        if resp.status_code == 200:
+            _manifests[svc.id] = resp.json()
+        else:
+            _manifests[svc.id] = None
+    except Exception:
+        # Service doesn't have a plugin manifest — not an error
+        _manifests[svc.id] = None
+
 
 async def check_all() -> None:
     """Run health checks for all registered services concurrently."""
@@ -125,3 +149,16 @@ def get_all_statuses() -> list[dict]:
         }
         for svc in _REGISTRY
     ]
+
+
+def get_cached_manifest(service_id: str) -> dict | None:
+    """Return the cached plugin manifest for a service, or None if unavailable."""
+    return _manifests.get(service_id)
+
+
+def get_service_url(service_id: str) -> str | None:
+    """Return the internal URL for a registered service, or None if unknown."""
+    for svc in _REGISTRY:
+        if svc.id == service_id:
+            return svc.internal_url
+    return None