---
description: 
globs: **/*.ts,**/*.tsx
alwaysApply: false
---
## Technologies used

- **React & Astro** - Build interactive UIs with React components in Astro
- **tRPC** - End-to-end type-safe APIs without schemas or code generation
- **Tailwind CSS** - Utility-first CSS framework for rapid UI development
- **TypeScript** - Full type safety across all packages
- **Turborepo** - High-performance build system for JavaScript/TypeScript monorepos
- **PNPM Workspaces** - Fast, disk-efficient package management
- **ESLint & Prettier** - Code quality tools configured and ready to use
- **Renovate** - Automated dependency updates
- **Auth** - We use better-auth
- **DB** - We use postgres and kysely as the client.

# Code Conventions

When writing or modifying code in this project, please adhere to the following conventions:

1.  **TypeScript Best Practices**: Follow standard, idiomatic TypeScript coding practices for structure, naming, and types, unless otherwise overridden.
2.  **Minimal Comments**: Avoid adding comments unless they explain complex logic or non-obvious decisions. Well-written, self-explanatory code is preferred. Do not add comments that merely restate what the code does.
3.  **Tests as Documentation**: Rely on comprehensive tests (which will be added later if not present) to document the behavior and usage of the code, rather than extensive comments within the code itself.
4. **File naming conventions**: Use kebab-case when naming directories, TypeScript, and other files. 
5. **Type checking**: after major modifications run `pnpm typecheck` and fix any errors.
6. **UX/UI** We are using Tailwind CSS, React, shadcn/ui components and Lucide React icons. Generate responsive designs. Provide default props for React Components. Check to see if a shadcn component exists under `apps/webs/src/components/ui` before installing it.
7. **Models/db/tables** When pulling in a database type, use:

```typescript
import type { Conversation } from '@app/db/types'
import type { Selectable } from 'kysely'

interface ConversationItemProps {
  conversation: Selectable<Conversation>
}
```

8. **Installing packages**. We are using a pnpm Monorepo or Workspace. Typically when you install a pnpm package, you'll want to install it either in an app or you'll install it inside of a package. For example `pnpm add uuid --filter @app/web && pnpm add -D @types/uuid --filter @app/web`

9. **Actions Pattern**: Organize server-side logic in the `packages/api/src/actions` directory following this structure:
   - **Getters** (`getters.ts`) - Functions that retrieve data from the database
   - **Setters** (`setters.ts`) - Functions that create or update data
   - **Validators** (`validators.ts`) - Functions that validate input data
   - **Checkers** (`checkers.ts`) - Functions that check permissions and authorization
   - **Domain-specific logic** - Additional files for complex business logic (e.g., `process-inbound.ts`)
   
   Example structure:
   ```
   packages/api/src/actions/emails/
   ├── getters.ts     # getProjectInboundEmailAddress()
   ├── setters.ts     # createProjectInboundEmailToken()
   ├── validators.ts  # validateMailgunWebhook()
   ├── checkers.ts    # assertProjectEmailPermission()
   └── process-inbound.ts  # processInboundEmail()
   ```

10. **API Exports for apps/web**: To make functions and types from `packages/api` available in `apps/web`, you MUST export them in `packages/api/src/index.ts`:

    ```typescript
    // packages/api/src/index.ts
    
    // Export functions
    export { processInboundEmail } from './actions/emails/process-inbound'
    export { getProjectInboundEmailAddress } from './actions/emails/getters'
    
    // Export types
    export type { MailgunWebhookSchema } from './actions/emails/process-inbound'
    ```

    Then in `apps/web`, import from `@app/api`:
    ```typescript
    // ✅ Correct - imports from the package export
    import { processInboundEmail, MailgunWebhookSchema } from '@app/api'
    
    // ❌ Wrong - direct file imports will fail
    import { processInboundEmail } from '@app/api/src/actions/emails/process-inbound'
    ```

    **Important**: If you forget to export in `index.ts`, the import will fail with linting/type errors.


Only make the exact changes I request—do not modify, remove, or alter any other code, styling, or page elements unless explicitly instructed. If my request conflicts with existing code, styling, or functionality, or if you anticipate any issues, pause execution and notify me for confirmation before proceeding. Always follow this rule for every modification. If in doubt, ask before making any change.