+231 -40

.cursor/rules/backend-api.mdc

reviewed

··· 1 1 --- 2 2 - description: 3 3 - globs: 2 2 + description: Backend API development guidelines for Hono, Drizzle ORM, and Better Auth 3 3 + globs: apps/api/**/* 4 4 alwaysApply: false 5 5 --- 6 6 - # Backend API Structure and Patterns 6 6 + # Backend API Guidelines 7 7 + 8 8 + The Kaneo API is built with Hono, Drizzle ORM, PostgreSQL, and Better Auth. This document outlines conventions and patterns for backend development. 9 9 + 10 10 + ## Framework: Hono 11 11 + 12 12 + Hono is a lightweight web framework. Follow these patterns: 13 13 + 14 14 + ### Route Structure 15 15 + 16 16 + Routes are organized by feature in `apps/api/src/`: 17 17 + 18 18 + ```typescript 19 19 + // apps/api/src/task/index.ts 20 20 + import { Hono } from "hono"; 21 21 + import { describeRoute, resolver, validator } from "hono-openapi"; 22 22 + import * as v from "valibot"; 23 23 + import createTask from "./controllers/create-task"; 24 24 + import getTask from "./controllers/get-task"; 25 25 + 26 26 + const task = new Hono<{ 27 27 + Variables: { 28 28 + userId: string; 29 29 + }; 30 30 + }>() 31 31 + .get( 32 32 + "/:id", 33 33 + describeRoute({ 34 34 + operationId: "getTask", 35 35 + tags: ["Tasks"], 36 36 + description: "Get a specific task by ID", 37 37 + responses: { 38 38 + 200: { 39 39 + description: "Task details", 40 40 + content: { 41 41 + "application/json": { schema: resolver(taskSchema) }, 42 42 + }, 43 43 + }, 44 44 + }, 45 45 + }), 46 46 + validator("param", v.object({ id: v.string() })), 47 47 + async (c) => { 48 48 + const { id } = c.req.valid("param"); 49 49 + const task = await getTask(id); 50 50 + return c.json(task); 51 51 + }, 52 52 + ); 53 53 + 54 54 + export default task; 55 55 + ``` 56 56 + 57 57 + ### Best Practices 58 58 + 59 59 + 1. **Always use OpenAPI decorators**: Use `describeRoute` for all endpoints 60 60 + 2. **Validate inputs**: Use `validator` with Valibot schemas 61 61 + 3. **Extract controllers**: Keep route handlers thin, move logic to controller files 62 62 + 4. **Type safety**: Use Hono's type system for context variables 63 63 + 64 64 + ```typescript 65 65 + // Good: Thin route handler 66 66 + .get("/:id", validator("param", v.object({ id: v.string() })), async (c) => { 67 67 + const { id } = c.req.valid("param"); 68 68 + const task = await getTask(id); 69 69 + return c.json(task); 70 70 + }) 71 71 + 72 72 + // Bad: Business logic in route handler 73 73 + .get("/:id", async (c) => { 74 74 + const id = c.req.param("id"); 75 75 + const task = await db.select().from(taskTable).where(eq(taskTable.id, id)); 76 76 + // ... more logic 77 77 + return c.json(task); 78 78 + }) 79 79 + ``` 80 80 + 81 81 + ## Database: Drizzle ORM 82 82 + 83 83 + ### Schema Definition 84 84 + 85 85 + Define schemas in `apps/api/src/database/schema.ts`: 86 86 + 87 87 + ```typescript 88 88 + import { pgTable, text, timestamp, boolean } from "drizzle-orm/pg-core"; 89 89 + import { createId } from "@paralleldrive/cuid2"; 90 90 + 91 91 + export const taskTable = pgTable("task", { 92 92 + id: text("id") 93 93 + .$defaultFn(() => createId()) 94 94 + .primaryKey(), 95 95 + title: text("title").notNull(), 96 96 + createdAt: timestamp("created_at", { mode: "date" }).defaultNow().notNull(), 97 97 + updatedAt: timestamp("updated_at", { mode: "date" }) 98 98 + .defaultNow() 99 99 + .$onUpdate(() => new Date()) 100 100 + .notNull(), 101 101 + }); 102 102 + ``` 103 103 + 104 104 + ### Best Practices 105 105 + 106 106 + 1. **Use CUID2 for IDs**: Always use `createId()` from `@paralleldrive/cuid2` 107 107 + 2. **Timestamps**: Always include `createdAt` and `updatedAt` with proper defaults 108 108 + 3. **Foreign Keys**: Use cascade deletes/updates where appropriate 109 109 + 4. **Indexes**: Add indexes for frequently queried columns 110 110 + 111 111 + ```typescript 112 112 + // Good: Proper schema with indexes 113 113 + export const taskTable = pgTable( 114 114 + "task", 115 115 + { 116 116 + id: text("id").$defaultFn(() => createId()).primaryKey(), 117 117 + projectId: text("project_id") 118 118 + .notNull() 119 119 + .references(() => projectTable.id, { 120 120 + onDelete: "cascade", 121 121 + onUpdate: "cascade", 122 122 + }), 123 123 + // ... 124 124 + }, 125 125 + (table) => [index("task_projectId_idx").on(table.projectId)], 126 126 + ); 127 127 + ``` 128 128 + 129 129 + ### Migrations 130 130 + 131 131 + 1. **Generate migrations**: `pnpm --filter @kaneo/api db:generate` 132 132 + 2. **Run migrations**: Automatically on API startup (see `apps/api/src/index.ts`) 133 133 + 3. **Migration files**: Stored in `apps/api/drizzle/` 134 134 + 135 135 + ## Authentication: Better Auth 136 136 + 137 137 + Better Auth handles authentication. Access user context via Hono variables: 7 138 8 8 - The backend API is located in [apps/api/](mdc:apps/api) and follows a modular, domain-driven architecture. 139 139 + ```typescript 140 140 + // User is available in context after auth middleware 141 141 + const userId = c.get("userId"); 142 142 + const user = c.get("user"); 143 143 + const session = c.get("session"); 144 144 + ``` 9 145 10 10 - ## Project Structure 146 146 + ### API Key Authentication 11 147 12 12 - ### Core Files 13 13 - - **Entry Point**: [apps/api/src/index.ts](mdc:apps/api/src/index.ts) - Main Hono application setup 14 14 - - **Database**: [apps/api/src/database/index.ts](mdc:apps/api/src/database/index.ts) - Database connection 15 15 - - **Schema**: [apps/api/src/database/schema.ts](mdc:apps/api/src/database/schema.ts) - Drizzle ORM schema definitions 16 16 - - **Config**: [apps/api/src/config/index.ts](mdc:apps/api/src/config/index.ts) - Environment configuration 148 148 + API keys are supported via Bearer token: 17 149 18 18 - ### Domain Modules 150 150 + ```typescript 151 151 + // Middleware in apps/api/src/index.ts handles this 152 152 + // Authorization: Bearer <api-key> 153 153 + ``` 154 154 + 155 155 + ## Validation: Valibot 156 156 + 157 157 + Use Valibot for request validation: 158 158 + 159 159 + ```typescript 160 160 + import * as v from "valibot"; 161 161 + 162 162 + validator( 163 163 + "json", 164 164 + v.object({ 165 165 + title: v.string(), 166 166 + description: v.optional(v.string()), 167 167 + dueDate: v.optional(v.string()), 168 168 + }), 169 169 + ) 170 170 + ``` 171 171 + 172 172 + ## Controller Pattern 173 173 + 174 174 + Controllers contain business logic and are imported into route files: 175 175 + 176 176 + ```typescript 177 177 + // apps/api/src/task/controllers/get-task.ts 178 178 + import db from "../../database"; 179 179 + import { taskTable } from "../../database/schema"; 180 180 + import { eq } from "drizzle-orm"; 181 181 + 182 182 + export default async function getTask(id: string) { 183 183 + const [task] = await db 184 184 + .select() 185 185 + .from(taskTable) 186 186 + .where(eq(taskTable.id, id)); 187 187 + 188 188 + if (!task) { 189 189 + throw new HTTPException(404, { message: "Task not found" }); 190 190 + } 191 191 + 192 192 + return task; 193 193 + } 194 194 + ``` 195 195 + 196 196 + ## Error Handling 197 197 + 198 198 + Use Hono's HTTPException for errors: 199 199 + 200 200 + ```typescript 201 201 + import { HTTPException } from "hono/http-exception"; 19 202 20 20 - Each domain follows the same structure pattern with `controllers/` and `index.ts`: 203 203 + if (!task) { 204 204 + throw new HTTPException(404, { message: "Task not found" }); 205 205 + } 206 206 + ``` 21 207 22 22 - - **Activity**: [apps/api/src/activity/](mdc:apps/api/src/activity) - Activity tracking and comments 23 23 - - **Task**: [apps/api/src/task/](mdc:apps/api/src/task) - Task management (CRUD, updates, exports) 24 24 - - **Project**: [apps/api/src/project/](mdc:apps/api/src/project) - Project management 25 25 - - **Workspace**: [apps/api/src/workspace/](mdc:apps/api/src/workspace) - Workspace management 26 26 - - **User**: [apps/api/src/user/](mdc:apps/api/src/user) - Authentication and user management 27 27 - - **GitHub Integration**: [apps/api/src/github-integration/](mdc:apps/api/src/github-integration) - GitHub app integration 28 28 - - **Time Entry**: [apps/api/src/time-entry/](mdc:apps/api/src/time-entry) - Time tracking 29 29 - - **Notification**: [apps/api/src/notification/](mdc:apps/api/src/notification) - User notifications 30 30 - - **Label**: [apps/api/src/label/](mdc:apps/api/src/label) - Task labeling system 208 208 + ## Events 31 209 32 32 - ## Architecture Patterns 210 210 + Publish events for activity tracking: 33 211 34 34 - ### Controller Pattern 35 35 - Each domain has controllers in `controllers/` directory that handle HTTP requests: 36 36 - - Controllers use Hono framework 37 37 - - Follow naming convention: `{action}-{resource}.ts` (e.g., `create-task.ts`) 38 38 - - Each controller exports a Hono route handler 212 212 + ```typescript 213 213 + import { publishEvent } from "../events"; 39 214 40 40 - ### Module Exports 41 41 - Each domain has an [index.ts](mdc:apps/api/src/task/index.ts) that exports all controllers as Hono routes. 215 215 + await publishEvent("task.status_changed", { 216 216 + taskId: task.id, 217 217 + userId: user, 218 218 + oldStatus: task.status, 219 219 + newStatus: status, 220 220 + title: task.title, 221 221 + type: "status_changed", 222 222 + }); 223 223 + ``` 42 224 43 43 - ### Authentication 44 44 - - Auth middleware: [apps/api/src/middlewares/auth.ts](mdc:apps/api/src/middlewares/auth.ts) 45 45 - - Session management in [apps/api/src/user/utils/](mdc:apps/api/src/user/utils) 225 225 + ## File Organization 46 226 47 47 - ### Database Migrations 48 48 - - Located in [apps/api/drizzle/](mdc:apps/api/drizzle) 49 49 - - Managed by Drizzle ORM 50 50 - - Configuration: [apps/api/drizzle.config.ts](mdc:apps/api/drizzle.config.ts) 227 227 + ``` 228 228 + apps/api/src/ 229 229 + ├── activity/ # Activity feature 230 230 + │ ├── controllers/ 231 231 + │ └── index.ts 232 232 + ├── auth.ts # Better Auth configuration 233 233 + ├── config/ # Configuration endpoints 234 234 + ├── database/ # Database schema and connection 235 235 + │ ├── schema.ts 236 236 + │ ├── relations.ts 237 237 + │ └── index.ts 238 238 + ├── events/ # Event publishing 239 239 + ├── task/ # Task feature 240 240 + │ ├── controllers/ 241 241 + │ └── index.ts 242 242 + └── index.ts # Main entry point 243 243 + ``` 51 244 52 52 - ## Key Utilities 245 245 + ## CORS Configuration 53 246 54 54 - - **Demo Data**: [apps/api/src/utils/create-demo-user.ts](mdc:apps/api/src/utils/create-demo-user.ts) 55 55 - - **Settings**: [apps/api/src/utils/get-settings.ts](mdc:apps/api/src/utils/get-settings.ts) 56 56 - - **Events**: [apps/api/src/events/index.ts](mdc:apps/api/src/events/index.ts) 247 247 + CORS is configured in `apps/api/src/index.ts`. Set `CORS_ORIGINS` environment variable for production.

