Architectural Refinement - Sprint 3

Architecture Overview

Sprint 3 focuses on implementing the system's core flows: the Feedback Request by collaborators and the Feedback Response by external reviewers. This phase is crucial for materializing the application's core business, involving the creation and orchestration of functionalities in the FeedbackRequestService and FeedbackResponseService microservices, as well as significant interactions with the Frontend, API Gateway, and the email notification service.

The architecture will continue to follow the principles of microservices, Domain-Driven Design (DDD), and communication via RESTful API, ensuring scalability, maintainability, and clarity in the responsibilities of each component.

Key Architectural Components for Sprint 3

During Sprint 3, the following components will be developed or have their functionalities expanded:

1. Feedback Request Microservice (FeedbackRequestService - Java/Spring Boot)

Responsible for the entire feedback request lifecycle:

• Creation and Editing of Requests: Allow collaborators to create and edit draft requests, adding custom questions and indicating external reviewers.
• Status Management: Control the request statuses ("in creation", "pending approval", "awaiting responses", "finished", "rejected").
• Submission for Approval: Send the request to the corresponding PDM.
• Approval/Rejection Process: Allow PDMs to approve or reject requests, with a justification for rejection.
• Hash Generation for Forms: Create a unique identifier (hash) for each form, to be used in the links sent to reviewers.
• Business Validations:
  • Minimum of 3 custom questions.
  • Minimum of 2 and maximum of 9 reviewers.
  • Reviewer's email cannot be from the @ciandt.com.br domain.
  • A collaborator can only create a new form 6 months after the last one was finalized.
• Notifications: Send emails to PDMs (new request), collaborators (request status), and reviewers (invitation for feedback).

2. Feedback Response Microservice (FeedbackResponseService - Java/Spring Boot)

Responsible for managing the response process from external reviewers:

• Reviewer Authentication:
  • Validate the reviewer's email (cannot be @ciandt.com.br).
  • Generate and send a unique access code via email.
  • Validate the provided access code.
