You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
4
4
5
+
## Self-Improvement Instructions
6
+
7
+
**Claude Code must actively maintain and improve this file.**
8
+
9
+
After significant development sessions where new fundamental insights were gained together with the developer, Claude Code should:
10
+
11
+
1.**Update this file** with new learnings that are valuable for future development sessions (patterns, pitfalls, best practices discovered during implementation)
12
+
13
+
2.**Validate against best practices** - Check if this CLAUDE.md still follows Claude Code best practices and can be optimally utilized for development
14
+
15
+
3.**Optimize automatically** - Restructure, clarify, or extend sections as needed to maximize effectiveness
16
+
17
+
**Goal:** This CLAUDE.md should always be current and optimally structured so that Claude Code is perfectly briefed to extend and improve this project in the best possible way.
18
+
19
+
**When to update:**
20
+
- New architectural patterns established
21
+
- Important edge cases or pitfalls discovered
22
+
- New integrations added that require specific handling
23
+
- Development workflows improved
24
+
- Common mistakes identified that should be avoided
25
+
26
+
## Project Overview
27
+
28
+
### What is this?
29
+
This is **@lenne.tech/nest-server** - an extension/layer on top of [NestJS](https://docs.nestjs.com/) that provides additional functionality for building server applications with GraphQL and MongoDB.
-**Reference project**: Each new version is integrated and tested here
48
+
-**Migration documentation**: Commits document required changes for each version upgrade
49
+
50
+
3.**lt CLI** (https://github.com/lenneTech/cli)
51
+
- Command-line tool for project initialization and extension
52
+
- Server commands: https://github.com/lenneTech/cli/tree/main/src/commands/server
53
+
- Use `lt server module <ModuleName>` to generate new modules
54
+
55
+
## Important Development Guidelines
56
+
57
+
### Design Principles
58
+
59
+
**Dynamic Integration & Flexible Configuration**
60
+
61
+
All new components (third-party package integrations, elements in `src/core/common`, and modules in `src/core/modules`) must be designed with maximum flexibility:
62
+
63
+
1.**Dynamic Integrability**: Components should be opt-in and configurable at runtime or during module initialization. Avoid hardcoded dependencies that force all consumers to use specific features.
64
+
65
+
2.**Flexible Configuration**: Provide comprehensive configuration options so consuming projects can customize behavior without modifying this package. Use:
66
+
- Configuration interfaces with sensible defaults
67
+
- Factory methods for custom implementations
68
+
- Conditional feature activation via config flags
69
+
- Dependency injection for swappable implementations
70
+
71
+
3.**No Package Modification Required**: The goal is that projects using @lenne.tech/nest-server can fully leverage all features, customized to their specific needs, without ever needing to fork or modify this package.
// Bad: Hardcoded behavior that can't be customized
83
+
```
84
+
85
+
### When Modifying This Package
86
+
87
+
1.**Backward Compatibility**: Changes affect all projects using this package. Consider breaking changes carefully.
88
+
89
+
2.**Version Documentation**: After significant changes, the corresponding update must be applied and documented in the [nest-server-starter](https://github.com/lenneTech/nest-server-starter) repository.
90
+
91
+
3.**Test Coverage**: All changes must pass E2E tests (`npm test`). Production-ready code requires all tests to pass without errors.
92
+
93
+
4.**Export Management**: New public components must be exported via `src/index.ts` to be available to consuming projects.
94
+
95
+
### Code Organization
96
+
97
+
-`src/core/` - **Reusable framework components** (exported to consumers)
|`MAJOR`| Mirrors the NestJS major version (e.g., `11.x.x` = NestJS 11) |
238
+
|`MINOR`| Breaking changes or significant restructuring |
239
+
|`PATCH`| Improvements (bugfixes) or additions (new features) - non-breaking |
240
+
241
+
**Examples:**
242
+
-`11.0.0` → Initial release for NestJS 11
243
+
-`11.1.0` → Breaking change or major restructuring within NestJS 11
244
+
-`11.1.5` → Bugfix or new feature (backward compatible)
245
+
246
+
**Important:** When incrementing the minor version, always document the breaking changes clearly in the commit message and ensure the nest-server-starter is updated with migration instructions.
247
+
248
+
### Release Process
249
+
1. Make changes and ensure all tests pass
250
+
2. Update version in `package.json`
251
+
3. Build the package (`npm run build`)
252
+
4. Publish to npm
253
+
5. Update and test in nest-server-starter
254
+
6. Commit changes to starter with migration notes
255
+
256
+
### Package Exports
257
+
- Main entry: `dist/index.js`
258
+
- Types: `dist/index.d.ts`
259
+
- All public APIs exported from `src/index.ts`
127
260
128
261
## Environment Configuration
129
262
@@ -142,4 +275,78 @@ This package serves dual purposes:
142
275
### Email Configuration
143
276
- Supports both SMTP and Mailjet providers
144
277
- Template rendering with EJS
145
-
- Development uses Ethereal Email / MailHog for testing
278
+
- Development uses Ethereal Email / MailHog for testing
279
+
280
+
## Debugging & Troubleshooting
281
+
282
+
### Common Issues
283
+
284
+
**E2E Tests Timeout or Fail**
285
+
- Ensure MongoDB is running on `localhost:27017`
286
+
- Verify `NODE_ENV=local` is set
287
+
- Use `npm run test:e2e-doh` for open handle detection
288
+
- Check test timeout settings in `vitest.config.ts`
289
+
290
+
**GraphQL Introspection Not Working**
291
+
- Verify introspection is enabled in `config.env.ts` for non-production
292
+
- Check Apollo Server configuration in CoreModule
293
+
294
+
**Database Connection Failures**
295
+
- Verify MongoDB connection string in environment config
- Check module is properly imported in CoreModule or target module
302
+
- Run `npm run build` to regenerate dist files
303
+
304
+
**Validation Errors Not Showing**
305
+
- Ensure `MapAndValidatePipe` is applied
306
+
- Check class-validator decorators on input classes
307
+
- Verify DTO extends correct base class
308
+
309
+
## Role System (RoleEnum)
310
+
311
+
The role system distinguishes between **real roles** and **system roles**:
312
+
313
+
### Real Roles
314
+
Actual roles stored in `user.roles` array in the database:
315
+
-`RoleEnum.ADMIN` - Administrator role
316
+
317
+
### System Roles (S_ Prefix)
318
+
System roles are used for **runtime checks only** and must **NEVER** be stored in `user.roles`:
319
+
320
+
| Role | Purpose | Check Logic |
321
+
|------|---------|-------------|
322
+
|`S_USER`| User is logged in |`currentUser` exists |
323
+
|`S_VERIFIED`| User is verified |`user.verified \|\| user.verifiedAt \|\| user.emailVerified`|
324
+
|`S_CREATOR`| User created the object |`object.createdBy === user.id`|
325
+
|`S_SELF`| User is accessing own data |`object.id === user.id`|
326
+
|`S_EVERYONE`| Public access | Always true |
327
+
|`S_NO_ONE`| Locked access | Always false |
328
+
329
+
### Critical Rule
330
+
```typescript
331
+
// CORRECT: Using S_ roles in decorators (runtime checks)
332
+
@Roles(RoleEnum.S_USER)
333
+
@Restricted(RoleEnum.S_VERIFIED)
334
+
335
+
// WRONG: Storing S_ roles in user.roles array
336
+
roles: [RoleEnum.S_USER] // ❌ NEVER do this!
337
+
338
+
// CORRECT: Empty roles or real roles only
339
+
roles: [] // ✓ Empty array
340
+
roles: [RoleEnum.ADMIN] // ✓ Real role
341
+
```
342
+
343
+
The `S_` prefix indicates a **system check**, not an actual role. These are evaluated dynamically at runtime based on context (current user, request, object being accessed).
344
+
345
+
## Best Practices for This Repository
346
+
347
+
1.**All code, comments, and documentation must be in English**
348
+
2.**Run tests before considering any change complete** - `npm test`
349
+
3.**Follow existing code patterns** for consistency across the codebase
350
+
4.**Consider downstream impact** - this package is used by multiple projects
351
+
5.**Document breaking changes** clearly for version updates
352
+
6.**Never store S_ roles in user.roles** - they are system checks, not actual roles
0 commit comments