Skip to content

Best practices

API responses

  • Backend APIs return snake_case field names.
  • We want to leverage OpenAPI generate types as much as possible. For this, you should for each query build an option helper and then call useQuery
// utils/reviews.ts
export function reviewSubmissionsQueryOptions(reviewId?: string) {
  return openApiQueryOptions({
    path: "/reviews/{review_id}/review-submissions",
    parameters: { path: { review_id: reviewId! } },
    enabled: reviewId !== undefined,
    staleTime: 1000 * 60 * 5,
  });
}


// In the component
const { data: reviewSubmissions, isLoading } = useQuery(reviewSubmissionsQueryOptions(review.id));

Folder structure

  • app/ – UI and routing.
  • App.tsx – Root component: auth check, route definitions.
  • components/ – Shared layout and reusable UI (e.g. Layout, AlanerCard, PermissionChecker). Use camelCase for folder names (e.g. components/roles/).
  • pages/ – One folder per feature or route (e.g. Reviews/, Oncall/, Team/, AlanerProfile/). Each page can have:
    • index.tsx – main page or route hub
    • Subcomponents next to it or in a components/ subfolder
    • Subpages are their own files with PascalCase names.
    • Page-specific hooks/, utils/, or tests/ when it keeps the feature self-contained
  • utils/ – Shared logic and API layer: auth, backend client, domain hooks and query options (e.g. alaners.ts, reviews.tsx, users.ts). Used across multiple pages.

Put new feature code under app/pages/<FeatureName>/; add shared hooks or helpers in utils/ only when reused elsewhere.

Naming

  • React components: PascalCase file names, one main component per file if possible.
  • Folders under the app: camelCase.
  • Follow the conventions in the frontend root README / AGENTS docs.

Internal tools (Alan Home)

  • We use Murray. While it's not ideal for internal tools, it gives a great platform testing platform for engineers working on Murray to test with limited consquences.
  • Alan Home is a great platform for testing new technical concept, and push for excelence. It's a usage we are proud of and want to continue developping. Being not only a product, but also an enabler is one of the biggest strengh of Alan Home.

General

  • Prefer the patterns already used in eu-home-app (e.g. TanStack Query for server state, existing hooks and layout) when adding new features so behavior and style stay consistent.