System Requirements Document

1. Introduction

This System Requirements Document defines SocialVerse — "One Identity. All Your Social Profiles." — a production-grade, full-stack, consent-first social identity aggregator. SocialVerse lets a person create a single owned identity, connect the social-media accounts they own, verify ownership through official OAuth-based flows, import only the public profile information those platforms officially permit, and publish one shareable profile link plus QR/deep link containing all of their connected accounts.

The document converts the source material into implementable requirements: functional requirements expressed as user stories, personas, core user flows, design and interaction direction, non-functional requirements, tech stack, constraints, and glossary.

Governing privacy architecture (non-negotiable): the system must NOT identify or track a private person from their face or photo, must NOT perform facial recognition against social-media databases, must NOT scrape private accounts, must NOT bypass authentication or CAPTCHA, and must NOT collect hidden or non-public profile information.

Core product promise: "Connect the social accounts YOU OWN, verify them, and share them from one place." SocialVerse must never become a facial-recognition, people-tracking, private-profile-discovery, or mass social-media-scraping system.

Project name: the project is named update-tool; the product it builds is SocialVerse.

2. System Overview

SocialVerse is a web-first (PWA-first) platform composed of:

• A profile identity layer where a user owns one SocialVerse identity (avatar, name, username/handle, bio, location, timezone).
• A social provider adapter layer that integrates each supported platform through its official APIs using per-provider OAuth, access-token management, profile retrieval, and capability declarations.
• A search/discovery layer restricted to information legally available through official APIs or permitted public sources, with no identity inference.
• A verification layer producing a "✓ VERIFIED BY SOCIALVERSE" badge only through defined, platform-honest verification methods.
• A public profile and sharing layer with granular visibility controls, one shareable link, QR/deep links, and optional digital business card/vCard/NFC-compatible URL.
• A privacy center providing data viewing, export, revocation, hiding, and a full "Delete My Data" workflow.
• An admin/operations layer for provider configuration, OAuth error monitoring, API usage, rate limits, verification requests, abuse reports, audit logs, and system health.
• A background job layer for syncing only user-connected accounts within permitted scopes.
• An abuse-prevention layer with rate limiting, search throttling, bot/suspicious-activity detection, reporting, blocking, and suspension.

Example public identity shape: socialverse.app/nilesh — displaying a profile with connected and verified accounts across Instagram, YouTube, Facebook, LinkedIn, X, Telegram, Threads, GitHub, Pinterest, Discord, and Website.

3. Functional Requirements

3.1 Identity Creation and Ownership

1. As a user, I want to create one SocialVerse identity, so that all of my social profiles are represented from a single owned account.
2. As a user, I want to upload a profile photo/avatar for my SocialVerse identity, so that my unified profile is visually identifiable.
3. As a user, I want to enter my name, so that my identity is displayed correctly.
4. As a user, I want to add a username/handle, so that my SocialVerse profile URL is claimable and shareable.
5. As a user, I want a public SocialVerse profile generated at /u/[username] (e.g., socialverse.app/u/nilesh), so that I can share one canonical link.
6. As a user, I want to see a verification status on each of my connected accounts, so that I know which accounts are proven to be mine.
7. As a user, I want to detect duplicate usernames/profile URLs, so that collisions and conflicting claims are surfaced rather than silently accepted.
8. As a user, I want to disconnect accounts anytime, so that I retain full control over which social accounts remain linked to my SocialVerse identity.
9. As a user, I want to import only permitted public profile information, so that my profile is populated without violating any platform's terms.

3.2 Consent and Privacy Architecture

10. As a user, I want account linking to be strictly user-owned and user-initiated, so that no third party can attach an account on my behalf.
11. As a user, I want my social accounts verified through OAuth-based verification, so that ownership proof is based on provider authorization rather than guesswork.
12. As a user, I want consent-based profile aggregation, so that only data I authorize is combined into my SocialVerse identity.
13. As a platform operator, I want the system to never identify or track a private person from their face/photo, so that SocialVerse cannot be used for facial surveillance.
14. As a platform operator, I want the system to never perform facial recognition against social-media databases, so that no biometric matching capability exists in the product.
15. As a platform operator, I want the system to never scrape private accounts, bypass authentication, or bypass CAPTCHA, so that all integrations remain authorized and lawful.
16. As a platform operator, I want the system to never collect hidden or non-public profile information, so that the aggregation surface stays public and consented.
17. As a user, I want an explicit "Not supported by this platform" message whenever an official API does not provide a capability, instead of the system scraping or guessing.

3.3 Profile Photo Function

18. As a user, I want to upload a profile photo, so that my SocialVerse identity has an avatar.
19. As a user, I want to crop my uploaded photo, so that the framing suits my profile.
20. As a user, I want to rotate my uploaded photo, so that orientation is corrected.
21. As a user, I want to resize my uploaded photo, so that it meets profile dimensions.
22. As a user, I want to compress my uploaded photo, so that storage and delivery are efficient.
23. As a user, I want my uploaded photo converted to WebP, so that delivery is optimized.
24. As a user, I want an avatar generated from my upload, so that consistent avatar sizes are produced.
25. As a user, I want optional blur/background removal on my photo where legally and technically supported, so that I can improve presentation.
26. As a user, I want EXIF metadata stripped from my uploaded photo, so that embedded location/device data is not stored.
27. As a user, I want my uploaded photo stored securely, so that my media is protected at rest.
28. As a platform operator, I want the photo used only for the user's SocialVerse profile, so that the photo is never used to identify an unknown private individual across social platforms.
29. As a platform operator, I want no reverse-face-search functionality built on the photo, so that the product cannot be repurposed for people-finding.

3.4 Account Connection System

30. As a user, I want a "Connected Accounts" dashboard section, so that I can see every linked account in one place.
31. As a user, I want a "+ Connect Account" action, so that I can begin linking a new provider.
32. As a user, I want a provider card for each supported provider (Instagram, Facebook, YouTube, LinkedIn, X, TikTok, Threads, Pinterest, Reddit, GitHub, Discord, Telegram, Twitch, Spotify), so that connection state is per-provider and explicit.
33. As a user, I want a Connect action per provider, so that I can start that provider's authorization.
34. As a user, I want a Connected state per provider, so that I can see which providers are linked.
35. As a user, I want a Verified state per provider, so that I can distinguish ownership-verified accounts from merely added ones.
36. As a user, I want a Disconnect action per provider, so that I can unlink any connected account directly from its provider card.
37. As a user, I want a Refresh action per provider, so that I can re-sync permitted profile data on demand.
38. As a user, I want the OAuth flow to run as: click Connect → provider OAuth → consent screen → callback → validate state → exchange authorization code → encrypt token → fetch permitted profile data → store provider identity → show VERIFIED badge.
39. As a platform operator, I want OAuth state validated on callback, so that authorization responses cannot be forged or replayed.
40. As a platform operator, I want raw OAuth credentials never stored in plaintext, so that credential compromise is contained.

