GearBox/.planning/phases/18-global-items-public-profiles/18-CONTEXT.md

Phase 18: Global Items & Public Profiles - Context

Gathered: 2026-04-05 Status: Ready for planning

## Phase Boundary

Create a global item catalog (brand, model, category, specs, image) that users can search and link their personal items to. Add user profiles (display name, avatar, bio) and public setup sharing. Public setups are viewable without auth and appear on profile pages. Global item pages show owner count.

## Implementation Decisions

Global Item Catalog

• D-01: Create globalItems table: id (serial), brand (text, not null), model (text, not null), category (text), weightGrams (double precision), priceCents (integer), imageUrl (text), description (text), createdAt (timestamp). Separate from user items table.
• D-02: Create itemGlobalLinks junction table: itemId (FK → items), globalItemId (FK → globalItems). A user item can optionally link to one global item.
• D-03: Global items are not user-owned — they're shared catalog entries. No userId column.
• D-04: Global item search: full-text search on brand + model via ILIKE (simple, sufficient for initial catalog size).
• D-05: Global item page shows: brand, model, category, specs (weight/price), image, description, and owner count (count of linked user items).

Seed Data

• D-06: JSON seed file (src/db/global-items-seed.json) with curated initial catalog. Migration script imports on first run.
• D-07: Seed covers common bikepacking gear categories as a starting point. Can be expanded later.

User Profiles

• D-08: Extend users table with: displayName (text), avatarUrl (text), bio (text). All nullable — profile is optional.
• D-09: Profile edit page at /settings/profile or within existing settings page.
• D-10: Public profile page at /users/:id — shows display name, avatar, bio, and public setups. No auth required.
• D-11: Avatar upload uses existing image upload + MinIO storage (from Phase 17).

Setup Visibility

• D-12: Add isPublic boolean column to setups table, default false. All existing setups remain private.
• D-13: Public setups are viewable at /setups/:id/public (or similar) without authentication.
• D-14: Setup toggle UI in setup edit/detail view — simple switch/checkbox.
• D-15: Public profile page lists only the user's public setups.

API Design

• D-16: GET /api/global-items — search/list global catalog (public, no auth needed)
• D-17: GET /api/global-items/:id — global item detail with owner count (public)
• D-18: POST /api/items/:id/link — link a personal item to a global item (auth required)
• D-19: DELETE /api/items/:id/link — unlink (auth required)
• D-20: GET /api/users/:id/profile — public profile data
• D-21: PUT /api/auth/profile — update own profile (auth required)
• D-22: GET /api/setups/:id/public — public setup view (no auth)

Claude's Discretion

• Exact seed data content and quantity
• Global item search implementation details (ILIKE vs tsvector)
• Profile page layout and component structure
• Public setup URL scheme
• Whether to add a "link to global item" button in item edit form or a separate flow
• Avatar upload integration with existing ImageUpload component
• MCP tool additions for global items

<canonical_refs>

Canonical References

Downstream agents MUST read these before planning or implementing.

Schema

• src/db/schema.ts — Current schema (add globalItems, itemGlobalLinks, user profile fields, setup isPublic)

Existing Services

• src/server/services/item.service.ts — Item CRUD (add link/unlink)
• src/server/services/setup.service.ts — Setup CRUD (add isPublic filter)

Existing Routes

• src/server/routes/items.ts — Item routes (add link endpoint)
• src/server/routes/setups.ts — Setup routes (add public view)
• src/server/routes/auth.ts — Auth routes (add profile update)

Client

• src/client/routes/ — File-based routing (add new pages)
• src/client/components/ — Existing components to extend

Requirements

• .planning/REQUIREMENTS.md — GLOB-01 through GLOB-05, PROF-01 through PROF-05

</canonical_refs>

<code_context>

Existing Code Insights

Reusable Assets

• Item CRUD pattern — global items follow the same service/route/component pattern
• ImageUpload component — reuse for avatar upload
• Setup detail views — extend for public view
• MinIO storage service — use for avatar storage
• TanStack Router file-based routing — add new route files
• TanStack Query hooks — add hooks for global items and profiles

Established Patterns

• Service DI (db, userId) — global item services may not need userId (public data)
• Zod validation schemas in shared/schemas.ts
• Light/airy minimalist UI (Tailwind CSS v4)

Integration Points

• src/db/schema.ts — New tables + column additions
• src/server/index.ts — Register new route groups
• src/client/routes/ — New route files auto-registered by TanStack Router

</code_context>

## Specific Ideas

No specific requirements — open to standard approaches.

## Deferred Ideas

• Freeform reviews/ratings (requires moderation — future milestone)
• Follow users / activity feeds (social features — future milestone)
• Comments on setups (moderation needed — future milestone)
• Fork/copy public setups as templates (future feature)

---

Phase: 18-global-items-public-profiles Context gathered: 2026-04-05