Cline rules

1# Project Structure
2 
3This monorepo hosts all npm packages prefixed with `@project-name/` or `@jetstyle/` locally; they are not installed from a registry but are sourced from within this repository.
4 
5## Main Directories
6- `apps/` — Houses all applications including backend and frontend services, microservices, or single-page applications (SPA).
7  - Examples:
8    - `apps/task-tracker/` Example basic Task Tracker API implementation with OpenAPI + Hono + Drizzle ORM
9    - `apps/auth-svc/` (authentication service)
10    - `apps/core-hub/` (Next.js application to demonstrate capabilities of the platform)
11- `libs/` — Shared libraries, utilities, components, hooks, and types used across multiple applications.
12 
13## Code Organization Principles
14- Place each service/application in its own folder under `apps/`. Services/applications must not depend on one another.
15- Place shared components, hooks, types, and functions in `libs/` and import by name via `package.json` (e.g., `@jetstyle/utils`). Always specify version `^1.0.0` for all newly created packages and applications.
16- Use kebab-case for file and directory names; use camelCase for types and variables.
17- Store UI components (e.g., shadcn/ui) in `apps/web/src/components/ui` or equivalent.
18 
19## Post-Change Verification
20- After implementing code changes, run `npm run build` from the project root to ensure the code compiles. Do not attempt to start or run applications — the user will run and review code changes separately.
21- After building, confirm that there are no compilation errors or warnings before considering the change complete.
22 
23# Technology Stack
24 
25## Frontend Stack
26- Frameworks: Next.js + React + TypeScript + Tailwind
27- Styling/UI: Tailwind CSS, shadcn/ui
28- Icons: Lucide
29- Animation: Motion
30- Fonts: San Serif, Inter, Geist, Mona Sans, IBM Plex Sans, Manrope
31 
32## Backend Stack
33- Node.js
34- Drizzle ORM
35- Hono + Zod + OpenAPI
36- Backend project structure should follow `apps/api` or `apps/task-tracker` for consistency
37 
38# Frontend Rules
39 
40## shadcn/ui Components Usage
41- Compose and customize shadcn components through props; do not modify their source directly.
42- Use shadcn/ui for all UI components unless there is a significant reason otherwise.
43- Install shadcn components with the CLI: `cd apps/web && npx shadcn@latest add <component-name>` from the correct directory.
44- Never manually copy shadcn components; always use the CLI for consistency and convenient updates.
45- Place UI library components from shadcn in `apps/web/src/components/ui`.
46- Before new installs, check if the component already exists in `src/components/ui`.
47 
48## Localization
49- By default, create new applications with localization support; omit only if the user explicitly requests so.
50- For Next.js, use `next-intl`. For Vite, adopt a popular equivalent, following best practices.
51- Extract all texts from components into translation files, even for single-language projects.
52- Plan to segment translation texts into multiple manageable files, rather than one large collection.
53 
54## Working with React Components
55- Store all shared/reusable React components in `apps/web/src/components`.
56- Always use path aliases: `@/components/...` or `@/components/ui/...`.
57- Component filenames must use kebab-case (e.g., `course-card.tsx`).
58 
59## API Handling
60- Place all API request functions in `apps/web/src/api.ts` or domain-specific subfiles: `apps/web/src/api/<resource-name>.ts`.
61- Keep data fetching and mutation logic centralized in the API module; do not mix with components.
62- Always use exported API functions; never call `fetch` or `axios` directly in components.
63  - Example: Use `fetchOrganizations(search)` — do not write custom fetch logic.
64- Use `@jetstyle/requests` from `core/libs/requests` for API requests unless otherwise specified.
65- API functions handle error and success. Always check `err === null` before accessing `.value`.
66- When extending API endpoints, update the client API layer, following existing function signatures and error-handling patterns.
67- Before implementing API-related changes, provide a concise checklist of the planned tasks, including any module splits, function updates, or endpoint extensions.
68 
69### API Module Structure (Updated)
70- Prefer a folder-based structure over a single `api.ts`; split by domain: `src/api/projects.ts`, `src/api/threads.ts`, etc.
71- Each module exports domain-specific functions.
72- Naming: File names use kebab-case by domain (`projects.ts`). Functions use verbs and (where helpful) domain prefixes (`fetchProjects`, `patchProject`).
73- From components/pages, import only required functions from the specific API module, not from a barrel — unless it does not create monolithic or circular dependencies.
74- Handle all possible runtime errors in API functions, returning `TResult` for reliable error handling.
75 
76## Working with C* Types
77- C-prefixed types (e.g., `CUser`, `CProject`, `CTask`) define client-side structures/props.
78  - Do not redefine or duplicate C* types within components or hooks.
79- Always use the correct property names as defined in each C* type.
80 
81### Types Module Structure
82- Organize C* types by domain under `src/types/` (e.g., `src/types/projects.ts`). Avoid monolithic files.
83- If types are sourced from a shared package (e.g., `@jetstyle/utils`), favor re-exporting to keep import paths stable.
84- Naming: Files in kebab-case by domain; types in PascalCase, prefixed with `C`.
85- Keep backend and frontend schemas aligned: update domain files and adjust imports as backend changes occur.
86 
87## Other Guidelines
88- Keep business logic outside UI components; use hooks or utilities as appropriate.
89- Maintain a clear separation of data fetching, types, and UI logic for maintainability and testability.
90- Use path aliases such as `@/api/projects` or `@/types` for imports; avoid deep relative paths.
91 
92# Backend Rules
93 
94## Entity Schema Creation
95- Every entity must have: `id`, `uuid`, `createdAt`, `updatedAt`, and `tenant` fields.
96- Define schemas using Drizzle's `pgTable` in a single file (`src/schema.ts`).
97- For each table, create `InsertSchema`, `SelectSchema`, and `PatchSchema` (`PatchSchema` via `.partial()` from `InsertSchema`).
98- For enums, use `varchar` with enum restrictions, not `text`.
99- Do not use ORM relations; use explicit reference fields (e.g., `learningModuleId`).
100 
101## CRUD Endpoint Organization
102- Each resource has its own CRUD route file in `routes/`, named in kebab-case and plural (e.g., `learning-module-practices.ts`).
103- All paths inside a CRUD file are relative; prefix added during router assembly in `index.ts`.
104- Each CRUD file must export the default router (e.g., `export default app`).
105- Attach routers in `index.ts` via `.route('/api/resource-name', app)`.
106- Limit each file to a single resource's CRUD operations; never mix resources.
107 
108## Code Style and Structure
109- Follow structure and naming conventions of existing examples.
110- Use camelCase for variable, schema, and type names and kebab-case for file names.
111- Only standard operations (list, create, get by uuid, update, delete) in each CRUD file; no custom endpoints.
112 
113## JSONB Column Declaration in Drizzle (pgTable)
114- Declare JSONB columns using `$type<...>` for full type-safety in Drizzle:
115  - Example: `createdBy: jsonb('created_by').$type<CallMessageCreatedBy | null>().default(null)`
116- Default to `null` for JSONB columns unless a non-null object is required, preventing TypeScript and OpenAPI inconsistencies.
117- Database columns use snake_case; TypeScript fields use camelCase.
118- Define nearby TypeScript types for complex JSONB structures, reuse in `$type`.
119 
120### Zod Schemas for JSONB
121- Create and re-use dedicated zod schemas for each JSONB field, reflecting nullability/optionality.
122  - Example: `const createdBySchema = z.object({...}).nullable().optional()`
123- Extend insert/select schemas with JSONB schemas; do not inline object shapes in routes.
124- Patch schemas should be derived from insert schemas with `.partial()`.
125 
126### CRUD and OpenAPI Integration
127- Import and use exported insert/select schemas for route definitions.
128- For PATCH operations, always derive from insert using `.partial()` to maintain JSONB typing.
129 
130### Examples
131- Table column: `createdBy: jsonb('created_by').$type<{...} | null>().default(null)`
132- Zod:
133  - `const createdBySchema = z.object({...}).nullable().optional()`
134  - `export const SomeInsertSchema = createInsertSchema(TableSome).omit({...}).extend({ createdBy: createdBySchema })`
135  - `export const SomeSelectSchema = createSelectSchema(TableSome).extend({ createdBy: createdBySchema })`
136 
137### Common Pitfalls
138- Omitting `$type<...>` causes loss of types and OpenAPI schema generation problems.
139- Using `default({})` with nullable/optional zod results in mismatches. Prefer `default(null)` and `nullable().optional()` unless an object is always present.
140- Failing to extend insert/select schemas with JSONB fields causes TypeScript errors in CRUD/OpenAPI.
141 
142## Other Backend Recommendations
143- Before creating a new entity, review and follow existing examples closely.
144- Do not write migrations manually. Run `npm run create-migration` in the application's folder when changing models.
145 
146## Project Permissions
147- Use permission checks from `apps/auth-svc` and `libs/server-auth`. Install via `package.json` names.
148- Global permissions (e.g., `users:admin`, `tenants:admin`) are implemented in the User entity's `scopes` field, granting unrestricted access.
149- For SaaS, per-tenant permissions are managed with the `PermissionBind` entity (user/tenant link).
150- If a user has no global permissions but is part of a tenant, access is limited to that tenant.
151- Permission checks are centralized via the `getPermissions` function from `@jetstyle/server-auth`, used as required. Implement custom checks explicitly within endpoints when necessary.
152- All new services/endpoints must utilize the centralized permissions mechanism via `getPermissions` unless stated otherwise in the requirements.
153 
154# Frontend-Backend Connection Rules
155 
156## Overview
157- C* entities (e.g., CTask, CProject, CUser) on the frontend must mirror backend schema structure exactly.
158- Use the generic `TListResponse` for all list API responses involving C* types.
159 
160## C* Entity Structure Verification
161- When creating or editing a C* type for frontend, always verify against the backend entity in `schema.ts`.
162- Only include fields present in the backend table/entity type. Do not add frontend-only fields even if useful.
163- Mark frontend fields as optional only if they are optional in the backend.
164- Example: If `TableProjects` has `uuid`, `createdAt`, `updatedAt`, `tenant`, `title`, then `CProject` has only these fields.
165 
166## TListResponse Usage for Lists of C* Entities
167- Always type list API responses using `TListResponse<CEntity>`.
168- Never define custom list types (e.g., `CProjectListResp`); always use `TListResponse`:
169```ts
170  export type TListResponse<T> = {
171    result: T[]
172    total: number
173    limit: number
174    offset: number
175  }
176```
177- Example: API fetching a project list returns `TListResponse<CProject>`.
178 
179## Other Recommendations
180- When unsure, check `schema.ts` for field validation.
181 
182# Code Style Guidelines
183 
184## Import Statements
185- Always place import statements at the very top of files, before any other code.
186- Never use `require` alongside `import` in the same file.
187- Use dynamic `import()` only if necessary (e.g., for circular dependency avoidance), and only after confirming the need.
188- Example:
189```ts
190  import { foo } from './foo'
191  // ...rest of the code
192```
193 
194## Non-Null Assertion Ban
195- Avoid the `!` operator (non-null assertion). Use explicit type guards and runtime checks instead.
196- Example (not allowed): `array!.push(item)`
197- Preferred: `if (Array.isArray(array)) { array.push(item) }`
198 
199## TypeScript
200- Prefer to write type safe typescript code, don't use `as any` until you totally sure this is the only or most efficient way to solve the problem
201 
202## TResult Error Handling Principles
203- Functions returning `TResult` must never throw; they always return `{ err: null, value }` for success or `{ err: string }` for error.
204- Never wrap calls to `TResult`-returning functions in try/catch; check `result.err` directly.
205- Usage pattern:
206```ts
207  const res = await someApiCall();
208  if (res.err == null) {
209    // Success: use res.value
210  } else {
211    // Error: handle res.err (and optionally res.errDescription)
212  }
213```
214- If required, handle exceptions separately for cases not covered by `TResult` (e.g., network failures), but do not expect `TResult` to throw.
215- When adding new APIs/utilities, prefer returning `TResult` for consistent error handling.
216