Discussions & Reviews
Relevant source files
The following files were used as context for generating this wiki page:
The Discussions & Reviews system is a core context boundary within the ProductCompare modular monolith. It enables collaborative interaction by providing users with the ability to create discussion threads, post replies, and submit structured product reviews. This system is integrated with the broader catalog to provide community-driven insights alongside technical product specifications.
The system is designed to handle CRUD (Create, Read, Update, Delete) operations for three primary entities: threads, posts, and reviews. It operates within the ProductCompare.Discussions context, following the project's strict boundary enforcement between business logic and data persistence.
Sources: 2026-03-03-product-compare-backend-mvp-plan.md:15, 2026-03-03-product-compare-backend-mvp-plan.md:204-206, README.md:27
Architecture and Data Modeling
The Discussions & Reviews module is organized as a discrete context boundary. All database interactions are performed through schema-only Ecto modules located in the ProductCompareSchemas.Discussions namespace, while the public API is exposed through the ProductCompare.Discussions module.
Sources: 2026-03-03-product-compare-backend-mvp-plan.md:14-16, 2026-03-03-product-compare-backend-mvp-plan.md:117-119
Entity Relationship Structure
The data model centers around products, users, and the various forms of community interaction. Discussions are structured as threads containing multiple posts, while reviews are structured as single-entry ratings tied to specific products and users.
Note: The diagram illustrates the core relationships between discussion entities and the catalog/account anchors. Optional post nesting allows for threaded conversations within a single discussion thread.
Sources: 2026-03-03-product-compare-backend-mvp-plan.md:92-94, 2026-03-03-product-compare-backend-mvp-plan.md:204-206
Data Models and Constraints
The following table summarizes the data structures used within the Discussions context:
| Schema Module | Description | Key Fields / Constraints |
|---|---|---|
ProductThread | Represents a top-level discussion topic linked to a product. | id (bigint), entropy_id (uuidv7). |
ThreadPost | Represents an individual message within a thread. | Supports optional parent post nesting for hierarchical replies. |
ProductReview | Represents a user's structured feedback and rating. | Unique constraint on (product_id, user_id); rating validation (1-5). |
Sources: 2026-03-03-product-compare-backend-mvp-plan.md:117-119, 2026-03-03-product-compare-backend-mvp-plan.md:204-206, 2026-03-03-product-compare-backend-mvp-plan.md:214
Core Workflows
The system implements standardized CRUD workflows for managing community content. These workflows are exposed via the ProductCompare.Discussions context API and follow the project's tagged tuple return convention ({:ok, value} or {:error, reason}).
Discussion Management Flow
Users can engage with products by starting threads or replying to existing posts. The API manages the creation and retrieval of these entities while ensuring foreign key integrity with the Catalog and Accounts contexts.
Note: This flow shows the logic for creating discussions and contributing posts to existing threads.
Sources: 2026-03-03-product-compare-backend-mvp-plan.md:204-206, 2026-03-03-product-compare-backend-mvp-plan.md:162-163
Review Submission
Product reviews are governed by stricter constraints than general discussions to ensure data quality and prevent duplicate entries from the same user.
- Validation: The system validates that the
ratingis an integer between 1 and 5. - Uniqueness: A database-level unique index on
(product_id, user_id)prevents a single user from submitting multiple reviews for the same product. - Atomic Persistence: Review creation is handled through standard Ecto changesets within the context boundary.
Sources: 2026-03-03-product-compare-backend-mvp-plan.md:206, 2026-03-03-product-compare-backend-mvp-plan.md:214
API Surface
The ProductCompare.Discussions module provides the following public functions for external consumption (e.g., by GraphQL resolvers):
list_threads_for_product(product_id): Retrieves all threads associated with a specific product.get_thread_with_posts(thread_id): Fetches a thread and its constituent posts, potentially including nested parent-child relationships.create_thread(attrs): Creates a new discussion thread.create_post(attrs): Adds a post to a thread.create_review(attrs): Submits a new product review with rating validation.
Sources: 2026-03-03-product-compare-backend-mvp-plan.md:231-232
Integration and Infrastructure
Shared Conventions
The Discussions module adheres to the global backend conventions established in the backend_starting_guide.md:
- Primary Keys: Uses
bigintfor internalidanduuidv7forentropy_id(public-facing). - Timestamps: Uses
:utc_datetime_usecfor all temporal fields. - Relay Support: Discussions and reviews are exposed via GraphQL and follow Relay-modern flavors, including global IDs and connection-based pagination for lists.
Sources: backend_starting_guide.md:7-14, backend_starting_guide.md:126-128, ARCHITECTURE.md:41-43
Testing Strategy
The context behavior is verified through integration tests using the DataCase infrastructure.
- Integrity Tests: Verify that deleting a product or user correctly handles associated threads and reviews via foreign key constraints.
- Validation Tests: Ensure ratings outside the 1-5 range are rejected.
- Uniqueness Tests: Confirm that multiple reviews from a single user for the same product trigger a constraint error.
Sources: 2026-03-03-product-compare-backend-mvp-plan.md:255-256, backend_starting_guide.md:163-167
Conclusion
The Discussions & Reviews system provides the social layer of the ProductCompare platform, allowing for structured user feedback and open-ended product discussions. By utilizing modular context boundaries and strict schema-only Ecto modules, the system maintains a clean separation of concerns while leveraging the performance and integrity features of PostgreSQL 18.