Skip to content

Latest commit

 

History

History
62 lines (47 loc) · 5.36 KB

index.md

File metadata and controls

62 lines (47 loc) · 5.36 KB

Bundled modules

simple_module_python ships with seventeen first-party modules. Each is a regular Python package — same shape as a module you'd write yourself — registered through the simple_module entry point and discovered at boot. They are independent: install only what you need.

Module Depends on What it provides
auth — Tiny public surface (UserContext, AuthProvider, get_current_user, require_permission) other modules import, plus the provider-agnostic AuthMiddleware and principal-resolver chain. The actual login/session logic lives in an auth-provider module (users, keycloak or oidc).
users auth Email + password auth, OAuth/OIDC (Google, GitHub, Microsoft/Entra ID, generic OIDC), sessions, roles, invites, password reset, email verification, admin UI, mailer backends, smpy users create-admin.
oidc auth (settings optional) Generic OIDC provider: Keycloak via discovery, single-tenant Entra and configurable claims.
keycloak auth, settings Alternative auth provider: Keycloak OIDC single sign-on.
api_tokens auth, users, settings Personal access tokens and service API keys: hashed at rest, scope-capped on every request, revocable on the next request; self-service page and admin screen.
permissions auth, users Role / direct-grant assignment store + admin UI; RequiresPermission dependency that honours both forms.
settings — DB-backed key/value store with system / tenant / user precedence; per-module pydantic settings registration; hot reload; smpy settings CLI.
feature_flags — Runtime feature toggles with system + tenant overrides.
file_storage settings Pluggable file storage (filesystem, S3-compatible) with upload validation, presigned URLs, browse/download/delete UI.
branding settings, file_storage White-labelling — app name, logo (plus a dark-background variant), favicon, primary colour, design pack and announcement banner, pushed to every page via Inertia shared props. Serves the logo and favicon from anonymous routes so guests see the brand too.
background_tasks users Celery + Redis workers, persistent task history, retry, stuck-task sweep, live worker dashboard.
audit_log users Automatic field-level audit trail for SQLModel entities, with an admin UI to browse change history.
dashboard users Authenticated landing page with system overview (user counts, module list, health checks).
tenants auth, settings SaaS organisations: tenants, many-to-many memberships with per-tenant roles, invitations, the membership-validated tenant resolver, and the entitlement/lifecycle seams billing plugs into.
site_lock settings, auth Optional site-wide shared-password gate for staging / pre-launch sites. Off by default.
mail settings Outgoing mail transport: SMTP (aiosmtplib) or a logging console backend, DB-backed settings, live reload, mail.mailer connection check. Other modules send through simple_module_core.mail.
sharing — Optional generic share table for resource-scoped access: grant a user view / edit on one row of another module, with expiry; grant/revoke API and an admin page.

How modules are wired in

Every module declares an entry point in its pyproject.toml:

[project.entry-points.simple_module]
users = "users.module:UsersModule"

At boot, simple_module_core.discovery.discover_modules() loads them, sorts them topologically by ModuleMeta.depends_on, and the host invokes their lifecycle hooks in order — see discovery and lifecycle hooks.

What each page covers

  • ModuleMeta — exact name, route_prefix, view_prefix, depends_on.
  • Routes — REST (/api/...) + Inertia view (/...) endpoints, with the permission each requires.
  • Public contracts — DTOs and protocols other modules import from <module>/contracts/.
  • Models — SQLModel tables the module owns.
  • Settings — DB-backed and bootstrap (SM_*) fields.
  • Permissions / menu / events / tasks / CLI — anything the module registers or exposes.
  • Inertia pages — what's under pages/*.tsx.

If a section isn't applicable to a given module, the page omits it.

Disabling a bundled module

Set SM_MODULES_ENABLED to a comma-separated allow-list; only those modules load. Useful when you don't need (say) background_tasks and don't want to run Redis:

SM_MODULES_ENABLED=users,permissions,settings,dashboard

Don't drop users unless you've replaced authentication with a different module — most other bundled modules rely on it for request.state.user.

Next steps