Normalize audio waveform peaks for Flutter

docs/artist-dashboard-api.md

@@ -0,0 +1,121 @@
+# Artist Dashboard API
+
+This endpoint powers the Flutter artist profile dashboard for the currently authenticated user.
+
+## Endpoint
+
+`GET /api/v1/users/me/dashboard`
+
+## Headers
+
+```http
+Authorization: Bearer <accessToken>
+```
+
+## Notes
+
+- This endpoint is private to the authenticated user.
+- It does not accept a `userId` parameter.
+- It does not expose another user's private analytics.
+- It keeps the existing `GET /api/v1/users/:id/profile-overview` endpoint unchanged.
+- Earnings, audience non-followers, and chart data are not faked. They return safe empty/default values until dedicated analytics storage exists.
+
+## Success Response Example
+
+```json
+{
+  "profile": {
+    "_id": "665f00000000000000000001",
+    "coverImage": "",
+    "avatar": "",
+    "name": "Artist Name",
+    "stageName": "Stage Name",
+    "bio": "Short artist bio",
+    "isVerified": false
+  },
+  "stats": {
+    "followersCount": 120,
+    "followingCount": 45,
+    "postsCount": 12,
+    "collaborationsCount": 2,
+    "viewCount": 3000,
+    "playCount": 980,
+    "listenCount": 980,
+    "likesCount": 220,
+    "commentsCount": 40,
+    "savesCount": 18,
+    "sharesCount": 11,
+    "engagementRate": 7.26,
+    "scorePercentage": 0,
+    "earnings": 0
+  },
+  "audience": {
+    "followers": 120,
+    "nonFollowers": 0,
+    "newFollowersThisWeek": 4,
+    "newFollowersThisMonth": 19
+  },
+  "engagementChart": [],
+  "topContent": [
+    {
+      "_id": "665f00000000000000000002",
+      "postType": "audio",
+      "thumbnailUrl": "",
+      "displayUrl": "",
+      "content": "New track",
+      "viewCount": 1000,
+      "playCount": 600,
+      "likesCount": 90,
+      "commentsCount": 10,
+      "savesCount": 8,
+      "engagementScore": 113,
+      "createdAt": "2026-06-08T00:00:00.000Z"
+    }
+  ],
+  "recentActivity": [],
+  "meta": {
+    "generatedAt": "2026-06-08T00:00:00.000Z",
+    "chartAvailable": false,
+    "earningsAvailable": false,
+    "audienceAnalyticsAvailable": false
+  }
+}
+```
+
+## Flutter Model Suggestion
+
+- `ArtistDashboard`
+- `ArtistDashboardProfile`
+- `ArtistDashboardStats`
+- `ArtistDashboardAudience`
+- `ArtistDashboardTopContent`
+- `ArtistDashboardRecentActivity`
+- `ArtistDashboardMeta`
+
+## UI Sections
+
+1. Profile header: use `profile.coverImage`, `profile.avatar`, `profile.name`, `profile.stageName`, `profile.bio`, `profile.isVerified`.
+2. Stats cards: use `stats.followersCount`, `stats.followingCount`, `stats.viewCount`, `stats.listenCount`, `stats.engagementRate`.
+3. Engagement chart: render only when `meta.chartAvailable === true`; otherwise show the empty state.
+4. Top content list: use `topContent`.
+5. Audience summary: use `audience.followers`, `audience.nonFollowers`, `audience.newFollowersThisWeek`, `audience.newFollowersThisMonth`.
+6. Recent activity: use `recentActivity`.
+7. Empty states: show clear UI for no posts, no analytics, chart unavailable, and earnings unavailable.
+
+## Empty States
+
+- No posts yet: `stats.postsCount === 0`.
+- No analytics yet: `stats.viewCount === 0 && stats.playCount === 0`.
+- Chart not available: `meta.chartAvailable === false`.
+- Earnings not available: `meta.earningsAvailable === false`.
+
+## Future Analytics Upgrade
+
+Daily chart data requires event-level or snapshot storage. Recommended future collections:
+
+- `post_view_events`
+- `post_play_events`
+- `post_engagement_events`
+- `daily_artist_analytics`
+
+Audience split requires viewer identity tracking per view/play event. Earnings requires a monetization/revenue module. Until those exist, the backend intentionally returns safe defaults instead of fake values.