Repository map and agent tooling¶

src/sandloom/
  sdk/         # Public API 1.0: the ONLY framework code a business module and
               # its tests import (plus generated contract stubs and DTOs).
               # Public modules: module, app, migrations, tooling, web, data,
               # tenant, events, effects, contracts, authz, sagas, projections,
               # infra, security, errors, testing. Each declares __all__ and
               # __beginner__; the root sandloom.sdk re-exports the beginner names.
  sdk/_decl/, sdk/_prim/  #   the declarative layer (typed events, @contract,
               #   define_module discovery) and the primitives behind it;
               #   private (leading underscore), never imported by modules
  core/        # framework kernel — touch only for framework work. Never
               # imported by a business module (`sandloom check` SANDLOOM-C002).
               # Internals are grouped into thematic subpackages:
  core/observability/  #   logging, metrics, tracing, guardrails (redaction)
  core/eventing/       #   event_bus, transport, core_events (channel schemas)
  core/http/           #   middlewares, error_handlers, rate_limit
  core/migrations/     #   migration runner (`sandloom migrate`), alembic_support
  core/loader/         #   plugin_loader, service_registry (module wiring)
  core/app_factory.py  #   kernel create_app() (public as sandloom.sdk.app.create_app);
               #   sandloom/main.py only adds every installed sandloom.modules
               #   entry point (the kernel names no module); enforce_configuration:
               #   the boot-time config checks every entry point runs (app,
               #   worker, `sandloom migrate`, the sandloom CLI)
  core/composition.py  #   SANDLOOM_COMPOSITION_ROOT resolution for worker/migrate/CLIs
  core/config/         #   configuration layer (imports nothing above it):
                       #   settings (Settings, one section per domain), tiers,
                       #   accepted_risks
  core/auth/           #   hashing, tokens (JWT), bearer, the subject-state
                       #   record (marks), writers / verification, blocks,
                       #   recovery
  core/cli/            #   `sandloom new`, `sandloom add` (generators and templates),
                       #   `sandloom check`, `sandloom test`, the ops CLIs, gunicorn_conf
  core/archcheck/      #   architecture analyzers behind `sandloom check`
  core/testing/        #   the test harness behind sandloom.sdk.testing (pytest
                       #   plugin, fixtures, UoW test helpers)
  core/sagas/          #   saga runtime (ADR-0008): registry checks, step
                       #   protocol, outcome table, timer sweep, operator ops
  core/worker.py       #   Celery worker/beat entrypoint
  core/infra/  # infrastructure plugin layer: capability contracts, the
               # InfraRegistry, built-in drivers, config — see
               # Capabilities & Infrastructure
  shared/      # cross-module DTOs and generated contract stubs
  identity/    # users, JWT auth, RBAC, 2FA, SSO
  tenancy/     # organizations, membership (owner/admin/member), invitations
  billing/     # plans, subscriptions, credits ledger, Stripe
tests/architecture/_fixtures/  # deliberately-broken example modules
                            # (.py.txt data, NOT importable, never shipped) the
                            # analyzer self-tests scan for positive detection
migrations/core/versions/   # CORE chain: shared infra tables only
                            # (outbox/audit/consumer_inbox/contract_command_log),
                            # applied to every hosting database; shipped in the
                            # wheel as sandloom/core/migrations/core_chain. Each
                            # module owns its OWN chain in
                            # src/sandloom/<module>/migrations/
architecture_rules.yml  # import-boundary manifest (main.py is the
                            # platform composition root and is allowlisted
                            # there; the wiring itself lives in
                            # core/app_factory.py inside the kernel)
public_api_baseline.json  # every public sandloom.sdk name and signature
                            # (a change fails `sandloom test`, SANDLOOM-T008)
deploy/                     # monolith + microservices compose profiles
                            # (deploy/README.md is the deployment reference)
docs/                       # docs site sources; archive/ = legacy and Russian
                            # specs; tutorial-app/ = the generated application
                            # the tutorial and how-tos include code from
admin/                      # platform-owner console (React + Vite)