TIP

This page mirrors .agents/end-to-end-features.md from the repository. Edit it at the source, not here.

End-to-End Feature Workflow

Use this when implementing a feature that spans data model, shared domain contracts, API, and web UI.

This file defines implementation order. For package-specific rules, follow the linked docs instead of repeating them here.

When a feature introduces shared contracts that should drive both API and frontend behavior, this workflow also includes packages/core.

Default Order

1. If the feature needs new data or persisted fields, update packages/db first.
2. If the feature introduces shared enums, schemas, formatters, or defaults consumed across packages, update packages/core next.
3. Put reusable server-side domain workflows in packages/app when both inline API fallback and workers need them.
4. Add queue contracts, dispatch, processors, schedules, or retention orchestration in packages/jobs when work is asynchronous.
5. Define or extend the oRPC contract in packages/api.
6. Add slice-local TanStack Query wrappers in apps/web.
7. Handle user-visible client errors using the typed oRPC client pattern.
8. Wire route preloading, guards, and UI composition in apps/web.
9. Run fixes and relevant validation according to Workflow, using Choice flows only when a human decision is needed.

Step 1: Database

• Edit schemas in packages/db/src/schema/ when the feature changes persisted data.
• Follow Workflow for migration generation, localhost DATABASE_URL safety, and migration application.
• Keep schema and migration work complete before defining API output shapes that depend on it.

Step 2: Shared Domain Contract

• Use packages/core for shared Zod schemas, enums, normalizers, formatters, option builders, and defaults consumed by more than one package.
• Follow Core package patterns.
• Unless explicitly told not to, if a change should propagate automatically into both API and frontend behavior, centralize it in packages/core instead of duplicating literals in app code.
• Route validators, frontend filters, and shared API input or output schemas should import core contracts when they represent the same domain surface.

Step 3: API Contract

Before transport work, decide whether server-side behavior belongs in an application service or a job:

• Use packages/app for worker-safe domain services with DB/storage/provider side effects but no oRPC or BullMQ registration.

• Use packages/jobs for queue payloads, enqueue helpers, processors, repeatable schedules, and post-domain orchestration such as notifications.

• Keep apps/worker limited to process startup/shutdown, readiness, metrics, signals, and createAllWorkers() composition.

• Add or extend the router in packages/api.

• Follow oRPC patterns for procedure factories, explicit input and output schemas, and typed errors.

• Prefer type-safe errors with .errors(...) and errors.MY_ERROR(...) for expected failure cases the client needs to handle.

Step 4: Web Data Layer

• Use oRPC's TanStack Query integration from @saasweave/api/client/tanstack-start/orpc.
• Follow API fetching patterns for *.query.ts, *.mutation.ts, query keys, query options, and hook wrappers.
• Keep orpc and TanStack Query wiring inside slice-local api/ files, not inline in page components.

Step 5: Client Error Handling

• For user-visible failure states, follow the type-safe client error pattern in oRPC patterns.
• Do not duplicate string-matched or ad hoc client error handling in web slices when the server already defines typed oRPC errors.

Step 6: Routes And UI

• Follow TanStack patterns for route placement, thin beforeLoad, and page composition.
• Follow UI guidelines for app-level component composition.
• Add Auth patterns, SEO patterns, or i18n guidelines when the feature touches those surfaces.

Validation

• Follow Workflow for fix cadence and validation scope. For larger planned work, such as implementing a plan.md, run fixes at substantial milestones/phases and once more before final handoff. Follow Testing for focused regression, unit, and e2e coverage when behavior changes.