Cursor rule

1---
2description: Guidelines for creating typesafe apis on hono restful API.
3globs: apps/**/*.ts
4alwaysApply: false
5---
6# Backend API Architecture and Development Guidelines
7 
8You are an expert TypeScript backend engineer specializing in building modern, type-safe APIs. Your expertise covers Hono for HTTP routing, Drizzle ORM for database operations, and React Query for frontend integration.
9 
10<core_architecture>
11 
12<tech_stack>
13- **Server & Routing**: Hono
14- **Database ORM**: Drizzle with PostgreSQL
15- **RPCs**: TRPC
16- **Frontend Integration**: React Query
17- **Authentication**: Clerk
18- **Validation**: Zod with zValidator
19</tech_stack>
20 
21<project_structure>
22apps/
23  ├── backend/
24      ├── src/
25          ├── modules/           # Feature-based modules
26          │   ├── [module]/      # e.g., posts, webhooks
27          │   │   ├── [module].router.ts   # Route definitions
28          │   │   └── [module].service.ts  # Business logic & DB operations
29          ├── pkg/               # Shared utilities and middleware
30          └── index.ts          # Main application setup; must list new TRPC modules here.
31 
32packages/
33  └── db/
34      ├── src/
35      │   ├── schema.ts         # Database schema definitions
36      │   ├── types.ts          # Shared TypeScript types
37      │   ├── index.ts          # Main exports
38      │   └── util/             # Database utilities
39</project_structure>
40 
41<module_development_guidelines>
42### 1. Database layer
43- If the request needs a new column or addition database fields start by creating and updating schema.ts
44- Leverage types.ts inside packages/db to create new zod schemas for the newly created tables or columns and eg:
45```
46export type Post = InferSelectModel<typeof schema.posts>;
47export type NewPost = InferInsertModel<typeof schema.posts>;
48 
49export const postInsertSchema = createInsertSchema(schema.posts).omit({ userId: true });
50export const postSelectSchema = createSelectSchema(schema.posts);
51```
52 
53 
54### 2. Service Layer ([module].service.ts)
55- Implement business logic
56- Handle database operations using Drizzle
57- Return strongly typed responses
58- Keep services focused and modular
59- Import db from the `packages/db` 
60 
61Example service implementation:
62```ts
63`[module].service.ts`
64import { db, eq, items} from "@repo/db"
65 
66export const moduleService = {
67  async getItems() {
68    return db.select().from(items);
69  },
70  
71  async createItem(data: NewItem) {
72    return db.insert(items).values(data).returning();
73  }
74};
75```
76 
77 
78### 3. Route Layer ([module].router.ts)
79- Define endpoints using TRPC
80 
81After the route is created, you must add it to the `apps/backend/src/index.ts` route so its accessable by the frontend.
82 
83</module_development_guidelines>
84 
85<package_management>
86 
87- Use `pnpm` as the primary package manager for the project
88- Install dependencies using `pnpm add [package-name]`
89- Install dev dependencies using `pnpm add -D [package-name]`
90- Install workspace dependencies using `pnpm add -w [package-name]`
91</package_management>
92 
93<development_guidelines>
94### Running Scripts
95- Use `bun` as the runtime environment and script runner
96- Execute scripts defined in package.json using `bun run [script-name]`
97- Run TypeScript files directly using `bun [file.ts]`
98 
99### Monorepo 
100The project use turbo repo. To run everything, use the `turbo dev` script from the root folder.
101 
102### Type Safety
103- Use Drizzle schemas for database types
104- Share types between frontend and backend using a shared package
105- Leverage zod for runtime validation
106- Use TRPC for RPC type-safety
107 
108### Error Handling
109- Implement consistent error handlers
110- Use proper HTTP status codes
111- Return structured error responses
112- Handle edge cases appropriately
113- Use the logger from the package @repo/logger, i.e `logger.error` instead of `console.error`
114 
115### Authentication & Authorization
116- Use Clerk middleware for authentication
117- Implement role-based access control where needed
118- Validate user permissions at the route level
119- Keep authentication logic in middleware
120 
121### API Design Principles
122- Use TRPC for API connections between frontend and backend
123- Use consistent naming patterns
124- Implement proper request validation
125- Structure endpoints by resource/module
126- Keep routes clean and delegate logic to services
127 
128### Database Operations
129- Use Drizzle for all database interactions
130- Implement proper migrations
131- Handle transactions when needed
132- Write efficient queries
133- Use appropriate indexes
134</development_guidelines>
135 
136<dev_workflow>
137### Creating a New Module for different buisness logic
1381. Create module directory in api/src/modules/[module]
1392. Define routes in [module].router.ts
1403. Implement service logic in [module].service.ts
1414. Add route to main application in index.ts
1425. Create frontend integration in frontend/src/api/[module].api.ts
143</dev_workflow>
144 
145### Testing Requirements
146- If needed use vitest to create testing files inside of the modules, [module].test.ts 
147- 
148### Code Quality
149- For methods with more than one argument, use object destructuring: `function myMethod({ param1, param2 }: MyMethodParams) {...}`.
150</best_practices>
151 
152 
153<example_api_workflow>
154Router file:
155 
156tenants.router.ts
157```ts
158import { publicProcedure, router } from "../../trpc";
159import { tenantsService } from "./tenants.service";
160import { z } from "zod";
161 
162// Define the Tenant schema
163const TenantSchema = z.object({
164  id: z.string(),
165  name: z.string(),
166  createdAt: z.date(),
167  updatedAt: z.date().nullable(),
168});
169 
170export const tenantsRouter = router({
171  list: publicProcedure
172    .output(z.array(TenantSchema))
173    .query(async () => {
174      return tenantsService.list();
175    }),
176 
177  create: publicProcedure
178    .input(z.object({ name: z.string().min(1) }))
179    .output(TenantSchema)
180    .mutation(async ({ input }) => {
181      const result = await tenantsService.create(input);
182      if (!result) throw new Error('Failed to create tenant');
183      return result;
184    }),
185}); 
186```
187 
188tenants.service.ts
189```ts
190import { db, tenants } from "@repo/db";
191import { eq } from "drizzle-orm";
192 
193type NewTenant = typeof tenants.$inferInsert;
194 
195export const tenantsService = {
196  async list() {
197    try {
198      const results = await db.select().from(tenants);
199      return results ?? [];
200    } catch (error) {
201      console.error(error);
202      throw error;
203    }
204  },
205 
206  async create(data: Omit<NewTenant, "id" | "createdAt" | "updatedAt">) {
207    try {
208      const result = await db
209        .insert(tenants)
210        .values({
211          id: crypto.randomUUID(),
212          ...data,
213          createdAt: new Date(),
214          updatedAt: new Date(),
215        })
216        .returning();
217      return result[0];
218    } catch (error) {
219      console.error(error);
220      throw error;
221    }
222  },
223}; 
224```
225 
226tenants/page.tsx
227```ts
228"use client";
229 
230import { useTRPC } from "@/utils/trpc";
231import { useQuery, useMutation, useQueryClient } from "@tanstack/react-query";
232import { DataGrid, GridColDef } from '@mui/x-data-grid';
233import { Button } from "@/components/ui/button";
234import { Dialog, DialogContent, DialogHeader, DialogTitle, DialogFooter } from "@/components/ui/dialog";
235import { useState } from "react";
236import { Skeleton } from "@/components/ui/skeleton";
237 
238export default function TenantsPage() {
239  const trpc = useTRPC();
240  const queryClient = useQueryClient();
241  const { data: tenants, isLoading, error } = useQuery(trpc.tenants.list.queryOptions());
242  
243  const createMutation = useMutation({
244    ...trpc.tenants.create.mutationOptions(),
245    onSuccess: () => {
246      queryClient.invalidateQueries({ queryKey: trpc.tenants.list.queryKey() });
247    }
248  });
249 
250  const createTenant = () => createMutation.mutate({ name: "New Tenant" });
251 
252  ...
253 
254  <Button onClick={createTenant}>Add Tenant</Button>
255 
256  ...
257```
258</example_api_workflow>
259 
260 
261