+66

.cursor/rules/cursor-rules.mdc

reviewed

··· 1 1 + --- 2 2 + description: How to add or edit Cursor rules in our project 3 3 + globs: 4 4 + alwaysApply: false 5 5 + --- 6 6 + # Cursor Rules Location 7 7 + 8 8 + How to add new cursor rules to the project 9 9 + 10 10 + 1. Always place rule files in PROJECT_ROOT/.cursor/rules/: 11 11 + ``` 12 12 + .cursor/rules/ 13 13 + ├── your-rule-name.mdc 14 14 + ├── another-rule.mdc 15 15 + └── ... 16 16 + ``` 17 17 + 18 18 + 2. Follow the naming convention: 19 19 + - Use kebab-case for filenames 20 20 + - Always use .mdc extension 21 21 + - Make names descriptive of the rule's purpose 22 22 + 23 23 + 3. Directory structure: 24 24 + ``` 25 25 + PROJECT_ROOT/ 26 26 + ├── .cursor/ 27 27 + │ └── rules/ 28 28 + │ ├── your-rule-name.mdc 29 29 + │ └── ... 30 30 + └── ... 31 31 + ``` 32 32 + 33 33 + 4. Never place rule files: 34 34 + - In the project root 35 35 + - In subdirectories outside .cursor/rules 36 36 + - In any other location 37 37 + 38 38 + 5. Cursor rules have the following structure: 39 39 + 40 40 + ```` 41 41 + --- 42 42 + description: Short description of the rule's purpose 43 43 + globs: optional/path/pattern/**/* 44 44 + alwaysApply: false 45 45 + --- 46 46 + # Rule Title 47 47 + 48 48 + Main content explaining the rule with markdown formatting. 49 49 + 50 50 + 1. Step-by-step instructions 51 51 + 2. Code examples 52 52 + 3. Guidelines 53 53 + 54 54 + Example: 55 55 + ```typescript 56 56 + // Good example 57 57 + function goodExample() { 58 58 + // Implementation following guidelines 59 59 + } 60 60 + 61 61 + // Bad example 62 62 + function badExample() { 63 63 + // Implementation not following guidelines 64 64 + } 65 65 + ``` 66 66 + ````

+267 -62

.cursor/rules/database-schema.mdc

reviewed

