Jean-Luc Makiola
fddbf8166d
- SUMMARY.md documents 30 async function conversions across 9 service files - STATE.md updated with position, decisions, session info - ROADMAP.md progress updated (4/6 summaries for phase 14) - Requirements DB-01, DB-02 marked complete
6.4 KiB
6.4 KiB
Requirements: GearBox v2.0 Platform Foundation
Defined: 2026-04-03 Core Value: Help people make better gear decisions — discover what others use, compare real-world data, and see how a potential buy affects your setup before committing.
v2.0 Requirements
Requirements for this milestone. Each maps to roadmap phases.
Database Migration
- DB-01: Application runs on PostgreSQL instead of SQLite
- DB-02: All service functions use async database operations
- DB-03: Test infrastructure uses PGlite instead of bun:sqlite in-memory databases
- DB-04: Existing SQLite data can be migrated to Postgres via a one-time script
- DB-05: Docker Compose provides Postgres for local development
Authentication
- AUTH-01: User can register an account via external OIDC auth provider
- AUTH-02: User can log in via external auth provider and access their data
- AUTH-03: API keys remain functional for programmatic access (MCP, scripts)
- AUTH-04: Auth provider runs self-hosted alongside the application
- AUTH-05: E2E tests authenticate via API keys without depending on the auth provider
Multi-User Data Model
- MULTI-01: Every item, category, thread, and setup is owned by a specific user
- MULTI-02: User can only see and modify their own data (cross-user isolation)
- MULTI-03: Categories use composite unique constraint (userId + name)
- MULTI-04: Existing data is assigned to the original user during migration
- MULTI-05: MCP tools operate within the authenticated user's scope
- MULTI-06: Settings are per-user rather than global
Image Storage
- IMG-01: Images are stored in MinIO (S3-compatible) instead of local filesystem
- IMG-02: Existing uploaded images are migrated to MinIO
- IMG-03: Image upload and retrieval work through the new storage layer
- IMG-04: Docker Compose provides MinIO for local development
Global Item Database
- GLOB-01: A global item catalog exists with brand, model, category, manufacturer specs, and image
- GLOB-02: Global catalog is seeded with initial items from manufacturer data
- GLOB-03: User can search the global catalog by name or brand
- GLOB-04: User can link a personal collection item to a global catalog entry
- GLOB-05: Global item pages show basic info and owner count
User Profiles & Sharing
- PROF-01: User has a profile with display name, avatar, and bio
- PROF-02: User can view their own public profile page
- PROF-03: User can set a setup as public or private
- PROF-04: Public setups are viewable by anyone without authentication
- PROF-05: Public profile page lists the user's public setups
Future Requirements
Deferred to future milestones. Tracked but not in current roadmap.
Reviews & Ratings
- REV-01: User can rate a global item with an overall star rating
- REV-02: User can rate a global item on predefined dimensions (durability, value, etc.)
- REV-03: Item detail pages show average ratings from all reviewers
Discovery
- DISC-01: User can browse recently shared public setups
- DISC-02: User can browse recently reviewed items
- DISC-03: User can browse popular gear by owner count
Aggregation
- AGG-01: Item detail pages show crowd-verified specs (manufacturer vs community-measured weight)
- AGG-02: Item detail pages show which setups include this item
- AGG-03: Setup composition insights ("commonly paired with")
Social
- SOCL-01: User can fork/copy a public setup as a template
- SOCL-02: Planning thread candidates can link to global items for auto-populated specs
- SOCL-03: User can follow other users
- SOCL-04: User can view an activity feed of followed users' content
Content Moderation
- MOD-01: User can submit freeform text reviews
- MOD-02: User can report inappropriate content
- MOD-03: Admin can review and act on reported content
Out of Scope
Explicitly excluded. Documented to prevent scope creep.
| Feature | Reason |
|---|---|
| Freeform text reviews | Requires moderation infrastructure not yet built |
| Comments on setups | Moderation burden, notification system needed |
| User-to-user messaging | High moderation burden, not core to discovery |
| Wiki-style open item editing | Quality control risk; structured contributions only |
| Marketplace / buy-sell | Payment processing, fraud, legal liability |
| AI gear recommendations | Training data requirements, hallucination risk |
| Gamification (badges, points) | Incentivizes quantity over quality |
| Instagram-style infinite scroll | Engagement-maximizing conflicts with utility focus |
| Price tracking / deal alerts | Requires scraping, fragile, legal gray area |
| Mobile native app | Web-first, responsive design sufficient |
| Real-time collaborative setups | WebSocket complexity for niche use case |
| Maintaining SQLite single-user mode | Platform features irrelevant for solo use; diverged at v2.0 |
| Redis infrastructure | Not needed at v2.0 scale; auth provider (Logto) doesn't require it |
Traceability
Which phases cover which requirements. Updated during roadmap creation.
| Requirement | Phase | Status |
|---|---|---|
| DB-01 | Phase 14 | Complete |
| DB-02 | Phase 14 | Complete |
| DB-03 | Phase 14 | Pending |
| DB-04 | Phase 14 | Complete |
| DB-05 | Phase 14 | Pending |
| AUTH-01 | Phase 15 | Pending |
| AUTH-02 | Phase 15 | Pending |
| AUTH-03 | Phase 15 | Pending |
| AUTH-04 | Phase 15 | Pending |
| AUTH-05 | Phase 15 | Pending |
| MULTI-01 | Phase 16 | Pending |
| MULTI-02 | Phase 16 | Pending |
| MULTI-03 | Phase 16 | Pending |
| MULTI-04 | Phase 16 | Pending |
| MULTI-05 | Phase 16 | Pending |
| MULTI-06 | Phase 16 | Pending |
| IMG-01 | Phase 17 | Pending |
| IMG-02 | Phase 17 | Pending |
| IMG-03 | Phase 17 | Pending |
| IMG-04 | Phase 17 | Pending |
| GLOB-01 | Phase 18 | Pending |
| GLOB-02 | Phase 18 | Pending |
| GLOB-03 | Phase 18 | Pending |
| GLOB-04 | Phase 18 | Pending |
| GLOB-05 | Phase 18 | Pending |
| PROF-01 | Phase 18 | Pending |
| PROF-02 | Phase 18 | Pending |
| PROF-03 | Phase 18 | Pending |
| PROF-04 | Phase 18 | Pending |
| PROF-05 | Phase 18 | Pending |
Coverage:
- v2.0 requirements: 30 total
- Mapped to phases: 30
- Unmapped: 0
Requirements defined: 2026-04-03 Last updated: 2026-04-03 after roadmap creation