Skip to content

IMPLEMENTATION-PLAN.md

Latest commit

 

History

History
599 lines (486 loc) · 13.8 KB

IMPLEMENTATION-PLAN.md

File metadata and controls

599 lines (486 loc) · 13.8 KB

Guild Hall — V1 Implementation Plan

Last Updated: 2025-01-24

Overview

This document outlines the technical implementation plan for Guild Hall V1. It covers phases, dependencies, and deliverables for building the Bounty Board MVP.

Tech Stack Summary

Layer Technology ADR
Frontend Next.js 14 (App Router) ADR-001
Hosting Netlify ADR-002
Backend Supabase (PostgreSQL, Auth, Realtime, Storage) ADR-003
Styling Tailwind CSS ADR-004
UI Components shadcn/ui ADR-005
State Management React Query + React Context ADR-006

Implementation Phases

Phase 0: Project Setup

Duration: Foundation work

0.1 Repository Setup

  • Initialize Next.js project with TypeScript
  • Configure Tailwind CSS
  • Install and configure shadcn/ui
  • Set up ESLint and Prettier
  • Configure path aliases

0.2 Supabase Setup

  • Create Supabase project
  • Run database migrations (SPEC-001)
  • Apply RLS policies (SPEC-002)
  • Configure Auth providers (Email, Google, Apple)
  • Set up Storage buckets (for future use)

0.3 Development Infrastructure

  • Environment configuration (.env.local)
  • Supabase client setup (lib/supabase.ts)
  • Type generation from database schema
  • Configure React Query provider

0.4 CI/CD Setup

  • GitHub Actions for linting/testing
  • Netlify deployment configuration
  • Preview deployments for PRs
  • Environment variable management

Deliverables:

  • Running Next.js app deployed to Netlify
  • Supabase project with schema and RLS
  • CI/CD pipeline operational

Phase 1: Authentication

Duration: Core auth flows

1.1 Auth UI Components

  • Login page (/login)
  • Registration page (/register)
  • Password reset flow (/reset-password)
  • OAuth buttons (Google, Apple)

1.2 Auth Logic

  • Supabase Auth integration
  • AuthContext provider (SPEC-003)
  • Session management
  • Auth state listener

1.3 Protected Routes

  • Middleware for route protection
  • Redirect logic (unauthenticated → login)
  • Role-based route guards (GM routes)

1.4 Auth Callbacks

  • OAuth callback handler (/auth/callback)
  • Email confirmation handler (/auth/confirm)
  • Password reset handler

Deliverables:

  • Users can register, login, logout
  • OAuth with Google and Apple works
  • Protected routes enforce authentication
  • GM routes require GM role

Phase 2: User Foundation

Duration: Profiles and settings

2.1 User Profile

  • Profile page (/profile)
  • Display name and avatar
  • Join date and tenure
  • Points and stats display

2.2 Privacy Settings

  • Privacy settings page (/settings/privacy)
  • Profile visibility toggle
  • Leaderboard opt-out
  • Quest history visibility
  • Activity feed visibility

2.3 Public Profiles

  • Public profile page (/users/[id])
  • Privacy-aware data display
  • Badge showcase

2.4 Data Export

  • Export page (/settings/export)
  • JSON export generation
  • Download functionality

Deliverables:

  • Users can view and edit profiles
  • Privacy settings work correctly
  • Public profiles respect privacy
  • Data export functional

Phase 3: Quest Display (User)

Duration: Bounty Board read experience

3.1 Bounty Board

  • Quest list page (/quests)
  • Category filtering
  • Quest cards with key info
  • Status indicators (deadline, points)

3.2 Quest Detail

  • Quest detail page (/quests/[id])
  • Full description display
  • Objectives list
  • Deadline information
  • Accept quest CTA

3.3 Category Management

  • Category display
  • Category icons
  • Filtered views

Deliverables:

  • Users can browse available quests
  • Users can filter by category
  • Quest details fully visible
  • Clear acceptance deadline display

Phase 4: Quest Acceptance & Progress

Duration: User quest journey

4.1 Quest Acceptance

  • Accept quest flow
  • Deadline calculation
  • user_quests record creation
  • user_objectives initialization

4.2 My Quests

  • Active quests page (/my-quests)
  • Quest progress cards
  • Status filtering (active, completed, abandoned)

4.3 Quest Progress View

  • Progress page (/my-quests/[id])
  • Objective checklist
  • Dependency visualization
  • Progress percentage

4.4 Evidence Submission

  • Evidence submission form
  • Text evidence input
  • Link evidence input
  • Submission confirmation

