.cursorrules

You are an expert in TypeScript, Node.js, Next.js App Router, React, Shadcn UI, Radix UI and Tailwind.

# Code Style and Structure

- Write concise, technical TypeScript code with accurate examples.
- Use functional and declarative programming patterns; avoid classes.
- Prefer iteration and modularization over code duplication.
- Use descriptive variable names with auxiliary verbs (e.g., isLoading, hasError).
- Structure files: exported component, subcomponents, helpers, static content, types.

# Code & Naming Conventions

- Use lowercase with dashes for directories (e.g., components/auth-wizard).
- Favor named exports for components.
- When adding "convenience" methods for e.g. fetching data in a file, always add at bottom.

# UI and Styling

- Use Shadcn UI, Radix, and Tailwind for components and styling.
- Use components from /app/src/layout whenevery possible to improve code-reuse
- Implement responsive design with Tailwind CSS; use a mobile-first approach.
- Optimize Web Vitals (LCP, CLS, FID).

# Database Schema

- We use drizzle-orm for interacting with our database.
- The entire schema is located in `@/drizzle/schema.ts`.
- Always preferthe query-syntax of drizzle, only as a last resort use raw SQL.
- As much as possible run queries using Promise.all to optimize endpoints.
- Never use direct database transactions, instead use guards with where-statements and check return results.

# tRPC endpoints

- Backend calls use tRPC routes, installed at `@/server/api/root.ts`
- Use tRPC endpoints across the codebase to ensure consistency.
- Always check other tRPC endpoints across the codebase to ensure you are not duplicating endpoints
- Always check other tRPC endpoints to ensure you are conforming to the same structure and naming conventions.
- Prefer to structure mutations such that they are separated into steps; queries->guards->mutation
- For mutations set the output to `baseServerResponse` from `@/server/api/trpc`

# Codebase folder logic

- `/app/src/app`: this is where all the pages are located
- `/app/src/libs`: this contains code related to specific features in the game
- `/app/src/utils`: this contains utility functions used across the codebase
- `/app/src/hooks`: here all custom hooks are placed
- `/app/src/validators`: here we place zod-schemas & inferred types, which are useful for sharing between UI and corresponding tRPC endpoints.
- `/app/src/components`: the (slightly) modified shadcn layout components
- `/app/src/layout`: more custom layout components pertaining to the codebase.

# Permissions

We try to aggregate all permission controls for who is allowed to do what in `/app/src/utils/permissions.ts`.

# Combat System layout

A particularly complex feature in the game is the combat system, which thus also warrents further explanation.

- `/app/src/server/api/routers/combat.ts`: this is the main entry point to understanding the logic of the combat system. This file defines the `initiateBattle` function which is used across multiple routes for initiating battles between users or between a user and an AI. It also defined the `performAction` endpoint, which is what controls the logic of what happens when an action is performed by a user in combat.

- `/app/src/libs/combat/actions.ts`: this file contains all the logic pertaining to the user actions in combat; i.e. figuring out which actions are available, figuring out which user has to make the next action, inserting the action into the database, etc.

- `/app/src/libs/combat/process.ts`: this file contains the logic for processing a round, i.e. applying all the ground and users effects on the user. The logic of all the applied effects are defined separately in the `tags.ts` file.

- `/app/src/libs/combat/tags.ts`: this file defined the logic of each tag (effect) in the game, e.g. damage, shield, heal, etc.

- `/app/src/libs/combat/types.ts`: this file defines various zod schemas and types relevant across the combat system. This is also where the tag types are defines in terms of zod schemas; i.e. their schema and type is defined in the `types.ts` file, and their logic in the `tags.ts` file.

- `/app/src/libs/combat/util.ts`: this file contains various utility functions used throughout the combat system both on the backend and frontend code.

- `/app/src/libs/combat/drawing.ts`: this file contains functionality specifically related to drawing the combat system on the frontend using ThreeJS.

- `/app/src/libs/combat/database.ts`: this file collects all utility functions for updating the database. These are collected here so as to make it easier to ensure that we call database updates not all across the combat system, but preferably only once in parallel on entry, and once in parallel on mutating the state.

- `/app/src/libs/combat/ai_v2.ts`: This file contains the logic for how the AI behaves in combat and which actions it takes. It's based off a sequential rule-based system.

- `/app/src/libs/combat/movement.ts`: TO BE MOVED to `/app/src/libs/combat/util.ts`
- `/app/src/libs/combat/constants.ts`: TO BE MOVED to `@/drizzle/constants`
- `/app/src/libs/combat/ai_v1.ts`: Deprecated