Instruction file imported from demetriomjr/real-estate-crm (.cursor/rules/backend-architecture.mdc). Copyright stays with the author.

PROJECT ARCHITECTURE

• Follow Clean Architecture principles
• Use existing services and repositories, don't change the current architecture
• No dependency injection for Repositories and Controllers
• No interface contracts (Clean Architecture approach)

LAYER RESPONSIBILITIES AND DATA CONSTRAINTS

• Domain Layer: Models and interfaces for Prisma ↔ Repository ↔ Application communication
• Application Layer: Services orchestrate business logic, Controllers handle API/NestJS logic only
• Infrastructure Layer: Repositories map Prisma ↔ Domain models internally
• Controllers: Only know about DTOs
• Services/Validators/Mappers: Only know DTOs and Domain Models
• Repositories: Only know Prisma models and Domain Models
• Services never map: Use mappers sublayer for DTO ↔ Domain conversion
• Repositories use internal mappers: Handle Prisma ↔ Domain internally

LOGGING REQUIREMENTS

• Use NestJS Logger in all backend layers (Services, Repositories, Controllers)
• Log in every catch block with stack trace
• Log business operations (user creation, updates, authentication events)

DTO MAPPING RULES

• Flattened fields: Conjoint tables (person + user, business + person) use flattened fields
• Inherited lists: DTOs inherit lists from both entities based on developer choices
• No foreign keys: DTOs exclude foreign keys, primary keys, audit fields (unless explicitly set)
  • Based on development choices, created_at will be always returned in DTOs.
• Service strategy: Use service-level strategy to feed subdomain foreign keys properly
• NEVER create sub-objects: user.full_name not user.person.full_name
• Fragment relationships: OneToOne - fetch separately, flatten into DTO
• Subdomain relationships: OneToMany - include via Prisma with take: 10 limit

VALIDATION ARCHITECTURE

• Validation happens in Application layer under validators folder
• Follow domain model structure - one validator per domain

ERROR HANDLING PATTERNS

• Error handling is obsolete in logging patterns - dev interprets logs
• Only categorize errors in service response - concise messages for API users

AUDIT FIELD REQUIREMENTS

• All domain entities must implement IAudit or IAuditBase
• IAuditBase: Holds all audit fields except tenant_id (for subdomain tables)
• IAudit: Includes tenant_id (for master domain tables)
• Business is tenant orchestrator - no tenant_id needed in business table

MULTI-TENANCY CONTEXT

• Multi-tenant SaaS with tenant_id in JWT for security
• Middleware prepares sensitive JWT data for service layer consumption