infrasynth-backend-kit/README.md

InfraSynth Base

Reusable, multi-tenant Django infrastructure kit — the one shared package every InfraSynth app depends on.

pip install -e ".[dev]"          # install the kit + dev tooling
docker compose up -d db redis    # postgres + redis
python manage.py migrate         # create the schema
python manage.py runserver       # http://localhost:8000/api/v1/schema/docs/

Then pytest (single-command test suite), ruff check ., and mypy infrasynth/.

---

What this is

One pip package (infrasynth-base) providing ten Django apps so no app ever reimplements auth, tenancy, entitlements, audit, files, notifications, webhooks, workflows, scheduling, or the API envelope:

Module	Responsibility
infrasynth.shared	Zero-Django primitives: protocols, enums, Result, Fernet crypto, settings helper
infrasynth.api	DRF envelope, camelCase, cursor pagination, request-id, exceptions, throttling, idempotency, webhook hardening
infrasynth.tenancy	Tenant, membership, invitations, platform staff, current_tenant, scoped managers, middleware
infrasynth.security	JWT cookie + API-key auth, roles/grants/revokes, 2FA (TOTP), ALTCHA, login brute-force guard, password policy
infrasynth.audit	Passive create/update/delete tracking, API interaction log, security events, retention purge
infrasynth.features	Operational feature flags with tenant/user/group overrides, rollout %, environment targeting
infrasynth.billing	App catalog, plans, entitlements, subscriptions, invoices, gateways, entitlement lifecycle jobs
infrasynth.files	Storage abstraction (S3/GCS/local/Cloudinary), signed URLs, processing pipelines, pluggable virus scanning
infrasynth.notifications	Multi-channel delivery with failover, retries, rate limits, and log retention
infrasynth.webhooks	Outbound delivery with HMAC + retry, verified inbound processing, event registry
infrasynth.workflows	State-machine engine, voting/approval strategies, validators
infrasynth.scheduler	Celery job dashboard + on-demand execution

Every app is multi-tenant. One deployment, one schema, row-level isolation via a non-null tenant_id, a fail-closed TenantManager, and cross-tenant access that returns 404. See ../TENANCY.md (binding).

There is no license server. Access is an in-process entitlement (is_entitled / check_limit), enforced server-side. See ../ENTITLEMENTS.md (binding).

---

Configuration

Every knob is a namespaced dict with a safe default, read through infrasynth.shared.settings_utils.get_setting:

INFRASYNTH_SECURITY = {"COOKIE_SECURE": True, "IP_BLACKLIST_THRESHOLD": 100}
INFRASYNTH_TENANCY = {"REQUIRE_TENANT_BY_DEFAULT": True, "TENANT_CLAIM": "tenant"}
INFRASYNTH_BILLING = {"GRACE_PERIOD_DAYS": 5, "DEFAULT_CURRENCY": "USD"}
INFRASYNTH_NOTIFICATIONS = {"CHANNELS": {"email": {"primary": "myapp.channels.SlackChannel"}}}

The full, commented reference lives in config/settings/base.py. Real settings files never live in this package — apps supply their own and pin the kit.

---

Extending without forking

Integrate through settings, signals, registries, ABCs, and feature flags — never a local patch:

# myapp/channels.py
from infrasynth.notifications.channels.base import BaseChannel
from infrasynth.shared.results import Result

class SlackChannel(BaseChannel):
    channel_type = "slack"
    def send(self, recipient, subject, body, is_html=True, attachments=None):
        ...
        return Result.ok(True)
    def health_check(self) -> bool:
        return True
    @classmethod
    def from_config(cls, config): return cls(**config)

Registries are populated in apps.py:ready(): FeatureRegistry, EventRegistry, VariableResolverRegistry, DataValidatorRegistry, PipelineStepRegistry.

Extension points, per module

Every module is swappable through settings/registries — no kit edits, no forks:

