Planned splits for files at the 300-line cap and oversized modules (before the next feature forces them) #522

Tier 3: maintainability

Problem

96 source files sit between 250 and 300 lines, and 22 sit between 290 and 300. The cap is doing its job, but the next feature that touches any of these has to split the file under time pressure, and those splits tend to be mechanical rather than along lines of responsibility.

Candidates, with suggested seams

• modules/file_storage/file_storage/service.py (300): split into queries, mutations and visibility.
• modules/permissions/permissions/service.py (299): split registry sync from role CRUD.
• modules/background_tasks/background_tasks/signals.py (297) and module.py (287).
• modules/tenants/tenants/service.py (295).
• modules/users/users/provider.py (291).
• framework/core/simple_module_core/module.py (299). This is mostly hook docstrings. Consider moving the hook reference docs to docs/framework/hooks.md.
• modules/file_storage/file_storage/pages/Browse.tsx (298): move its four inline mutation handlers into useFileActions(). This pairs with the typed API client issue.
• modules/users/users/pages/Users/AddPeople.tsx (298): split by step.
• packages/ui/src/layouts/SidebarLayout.tsx (289): extract sub-sections.

Shared frontend pieces to extract

Each page builds its own submit → error → toast cycle and table shell. Add a useAction({ request, successKey, errorKey }) hook and a DataTable shell to packages/ui.

Oversized modules

• users is about 7.2k source lines: admin, auth_local, OAuth, mailer, demo data, bootstrap, bulk invite, setup steps, session revocation and the token strategy. Moving the mailer out (tenants: invitation emails are never sent (InvitationCreated has no subscriber) #496) is the first cut. Consider splitting OAuth and people-management afterwards.
• For background_tasks, see Design: put the event outbox behind a framework transport protocol instead of inside background_tasks #502.