··· 1 1 --- 2 2 - description: 3 3 - globs: 2 2 + description: Database schema conventions and patterns using Drizzle ORM and PostgreSQL 3 3 + globs: apps/api/src/database/**/* 4 4 alwaysApply: false 5 5 --- 6 6 - # Database Schema and Data Model 6 6 + # Database Schema Guidelines 7 7 + 8 8 + Kaneo uses Drizzle ORM with PostgreSQL. This document outlines schema conventions and best practices. 9 9 + 10 10 + ## Schema Definition 11 11 + 12 12 + All schemas are defined in `apps/api/src/database/schema.ts`: 13 13 + 14 14 + ```typescript 15 15 + import { pgTable, text, timestamp, boolean, integer, index } from "drizzle-orm/pg-core"; 16 16 + import { createId } from "@paralleldrive/cuid2"; 17 17 + 18 18 + export const taskTable = pgTable( 19 19 + "task", 20 20 + { 21 21 + id: text("id") 22 22 + .$defaultFn(() => createId()) 23 23 + .primaryKey(), 24 24 + projectId: text("project_id") 25 25 + .notNull() 26 26 + .references(() => projectTable.id, { 27 27 + onDelete: "cascade", 28 28 + onUpdate: "cascade", 29 29 + }), 30 30 + title: text("title").notNull(), 31 31 + description: text("description"), 32 32 + status: text("status").notNull().default("to-do"), 33 33 + createdAt: timestamp("created_at", { mode: "date" }).defaultNow().notNull(), 34 34 + updatedAt: timestamp("updated_at", { mode: "date" }) 35 35 + .defaultNow() 36 36 + .$onUpdate(() => new Date()) 37 37 + .notNull(), 38 38 + }, 39 39 + (table) => [ 40 40 + index("task_projectId_idx").on(table.projectId), 41 41 + ], 42 42 + ); 43 43 + ``` 44 44 + 45 45 + ## Naming Conventions 46 46 + 47 47 + 1. **Table names**: Use singular, lowercase with underscores: `task`, `workspace_user` 48 48 + 2. **Column names**: Use snake_case: `project_id`, `created_at`, `updated_at` 49 49 + 3. **Index names**: Format: `{table}_{column}_idx` 50 50 + 4. **Foreign key columns**: End with `_id`: `project_id`, `user_id` 51 51 + 52 52 + ```typescript 53 53 + // Good: Consistent naming 54 54 + export const workspaceUserTable = pgTable("workspace_user", { 55 55 + id: text("id").primaryKey(), 56 56 + workspaceId: text("workspace_id").notNull(), 57 57 + userId: text("user_id").notNull(), 58 58 + role: text("role").notNull(), 59 59 + }); 60 60 + 61 61 + // Bad: Inconsistent naming 62 62 + export const workspaceUserTable = pgTable("WorkspaceUsers", { 63 63 + ID: text("ID").primaryKey(), 64 64 + workspace: text("workspace").notNull(), 65 65 + user: text("user").notNull(), 66 66 + }); 67 67 + ``` 68 68 + 69 69 + ## Required Fields 70 70 + 71 71 + Every table should include: 72 72 + 73 73 + 1. **Primary Key**: `id` field using CUID2 74 74 + 2. **Timestamps**: `created_at` and `updated_at` with proper defaults 75 75 + 3. **Foreign Keys**: Proper references with cascade options 76 76 + 77 77 + ```typescript 78 78 + export const exampleTable = pgTable("example", { 79 79 + // Required: Primary key with CUID2 80 80 + id: text("id") 81 81 + .$defaultFn(() => createId()) 82 82 + .primaryKey(), 83 83 + 84 84 + // Required: Timestamps 85 85 + createdAt: timestamp("created_at", { mode: "date" }) 86 86 + .defaultNow() 87 87 + .notNull(), 88 88 + updatedAt: timestamp("updated_at", { mode: "date" }) 89 89 + .defaultNow() 90 90 + .$onUpdate(() => new Date()) 91 91 + .notNull(), 92 92 + 93 93 + // Foreign keys with cascade 94 94 + projectId: text("project_id") 95 95 + .notNull() 96 96 + .references(() => projectTable.id, { 97 97 + onDelete: "cascade", 98 98 + onUpdate: "cascade", 99 99 + }), 100 100 + }); 101 101 + ``` 102 102 + 103 103 + ## ID Generation 104 104 + 105 105 + Always use CUID2 for primary keys: 106 106 + 107 107 + ```typescript 108 108 + import { createId } from "@paralleldrive/cuid2"; 109 109 + 110 110 + id: text("id") 111 111 + .$defaultFn(() => createId()) 112 112 + .primaryKey(), 113 113 + ``` 114 114 + 115 115 + ## Timestamps 116 116 + 117 117 + Use consistent timestamp patterns: 118 118 + 119 119 + ```typescript 120 120 + // Created timestamp (never changes) 121 121 + createdAt: timestamp("created_at", { mode: "date" }) 122 122 + .defaultNow() 123 123 + .notNull(), 124 124 + 125 125 + // Updated timestamp (auto-updates on change) 126 126 + updatedAt: timestamp("updated_at", { mode: "date" }) 127 127 + .defaultNow() 128 128 + .$onUpdate(() => new Date()) 129 129 + .notNull(), 130 130 + 131 131 + // Optional timestamp (e.g., deleted_at) 132 132 + deletedAt: timestamp("deleted_at", { mode: "date" }), 133 133 + ``` 134 134 + 135 135 + ## Foreign Keys 136 136 + 137 137 + Always specify cascade behavior: 138 138 + 139 139 + ```typescript 140 140 + // Good: Explicit cascade behavior 141 141 + userId: text("user_id") 142 142 + .notNull() 143 143 + .references(() => userTable.id, { 144 144 + onDelete: "cascade", 145 145 + onUpdate: "cascade", 146 146 + }), 147 147 + 148 148 + // Bad: Missing cascade options 149 149 + userId: text("user_id").references(() => userTable.id), 150 150 + ``` 151 151 + 152 152 + ### Cascade Options 153 153 + 154 154 + - **`onDelete: "cascade"`**: Delete related records when parent is deleted 155 155 + - **`onUpdate: "cascade"`**: Update foreign key when parent ID changes 156 156 + - **`onDelete: "set null"`**: Set foreign key to null when parent is deleted (use nullable column) 157 157 + 158 158 + ## Indexes 159 159 + 160 160 + Add indexes for frequently queried columns: 161 161 + 162 162 + ```typescript 163 163 + export const taskTable = pgTable( 164 164 + "task", 165 165 + { 166 166 + // ... columns 167 167 + projectId: text("project_id").notNull(), 168 168 + userId: text("user_id"), 169 169 + status: text("status").notNull(), 170 170 + }, 171 171 + (table) => [ 172 172 + index("task_projectId_idx").on(table.projectId), 173 173 + index("task_userId_idx").on(table.userId), 174 174 + index("task_status_idx").on(table.status), 175 175 + ], 176 176 + ); 177 177 + ``` 7 178 8 8 - The application uses **PostgreSQL** with **Drizzle ORM** for type-safe database operations and migrations. 179 179 + ### When to Add Indexes 9 180 10 10 - ## Core Schema Files 181 181 + - Foreign key columns (always) 182 182 + - Columns used in WHERE clauses frequently 183 183 + - Columns used for sorting/ordering 184 184 + - Composite indexes for multi-column queries 11 185 12 12 - - **Schema Definition**: [apps/api/src/database/schema.ts](mdc:apps/api/src/database/schema.ts) - All table definitions 13 13 - - **Database Connection**: [apps/api/src/database/index.ts](mdc:apps/api/src/database/index.ts) - Database client setup 14 14 - - **Migration Config**: [apps/api/drizzle.config.ts](mdc:apps/api/drizzle.config.ts) - Drizzle configuration 186 186 + ## Relations 15 187 16 16 - ## Migration Management 188 188 + Define relations in `apps/api/src/database/relations.ts`: 17 189 18 18 - ### Migration Files 19 19 - - **Directory**: [apps/api/drizzle/](mdc:apps/api/drizzle) - Contains all migration files 20 20 - - **Journal**: [apps/api/drizzle/meta/_journal.json](mdc:apps/api/drizzle/meta/_journal.json) - Migration tracking 21 21 - - **Snapshots**: [apps/api/drizzle/meta/](mdc:apps/api/drizzle/meta) - Schema snapshots for each migration 190 190 + ```typescript 191 191 + import { relations } from "drizzle-orm"; 192 192 + import { taskTable } from "./schema"; 193 193 + import { projectTable } from "./schema"; 22 194 23 23 - ### Migration Commands 24 24 - ```bash 25 25 - # Generate migration 26 26 - npm run db:generate 195 195 + export const taskTableRelations = relations(taskTable, ({ one, many }) => ({ 196 196 + project: one(projectTable, { 197 197 + fields: [taskTable.projectId], 198 198 + references: [projectTable.id], 199 199 + }), 200 200 + labels: many(labelTable), 201 201 + })); 202 202 + ``` 203 203 + 204 204 + ## Data Types 205 205 + 206 206 + Use appropriate PostgreSQL types: 207 207 + 208 208 + ```typescript 209 209 + // Text (varchar) 210 210 + title: text("title").notNull(), 211 211 + 212 212 + // Optional text 213 213 + description: text("description"), 214 214 + 215 215 + // Boolean 216 216 + isActive: boolean("is_active").default(true).notNull(), 217 217 + 218 218 + // Integer 219 219 + position: integer("position").default(0), 27 220 28 28 - # Apply migrations 29 29 - npm run db:migrate 221 221 + // Timestamp 222 222 + createdAt: timestamp("created_at", { mode: "date" }).defaultNow().notNull(), 30 223 31 31 - # View database 32 32 - npm run db:studio 224 224 + // JSON (if needed) 225 225 + metadata: json("metadata").$type<{ key: string }>(), 33 226 ``` 34 227 35 35 - ## Data Model Overview 228 228 + ## Default Values 36 229 37 37 - Based on the project structure, the main entities likely include: 230 230 + Provide sensible defaults: 38 231 39 39 - ### Core Entities 40 40 - - **Users** - User accounts and authentication 41 41 - - **Workspaces** - Team/organization containers 42 42 - - **WorkspaceUsers** - User membership in workspaces 43 43 - - **Projects** - Project containers within workspaces 44 44 - - **Tasks** - Individual work items within projects 45 45 - - **Labels** - Task categorization and tagging 46 46 - - **TimeEntries** - Time tracking for tasks 47 47 - - **Activities** - Activity logs and comments 48 48 - - **Notifications** - User notification system 232 232 + ```typescript 233 233 + // Boolean defaults 234 234 + isActive: boolean("is_active").default(true).notNull(), 235 235 + 236 236 + // Integer defaults 237 237 + position: integer("position").default(0), 238 238 + 239 239 + // Text defaults 240 240 + status: text("status").notNull().default("to-do"), 49 241 50 50 - ### Integration Entities 51 51 - - **GitHubIntegrations** - GitHub app connections 52 52 - - **Settings** - Application and user settings 242 242 + // Timestamp defaults 243 243 + createdAt: timestamp("created_at", { mode: "date" }).defaultNow().notNull(), 244 244 + ``` 53 245 54 54 - ## Schema Patterns 246 246 + ## Migrations 55 247 56 56 - ### Primary Keys 57 57 - - Uses auto-incrementing integers or UUIDs 58 58 - - Consistent naming: `id` for primary keys 248 248 + ### Generating Migrations 59 249 60 60 - ### Foreign Keys 61 61 - - Clear naming convention for references 62 62 - - Proper cascading rules for data integrity 250 250 + After schema changes: 63 251 64 64 - ### Timestamps 65 65 - - `createdAt` and `updatedAt` fields on most entities 66 66 - - Consistent timestamp handling 252 252 + ```bash 253 253 + pnpm --filter @kaneo/api db:generate 254 254 + ``` 67 255 68 68 - ### Soft Deletes 69 69 - - May use `deletedAt` for soft deletion patterns 70 70 - - Preserves data integrity and audit trails 256 256 + This creates migration files in `apps/api/drizzle/`. 71 257 72 72 - ## Database Operations 258 258 + ### Running Migrations 73 259 74 74 - ### Query Examples 260 260 + Migrations run automatically on API startup (see `apps/api/src/index.ts`): 261 261 + 75 262 ```typescript 76 76 - // Import from schema 77 77 - import { db } from './database' 78 78 - import { tasks, projects } from './database/schema' 263 263 + await migrate(db, { 264 264 + migrationsFolder: `${process.cwd()}/drizzle`, 265 265 + }); 266 266 + ``` 267 267 + 268 268 + ### Migration Best Practices 269 269 + 270 270 + 1. **Never edit existing migrations**: Create new migrations for changes 271 271 + 2. **Test migrations**: Test both up and down migrations 272 272 + 3. **Backup first**: Always backup production data before migrations 273 273 + 4. **Review SQL**: Check generated SQL before applying 274 274 + 275 275 + ## Schema Export 276 276 + 277 277 + Export all schemas and relations from `apps/api/src/database/index.ts`: 278 278 + 279 279 + ```typescript 280 280 + export const schema = { 281 281 + taskTable, 282 282 + projectTable, 283 283 + // ... all tables 284 284 + taskTableRelations, 285 285 + projectTableRelations, 286 286 + // ... all relations 287 287 + }; 79 288 80 80 - // Type-safe queries with Drizzle 81 81 - const userTasks = await db 82 82 - .select() 83 83 - .from(tasks) 84 84 - .where(eq(tasks.userId, userId)) 289 289 + const db = drizzle(pool, { 290 290 + schema: schema, 291 291 + }); 85 292 ``` 86 293 87 87 - ### Transaction Patterns 88 88 - - Use database transactions for multi-table operations 89 89 - - Ensure data consistency across related entities 294 294 + This enables Drizzle's relational queries and type inference.

+383 -85

.cursor/rules/deployment-devops.mdc

reviewed

