B2B SaaS applications

Define membership and creation together

Organization configuration lives in the application’s backend configuration. This selected Wonder Todos example defines a workspace organization type. Other organization options, including directory provisioning, are omitted.

organizationTypes: {
  workspace: {
    userTypes: ['member'],
    availableOrgRoles: [
      CORE_ORG_ROLES.ORG_OWNER,
      CORE_ORG_ROLES.ORG_ADMIN,
      CORE_ORG_ROLES.ORG_MEMBER,
    ],
    defaultMemberRole: CORE_ORG_ROLES.ORG_MEMBER,
    authOverrides: undefined,
    creationPolicy: {
      createOnUserTypeRegistration: ['member'],
      orgNameSource: OrganizationNameSource.ASK,
      defaultOwnerRole: CORE_ORG_ROLES.ORG_OWNER,
    },
  },
},

The member user type is declared elsewhere in the same application. Registration for that type creates a workspace under this policy, asks for its name and gives the creator the owner role. defaultMemberRole separately describes ordinary membership; it does not make every subsequent member an owner.

This configuration belongs alongside the application’s selected organization and identity mechanisms. It describes a configured customer model, not a rule that every Wildo application must use organizations.

Carry the boundary into business resources

An organization type does not, by itself, partition every custom table or endpoint. Declare the primary scope and relationships of customer-owned resources, then configure the permitted roles and contextual access for their operations. A custom implementation must preserve the same execution context when it reads or writes data.

User identity and customer membership are separate: a person can participate in different contexts without those contexts becoming interchangeable. Likewise, an application-wide resource is not automatically a customer-owned record.

Make onboarding agree with the model

Use the declared registration and invitation paths, with the relevant authentication configuration and message provider. The UI should carry the active workspace into navigation and related-record choices; the server must independently check the request context. Changing the visible workspace is not an authorization grant.

For an acceptance scenario, create two organizations with their own records. Test an owner, an ordinary member and a person outside the organization. Check list, detail, mutation and custom-action requests, then repeat after a membership is removed. This tests the customer boundary as people actually use it.

Read users, organizations and security for the mechanisms behind identity and scoped access.

Give a business action its own contract

An action can narrow an existing operation or add new business processing. Naming it does not automatically require a new persistence implementation.

For example, Wonder Todos’ ASSIGN_LEAD action reuses an update while restricting the input and the eligible assignee. This is a selected entry from the resource’s operation map; imports and surrounding resource declarations are omitted.

[Todos_Operations.ASSIGN_LEAD]: {
  variants: [{
    variantType: ResourceOperationVariantType.API_CALL,
    isDefault: true,
    roles: [CORE_ORG_ROLES.ORG_ADMIN],
    riskLevel: ResourceOperationRiskLevel.MEDIUM,
    resourceOperationLike: CoreResourceOperation.UPDATE,
    requestDto: z.object({
      assignedToUserId: z.string().min(1),
    }),
    referenceConstraints: {
      assignedToUserId: {
        qualifyingStatuses: [OrganizationMemberStatus.ACTIVE],
        requiredRoles: {
          scope: ResourcePrimaryScope.ORGANIZATIONS,
          roles: [CORE_ORG_ROLES.ORG_ADMIN],
        },
      },
    },
  }],
},

roles controls who may invoke the action. referenceConstraints controls who may be assigned: an active organization member satisfying the required role. These are different checks. resourceOperationLike supplies the existing update behavior; the registered resource schema and relationship give assignedToUserId its meaning.

For the purchasing example above, an approval threshold or external verification needs application-authored processing. Declare its inputs, scope and access requirements, then supply the additional backend phases or implementation that performs those decisions. Standard update behavior cannot infer an approval policy from the action’s name.

Decide how the action appears

The API contract and its screen presentation have different owners. Resource UI behavior chooses an addressable page, an embedded surface or API-only use. Existing presets or a backend defaultFrontendPosture can provide that choice; every action does not need a new screen declaration. Authorization still decides whether a caller may execute it.

For example, Wonder Todos binds a custom record view within its resource UI behavior. This excerpt shows two entries in its views array:

