code-structure

Keep domain rules in actions: auth checks, state transitions, failure classification, and user-facing errors. Move reusable mechanics to the service layer: provider interactions, command execution, and health checks. The rule of thumb is actions own the why and when, services own the how.

Extract when the same low-level operation appears in two or more callers, such as sandbox creation or email sending across multiple flows. Skip extraction when logic is genuinely domain-specific with only one caller, since that leads to over-abstraction.

Design service functions as composable capability blocks rather than one monolithic method. Each function accepts explicit parameters, returns structured outputs, never touches the database directly, and surfaces failures as structured results instead of swallowing errors.

The main anti-patterns are the god service (one huge function hiding control flow), the leaky service (mutating database tables directly), inconsistent APIs across functions, and over-abstraction by extracting logic used by only one caller.

Write the flow in action code first, mark repeated operational chunks, then extract only the repeated non-domain parts. Replace one caller, verify it works, then migrate the rest, finishing with typecheck and lint to confirm all flows still work.