··· 1 1 --- 2 2 - description: 3 3 - globs: 2 2 + description: Deployment and DevOps guidelines for Docker Compose and Kubernetes 3 3 + globs: compose.yml,charts/**/* 4 4 alwaysApply: false 5 5 --- 6 6 - # Deployment and DevOps 6 6 + # Deployment & DevOps Guidelines 7 7 + 8 8 + Kaneo supports multiple deployment methods: Docker Compose for development/testing and Kubernetes for production. This document outlines deployment patterns and best practices. 9 9 + 10 10 + ## Docker Compose 7 11 8 8 - This document covers the deployment infrastructure, containerization, and DevOps practices for the Kaneo project. 12 12 + ### Configuration 9 13 10 10 - ## Containerization 14 14 + The main Docker Compose configuration is in `compose.yml` at the project root. 11 15 12 12 - ### Docker Configuration 13 13 - - **API Dockerfile**: [apps/api/Dockerfile](mdc:apps/api/Dockerfile) - Backend API container 14 14 - - **Web Dockerfile**: [apps/web/Dockerfile](mdc:apps/web/Dockerfile) - Frontend application container 15 15 - - **Environment Script**: [apps/web/env.sh](mdc:apps/web/env.sh) - Runtime environment configuration 16 16 + ### Service Structure 17 17 + 18 18 + ```yaml 19 19 + services: 20 20 + postgres: 21 21 + image: postgres:16-alpine 22 22 + env_file: 23 23 + - .env 24 24 + ports: 25 25 + - "5432:5432" 26 26 + volumes: 27 27 + - postgres_data:/var/lib/postgresql/data 28 28 + restart: unless-stopped 29 29 + healthcheck: 30 30 + test: ["CMD-SHELL", "pg_isready -U kaneo -d kaneo"] 31 31 + interval: 10s 32 32 + timeout: 5s 33 33 + retries: 5 16 34 17 17 - ### Container Patterns 18 18 - - **Multi-stage builds** for optimized production images 19 19 - - **Node.js Alpine** base images for smaller footprint 20 20 - - **Environment variables** for runtime configuration 21 21 - - **Health checks** for container monitoring 35 35 + api: 36 36 + image: ghcr.io/usekaneo/api:latest 37 37 + ports: 38 38 + - "1337:1337" 39 39 + env_file: 40 40 + - .env 41 41 + depends_on: 42 42 + postgres: 43 43 + condition: service_healthy 44 44 + restart: unless-stopped 22 45 23 23 - ## Kubernetes Deployment 46 46 + web: 47 47 + image: ghcr.io/usekaneo/web:latest 48 48 + ports: 49 49 + - "5173:5173" 50 50 + env_file: 51 51 + - .env 52 52 + depends_on: 53 53 + - api 54 54 + restart: unless-stopped 55 55 + ``` 24 56 25 25 - ### Helm Charts 26 26 - The project uses **Helm** for Kubernetes deployments: 57 57 + ### Best Practices 27 58 28 28 - - **Chart Directory**: [charts/kaneo/](mdc:charts/kaneo) - Main Helm chart 29 29 - - **Chart.yaml**: [charts/kaneo/Chart.yaml](mdc:charts/kaneo/Chart.yaml) - Chart metadata 30 30 - - **Values**: [charts/kaneo/values.yaml](mdc:charts/kaneo/values.yaml) - Default configuration values 59 59 + 1. **Health Checks**: Always include health checks for databases 60 60 + 2. **Dependencies**: Use `depends_on` with `condition: service_healthy` for databases 61 61 + 3. **Volumes**: Use named volumes for persistent data 62 62 + 4. **Restart Policy**: Use `unless-stopped` for production-like behavior 63 63 + 5. **Environment Variables**: Use `.env` file, never hardcode secrets 31 64 32 32 - ### Kubernetes Resources 65 65 + ```yaml 66 66 + # Good: Proper health check and dependency 67 67 + services: 68 68 + api: 69 69 + depends_on: 70 70 + postgres: 71 71 + condition: service_healthy 33 72 34 34 - Located in [charts/kaneo/templates/](mdc:charts/kaneo/templates): 73 73 + postgres: 74 74 + healthcheck: 75 75 + test: ["CMD-SHELL", "pg_isready -U kaneo -d kaneo"] 76 76 + interval: 10s 77 77 + timeout: 5s 78 78 + retries: 5 79 79 + ``` 35 80 36 36 - - **Deployment**: [charts/kaneo/templates/deployment.yaml](mdc:charts/kaneo/templates/deployment.yaml) - Application deployment 37 37 - - **Service**: Application service definitions 38 38 - - **Ingress**: External traffic routing 39 39 - - **ConfigMap**: Configuration management 40 40 - - **Secret**: Sensitive data management 41 41 - - **HPA**: [charts/kaneo/templates/hpa.yaml](mdc:charts/kaneo/templates/hpa.yaml) - Horizontal Pod Autoscaler 81 81 + ## Kubernetes (Helm Charts) 42 82 43 43 - ### Deployment Features 44 44 - - **Horizontal Pod Autoscaling** for traffic-based scaling 45 45 - - **Rolling updates** for zero-downtime deployments 46 46 - - **Resource limits** and requests for efficient resource usage 47 47 - - **Liveness and readiness probes** for health monitoring 83 83 + ### Chart Structure 48 84 49 49 - ## Environment Configuration 85 85 + Helm charts are located in `charts/kaneo/`: 86 86 + 87 87 + ``` 88 88 + charts/kaneo/ 89 89 + ├── Chart.yaml # Chart metadata 90 90 + ├── values.yaml # Default values 91 91 + ├── README.md # Chart documentation 92 92 + └── templates/ 93 93 + ├── deployment.yaml # API and Web deployments 94 94 + ├── services.yaml # Service definitions 95 95 + ├── ingress.yaml # Ingress configuration 96 96 + ├── postgresql-deployment.yaml # PostgreSQL deployment 97 97 + ├── pvc.yaml # Persistent volume claims 98 98 + ├── hpa.yaml # Horizontal Pod Autoscaler 99 99 + └── serviceaccount.yaml # Service accounts 100 100 + ``` 101 101 + 102 102 + ### Deployment Patterns 103 103 + 104 104 + #### API Deployment 105 105 + 106 106 + ```yaml 107 107 + apiVersion: apps/v1 108 108 + kind: Deployment 109 109 + metadata: 110 110 + name: {{ include "kaneo.fullname" . }}-api 111 111 + spec: 112 112 + replicas: {{ .Values.api.replicaCount }} 113 113 + template: 114 114 + spec: 115 115 + containers: 116 116 + - name: api 117 117 + image: "{{ .Values.api.image.repository }}:{{ .Values.api.image.tag }}" 118 118 + env: 119 119 + - name: DATABASE_URL 120 120 + valueFrom: 121 121 + secretKeyRef: 122 122 + name: {{ include "kaneo.fullname" . }}-secrets 123 123 + key: database-url 124 124 + ``` 125 125 + 126 126 + #### Web Deployment 127 127 + 128 128 + ```yaml 129 129 + apiVersion: apps/v1 130 130 + kind: Deployment 131 131 + metadata: 132 132 + name: {{ include "kaneo.fullname" . }}-web 133 133 + spec: 134 134 + replicas: {{ .Values.web.replicaCount }} 135 135 + template: 136 136 + spec: 137 137 + containers: 138 138 + - name: web 139 139 + image: "{{ .Values.web.image.repository }}:{{ .Values.web.image.tag }}" 140 140 + env: 141 141 + - name: VITE_API_URL 142 142 + value: {{ .Values.web.apiUrl | quote }} 143 143 + ``` 144 144 + 145 145 + ### Best Practices 146 146 + 147 147 + 1. **Secrets Management**: Use Kubernetes Secrets, never hardcode 148 148 + 2. **ConfigMaps**: Use ConfigMaps for non-sensitive configuration 149 149 + 3. **Resource Limits**: Always set resource requests and limits 150 150 + 4. **Health Checks**: Include liveness and readiness probes 151 151 + 5. **Replicas**: Configure appropriate replica counts for high availability 152 152 + 153 153 + ```yaml 154 154 + # Good: Proper resource limits and health checks 155 155 + containers: 156 156 + - name: api 157 157 + resources: 158 158 + requests: 159 159 + memory: "256Mi" 160 160 + cpu: "100m" 161 161 + limits: 162 162 + memory: "512Mi" 163 163 + cpu: "500m" 164 164 + livenessProbe: 165 165 + httpGet: 166 166 + path: /api/health 167 167 + port: 1337 168 168 + initialDelaySeconds: 30 169 169 + periodSeconds: 10 170 170 + readinessProbe: 171 171 + httpGet: 172 172 + path: /api/health 173 173 + port: 1337 174 174 + initialDelaySeconds: 5 175 175 + periodSeconds: 5 176 176 + ``` 177 177 + 178 178 + ## Environment Variables 50 179 51 180 ### Development 52 52 - - **Local development** with Docker Compose (likely) 53 53 - - **Hot reloading** for faster iteration 54 54 - - **Development database** setup 181 181 + 182 182 + All environment variables in a single `.env` file at project root: 183 183 + 184 184 + ```bash 185 185 + # Database 186 186 + DATABASE_URL=postgresql://kaneo_user:kaneo_password@localhost:5432/kaneo 187 187 + POSTGRES_DB=kaneo 188 188 + POSTGRES_USER=kaneo_user 189 189 + POSTGRES_PASSWORD=kaneo_password 190 190 + 191 191 + # API 192 192 + KANEO_API_URL=http://localhost:1337 193 193 + AUTH_SECRET=your-secret-key 194 194 + 195 195 + # Web 196 196 + KANEO_CLIENT_URL=http://localhost:5173 197 197 + VITE_API_URL=http://localhost:1337 198 198 + ``` 55 199 56 200 ### Production 57 57 - - **Kubernetes cluster** deployment 58 58 - - **External database** (managed PostgreSQL) 59 59 - - **CDN integration** for static assets 60 60 - - **SSL/TLS termination** at ingress level 61 201 62 62 - ## CI/CD Pipeline 202 202 + Use Kubernetes Secrets and ConfigMaps: 63 203 64 64 - ### Build Process 65 65 - - **Monorepo builds** with optimized caching 66 66 - - **Multi-stage Docker builds** for production efficiency 67 67 - - **TypeScript compilation** and type checking 68 68 - - **Linting and formatting** with Biome 204 204 + ```yaml 205 205 + # Secret for sensitive data 206 206 + apiVersion: v1 207 207 + kind: Secret 208 208 + metadata: 209 209 + name: kaneo-secrets 210 210 + type: Opaque 211 211 + stringData: 212 212 + database-url: postgresql://user:pass@postgres:5432/kaneo 213 213 + auth-secret: your-secret-key 214 214 + 215 215 + # ConfigMap for non-sensitive data 216 216 + apiVersion: v1 217 217 + kind: ConfigMap 218 218 + metadata: 219 219 + name: kaneo-config 220 220 + data: 221 221 + api-url: https://api.example.com 222 222 + client-url: https://app.example.com 223 223 + ``` 224 224 + 225 225 + ## Database Migrations 226 226 + 227 227 + ### Automatic Migrations 228 228 + 229 229 + Migrations run automatically on API startup: 230 230 + 231 231 + ```typescript 232 232 + // apps/api/src/index.ts 233 233 + await migrate(db, { 234 234 + migrationsFolder: `${process.cwd()}/drizzle`, 235 235 + }); 236 236 + ``` 237 237 + 238 238 + ### Manual Migrations 69 239 70 70 - ### Deployment Strategy 71 71 - - **GitOps approach** with Helm charts 72 72 - - **Environment promotion** (dev → staging → production) 73 73 - - **Automated testing** before deployment 74 74 - - **Rollback capabilities** for quick recovery 240 240 + For production, consider running migrations separately: 241 241 + 242 242 + ```bash 243 243 + # In Kubernetes, use a Job 244 244 + kubectl run migrate-db --image=ghcr.io/usekaneo/api:latest -- \ 245 245 + node -e "require('./dist/migrate.js')" 246 246 + ``` 247 247 + 248 248 + ## Health Checks 249 249 + 250 250 + ### API Health Endpoint 75 251 76 76 - ## Monitoring and Observability 252 252 + The API exposes a health check endpoint: 77 253 78 78 - ### Application Monitoring 79 79 - - **Health check endpoints** in API 80 80 - - **Application metrics** collection 81 81 - - **Error tracking** and alerting 82 82 - - **Performance monitoring** 254 254 + ```typescript 255 255 + // apps/api/src/index.ts 256 256 + api.get("/health", (c) => { 257 257 + return c.json({ status: "ok" }); 258 258 + }); 259 259 + ``` 83 260 84 84 - ### Infrastructure Monitoring 85 85 - - **Kubernetes cluster** health monitoring 86 86 - - **Resource utilization** tracking 87 87 - - **Pod status** and availability metrics 88 88 - - **Network traffic** monitoring 261 261 + ### Kubernetes Probes 89 262 90 90 - ## Configuration Management 263 263 + ```yaml 264 264 + livenessProbe: 265 265 + httpGet: 266 266 + path: /api/health 267 267 + port: 1337 268 268 + initialDelaySeconds: 30 269 269 + periodSeconds: 10 91 270 92 92 - ### Environment Variables 93 93 - - **Database connection** strings 94 94 - - **API keys** and secrets 95 95 - - **Feature flags** for environment-specific behavior 96 96 - - **Third-party service** configurations 271 271 + readinessProbe: 272 272 + httpGet: 273 273 + path: /api/health 274 274 + port: 1337 275 275 + initialDelaySeconds: 5 276 276 + periodSeconds: 5 277 277 + ``` 97 278 98 98 - ### Secrets Management 99 99 - - **Kubernetes Secrets** for sensitive data 100 100 - - **External secret management** (vault, cloud providers) 101 101 - - **Secure key rotation** practices 102 102 - - **Encryption at rest** and in transit 279 279 + ## Scaling 103 280 104 104 - ## Scaling Strategies 281 281 + ### Horizontal Pod Autoscaling 105 282 106 106 - ### Horizontal Scaling 107 107 - - **Pod replication** based on CPU/memory usage 108 108 - - **Load balancing** across multiple instances 109 109 - - **Database connection pooling** 110 110 - - **Stateless application design** 283 283 + Configure HPA in `charts/kaneo/templates/hpa.yaml`: 111 284 112 112 - ### Performance Optimization 113 113 - - **CDN usage** for static assets 114 114 - - **Database query optimization** 115 115 - - **Caching strategies** (Redis, in-memory) 116 116 - - **Bundle optimization** for frontend assets 285 285 + ```yaml 286 286 + apiVersion: autoscaling/v2 287 287 + kind: HorizontalPodAutoscaler 288 288 + metadata: 289 289 + name: {{ include "kaneo.fullname" . }}-api 290 290 + spec: 291 291 + minReplicas: 2 292 292 + maxReplicas: 10 293 293 + metrics: 294 294 + - type: Resource 295 295 + resource: 296 296 + name: cpu 297 297 + target: 298 298 + type: Utilization 299 299 + averageUtilization: 70 300 300 + ``` 301 301 + 302 302 + ## Ingress 303 303 + 304 304 + ### TLS Configuration 305 305 + 306 306 + Always use TLS in production: 307 307 + 308 308 + ```yaml 309 309 + apiVersion: networking.k8s.io/v1 310 310 + kind: Ingress 311 311 + metadata: 312 312 + name: kaneo-ingress 313 313 + annotations: 314 314 + cert-manager.io/cluster-issuer: letsencrypt-prod 315 315 + spec: 316 316 + tls: 317 317 + - hosts: 318 318 + - app.example.com 319 319 + secretName: kaneo-tls 320 320 + rules: 321 321 + - host: app.example.com 322 322 + http: 323 323 + paths: 324 324 + - path: / 325 325 + pathType: Prefix 326 326 + backend: 327 327 + service: 328 328 + name: kaneo-web 329 329 + port: 330 330 + number: 80 331 331 + ``` 332 332 + 333 333 + ## Monitoring 334 334 + 335 335 + ### Logging 336 336 + 337 337 + - Use structured logging 338 338 + - Include request IDs for tracing 339 339 + - Log errors with context 340 340 + 341 341 + ### Metrics 342 342 + 343 343 + - Expose Prometheus metrics if needed 344 344 + - Monitor database connection pools 345 345 + - Track API response times 346 346 + 347 347 + ## Backup & Recovery 348 348 + 349 349 + ### Database Backups 350 350 + 351 351 + For PostgreSQL: 352 352 + 353 353 + ```bash 354 354 + # Backup 355 355 + kubectl exec -it postgres-pod -- pg_dump -U kaneo kaneo > backup.sql 356 356 + 357 357 + # Restore 358 358 + kubectl exec -i postgres-pod -- psql -U kaneo kaneo < backup.sql 359 359 + ``` 360 360 + 361 361 + ### Volume Backups 362 362 + 363 363 + Use volume snapshots for persistent data: 364 364 + 365 365 + ```yaml 366 366 + apiVersion: snapshot.storage.k8s.io/v1 367 367 + kind: VolumeSnapshot 368 368 + metadata: 369 369 + name: postgres-snapshot 370 370 + spec: 371 371 + source: 372 372 + persistentVolumeClaimName: postgres-pvc 373 373 + ``` 374 374 + 375 375 + ## Security 376 376 + 377 377 + ### Image Security 378 378 + 379 379 + - Use specific image tags, not `latest` 380 380 + - Scan images for vulnerabilities 381 381 + - Use minimal base images (Alpine Linux) 382 382 + 383 383 + ### Network Policies 384 384 + 385 385 + Restrict pod-to-pod communication: 386 386 + 387 387 + ```yaml 388 388 + apiVersion: networking.k8s.io/v1 389 389 + kind: NetworkPolicy 390 390 + metadata: 391 391 + name: kaneo-api-policy 392 392 + spec: 393 393 + podSelector: 394 394 + matchLabels: 395 395 + app: kaneo-api 396 396 + policyTypes: 397 397 + - Ingress 398 398 + - Egress 399 399 + ingress: 400 400 + - from: 401 401 + - podSelector: 402 402 + matchLabels: 403 403 + app: kaneo-web 404 404 + ports: 405 405 + - protocol: TCP 406 406 + port: 1337 407 407 + ``` 408 408 + 409 409 + ### Secrets Management 410 410 + 411 411 + - Never commit secrets to Git 412 412 + - Use Kubernetes Secrets or external secret managers 413 413 + - Rotate secrets regularly 414 414 + - Use least privilege principle