3.5 Social Provider Adapter Architecture

41. As a platform operator, I want a SocialProvider adapter architecture with one adapter per platform (Instagram, Facebook, YouTube, LinkedIn, X, TikTok, Threads, Pinterest, Reddit, GitHub, Discord, Telegram, Snapchat, Twitch, Spotify, and Custom URL), so that each platform's differences are isolated.
42. As a platform operator, I want each provider adapter to define its OAuth URL, so that authorization redirects are correct per platform.
43. As a platform operator, I want each provider adapter to define its OAuth callback, so that authorization responses are handled per platform.
44. As a platform operator, I want each provider adapter to perform access-token management, so that provider credentials are issued, associated with the correct social account, and kept current over the life of the connection.
45. As a platform operator, I want each provider adapter to encrypt tokens, so that stored credentials are protected.
46. As a platform operator, I want each provider adapter to retrieve profile data, so that permitted profile fields can be imported.
47. As a platform operator, I want each provider adapter to retrieve usernames, so that handles are displayed accurately.
48. As a platform operator, I want each provider adapter to expose the profile URL, so that visitors can reach the original account.
49. As a platform operator, I want each provider adapter to retrieve avatars where permitted, so that avatars appear only when legally allowed.
50. As a platform operator, I want each provider adapter to retrieve the display name, so that accounts are labeled correctly.
51. As a platform operator, I want each provider adapter to report verification status, so that badges reflect real platform-provided verification.
52. As a platform operator, I want each provider adapter to implement a disconnect function, so that unlinking fully revokes and removes the connection.
53. As a platform operator, I want each provider adapter to handle API rate limits, so that provider throttling does not break the product.
54. As a platform operator, I want each provider adapter to handle errors, so that provider failures degrade gracefully.
55. As a platform operator, I want each provider adapter to declare provider-specific permissions/scopes, so that only the minimum necessary access is requested.
56. As a user, I want access-token management handled on my behalf — token issuance, association with my connected account, encrypted storage, expiry tracking, refresh, rotation, and revocation on disconnect or deletion — so that my provider connections stay valid and secure without any credential ever being exposed to me or to other users.

3.6 Social Media Directory and Capability Matrix

57. As a platform operator, I want a provider registry (directory) covering Instagram, Facebook, YouTube, LinkedIn, X, TikTok, Threads, Pinterest, Reddit, GitHub, Discord, Telegram, Snapchat, Twitch, Spotify, Medium, Behance, Dribbble, Stack Overflow, and Quora, so that supported platforms are centrally catalogued.
58. As a platform operator, I want per-provider capabilities declared for OAuth, Profile, Username, Avatar, Public profile, Followers, Following, Posts, and Statistics, so that the product never assumes every provider behaves the same.
59. As a platform operator, I want a stored capability matrix (e.g., Instagram — OAuth: YES/NO, Profile API: YES/NO, Search API: YES/NO, Public stats: YES/NO), so that capability gaps are explicit.
60. As a user, I want the UI to automatically adapt to each provider's capabilities, so that unsupported actions are never shown as available.

3.7 Name / Username Search and Discovery

61. As a visitor, I want a search screen accepting a name, username, or profile URL (e.g., Nilesh Wakodikar, @nilesh, instagram.com/username, youtube.com/@channel), so that I can find permitted public profiles.
62. As a visitor, I want search results to contain only information legally available through official APIs or permitted public sources, so that discovery never depends on unauthorized data.
63. As a visitor, I want each result card to show profile photo, display name, username, platform, profile URL, verification status, and public bio if permitted, so that I can evaluate the profile before opening it.
64. As a visitor, I want an "Open Profile"/"Open Channel" action on each result, so that I can visit the original platform profile.
65. As a visitor, I want the system to not claim two profiles belong to the same person unless ownership is verified or the platform explicitly provides verification.
66. As a platform operator, I want a SearchProvider interface with searchByUsername(), searchByPublicProfileURL(), and getConnectedProfile(), so that search is a clean provider abstraction.
67. As a platform operator, I want searches executed only against supported official APIs and user-provided profile URLs, so that unauthorized scraping never occurs.
68. As a platform operator, I want search results normalized into { provider, username, displayName, profileUrl, avatarUrl, bio, verified, source }, so that results are consistent across providers.
69. As a platform operator, I want ranking to never infer identity, so that ordering does not assert that profiles are the same person.
70. As a visitor, I want the message "Multiple profiles found. These profiles are not confirmed to belong to the same person." when several profiles share a name, so that I do not assume identity equivalence.
71. As a user, I want to save/submit my own profile URLs as a supported input, so that accounts without search APIs can still be represented.
72. As a user, I want public-profile discovery by username/name where officially permitted, so that I can locate my own accounts on supported platforms.

3.8 Profile Verification

73. As a user, I want OAuth verification of my accounts, so that ownership is proven through provider authorization.
74. As a user, I want provider authorization as a verification method, so that platform-confirmed ownership is recognized.
75. As a user, I want user-added URL verification performed where technically possible, so that I can verify accounts that lack OAuth.
76. As a user, I want website ownership verification, so that my website link can be proven mine.
77. As a user, I want email-domain verification for professional profiles, so that professional identity can be proven.
78. As a user, I want a "✓ VERIFIED BY SOCIALVERSE" badge, so that my verified status is clearly attributed to SocialVerse.
79. As a platform operator, I want no verification badge that implies verification by an external platform unless that platform actually provides such verification, so that badges remain honest.
80. As a user, I want to track verification requests and their statuses, so that I know what has been verified and when.

3.9 Public Profile, Sharing, and Visibility Controls

