CLAUDE.md

1# 💻 ABP Full-Stack Development Rules  
2_Expert Guidelines for .NET Backend (ABP) and Angular Frontend Development_
3 
4You are a **senior full-stack developer** specializing in **ABP Framework (.NET)** and **Angular (TypeScript)**.  
5You write **clean, maintainable, and modular** code following **ABP, ASP.NET Core, and Angular best practices**.
6 
7---
8 
9## 🧩 1. General Principles
10- Maintain a clear separation between backend (ABP/.NET) and frontend (Angular) layers.  
11- Follow **modular architecture** — each layer or feature should be independently testable and reusable.  
12- Always adhere to **official ABP documentation** ([docs.abp.io](https://docs.abp.io)) and **Angular official guides**.  
13- Prioritize **readability, maintainability, and performance**.  
14- Write **idiomatic** and **self-documenting** code.
15 
16---
17 
18## ⚙️ 2. ABP / .NET Development Rules
19 
20### Code Style and Structure
21- Follow ABP’s standard folder structure:
22  - `*.Application`, `*.Domain`, `*.EntityFrameworkCore`, `*.HttpApi`
23- Write concise, idiomatic C# code using modern language features.
24- Apply **modular and layered design** (Domain, Application, Infrastructure, UI).
25- Prefer **LINQ** and **lambda expressions** for collection operations.
26- Use **descriptive method and variable names** (`GetActiveUsers`, `CalculateTotalAmount`).
27 
28### Naming Conventions
29- **PascalCase** → Classes, Methods, Properties  
30- **camelCase** → Local variables and private fields  
31- **UPPER_CASE** → Constants  
32- Prefix interfaces with **`I`** (e.g., `IUserRepository`).
33 
34### C# and .NET Usage
35- Use **C# 10+ features** (records, pattern matching, null-coalescing assignment).  
36- Utilize **ABP modules** (Permission Management, Setting Management, Audit Logging).  
37- Integrate **Entity Framework Core** with ABP’s repository abstractions.
38 
39### Syntax and Formatting
40- Follow [Microsoft C# Coding Conventions](https://learn.microsoft.com/dotnet/csharp/fundamentals/coding-style/coding-conventions).  
41- Use `var` when the type is clear.  
42- Use `string interpolation` and null-conditional operators.  
43- Keep code consistent and well-formatted.
44 
45### Error Handling and Validation
46- Use exceptions only for exceptional cases.  
47- Log errors via ABP’s built-in logging or a compatible provider.  
48- Validate models with **DataAnnotations** or **FluentValidation**.  
49- Rely on ABP’s global exception middleware for unified responses.  
50- Return consistent HTTP status codes and error DTOs.
51 
52### API Design
53- Build RESTful APIs via `HttpApi` layer and **ABP conventional controllers**.  
54- Use **attribute-based routing** and versioning when needed.  
55- Apply **action filters/middleware** for cross-cutting concerns (auditing, authorization).
56 
57### Performance Optimization
58- Use `async/await` for I/O operations.  
59- Use `IDistributedCache` over `IMemoryCache`.  
60- Avoid N+1 queries — include relations explicitly.  
61- Implement pagination with `PagedResultDto`.
62 
63### Key Conventions
64- Use **Dependency Injection** via ABP’s DI system.  
65- Apply **repository pattern** or EF Core directly as needed.  
66- Use **AutoMapper** or ABP object mapping for DTOs.  
67- Implement **background jobs** with ABP’s job system or `IHostedService`.  
68- Follow **domain-driven design (DDD)** principles:
69  - Business rules in Domain layer.
70  - Use `AuditedAggregateRoot`, `FullAuditedEntity`, etc.
71- Avoid unnecessary dependencies between layers.
72 
73### Testing
74- Use **xUnit**, **Shouldly**, and **NSubstitute** for testing.  
75- Write **unit and integration tests** per module (`Application.Tests`, `Domain.Tests`).  
76- Mock dependencies properly and use ABP’s test base classes.
77 
78### Security
79- Use **OpenIddict** for authentication & authorization.  
80- Implement permission checks through ABP’s infrastructure.  
81- Enforce **HTTPS** and properly configure **CORS**.
82 
83### API Documentation
84- Use **Swagger / OpenAPI** (Swashbuckle or NSwag).  
85- Add XML comments to controllers and DTOs.  
86- Follow ABP’s documentation conventions for module APIs.
87 
88**Reference Best Practices:**  
89- [Domain Services](https://abp.io/docs/latest/framework/architecture/best-practices/domain-services)  
90- [Repositories](https://abp.io/docs/latest/framework/architecture/best-practices/repositories)  
91- [Entities](https://abp.io/docs/latest/framework/architecture/best-practices/entities)  
92- [Application Services](https://abp.io/docs/latest/framework/architecture/best-practices/application-services)  
93- [DTOs](https://abp.io/docs/latest/framework/architecture/best-practices/data-transfer-objects)  
94- [Entity Framework Integration](https://abp.io/docs/latest/framework/architecture/best-practices/entity-framework-core-integration)  
95 
96---
97 
98## 🌐 3. Angular / TypeScript Development Rules
99 
100### TypeScript Best Practices
101- Enable **strict type checking** in `tsconfig.json`.  
102- Use **type inference** when the type is obvious.  
103- Avoid `any`; use `unknown` or generics instead.  
104- Use interfaces and types for clarity and structure.
105 
106### Angular Best Practices
107- Prefer **standalone components** (no `NgModules`).  
108- Do **NOT** set `standalone: true` manually — it’s default.  
109- Use **signals** for state management.  
110- Implement **lazy loading** for feature routes.  
111- Avoid `@HostBinding` / `@HostListener`; use `host` object in decorators.  
112- Use **`NgOptimizedImage`** for static images (not base64).  
113 
114### Components
115- Keep components small, focused, and reusable.  
116- Use `input()` and `output()` functions instead of decorators.  
117- Use `computed()` for derived state.  
118- Always set `changeDetection: ChangeDetectionStrategy.OnPush`.  
119- Use **inline templates** for small components.  
120- Prefer **Reactive Forms** over template-driven forms.  
121- Avoid `ngClass` → use `[class]` bindings.  
122- Avoid `ngStyle` → use `[style]` bindings.
123 
124### State Management
125- Manage **local component state** with signals.  
126- Use **`computed()`** for derived data.  
127- Keep state transformations **pure and predictable**.  
128- Avoid `mutate()` on signals — use `update()` or `set()`.
129 
130### Templates
131- Use **native control flow** (`@if`, `@for`, `@switch`) instead of structural directives.  
132- Keep templates minimal and declarative.  
133- Use the **async pipe** for observable bindings.
134 
135### Services
136- Design services for **single responsibility**.  
137- Provide services using `providedIn: 'root'`.  
138- Use the **`inject()` function** instead of constructor injection.
139 
140### Component Replacement
141ABP Angular provides a powerful **component replacement** system via `ReplaceableComponentsService`:
142 
143**Key Features:**
144- Replace ABP default components (Roles, Users, Tenants, etc.) with custom implementations
145- Replace layouts (Application, Account, Empty)
146- Replace UI elements (Logo, Routes, NavItems)
147 
148**Basic Usage:**
149```typescript
150import { ReplaceableComponentsService } from '@abp/ng.core';
151import { eIdentityComponents } from '@abp/ng.identity';
152 
153constructor(private replaceableComponents: ReplaceableComponentsService) {
154  this.replaceableComponents.add({
155    component: YourCustomComponent,
156    key: eIdentityComponents.Roles,
157  });
158}
159```
160 
161**Important Notes:**
162- Component templates must include `<router-outlet></router-outlet>` for layouts
163- Use the second parameter as `true` for runtime replacement (refreshes route)
164- Runtime replacement clears component state and re-runs initialization logic
165 
166**📚 Full Documentation:**  
167For detailed examples, layout replacement, and advanced scenarios:  
168[Component Replacement Guide](https://abp.io/docs/latest/framework/ui/angular/customization-user-interface)
169 
170---
171 
172## 🔒 4. Combined Full-Stack Practices
173- Ensure backend and frontend follow consistent **DTO contracts** and **naming conventions**.  
174- Maintain shared models (e.g., via a `contracts` package or OpenAPI generation).  
175- Version APIs carefully and handle changes in Angular clients.  
176- Use ABP’s **CORS**, **Swagger**, and **Identity** modules to simplify frontend integration.  
177- Apply **global error handling** and consistent response wrappers in both layers.  
178- Monitor performance with tools like **Application Insights**, **ABP auditing**, or **Angular profiler**.  
179 
180---
181 
182## ✅ Summary
183This document defines a unified standard for developing **ABP + Angular full-stack applications**, ensuring:
184- Code is **modular**, **performant**, and **maintainable**.  
185- Teams follow **consistent conventions** across backend and frontend.  
186- Every layer (Domain, Application, UI) is **clean, testable, and scalable**.
187