Module	How a consumer extends it
shared	Use the primitives directly (Result, encrypt/decrypt, get_setting, protocols)
api	Override renderer/pagination/exception handler per view; add idempotency with @idempotent
tenancy	TenantService, scoped managers, tenant_context; configure INFRASYNTH_TENANCY
security	AUTH_BACKEND_CLASS; TWO_FACTOR_SERVICE/TWO_FACTOR_RECOVERY_SERVICE; PasswordPolicyValidator; custom permission classes; infrasynth.gates
audit	EXCLUDED_MODELS/EXCLUDED_FIELDS/SENSITIVE_KEYS/STORE_IN_DB; listen to security_event_occurred
features	FeatureRegistry.register(...) or INFRASYNTH_FEATURES["FLAGS"]; FeatureFlagOverride rows
billing	Gateway via PaymentGateway.gateway_class; INVOICE_PDF_BUILDER; Entitlement/plan
files	register_storage_backend(...) or STORAGE_BACKENDS[name]["CLASS"]; PipelineStepRegistry.register(...); PIPELINE_EXECUTOR; VIRUS_SCANNER
notifications	INFRASYNTH_NOTIFICATIONS["CHANNELS"] dotted paths; VariableResolverRegistry
webhooks	EventRegistry; InboundEndpoint.handler dotted path; signature algorithm setting
workflows	DataValidatorRegistry; node/transition data; WorkflowAwareModel
scheduler	ScheduledTask.task_path dotted path (any Celery task or callable)

A consuming app never imports another app's models directly — it uses the services, registries, signals, and infrasynth.gates documented here.

---

Gating your own endpoints (no kit edits)

infrasynth.gates is the composable, per-endpoint access layer. A view declares exactly what it needs; the default is gate nothing:

from rest_framework.permissions import AllowAny, IsAuthenticated
from infrasynth.gates import (
    GatePermission, gated,
    TwoFactorGate, AltchaGate, EntitlementGate, FeatureGate, PermissionGate,
)

# Public form: proof-of-work, no login.
class SignupView(APIView):
    permission_classes = [AllowAny, GatePermission]
    infrasynth_gates = [AltchaGate()]

# Sensitive action: step-up 2FA + commercial right + codename.
class PayoutView(APIView):
    permission_classes = [IsAuthenticated, GatePermission]
    infrasynth_gates = [
        TwoFactorGate(),                                # passes users without 2FA;
        EntitlementGate("billing", feature="payouts"),  # use require_configured=True to demand setup
        PermissionGate("billing.payout"),
    ]

class TicketViewSet(ModelViewSet):
    permission_classes = [IsAuthenticated, GatePermission]
    infrasynth_gates = [FeatureGate("ticketing")]       # 404 when the flag is off

    @gated(TwoFactorGate())
    @action(detail=True, methods=["post"])
    def close(self, request, pk=None): ...

• Gates run in order; the first denial raises the matching namespaced error (AUTH_*, ENTITLEMENT_*, VALIDATION_*, NOT_FOUND) so the envelope gets the right code and status. No gates declared ⇒ the permission is a no-op.
• GatePermission is in DEFAULT_PERMISSION_CLASSES; the kit's own HybridPermission/IsAuthenticatedAndPermitted also evaluate declared gates, so you only add it explicitly on views that use plain DRF permissions.
• AltchaGate accepts the solution in a JSON altcha object, flat body/query keys, or the X-Altcha: <challenge_id>:<solution>:<number> header; clients get a challenge from /api/v1/auth/altcha/challenge/.
• TwoFactorGate verifies a JWT 2fa claim (minted at verification and carried across workspace selection) or a verified session. Users without 2FA pass by default; require_configured=True denies them with AUTH_2FA_SETUP_REQUIRED.

Every gate is also a plain class implementing check(request, view) -> GateResult, so an app can ship its own (e.g. an IP allow-list) and pass it to @gated(...).

---

Stable import paths

Consumers import from the public modules, never internal helpers:

Need	Import
Gating	from infrasynth.gates import GatePermission, AltchaGate, …
Permissions/auth	from infrasynth.security.permissions import HybridPermission
JWT/API-key auth	from infrasynth.security.auth.cookies import CookieJWTAuthentication
Authorization	from infrasynth.security.services import AuthorizationService
Tenant context/scoping	from infrasynth.tenancy.managers import TenantManager
Entitlements	from infrasynth.billing.entitlements import EntitlementService
Feature flags	from infrasynth.features.services import FeatureService
Storage	from infrasynth.files.storage import get_storage_backend
Errors/envelope	from infrasynth.shared.exceptions import EntitlementError
Wire format	from infrasynth.api.renderers import EnvelopeJSONRenderer

---

Scheduled work

CELERY_BEAT_SCHEDULE ships with the kit: notification retries/log purge, billing sync + lifecycle + renewal invoices, and audit retention. Run celery -A config beat and celery -A config worker.

---

Quality bar

• ruff check + ruff format --check + mypy infrasynth/ are CI gates.
• pytest runs the full suite; coverage is enforced in CI (see pyproject.toml).
• A change to kit behavior belongs here, then consuming apps bump their pin — see ../AGENTS.backend-packages.md §9.