81. As a user, I want my public profile to display a large avatar, name, username, and bio, so that visitors immediately understand who I am.
82. As a user, I want a "Follow SocialVerse Profile" action on my public profile, so that visitors can follow my SocialVerse identity.
83. As a user, I want a SOCIAL LINKS section listing my connected accounts (including Instagram, YouTube, LinkedIn, Facebook, X, TikTok, GitHub, Telegram, and Website), so that visitors can reach every account I choose to publish.
84. As a user, I want only accounts I explicitly made visible to appear on my public profile, so that visibility is fully owner-controlled.
85. As a user, I want privacy controls of PUBLIC, PRIVATE, and VISIBLE ONLY TO ME, so that I can control profile visibility at the required levels.
86. As a user, I want to hide my entire profile, so that my identity is not publicly discoverable.
87. As a user, I want to hide an individual social account, so that granular visibility is possible.
88. As a user, I want to share one link containing all my social accounts, so that one share replaces many.
89. As a user, I want QR/deep links for sharing my verified social identity, so that my profile can be shared physically or via device.
90. As a user, I want the dashboard to display MY SOCIALVERSE LINK with Copy Link, Share, and QR Code actions, so that sharing is immediate.

3.10 QR Code

91. As a user, I want a QR code generated for my SocialVerse profile (e.g., socialverse.app/u/nilesh), so that my profile can be scanned.
92. As a user, I want to download my QR code as PNG, so that I can use it in print or digital media.
93. As a user, I want to download my QR code as SVG, so that I can use it at any scale.
94. As a user, I want to share my QR code directly, so that I can distribute it without downloading first.
95. As a user, I want to print my QR code, so that it can be used on physical materials.
96. As a user, I want an optional digital business card, so that my identity can be presented professionally.
97. As a user, I want an optional vCard, so that my profile can be saved to contacts.
98. As a user, I want an optional NFC-compatible profile URL, so that my profile can be shared by tapping.

3.11 Dashboard

99. As a user, I want a "WELCOME BACK" dashboard greeting with my name, so that I land in a personalized workspace.
100. As a user, I want to see Connected Accounts count, so that I know how many accounts are linked.
101. As a user, I want to see Verified Accounts count, so that I know how many accounts are proven mine.
102. As a user, I want to see the Public Profile ON state, so that I know whether my profile is public.
103. As a user, I want to see Profile Views, so that I understand my reach.
104. As a user, I want a CONNECTED SOCIALS list with status markers and a "+ Add Social Account" action, so that I can manage accounts from the dashboard.
105. As a user, I want a dashboard sidebar navigation containing Home, My Profile, Social Accounts, Search, Verification, QR Code, Privacy, and Settings, so that every core area is reachable.
106. As a user, I want the frontend to provide the pages /, /login, /register, /dashboard, /profile, /profile/edit, /accounts, /accounts/connect, /search, /search/results, /verification, /settings, /security, /privacy, /share, /qr, and /admin, so that all product surfaces exist as routed pages.
107. As a visitor, I want a landing page titled SOCIALVERSE with the line "Connect all your social identities in one place." and the buttons [ Create My Social Profile ] and [ Search Public Profiles ], so that I can immediately start either journey.
108. As a visitor, I want the landing page to present the display line "One Identity. All Your Social Profiles." with a single sentence explaining consent-first aggregation, a primary button reading "Create your identity", and a text link "See how verification works →", so that the product promise and the consent-first posture are stated before any signup.

3.12 Privacy Center

108. As a user, I want a Privacy Dashboard, so that I can manage my data in one place.
109. As a user, I want to view stored data, so that I know exactly what SocialVerse holds about me.
110. As a user, I want to delete a connected account, so that a link can be removed.
111. As a user, I want to delete my profile, so that my SocialVerse identity is removed.
112. As a user, I want to export my data, so that I can take my information with me.
113. As a user, I want to hide my profile, so that I can go private at any time.
114. As a user, I want to hide an individual social account, so that I can publish selectively.
115. As a user, I want to revoke access, so that provider permissions are withdrawn.
116. As a user, I want to delete my search history, so that my queries are not retained.
117. As a user, I want to delete my uploaded avatar, so that my media can be removed.
118. As a user, I want a "Delete My Data" workflow that runs Confirm → Revoke OAuth tokens → Delete social connections → Delete profile data → Delete avatar → Delete logs according to retention policy, so that deletion is complete and orderly.

3.13 Social Profile Database

119. As a platform operator, I want a PostgreSQL users table with id, email, password_hash, display_name, avatar_url, bio, country, city, timezone, created_at, updated_at, deleted_at, so that identity records are persisted.
120. As a platform operator, I want a PostgreSQL social_accounts table with id, user_id, provider, provider_user_id, username, display_name, profile_url, avatar_url, bio, verified, verification_method, connected_at, last_synced_at, status, so that connected accounts are persisted.
121. As a platform operator, I want a UNIQUE constraint on (provider, provider_user_id) in social_accounts, so that the same provider account cannot be linked twice.
122. As a platform operator, I want a social_tokens table with id, social_account_id, encrypted_access_token, encrypted_refresh_token, expires_at, scopes, created_at, updated_at, so that tokens are stored encrypted with scope and expiry metadata.
123. As a platform operator, I want a social_searches table with id, user_id, query, search_type, created_at, so that searches are tracked without storing unnecessary personal search data.
124. As a platform operator, I want a profile_links table with id, user_id, platform, url, label, is_verified, created_at, so that user-provided profile links are persisted.
125. As a platform operator, I want a verification_requests table with id, user_id, platform, provider_account_id, status, verification_method, created_at, verified_at, so that verification lifecycle is recorded.
126. As a platform operator, I want an audit_logs table with id, user_id, action, resource_type, resource_id, ip_hash, user_agent_hash, created_at, so that actions are auditable using hashed network/agent identifiers.

3.14 Security Requirements

