Feedback Mechanism

Relevant source files

The following files were used as context for generating this wiki page:

• apps/api/spec/feedback.md
• apps/api/src/modules/feedback/application/feedback.service.ts
• apps/api/src/modules/feedback/interface/feedback.tool.ts
• apps/api/src/modules/feedback/domain/feedback.ts
• apps/api/src/modules/feedback/index.ts
• apps/api/test/modules/feedback/application/feedback.service.test.ts
• apps/api/test/modules/feedback/interface/feedback.tool.integration.test.ts

The Feedback Mechanism provides a public interface for visitors to submit freeform messages to the site owner. It operates as a Model Context Protocol (MCP) tool named submit_feedback. The system validates user input, generates unique identifiers, and persists the data to a repository.

Architecture and Components

The mechanism follows a layered architecture consisting of an interface layer, an application service, and a domain model.

Component Overview

• FeedbackTool: Registers the submit_feedback tool with the MCP server and handles incoming JSON-RPC calls.
• FeedbackService: Orchestrates the submission process by transforming DTOs into domain entities and invoking persistence logic.
• Feedback Domain Model: Defines the structure and requirements for a feedback entry.
• FeedbackRepository: Defines the interface for persisting feedback data.

Sources: apps/api/src/modules/feedback/index.ts:1-3, apps/api/src/modules/feedback/interface/feedback.tool.ts:10-14

Class Structure

This diagram shows the relationships between the primary feedback components:

Data Flow

When a visitor submits a message, the data flows from the MCP client through the internal layers for validation and storage.

Input Validation and Rules

The system enforces specific business rules during the submission process. Validation occurs at the schema level before the handler executes.

Rule ID	Condition	Result
RULE-FB-001	Empty message	INVALID_INPUT error
RULE-FB-002	Invalid email format	INVALID_INPUT error
RULE-FB-003	Successful call	Persists exactly one entry
RULE-FB-004	Persistence	App assigns id and created_at automatically

Sources: apps/api/spec/feedback.md:21-25, apps/api/test/modules/feedback/interface/feedback.tool.integration.test.ts:41-62

Data Model

The Feedback entity represents the data structure stored in the system. Optional fields are left undefined if not provided by the visitor.

Field	Type	Required	Description
id	string	Yes	Unique identifier generated by the system
message	string	Yes	The freeform content of the feedback
name	string	No	Visitor's name
topic	string	No	Subject of the feedback
email	string	No	Visitor's contact email
createdAt	Date	Yes	Timestamp of submission

Sources: apps/api/src/modules/feedback/domain/feedback.ts:1-12, apps/api/test/modules/feedback/application/feedback.service.test.ts:27-33

Technical Implementation Details

The FeedbackService uses an IdGenerator to ensure every entry has a unique identity. It constructs a new Feedback instance with the current timestamp before passing it to the repository.

// apps/api/src/modules/feedback/application/feedback.service.ts:14-26
async submit(input: NewFeedbackDTO): Promise<Feedback> {
    const feedback = new Feedback({
        id: this.ids.next(),
        message: input.message,
        name: input.name,
        topic: input.topic,
        email: input.email,
        createdAt: new Date(),
    });

    await this.repo.save(feedback);

    return feedback;
}

The FeedbackTool maps the MCP tool call to the service. It returns a standardized acknowledgment message to the MCP client upon success.

Sources: apps/api/src/modules/feedback/interface/feedback.tool.ts:15-27, apps/api/src/modules/feedback/application/feedback.service.ts:14-26

The Feedback Mechanism ensures site owners receive visitor communications reliably by combining strict input validation with automated metadata assignment. Its exposure as an MCP tool allows LLM-based agents to handle user feedback workflows programmatically.