Flows custom app architecture patterns reference

function useWellList(startDate: string, endDate: string) {
  return useQuery({
    queryKey: ["wells", startDate, endDate],
    queryFn: async () => {
      const [wells, deferments] = await Promise.all([
        fetchWells(),
        fetchDeferments(),
      ]);
      return joinWellData(wells, deferments);
    },
    staleTime: 60_000,
  });
  // caching, dedup, retries, background refetch: included
}

// schema.ts — one schema per view; z.infer is the type
const WellSchema = z.object({
  name: z.string().optional(),
  uwi: z.string().nullish(),
  latitudeWGS84: z.coerce.number().default(0),
  longitudeWGS84: z.coerce.number().default(0),
});
type Well = z.infer<typeof WellSchema>;

function mapNode(node: NodeDefinition): Well {
  const raw = node.properties?.[VIEW.space]?.[KEY] ?? {};
  return WellSchema.parse(raw);
  // wrong shape → throws here, surfaced as a query error
  // not silently wrong data
}

// useAlerts.ts — one obvious place per resource
export function useAlerts() {
  const client = useCogniteSdk();
  return useQuery({
    queryKey: ["alerts"],
    queryFn: async () => {
      const res = await client.instances.list(ALERT_SOURCE);
      return res.items.map((node) => {
        const raw = node.properties?.[VIEW.space]?.[KEY] ?? {};
        return AlertSchema.parse(raw);
        // consumers receive Alert[] — never unknown
      });
    },
  });
}

// store.ts — colocated with the feature
// Use Zustand for state that changes often (filters, selection)
export const useTriageStore = create<TriageState>((set) => ({
  selectedId: null,
  filters: defaultFilters,
  select: (id) => set({ selectedId: id }),
  setFilters: (f) => set((s) => ({ filters: { ...s.filters, ...f } })),
}));

// Components subscribe only to the slice they need
function Row({ id }: { id: string }) {
  const selected = useTriageStore((s) => s.selectedId === id);
  const select = useTriageStore((s) => s.select);
  // re-renders only when this row's selected state changes
}

// hook owns data & commands — testable in isolation
function usePipelineRun() {
  const run = useMutation({ mutationFn: runPipeline });
  return { run: run.mutate, isPending: run.isPending, error: run.error };
}

// component is a thin binding to the design system
function PipelinePanel() {
  const { run, isPending, error } = usePipelineRun();
  return (
    <Card>
      <Button onClick={() => run()} disabled={isPending}>
        {isPending ? "Running…" : "Run"}
      </Button>
      {error && <Alert variant="destructive">{error.message}</Alert>}
    </Card>
  );
}

function FormUI() {
  // business logic lives in the hook
  const { data, isLoading, addData } = useFormBusinessLogic();

  // UI state stays in the component
  const [modalOpen, setModalOpen] = useState(false);

  // simple UI events are fine
  const handleChange = (e: ChangeEvent<HTMLInputElement>) => {
    // ...
  };

  return <div>...</div>;
}

// Always up to date — no Effect needed
const filtered = items.filter((i) => i.active);

// For genuinely expensive transforms, memoize
const sorted = useMemo(() => items.slice().sort(byDate), [items]);

// Split into focused hooks — each component subscribes to what it needs
const useUserStats = () => {
  // ...
  return { userStats };
};

const useChartData = () => {
  // ...
  return { chartData };
};

function UserStatsComponent() {
  const { userStats } = useUserStats();
  // only re-renders when userStats changes
  return <div>{userStats.total}</div>;
}

function useFormBusinessLogic() {
  const query = useQuery({ queryKey: ["form"], queryFn: fetchFormData });
  const mutation = useMutation({ mutationFn: submitForm });

  // wrap mutations in named command functions
  const addData = (data: DataType) => mutation.mutate(data);

  // derive cheap values inline
  const itemCount = query.data?.length ?? 0;

  // memoize only when profiling shows a real cost
  const sortedItems = useMemo(
    () => query.data?.slice().sort(byDate),
    [query.data]
  );

  return {
    data: query.data,
    isLoading: query.isLoading,
    addData,
    itemCount,
    sortedItems,
  };
}

// tasks.tsx
import { useTasks as useTasksImpl } from "../services/use-tasks";
import type { Task } from "../types";

type TasksDeps = {
  useTasks: () => { isLoading: boolean; tasks: Task[] };
};
const defaultDeps: TasksDeps = { useTasks: useTasksImpl };

export const Tasks = ({ deps = defaultDeps }: { deps?: TasksDeps }) => {
  const { isLoading, tasks } = deps.useTasks();
  if (isLoading) return <Spinner />;
  return <ul>{tasks.map((t) => <TaskItem key={t.id} task={t} />)}</ul>;
};

// tasks.spec.tsx — no vi.mock needed
const deps: ComponentProps<typeof Tasks>["deps"] = {
  useTasks: vi.fn(() => ({ isLoading: false, tasks: [{ id: "1", text: "a" }] })),
};
render(<Tasks deps={deps} />);

function StatusCard({ status }: { status: "ok" | "error" }) {
  return (
    <Card>
      <Badge variant={status === "ok" ? "success" : "destructive"}>
        {status}
      </Badge>
    </Card>
  );
}

// config/model.ts — one place for all CDF view identifiers
export const MODEL = {
  space: "my-solution-space",
  views: {
    well: { externalId: "Well", version: "1" },
  },
  properties: {
    well: { name: "name", uwi: "uwi", lat: "latitudeWGS84" },
  },
} as const;

// Changing the space name means editing one line here.
// All usages across the codebase update automatically.
function useWells() {
  const client = useCogniteSdk();
  return useQuery({
    queryKey: ["wells"],
    queryFn: () =>
      client.instances.list({
        sources: [{ source: { type: "view", ...MODEL.views.well, space: MODEL.space } }],
      }),
  });
}

// App.tsx — one boundary at the shell catches render crashes
<ErrorBoundary fallback={<AppError />}>
  <QueryClientProvider client={queryClient}>
    <App />
  </QueryClientProvider>
</ErrorBoundary>

// Per view — use the query's own error state
const { data, error, isError, refetch } = usePlans();
if (isError) return <ErrorState onRetry={refetch} error={error} />;

// <ErrorState /> is one shared component used everywhere