Primary Apps

Primary's two main web applications: the Ops Portal and the Client Portal. These are not currently served separately.

View this documentation at primary-apps-docs.pages.dev.

Stack (NodeJS)

  • Remix (React + React Router)

Frontend

Backend

Observability

  • Posthog - Feature flagging and analytics
  • Sentry - Error monitoring

Dev tooling

AuthN & AuthZ

CI

Contributing

Quick Start

  • Get a tool like nvm, mise-en-place, or asdf to install the right node version.
  • npm install
  • Ask another dev for a .env file to fill in secret gaps.
  • Run npm run docker-db to start a local Postgres and Valkey.
  • npm run setup to seed and migrate the database.
  • npm run dev to start the dev server.
  • npm run storybook to develop UIs with Storybook.

Prerequisites

Firstly, you will need to grab a .env file for local development. See .env.example for what this should look like. Ask another dev for their .env file.

Additionally, you will want to get access to these 3rd party services. Contact someone in the eng team to grant access via Google auth to these dashboards -

  • Clerk for user management.
  • Posthog for feature flagging and more.
  • Sentry for monitoring.
  • AWS

Local Dev Environment Requirements

  • NodeJS. Recommended to use a version management tool, e.g. nvm, mise-en-place or asdf. See .nvmrc for the required version, use node --version to verify.
  • Docker

Getting Started

Tip: go through these commands in package.json to see exactly what they are doing.

  1. Start the local databases (Postgres and valkey) in Docker:
npm run docker-db

Note: The npm script will complete while Docker sets up the container in the background. Ensure that Docker has finished and your container is running before proceeding. The database will continue to run in the background, so you shouldn't need to re-run this command often.

  1. Setup command
npm run setup

This will install dependencies, generate the Prisma client libraies, run any outstanding DB migrations (or all of them for the first time), and populate the local DB with seed data.

This should only be needed when:

  • There are new dependencies you want to install
  • There are new DB migrations which haven't been applied to your local DB instance
  • You would like to wipe and reset your local DB
  1. Start dev server:
npm run dev

This starts your app in development mode with hot module reload. This additionally starts the Graphile Worker process.

Testing

Our tests are broken down into these categories:

  1. npm run test - unit tests run with vitest. Files ending in .test.ts or .test.tsx will be run.
  2. npm run test:integration - unit tests which also hit the local database, also run with vitest. Files ending with .integration.test.ts.

Type Checking

This project uses TypeScript. It's recommended to get TypeScript set up for your editor to get a really great in-editor experience with type checking and auto-complete. To run type checking across the whole project, run npm run typecheck.

Linting

This project uses ESLint for linting. That is configured in .eslintrc.js.

Formatting

We use Prettier for auto-formatting in this project. It's recommended to install an editor plugin (like the VSCode Prettier plugin) to get auto-formatting on save. There's also a npm run format script you can run to format all files in the project.

Dependency Cruiser

We use dependency-cruiser to enforce boundaries within the project.

See .dependency-cruiser.js for the complete ruleset.

We should aim to fix any violations as they arise, though you can add violations to the known violations list in exceptional cases by running npm run depcheck:baseline, and committing the resulting changes.

E2E Testing

We use Playwright for end-to-end testing. To run the tests, you can use npm run test:e2e. You can also use npm run test:e2e -- --ui to debug them visually.

These are also run in CI on every PR.