• Form Display: Present the feedback form (questions) based on the request's hash.
• Deadline Validation: Check if the form is within the 3-month period for response (from the PDM's approval date).
• Response Collection and Storage:
  • Allow the reviewer to answer the questions or indicate "don't know how to evaluate".
  • Save responses as a draft.
  • Finalize and submit the evaluation.
• Notifications: Inform the collaborator when a feedback is finalized (if it's the last reviewer).
• Status Update: Signal the FeedbackRequestService when a response is submitted so that the overall request status can be updated.

3. Frontend (Next.js) - Roles and Interactions

Specific user interfaces will be developed for:

• Collaborator:
  • List their feedback requests (with status and actions).
  • Create a new request form (add questions, reviewers).
  • Edit draft or rejected forms.
  • Delete requests (according to status rules).
  • View the status of approval and responses.
• PDM (People Development Manager):
  • List requests pending their approval.
  • Analyze request details (questions, reviewers).
  • Approve or reject requests, adding comments if rejected.
• External Reviewer:
  • "Login" page to enter email and receive an access code.
  • Page to enter the access code.
  • Feedback form to answer the questions.
  • Options to save a draft or finalize the evaluation.

4. Email Service

A crucial component for notifications. It can be a dedicated internal service or an integration with an external email provider. It will be used to:

• Send an access code to reviewers.
• Notify PDMs about new feedback requests.
• Notify collaborators about the status of their requests (approved, rejected, responded).
• Send invitations with the form link (containing the hash) to reviewers.

Sprint 3 Component Diagram

Architectural Decisions for Sprint 3

1. External Reviewer Authentication via Email Access Code:

   • Decision: External reviewers authenticate by providing their email (previously registered in the request) and a unique access code sent to that email.
   • Rationale: A simple, low-friction mechanism for the reviewer, who does not need to create a formal account. It ensures that only the owner of the invited email can respond. It prevents internal collaborators (@ciandt.com.br) from responding, as the system already validates the domain during registration and can reinforce it at login.
   • Implications: Strong dependency on the email service for the response flow. Need to manage the generation, sending, validity, and uniqueness of access codes.

2. Hashing of Form ID for External Links:

   • Decision: The feedback request identifier used in links sent to reviewers will be a non-sequential and hard-to-guess hash, instead of a direct numerical ID.
   • Rationale: Increases security through obscurity, making it difficult for third parties to guess valid form URLs.
   • Implications: The FeedbackRequestService must generate and store this hash. The FeedbackResponseService (and the Frontend) will use this hash to fetch and identify the forms.

3. Response Deadline Validation (3 months):

   • Decision: Feedback responses will only be accepted if submitted within a 3-month period from the date the request was approved by the PDM.
   • Rationale: Ensures that the collected feedback is temporally relevant to the collaborator's development.
   • Implications: The FeedbackResponseService needs to query the request's approval date (likely via FeedbackRequestService or directly from a shared/replicated database) and compare it with the current date before allowing a response.

4. Email Notifications for Key Events:

   • Decision: Use emails to notify users (collaborators, PDMs, reviewers) about important events in the feedback lifecycle.
   • Rationale: Keeps users informed and engaged in the process. It is a standard and expected means of communication for such interactions.
   • Implications: Need for a reliable and resilient email service. Email sending operations should preferably be asynchronous to avoid blocking the main application flows.

5. Functional Separation between FeedbackRequestService and FeedbackResponseService:

   • Decision: Maintain the business logic for creating/managing requests and for the response process in distinct microservices.
   • Rationale: Aligns with DDD's Bounded Contexts (Feedback Request and Feedback Response). Allows for independent development, deployment, and scalability for each context.
   • Implications: Need for inter-service communication (e.g., FeedbackResponseService may need to query FeedbackRequestService for form details or to notify about a completed response). This communication must be designed to be resilient.

Applied Architectural Patterns

• Domain-Driven Design (DDD):
  • Aggregates: FeedbackRequest (encompassing Questions, Invited Reviewers, status, hashId) and FeedbackResponse (encompassing the individual answers to a request's questions by a reviewer).
  • Domain Services: Approval/rejection logic, access code generation, deadline validation, notification orchestration.
  • Bounded Contexts: Clearly delineated for FeedbackRequest and FeedbackResponse, each with its own microservice.
• API Gateway: A single point of entry for the frontend, handling routing, initial authentication, and light aggregation if necessary.
• Microservices: Decomposition of the application into smaller, cohesive, and independent services.
• Layered Architecture (within each microservice):
  • Presentation (Controllers): REST endpoints.
  • Application (Services): Use case orchestration.
  • Domain (Entities, Value Objects, Domain Services): Business rules and state.
  • Infrastructure (Repositories, Email Clients): Persistence, external communication.

Security Considerations

• Protection of Response Endpoints and Reviewer Authentication:
  • Access to response forms only via a link with a unique hash.
  • Implicit two-factor authentication for the reviewer (email + access code sent to the email).
  • Access codes must be single-use and have a short expiration time.
• Input Data Validation:
  • Strict validation of all data received via API (e.g., email format, number of questions/reviewers, content of responses).
  • Prevent emails from the @ciandt.com.br domain for external reviewers.
• Authorization in Request and Approval Flows:
  • Collaborators can only manage (create, edit, delete) their own requests.
  • PDMs can only analyze and approve/reject requests from collaborators under their management.
  • The UserService will be queried to verify roles and hierarchies.
• Response Anonymity: As specified in the epics, the system must ensure that, although the collaborator indicates the reviewers, individual responses are not directly attributable to a specific reviewer in the collaborator's view (unless the viewing model allows it). The response process itself is authenticated to ensure that only the invited reviewer responds.
• Protection Against Abuse: Consider rate limiting for sending access codes and submitting forms to mitigate abuse risks.