AGENTS.md

1Coding instructions for all programming languages:
2 
3- Never use emojis anywhere unless explicitly requested.
4- If no language is specified, assume the latest version of python.
5- If tokens or other secrets are needed, pull them from an environment variable
6- Prefer early returns over nested if statements.
7- Prefer `continue` within a loop vs nested if statements.
8- Prefer smaller functions over larger functions. Break up logic into smaller chunks with well-named functions.
9- Prefer constants with separators: `10_000` is preferred to `10000` (or `10_00` over `1000` in the case of a integer representing cents).
10- Only add comments if the code is not self-explanatory. Do not add obvious comments.
11- Do not remove existing comments.
12- Do not capitalize or add periods at the end of single-line comments.
13- When I ask you to write code, prioritize simplicity and legibility over covering all edge cases, handling all errors, etc.
14- When a particular need can be met with a mature, reasonably adopted and maintained package, I would prefer to use that package rather than engineering my own solution.
15- Never add error handling to catch an error without being asked to do so. Fail hard and early with assertions and allow exceptions to propagate.
16- When naming variables or functions, use names that describe the effect. For example, instead of `function handleClaimFreeTicket` (a function which opens a dialog box) use `function openClaimFreeTicketDialog`.
17- Do not install missing system packages! Instead, ask me to install them for you.
18- If terminal commands are failing because of missing variables or commands which are unrelated to your current task, stop your work and let me know.
19- Don't worry about fixing lint errors or running lint scripts unless I specifically ask you to.
20- When implementing workarounds for tooling limitations (like using `Any` for unresolvable types) or handling non-obvious edge cases, always add a brief inline comment explaining the technical reasoning.
21- Reserve exact-width `#`-box section separators for long files requiring organization, though they should not be necessary in the large majority of cases (separate files is generally better).
22 
23Use line breaks to organize code into logical groups. Instead of:
24 
25```python
26if not client_secret_id:
27    raise HTTPException(status.HTTP_400_BAD_REQUEST)
28session_id = client_secret_id.split("_secret")[0]
29```
30 
31Prefer:
32 
33```python
34if not client_secret_id:
35    raise HTTPException(status.HTTP_400_BAD_REQUEST)
36 
37session_id = client_secret_id.split("_secret")[0]
38```
39 
40**DO NOT FORGET**: keep your responses short, dense, and without fluff. I am a senior, well-educated software engineer, and hate long explanations.
41 
42### Add Comments for Expert Engineer with Limited Domain Knowledge
43 
44The engineer reading your code is a world-class software engineer, but is not familiar with the internals of every system. Include concise one-line comments explaining key hooks, API usage, blocks of logic, etc., to help the reader quickly understand the code you've written.
45 
46In other words, embed the business requirements as comments in the code when the code does not self-document.
47 
48### Important Workflow Rules
49 
50Pay careful attention to these instructions when running tests, generating database migrations, or otherwise figuring out how to operate this project:
51 
52- Run `just` to understand the more important workflow commands.
53  - Run `just --list` to see all available pre-written workflow development commands.
54- **IMPORTANT:** Never manually set environment variables that are required. You can set optional variables for debugging, but any missing required environment variables is an error that should be reported and you should stop your work immediately.
55- **NEVER** git commit changes. Always let me run any git commands which are not read-only.
56- Do not worry about cleaning up the environment. This is done automatically.
57- Run python code with `uv run python`
58- Use `pytest` to run tests. If tests fail because of a configuration, environment, or system error: let me know and stop working.
59  - Initially run `pytest --ignore=tests/integration` then only run `pytest tests/integration`
60  - When debugging integration tests look at `$PLAYWRIGHT_RESULT_DIRECTORY`. There's a directory for each test failure. In that directory you fill find a `failure.html` containing the rendered DOM of the page on failure and a screenshot of the contents. Use these to debug why it failed.
61- Do not attempt to create or run database migrations. Pause your work and let me know you need a migration run.
62  - If you receive errors about missing migrations, missing tables, database connectivity, etc, stop your work and let me know.
63 
64 
65## Alembic Migrations
66 
67 
68### Default Content for New Non-Nullable Columns
69 
70To add a non-nullable column and set a specific value for all existing rows without a persistent server default:
71 
72```python
73# 1. Add the column as nullable (no default needed):
74op.add_column('distribution', sa.Column('default_campaign_ending_date', sa.DateTime(timezone=True), nullable=True))
75# 2. Update existing rows with your desired value (e.g., a specific datetime)
76op.execute("UPDATE distribution SET default_campaign_ending_date = %s", [datetime.utcnow()])
77# 3. Alter the column to non-nullable:
78op.alter_column('distribution', 'default_campaign_ending_date', nullable=False)
79```
80 
81### Record Backfill Operations
82 
83For migrations that include data mutation, and not only schema modifications, use this pattern to setup a session:
84 
85```python
86from alembic import op
87from sqlmodel import Session
88from activemodel.session_manager import global_session
89from app import log
90 
91def run_migration_helper():
92  pass
93 
94def upgrade() -> None:
95  session = Session(bind=op.get_bind())
96 
97  with global_session(session):
98      run_migration_helper()
99      flip_point_coordinates()
100      backfill_screening_host_data()
101 
102  # flush before running any other operations, otherwise not all changes will persist to the transaction
103  session.flush()
104```
105 
106However, if you don't need the business logic attached to the models, you can execute a query using `op.execute`:
107 
108```python
109op.execute(
110  TheModel.__table__.update().values({"a_field": "a_value"}) # type: ignore
111)
112```
113 
114 
115## Fastapi
116 
117 
118- When throwing a `HTTPException`, do not add a `detail=` and use a named status code (`status.HTTP_400_BAD_REQUEST`)
119- Do not return a `dict`, instead create a `class RouteNameResponse`
120  - Locate these classes right above the `def route_name():` function which uses them.
121- Use `Model.one` when a record must exist in order for the business logic to succeed.
122- Do not try/except `Model.one` when using a parameter from the request to pull a record. Let this exception bubble up.
123- Use `model_id: Annotated[TypeID, Path()]` to represent a model ID as a URL path parameter
124- Use the typed route helpers in `app/generated/fastapi_typed_routes.py` for all URL generation.
125 
126 
127## Justfiles
128 
129 
130- Never use `just_executable()` to reference the executable for `just`. If `just` DNE, then something is wrong adn you should stop your work and let me know.
131- You should not have to mutate `$PATH`. If you cannot find an expected binary, stop your work and let me know.
132 
133 
134## Python App
135 
136 
137- `app/lib/` is for code that is not specified to this application and with some effort could extracted into a external package.
138- `app/helpers` is for larger reusable modules that if they weren't specific to this application, could be extracted into their own package.
139- `app/utils` are small helper functions that are specific to a particular page or area of the application.
140- `app/__init__.py` is the entrypoint for the application which is run when _anything_ is executed (fastapi, celery, etc).
141  - It primarily runs `configure_*` commands for any `app.configuration.*` modules. These modules primary setup API clients, database connections, python language configuration, etc.
142  - Also makes sure anything that mutates global state loads early.
143- FastAPI server and routes are specified in `app/routes/`
144- SQLModels are specified in `app/models/`
145- Files within `app/commands/` should have:
146  - Are not designed for CLI execution, but instead are interactor-style internal commands.
147  - Should not be used on the queuing system
148  - A `perform` function that is the main entry point for the command.
149  - Look at existing commands for examples of how to structure the command.
150  - Use `TypeID` for any parameters that are IDs of models.
151- Files within `app/jobs/` should have:
152  - Are designed for use on the queuing system.
153  - A `perform` function that is the main entry point for the job.
154  - Look at existing jobs for examples of how to structure the job.
155  - Use `TypeID | str` for any parameters that are IDs of models.
156- When referencing a command, use the full-qualified name, e.g. `app.commands.transcript_deletion.perform`.
157- When queuing a job or `perform`ing it in a test, use the full-qualified name, e.g. `app.jobs.transcript_deletion.perform`.
158- `app/cli/` is for scripts or CLI tools that are specific to the application.
159 
160### Factories
161 
162globs: app/factories/**/.py
163 
164* Each model should get it's own file under app/factories/model_name.py
165* `ActiveModelFactory` (which is a polyfactory subclass) should be used.
166* Use `BaseFactory.__faker__` to generate more specific fake data for important fields (used in routes, etc)
167* Prefer `slug = BaseFactory.__faker__.unique.slug` to `slug = Use(lambda: BaseFactory.__faker__.unique.slug())`
168 
169#### Factory Example
170 
171```python
172class ScreeningFactory(ActiveModelFactory[Screening]):
173    funding_goal = lambda: BaseFactory.__faker__.random_int(
174        min=0, max=2000_00
175    )
176 
177    ticket_price = DEFAULT_TICKET_PRICE
178    status = ScreeningStatus.active
179 
180    # always None
181    funding_ending_at = None
182 
183    # pick entry from a fixed list
184    zip_code = lambda: BaseFactory.__faker__.random_element(elements=REAL_ZIP_CODES)
185 
186    host_name = BaseFactory.__faker__.name
187    host_description = lambda: BaseFactory.__faker__.paragraph(nb_sentences=2)
188 
189    # this method runs before the model is persisted to the database
190    @classmethod
191    def post_build(cls, model):
192      # if the user does not pass in a important relationship during creation, you can generate a factory fallback
193        if not model.distribution_id:
194            model.distribution_id = DistributionFactory.save().id
195 
196        return model.save()
197 
198    # runs after the model is persisted to the database
199    @classmethod
200    def post_save(cls, model):
201        return model.save()
202```
203 
204### Database & ORM
205 
206When accessing database records:
207 
208* SQLModel (wrapping SQLAlchemy) is used
209* `Model.one(primary_key)` or `Model.get(primary_key)` should be used to retrieve a single record
210* Do not manage database sessions, these are managed by a custom tool
211  * Use `TheModel(...).save()` to persist a record
212  * Use `TheModel.where(...).order_by(...)` to query records. `.where()` returns a SQLAlchemy select object that you can further customize the query.
213  * To iterate over the records, you'll need to end your query chain with `.all()` which returns an interator: `TheModel.where(...)...all()`
214* Instead of repulling a record `order = HostScreeningOrder.one(order.id)` refresh it using `order.refresh()`
215 
216When writing database models:
217 
218* Don't use `Field(...)` unless required (i.e. when specifying a JSON type for a `dict` or pydantic model using `Field(sa_type=JSONB)`). For instance, use `= None` instead of `= Field(default=None)`.
219* Add enum classes close to where they are used, unless they are used across multiple classes (then put them at the top of the file)
220* Use `ModelName.foreign_key()` when generating a foreign key field
221* Store currency as an integer, e.g. $1 = 100.
222* `before_save`, `after_save(self):`, `after_updated(self):` are lifecycle methods (modelled after ActiveRecord) you can use.
223 
224Example:
225 
226```python
227class Distribution(
228    BaseModel, TimestampsMixin, SoftDeletionMixin, table=True
229):
230    """Triple-quoted strings for multi-line class docstring"""
231 
232    id: TypeID[Literal["dst"]] = TypeIDPrimaryKey("dst")
233 
234    date_field_with_comment: datetime | None = None
235    "use a string under the field to add a comment about the field"
236 
237    # no need to add a comment about an obvious field; no need for line breaks if there are no field-level docstrings
238    title: str = Field(unique=True)
239    state: str
240 
241    optional_field: str | None = None
242 
243    # here's how relationships are constructed
244    doctor_id: TypeID = Doctor.foreign_key()
245    doctor: Doctor = Relationship()
246 
247    @computed_field
248    @property
249    def order_count(self) -> int:
250        return self.where(Order.distribution_id == self.id).count()
251```
252 
253 
254## Python
255 
256 
257When writing Python:
258 
259* Assume the latest python, version 3.13.
260* Prefer Pathlib methods (including read and write methods, like `read_text`) over `os.path`, `open`, `write`, etc.
261* Prefer docstr to multi-line comments at the top of a function or file.
262* If a docstr does not span multiple lines, do not use triple-quoted strings.
263* Do not create `__init__` files unless specifically instructed
264* Use Pydantic models over dataclass or a typed dict.
265* Use SQLAlchemy for generating any SQL queries.
266* Use `click` for command line argument parsing.
267* Use `log.info("the message", the_variable=the_variable)` instead of `log.info("The message: %s", the_variable)` or `print` for logging. This object can be found at `from app import log`.
268  * Log messages should be lowercase with no leading or trailing whitespace.
269  * No variable interpolation in log messages.
270  * Do not coerce database IDs, dates, or Path objects to `str`
271* Do not fix import ordering or other linting issues.
272* Never edit or create any files in `migrations/versions/`
273* Place all comments on dedicated lines immediately above the code statements they describe. Avoid inline comments appended to the end of code lines.
274* Do not `try/catch` raw `Exceptions` unless explicitly told to. Prefer to let exceptions raise and cause an explicit error.
275* Always make an explicit copy before mutating a dictionary that you did not create in the current narrow scope.
276* Never use `from __future__`
277* Always use `re.compile(pattern, re.VERBOSE)` and inline `#` comments to document the logic of each capture group or condition in any complex regular expression.
278* **IMPORTANT** never edit app/generated/ files. These are autogenerated.
279 
280### Package Management
281 
282- Use `uv add` to add python packages. No need for `pip compile`, `pip install`, etc.
283 
284### Typing
285 
286* Assume the latest pyright version
287* Prefer modern typing: `list[str]` over `List[str]`, `dict[str, int]` over `Dict[str, int]`, etc.
288* Prefer to keep typing errors in place than eliminate type specificity:
289  * Do not add ignore comments such as `# type: ignore`
290  * Never add an `Any` type.
291  * Do not `cast(object, ...)`
292 
293### Data Manipulation
294 
295* Prefer `funcy` utilities to complex list comprehensions or repetitive python statements.
296* `import funcy as f` and `import funcy_pipe as fp`
297* Some utilities to look at: `f.compact`
298 
299For example, instead of:
300 
301```python
302params: dict[str, str] = {}
303if city:
304    params["city"] = city
305if state_code:
306    params["stateCode"] = state_code
307```
308 
309Use:
310 
311```python
312params = f.compact({"city": city, "stateCode": stateCode})
313```
314 
315### Date & DateTime
316 
317* Use the `whenever` library for datetime + time instead of the stdlib date library. `Instant.now().format_iso()`
318* DateTime mutation should explicitly opt in to a specific timezone `SystemDateTime.now().add(days=-7)`
319 
320 
321## React Router
322 
323 
324- You are using the latest version of React Router (v7).
325- Always include the suffix `Page` when naming the default export of a route.
326- 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`.
327- Use `href("/products/:id", { id: "abc123" })` to generate a url path for a route managed by the application.
328  - Look at [routes.ts](mdc:web/app/routes.ts) to determine what routes and path parameters exist.
329- Use `export async function clientLoader(loaderArgs: Route.ClientLoaderArgs)` to define a `clientLoader` on a route.
330- Do not define `Route.*` types, these are autogenerated and can be imported from `import type { Route } from "./+types/routeFileName"`
331- 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`
332- Never worry about generating types using `pnpm`
333- Use [`<AllMeta />`](web/app/components/shared/AllMeta.tsx) instead of MetaFunction or individual `<meta />` tags
334- Use the following pattern to reference query string values (i.e. `?theQueryStringParam=value`)
335 
336```typescript
337const [searchParams, _setSearchParams] = useSearchParams()
338// searchParams contains the value of all query string parameters
339const queryStringValue = searchParams.get("theQueryStringParam")
340```
341 
342### Loading Mock Data
343 
344Don't load mock data in the component function with `useEffect`. Instead, load data in a `clientLoader`:
345 
346```typescript
347// in mock.ts
348export async function getServerData(options: any) {
349  // ...
350}
351 
352// in web/app/routes/**/*.ts
353export async function clientLoader(loaderArgs: Route.ClientLoaderArgs) {
354  // no error reporting is needed, this will be handled by the `getServerData`
355  // mock loading functions should return result in a `data` key
356  const { data } = await getServerData({
357    /* ... */
358  });
359 
360  // the return result here is available in `loaderData`
361  return data;
362}
363```
364 
365### How to Use `clientLoader`
366 
367- `export async function clientLoader(loaderArgs: Route.ClientLoaderArgs) {`
368- Load any server data required for page load here, not in the component function.
369- Use `return redirect(href("/the/url"))` to redirect users
370- Use [getQueryParam](web/app/lib/utils.ts) to get query string variables
371- `throw new Response` if you need to mimic a 400, 500, etc error
372- `loaderArgs` and all sub-objects are all fully typed
373- `loaderArgs.params.id` to get URL parameters
374 
375### Loading Backend Data
376 
377- `~/configuration/client` re-exports all types and functions from `client/*`. Import from `~/configuration/client` instead of anything you find in the `client/` folder/package.
378- 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.
379  - Do not generate types for API parameters or responses. Reference the autogenerated types that are re-exported in `~/configuration/client`
380  - For instance, the `getSignedUrl` function in [web/client/sdk.gen.ts] has a `SignedUrlResponse` type in [web/client/types.gen.ts]
381  - This same type is used in the function signature, i.e. `type SignedUrlResponse = Awaited<ReturnType<typeof getSignedUrl>>["data"]`
382 
383- When using an import from `~/configuration/client`:
384  - use `body:` for request params
385  - always `const { data, error } = await theCall()`
386 
387`clientLoader` can only be used on initial page load within a route. If you need to load additional server data on component mount:
388 
389```tsx
390import { useQuery } from "@tanstack/react-query"
391import {
392  // these options correspond to the server route
393  createCheckoutSessionOptions,
394  publicClient,
395} from "~/configuration/client"
396 
397function TheComponent() {
398  const { data, error } = useQuery({
399    enabled: open,
400    ...createCheckoutSessionOptions({
401      // or `client` if authenticated
402      client: publicClient,
403      body: { /* API parameters here */ },
404    }),
405  })
406 
407  // remember to display errors by checking `error`
408}
409```
410 
411 
412## React
413 
414 
415- You are using the latest version of React (v19)
416- Do not write any backend code. Just frontend logic.
417- If a complex skeleton is needed, create a component function `LoadingSkeleton` in the same file.
418- Store components for each major page or workflow in `app/components/$WORKFLOW/$COMPONENT.tsx`.
419  - If a single page has more than two dedicated components, create a subfolder `app/components/$WORKFLOW/$PAGE/$COMPONENT.tsx`
420- Use lowercase dash separated words for file names.
421- Use React 19, TypeScript, Tailwind CSS, and ShadCN components.
422- Prefer function components, hooks over classes.
423- Use ShadCN components in `web/app/components/ui` as your component library. If you need new components, ask for them.
424  - Never edit the `web/components/ui/*.tsx` files.
425  - You can find a list of components here https://ui.shadcn.com/docs/components
426- Break up large components into smaller components, but keep them in the same file unless they can be generalized.
427- Put any "magic" strings like API keys, hosts, etc into a "constants.ts" file.
428- For React functional components with three or fewer props, always inline the prop types as an object literal directly in the function signature after the destructured parameters (e.g., `function Component({ prop1, prop2 }: { prop1: string; prop2?: number }) { ... })`. Include default values in destructuring and mark optional props with ? in the type object. Do not use separate interfaces or type aliases; keep types inline. For complex types, add inline comments if needed.
429- Put the interface definition right above the related function
430- Internally, store all currency values as integers and convert them to floats when rendering visually
431- When building forms use React Hook Form.
432- Include a two line breaks between any `useHook()` calls and any `useState()` definitions for a component.
433- When using a function prop inside a `useEffect`, please use a pattern that avoids including the function in the dependency array, like the `useRef` trick.
434- When writing React components, always hoist complex conditional expressions into descriptively named constants at the top of the component function for better readability and maintainability.
435- When managing API response data, store the entire response object (or relevant subset) in a single `useState` rather than creating separate state variables for each field. Derive individual values from the response object when passing to child components using optional chaining (e.g., response?.field || defaultValue).
436- Refactor ternary to &&: `{condition ? <A/> : <B/>}` → `{condition && <A/>}{!condition && <B/>}`
437- Use the following pattern to reference query string values (i.e. `?theQueryStringParam=value`):
438 
439```typescript
440const [searchParams, _setSearchParams] = useSearchParams();
441// searchParams contains the value of all query string parameters
442const queryStringValue = searchParams.get("theQueryStringParam")
443```
444 
445### Mock Data
446 
447- For any backend communication, create mock responses. Use a async function to return mock data that I will swap out later for a async call to an API.
448- When creating mock data, always specify it in a dedicated `web/app/mock.ts` file
449- Load mock data using a react router `clientLoader`. Use the Skeleton component to present a loading state.
450 
451### React Hook Form
452 
453Follow this structure when generating a form.
454 
455```tsx
456 
457// add a mock function simulating server communication
458async function descriptiveServerSendFunction(values: any) {
459  const mockData = getMockReturnData(/* ... */)
460  return new Promise(resolve => setTimeout(() => resolve(mockData), 500));
461}
462 
463const formSchema = z.object({
464  field_name: z.string(),
465  // additional schema definition
466})
467 
468const form = useForm<z.infer<typeof formSchema>>({
469  resolver: zodResolver(formSchema),
470})
471 
472const {
473  formState: { isSubmitting, errors },
474  setError,
475  clearErrors,
476} = form
477 
478 
479async function onSubmit(values: z.infer<typeof formSchema>) {
480  clearErrors("root")
481 
482  // ...
483  const { data, error } = await descriptiveSendFunction(values)
484 
485  if (error) {
486    setError("root.serverError", { message: error.detail?.[0]?.msg })
487    return
488  }
489  // ...
490}
491 
492return (
493  <Form {...form}>
494    <form onSubmit={form.handleSubmit(onSubmit)}>
495      {/* form fields */}
496 
497      <ServerErrorAlert error={errors.root?.serverError} />
498 
499      <Button
500        type="submit"
501        disabled={isSubmitting}
502      >
503        {isSubmitting ? "Submitting..." : "Submit"}
504      </Button>
505    </form>
506  </Form>
507)
508```
509 
510### Styling
511 
512* Use `text-blue-link` for styling any simple `<a>` tags
513 
514 
515## Shell
516 
517 
518- 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.
519 
520 
521## Typescript
522 
523 
524- Use `pnpm` or `pnpx` and not `npm` or `npx`.
525  - Use `just js_shadcn`, `just pnpm`, and `just js_lint` instead of executing these operations exactly. @just/javascript.just
526- Node libraries are not available
527- Use `lib/` for generic code, `utils/` for project utilities, `hooks/` for React hooks, and `helpers/` for page-specific helpers.
528- Prefer `function theName() {` over `const theName = () =>`
529- Use `import { invariant } from @epic-web/invariant` instead of another invariant library
530- Use `requireEnv("VITE_THE_ENV_VAR")` instead of `process.env.THE_ENV_VAR`
531- Don't use `console.{log,error}`. Use `from ~/configuration/logging import log` and `log.info("string", {structured: "log"})` instead.
532 
533Here's how frontend code is organized in `web/app/`:
534 
535- `lib/` not specific to the project. This code could be a separate package at some point.
536- `utils/` project-specific code, but not specific to a particular page.
537- `helpers/` page- or section-specific code that is not a component, hook, etc.
538- `hooks/` react hooks.
539- `configuration/` providers, library configuration, and other setup code.
540- `components/` react components.
541  - `ui/` reusable ShadCN UI components (buttons, forms, etc.).
542  - `shared/` components shared across multiple pages.
543  - create additional folders for route- or section-specific components.
544 
545### Dates & Times
546 
547* Always use the ISO 8601 format when sending dates in an API request.
548* Use `Temporal` for any date or time manipulation. You can assume it's available in the browser.
549* DateTime objects should always be converted to UTC before included in any API request. Never send a timestamp with the user's timezone.
550* Unless otherwise specified, do not shift server-provided times based on the user's timezone.
551