127. As a platform operator, I want JWT-based authentication, so that sessions are securely issued.
128. As a platform operator, I want refresh tokens, so that sessions can be renewed without re-authentication.
129. As a platform operator, I want OAuth state validation, so that callback forgery is prevented.
130. As a platform operator, I want PKCE where supported, so that authorization code interception is mitigated.
131. As a platform operator, I want CSRF protection, so that cross-site request forgery is prevented.
132. As a platform operator, I want rate limiting, so that abuse and brute force are constrained.
133. As a platform operator, I want input validation, so that malformed or malicious input is rejected.
134. As a platform operator, I want SQL injection protection, so that database integrity is preserved.
135. As a platform operator, I want XSS protection, so that injected scripts cannot execute.
136. As a platform operator, I want a Content Security Policy (CSP), so that script and resource loading is restricted.
137. As a platform operator, I want secure cookies, so that session material is not exposed.
138. As a platform operator, I want encryption at rest, so that stored data and tokens are protected.
139. As a platform operator, I want HTTPS enforced, so that traffic is encrypted in transit.
140. As a platform operator, I want secret management, so that credentials are handled outside source control.
141. As a platform operator, I want token rotation, so that long-lived credential exposure is limited.
142. As a platform operator, I want audit logs, so that security-relevant actions are traceable.
143. As a platform operator, I want account deletion, so that users can be fully removed.
144. As a platform operator, I want data export, so that users can retrieve their data.
145. As a platform operator, I want the system to never expose OAuth access tokens, refresh tokens, passwords, private messages, private account data, or private account content, so that sensitive material never leaks.

3.15 Abuse Prevention

146. As a platform operator, I want rate limiting and search throttling, so that query volume is controlled.
147. As a platform operator, I want bot detection, so that automated abuse is identified.
148. As a platform operator, I want suspicious activity detection, so that anomalous behavior triggers review.
149. As a user, I want to report a profile, so that harmful or impersonating profiles can be escalated.
150. As a user, I want to block a user, so that unwanted interaction is prevented.
151. As an administrator, I want account suspension, so that violating accounts can be actioned.
152. As a platform operator, I want API abuse monitoring, so that provider-API misuse is detected.
153. As a platform operator, I want the system to disallow bulk harvesting of profiles, so that directory-scale extraction is impossible.
154. As a platform operator, I want the system to disallow mass scraping, so that provider terms are respected.
155. As a platform operator, I want the system to disallow private-account discovery, so that non-public accounts are never surfaced.
156. As a platform operator, I want the system to disallow face-based identification, so that the platform cannot identify people from photos.
157. As a platform operator, I want the system to disallow doxxing, so that personal information is not aggregated for targeting.
158. As a platform operator, I want the system to disallow location tracking, so that no individual is tracked by location.
159. As a platform operator, I want the system to disallow password collection and credential harvesting, so that the platform cannot be used for phishing-style data capture.

3.16 Admin Panel

160. As an administrator, I want an admin dashboard showing Users, so that I can review the user base.
161. As an administrator, I want the admin dashboard to show Connected Accounts, so that linkage volume is visible.
162. As an administrator, I want the admin dashboard to show Providers, so that provider status is centralized.
163. As an administrator, I want the admin dashboard to show OAuth errors, so that integration failures are diagnosable.
164. As an administrator, I want the admin dashboard to show API usage, so that provider consumption is tracked.
165. As an administrator, I want the admin dashboard to show Rate limits, so that throttling incidents are visible.
166. As an administrator, I want the admin dashboard to show Search requests, so that search load and patterns are monitored.
167. As an administrator, I want the admin dashboard to show Verification requests, so that pending verifications can be handled.
168. As an administrator, I want the admin dashboard to show Reports, so that submitted reports are triaged.
169. As an administrator, I want the admin dashboard to show Abuse reports, so that abuse handling is centralized.
170. As an administrator, I want the admin dashboard to show Audit logs, so that actions are reviewable.
171. As an administrator, I want the admin dashboard to show System health, so that service status is observable.
172. As an administrator, I want provider management covering Provider name, so that providers are identifiable.
173. As an administrator, I want provider management covering Enabled, so that providers can be switched on/off.
174. As an administrator, I want provider management covering OAuth configuration, so that client credentials and callbacks are managed.
175. As an administrator, I want provider management covering Scopes, so that requested permissions are controlled.
176. As an administrator, I want provider management covering API version, so that each adapter targets the correct API.
177. As an administrator, I want provider management covering Rate limits, so that thresholds are configurable.
178. As an administrator, I want provider management covering Capabilities, so that the capability matrix is administrable.

3.17 API Architecture and Endpoints

179. As a platform operator, I want a FastAPI backend structured as backend/app/ with main.py, api/ (auth.py, users.py, profiles.py, social_accounts.py, search.py, verification.py, providers.py, privacy.py, admin.py), providers/ (base.py, instagram.py, facebook.py, youtube.py, linkedin.py, x.py, tiktok.py, threads.py, github.py, reddit.py), models/, schemas/, services/, security/, workers/, so that the codebase is organized by concern.
180. As a platform operator, I want the following endpoints implemented: POST /auth/register, POST /auth/login, POST /auth/logout.
181. As a platform operator, I want GET /me and PATCH /me implemented, so that the current user record is readable and updatable.
182. As a platform operator, I want GET /social/providers implemented, so that available providers and capabilities are exposed.
183. As a platform operator, I want POST /social/{provider}/connect and GET /social/{provider}/callback implemented, so that the OAuth connect flow works per provider.
184. As a platform operator, I want GET /social/accounts and DELETE /social/accounts/{id} implemented, so that connected accounts can be listed and removed.
185. As a platform operator, I want POST /search and GET /search/{id} implemented, so that searches can be executed and retrieved.
186. As a platform operator, I want GET /profile/{username} and PATCH /profile implemented, so that public profiles can be fetched and edited.
187. As a platform operator, I want POST /verification and GET /verification/status implemented, so that verification can be requested and tracked.
188. As a platform operator, I want POST /qr/generate implemented, so that QR codes can be produced.
189. As a platform operator, I want GET /privacy/export and DELETE /privacy/account implemented, so that data export and account deletion are available.

3.18 Background Jobs

190. As a platform operator, I want a Celery task sync_social_profile, so that connected profiles are refreshed within permitted scopes.
191. As a platform operator, I want a Celery task refresh_oauth_token, so that tokens are renewed before expiry.
192. As a platform operator, I want a Celery task check_provider_status, so that provider availability is monitored.
193. As a platform operator, I want a Celery task update_profile_avatar, so that avatar processing runs asynchronously.
194. As a platform operator, I want a Celery task cleanup_expired_tokens, so that stale credentials are purged.
195. As a platform operator, I want a Celery task process_data_export, so that export generation is handled in the background.
196. As a platform operator, I want a Celery task delete_user_data, so that deletion workflows complete reliably.
197. As a platform operator, I want a Celery task security_monitoring, so that security signals are evaluated continuously.
198. As a platform operator, I want background jobs to never continuously monitor people and to synchronize only accounts connected by the user and only within permitted API scopes.

