Actors & Workflows

System Actors

Primary Actors (End Users)

Actor	Description	Key Needs
Artist	Vocalist, rapper, singer-songwriter	Review mixes, approve finals, track versions
Producer	Beat maker, arranger, instrumentalist	Upload stems, manage sessions, gather feedback
Manager	Artist representative, label rep	Oversight, approvals, business decisions
Engineer	Mixing, mastering, recording engineer	Deliver versions, track revisions
Visual Artist	Graphic designer, video editor	Upload artwork, review with comments
Creative Director	Brand/creative lead	Final approvals, quality control

Secondary Actors

Actor	Description	Key Needs
Label A&R	Talent scout, project supervisor	Monitor progress, discovery
Distributor	Digital distribution partner	Asset delivery, metadata
Legal	Contract administration	Document management, signatures

---

User Journeys

Journey 1: Producer Creates a Project

sequenceDiagram
    participant P as Producer
    participant S as Sonnance
    participant A as Artist
    
    P->>S: Sign up / Login
    P->>S: Create ArtistSpace "Studio Sessions"
    P->>S: Create Project "New Single"
    P->>S: Create Track "Summer Vibes"
    P->>S: Upload beat (v1)
    P->>S: Invite Artist (email)
    S->>A: Email: "You're invited to collaborate"
    A->>S: Accept invite
    A->>S: Listen to beat
    A->>S: Add comment at 0:32 "Love this drop!"
    S->>P: Notification: New comment
    P->>S: Reply to comment
    P->>S: Upload beat (v2)
    S->>A: Notification: New version available
    A->>S: Review v2, mark approved
    S->>P: Notification: Version approved

Journey 2: Manager Reviews Progress

sequenceDiagram
    participant M as Manager
    participant S as Sonnance
    
    M->>S: Login
    M->>S: View Library (all ArtistSpaces)
    S->>M: Show 3 spaces with recent activity
    M->>S: Open "Client Album" project
    S->>M: Show 8 tracks, 2 pending approval
    M->>S: Open "Lead Single" track
    S->>M: Show version history, comments
    M->>S: Listen to latest version
    M->>S: Add comment: "Ready for mastering"
    M->>S: Mark as approved
    S->>M: Notification sent to collaborators

Journey 3: New User Onboarding

flowchart TD
    A[Land on Homepage] --> B[Sign Up]
    B --> C{Auth Method?}
    C -->|Email| D[Verify Email]
    C -->|Google| E[OAuth Flow]
    C -->|Apple| E
    D --> F[Welcome Screen]
    E --> F
    F --> G[Create First ArtistSpace]
    G --> H[Prompted: Upload or Invite?]
    H -->|Upload| I[Upload First Track]
    H -->|Invite| J[Enter Collaborator Email]
    I --> K[Dashboard Tour]
    J --> K
    K --> L[Start Using Platform]

---

Core Workflows

Workflow 1: File Upload & Processing

flowchart LR
    A[User selects file] --> B[Frontend validation]
    B --> C{File type?}
    C -->|Audio| D[Upload to Backend]
    C -->|Image| E[Upload with variants]
    D --> F[Store in Azure Blob]
    E --> G[Sharp processing]
    G --> H[thumb/medium/original]
    H --> F
    F --> I[CDN URL generation]
    I --> J[Save to MongoDB]
    J --> K[Emit WebSocket event]
    K --> L[Collaborators see new file]

Workflow 2: Comment & Notification Flow

flowchart LR
    A[User writes comment] --> B[POST /comment]
    B --> C[Save to MongoDB]
    C --> D[Get track collaborators]
    D --> E[Create notifications]
    E --> F[Emit WebSocket]
    F --> G[Live update in Wave view]
    F --> H[Update notification bell]

Workflow 3: Collaboration Invite

flowchart TD
    A[Owner clicks Invite] --> B[Enter email + role]
    B --> C{User exists?}
    C -->|Yes| D[Add to collaborators]
    C -->|No| E[Create invite link]
    D --> F[Send notification]
    E --> G[Send email invite]
    G --> H[User signs up]
    H --> I[Auto-add to resource]
    F --> J[User can access immediately]
    I --> J

Workflow 4: Version Approval

stateDiagram-v2
    [*] --> Draft
    Draft --> InReview: Upload file
    InReview --> NeedsRevision: Request changes
    InReview --> Approved: Approve
    NeedsRevision --> InReview: Upload new version
    Approved --> [*]

---

Permission Inheritance

Collaborators added at higher levels inherit access to child resources:

ArtistSpace (Admin)
    │
    ├── Project A (Inherited: Admin)
    │   ├── Track 1 (Inherited: Admin)
    │   └── Track 2 (Inherited: Admin)
    │
    └── Project B (Inherited: Admin)
        └── Track 3 (Inherited: Admin)

Override Rules:

• Child resource can have MORE restrictive permissions
• Child resource CANNOT have LESS restrictive permissions
• Owner at any level has full control

---

Mobile App Workflows (Future)

Quick Actions (Mobile-First)

Action	Gesture	Result
Quick Approve	Swipe right	Mark version approved
Quick Comment	Tap + hold	Voice-to-text comment
Share Link	Long press	Copy share link
Push Notification	Tap	Jump to context

Offline Capabilities

Feature	Offline Behavior
View library	Cached data
Play audio	Downloaded files
Add comment	Queued, sync on reconnect
Upload file	Queued, sync on WiFi

---

Analytics Events (User Tracking)

Engagement Events

Event	Trigger	Data
session_start	Login/app open	userId, platform
file_upload	Upload complete	fileType, size, duration
comment_created	New comment	trackId, hasTimestamp
version_approved	Approval click	trackId, version
invite_sent	Send invite	role, method

Business Events

Event	Trigger	Data
subscription_started	Plan upgrade	plan, price
subscription_cancelled	Cancel	plan, reason
storage_limit_warning	80% usage	currentUsage, limit

---

Integration Workflows (Future)

DAW Plugin Integration

sequenceDiagram
    participant D as DAW (Logic/Ableton)
    participant P as Sonnance Plugin
    participant S as Sonnance API
    
    D->>P: Export stems
    P->>S: Upload files
    S->>P: Return CDN URLs
    P->>D: Show success notification
    D->>P: Fetch comments
    P->>S: GET /comments?track=xxx
    S->>P: Return comments
    P->>D: Display in-DAW timeline

Distribution Integration

sequenceDiagram
    participant U as User
    participant S as Sonnance
    participant D as Distributor (DistroKid/TuneCore)
    
    U->>S: Click "Distribute"
    S->>S: Validate: approved version, metadata complete
    S->>D: API: Submit release
    D->>S: Webhook: Processing
    D->>S: Webhook: Live on platforms
    S->>U: Notification: "Now streaming!"