[Op.CREATE, { surface: ResourceOperationFrontendSurface.EMBEDDED }],
[Op.READ, {
  surface: ResourceOperationFrontendSurface.ADDRESSABLE,
  customView: TodoReadCustomView,
}],

The custom host below keeps the standard record layout and adds a resource-owned workspace. The composite view is defined separately and registered with that resource; its reference is not a globally supplied name. Imports are from the public frontend package, with the application-owned view reference imported locally.

import type { ResourceReadCustomViewComponent } from '@wildo-ai/saas-frontend-lib';
import {
  EmbedResourceOwnedCompositeView,
  ResourceLayoutPreset_Read_Default,
  useReadOperationSurface,
} from '@wildo-ai/saas-frontend-lib';
import { TODO_WORKSPACE_COMPOSITE_VIEW_REF } from './TodoWorkspaceCompositeView.js';

export const TodoReadCustomView: ResourceReadCustomViewComponent = (props) => {
  const { resourceContext } = useReadOperationSurface({
    resourceContext: props.resourceContext,
    navigationZone: props.navigationZone,
    navigationInitiator: props.navigationInitiator,
  });

  return (
    <ResourceLayoutPreset_Read_Default {...props} showCharts={false}>
      <EmbedResourceOwnedCompositeView
        resourceContext={resourceContext}
        viewRef={TODO_WORKSPACE_COMPOSITE_VIEW_REF}
        navigationZone={props.navigationZone}
        navigationInitiator={props.navigationInitiator}
      />
    </ResourceLayoutPreset_Read_Default>
  );
};

The hook uses the supplied operation and navigation context. The preset retains the standard record presentation; the embedded view receives the same record context. This explicit composition lets a specialized screen participate in the application rather than becoming a separate implementation of record loading and navigation.

Connect the module, not just the file

The shared registry combines the engine module with application modules. Backend and frontend registries collect their corresponding contributions. Inside those registered modules, generated scanners deliberately discover exports such as .operation files; follow the module’s naming and export conventions rather than adding a manual registry row for every file.

Check that the resource configuration, schema and relationships reach the shared registry, that authored backend processing is discovered by its registered module, and that resource UI behavior and composite definitions reach the frontend module registry. These assembled inputs are consumed by the application’s frontend provider and backend startup.

Define what succeeds together

For a custom approval that changes related records, choose the execution boundary explicitly. The custom-operation factory supports transactionalCore; participating service calls must carry the transaction context and use compatible participants. An HTTP request to another service does not become rollback-safe because it runs beside database changes.

Keep external effects outside the transaction where the chosen workflow requires it. If the product needs retryable delivery after commit, use a persisted delivery mechanism and verify its consumer; an ordinary callback alone does not provide that guarantee. The custom-operation contract explains the phases and authoring choices.

Keep the meaning beside the behavior

Specifications describe intent for the development workflow and companion’s exported knowledge. They do not execute the rule. For the assignment example, record the distinction between the actor and the assignee in the corresponding operation specification, then check both allowed and refused assignments through the API and interface. Maintain that meaning when the configuration changes.

For the purchasing example, exercise allowed and refused approvals, invalid inputs and external-service failure. A disabled button explains availability; it does not replace server-side enforcement. The observable result must match the declared contract and specification.

Explore the resource system for business contracts and front-end composition for interface extension points.

Describe grants and lifecycle in the catalogue

This selected Wonder Todos product definition shows the organization’s plan, benefits and change policy. Its prices and presentation fields are omitted; the named features are declared in the application’s feature configuration.