How to understand and debug a failing test in CI

  1. Notice the failing test, e.g. this line in the logs: https://github.com/primaryco/primary-apps/actions/runs/13718048846/job/38367056208?pr=1166#step:14:29
  2. If it's not clear what the problem is, download the test results zip (e.g. under "Artifacts" https://github.com/primaryco/primary-apps/actions/runs/13718048846?pr=1166) and run the command that the logs specify, e.g. npx playwright show-trace test-results/smoke-Top-level-route-smok-142ce-rtal-admin-transactions-new-chromium-retry1/trace.zip. This will show you a complete trace, including network requests, console errors, and screenshots.
  3. If the issue is still not clear, it may be an issue on the server (e.g. migrations haven't run). You can inspect server logs in the docker compose logs step https://github.com/primaryco/primary-apps/actions/runs/13718048846/job/38367056208?pr=1166#step:17:22)

Storybook

We use Storybook as a frontend development tool, and to document and catalog components, blocks, and pages. To start Storybook, run npm run storybook.

Storybook previews are deployed on every PR which can be used by reviewers to experience changes.

Pull Requests

Tests, linting, formatting, dep cruiser check and Typescript check are all required to pass before merging is enabled in GitHub.

The exact set of commands useds can be found in .github/workflows/pr-ci.yml.

Deployment

We use GitHub Actions for continuous integration and deployment. See .github/workflows/deploy.yml to see exactly what happens on merge to main. In short, the changes will be build and deployed first to the Staging environment, if successful it will be immedaitely deployed to Production.

CLI Commands

This repo also contains a number of CLI commands used for ad-hoc tasks (e.g. data backfill or debugging). These are located in app/commands, and can be run using npm run dev-cmd <command name>.

E.g. backfilling ledger transactions

npm run dev-cmd backfill-ledger-transactions -- --actor test --dataFile ./data/backfill-ledger-transactions/dev/test.json

See each command for usage.

Making Database Changes During Dev

  • Update the schema in schema.prisma
  • run npx prisma format to format the prisma schema
  • run npx prisma migrate dev --create-only to generate a migration file
  • run npm run setup to generate types, update the db schema, and rerun seed
  • run npx prisma studio to look at your data
  • run npx prisma seed to run just the seed script (with the overhead of npm run setup).

See the Prisma CLI documentation.

Conventions & Best Practices

Services (Backend)

Forms

UI

Authentication & Authorisation

We use Clerk for authentication, user management, user organisations, roles, permissions, and authorisation.

Authorisation

Permissions

Clerk allows up to 50 custom permissions to be defined per application. These permissions should be defined in Clerk, then added to our global typing in types/clerk.d.ts. From there, they can be used in our codebase to check if a user has a particular permission.

Authorisation checks should always check that a subject (in our case, a user) has a particular permission. Do not check that the user is a member of a particular role. Roles can change, as can the permissions associated with those roles. We want to enable making those changes in future without having to audit all existing authorisation checks in the codebase to ensure that they are still appropriate.

Ops User Authorisation

There is a custom session claim, primary_ops, which can be used to check whether a user should have access to the operator portal or not. This is not ideal. In future, the ops portal will be a separate application in Clerk with its own roles and permissions.

Tenancy Checks

Since our app is multi-tentanted, it is imperative that all resources are explicitly checked against the current user. The Identity pattern (see identity.server.ts) provides a simple way to do this.

// route.tsx
export const loader = async (loaderArgs: LoaderFunctionArgs) => {
  const { identity } = await requireUserAndOrganisation({ loaderArgs });

  await myServiceFunction({ context: { identity } });
};

// myService.server.ts
const myServiceFunction = async ({ context }: { context: IdentityContext }) => {
  // to check access to a single organisation
  requireOrganisationAccess(identity, organisationId);

  // to check access to a all organisations (relevant to admin/ops portal users)
  requireAllOrganisationAccess(identity);
};

We expect that tenancy checks are done at the service level, as per the above example.

Failed Authorisation Checks Should 404

Return 404 if the user doesn't have the right permissions.

It is Clerk's convention to return 404 (not found) when a request is deemed unauthorized with respect to permissions or role. https://clerk.com/docs/references/nextjs/auth#protect

I suppose this is according to a "you shouldn't know about what you can't see" philosophy. However, it can be counterintuitive during development. You may sometimes think "Huh? am I running the right code? Restarted server? Is the request URL incorrect?"

Use Typed Remix Actions And Form Responses

import { formAction } from "~/form-action.server";

const schema = z.object({
  greeting: z.string(),
});

export const action = async (actionArgs: ActionFunctionArgs) => {
  return formAction({
    //...other props
    schema,
    //...
  });
};

export const View = () => {
  const { greeting } = useActionData<typeof action>();

  // render things
};

export default View;
  • Don't use action: ActionFunction as it is not generic and can't infer the response type from your return statements. Use actionArgs: ActionFunctionArgs as the first parameter instead.

When to use native form submission and when to use fetch

Generally:

  • Use <Form>, causing a navigation and full page reload, when there will be significant changes to the frontend state after submission, such as creating or deleting a record.

  • Use <fetcher.Form>, an async fetch request, for actions that cause easy to reason about mutations, such as updating a field in a record.

Heres an excerpt from the Remix docs that explains this well:

When the URL Should Change

These actions typically reflect significant changes to the user's context or state:

Creating a New Record: After creating a new record, it's common to redirect users to a page dedicated to that new record, where they can view or further modify it.

Deleting a Record: If a user is on a page dedicated to a specific record and decides to delete it, the logical next step is to redirect them to a general page, such as a list of all records.

For these cases, developers should consider using a combination of <Form>, useActionData, and useNavigation. Each of these tools can be coordinated to handle form submission, invoke specific actions, retrieve action-related data, and manage navigation respectively.

When the URL Shouldn't Change

These actions are generally more subtle and don't require a context switch for the user:

Updating a Single Field: Maybe a user wants to change the name of an item in a list or update a specific property of a record. This action is minor and doesn't necessitate a new page or URL.

Deleting a Record from a List: In a list view, if a user deletes an item, they likely expect to remain on the list view, with that item no longer in the list.

Creating a Record in a List View: When adding a new item to a list, it often makes sense for the user to remain in that context, seeing their new item added to the list without a full page transition.

Loading Data for a Popover or Combobox: When loading data for a popover or combobox, the user's context remains unchanged. The data is loaded in the background and displayed in a small, self-contained UI element.

For such actions, useFetcher is the go-to API. It's versatile, combining functionalities of the other four APIs, and is perfectly suited for tasks where the URL should remain unchanged.

https://remix.run/docs/en/main/discussion/form-vs-fetcher#specific-use-cases

UI Code Conventions

Write stories for all components and key UI blocks when reasonable

For example: https://primary-storybook.pages.dev/?path=/docs/alertv2--docs

app/ui/dashboard/Alert/AlertV2.stories.tsx

Components shouldn't define outer margin or padding

Parents should define layout and spacing between elements, whereas children/components shouldn't decide how much space they should have around them. This makes it possible to compose components with layouts, without hacks or overrides. https://youtu.be/jnV1u67_yVg?t=620

Do

function AccountCard({
  name,
  bsb,
  number,
}: {
  className?: string;
  name;
  bsb;
  number;
}) {
  return (
    <div
      className={cn(
        "p-2 grid gap-2 bg-white rounded-md border shadow-md",
        className
      )}
    >
      <h2>{name}</h2>
      <p>
        {bsb} {number}
      </p>
    </div>
  );
}

function AccountList({ accounts }: { accounts: Account[] }) {
  return (
    <div className="grid gap-4">
      {accounts.map((account) => (
        <AccountCard key={account.id} {...account} />
      ))}
    </div>
  );
}

// Or

function AccountListWithPrimaryAccount({ accounts }: { accounts: Account[] }) {
  return (
    <div className="grid">
      {accounts.map((account, i) => (
        <AccountCard
          className={i === 0 ? "mb-8" : i !== accounts.length - 1 ? "mb-4" : ""}
          key={account.id}
          {...account}
        />
      ))}
    </div>
  );
}

Parents should define spacing between elements. This can be, preferrably, through grid or flex features. However, in AccountListWithPrimaryAccount for example, a variable margin is set on the AccountCard, and it is still the parent that decides the spacing between elements.

Don't

function AccountCard({
  name,
  bsb,
  number,
}: {
  className?: string;
  name;
  bsb;
  number;
}) {
  return (
    <div
      className={cn(
        "mb-4 p-2 grid gap-2 bg-white rounded-md border shadow-md",
        className
      )}
    >
      <h2>{name}</h2>
      <p>
        {bsb} {number}
      </p>
    </div>
  );
}

function AccountList({ accounts }: { accounts: Account[] }) {
  return (
    <div className="grid">
      {accounts.map((account) => (
        <AccountCard key={account.id} {...account} />
      ))}
    </div>
  );
}

Extract components, not classes

Do

function ListItem({ children }) {
  return <li className="flex items-center">{children}</li>;
}

export function AccountDetails({ payId, bsb, number }) {
  return (
    <ul className="list-disc list-inside">
      <ListItem>Account number: {number}</ListItem>
      <ListItem>BSB: {bsb}</ListItem>
      <ListItem>PayID: {payId}</ListItem>
    </ul>
  );
}

Don't

export function AccountDetails {
    return (
      <ul className="list-disc list-inside">
        <li className="flex items-center">Account number: {this.props.number}</li>
        <li className="flex items-center">BSB: {this.props.bsb}</li>
        <li className="flex items-center">PayID: {this.props.payId}</li>
      </ul>
    )
}

Use cn when composing classNames

This merges tailwind classes appropriately and consistently.

import { cn } from "~/lib/utils";

function AccountCard({
  name,
  bsb,
  number,
}: {
  className?: string;
  name: string;
  bsb: string;
  number: string;
}) {
  return (
    <div
      className={cn(
        "p-2 grid gap-2 bg-white rounded-md border shadow-md",
        className
      )}
    >
      <h2>{name}</h2>
      <p>
        {bsb} {number}
      </p>
    </div>
  );
}

Use semantic Z-index values from tailwind.config.mts

Using arbitrary z-index values throughout our codebase can make it hard to to be predictable about the 3rd dimension in our UI.

function Sidebar() {
  return <nav className="z-sidebar"></nav>;
}

Use tailwind-variants for complex components

You'll need this when switching styles based on props.

import type { VariantProps } from "tailwind-variants";
import { tv } from "tailwind-variants";

const alertStyles = tv({
  base: "p-4 rounded-xl border",
  // When feasible, try to match variants to their matching Figma components.
  variants: {
    kind: {
      default: "bg-gray-100 border-gray-500",
      success: "bg-green-100 border-green-500",
      error: "bg-red-100 border-red-500",
      warning: "bg-yellow-100 border-yellow-500",
    },
  },
  defaultVariants: {
    kind: "default",
  },
});

// Note the use of `VariantProps` for extracting prop types from above.
export function Alert({
  kind,
  children,
}: { children: React.ReactNode } & VariantProps<typeof alertStyles>) {
  return <div className={alertStyles({ kind })}>{children}</div>;
}

See app/ui/dashboard/Alert/AlertV2.tsx for a larger example, including the use of slots.

Don't abuse className overrides

When overriding any styles using className, ask yourself how hard it would be for a stranger to make internal style changes to the component without visual regressions in your instance.

Do

function DashboardPage() {
  return (
    <div className="grid min-h-dvh">
      {/*
      This is safe because place-self only affects it's position within the parent layout.
      Using something like `flex` or `grid` would be dangerous.
    */}
      <AccountsList className="m-4 place-self-center" />

      {/*
        `fixed` may be a dangerous override because the element may be
        assuming a `relative` root, for positioning children within it.

        It it most likely safer to wrap the element.
      */}
      <div className="fixed bottom-4 right-4 h-52 w-52">
        <DevToolsOverlay className="h-full w-full" />
      </div>
    </div>
  );
}

Don't

function DashboardPage() {
  return (
    <div className="grid min-h-dvh">
      {/*
      Padding isn't safe beause the AccountsList could be setting a border or shadow.
      It shouldn't be the parent's responsibility to know how to style the accounts list, so `bg-black`
      doesn't make sense here.
      Rather, it indicates you may need to add another variant to AccountsList.
    */}
      <AccountsList className="m-4 bg-black p-2" />
      <DevToolsOverlay className="fixed bottom-4 right-4 h-52 w-52" />
    </div>
  );
}

Use 100dvh, not 100vh

When you need something to span the height of the viewport.

dvh is more reliable because it is the "safe" area of the screen; it respects extraneous elements in all browsers, e.g. the address bar in some mobile browsers.

It is dynamic; it updates when the viewport changes.

Note: dvh isn't for every use case. E.g. when you don't want it's value to change upon resizing the viewport.

https://learnbricksbuilder.com/demystifying-vh-dvh-svh-and-lvh-in-css/

Use function over const for React components

Use const when you need, but prefer function.

Do

function MyComponent() {
  return <div>My component</div>;
}

Don't

const MyComponent = () => {
  return <div>My component</div>;
};

Naming Conventions

Date Ranges

When a date range is specified, variables should be named to indicate inclusivity or exclusivitiy explicitly, e.g. startAtInclusive and endAtExclusive.

In some cases, inclusivity/exclusivity may be parametried, for example:

type IntervalBoundary = "inclusive" | "exclusive";
{
    startAt: Date;
    endAt: Date;
    options: {
        endAtBoundary: IntervalBoundary;
        startAtBoundary: IntervalBoundary;
    }
}

Helpful Tips and Tricks

Add a keybinding for "fix all fixable ESLint problems" in VSCode

For me, it's "Shift + Cmd + E" in VSCode. Doing this often will save you headaches when trying to merge a PR, since it will be blocked if there are linting errors.

Use "organize imports" in VSCode

Similar to the above, this will clean your imports and help you pass PR checks.

Decisions

Code Review Requirements (2024-10-11)

In the context of:

  • code review requirements facing:
  • a need to deliver features quickly approaching Primary's public launch we decided to:
  • remove PR review requirements from the main branch and neglected:
  • our existing setup of requiring at least 1 review and enforcing code ownership to achieve:
  • higher velocity
  • more autonomy for team members
  • less slack in the development process accepting downsides:
  • that we will probably need to reverse this decision when we aim to become ISO certified
  • that this will not scale effectively as the team grows
  • that we each bear individual responsibility for:
    • asking for review when we feel it is needed
    • drawing attention to others PRs if we feel they should have been reviewed
    • being open to reversing this decision if it is not working

Authorisation (2024-08-19)

In the context of:

  • building the approvals feature, which requires checking that a user has permission to approve a payout, transfer, or beneficiary account facing:
  • a need to check that the user is authorised to access a particular route loader or action
  • allowing customers to manager their organisation's users and role memberships in Clerk we decided to:
  • use Clerk's organisation roles and permissions, along with their SDK to check permissions and neglected:
  • using a library, options we considered:
    • casbin
    • accesscontrol
    • casl
    • @tselect/access-control
  • using a more sophisticated Authorisation-as-a-Service provider, options we considered:
  • a clean interaction between our authn and authz systems
    • since role membership is defined in Clerk, we want to avoid having to duplicate this in our authz system
  • an ability to express authz checks in terms of permissions, not roles (e.g. "does this user have this permission?")
    • as we feel this is the most forward-compatible way to express authz checks, enabling a simpler migration to custom roles, ABAC, ReBAC, or other models in future
  • rapid delivery
    • since we already use Clerk, no need to onboard with a new vendor
    • Clerk's authz model fits our current needs, so no need to build our own authz model using a complex library or service
  • defining existing permissions in a single place
    • rather than allowing adhoc permission creation in the codebase
  • a well-typed API for authz checks accepting downsides:
  • permissions included in tokens
  • a limited number of roles (10)
  • a limited number of permissions (50)
  • no custom roles for individual organisations
  • less sophisticated authz policy model
  • we will probably have to migrate away if our authz requirements become more complex

How-Tos

How To Show a Notification After a Form Submission

import { redirectWithSuccess, redirectWithError } from "remix-toast";
import { performMutation } from "remix-forms";

// in your action function:
const result = await performMutation({
  request,
  schema: someSchema,
  mutation: someMutation,
  environment: { userId, orgId },
});
if (result.success) {
  return redirectWithSuccess(`/dashboard/payouts/${payoutId}`, {
    message: "Payout approved",
    description: `Optional description`,
  });
} else {
  return redirectWithError(`/dashboard/payouts/${payoutId}`, {
    message: "Falied to approve payout",
  });
}

remix-toast is setup in app/routes/dashboard.tsx. Internally, it uses session.flash to set a temporary cookie that is unset after reading https://remix.run/docs/en/main/utils/sessions#sessionflashkey-value.

How To Check For Permissions On The Server (in a loader or action)

export const loader = async (loaderArgs: LoaderFunctionArgs) => {
  const { auth } = await requireUserAndOrganisation({ loaderArgs });
  const canManagePayouts = auth.has({ permission: "org:payouts:manage" });
  // ...
};

Calling requireUserAndOrganisation checks that you're logged in and have an organisation selected. It also returns an auth object from Clerk's library, which has orgPermissions: string[], or a convenient has function to check either role or permission existence.

How To Analyse React Performance Issues Using React Scan

  1. Set VITE_ENABLE_REACT_SCAN to true in your .env file to enable React Scan.
  2. Run the dev server
  3. Open in a browser, with devtools open. Refresh while devtools are open for good measure.
  4. You'll now see the the dev tool widget showing FPS, and renders will be annoyingly highlighted around components. See https://react-scan.com/ for more about what you can do.

Settings

Member Visibility

On This Page

Primary Apps