diff --git a/docs/ETHOS_GUILD_PHASE2_NEXUS_INTEGRATION.md b/docs/ETHOS_GUILD_PHASE2_NEXUS_INTEGRATION.md new file mode 100644 index 00000000..6be530cf --- /dev/null +++ b/docs/ETHOS_GUILD_PHASE2_NEXUS_INTEGRATION.md @@ -0,0 +1,406 @@ +# Ethos Guild Phase 2: NEXUS Marketplace Integration Plan + +## Overview + +This document outlines the Phase 2 technical implementation plan for integrating Ethos Guild into the NEXUS talent marketplace. This phase follows **Phase 1: Foundation**, which has already delivered: + +- ✅ Database schema (ethos_tracks, ethos_artist_profiles, ethos_guild_members, ethos_licensing_agreements) +- ✅ Community group page (/community/groups/ethos) +- ✅ Curriculum skeleton (/docs/curriculum/ethos) +- ✅ Legal licensing templates (CEO to deliver this week) + +**Phase 2 Focus:** MVP build of the actual feature—upload UI, artist profiles, NEXUS integration, and licensing workflow. + +--- + +## Phase 2: MVP Build Objectives + +### 1. Track Upload & Library Interface + +**Goal:** Allow Ethos Guild members to upload their music and sound effects. + +**Technical Scope:** + +- **File Upload Component** + - Location: `code/client/components/ethos/TrackUploadModal.tsx` + - Features: + - Support MP3, WAV file formats + - File size limit: 50MB per track + - Progress bar for uploads + - Error handling for invalid files + - Storage: Supabase Storage (`ethos-tracks/{user_id}/{track_id}.{ext}`) + +- **Track Metadata Form** + - Location: `code/client/components/ethos/TrackMetadataForm.tsx` + - Fields: + - `title` (required, text) + - `description` (optional, textarea) + - `genre[]` (required, multi-select: "Synthwave", "Orchestral", "SFX", "Ambient", "Electronic") + - `bpm` (optional, number) + - `license_type` (required, radio: "ecosystem" vs "commercial_sample") + - `is_published` (optional, toggle) + +- **Track Library Page** + - Location: `code/client/pages/ethos/TrackLibrary.tsx` + - Features: + - Grid view of all published tracks + - Filter by genre, license type, artist + - Search by title + - Sort by: date, downloads, artist name + - Show: title, artist, genre badges, duration, license type, download count + - CTA: "Listen", "Download", "Use in My Project" (if ecosystem licensed), "Contact Artist" (if commercial) + +- **API Endpoints** + - `POST /api/ethos/tracks` - Create track (with file upload) + - `GET /api/ethos/tracks` - List all published tracks (paginated, filterable) + - `GET /api/ethos/tracks/:id` - Get track details + - `PUT /api/ethos/tracks/:id` - Update track metadata + - `DELETE /api/ethos/tracks/:id` - Delete track (soft delete, owner only) + - `POST /api/ethos/tracks/:id/download` - Increment download count + +--- + +### 2. Artist Profile Pages & Portfolio + +**Goal:** Let artists showcase their work and set up their portfolio. + +**Technical Scope:** + +- **Artist Profile Page** + - Location: `code/client/pages/ethos/ArtistProfile.tsx` + - Route: `/ethos/artists/:userId` or `/passport/:username/ethos` + - Displays: + - Artist name, avatar, bio + - Verified badge (if applicable) + - Skills (Synthwave, SFX Design, Orchestral, etc.) + - "For Hire" status + - Sample pricing (Custom Track $500, SFX Pack $150, Full Score $2000) + - Portfolio grid: all tracks (filter by published/private) + - Stats: total downloads, member since, success rate + - CTA: "Contact Artist", "Hire for Project" + +- **Artist Settings Page** + - Location: `code/client/pages/ethos/ArtistSettings.tsx` + - Route: `/ethos/settings` (authenticated) + - Features: + - Edit bio, avatar, portfolio URL + - Manage skills (multi-select) + - Toggle "for_hire" status + - Set sample pricing (track, SFX, score) + - Set turnaround_days estimate + - View licensing agreements (pending & approved) + +- **API Endpoints** + - `GET /api/ethos/artists/:userId` - Get artist profile + - `PUT /api/ethos/artists/:userId` - Update artist profile (owner only) + - `GET /api/ethos/artists/:userId/tracks` - Get artist's tracks + - `GET /api/ethos/artists` - List all artists (for discovery) + +--- + +### 3. NEXUS "Audio Production" Category Integration + +**Goal:** Ethos artists appear in NEXUS marketplace as "Audio Production" service providers. + +**Technical Scope:** + +- **NEXUS Audio Category** + - New service category on `/nexus` + - Display: Audio Production (alongside existing categories) + - Filter options: + - By skill: Synthwave, SFX, Orchestral, Ambient, Electronic + - By price range: $500-1000, $1000-5000, $5000+ + - By turnaround: 1-7 days, 1-4 weeks, 4+ weeks + - By rating: sort by downloads, artist rating + +- **Ethos Service Card** (in NEXUS grid) + - Artist name, avatar, verified badge + - Sample pricing preview: "Custom Track $500 • SFX Pack $150" + - Skills tags: [Synthwave] [SFX Design] [Electronic] + - Quick stats: 847 downloads, "For Hire" + - Rating: 4.8★ (based on licensing agreement ratings) + - CTA: "View Portfolio" → `/ethos/artists/:userId` + +- **Integration Points** + - Location: `code/client/pages/Nexus.tsx` + - Modify: + - Add "Audio Production" filter/category button + - Add Ethos service cards to the marketplace grid + - Ensure responsive layout (grid works on mobile/desktop) + - Add "Browse Audio Production" navigation link in hero + +- **API Changes** + - Update `GET /api/nexus/services` endpoint to include Ethos artists + - Query: `SELECT * FROM ethos_artist_profiles WHERE for_hire = true` + - Join with `user_profiles` for name, avatar, bio + - Include computed stats: total_downloads, license_agreements_count + +--- + +### 4. Licensing Agreement Workflow + +**Goal:** Manage commercial licensing agreements from inquiry to contract. + +**Technical Scope:** + +- **Contact Artist Flow** + - Location: `code/client/components/ethos/ContactArtistModal.tsx` + - When user clicks "Contact Artist" on a track or profile: + - Modal asks: "What's your project about?" + - Textarea for project description + - Link to sample commercial contract (stored in docs) + - CTA: "Request Licensing Agreement" + - Backend: Creates a `pending` agreement in ethos_licensing_agreements table + - Email: Notify artist that someone wants to license their track + +- **Artist Licensing Dashboard** + - Location: `code/client/pages/ethos/LicensingDashboard.tsx` + - Tab 1: "Pending Agreements" (awaiting response) + - Card per agreement: licensee name, track, project desc, created date + - CTA: "Review & Approve" or "Decline" + - Tab 2: "Active Agreements" (approved) + - Card per agreement: licensee, track, license type, expires_at + - Status: "Active", "Expiring Soon", "Expired" + - Tab 3: "Declined" + - Archive of declined agreements + +- **Approval Flow** + - Artist clicks "Review & Approve" + - Modal shows: + - Licensee info, project description + - Contract preview (linked to agreement_url) + - Options: "Approve" or "Decline with Message" + - If "Approve": + - Set `approved = true` in database + - Email licensee a confirmation & next steps (how to sign contract) + +- **API Endpoints** + - `POST /api/ethos/licensing-agreements` - Create agreement request + - `GET /api/ethos/licensing-agreements` - List for artist or licensee + - `PUT /api/ethos/licensing-agreements/:id` - Approve/decline + - `DELETE /api/ethos/licensing-agreements/:id` - Archive + +--- + +## UI/UX Design Principles + +### Color Palette +- Primary: Neon pink (#ec4899), purple (#a855f7), cyan (#06b6d4) +- Synthwave aesthetic: dark backgrounds, glowing accents +- Consistent with NEXUS (purple) and existing AeThex arms + +### Components +- Reuse existing UI components (Button, Card, Badge, Input, Textarea) +- Create new Ethos-specific components: + - `TrackUploadModal.tsx` + - `TrackMetadataForm.tsx` + - `TrackCard.tsx` (for grid display) + - `ArtistCard.tsx` (for NEXUS integration) + - `ContactArtistModal.tsx` + - `LicensingAgreementCard.tsx` + +### Navigation +- Add Ethos link to main nav: "Ethos Guild" +- Link to: `/ethos` or `/community/groups/ethos` (Phase 1 page) +- From Ethos Guild page, link to: + - `/ethos/library` - Browse all tracks + - `/ethos/artists` - Discover artists + - `/ethos/settings` - Artist settings (authenticated) + +--- + +## Database Queries & Indexing + +### Optimized Queries +```sql +-- Get all published tracks (with artist info) +SELECT t.*, p.full_name as artist_name, p.avatar_url +FROM ethos_tracks t +JOIN user_profiles p ON t.user_id = p.id +WHERE t.is_published = true +ORDER BY t.created_at DESC +LIMIT 20 OFFSET 0; + +-- Get artist profile with stats +SELECT ap.*, p.full_name, p.avatar_url, + COUNT(t.id) as track_count, + SUM(t.download_count) as total_downloads +FROM ethos_artist_profiles ap +JOIN user_profiles p ON ap.user_id = p.id +LEFT JOIN ethos_tracks t ON ap.user_id = t.user_id AND t.is_published = true +WHERE ap.user_id = $1 +GROUP BY ap.user_id, p.id; + +-- Get pending licensing agreements for artist +SELECT la.*, t.title as track_title, p.full_name as licensee_name +FROM ethos_licensing_agreements la +JOIN ethos_tracks t ON la.track_id = t.id +JOIN user_profiles p ON la.licensee_id = p.id +WHERE t.user_id = $1 AND la.approved = false +ORDER BY la.created_at DESC; +``` + +### Index Strategy +- `ethos_tracks`: index on (is_published, created_at), (user_id), (genre) +- `ethos_artist_profiles`: index on (for_hire, verified) +- `ethos_licensing_agreements`: index on (track_id, approved), (licensee_id) + +--- + +## API Endpoint Specifications + +### Tracks API + +**POST /api/ethos/tracks** +``` +Headers: Authorization: Bearer +Body: FormData { + file: File, + title: string, + description: string, + genre: string[], + bpm: number, + license_type: 'ecosystem' | 'commercial_sample', + is_published: boolean +} +Response: { id, user_id, title, file_url, ... } +``` + +**GET /api/ethos/tracks** +``` +Query: ?genre=Synthwave&license_type=ecosystem&page=1&limit=20&sort=downloads +Response: { tracks: [...], total, page, limit } +``` + +**PUT /api/ethos/tracks/:id** +``` +Headers: Authorization: Bearer +Body: Partial track update (title, description, genre, license_type, is_published) +Response: Updated track +``` + +**DELETE /api/ethos/tracks/:id** +``` +Headers: Authorization: Bearer +Response: { success: true } +``` + +### Artists API + +**GET /api/ethos/artists** +``` +Query: ?for_hire=true&verified=true&page=1&limit=20&skills=Synthwave +Response: { artists: [...], total } +``` + +**GET /api/ethos/artists/:userId** +``` +Response: { id, user_id, full_name, avatar_url, bio, skills, for_hire, pricing, stats } +``` + +**PUT /api/ethos/artists/:userId** +``` +Headers: Authorization: Bearer +Body: { bio, skills, for_hire, portfolio_url, sample_price_track, ... } +Response: Updated artist profile +``` + +### Licensing API + +**POST /api/ethos/licensing-agreements** +``` +Headers: Authorization: Bearer +Body: { track_id, project_description } +Response: { id, track_id, licensee_id, status: 'pending', ... } +``` + +**PUT /api/ethos/licensing-agreements/:id** +``` +Headers: Authorization: Bearer (artist only) +Body: { approved: boolean, message?: string } +Response: Updated agreement +``` + +--- + +## File Structure + +``` +code/client/ +├── pages/ +│ ├── ethos/ +│ │ ├── TrackLibrary.tsx +│ │ ├── ArtistProfile.tsx +│ │ ├── ArtistSettings.tsx +│ │ └── LicensingDashboard.tsx +├── components/ +│ └── ethos/ +│ ├── TrackUploadModal.tsx +│ ├── TrackMetadataForm.tsx +│ ├── TrackCard.tsx +│ ├── ArtistCard.tsx +│ ├── ContactArtistModal.tsx +│ └── LicensingAgreementCard.tsx +│ +code/api/ +├── ethos/ +│ ├── tracks.ts +│ ├── artists.ts +│ └── licensing-agreements.ts +``` + +--- + +## Timeline Estimate + +- **Week 1:** API endpoints + database queries (4 hours) +- **Week 2:** Track upload UI + library page (6 hours) +- **Week 3:** Artist profiles + NEXUS integration (6 hours) +- **Week 4:** Licensing workflow + testing (4 hours) + +**Total:** ~20 hours development + +--- + +## Success Criteria + +- ✅ Artists can upload tracks with metadata +- ✅ Tracks appear in library and NEXUS marketplace +- ✅ Artists can manage profiles and set pricing +- ✅ Licensing agreements workflow functional +- ✅ Downloads tracked and displayed +- ✅ Error handling and validation complete +- ✅ Performance: Track queries <200ms, artist queries <150ms +- ✅ Mobile responsive on all pages + +--- + +## Legal & Compliance + +- All licensing agreements linked to signed contract (agreement_url) +- Ecosystem license terms displayed at upload (user must agree) +- Commercial licensing disabled until legal templates approved +- Email notifications to artists for pending agreements +- Archive all licensing agreements for audit trail + +--- + +## Follow-Up: Phase 3 (Content & Community) + +Once Phase 2 MVP is live: + +1. Community team writes music production curriculum +2. Founding artists invited to upload their tracks +3. Monthly artist spotlights & events launched +4. Integration with Dev-Link for B2B game projects +5. CORP arm can hire artists for commercial projects via NEXUS + +--- + +## Related Documents + +- `code/docs/ETHOS_GUILD_STRATEGIC_BRIEF.md` - Strategic overview +- `code/supabase/migrations/20250206_add_ethos_guild.sql` - Database schema +- `/community/groups/ethos` - Community group landing page +- `/docs/curriculum/ethos` - Curriculum skeleton +