4.5 Deadline Extensions

  • Extension request form
  • Reason input
  • Request status display

Deliverables:

  • Users can accept quests
  • Users can view their active quests
  • Users can submit evidence
  • Users can request extensions

Phase 5: GM Dashboard - Quests

Duration: Quest management

5.1 GM Layout

  • GM dashboard layout (/gm)
  • GM navigation
  • Role verification

5.2 Quest List (GM)

  • All quests view (/gm/quests)
  • Status filtering (draft, published, archived)
  • Quick actions (publish, archive)

5.3 Quest Creation

  • Quest form (/gm/quests/new)
  • Basic fields (title, description, category)
  • Deadline configuration
  • Points configuration
  • Reward description

5.4 Objective Management

  • Objectives editor
  • Add/remove objectives
  • Dependency configuration
  • Evidence type selection
  • Point allocation

5.5 Quest Editing

  • Edit quest page (/gm/quests/[id]/edit)
  • Status transitions
  • Publish/archive actions

5.6 Templates

  • Save as template
  • Create from template
  • Clone quest
  • Template management

5.7 Smart Quest Creator Placeholder

  • Coming soon page (/gm/quests/smart)
  • Feature preview content

Deliverables:

  • GMs can create quests with objectives
  • GMs can configure dependencies
  • GMs can publish/archive quests
  • Templates and cloning work
  • Smart Creator placeholder visible

Phase 6: GM Dashboard - Review

Duration: Evidence review workflow

6.1 Review Queue

  • Pending submissions view (/gm/review)
  • Submission cards
  • Filter by quest
  • Sort by date

6.2 Evidence Review

  • Review detail view
  • Evidence display (text/link)
  • User context
  • Quest/objective context

6.3 Review Actions

  • Approve submission
  • Reject with feedback
  • Feedback input
  • Point awarding on approval

6.4 Extension Requests

  • Extension queue (/gm/extensions)
  • Request details
  • Approve/deny actions
  • New deadline setting

6.5 User Overview

  • All users view (/gm/users)
  • User progress summary
  • User detail view

Deliverables:

  • GMs can review all pending submissions
  • GMs can approve/reject with feedback
  • GMs can manage extension requests
  • GMs can view all user progress

Phase 7: Rewards & Leaderboard

Duration: Recognition system

7.1 Points System

  • Point calculation on approval
  • Quest completion bonus
  • Points display throughout app

7.2 Achievements

  • Achievement definitions (seed data)
  • Automatic achievement checking
  • Achievement award triggers
  • Achievement notifications

7.3 Leaderboard

  • Leaderboard page (/leaderboard)
  • Privacy-aware ranking
  • User position indicator
  • Points and quest counts

7.4 Profile Badges

  • Badge display on profile
  • Badge detail modal
  • Achievement history

Deliverables:

  • Points awarded correctly
  • Achievements trigger automatically
  • Leaderboard respects privacy
  • Badges display on profiles

Phase 8: Notifications

Duration: Real-time updates

8.1 Notification System

  • Notification bell component
  • Unread count badge
  • Notification dropdown

8.2 Notification Types

  • Quest accepted (GM)
  • Evidence submitted (GM)
  • Extension requested (GM)
  • Evidence approved/rejected (User)
  • Extension approved/denied (User)
  • Deadline approaching (User)
  • Quest completed (User)

8.3 Realtime Integration

  • Supabase Realtime subscription
  • React Query cache invalidation
  • Optimistic updates

8.4 Notification Management

  • Mark as read
  • Mark all as read
  • Notification history page

Deliverables:

  • Real-time notifications work
  • All notification types implemented
  • Notifications properly marked as read

Phase 9: Polish & Launch Prep

Duration: Final touches

9.1 Error Handling

  • Global error boundary
  • Form validation
  • API error handling
  • User-friendly error messages

9.2 Loading States

  • Skeleton loaders
  • Suspense boundaries
  • Optimistic UI updates

9.3 Responsive Design

  • Mobile navigation
  • Touch-friendly interactions
  • Tablet layouts

9.4 Accessibility

  • Keyboard navigation
  • Screen reader testing
  • Color contrast verification
  • Focus management

9.5 Performance

  • Image optimization
  • Code splitting
  • Bundle analysis
  • Lighthouse audit

9.6 Documentation

  • README completion
  • Environment setup guide
  • Deployment documentation

Deliverables:

  • App handles errors gracefully
  • Responsive on all devices
  • Accessible (WCAG 2.1 AA target)
  • Performance targets met

File Structure