3.19 Notifications

199. As a user, I want a notification when an account is connected, so that I have confirmation.
200. As a user, I want a notification when an account is disconnected, so that I am aware of changes.
201. As a user, I want a notification when verification is completed, so that I know my status changed.
202. As a user, I want a notification when OAuth expires, so that I can reconnect.
203. As a user, I want a security alert notification, so that I can respond to risk.
204. As a user, I want a notification for a new profile view, so that I know my profile is being seen.
205. As a user, I want optional email notifications, so that I can receive alerts outside the app.

3.20 Analytics

206. As a user, I want Profile views analytics for my own profile, so that I understand reach.
207. As a user, I want Link clicks analytics, so that I know which links perform.
208. As a user, I want Social clicks analytics, so that I see which platforms attract attention.
209. As a user, I want QR scans analytics, so that I can measure offline sharing.
210. As a user, I want Device type analytics, so that I understand visitor context.
211. As a user, I want country-level aggregate statistics where privacy-safe, so that I get regional insight without individual tracking.
212. As a platform operator, I want analytics to never provide private-person tracking, so that measurement remains privacy-safe and limited to the user's own profile.

3.21 Mobile Application

213. As a user, I want a PWA-first experience, so that I can use SocialVerse on mobile without an app install.
214. As a user, I want later Android and iOS applications built with React Native / Expo, so that native mobile access is available.
215. As a user, I want mobile screens including Splash, Login, Register, Dashboard, Connect Accounts, Search, Profile, QR, Settings, and Privacy, so that all key journeys exist on mobile.

3.22 Monetization / Plans

216. As a user on the FREE plan, I want 5 connected accounts, a basic profile, and a QR code, so that I can start at no cost.
217. As a user on the PRO plan, I want unlimited permitted social links, advanced analytics, a custom profile URL, custom themes, and a digital business card, so that I can build a premium identity.
218. As a user on the BUSINESS plan, I want team profiles, brand pages, an employee social directory, analytics, and admin controls, so that organizations can present collective identity.

3.23 Environment, Deliverables, and Setup

219. As a platform operator, I want Docker Compose services for frontend, backend, postgres, redis, worker, and nginx, so that the stack runs locally and consistently.
220. As a platform operator, I want production deployment using Vercel or equivalent for the frontend, AWS/GCP/Azure/Railway/Render for the backend, a managed PostgreSQL service for the database, S3-compatible object storage, and Cloudflare CDN, so that the system scales in production.
221. As a platform operator, I want environment variables DATABASE_URL, REDIS_URL, JWT_SECRET, ENCRYPTION_KEY, and per-provider client credentials (e.g., INSTAGRAM_CLIENT_ID/INSTAGRAM_CLIENT_SECRET, YOUTUBE_CLIENT_ID/YOUTUBE_CLIENT_SECRET, LINKEDIN_CLIENT_ID/LINKEDIN_CLIENT_SECRET, X_CLIENT_ID/X_CLIENT_SECRET, TIKTOK_CLIENT_KEY/TIKTOK_CLIENT_SECRET), so that configuration is externalized.
222. As a platform operator, I want secrets never committed to Git, so that credentials are not exposed.
223. As a platform operator, I want Swagger/OpenAPI documentation available at /docs, so that the API is discoverable.
224. As a platform operator, I want the final deliverable to include frontend, backend, database, Redis, Celery, OAuth architecture, provider adapters, authentication, authorization, admin panel, privacy center, search, profile pages, QR generator, API documentation, Docker, .env.example, database migrations, seed data, tests, and README.
225. As a platform operator, I want a complete setup procedure: 1) install dependencies, 2) configure .env, 3) create database, 4) run migrations, 5) start Redis, 6) start Celery, 7) start FastAPI, 8) start Next.js, 9) configure OAuth providers, 10) deploy production.

3.24 Testing Requirements

226. As a platform operator, I want unit tests, integration tests, OAuth tests, API tests, security tests, database tests, frontend tests, and E2E tests.
227. As a platform operator, I want tests covering registration and login.
228. As a platform operator, I want tests covering OAuth.
229. As a platform operator, I want tests covering connect account and disconnect account.
230. As a platform operator, I want tests covering profile editing.
231. As a platform operator, I want tests covering the public profile.
232. As a platform operator, I want tests covering search.
233. As a platform operator, I want tests covering QR generation.
234. As a platform operator, I want tests covering privacy deletion.
235. As a platform operator, I want tests covering data export.

4. User Personas

1. Identity Owner (individual user) Owns one SocialVerse identity. Creates a profile with avatar, name, username/handle, bio, and location. Connects owned accounts, completes OAuth verification, relies on managed access tokens, manages visibility levels, generates QR codes, shares one link, reviews notifications and analytics, disconnects accounts at any time, and exercises the privacy center (hide, revoke, export, delete). Sees provider cards, connected/verified states, and the "Not supported by this platform" state.

2. Public Profile Visitor / Searcher Searches by name, username, or profile URL. Views result cards (photo, display name, username, platform, profile URL, verification status, permitted public bio). Opens original platform profiles, follows SocialVerse profiles, and scans QR/deep links. Never sees private data and never receives identity assertions that are not verified.

3. Platform Administrator / Operator Manages the provider registry and capability matrix, provider enablement, OAuth configuration, scopes, API versions, and rate limits. Monitors OAuth errors, API usage, rate limits, search requests, verification requests, reports, abuse reports, audit logs, and system health. Handles abuse (reports, blocks, suspensions) and reviews verification requests.

4. Business/Team Account Manager (BUSINESS plan) Uses team profiles, brand pages, and an employee social directory with analytics and admin controls, presenting collective organizational identity under the same consent-first rules.

System actors (not personas): Social providers (Instagram, Facebook, YouTube, LinkedIn, X, TikTok, Threads, Pinterest, Reddit, GitHub, Discord, Telegram, Snapchat, Twitch, Spotify, and Custom URL), the optional email delivery channel (outbound recipient for notifications), and infrastructure services (PostgreSQL, Redis, Celery, object storage, CDN).

5. Core User Flows

Flow A — Create identity and connect the first account (Identity Owner)