+296 -107

.cursor/rules/development-conventions.mdc

reviewed

··· 1 1 --- 2 2 - description: 3 3 - globs: 4 4 - alwaysApply: false 2 2 + description: Development conventions, code style, and best practices for the Kaneo project 3 3 + globs: 4 4 + alwaysApply: true 5 5 --- 6 6 - # Development Conventions and Best Practices 6 6 + # Development Conventions 7 7 8 8 - This document outlines the coding standards, patterns, and conventions used throughout the Kaneo project. 8 8 + This document outlines coding standards, conventions, and best practices for the Kaneo project. 9 9 10 10 - ## Code Quality Tools 10 10 + ## Code Style 11 11 12 12 - - **Biome**: [biome.json](mdc:biome.json) - Linting and formatting configuration 13 13 - - **Commitlint**: [commitlint.config.js](mdc:commitlint.config.js) - Commit message conventions 14 14 - - **TypeScript**: Strict type checking across all applications 12 12 + ### Biome Configuration 13 13 + 14 14 + Kaneo uses **Biome** for linting and formatting. Configuration is in `biome.json`. 15 15 + 16 16 + #### Formatting Rules 17 17 + 18 18 + - **Indentation**: Tabs (not spaces) for TypeScript/TSX 19 19 + - **JavaScript**: Spaces for indentation (legacy support) 20 20 + - **Quote Style**: Double quotes (`"`) 21 21 + - **Semicolons**: Required 22 22 + 23 23 + ```typescript 24 24 + // Good: Tabs, double quotes, semicolons 25 25 + function example() { 26 26 + const value = "hello"; 27 27 + return value; 28 28 + } 15 29 16 16 - ## File and Directory Naming 30 30 + // Bad: Spaces, single quotes, no semicolons 31 31 + function example() { 32 32 + const value = 'hello' 33 33 + return value 34 34 + } 35 35 + ``` 17 36 18 18 - ### General Conventions 19 19 - - **kebab-case** for directory names: `github-integration/`, `time-entry/` 20 20 - - **kebab-case** for file names: `create-task.ts`, `sign-in-form.tsx` 21 21 - - **PascalCase** for React components: `TaskCard.tsx`, `SignInForm.tsx` 37 37 + #### Linting Rules 22 38 23 23 - ### Backend API Conventions 24 24 - - **Controllers**: `{action}-{resource}.ts` pattern 25 25 - - Examples: `create-task.ts`, `get-project.ts`, `delete-workspace.ts` 26 26 - - **Utils**: Descriptive names in `utils/` directories 27 27 - - **Domain Modules**: Each module has `controllers/` and `index.ts` 39 39 + Key Biome rules enabled: 28 40 29 29 - ### Frontend Conventions 30 30 - - **Components**: Organized by feature in `components/` 31 31 - - **Hooks**: Custom hooks in `hooks/mutations/` and `hooks/queries/` 32 32 - - **Fetchers**: API calls organized by domain in `fetchers/` 33 33 - - **Types**: TypeScript definitions in `types/` by domain 41 41 + - `noParameterAssign`: Don't reassign function parameters 42 42 + - `useAsConstAssertion`: Use `as const` for literal types 43 43 + - `useDefaultParameterLast`: Default parameters must be last 44 44 + - `useSelfClosingElements`: Use self-closing JSX elements 45 45 + - `useSingleVarDeclarator`: One variable per declaration 46 46 + - `noInferrableTypes`: Don't add explicit types that can be inferred 34 47 35 35 - ## Code Organization Patterns 48 48 + ```typescript 49 49 + // Good: Follows Biome rules 50 50 + const items = ["a", "b"] as const; 51 51 + function greet(name: string, greeting = "Hello") { 52 52 + return `${greeting}, ${name}`; 53 53 + } 54 54 + const x = 1; 55 55 + const y = 2; 36 56 37 37 - ### Backend Architecture 57 57 + // Bad: Violates Biome rules 58 58 + const items: string[] = ["a", "b"]; 59 59 + function greet(greeting = "Hello", name: string) { 60 60 + return `${greeting}, ${name}`; 61 61 + } 62 62 + const x = 1, y = 2; 38 63 ``` 39 39 - src/ 40 40 - ├── {domain}/ 41 41 - │ ├── controllers/ 42 42 - │ │ ├── create-{resource}.ts 43 43 - │ │ ├── get-{resource}.ts 44 44 - │ │ └── update-{resource}.ts 45 45 - │ ├── utils/ (optional) 46 46 - │ └── index.ts (exports routes) 64 64 + 65 65 + ### Running Linter 66 66 + 67 67 + ```bash 68 68 + # Check and auto-fix 69 69 + pnpm lint 70 70 + 71 71 + # Check only (no fixes) 72 72 + pnpm biome check . 47 73 ``` 48 74 49 49 - ### Frontend Architecture 75 75 + ## TypeScript Conventions 76 76 + 77 77 + ### Type Definitions 78 78 + 79 79 + - **Types**: Prefer types for all type definitions (object shapes, unions, intersections, computed types) 80 80 + - **Interfaces**: Only use interfaces when extending/merging is needed (rare) 81 81 + - **Inference**: Prefer type inference when types are obvious 82 82 + 83 83 + ```typescript 84 84 + // Good: Type for object shape 85 85 + type Task = { 86 86 + id: string; 87 87 + title: string; 88 88 + status: string; 89 89 + }; 90 90 + 91 91 + // Good: Type for union 92 92 + type Status = "to-do" | "in-progress" | "done"; 93 93 + 94 94 + // Good: Type inference 95 95 + const tasks: Task[] = []; // Explicit for arrays 96 96 + const count = tasks.length; // Inferred 50 97 ``` 51 51 - src/ 52 52 - ├── components/ 53 53 - │ ├── {feature}/ 54 54 - │ │ ├── index.tsx 55 55 - │ │ └── {sub-components}.tsx 56 56 - ├── fetchers/ 57 57 - │ └── {domain}/ 58 58 - ├── hooks/ 59 59 - │ ├── mutations/ 60 60 - │ └── queries/ 61 61 - └── types/ 62 62 - └── {domain}/ 98 98 + 99 99 + ### File Naming 100 100 + 101 101 + - **Components**: PascalCase: `TaskCard.tsx` 102 102 + - **Utilities**: kebab-case: `format-date.ts` 103 103 + - **Hooks**: camelCase with `use` prefix: `use-task.ts` 104 104 + - **Types**: kebab-case: `task-types.ts` 105 105 + 106 106 + ``` 107 107 + components/ 108 108 + ├── TaskCard.tsx # Component 109 109 + ├── task-card.tsx # Also acceptable 110 110 + └── utils/ 111 111 + └── format-date.ts # Utility function 112 112 + ``` 113 113 + 114 114 + ## Git Conventions 115 115 + 116 116 + ### Commit Messages 117 117 + 118 118 + Use [Conventional Commits](https://www.conventionalcommits.org/): 119 119 + 120 120 + ``` 121 121 + <type>: <description> 122 122 + 123 123 + [optional body] 124 124 + 125 125 + [optional footer] 126 126 + ``` 127 127 + 128 128 + #### Commit Types 129 129 + 130 130 + - `feat:` - New features 131 131 + - `fix:` - Bug fixes 132 132 + - `docs:` - Documentation changes 133 133 + - `refactor:` - Code refactoring (no feature/fix) 134 134 + - `test:` - Adding or updating tests 135 135 + - `chore:` - Maintenance tasks (deps, config, etc.) 136 136 + - `style:` - Code style changes (formatting, etc.) 137 137 + 138 138 + #### Examples 139 139 + 140 140 + ```bash 141 141 + feat: add bulk task operations 142 142 + fix: resolve calendar date selection bug 143 143 + docs: update deployment guide 144 144 + refactor: simplify task controller logic 145 145 + chore: update dependencies 146 146 + ``` 147 147 + 148 148 + ### Branch Naming 149 149 + 150 150 + Use descriptive branch names with prefixes: 151 151 + 152 152 + - `feat/` - New features 153 153 + - `fix/` - Bug fixes 154 154 + - `docs/` - Documentation 155 155 + - `refactor/` - Refactoring 156 156 + - `chore/` - Maintenance 157 157 + 158 158 + ```bash 159 159 + feat/bulk-task-operations 160 160 + fix/calendar-date-bug 161 161 + docs/update-deployment-guide 162 162 + ``` 163 163 + 164 164 + ## Import Organization 165 165 + 166 166 + Biome automatically organizes imports. Follow these patterns: 167 167 + 168 168 + ### Import Order 169 169 + 170 170 + 1. External packages 171 171 + 2. Internal packages (`@/` aliases) 172 172 + 3. Relative imports 173 173 + 174 174 + ```typescript 175 175 + // Good: Organized imports 176 176 + import { useState } from "react"; 177 177 + import { useQuery } from "@tanstack/react-query"; 178 178 + import { Button } from "@/components/ui/button"; 179 179 + import { TaskCard } from "./task-card"; 63 180 ``` 64 181 65 65 - ## TypeScript Conventions 182 182 + ### Import Style 66 183 67 67 - ### Import Organization 68 68 - 1. **External libraries** (React, Hono, etc.) 69 69 - 2. **Internal shared packages** (@kaneo/libs) 70 70 - 3. **Relative imports** (./components, ../utils) 184 184 + - Use named imports when possible 185 185 + - Group related imports 186 186 + - Remove unused imports (Biome does this automatically) 187 187 + 188 188 + ```typescript 189 189 + // Good: Named imports 190 190 + import { useState, useEffect } from "react"; 191 191 + import { Button, Input } from "@/components/ui"; 71 192 72 72 - ### Type Definitions 73 73 - - **Interfaces** for object shapes 74 74 - - **Types** for unions and computed types 75 75 - - **Enums** for constants with meaningful names 76 76 - - **Generics** for reusable type patterns 193 193 + // Avoid: Default imports when named available 194 194 + import React from "react"; // Prefer named imports 195 195 + ``` 77 196 78 78 - ## React Patterns 197 197 + ## File Structure 79 198 80 80 - ### Component Structure 81 81 - ```tsx 82 82 - // Props type 83 83 - type ComponentProps { 84 84 - prop: string 85 85 - } 199 199 + ### Component Files 86 200 87 87 - // Component with TypeScript 88 88 - function Component({ prop }: ComponentProps) { 89 89 - // Hooks first 90 90 - const [state, setState] = useState() 201 201 + ```typescript 202 202 + // 1. Imports (external, then internal) 203 203 + import { useState } from "react"; 204 204 + import { Button } from "@/components/ui/button"; 91 205 92 92 - // Event handlers 93 93 - const handleClick = () => {} 206 206 + // 2. Types 207 207 + type ComponentProps = { 208 208 + title: string; 209 209 + }; 94 210 95 95 - // Render 96 96 - return <div>{prop}</div> 211 211 + // 3. Component 212 212 + export function Component({ title }: ComponentProps) { 213 213 + // Implementation 97 214 } 98 215 216 216 + // 4. Exports (if needed) 99 217 export default Component; 100 218 ``` 101 219 102 102 - ### State Management 103 103 - - **TanStack Query** for server state 104 104 - - **Zustand** for client state: [apps/web/src/store/](mdc:apps/web/src/store) 105 105 - - **React Context** for theme and auth: [apps/web/src/components/providers/](mdc:apps/web/src/components/providers) 220 220 + ### API Controller Files 106 221 107 107 - ## API Design Patterns 222 222 + ```typescript 223 223 + // 1. Imports 224 224 + import db from "../../database"; 225 225 + import { taskTable } from "../../database/schema"; 108 226 109 109 - ### REST Conventions 110 110 - - **GET** `/api/{resource}` - List resources 111 111 - - **GET** `/api/{resource}/{id}` - Get single resource 112 112 - - **POST** `/api/{resource}` - Create resource 113 113 - - **PUT** `/api/{resource}/{id}` - Update resource 114 114 - - **DELETE** `/api/{resource}/{id}` - Delete resource 227 227 + // 2. Function 228 228 + export default async function getTask(id: string) { 229 229 + // Implementation 230 230 + } 231 231 + ``` 232 232 + 233 233 + ## Error Handling 115 234 116 116 - ### Response Format 235 235 + ### Backend 236 236 + 237 237 + Use Hono's HTTPException: 238 238 + 117 239 ```typescript 118 118 - // Success response 119 119 - { 120 120 - data: T, 121 121 - success: true 240 240 + import { HTTPException } from "hono/http-exception"; 241 241 + 242 242 + if (!task) { 243 243 + throw new HTTPException(404, { message: "Task not found" }); 122 244 } 245 245 + ``` 246 246 + 247 247 + ### Frontend 248 248 + 249 249 + Use try-catch with user-friendly messages: 123 250 124 124 - // Error response 125 125 - { 126 126 - error: string, 127 127 - success: false 251 251 + ```typescript 252 252 + import { toast } from "sonner"; 253 253 + 254 254 + try { 255 255 + await updateTask(taskId, data); 256 256 + toast.success("Task updated"); 257 257 + } catch (error) { 258 258 + toast.error( 259 259 + error instanceof Error ? error.message : "Failed to update task", 260 260 + ); 128 261 } 129 262 ``` 130 263 131 131 - ## Git Conventions 264 264 + ## Testing 132 265 133 133 - ### Commit Messages 134 134 - Following [Conventional Commits](mdc:https:/www.conventionalcommits.org): 135 135 - - `feat:` new features 136 136 - - `fix:` bug fixes 137 137 - - `docs:` documentation changes 138 138 - - `style:` formatting changes 139 139 - - `refactor:` code refactoring 140 140 - - `test:` adding tests 141 141 - - `chore:` maintenance tasks 266 266 + ### Test Structure 142 267 143 143 - ### Branch Naming 144 144 - - `feature/description` for new features 145 145 - - `fix/description` for bug fixes 146 146 - - `docs/description` for documentation 147 147 - - `refactor/description` for refactoring 268 268 + ```typescript 269 269 + describe("Feature", () => { 270 270 + it("should do something", () => { 271 271 + // Arrange 272 272 + const input = "test"; 273 273 + 274 274 + // Act 275 275 + const result = functionUnderTest(input); 276 276 + 277 277 + // Assert 278 278 + expect(result).toBe("expected"); 279 279 + }); 280 280 + }); 281 281 + ``` 282 282 + 283 283 + ## Documentation 284 284 + 285 285 + ### Code Comments 286 286 + 287 287 + - **Why, not what**: Explain reasoning, not obvious code 288 288 + - **Complex logic**: Comment complex algorithms or business rules 289 289 + - **TODOs**: Use `// TODO: description` for future work 290 290 + 291 291 + ```typescript 292 292 + // Good: Explains why 293 293 + // Use CUID2 instead of UUID for better database performance 294 294 + const id = createId(); 295 295 + 296 296 + // Bad: States the obvious 297 297 + // Create an ID 298 298 + const id = createId(); 299 299 + ``` 300 300 + 301 301 + ### README Files 302 302 + 303 303 + - Keep README files updated 304 304 + - Include setup instructions 305 305 + - Document environment variables 306 306 + - Provide examples 307 307 + 308 308 + ## Environment Variables 309 309 + 310 310 + - **Single `.env` file**: All variables in project root 311 311 + - **Documentation**: Document all variables in `ENVIRONMENT_SETUP.md` 312 312 + - **Never commit**: `.env` files are gitignored 313 313 + - **Defaults**: Provide sensible defaults in code when possible 314 314 + 315 315 + ## Performance 316 316 + 317 317 + ### Backend 318 318 + 319 319 + - Use database indexes for frequently queried columns 320 320 + - Limit query results with pagination 321 321 + - Use transactions for multi-step operations 322 322 + 323 323 + ### Frontend 324 324 + 325 325 + - Use React Query for caching and data fetching 326 326 + - Implement proper loading states 327 327 + - Lazy load routes when possible 328 328 + - Optimize images and assets 329 329 + 330 330 + ## Security 331 331 + 332 332 + - **Never commit secrets**: Use environment variables 333 333 + - **Validate inputs**: Always validate user input (Valibot on backend) 334 334 + - **Sanitize outputs**: Sanitize data before rendering 335 335 + - **Authentication**: Always check authentication in protected routes 336 336 + - **Authorization**: Verify user permissions before operations