guild-hall/
├── app/
│   ├── (auth)/
│   │   ├── login/
│   │   ├── register/
│   │   └── reset-password/
│   ├── (dashboard)/
│   │   ├── layout.tsx
│   │   ├── quests/
│   │   ├── my-quests/
│   │   ├── profile/
│   │   ├── settings/
│   │   └── leaderboard/
│   ├── (gm)/
│   │   └── gm/
│   │       ├── layout.tsx
│   │       ├── quests/
│   │       ├── review/
│   │       ├── extensions/
│   │       └── users/
│   ├── auth/
│   │   ├── callback/
│   │   └── confirm/
│   ├── users/
│   │   └── [id]/
│   ├── layout.tsx
│   └── page.tsx
├── components/
│   ├── ui/              # shadcn/ui components
│   ├── auth/
│   ├── quests/
│   ├── objectives/
│   ├── notifications/
│   ├── leaderboard/
│   └── layout/
├── lib/
│   ├── supabase/
│   │   ├── client.ts
│   │   ├── server.ts
│   │   └── middleware.ts
│   ├── hooks/
│   ├── utils/
│   └── types/
├── contexts/
│   └── AuthContext.tsx
├── docs/
│   ├── adrs/
│   ├── specs/
│   ├── NORTH-STAR.md
│   ├── ROADMAP.md
│   ├── IMPLEMENTATION-PLAN.md
│   └── REQUIREMENTS.md
├── supabase/
│   ├── migrations/
│   └── seed.sql
└── public/

Database Migrations Order

-- 1. Core tables
001_create_users.sql
002_create_user_roles.sql
003_create_privacy_settings.sql
004_create_categories.sql
005_create_quests.sql
006_create_objectives.sql
007_create_user_quests.sql
008_create_user_objectives.sql
009_create_notifications.sql
010_create_achievements.sql
011_create_user_achievements.sql

-- 2. Functions
020_function_has_role.sql
021_function_is_gm.sql
022_function_update_user_points.sql
023_function_handle_new_user.sql
024_function_set_user_quest_deadline.sql
025_function_create_user_objectives.sql
026_function_unlock_dependent_objectives.sql
027_function_export_user_data.sql

-- 3. Triggers
030_trigger_on_auth_user_created.sql
031_trigger_set_deadline_on_accept.sql
032_trigger_create_objectives_on_accept.sql
033_trigger_unlock_objectives_on_approval.sql

-- 4. RLS Policies
040_rls_users.sql
041_rls_user_roles.sql
042_rls_privacy_settings.sql
043_rls_categories.sql
044_rls_quests.sql
045_rls_objectives.sql
046_rls_user_quests.sql
047_rls_user_objectives.sql
048_rls_notifications.sql
049_rls_achievements.sql
050_rls_user_achievements.sql

-- 5. Views
060_view_leaderboard.sql

-- 6. Seed data
070_seed_categories.sql
071_seed_achievements.sql

Key Dependencies

Phase 0 ─┬─► Phase 1 (Auth)
         │
         └─► Phase 2 (User) ──► Phase 4 (Quest Progress)
                                      │
Phase 3 (Quest Display) ◄─────────────┘
         │
         └─► Phase 5 (GM Quests) ──► Phase 6 (GM Review)
                                           │
Phase 7 (Rewards) ◄────────────────────────┘
         │
         └─► Phase 8 (Notifications)
                    │
                    └─► Phase 9 (Polish)

Testing Strategy

Unit Tests

  • Utility functions
  • Custom hooks
  • Component logic

Integration Tests

  • Auth flows
  • Quest CRUD operations
  • Evidence submission
  • Review workflow

E2E Tests (Playwright)

  • Complete user journey
  • Complete GM journey
  • Cross-role interactions

Manual Testing

  • OAuth provider testing
  • Mobile responsiveness
  • Accessibility audit

Launch Checklist

Pre-Launch

  • All Phase 1-9 complete
  • All tests passing
  • Security review complete
  • Performance audit passed
  • Accessibility audit passed
  • Documentation complete

Environment

  • Production Supabase project
  • Production environment variables
  • OAuth credentials (production)
  • Custom domain configured
  • SSL certificate active

Data

  • Production database migrated
  • Seed data loaded (categories, achievements)
  • Initial GM account created

Monitoring

  • Error tracking enabled
  • Performance monitoring enabled
  • Uptime monitoring configured

Go-Live

  • DNS propagation complete
  • Smoke test on production
  • Initial users invited
  • Support channel ready

"Plan the work, work the plan, adapt as you learn."