const ORG_PLAN_PROFESSIONAL: ProductDefinition = {
  key: 'org-professional',
  type: ProductType.PLAN,
  targetScopes: [ResourcePrimaryScope.ORGANIZATIONS],
  planTierOrder: 1,
  grantedFeatures: [
    ApplicationFeature.BULK_EXPORT,
    ApplicationFeature.ADVANCED_REPORTS,
    ApplicationFeature.CUSTOM_WORKFLOWS,
  ],
  grantedLimits: {
    [ApplicationFeature.MAX_TODO_LISTS]: { value: 100, mode: LimitGrantMode.SET },
  },
  behaviorPolicy: {
    trial: { days: 14, requirePaymentMethod: false },
    upgrade: { proration: ProrationBehavior.CREATE_PRORATIONS, timing: BillingTiming.IMMEDIATE },
    downgrade: { proration: ProrationBehavior.NONE, timing: BillingTiming.AT_PERIOD_END },
    cancellation: { allowImmediate: false, defaultBehavior: BillingTiming.AT_PERIOD_END },
  },
};

targetScopes identifies the purchaser’s scope. grantedFeatures and grantedLimits contribute to its effective entitlements. planTierOrder determines whether a change is an upgrade or downgrade by comparison with the current plan; it is distinct from display ordering. The target plan supplies the corresponding proration policy. Feature names such as CUSTOM_WORKFLOWS name grants; they do not generate that product functionality.

In the Stripe plan-change path, the selected plan is updated immediately: proration controls how the change is billed. The timing value is carried as metadata; AT_PERIOD_END does not schedule that plan change. Period-end cancellation is a separate provider action that does defer cancellation. Check these outcomes separately when designing the customer journey.

Register the complete catalogue as productDefinitions on the shared engine module. This is how the definitions enter the assembled application, alongside the corresponding feature declarations.

Complete the provider connection

The backend selects billing and its provider. Wonder Todos configures:

billing: {
  enabled: true,
  providerRef: 'stripe',
},

Connect this selection to the application’s other configuration owners:

Discovery reads engine-shipped provider contributions from their package. Do not add a duplicate application provider-contributions.ts entry for Stripe; that authoring surface is for a provider implemented by the application itself.

Synchronize the catalogue and check the resulting provider product/price mappings before offering checkout. Configure the webhook path and its verification so provider events can update the correct local billing account.

A checkout return URL tells the browser where to go. The provider event and its processing establish the purchase state in the application. Verify that the correct organization receives the subscription and grants, including when an event is delivered again.

Keep commercial access and permission separate

An interface policy can explain an unavailable feature or guide someone toward an upgrade. The backend requirement protects the actual operation. Usage reporting, numeric allowances and prepaid credits have different contracts; select and wire the mechanism that matches the offer.

Verify changes, not only the first purchase

Exercise trial entry, a successful purchase, an upgrade, a downgrade and period-end cancellation in the provider’s test environment. Check the billing account, local subscription state and effective access after each transition. Include a failed or delayed payment and a repeated provider event, then verify the customer-facing messages and actions remain consistent.

Follow the connected billing flow from registered product and price through checkout, signed events and effective grants. Its engineering guide links to the complete catalogue, checkout and invoice examples.

Define roles where the application assembles them

Wonder Todos declares custom roles in its shared engine configuration. This excerpt preserves the role definitions, with formatting simplified. The types and core roles are imported from @wildo-ai/saas-models.

export const CUSTOM_ROLES_CONFIGURATION: RolesConfiguration = {
  CUSTOM_APP_MANAGER: {
    role: 'CUSTOM_APP_MANAGER',
    inheritFrom: CORE_APP_ROLES.APP_USER,
    isSystemRole: false,
    relatedPrimaryScope: ResourcePrimaryScope.APPLICATION,
  },
  CUSTOM_ORG_SUPERVISOR: {
    role: 'CUSTOM_ORG_SUPERVISOR',
    inheritFrom: CORE_ORG_ROLES.ORG_MANAGER,
    isSystemRole: false,
    relatedPrimaryScope: ResourcePrimaryScope.ORGANIZATIONS,
  },
};

The first role belongs to application scope; the second belongs to organization scope. Their inheritance is explicit. In particular, the name CUSTOM_APP_MANAGER does not grant administrator authority: this example inherits APP_USER. Access follows the declared inheritance and operation rules, not an interpretation of the label.

The shared engine module registers these definitions through customRoles: CUSTOM_ROLES_CONFIGURATION. Resource operations then declare which roles may invoke them. Registering a role alone does not add it to every operation’s permitted audience.