1. Land on the SOCIALVERSE landing page; choose "Create My Social Profile".
2. Register/login; create the SocialVerse identity.
3. Enter name, username/handle, bio, country, city, timezone; upload and process a profile photo (crop, rotate, resize, compress, WebP conversion, avatar generation, EXIF stripping, secure storage).
4. Go to Accounts → "+ Connect Account"; select a provider card.
5. Click Connect → provider OAuth → consent screen → callback → validate state → exchange authorization code → encrypt token → fetch permitted profile data → store provider identity → show VERIFIED badge.
6. If the provider API lacks a capability, see "Not supported by this platform".
7. Repeat for further providers; optionally add a user-provided profile URL, verification request, or refresh.
8. Disconnect any account at any time from its provider card; confirm the notification.

Flow B — Publish, share, and QR distribution (Identity Owner)

1. Open the public profile at /u/[username]; choose visibility (PUBLIC / PRIVATE / VISIBLE ONLY TO ME) and hide/show individual accounts.
2. Confirm only explicitly visible accounts appear in SOCIAL LINKS.
3. From the dashboard's "YOUR SOCIALVERSE LINK", Copy Link, Share, or open QR Code.
4. Generate the QR code; download PNG or SVG, share, or print; optionally use the digital business card, vCard, or NFC-compatible URL.

Flow C — Search and view a public profile (Visitor/Searcher)

1. Open the search screen; enter name, username, or profile URL.
2. Submit search; system queries only official APIs and permitted public sources via the SearchProvider abstraction.
3. Read normalized result cards (photo, display name, username, platform, profile URL, verification status, permitted public bio).
4. If multiple same-name profiles appear, read: "Multiple profiles found. These profiles are not confirmed to belong to the same person."
5. Open the original profile, or open the SocialVerse public profile, follow it, click a social link, or scan the QR/deep link.

Flow D — Verification (Identity Owner)

1. Go to Verification; select an account or link.
2. Choose a method: OAuth verification, provider authorization, user-added URL verification (where technically possible), website ownership verification, or email-domain verification for professional profiles.
3. Submit a verification request; track its status and timestamp.
4. On success, the connection shows "✓ VERIFIED BY SOCIALVERSE"; no badge implies external-platform verification unless the platform itself provides it.

Flow E — Privacy / "Delete My Data" (Identity Owner)

1. Open Privacy Dashboard; view stored data, connections, searches, avatar, and tokens.
2. Choose a targeted action: delete connected account, hide profile, hide individual account, revoke access, delete search history, delete uploaded avatar, disconnect accounts anytime, or export data.
3. For full deletion: Confirm → Revoke OAuth tokens → Delete social connections → Delete profile data → Delete avatar → Delete logs according to retention policy.

Flow F — Provider and platform operations (Administrator)

1. Review the admin dashboard: users, connected accounts, providers, OAuth errors, API usage, rate limits, search requests, verification requests, reports, abuse reports, audit logs, system health.
2. Update a provider record: name, enabled flag, OAuth configuration, scopes, API version, rate limits, capabilities.
3. Handle a report: report profile / block user / account suspension; monitor API abuse.
4. Confirm the system rejects bulk harvesting, mass scraping, private-account discovery, face-based identification, doxxing, location tracking, and credential harvesting.

Flow G — Team and brand identity (Business/Team Account Manager)

1. Operate on the BUSINESS plan with team profiles, brand pages, employee social directory, analytics, and admin controls.
2. Apply the same consent-first connection, verification, visibility, and privacy rules to all team and employee listings.

Flow H — Access-token lifecycle and background processing (System)

1. On connect, the adapter issues and encrypts the access token, records scope and expiry, and associates it with the linked social account.
2. Celery executes refresh_oauth_token ahead of expiry, rotates tokens where supported, and cleanup_expired_tokens purges stale credentials.
3. On disconnect, revocation, or account deletion, the token associated with that connection is revoked at the provider and removed from storage.
4. Celery also executes sync_social_profile, check_provider_status, update_profile_avatar, process_data_export, delete_user_data, and security_monitoring.
5. Jobs act only on user-connected accounts and only within permitted API scopes; no continuous person monitoring occurs.

6. Visuals Colors and Theme

The source specifies: premium modern SaaS design, dark + light mode, glass cards, rounded cards, smooth animations, responsive desktop/mobile, provider logos, and clean typography. The following restrained palette defaults are derived from that direction:

Core theme

