Project Overview
Relevant source files
The following files were used as context for generating this wiki page:
The ProductCompare project is a collaborative, AI-assisted platform designed for typed product comparison. It is architected as a modular monolith using Elixir and Phoenix for the backend, and Bun with React Router for the frontend. The system facilitates complex product data management including taxonomies, technical specifications (claims), pricing history, and affiliate link integration.
The primary objective is to provide a unified GraphQL-backed interface where users can browse products, view detailed technical specifications, and compare multiple products side-by-side. The architecture emphasizes strict context boundaries and a Relay-first approach to GraphQL to ensure maintainability and scalability.
Sources: README.md:1-5, ARCHITECTURE.md:7-12, 2026-03-03-product-compare-backend-mvp-plan.md:1-10
System Architecture
The project follows a split architecture between a Phoenix-based backend and a React-based frontend. Communication between these layers is handled primarily via a GraphQL API located at /api/graphql.
High-Level Component Relationship
The following diagram illustrates the interaction between the primary system components and the data flow for client requests.
The Phoenix backend manages session authority via cookies while exposing a GraphQL contract for all browser authentication and data fetching flows.
Sources: ARCHITECTURE.md:7-18, backend_starting_guide.md:27-35, AGENTS.md:22-26
Backend Architecture and Context Boundaries
The backend is built as a modular monolith where business logic is organized into discrete context boundaries. These boundaries interact with a shared ProductCompareSchemas layer that contains schema-only Ecto modules.
Core Contexts
| Context | Responsibility | Key Entities |
|---|---|---|
| Accounts | User management and reputation systems. | User, UserReputation |
| Taxonomy | Hierarchical classification of products and use-case tagging. | Taxon, TaxonClosure |
| Catalog | Core product registry and brand information. | Product, Brand |
| Specs | Technical attributes, unit conversions, and attribute claims. | Attribute, Claim, Unit |
| Pricing | Merchant listings and historical price tracking. | Merchant, PricePoint |
| Affiliate | Referral links, network programs, and coupons. | AffiliateLink, Coupon |
| Discussions | Community interaction through reviews and threads. | ProductReview, Thread |
Sources: README.md:23-29, 2026-03-03-product-compare-backend-mvp-plan.md:120-145
Data Persistence Standards
The project utilizes PostgreSQL 18 with specific conventions for data integrity and performance:
- Primary Keys: Relational tables default to
bigintIDs for internal foreign keys. - Entropy IDs: Every relational table includes an
entropy_idusinguuidv7for public-facing identification. - Timestamps: All timestamps use microsecond precision (
:utc_datetime_usec). - Token Security: Authentication tokens are never stored in raw form; they are persisted as SHA3-256 hashes.
Sources: backend_starting_guide.md:9-15, 2026-03-03-product-compare-backend-mvp-plan.md:88-95
Frontend Architecture
The frontend is a React application utilizing React Router for Server-Side Rendering (SSR) and StyleX for styling. It is designed around a Relay-first data fetching strategy, although currently transitioning from manual GraphQL fetches to integrated Relay preloading.
Application Flow and Routing
The application utilizes specialized loaders to fetch data from the GraphQL API before rendering routes.
Key Frontend Routes
- Browse (
/products): Displays a grid of available products fetched via theBrowseProductsquery. - Detail (
/products/:slug): Shows comprehensive product information, including brand details and active merchant offers. - Compare (
/compare?slug=...): Allows side-by-side comparison of up to three products. - Auth (
/auth/*): Handles registration, login, and password recovery via GraphQL mutations.
Sources: ARCHITECTURE.md:21-30, assets/src/routes/products/api.ts:89-115, assets/src/routes/compare/api.ts:47-65, AGENTS.md:21-25
GraphQL Data Contract
The GraphQL schema follows Relay conventions, utilizing global IDs and connections for pagination.
Technical Specification Handling
A core feature of the project is the "Claims" system for product specifications. This system allows for:
- Proposing Claims: Users can suggest technical specs.
- Verification: Claims go through a lifecycle (Propose -> Accept/Reject).
- Normalization: Numeric values are converted to base units (e.g., inches to millimeters) using dimensions and multipliers to ensure deterministic filtering.
- Current Selection: One claim is selected as the "current" authoritative value for a product attribute.
Sources: 2026-03-03-product-compare-backend-mvp-plan.md:154-180, backend_starting_guide.md:16-20
Authentication Contract
Browser authentication is handled exclusively through GraphQL mutations. These mutations interact with the Phoenix session authority to set or clear HTTP-only session cookies.
| Mutation | Purpose |
|---|---|
login | Authenticates a user and sets a session cookie. |
register | Creates a new account and initiates a session. |
forgotPassword | Triggers a password reset flow via email. |
verifyEmail | Consumes a token to confirm a user's email address. |
Sources: AGENTS.md:21-26, assets/tests/e2e/auth.spec.ts:60-150
Development and Verification
The project includes a robust CI/CD and local development toolset. A Nix development shell provides the environment, while Docker Compose manages the PostgreSQL 18 instance.
Quality Gates
- Type Checking: Strict Dialyzer checks and
mix check.typespecsare required for all public functions. - Formatting: Mandatory code formatting gates.
- Testing: A tiered testing strategy includes:
- Unit Tests: Logic and unit conversions.
- Context Tests: Database integrity and boundary behavior.
- E2E Tests: Playwright-based flows for critical paths like authentication.
Sources: README.md:31-38, backend_starting_guide.md:144-155, 2026-03-03-product-compare-backend-mvp-plan.md:225-240
The ProductCompare architecture provides a structured foundation for building a data-rich product ecosystem, combining the reliability of a modular Elixir backend with the interactive capabilities of a modern React frontend.