Skip to content

Backend Engineering Guidelines

Welcome to the backend integration phase! Please review and adhere to the following best practices to ensure consistency, maintainability, and smooth collaboration across the team.

1. Entities & DTOs

  • Entities
  • Do NOT use Lombok annotations (e.g., @Data, @Getter, @Setter) in JPA entities. Lombok can cause performance issues and obscure code clarity.
  • Manually generate getters and setters.
  • Only create constructors when necessary.

  • Why Lombok is discouraged in JPA Entities

  • DTOs

  • You may use either record or class for DTOs.
  • Prefer record for lightweight, immutable data carriers.
  • Use class only if you require mutability or additional logic.

2. Controllers & Endpoints

  • Implement all CRUD methods if your endpoint requires them. Do not leave only search or fetch methods.
  • Incomplete endpoints create blockers for other teams (e.g., Frontend team).
  • Swagger Documentation: Ensure all endpoints are documented.

3. Logging

  • Keep log objects lightweight. Avoid logging heavy objects or stack traces unless necessary.
  • Remove unnecessary or verbose logs before committing.
  • Use structured logging for better observability.
  • Logback: Use the updated configuration for consistent log patterns and service tagging.
  • For exceptions, always throw BaseException("msg", httpStatus, "optional context"). If introducing a new exception, update the global handler.

4. Database & Migrations

  • Flyway & Database Migration
  • Do not set show-sql: true in production or shared configs.
  • Format migration scripts for readability.
  • Specify column sizes thoughtfully (avoid default VARCHAR(255) if not needed).
  • Use appropriate data types (e.g., TEXT for descriptions).
  • Keep database names and credentials consistent for local testing.
  • Do not commit local credential changes.

5. Design & Process Flow

  • Review the Figma designs and architectural diagrams before implementation.
  • Ensure endpoints fully support the documented design (e.g., all required fields present).
  • If the design is unclear, escalate to the design team for clarification.
  • The API docs should be sufficient for integration with minimal support.

6. Gateway & Routes

  • Only exposed and configured routes are accessible.
  • Update the gateway configuration when adding new endpoints or services.
  • For Swagger docs addition: 
    {
  "routeId": "swagger-fee-service",
  "paths": ["/v1/api-docs/fee-service"],
  "uri": "lb://fee-service",
  "roles": [],
  "permissions": []
}
  • For Route Configurations (use wildcards carefully): 
    {
  "routeId": "document-service",
  "paths": ["/api/v1/documents/**"],
  "uri": "lb://document-service",
  "roles": [],
  "permissions": [],
  "requiresTenantId": false,
  "requiresRoles": false,
  "isAuthenticated": true
}

7. Consistency & Collaboration

  • Review similar services for established patterns.
  • Use // TODO: comments for unfinished features or known issues.
  • Ask questions or escalate concerns early to avoid technical debt.

8. Docker & Deployment

  • Use the optimized Dockerfile: 
    # Build with minimal memory (256MB heap)
ENV GRADLE_OPTS="-Xmx256m -Dorg.gradle.daemon=false -Dorg.gradle.configureondemand=true"
RUN gradle --no-daemon --stacktrace --parallel --max-workers=2 dependencies
  • Docker Compose:
  • Set the correct container_name.
  • Enable auto-restart: restart: unless-stopped.
  • Set environment variables (e.g., SPRING_PROFILES_ACTIVE=uat for UAT).
  • Reserve and use the correct port (refer to the shared Excel document).
  • Restrict container logs: max 10MB, 3 files.
  • Use olanna-network for service discovery.
  • Configure Traefik labels for external subdomains.
  • Expose health endpoints: 
    MANAGEMENT_ENDPOINTS_WEB_EXPOSURE_INCLUDE=health,info,metrics
test: ["CMD", "curl", "-f", "http://localhost:10003/actuator/health"]

9. Framework Usage

  • Reference only the frameworks your project needs (e.g., common-cache, common-rest).
  • Avoid including unfinished or buggy frameworks (e.g., common-rabbitmq, common-cache until stable).
  • Consult documentation if unsure about framework purposes.

10. Documentation

  • Keep documentation up-to-date as endpoints are added or changed.
  • If you need help, reach out to the documentation lead.
  • The final output is being migrated to the docs project.

11. Code Review Process

  • All code must be peer-reviewed before merging.
  • Use pull requests and request at least one reviewer.
  • Address all comments and suggestions before approval.

12. Security Best Practices

  • Never commit secrets or credentials to version control.
  • Validate and sanitize all user inputs.
  • Use HTTPS for all external communications.
  • Regularly update dependencies to patch vulnerabilities.

13. Testing & Quality Assurance

  • Write unit and integration tests for all new features.
  • Ensure tests pass before merging.
  • Use test coverage tools to identify untested code.
  • Perform manual testing for critical paths.

14. Support & Questions

  • If you are blocked or unsure, reach out on the team channel or directly to the relevant lead.
  • Collaboration and communication are key to our success.

Let's build a robust, maintainable, and scalable backend together!