• Modes: Dark (default) and Light, with a user-switchable toggle.
• Foundation dark: deep near-black slate (#0B0E14) with elevated surfaces (#121722).
• Foundation light: soft off-white (#F7F8FB) with white surfaces (#FFFFFF).
• Primary brand: indigo-violet (#6366F1 → #8B5CF6 gradient) representing the "one identity" hub.
• Accent (verified): emerald (#22C55E) for "✓ Verified" badges and enabled provider states.
• Accent (attention): amber (#F59E0B) for OAuth expiry, "Added" state, and pending verification.
• Accent (destructive): red (#EF4444) for disconnect, delete, and abuse actions.
• Neutrals: slate ramp for typography hierarchy (#0F172A → #94A3B8 dark-mode inverse).
• Surfaces: glass cards using translucent fills with 12–20px backdrop blur, 1px subtle borders, and soft elevation shadows; rounded corners at 12–20px radius.
• Provider logos: official, platform-supplied brand marks rendered consistently at fixed sizes with monochrome fallback.
• Typography: one clean geometric sans for UI (display weights for headings, regular/medium for body), tabular numerals for counts and analytics.
• Data visualization: single-hue brand ramp with capability/verification semantics matching the badge colors.
• Contrast: text and interactive states meet readable contrast in both modes; badges never rely on color alone (icon + label).

7. Signature Design Concept

"Orbit Identity Hub." The central avatar sits as the single owned identity; provider logos orbit it in concentric rings, each node either verified (solid, emerald-tinged), added (outlined, amber-tinged), or unavailable/not supported (dimmed, labeled "Not supported by this platform"). The composition states the product promise visually — one identity, all your social profiles — and makes verification status legible at a glance. The same motif scales down into the dashboard header, the provider connection cards, and the public profile's SOCIAL LINKS block, so identity and verification read as one continuous visual language across the app, the QR/digital business card, and the mobile PWA.

8. Interaction Model & Motion Direction

• Connect and consent: clicking Connect initiates a clear linear progression (OAuth → consent → callback → token encrypted → profile data fetched → identity stored → VERIFIED badge). Each step is expressed with an inline step indicator, never a blocking full-screen takeover.
• Token state transparency: connection cards silently reflect token health — valid, refreshing, expiring, or revoked — and surface a reconnect affordance when a token can no longer be refreshed.
• Badge reveal: the "✓ VERIFIED BY SOCIALVERSE" badge animates in with a short scale-and-fade once verification resolves; "Added" states settle without celebratory motion.
• Glass depth: cards lift marginally on hover/focus with a subtle border and shadow shift, reinforcing the frosted-glass language without heavy parallax.
• Provider grid: cards react to capability state — enabled, connected, verified, refreshing, and not-supported — with a short shimmer only during refresh.
• Disconnect confirmation: unlinking is a two-step gesture (confirm sheet → settled disconnected state) with an undo-safe ordering, so accounts are never removed accidentally.
• QR interaction: QR panel flips or expands to reveal PNG/SVG/Share/Print and the optional business card/vCard/NFC URL, keeping distribution options one gesture away.
• Dashboard motion: counts (Connected Accounts, Verified Accounts, Profile Views) animate with a restrained count-up on load; the sidebar transitions between Home, My Profile, Social Accounts, Search, Verification, QR Code, Privacy, and Settings.
• Search feedback: results stream in as cards with staggered soft entry; the multi-profile disclaimer appears as a persistent inline banner, not a dismissible toast.
• Privacy destructive actions: deletions use explicit confirm steps with typed or double confirmation, and progress through the Delete My Data sequence visibly.
• Responsiveness: the same interaction vocabulary adapts from desktop sidebar layouts to mobile stacked layouts in the PWA and later React Native/Expo apps.
• Timing and restraint: short, purposeful easing (150–300ms); motion never obscures content, and a reduced-motion preference collapses animation to opacity-only transitions.

9. Non-Functional Requirements

Security and credential handling

• JWT, refresh tokens, OAuth state validation, PKCE where supported, CSRF protection, rate limiting, input validation, SQL injection protection, XSS protection, CSP, secure cookies, encryption at rest, HTTPS, secret management, token rotation, and audit logs are mandatory.
• Access tokens and refresh tokens are issued, tracked with scopes and expiry, refreshed, rotated, and revoked through the provider adapters; they are stored only in encrypted fields and never in plaintext.
• Passwords, private messages, and private account data are never exposed.
• Secrets are never committed to Git.
• Disconnection must revoke provider credentials and remove stored tokens, not merely hide the account.

Privacy and consent

• Consent-first aggregation: only user-owned, user-initiated, OAuth-authorized connections are aggregated.
• No facial recognition, no face-based identification, no reverse-face-search, no private-account discovery, no CAPTCHA or authentication bypass, no collection of hidden/non-public profile data.
• No bulk harvesting, mass scraping, doxxing, location tracking, or credential harvesting.
• Unnecessary personal search data is not stored; audit logs use hashed IP and user-agent values.
• "Delete My Data" completes revocation, connection deletion, profile deletion, avatar deletion, and retention-policy-compliant log deletion.

Rate limiting and provider etiquette

• Per-provider API rate-limit handling is implemented in each adapter; search throttling applies to discovery surfaces; API abuse monitoring and rate-limit visibility exist in the admin panel.
• If an official API cannot provide a capability, the UI shows "Not supported by this platform" rather than scraping or guessing.
• Platforms are never scraped where their terms or APIs prohibit it.

Background processing and monitoring boundaries

• Jobs synchronize only user-connected accounts, only within permitted API scopes, and never continuously monitor individuals.
• Worker tasks (sync, token refresh, provider status, avatar update, token cleanup, export, deletion, security monitoring) must be idempotent and failure-tolerant.

Data integrity

• The (provider, provider_user_id) uniqueness constraint protects against duplicate account linkage.
• Soft deletion is supported on user records via deleted_at.

Observability and operations

• Admin dashboard surfaces users, connected accounts, providers, OAuth errors, API usage, rate limits, search requests, verification requests, reports, abuse reports, audit logs, and system health.
• Email notifications are optional and outbound-only.

Analytics privacy

• Analytics are scoped to the user's OWN profile and never provide private-person tracking; geographic insight is limited to country-level aggregates where privacy-safe.

Quality assurance

• Unit, integration, OAuth, API, security, database, frontend, and E2E tests cover registration, login, OAuth, connect account, disconnect account, profile editing, public profile, search, QR generation, privacy deletion, and data export.

10. Tech Stack

Frontend

• Next.js, TypeScript, Tailwind CSS, shadcn/ui.
• Dark + light mode, glass cards, rounded cards, smooth animations, responsive desktop/mobile, provider logos, clean typography.
• Routes: /, /login, /register, /dashboard, /profile, /profile/edit, /accounts, /accounts/connect, /search, /search/results, /verification, /settings, /security, /privacy, /share, /qr, /admin.

Backend

• FastAPI with the specified structure: backend/app/main.py, api/ (auth.py, users.py, profiles.py, social_accounts.py, search.py, verification.py, providers.py, privacy.py, admin.py), providers/ (base.py, instagram.py, facebook.py, youtube.py, linkedin.py, x.py, tiktok.py, threads.py, github.py, reddit.py), models/, schemas/, services/, security/, workers/.
• Provider adapters own the access-token lifecycle: issuance, encrypted persistence, scope and expiry tracking, refresh, rotation, and revocation.
• API endpoints: POST /auth/register, POST /auth/login, POST /auth/logout, GET /me, PATCH /me, GET /social/providers, POST /social/{provider}/connect, GET /social/{provider}/callback, GET /social/accounts, DELETE /social/accounts/{id}, POST /search, GET /search/{id}, GET /profile/{username}, PATCH /profile, POST /verification, GET /verification/status, POST /qr/generate, GET /privacy/export, DELETE /privacy/account.
• Swagger/OpenAPI documentation served at /docs.

Data and messaging

• PostgreSQL (tables: users, social_accounts, social_tokens, social_searches, profile_links, verification_requests, audit_logs).
• Redis.
• Celery workers (sync_social_profile, refresh_oauth_token, check_provider_status, update_profile_avatar, cleanup_expired_tokens, process_data_export, delete_user_data, security_monitoring).

Mobile

• PWA first; later Android and iOS via React Native / Expo (Splash, Login, Register, Dashboard, Connect Accounts, Search, Profile, QR, Settings, Privacy).

Infrastructure and deployment

• Docker Compose services: frontend, backend, postgres, redis, worker, nginx.
• Production: frontend on Vercel or equivalent; backend on AWS / GCP / Azure / Railway / Render; managed PostgreSQL service; S3-compatible object storage; Cloudflare CDN.
• Configuration: .env with DATABASE_URL, REDIS_URL, JWT_SECRET, ENCRYPTION_KEY, and per-provider client credentials (e.g., INSTAGRAM_CLIENT_ID/INSTAGRAM_CLIENT_SECRET, YOUTUBE_CLIENT_ID/YOUTUBE_CLIENT_SECRET, LINKEDIN_CLIENT_ID/LINKEDIN_CLIENT_SECRET, X_CLIENT_ID/X_CLIENT_SECRET, TIKTOK_CLIENT_KEY/TIKTOK_CLIENT_SECRET), plus .env.example.

Delivery artifacts

• Database migrations, seed data, tests, README, and a setup procedure covering dependency install, .env configuration, database creation, migrations, Redis, Celery, FastAPI, Next.js, OAuth provider configuration, and production deployment.

11. Assumptions and Constraints

• SocialVerse is a consent-first social identity aggregator; its promise is "Connect the social accounts YOU OWN, verify them, and share them from one place."
• The system must never become a facial-recognition, people-tracking, private-profile-discovery, or mass social-media-scraping system.
• Providers are integrated only through official APIs and permitted public sources; a platform is never scraped where its Terms or API prohibit it.
• Unsupported capabilities display "Not supported by this platform" rather than being scraped or guessed.
• No two profiles are asserted to belong to the same person unless ownership is verified or the platform explicitly provides verification.
• Verification badges are asserted as SocialVerse verification and never imply verification by an external platform unless that platform provides it.
• Only accounts explicitly made visible by the owner appear on the public profile; visibility levels are PUBLIC, PRIVATE, and VISIBLE ONLY TO ME.
• Users can disconnect any connected account at any time; disconnection revokes the provider token and stops further synchronization for that account.
• Access tokens are managed by the platform on the user's behalf — issued, encrypted, expiry-tracked, refreshed, rotated, and revoked — and are never displayed to users or other parties.
• Raw OAuth credentials are never stored in plaintext; secrets are never committed to Git; sensitive material (access tokens, refresh tokens, passwords, private messages, private account data) is never exposed.
• Unnecessary personal search data is not stored; logs follow a defined retention policy.
• Background processing is limited to user-connected accounts and permitted API scopes, and never continuously monitors people.
• Analytics are limited to the user's own profile and never provide private-person tracking.
• Provider capabilities differ; the UI must adapt to the capability matrix rather than assume uniform provider behavior.
• Plan limits apply as specified: FREE (5 connected accounts, basic profile, QR code), PRO (unlimited permitted social links, advanced analytics, custom profile URL, custom themes, digital business card), BUSINESS (team profiles, brand pages, employee social directory, analytics, admin controls).
• Mobile starts as PWA first, with Android and iOS added later.

12. Glossary

• SocialVerse — The unified social identity platform; "One Identity. All Your Social Profiles."
• SocialVerse Identity — The user's single owned profile (avatar, name, username, bio, location, timezone) at /u/[username].
• Social Provider — A supported external platform integrated through its official API (e.g., Instagram, YouTube, GitHub).
• SocialProvider Adapter — The per-platform module implementing OAuth URL, callback, access-token management, token encryption, profile/username retrieval, profile URL, permitted avatar, display name, verification status, disconnect, rate-limit handling, error handling, and provider-specific permissions.
• Access-Token Management — The lifecycle handling of provider credentials: issuance, association with the linked social account, encrypted storage, scope and expiry tracking, refresh, rotation, cleanup of expired tokens, and revocation on disconnect or deletion.
• Capability Matrix — The stored per-provider declaration of OAuth, Profile API, Search API, Public stats, and related capabilities that drives automatic UI adaptation.
• User-Owned Account Linking — Linking a social account exclusively at the account owner's initiative.
• OAuth Verification — Proving ownership of an account through the platform's authorization flow.
• Consent-Based Profile Aggregation — Combining only data the user has authorized into one identity.
• Provider User ID — The platform's own identifier for a connected account; unique together with the provider name.
• PKCE — Proof Key for Code Exchange, applied where supported during authorization.
• Access Token / Refresh Token — Provider credentials stored only in encrypted form with expiry and scopes.
• Disconnect — The owner-initiated action that revokes provider credentials, removes the stored token, and unlinks the account; available at any time.
• Verified Badge ("✓ VERIFIED BY SOCIALVERSE") — The badge indicating SocialVerse-verified ownership, never implying external-platform verification unless provided.
• Verification Methods — OAuth verification, provider authorization, user-added URL verification where technically possible, website ownership verification, and email-domain verification for professional profiles.
• Public Profile — The shareable page at /u/[username] showing only owner-approved accounts.
• Visibility Controls — PUBLIC, PRIVATE, and VISIBLE ONLY TO ME.
• QR / Deep Link — A scannable or linkable entry point to a SocialVerse profile; supports PNG/SVG download, share, print, digital business card, vCard, and NFC-compatible URL.
• SearchProvider Interface — The abstraction exposing searchByUsername(), searchByPublicProfileURL(), and getConnectedProfile().
• Normalized Search Result — { provider, username, displayName, profileUrl, avatarUrl, bio, verified, source }.
• Privacy Dashboard — The surface for viewing stored data and performing deletion, export, hiding, and revocation actions.
• Delete My Data — The workflow: Confirm → Revoke OAuth tokens → Delete social connections → Delete profile data → Delete avatar → Delete logs per retention policy.
• Audit Log — A record of user action, resource type/id, hashed IP, hashed user agent, and timestamp.
• Capability Gap Message — "Not supported by this platform," shown instead of scraping or guessing.
• PWA — Progressive Web App, the first mobile delivery form; React Native/Expo apps follow for Android and iOS.
• Celery Worker Tasks — sync_social_profile, refresh_oauth_token, check_provider_status, update_profile_avatar, cleanup_expired_tokens, process_data_export, delete_user_data, security_monitoring.
• Plans — FREE, PRO, and BUSINESS tiers with the specified entitlements.