Cursor rule

1---
2description: 
3globs: apps/api/**/*.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- **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    // If results could be undefined or otherwise, we can throw http 
101    if (!result){
102        // throw proper error code
103        throw new HTTPException(404, {message: ...})
104    }
105    return c.json(result);
106  });
107```
108 
109After the route is created, you must add it to the `apps/api/src/index.ts` route so its accessable by the frontend.
110 
111</module_development_guidelines>
112 
113<frontend_integration>
114When fetching data from the backend api on the client, use the following guidelines
115`post.api.ts`
116```ts
117import { apiRpc, getApiClient, InferRequestType, callRpc } from "./client";
118 
119const $createPost = apiRpc.posts.$post;
120// Simple get
121export async function getPosts() {
122  const client = await getApiClient();
123 
124  return callRpc(client.posts.$get());
125}
126// Safely leverage the typed params elsewhere within the nextjs application 
127export type CreatePostParams = InferRequestType<typeof $createPost>["json"];
128export async function createPost(params: CreatePostParams) {
129  const client = await getApiClient();
130 
131  return callRpc(client.posts.$post({ json: params }));
132}
133```
134</frontend_integration>
135<package_management>
136 
137- Use `pnpm` as the primary package manager for the project
138- Install dependencies using `pnpm add [package-name]`
139- Install dev dependencies using `pnpm add -D [package-name]`
140- Install workspace dependencies using `pnpm add -w [package-name]`
141</package_management>
142 
143<development_guidelines>
144### Running Scripts
145- Use `bun` as the runtime environment and script runner
146- Execute scripts defined in package.json using `bun run [script-name]`
147- Run TypeScript files directly using `bun [file.ts]`
148 
149### Monorepo 
150The project use turbo repo. To run everything, use the `turbo dev` script from the root folder.
151 
152### Type Safety
153- Use Drizzle schemas for database types
154- Share types between frontend and backend using a shared package
155- Leverage zod for runtime validation
156 
157### Error Handling
158- Implement consistent error handlers
159- Use proper HTTP status codes
160- Return structured error responses
161- Handle edge cases appropriately
162- Use the logger from the package @repo/logger with object inside, i.e `logger.error({...})` instead of `console.error`
163 
164### Authentication & Authorization
165- Use Clerk middleware for authentication
166- Implement role-based access control where needed
167- Validate user permissions at the route level
168- Keep authentication logic in middleware
169 
170### API Design Principles
171- Follow RESTful conventions
172- Use consistent naming patterns
173- Implement proper request validation
174- Structure endpoints by resource/module
175- Keep routes clean and delegate logic to services
176 
177### Database Operations
178- Use Drizzle for all database interactions
179- Implement proper migrations
180- Handle transactions when needed
181- Write efficient queries
182- Use appropriate indexes
183</development_guidelines>
184 
185<dev_workflow>
186### Creating a New Module for different buisness logic
1871. Create module directory in api/src/modules/[module]
1882. Define routes in [module].routes.ts
1893. Implement service logic in [module].service.ts
1904. Add route to main application in index.ts
1915. Create frontend integration in web/src/api/[module].api.ts
192</dev_workflow>
193 
194### Testing Requirements
195- If needed use vitest to create testing files inside of the modules, [module].test.ts 
196- 
197### Code Quality
198- For methods with more than one argument, use object destructuring: `function myMethod({ param1, param2 }: MyMethodParams) {...}`.
199</best_practices>
200 
201 
202<example_api_workflow>
203Here's a complete example of a typical module:
204 
205(if required) create new schemas. 
206// packages/db/schema.ts
207.. new schema files
208 
209Then:
210```ts
211// posts.service.ts
212import { db, posts, type NewPost } from "@repo/db";
213 
214export const postService = {
215  async getPosts() {
216    return db.select().from(posts);
217  },
218 
219  async createPost(post: NewPost) {
220    return db.insert(posts).values(post).returning();
221  }
222};
223 
224// posts.routes.ts
225import { Hono } from "hono";
226import { auth, requireAuth, getUserId } from "@/pkg/middleware/clerk-auth";
227import { postService } from "./post.service";
228import { zValidator } from "@/pkg/util/validator-wrapper";
229import { postInsertSchema } from "@repo/db";
230 
231export const postRoutes = new Hono()
232  .use(auth(),requireAuth)
233  .get("/", async (c) => {
234    const posts = await postService.getPosts();
235    return c.json(posts);
236  })
237  .post("/", zValidator("json", postInsertSchema), async (c) => {
238    const data = c.req.valid("json");
239    const userId = getUserId(c);
240    const post = await postService.createPost({ ...data, userId });
241    return c.json(post);
242  });
243```
244 
245- Use the RPC-style API client for type-safe API calls
246- Leverage `InferRequestType` for parameter typing
247- Export plain async functions for API operations
248- Optionally create React Query hooks when needed
249```ts
250// posts.api.ts (Frontend)
251import { apiRpc, getApiClient, InferRequestType, callRpc } from "./client";
252 
253const $createPost = apiRpc.posts.$post;
254 
255export async function getPosts() {
256  const client = await getApiClient();
257  return  callRpc(client.posts.$get());
258}
259 
260export async function createPost(params: InferRequestType<typeof $createPost>["json"]) {
261  const client = await getApiClient();
262  return callRpc(client.posts.$post({ json: params }));
263  return response.json();
264}
265```
266</example_api_workflow>
267 
268 
269