Thor Code Patterns
Architectural patterns specific to the Thor trading bot. These define how features are built — the data flow, library wiring, and conventions that every new piece of code should follow.
For universal React/JS performance rules, see docs/react-best-practices/SKILL.md.
Patterns
| Pattern | File | Scope |
|---|---|---|
| Error Handling | error-handling.md | AppErrorCode enum, TRPCError with structured cause, BFF error propagation, 6 UI error display channels |
| tRPC Router & Procedures | trpc.md | Domain-based routers, procedure naming, two-hop subscription demux, middleware chain, full procedure listing |
| Type System | type-system.md | Zod 4 .meta(), compositional atoms, branded types, decimal.js serialization, no as/any, as const satisfies, parse-at-boundaries |
| Database Access | database.md | Thin service layer, transaction composability, soft delete, baseColumns/auditColumns, Drizzle schema files |
| BullMQ Jobs | bullmq.md | Self-contained job files, queue naming, retry/backoff/timeout, dual-write results (DB + SSE) |
| Environment & Configuration | env-config.md | Zod-validated env vars, Pydantic BaseSettings, runtime config boundary, constants strategy |
| Logging & Correlation | logging.md | Pino base logger, OTel trace ID correlation, request-scoped children, log levels, standard log shapes |
| React Components | react.md | Route loader prefetch, query + subscription bridge hooks, TanStack Form flow, loading/error/empty states, table pagination |
| Events & Subscriptions | events.md | Typed event envelope (15 types), mitt emitter, three-layer SSE pipeline, domain-filtered BFF subscriptions |
| Testing (Universal) | testing.md | File location, naming, two-layer factories, mocking strategy, test structure conventions, superfluous test detection, broad-to-narrow debugging |
| Unit & Integration Testing | testing-unit-integration.md | RTL query priority, userEvent, async handling, custom hooks, timers, forms, MSW tRPC interception, tRPC procedure tests, testcontainers, Python conventions |
| E2E Testing | testing-e2e.md | Playwright file organization, storageState auth, selector priority, waiting strategies, tRPC API mocking, test isolation, axe-core a11y |
| Code Review | code-review.md | Review workflow, severity levels, review area → rule file mapping, TanStack Start-specific review points, when NOT to flag |
| Forms | form.md | TanStack Form validation, Standard Schema gotchas, defaultValues reset bug, dual-error system, persistence, operation ID cancellation |
| UI Components | ui-components.md | CVA variants, HugeIcons, theme tokens, shadcn/ui directory structure, component catalog, adding new components |
| Project Structure | project-structure.md | Placement rules, path aliases, model domain structure, expected domains, utility functions layer |
| Auth & Security | auth.md | Session cache busting, server-side auth authority, sign-out invalidation, auth file locations |