In the application’s existing shared engine module, keep its other contributions and add the role configuration. These are the relevant lines from Wonder Todos’ shared-lib/src/engine/index.ts:

import type { SharedSaaSModule } from '@wildo-ai/saas-models';
import { CUSTOM_ROLES_CONFIGURATION } from './roles';

const engineSharedModule: SharedSaaSModule = {
  moduleId: 'engine',
  kind: 'engine',
  customRoles: CUSTOM_ROLES_CONFIGURATION,
  // Keep the application's other shared contributions here.
};

export default engineSharedModule;

Give each audience an intentional surface

Use resource UI behavior, navigation and custom views to present the relevant actions. Keep backend authorization independent of their visibility. A menu hidden from members does not protect the endpoint, and an application-level role should not be treated as an implicit bypass for every customer-owned operation.

Design support around actions, not blanket access

Name the operation your team needs: inspect an account status, change an allowed setting or resolve a specific business issue. Declare its inputs, permitted roles and scope, and implement the intended effect. Preserve actor attribution and use the relevant audit mechanisms for sensitive administrative changes.

Do not infer impersonation, unrestricted customer-record access or a complete support workflow from the existence of an operator role. Those are separate product decisions with their own operations and interfaces.

Change authority through its dedicated operations

For example, granting a product operator the application’s CUSTOM_APP_MANAGER role uses the user resource’s Users_Operations.ASSIGN_ROLES contract. The targeted user’s identity belongs in the operation address; the request body names the requested roles:

Use the application’s API base URL (including its API prefix), an existing target user’s ID and the signed-in application super-administrator’s access token. The following commands are two separate lifecycle steps: first grant responsibility, then revoke it when that responsibility ends. Check the subject’s access between them.

Grant the declared application role without replacing the other roles:

curl --fail-with-body --request PUT "$API_BASE/users/$SUBJECT_USER_ID/assign-roles" \
  --header "Authorization: Bearer $ADMIN_ACCESS_TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{"roles":["CUSTOM_APP_MANAGER"],"reason":"Assign product operations responsibility"}'

Later, remove that role while preserving unrelated roles:

curl --fail-with-body --request PUT "$API_BASE/users/$SUBJECT_USER_ID/revoke-roles" \
  --header "Authorization: Bearer $ADMIN_ACCESS_TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{"roles":["CUSTOM_APP_MANAGER"],"reason":"Product operations responsibility ended"}'

The HTTP segments are assign-roles and revoke-roles; the operation identifiers are assign_roles and revoke_roles. Use the global user ID, not an organization-membership ID. If the application’s step-up policy challenges this high-risk operation, obtain fresh proof for the same caller through reauthentication and include its x-reauth-token header on that request.

The caller must satisfy the operation’s application-super-administrator role requirement. This payload grants the role defined above; its name does not add permissions beyond its declared inheritance. The engine applies an additive union against persisted appRoles. Users_Operations.REVOKE_ROLES accepts the corresponding role list and removes those roles; ordinary array replacement is a different operation.

These operations enforce the caller’s role ceiling, preserve the last-super-administrator floor and record the authority change. Test the resulting permissions on the subject’s next request as well as the operation response. For customer membership roles, use the organization-scoped contract rather than substituting this application-role operation.

Temporary platform access is another, conditional governance flow: the operation must explicitly admit it, the caller needs qualifying application-scoped administrator authority, and access requires a usable grant for the target organization. This example’s CUSTOM_APP_MANAGER does not meet that authority requirement. Use the identity engineering guidance when that support model belongs in the product.

Test changes in authority

Verify permitted and refused requests for a member, customer administrator and application operator. Repeat after a role is removed. Check cross-customer attempts, direct API calls and the recorded actor for sensitive operations. Ensure the interface communicates the new state without relying on stale visibility as the access control.

See users, organizations and security and compliance and audit for the underlying controls and evidence mechanisms.

Declare the target environment

The application configuration describes its services; environment configuration describes where and how they run. This selected excerpt from Wonder Todos’ staging configuration sits inside defineInfraEnvConfig. Imports, backing-service declarations and comments are omitted.

