Local Development Setup
Relevant source files
The following files were used as context for generating this wiki page:
The ProductCompare project is a modular monolith consisting of a Phoenix backend and a React-based frontend. The local development environment is designed to be reproducible using Nix for toolchain management and Docker Compose for infrastructure dependencies, specifically PostgreSQL 18. This setup ensures that all developers work with consistent versions of Elixir, Erlang, and Node.js-compatible runtimes.
The architecture separates concerns into two primary lanes: the Phoenix API, which handles the GraphQL contract and session authority, and the Bun/Vite-powered frontend located in the assets/ directory.
Sources: README.md:1-12, ARCHITECTURE.md:8-12, 2026-03-03-product-compare-backend-mvp-plan.md:14-16
Prerequisites and Environment Management
The project uses Nix Flakes to manage the development shell. This environment provides the Elixir 1.19.x, Erlang/OTP 28, and Phoenix 1.8.x toolchains required for the backend, as well as the necessary tools for the frontend assets.
To enter the development environment:
XDG_CACHE_HOME=$PWD/.cache nix --extra-experimental-features 'nix-command flakes' develop
Sources: README.md:12-20, 2026-03-03-product-compare-backend-mvp-plan.md:21-25
Infrastructure and Database
PostgreSQL 18 is the mandatory durable datastore for the project. For local development, it is managed via Docker Compose. The application expects the database to be available at localhost:5433 by default.
Database Conventions
- Primary Keys: Default to
bigint(id). - Unique Identifiers: Every relational table must include an
entropy_idusinguuidv7(). - Timestamps: Configured to use
:utc_datetime_usecfor microsecond precision. - Token Secrets: Persisted only as SHA3-256 hashes.
Sources: README.md:21-23, backend_starting_guide.md:11-20, backend_starting_guide.md:81-86, 2026-03-03-product-compare-backend-mvp-plan.md:46-50
Database Initialization Flow
The following diagram illustrates the sequence for spinning up the local data layer.
The mix setup command handles dependency installation and database migration/seeding.
Sources: README.md:24-28, 2026-03-03-product-compare-backend-mvp-plan.md:52-54
Backend Configuration
The backend is built as a modular monolith with strict context boundaries. These boundaries separate business logic from the transport layer (GraphQL).
| Context Boundary | Description |
|---|---|
ProductCompare.Accounts | User management, authentication, and reputation tracking. |
ProductCompare.Taxonomy | Product trees, closure tables, and use-case tagging. |
ProductCompare.Catalog | Brand and product entity management. |
ProductCompare.Specs | Attributes, units, claims, and filtering logic. |
ProductCompare.Pricing | Merchant discovery, price history, and listings. |
ProductCompare.Affiliate | Affiliate networks, programs, and link management. |
ProductCompare.Discussions | Threads, posts, and product reviews. |
Sources: README.md:33-40, backend_starting_guide.md:54-75, 2026-03-03-product-compare-backend-mvp-plan.md:117-142
Frontend Asset Development
The frontend is located in the assets/ directory and utilizes Vite for the build pipeline and Bun for script execution. It communicates with the Phoenix backend via a GraphQL endpoint at /api/graphql.
Configuration Variables
Local development relies on specific environment variables to resolve the API location.
| Variable | Default (Dev) | Description |
|---|---|---|
VITE_API_BASE_URL | http://localhost:4000 | The base URL for the Phoenix backend. |
PORT | 4000 | The backend API port. |
Development Scripts
From within the assets/ directory, use the following commands:
bun run dev: Starts the Vite development server.bun run build: Builds the client and SSR server bundles.bun run relay: Runs the Relay compiler to generate GraphQL artifacts.bun run test:unit: Executes Vitest unit tests.
Sources: assets/package.json:7-15, assets/src/relay/fetch-graphql.ts:3-10, README.md:29-31
Development Workflow and Quality Gates
The project enforces strict quality gates through mix aliases. These must pass before code is considered ready for integration.
- Static Analysis: Every public function must have a
@spec. Ecto schemas must expose a@type t. - Testing: Includes
DataCasefor database integration andConnCasefor GraphQL/Auth testing. - Relay: Developers must run the Relay compiler when changing GraphQL queries or the schema.
Sources: backend_starting_guide.md:143-157, backend_starting_guide.md:175-182, assets/package.json:14
Summary
Setting up the local environment for ProductCompare involves initializing a Nix shell for toolchain consistency, starting a PostgreSQL 18 container via Docker Compose, and running the mix setup task. The development workflow is split between the Phoenix backend (running on port 4000) and the React frontend, with a strong emphasis on type safety and automated quality checks through the mix precommit suite.