Imported from tthau02/nexus-platform (.agents/AGENTS.md). Install upstream with npx skills add tthau02/nexus-platform --skill .agents. Copyright stays with the author.

Workspace Guidelines & Project Rules

⚠️ MANDATORY RULES FOR ALL DEVELOPERS AND AI AGENTS Every code change in this workspace must strictly adhere to the guidelines and rules defined below.

1. Monorepo Architecture (Turborepo)

• No Cross-App Imports: apps/web must NEVER import anything from apps/api directly (and vice versa).
• Shared Packages: Any code, config, or type definition shared between apps/api and apps/web must reside inside packages/ (e.g. @repo/types).
• Data Boundary Typing: All API Request/Response payloads, search query params, and domain models MUST use shared types exported from @repo/types.

2. Directory Layout & Naming Conventions

• Apps:
  • apps/api: NestJS backend. Feature modules live in src/modules/<feature>/.
  • apps/web: Next.js (App Router) frontend. Shared UI components live in components/shared/common and components/ui.
• Naming Conventions:
  • Files & Folders: kebab-case (e.g. user-role.entity.ts).
  • Classes & Components: PascalCase (e.g. UserService, CommonTable).
  • Variables & Functions: camelCase (e.g. getUserPermissions).
  • Database Tables & Columns: PascalCase for SQL Server (e.g. @Entity({ name: 'Users' }), @Column({ name: 'UserName' })).

3. Coding Standards & Clean Code

• DRY: Check for existing helpers in src/common/utils or components/shared/common before writing new utilities.
• Strict TypeScript: Do not use any. Use concrete types, generics (<T>), or shared types from @repo/types.
• Dead Code: Remove unused variables, empty functions, and commented-out code.
• SOLID Architecture:
  • Controllers: Only handle HTTP routing and DTO validation.
  • Services: Contain all core business logic.
  • Repositories/Entities: Handle TypeORM database persistence.

4. Frontend Design System & Best Practices

• Design System: Follow Starbucks-inspired warm cream canvas and green accent styling tokens in globals.css. Use ds- utility classes (ds-btn-primary-pill, ds-surface-card).
• State Management:
  • React Query (@tanstack/react-query) for all API communication and server data caching.
  • Redux Toolkit strictly for global client UI state.

5. Database & API Performance

• Database Filtering: Always filter at SQL level using TypeORM options or accentInsensitiveLike helper rather than filtering in-memory JS arrays.
• Password Security: Always hash passwords with bcrypt (salt factor 10). Never return passwordHash in API responses.