environment: WildoEnvironment.STAGING,
locationType: WildoLocationType.REMOTE,
runtime: WildoDeploymentRuntime.DOCKER_COMPOSE,
runtimeEnvironment: RuntimeEnvironment.STAGING,
publicDomain: 'staging.wonder-todos.com',
serviceHosts: {
  app: 'app',
  docs: 'docs',
  website: '',
},
remoteProvider: {
  provider: 'scaleway',
  registryEndpoint: 'rg.fr-par.scw.cloud/wonder-todos',
  region: 'fr-par',
},
deployment: {
  branch: 'staging',
  runtime: WildoDeploymentRuntime.DOCKER_COMPOSE,
},

The host map places the application at the app subdomain, documentation at docs and the configured website at the environment’s apex domain. Those additional frontends are services selected for this application; the map does not create their content. Provider identifiers and domains here belong to the example, not settings to copy unchanged.

Generate delivery files from the selected runtime

The CLI’s deployment generators consume the application and environment configuration to produce Docker Compose or Kubernetes material and the corresponding deployment workflow. Configure backing services, provider access, environment credentials and public routing for the selected target. Generated files describe delivery; running the target and checking it establish that delivery worked.

For example, from a configured and registered application workspace, install the production workflow and generate its environment material with:

wildo config sync --env=production --domain cicd
wildo config sync --env=production --domain config

Use the environment name declared by your application. Inside CI, the generated workflow adds --ci to the second command and supplies the required secret values as environment variables; that mode reconstructs secrets from the CI environment rather than reading the local secrets file. Workflow installation and deployment generation need access to the registered application’s service descriptors and the appropriate credentials. Confirm that sync produced .wildo-saas/deploy/<env>/ material: a classified platform-access or credential failure can report a skipped deployment output while retaining local output.

The Kubernetes workflow contains cluster apply steps. The Compose workflow generates the configuration and builds and publishes images; the operator supplies the remote transfer and apply procedure for the chosen host. Neither a generated file nor a published image proves that users can reach the new release.

Existing workflow files are preserved unless replacement is explicitly requested. After changing services or infrastructure, review the workflow as well as regenerated runtime material; preservation protects edits, not continued agreement with new configuration.

Apply change to the existing project deliberately

Composition scenarios materialize declared project structure and registrations. Their apply path supports a dry run; identical output can be skipped, while conflicting authored output requires reconciliation instead of silent replacement. Version control remains the place to review and merge changes.

For a new business module, inspect its shared, backend and frontend contributions and the registry updates that expose them. Implement the behavior, update its specifications and check the affected consumers. A generated module scaffold is a starting structure, not a completed business feature.

Ship data changes with the release

For PostgreSQL-backed resources, carry a reviewed migration with the schema change and maintain the accepted schema baseline. Application startup applies shipped migrations before checking the physical schema; a changed TypeScript declaration alone is not the migration deliverable.

Review the generated plan and SQL against the existing database, including how existing rows satisfy new requirements. Exercise the upgrade with representative data before release. The data-storage guidance explains the storage contract; the application’s application-database-migrations knowledge gives the authoring and baseline workflow.

Adopt a framework release deliberately

Changing your product and adopting a new framework release are separate decisions. After choosing the new @wildo-ai/* versions in the application’s overrides, install them before deriving their dependency requirements:

pnpm install
wildo align-deps --write
pnpm install
wildo assets sync

align-deps reads the installed framework and writes dependency manifests; the second install updates the resolved dependencies and lockfile. assets sync refreshes the delivered development knowledge. Neither command rewrites your business logic or establishes compatibility: review the diff, follow the release’s migration requirements and run the affected application checks.

Verify the deployed customer experience

Check startup and readiness for the selected services, then exercise login, workspace access, a representative custom action and any configured external provider flow through the target’s public addresses. Review operational signals and the release’s data changes as well as its screens. A successful file-generation step is not a successful deployment.

Read Docker or Kubernetes for deployment choices and the development companion and CLI for the development workflow.