+285 -51

.cursor/rules/frontend-web.mdc

reviewed

··· 1 1 --- 2 2 - description: 3 3 - globs: 2 2 + description: Frontend web development guidelines for React, TanStack Router, and TanStack Query 3 3 + globs: apps/web/**/* 4 4 alwaysApply: false 5 5 --- 6 6 - # Frontend Web Application Structure 6 6 + # Frontend Web Guidelines 7 7 8 8 - The frontend web application is located in [apps/web/](mdc:apps/web) and is built with React, Vite, and TanStack Router. 8 8 + The Kaneo web application is built with React, TanStack Router, TanStack Query, and Vite. This document outlines conventions and patterns for frontend development. 9 9 10 10 - ## Project Structure 10 10 + ## Framework: React 11 11 12 12 - ### Core Files 13 13 - - **Entry Point**: [apps/web/src/main.tsx](mdc:apps/web/src/main.tsx) - React application root 14 14 - - **Root Route**: [apps/web/src/routes/__root.tsx](mdc:apps/web/src/routes/__root.tsx) - Root layout and providers 15 15 - - **Router Config**: [apps/web/src/tanstack/router.tsx](mdc:apps/web/src/tanstack/router.tsx) - TanStack Router setup 16 16 - - **Route Tree**: [apps/web/src/routeTree.gen.ts](mdc:apps/web/src/routeTree.gen.ts) - Auto-generated route tree 17 17 - - **Global Styles**: [apps/web/src/index.css](mdc:apps/web/src/index.css) - Tailwind CSS imports 12 12 + ### Component Structure 18 13 19 19 - ### Routing Structure (`src/routes/`) 20 20 - - **Dashboard**: [apps/web/src/routes/dashboard.tsx](mdc:apps/web/src/routes/dashboard.tsx) - Main dashboard layout 21 21 - - **Auth Routes**: [apps/web/src/routes/auth/](mdc:apps/web/src/routes/auth) - Sign in/up pages 22 22 - - **Home**: [apps/web/src/routes/index.tsx](mdc:apps/web/src/routes/index.tsx) - Landing page 14 14 + Components are organized in `apps/web/src/components/`: 23 15 24 24 - ### Components Architecture (`src/components/`) 16 16 + ```typescript 17 17 + // apps/web/src/components/task/task-card.tsx 18 18 + import { Task } from "@/types/task"; 25 19 26 26 - #### Feature Components 27 27 - - **Auth**: [apps/web/src/components/auth/](mdc:apps/web/src/components/auth) - Authentication forms and layouts 28 28 - - **Dashboard**: [apps/web/src/components/dashboard/](mdc:apps/web/src/components/dashboard) - Dashboard specific components 29 29 - - **Task Management**: 30 30 - - [apps/web/src/components/kanban-board/](mdc:apps/web/src/components/kanban-board) - Kanban board view 31 31 - - [apps/web/src/components/list-view/](mdc:apps/web/src/components/list-view) - List view for tasks 32 32 - - [apps/web/src/components/backlog-list-view/](mdc:apps/web/src/components/backlog-list-view) - Backlog view 33 33 - - [apps/web/src/components/task/](mdc:apps/web/src/components/task) - Task detail components 34 34 - - **Project**: [apps/web/src/components/project/](mdc:apps/web/src/components/project) - Project management components 35 35 - - **Team**: [apps/web/src/components/team/](mdc:apps/web/src/components/team) - Team management components 20 20 + type TaskCardProps = { 21 21 + task: Task; 22 22 + onUpdate?: (task: Task) => void; 23 23 + }; 36 24 37 37 - #### Common Components 38 38 - - **UI Library**: [apps/web/src/components/ui/](mdc:apps/web/src/components/ui) - Shadcn/ui components 39 39 - - **Common**: [apps/web/src/components/common/](mdc:apps/web/src/components/common) - Shared components (Editor, Logo, Sidebar) 40 40 - - **Providers**: [apps/web/src/components/providers/](mdc:apps/web/src/components/providers) - React context providers 25 25 + export function TaskCard({ task, onUpdate }: TaskCardProps) { 26 26 + return ( 27 27 + <div className="p-4 border rounded-lg"> 28 28 + <h3>{task.title}</h3> 29 29 + {/* ... */} 30 30 + </div> 31 31 + ); 32 32 + } 33 33 + ``` 41 34 42 42 - ## Data Management 35 35 + ### Best Practices 43 36 44 44 - ### API Integration (`src/fetchers/`) 45 45 - - **TanStack Query**: [apps/web/src/query-client/index.ts](mdc:apps/web/src/query-client/index.ts) - Query client setup 46 46 - - **Fetchers**: Domain-specific API calls organized by feature (task, project, user, etc.) 47 47 - - **Hooks**: 48 48 - - **Mutations**: [apps/web/src/hooks/mutations/](mdc:apps/web/src/hooks/mutations) - Data mutation hooks 49 49 - - **Queries**: [apps/web/src/hooks/queries/](mdc:apps/web/src/hooks/queries) - Data fetching hooks 37 37 + 1. **TypeScript**: Always type props and component return types 38 38 + 2. **Component naming**: Use PascalCase for component files and exports 39 39 + 3. **Props destructuring**: Destructure props in function parameters 40 40 + 4. **Conditional rendering**: Use ternary or logical operators clearly 50 41 51 51 - ### State Management (`src/store/`) 52 52 - - **Zustand Stores**: 53 53 - - [apps/web/src/store/project.ts](mdc:apps/web/src/store/project.ts) - Project state 54 54 - - [apps/web/src/store/workspace.ts](mdc:apps/web/src/store/workspace.ts) - Workspace state 55 55 - - [apps/web/src/store/user-preferences.ts](mdc:apps/web/src/store/user-preferences.ts) - User preferences 42 42 + ```typescript 43 43 + // Good: Typed component with clear structure 44 44 + type ButtonProps = { 45 45 + variant?: "primary" | "secondary"; 46 46 + children: React.ReactNode; 47 47 + onClick?: () => void; 48 48 + }; 56 49 57 57 - ## Type Definitions (`src/types/`) 58 58 - - **API Types**: [apps/web/src/types/api-response.ts](mdc:apps/web/src/types/api-response.ts) 59 59 - - **Domain Types**: Organized by feature (task, project, workspace, etc.) 50 50 + export function Button({ variant = "primary", children, onClick }: ButtonProps) { 51 51 + return ( 52 52 + <button 53 53 + className={cn("px-4 py-2", variant === "primary" && "bg-blue-500")} 54 54 + onClick={onClick} 55 55 + > 56 56 + {children} 57 57 + </button> 58 58 + ); 59 59 + } 60 60 61 61 - ## Utilities and Constants 62 62 - - **Utilities**: [apps/web/src/lib/](mdc:apps/web/src/lib) - Helper functions and utilities 63 63 - - **Constants**: [apps/web/src/constants/](mdc:apps/web/src/constants) - App constants (columns, colors, icons) 61 61 + // Bad: Untyped, unclear structure 62 62 + export function Button(props: any) { 63 63 + return <button onClick={props.onClick}>{props.children}</button>; 64 64 + } 65 65 + ``` 64 66 65 65 - ## Configuration 66 66 - - **Components**: [apps/web/components.json](mdc:apps/web/components.json) - Shadcn/ui configuration 67 67 - - **Package**: [apps/web/package.json](mdc:apps/web/package.json) - Dependencies and scripts 67 67 + ## Routing: TanStack Router 68 68 + 69 69 + ### File-Based Routing 70 70 + 71 71 + Routes are defined using file-based routing in `apps/web/src/routes/`: 72 72 + 73 73 + ```typescript 74 74 + // apps/web/src/routes/tasks/$taskId.tsx 75 75 + import { createFileRoute } from "@tanstack/react-router"; 76 76 + import { useTask } from "@/hooks/queries/task/use-task"; 77 77 + 78 78 + export const Route = createFileRoute("/tasks/$taskId")({ 79 79 + component: TaskPage, 80 80 + }); 81 81 + 82 82 + function TaskPage() { 83 83 + const { taskId } = Route.useParams(); 84 84 + const { data: task } = useTask(taskId); 85 85 + 86 86 + if (!task) return <div>Loading...</div>; 87 87 + 88 88 + return <div>{task.title}</div>; 89 89 + } 90 90 + ``` 91 91 + 92 92 + ### Route Patterns 93 93 + 94 94 + - **Layout routes**: Use `_layout.tsx` for shared layouts 95 95 + - **Auth routes**: Grouped in `auth/` directory 96 96 + - **Dynamic routes**: Use `$param` syntax for route parameters 97 97 + 98 98 + ```typescript 99 99 + // Layout route: apps/web/src/routes/_layout.tsx 100 100 + export const Route = createFileRoute("/_layout")({ 101 101 + component: Layout, 102 102 + }); 103 103 + 104 104 + // Dynamic route: apps/web/src/routes/tasks/$taskId.tsx 105 105 + export const Route = createFileRoute("/tasks/$taskId")({ 106 106 + component: TaskPage, 107 107 + }); 108 108 + ``` 109 109 + 110 110 + ## Data Fetching: TanStack Query 111 111 + 112 112 + ### Query Hooks 113 113 + 114 114 + Create query hooks in `apps/web/src/hooks/queries/`: 115 115 + 116 116 + ```typescript 117 117 + // apps/web/src/hooks/queries/task/use-task.ts 118 118 + import { useQuery } from "@tanstack/react-query"; 119 119 + import { getTask } from "@/fetchers/task/get-task"; 120 120 + 121 121 + export function useTask(taskId: string) { 122 122 + return useQuery({ 123 123 + queryKey: ["task", taskId], 124 124 + queryFn: () => getTask(taskId), 125 125 + }); 126 126 + } 127 127 + ``` 128 128 + 129 129 + ### Mutation Hooks 130 130 + 131 131 + Create mutation hooks in `apps/web/src/hooks/mutations/`: 132 132 + 133 133 + ```typescript 134 134 + // apps/web/src/hooks/mutations/task/use-update-task.ts 135 135 + import { useMutation, useQueryClient } from "@tanstack/react-query"; 136 136 + import { updateTask } from "@/fetchers/task/update-task"; 137 137 + import { toast } from "sonner"; 138 138 + 139 139 + export function useUpdateTask() { 140 140 + const queryClient = useQueryClient(); 141 141 + 142 142 + return useMutation({ 143 143 + mutationFn: updateTask, 144 144 + onSuccess: () => { 145 145 + queryClient.invalidateQueries({ queryKey: ["task"] }); 146 146 + toast.success("Task updated"); 147 147 + }, 148 148 + onError: (error) => { 149 149 + toast.error(error.message); 150 150 + }, 151 151 + }); 152 152 + } 153 153 + ``` 154 154 + 155 155 + ### Best Practices 156 156 + 157 157 + 1. **Query keys**: Use arrays with consistent structure: `["resource", id]` 158 158 + 2. **Invalidation**: Invalidate related queries after mutations 159 159 + 3. **Error handling**: Use toast notifications for user feedback 160 160 + 4. **Loading states**: Handle loading and error states in components 161 161 + 162 162 + ```typescript 163 163 + // Good: Proper query with error handling 164 164 + function TaskPage() { 165 165 + const { taskId } = Route.useParams(); 166 166 + const { data: task, isLoading, error } = useTask(taskId); 167 167 + 168 168 + if (isLoading) return <Skeleton />; 169 169 + if (error) return <Error message={error.message} />; 170 170 + if (!task) return <NotFound />; 171 171 + 172 172 + return <TaskDetails task={task} />; 173 173 + } 174 174 + ``` 175 175 + 176 176 + ## Fetchers 177 177 + 178 178 + API calls are abstracted in `apps/web/src/fetchers/`: 179 179 + 180 180 + ```typescript 181 181 + // apps/web/src/fetchers/task/get-task.ts 182 182 + import { apiClient } from "@/lib/api-client"; 183 183 + 184 184 + export async function getTask(taskId: string) { 185 185 + const response = await apiClient.get(`/api/task/${taskId}`); 186 186 + return response.data; 187 187 + } 188 188 + ``` 189 189 + 190 190 + ### Fetcher Organization 191 191 + 192 192 + Organize fetchers by feature, mirroring API structure: 193 193 + 194 194 + ``` 195 195 + apps/web/src/fetchers/ 196 196 + ├── task/ 197 197 + │ ├── get-task.ts 198 198 + │ ├── update-task.ts 199 199 + │ └── create-task.ts 200 200 + ├── project/ 201 201 + │ └── ... 202 202 + └── workspace/ 203 203 + └── ... 204 204 + ``` 205 205 + 206 206 + ## Styling: Tailwind CSS 207 207 + 208 208 + Use Tailwind CSS utility classes: 209 209 + 210 210 + ```typescript 211 211 + <div className="flex items-center gap-4 p-4 bg-white rounded-lg shadow"> 212 212 + <h2 className="text-xl font-semibold">Title</h2> 213 213 + </div> 214 214 + ``` 215 215 + 216 216 + ### Utility Functions 217 217 + 218 218 + Use `cn()` utility for conditional classes: 219 219 + 220 220 + ```typescript 221 221 + import { cn } from "@/lib/cn"; 222 222 + 223 223 + <button 224 224 + className={cn( 225 225 + "px-4 py-2 rounded", 226 226 + isActive && "bg-blue-500 text-white", 227 227 + disabled && "opacity-50 cursor-not-allowed", 228 228 + )} 229 229 + > 230 230 + Click me 231 231 + </button> 232 232 + ``` 233 233 + 234 234 + ## Authentication 235 235 + 236 236 + Use Better Auth client for authentication: 237 237 + 238 238 + ```typescript 239 239 + import { authClient } from "@/lib/auth-client"; 240 240 + 241 241 + // Sign in 242 242 + await authClient.signIn.email({ 243 243 + email: "user@example.com", 244 244 + password: "password", 245 245 + }); 246 246 + 247 247 + // Get current user 248 248 + const session = await authClient.getSession(); 249 249 + ``` 250 250 + 251 251 + ## File Organization 252 252 + 253 253 + ``` 254 254 + apps/web/src/ 255 255 + ├── components/ # React components 256 256 + │ ├── ui/ # Base UI components 257 257 + │ └── ... 258 258 + ├── fetchers/ # API call functions 259 259 + ├── hooks/ # Custom React hooks 260 260 + │ ├── queries/ # TanStack Query hooks 261 261 + │ └── mutations/ # TanStack Query mutations 262 262 + ├── lib/ # Utility functions 263 263 + ├── routes/ # TanStack Router routes 264 264 + ├── store/ # Global state (Zustand) 265 265 + ├── types/ # TypeScript types 266 266 + └── main.tsx # Entry point 267 267 + ``` 268 268 + 269 269 + ## Type Safety 270 270 + 271 271 + Share types between frontend and backend when possible: 272 272 + 273 273 + ```typescript 274 274 + // apps/web/src/types/task.ts 275 275 + export type Task = { 276 276 + id: string; 277 277 + title: string; 278 278 + description?: string; 279 279 + status: string; 280 280 + priority: string; 281 281 + dueDate?: string; 282 282 + createdAt: string; 283 283 + }; 284 284 + ``` 285 285 + 286 286 + ## Error Handling 287 287 + 288 288 + Handle errors gracefully with user-friendly messages: 289 289 + 290 290 + ```typescript 291 291 + import { toast } from "sonner"; 292 292 + 293 293 + try { 294 294 + await updateTask(taskId, data); 295 295 + toast.success("Task updated"); 296 296 + } catch (error) { 297 297 + toast.error( 298 298 + error instanceof Error ? error.message : "Failed to update task", 299 299 + ); 300 300 + } 301 301 + ```

