docs: update instructions with frontend and python guidelines

- Added detailed organization guidelines for frontend (web/app/) and Python app/job structure.
- Clarified API call patterns and server/client loader practices for React Router.
- Updated pytest and FastAPI best practices.
- Improved clarity and added sections for easier onboarding and consistency.

Generated-by: aiautocommit

Author: iloveitaly

.cursor/rules/pytest-integration-tests.mdc

@@ -9,3 +9,4 @@ alwaysApply: false
   - Here's an example of how to create + persist a factory `DistributionFactory.build(domain=PYTHON_TEST_SERVER_HOST).save()`
 - Add the `server` factory to each test
 - Use the `faker` factory to generate emails, etc.
+- Don't add obvious `assert` descriptions

.cursor/rules/typescript.mdc

@@ -10,3 +10,15 @@ alwaysApply: false
 - Use `lib/` for generic code, `utils/` for project utilities, `hooks/` for React hooks, and `helpers/` for page-specific helpers.
 - Prefer `function theName() {` over `const theName = () =>`
 - Use `import { invariant } from @epic-web/invariant` instead of another invariant library
+
+Here's how frontend code is organized in `web/app/`:
+
+- `lib/` not specific to the project. This code could be a separate package at some point.
+- `utils/` project-specific code, but not specific to a particular page.
+- `helpers/` page- or section-specific code that is not a component, hook, etc.
+- `hooks/` react hooks.
+- `configuration/` providers, library configuration, and other setup code.
+- `components/` react components.
+  - `ui/` reusable ShadCN UI components (buttons, forms, etc.).
+  - `shared/` components shared across multiple pages.
+  - create additional folders for route- or section-specific components.

instructions.md

@@ -36,6 +36,40 @@ session_id = client_secret_id.split("_secret")[0]
 - When running python tests, use an already open terminal and the `pytest` binary.
 - If you added models, generate a migration with `just migration {add,delete,update}_model_other_description`
 
+## Fastapi
+
+- When throwing a `HTTPException`, do not add a `detail=` and use a named status code (`status.HTTP_400_BAD_REQUEST`)
+- Do not return a `dict`, instead create a `class RouteNameResponse`
+
+## Pytest Integration Tests
+
+- Look to tests/factories.py to generate any required database state
+  - Here's an example of how to create + persist a factory `DistributionFactory.build(domain=PYTHON_TEST_SERVER_HOST).save()`
+- Add the `server` factory to each test
+- Use the `faker` factory to generate emails, etc.
+- Don't add obvious `assert` descriptions
+
+## Python App
+
+* Files within `app/commands/` should have:
+  * Are not designed for CLI execution, but instead are interactor-style internal commands.
+  * Should not be used on the queuing system
+  * A `perform` function that is the main entry point for the command.
+  * Look at existing commands for examples of how to structure the command.
+  * Use `TypeIDType` for any parameters that are IDs of models.
+* Files within `app/jobs/` should have:
+  * Are designed for use on the queuing system.
+  * A `perform` function that is the main entry point for the job.
+  * Look at existing jobs for examples of how to structure the job.
+  * Use `TypeIDType | str` for any parameters that are IDs of models.
+* When referencing a command, use the full-qualified name, e.g. `app.commands.transcript_deletion.perform`.
+* When queuing a job or `perform`ing it in a test, use the full-qualified name, e.g. `app.jobs.transcript_deletion.perform`.
+
+## Python Route Tests
+
+- Polyfactory is the [factory](tests/factories.py) library in use. `ModelNameFactory.build()` is how you generate factories.
+- Use `assert_status(response)` to check the response of a client
+
 ## Python
 
 When writing Python:
@@ -100,33 +134,64 @@ class Distribution(
         return self.where(Order.distribution_id == self.id).count()
 ```
 
-## Python App
+## React Router
 
-* Files within `app/commands/` should have:
-  * Are not designed for CLI execution, but instead are interactor-style internal commands.
-  * Should not be used on the queuing system
-  * A `perform` function that is the main entry point for the command.
-  * Look at existing commands for examples of how to structure the command.
-  * Use `TypeIDType` for any parameters that are IDs of models.
-* Files within `app/jobs/` should have:
-  * Are designed for use on the queuing system.
-  * A `perform` function that is the main entry point for the job.
-  * Look at existing jobs for examples of how to structure the job.
-  * Use `TypeIDType | str` for any parameters that are IDs of models.
-* When referencing a command, use the full-qualified name, e.g. `app.commands.transcript_deletion.perform`.
-* When queuing a job or `perform`ing it in a test, use the full-qualified name, e.g. `app.jobs.transcript_deletion.perform`.
+- You are using the latest version of React Router (v7).
+- The primary export in a routes file should specify `loaderData` like `export default function RouteNamePage({ loaderData }: Route.ComponentProps)`. `loaderData` is the return value from `clientLoader`.
+- Use `href("/products/:id", { id: "abc123" })` to generate a url path for a route managed by the application.
+  - Look at [routes.ts](mdc:web/app/routes.ts) to determine what routes and path parameters exist.
+- Use `export async function clientLoader(loaderArgs: Route.ClientLoaderArgs)` to define a `clientLoader` on a route.
+- Do not define `Route.*` types, these are autogenerated and can be imported from `import type { Route } from "./+types/routeFileName"`
+- If URL parameters or query string values need to be checked before rendering the page, do this in a `clientLoader` and not in a `useEffect`
+- Never worry about generating types using `pnpm`
+- Use [`<AllMeta />`](web/app/components/shared/AllMeta.tsx) instead of MetaFunction or individual `<meta />` tags
+- Use the following pattern to reference query string values (i.e. `?theQueryStringParam=value`)
 
-## Pytest Integration Tests
+```typescript
+const [searchParams, _setSearchParams] = useSearchParams();
+// searchParams contains the value of all query string parameters
+const queryStringValue = searchParams.get("theQueryStringParam")
+```
 
-- Look to tests/factories.py to generate any required database state
-  - Here's an example of how to create + persist a factory `DistributionFactory.build(domain=PYTHON_TEST_SERVER_HOST).save()`
-- Add the `server` factory to each test
-- Use the `faker` factory to generate emails, etc.
+### Loading Mock Data
 
-## Fastapi
+Don't load mock data in the component function with `useEffect`. Instead, load data in a `clientLoader`:
 
-- When throwing a `HTTPException`, do not add a `detail=` and use a named status code (`status.HTTP_400_BAD_REQUEST`)
-- Do not return a `dict`, instead create a `class RouteNameResponse`
+```typescript
+
+// in mock.ts
+export async function getServerData(options: any) {
+  // ...
+}
+
+// in web/app/routes/**/*.ts
+export async function clientLoader(loaderArgs: Route.ClientLoaderArgs) {
+  // no error reporting is needed, this will be handled by the `getServerData`
+  // mock loading functions should return result in a `data` key
+  const { data } = await getServerData({ /* ... */ })
+
+  // the return result here is available in `loaderData`
+  return data
+}
+```
+
+### How to use clientLoader
+
+- `export async function clientLoader(loaderArgs: Route.ClientLoaderArgs) {`
+- Load any server data required for page load here, not in the component function.
+- Use `return redirect(href("/the/url"))` to redirect users
+- Use [getQueryParam](web/app/lib/utils.ts) to get query string variables
+- `throw new Response` if you need to mimic a 400, 500, etc error
+- `loaderArgs` and all sub-objects are all fully typed
+- `loaderArgs.params.id` to get URL parameters
+
+### Using API Data
+
+- `~/configuration/client` re-exports all types and functions from `client/*`. Import from `~/configuration/client` instead of anything you find in the `client/` folder/package.
+- For each API endpoint, there's a fully typed async function that can be used to call it. Never attempt to call an API endpoint directly.
+- When using an import from `~/configuration/client`:
+  - use `body:` for request params
+  - always `const { data, error } = await theCall()`
 
 ## React
 
@@ -199,69 +264,6 @@ return (
 )
 ```
 
-## React Router
-
-- You are using the latest version of React Router (v7).
-- The primary export in a routes file should specify `loaderData` like `export default function RouteNamePage({ loaderData }: Route.ComponentProps)`. `loaderData` is the return value from `clientLoader`.
-- Use `href("/products/:id", { id: "abc123" })` to generate a url path for a route managed by the application.
-  - Look at [routes.ts](mdc:web/app/routes.ts) to determine what routes and path parameters exist.
-- Use `export async function clientLoader(loaderArgs: Route.ClientLoaderArgs)` to define a `clientLoader` on a route.
-- Do not define `Route.*` types, these are autogenerated and can be imported from `import type { Route } from "./+types/routeFileName"`
-- If URL parameters or query string values need to be checked before rendering the page, do this in a `clientLoader` and not in a `useEffect`
-- Never worry about generating types using `pnpm`
-- Use [`<AllMeta />`](web/app/components/shared/AllMeta.tsx) instead of MetaFunction or individual `<meta />` tags
-- Use the following pattern to reference query string values (i.e. `?theQueryStringParam=value`)
-
-```typescript
-const [searchParams, _setSearchParams] = useSearchParams();
-// searchParams contains the value of all query string parameters
-const queryStringValue = searchParams.get("theQueryStringParam")
-```
-
-### Loading Mock Data
-
-Don't load mock data in the component function with `useEffect`. Instead, load data in a `clientLoader`:
-
-```typescript
-
-// in mock.ts
-export async function getServerData(options: any) {
-  // ...
-}
-
-// in web/app/routes/**/*.ts
-export async function clientLoader(loaderArgs: Route.ClientLoaderArgs) {
-  // no error reporting is needed, this will be handled by the `getServerData`
-  // mock loading functions should return result in a `data` key
-  const { data } = await getServerData({ /* ... */ })
-
-  // the return result here is available in `loaderData`
-  return data
-}
-```
-
-### How to use clientLoader
-
-- `export async function clientLoader(loaderArgs: Route.ClientLoaderArgs) {`
-- Load any server data required for page load here, not in the component function.
-- Use `return redirect(href("/the/url"))` to redirect users
-- Use [getQueryParam](web/app/lib/utils.ts) to get query string variables
-- `throw new Response` if you need to mimic a 400, 500, etc error
-- `loaderArgs` and all sub-objects are all fully typed
-- `loaderArgs.params.id` to get URL parameters
-
-### Using API Data
-
-- `~/configuration/client` re-exports all types and functions from `client/*`. Import from `~/configuration/client` instead of anything you find in the `client/` folder/package.
-- For each API endpoint, there's a fully typed async function that can be used to call it. Never attempt to call an API endpoint directly.
-- When using an import from `~/configuration/client`:
-  - use `body:` for request params
-  - always `const { data, error } = await theCall()`
-
-## React Router Client Loader
-
-Do this in a `clientLoader` and use `loaderData` to render the component. DO NOT create mock data, new interfaces, or mock data loader functions. Instead, assume `loaderData` has all of the data you need to render the component.
-
 ## Shell
 
 - Assume zsh for any shell scripts. The latest version of modern utilities like ripgrep (rg), fdfind (fd), bat, httpie (http), zq (zed), jq, procs, rsync are installed and you can request I install additional utilities.
@@ -274,37 +276,15 @@ Do this in a `clientLoader` and use `loaderData` to render the component. DO NOT
 - Prefer `function theName() {` over `const theName = () =>`
 - Use `import { invariant } from @epic-web/invariant` instead of another invariant library
 
-## Typescript Docstring
-
-Add a file-level docstring with a simple description of what this file does and where this is used.
-
-## Secrets
-
-Here's how environment variables are managed in this application:
-
-- `.envrc` entry point to load the correct env stack. Should not contain secrets and should be simple some shell logic and direnv stdlib calls.
-- `.env` common configuration for all systems. No secrets. No dotenv/custom scripts. Just `export`s to modify core configuration settings like `export TZ=UTC`.
-- `.env.local` overrides across all environments (dev and test). Useful for things like 1Password service account token and database hosts which mutate the logic followed in `.env.shared`. Not committed to source control.
-- `.env.shared` This contains the bulk of your system configuration. Shared across test, CI, dev, etc but not production.
-- `.env.shared.local` Override `.env.shared` configuration locally. Not committed to source.
-- `.env.dev.local` configuration overrides for non-test environments. `PYTHONBREAKPOINT`, `LOG_LEVEL`, etc. Most of your environment changes end up happening here.
-- `.env.test` test-only environment variables (`PYTHON_ENV=test`). This file should generally be short.
-- `.env.production.{backend,frontend}` for most medium-sized projects you'll have separate frontend and backend systems (even if your frontend is SPA, which I'm a fan of). These two files enable you to document the variables required to build (in the case of a SPA frontend) or run (in the case of a python backend) your system in production.
-- `*.local` files have a `-example` variant which is committed to version control. These document helpful environment variables for local development.
-- When writing TypeScript/JavaScript/React, use `requireEnv("THE_ENV_VAR_NAME")` to read an environment variable. `import {requireEnv} from '~/utils/environment'`
-
-## Implement Fastapi Routes
-
-The file docstring contains a description of the FastAPI routes we need to implement. Implement these routes.
-
-Avoid implementing any Stripe logic right now. I will do that later. Leave TODOs for this and other areas where you are very unsure of what to do.
-
-## Python Route Tests
-
-- Polyfactory is the [factory](tests/factories.py) library in use. `ModelNameFactory.build()` is how you generate factories.
-- Use `assert_status(response)` to check the response of a client
-
-## Refactor On Instructions
-
-Refactor this code following all the established coding rules. Carefully review each rule.
+Here's how frontend code is organized in `web/app/`:
+
+- `lib/` not specific to the project. This code could be a separate package at some point.
+- `utils/` project-specific code, but not specific to a particular page.
+- `helpers/` page- or section-specific code that is not a component, hook, etc.
+- `hooks/` react hooks.
+- `configuration/` providers, library configuration, and other setup code.
+- `components/` react components.
+  - `ui/` reusable ShadCN UI components (buttons, forms, etc.).
+  - `shared/` components shared across multiple pages.
+  - create additional folders for route- or section-specific components.