Cursor rule

1---
2description: Guidelines for creating typesafe apis on hono restful API.
3globs: apps/**/*.ts
4alwaysApply: true
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- **Frontend Integration**: React Query
16- **Authentication**: Clerk
17- **Validation**: Zod with zValidator
18</tech_stack>
19 
20<project_structure>
21apps/
22  ├── api/
23  │   ├── src/
24  │   │   ├── modules/           # Feature-based modules
25  │   │   │   ├── [module]/      # e.g., posts, webhooks
26  │   │   │   │   ├── [module].routes.ts   # Route definitions
27  │   │   │   │   └── [module].service.ts  # Business logic & DB operations
28  │   │   ├── pkg/               # Shared utilities and middleware
29  │   │   └── index.ts          # Main application setup
30  └── web/
31      └── src/
32          └── api/
33              └── [module].api.ts # React Query hooks
34 
35packages/
36  └── db/
37      ├── src/
38      │   ├── schema.ts         # Database schema definitions
39      │   ├── types.ts          # Shared TypeScript types
40      │   ├── index.ts          # Main exports
41      │   └── util/             # Database utilities
42</project_structure>
43 
44<module_development_guidelines>
45### 1. Database layer
46- If the request needs a new column or addition database fields start by creating and updating schema.ts
47- Leverage types.ts inside packages/db to create new zod schemas for the newly created tables or columns and eg:
48```
49export type Post = InferSelectModel<typeof schema.posts>;
50export type NewPost = InferInsertModel<typeof schema.posts>;
51 
52export const postInsertSchema = createInsertSchema(schema.posts).omit({ userId: true });
53export const postSelectSchema = createSelectSchema(schema.posts);
54```
55 
56 
57### 2. Service Layer ([module].service.ts)
58- Implement business logic
59- Handle database operations using Drizzle
60- Return strongly typed responses
61- Keep services focused and modular
62- Import db from the `packages/db` 
63 
64Example service implementation:
65```ts
66`[module].service.ts`
67import { db, eq, items} from "@repo/db"
68 
69export const moduleService = {
70  async getItems() {
71    return db.select().from(items);
72  },
73  
74  async createItem(data: NewItem) {
75    return db.insert(items).values(data).returning();
76  }
77};
78```
79 
80 
81### 3. Route Layer ([module].routes.ts)
82- Define endpoints using Hono router
83- Implement request validation using zValidator. You can leverage the created zod schemas from drizzle zod.
84- Apply authentication middleware where needed
85- Structure routes logically by resource
86- Return consistent HTTP responses
87 
88Example route implementation:
89```ts
90const moduleRoutes = new Hono()
91  .use(auth(),requireAuth)
92  .get("/", async (c) => {
93    const items = await moduleService.getItems();
94    return c.json(items);
95  })
96  .post("/", zValidator("json", insertSchema), async (c) => {
97    const data = c.req.valid("json");
98    const userId = getUserId(c);
99    const result = await moduleService.createItem({ ...data, userId });
100    return c.json(result);
101  });
102```
103 
104After the route is created, you must add it to the `apps/api/src/index.ts` route so its accessable by the frontend.
105 
106</module_development_guidelines>
107 
108<frontend_integration>
109When fetching data from the backend api on the client, use the following guidelines
110`post.api.ts`
111```ts
112import { apiRpc, getApiClient, InferRequestType } from "./client";
113 
114const $createPost = apiRpc.posts.$post;
115// Simple get
116export async function getPosts() {
117  const client = await getApiClient();
118 
119  const response = await client.posts.$get();
120  return response.json();
121}
122// Safely leverage the typed params elsewhere within the nextjs application 
123export type CreatePostParams = InferRequestType<typeof $createPost>["json"];
124export async function createPost(params: CreatePostParams) {
125  const client = await getApiClient();
126 
127  const response = await client.posts.$post({ json: params });
128  return response.json();
129}
130```
131</frontend_integration>
132<package_management>
133 
134- Use `pnpm` as the primary package manager for the project
135- Install dependencies using `pnpm add [package-name]`
136- Install dev dependencies using `pnpm add -D [package-name]`
137- Install workspace dependencies using `pnpm add -w [package-name]`
138</package_management>
139 
140<development_guidelines>
141### Running Scripts
142- Use `bun` as the runtime environment and script runner
143- Execute scripts defined in package.json using `bun run [script-name]`
144- Run TypeScript files directly using `bun [file.ts]`
145 
146### Monorepo 
147The project use turbo repo. To run everything, use the `turbo dev` script from the root folder.
148 
149### Type Safety
150- Use Drizzle schemas for database types
151- Share types between frontend and backend using a shared package
152- Leverage zod for runtime validation
153 
154### Error Handling
155- Implement consistent error handlers
156- Use proper HTTP status codes
157- Return structured error responses
158- Handle edge cases appropriately
159- Use the logger from the package @repo/logger, i.e `logger.error` instead of `console.error`
160 
161### Authentication & Authorization
162- Use Clerk middleware for authentication
163- Implement role-based access control where needed
164- Validate user permissions at the route level
165- Keep authentication logic in middleware
166 
167### API Design Principles
168- Follow RESTful conventions
169- Use consistent naming patterns
170- Implement proper request validation
171- Structure endpoints by resource/module
172- Keep routes clean and delegate logic to services
173 
174### Database Operations
175- Use Drizzle for all database interactions
176- Implement proper migrations
177- Handle transactions when needed
178- Write efficient queries
179- Use appropriate indexes
180</development_guidelines>
181 
182<dev_workflow>
183### Creating a New Module for different buisness logic
1841. Create module directory in api/src/modules/[module]
1852. Define routes in [module].routes.ts
1863. Implement service logic in [module].service.ts
1874. Add route to main application in index.ts
1885. Create frontend integration in web/src/api/[module].api.ts
189</dev_workflow>
190 
191### Testing Requirements
192- If needed use vitest to create testing files inside of the modules, [module].test.ts 
193- 
194### Code Quality
195- For methods with more than one argument, use object destructuring: `function myMethod({ param1, param2 }: MyMethodParams) {...}`.
196</best_practices>
197 
198 
199<example_api_workflow>
200Here's a complete example of a typical module:
201 
202(if required) create new schemas. 
203// packages/db/schema.ts
204.. new schema files
205 
206Then:
207```ts
208// posts.service.ts
209import { db, posts, type NewPost } from "@repo/db";
210 
211export const postService = {
212  async getPosts() {
213    return db.select().from(posts);
214  },
215 
216  async createPost(post: NewPost) {
217    return db.insert(posts).values(post).returning();
218  }
219};
220 
221// posts.routes.ts
222import { Hono } from "hono";
223import { auth, requireAuth, getUserId } from "@/pkg/middleware/clerk-auth";
224import { postService } from "./post.service";
225import { zValidator } from "@/pkg/util/validator-wrapper";
226import { postInsertSchema } from "@repo/db";
227 
228export const postRoutes = new Hono()
229  .use(auth(),requireAuth)
230  .get("/", async (c) => {
231    const posts = await postService.getPosts();
232    return c.json(posts);
233  })
234  .post("/", zValidator("json", postInsertSchema), async (c) => {
235    const data = c.req.valid("json");
236    const userId = getUserId(c);
237    const post = await postService.createPost({ ...data, userId });
238    return c.json(post);
239  });
240```
241 
242- Use the RPC-style API client for type-safe API calls
243- Leverage `InferRequestType` for parameter typing
244- Export plain async functions for API operations
245- Optionally create React Query hooks when needed
246```ts
247// posts.api.ts (Frontend)
248import { apiRpc, getApiClient, InferRequestType } from "./client";
249 
250const $createPost = apiRpc.posts.$post;
251 
252export async function getPosts() {
253  const client = await getApiClient();
254  const response = await client.posts.$get();
255  return response.json();
256}
257 
258export async function createPost(params: InferRequestType<typeof $createPost>["json"]) {
259  const client = await getApiClient();
260  const response = await client.posts.$post({ json: params });
261  return response.json();
262}
263```
264 
265Please note, on the frontend, do not need to generate response interfaces. The rpc client will handle safely types responses.
266</example_api_workflow>
267 
268 
269