+71 -29

.cursor/rules/project-overview.mdc

reviewed

··· 1 1 --- 2 2 - description: 3 3 - globs: 4 4 - alwaysApply: false 2 2 + description: Overview of the Kaneo project structure, architecture, and key technologies 3 3 + globs: 4 4 + alwaysApply: true 5 5 --- 6 6 - # Kaneo Project Overview 6 6 + # Project Overview 7 7 8 8 - Kaneo is a modern project management application built as a monorepo with multiple applications and shared packages. 8 8 + Kaneo is a self-hosted project management platform built with a focus on simplicity and performance. This document provides an overview of the project structure and architecture. 9 9 10 10 - ## Architecture 10 10 + ## Project Structure 11 11 12 12 - This is a **monorepo** containing: 12 12 + Kaneo is organized as a **monorepo** using pnpm workspaces: 13 13 14 14 - ### Applications (`apps/`) 15 15 - - **`api/`** - Backend API built with Hono framework and TypeScript 16 16 - - **`web/`** - Frontend React application with Vite and TanStack Router 17 17 - - **`docs/`** - Documentation website built with Next.js 14 14 + ``` 15 15 + kaneo/ 16 16 + ├── apps/ 17 17 + │ ├── api/ # Backend API (Hono/Node.js) 18 18 + │ ├── docs/ # Documentation site (Next.js) 19 19 + │ └── web/ # Frontend app (React/Vite) 20 20 + ├── packages/ # Shared code and configs 21 21 + │ ├── email/ # Email utilities 22 22 + │ ├── libs/ # Shared libraries 23 23 + │ └── typescript-config/ # TypeScript configurations 24 24 + ├── charts/ # Kubernetes Helm charts 25 25 + ├── .cursor/ # Cursor IDE rules 26 26 + └── compose.yml # Docker Compose configuration 27 27 + ``` 18 28 19 19 - ### Packages (`packages/`) 20 20 - - **`libs/`** - Shared TypeScript utilities and Hono extensions 21 21 - - **`typescript-config/`** - Shared TypeScript configurations 29 29 + ## Technology Stack 22 30 23 23 - ## Key Technologies 31 31 + ### Backend (API) 32 32 + - **Framework**: Hono (lightweight web framework) 33 33 + - **Runtime**: Node.js 34 34 + - **Database**: PostgreSQL with Drizzle ORM 35 35 + - **Authentication**: Better Auth 36 36 + - **Validation**: Valibot 37 37 + - **API Documentation**: OpenAPI (hono-openapi) 38 38 + - **Build Tool**: esbuild 24 39 25 25 - - **Backend**: Hono, TypeScript, Drizzle ORM, PostgreSQL 26 26 - - **Frontend**: React, Vite, TanStack Router, TanStack Query, Tailwind CSS 27 27 - - **Database**: PostgreSQL with Drizzle ORM migrations 28 28 - - **Deployment**: Docker, Kubernetes (Helm charts) 29 29 - - **Monorepo**: Turborepo for build orchestration 40 40 + ### Frontend (Web) 41 41 + - **Framework**: React 18+ 42 42 + - **Routing**: TanStack Router 43 43 + - **Data Fetching**: TanStack Query (React Query) 44 44 + - **Build Tool**: Vite 45 45 + - **Styling**: Tailwind CSS 46 46 + - **UI Components**: Custom component library 30 47 31 31 - ## Entry Points 48 48 + ### Development Tools 49 49 + - **Package Manager**: pnpm 50 50 + - **Linting/Formatting**: Biome 51 51 + - **TypeScript**: Strict mode enabled 52 52 + - **Git Hooks**: Husky 32 53 33 33 - - Backend API: [apps/api/src/index.ts](mdc:apps/api/src/index.ts) 34 34 - - Frontend Web App: [apps/web/src/main.tsx](mdc:apps/web/src/main.tsx) 35 35 - - Documentation: [apps/docs/app/layout.tsx](mdc:apps/docs/app/layout.tsx) 54 54 + ## Key Principles 36 55 37 37 - ## Configuration Files 56 56 + 1. **Simplicity First**: Features exist to solve real problems, not to impress 57 57 + 2. **Performance**: Fast load times and responsive interactions 58 58 + 3. **Self-Hosted**: Your data stays yours 59 59 + 4. **Open Source**: Free forever, MIT licensed 38 60 39 39 - - Database config: [apps/api/drizzle.config.ts](mdc:apps/api/drizzle.config.ts) 40 40 - - Database schema: [apps/api/src/database/schema.ts](mdc:apps/api/src/database/schema.ts) 41 41 - - Backend package.json: [apps/api/package.json](mdc:apps/api/package.json) 42 42 - - Frontend package.json: [apps/web/package.json](mdc:apps/web/package.json) 61 61 + ## Development Workflow 62 62 + 63 63 + 1. **Install dependencies**: `pnpm install` 64 64 + 2. **Start development**: `pnpm dev` (starts both API and web) 65 65 + 3. **Lint code**: `pnpm lint` (runs Biome) 66 66 + 4. **Database migrations**: `pnpm --filter @kaneo/api db:generate` and `db:migrate` 67 67 + 68 68 + ## Environment Setup 69 69 + 70 70 + All environment variables are configured in a single `.env` file at the project root. See `ENVIRONMENT_SETUP.md` for detailed configuration instructions. 71 71 + 72 72 + ## Deployment 73 73 + 74 74 + - **Docker Compose**: Quick setup for development/testing 75 75 + - **Kubernetes**: Production-ready Helm charts in `charts/` 76 76 + - **Self-Hosted**: Designed to run on your infrastructure 77 77 + 78 78 + ## Contributing 79 79 + 80 80 + See `CONTRIBUTING.md` for guidelines on: 81 81 + - Code style (Biome configuration) 82 82 + - Commit messages (Conventional Commits) 83 83 + - Project structure conventions 84 84 + - Getting help