AI
ClaudeCode
Mario
Conventions Backend

Backend Engineering Conventions (TypeScript)

1. General Principles

  • MUST USE TYPESCRIPT!

  • NEVER DUPLICATE CODE! Always check if there is already a solution to the problem before writing your own code. If you find a solution, use it instead of reinventing the wheel. You MUST use existing code whenever possible.

  • SINGLE RESPONSIBILITY PRINCIPLE: Each module or function MUST have a single responsibility. This makes the code easier to understand, test, and maintain.

  • FOLLOW THE PROJECT ARCHITECTURE. You MUST make sure to split code into logical modules or features (e.g., domain-driven design concepts) and follow the layered architecture pattern as currently defined in the project.

  • MODULAR CODE. Code MUST be modular and decoupled to achieve better maintainability and reusability.

2. Best practices

  • You MUST use project defined dependencies documentation from package.json
  • You MUST use server actions and server components.
  • You MUST use Next.js best practices for server-side rendering (SSR) and static site generation (SSG).
  • You MUST split the backend code into self contained modules or features (e.g., domain-driven design concepts) and follow the layered architecture pattern as currently defined in the project.

3. IMPORTANT - BACKEND IMPLEMENTATION GUIDELINES

Before any new implementation or changes CHECK IF THERE IS ALREADY IMPLEMENTED A SERVICE OR REPOSITORY FOR THE FEATURE. IF SO, DO NOT START FROM SCRATCH. JUST REFERENCE THE EXISTING IMPLEMENTATION OR EXTEND THE EXISTING IMPLEMENTATION.

  1. Start with types: Define TypeScript interfaces and Zod schemas
  2. Database first: Update Prisma schema and run migrations
  3. Repository layer: Implement data access with organization scoping
  4. Service layer: Implement business logic and validation
  5. API routes: Create endpoints following authentication patterns

4. Frontend-Backend Integration Guidelines

4.1 API Design for URL-Driven Frontend

  • Design APIs to accept query parameters for filtering, sorting, and pagination.
  • Return paginated results with metadata (total count, page info, etc.).
  • Support search parameters across multiple fields.
  • Provide consistent response formats across all list endpoints.

4.2 Service Layer Enhancements

  • Services should accept filter objects that map to frontend URL parameters.
  • Implement consistent filtering patterns across all data types.
  • Provide statistics/summary endpoints for dashboard widgets.
  • Support flexible sorting and pagination options.

4.3 Repository Layer Patterns

  • Use Prisma query builders for dynamic filtering.
  • Implement consistent pagination patterns.
  • Support complex search queries across related fields.
  • Maintain organization-scoped access controls.
ClaudeConventions Frontend