System Requirements Document for crab

1. Introduction

Crab is a complete Android video-sharing application whose entire promise is one warm social gesture: a user uploads a video, Crab generates a unique shareable link, and the recipient taps that link and the video simply plays. The product intent is to make sharing a video as frictionless as sending a message — no searching, no browsing, no accounts to negotiate at the moment of watching.

The audience is everyday messaging-app users on Telegram, WhatsApp, or any other messaging platform, not professional creators or media teams. The uploader needs a fast, trustworthy way to get a video off their device and into a link they can paste into a chat. The recipient needs the link to open the right video immediately, in the Crab app if it is installed, or through a web fallback page with an install/open option if it is not. The application must be a real, working Android application — not a visual mockup — structured so it can be built into an APK/AAB and eventually published on Google Play.

Crab's branding is its own: a bold, warm, character-led interface built around a custom crab mascot, saturated coral and sunflower colour blocking on a deep harbour navy ground, and chunky hand-cut shapes. It must not copy Diskwala's exact design.

2. System Overview

Crab is delivered as a native Android application (APK/AAB) backed by a modular cloud backend. The application owns the uploader's durable video library and the identity that binds it, while the backend owns cloud video storage, the metadata database, unique video IDs, video URLs, thumbnail URLs, duration, file size, and upload timestamps. Large video files are never stored permanently inside the Android application's local storage; only thumbnails are cached locally.

The current delivery covers:

• Upload and link generation. Selecting a video from the device, previewing it, uploading it to cloud storage with progress and status feedback, generating a unique video ID, storing metadata, and producing a shareable URL of the form https://crab.app/v/{VIDEO_ID}.
• Sharing. Copying the link and sharing it through Telegram, WhatsApp, or any other messaging platform, and re-sharing from the library.
• Deep-link playback. Android App Links verification for https://crab.app/v/{VIDEO_ID} so that tapping a shared link detects the URL, extracts the VIDEO_ID, finds the video, and opens the Video Player directly with playback starting — no manual search.
• Web fallback. When Crab is not installed, the link opens a web fallback page with an option to install or open Crab.
• Library management. The uploader's video library with thumbnail, title, duration, and upload date, plus Share, Delete, and Open actions.
• Playback. Streaming uploaded videos from the server with full-screen playback, play/pause, seek bar, volume, and fullscreen controls.
• Settings. App information, Privacy Policy, Terms, Clear cache, Contact, and app version.
• Monetization. Google AdMob banner ads, interstitial ads where appropriate, and optional rewarded ads, with test IDs in development and configurable production IDs.

Actors are the Video Uploader / Sharer, the Link Recipient / Viewer, and the Prospective Installer (Web Fallback Visitor). The cloud backend, the AdMob ad service, and the messaging platforms are non-persona actors.

Narrow exclusions: Crab does not store large videos permanently in local application storage; it does not copy Diskwala's exact design; it does not place ads over important video controls or create accidental ad clicks; it does not expose backend secret keys inside the Android application.

2a. Product Interpretation and Delivery Boundary

Crab's delivery is split between a first-party Android application and a first-party web fallback surface, with a modular cloud backend behind both.

The Android application owns everything the uploader does: establishing and returning to their own account, selecting and previewing a video, uploading it, receiving the generated link, copying or sharing it, browsing and managing their library, and playing videos. Because Crab owns durable per-user video libraries and uploads, the uploader's identity is application-owned: a first-use self-service enrollment and a returning verification both live on the Login surface, which is anonymously reachable so that it can establish access to the protected destinations rather than being blocked by them. Home is the public entry surface and is reachable without signing in; Upload, Video Player, My Videos, and Settings require the uploader's verified identity.

The deep-link path is deliberately different. A recipient tapping https://crab.app/v/{VIDEO_ID} from Telegram, WhatsApp, or a browser is routed by Android App Links straight into the Video Player, which is the deep-link destination and also owns the "Video unavailable" state with a button back to Home. Recipients who do not have Crab installed land on the web fallback page at the same URL, which offers to install or open Crab.

The cloud backend is provider-owned and modular: Firebase, Supabase, or another suitable backend can be connected without changing the application's product behavior. The backend owns video storage, the metadata database, unique video IDs, video URLs, thumbnail URLs, duration, file size, and upload timestamps. AdMob is an external provider surface for banner, interstitial, and optional rewarded ads.

Current boundaries are the features listed in Section 2. There are no accepted future-horizon features in this generation; anything not listed here is out of scope.

2b. Source Content Inventory

Not applicable — no reference directive in this project declares content_source.

2c. Page Content and Component Coverage

Home

• Information and state: Crab logo/wordmark; the Upload Video button; a recently uploaded videos rail with large 16:9 video thumbnails; bottom navigation. Loading state while recent videos are fetched; empty state when the uploader has no uploads yet; error state with retry when the recent-videos fetch fails.
• Primary actions: Tap Upload Video to begin an upload; tap a recent video thumbnail to open it in the Video Player.
• Supporting actions: Navigate via bottom navigation to Upload, My Videos, and Settings.
• Domain entities: Video (thumbnail, title), uploader session.
• Component responsibilities: Hero block with wordmark and Upload Video pill; recently-uploaded rail with lazy-loaded, cached thumbnails; floating bottom navigation pill with four chunky icon+label tabs and a coral active capsule.
• States: Loading (skeleton rail), empty (crab holding an empty net), success (rail populated), error (retry affordance), recovery (retry re-fetches recent videos).

Login

• Information and state: Self-service enrollment fields for a first-time uploader and returning-verification fields for an existing uploader; validation and error messaging; loading state during submission.
• Primary actions: Create an account on first use; verify an existing account on return.
• Supporting actions: Switch between enrollment and returning verification on the same cohesive surface.
• Domain entities: Uploader account, session.
• Component responsibilities: Enrollment form; returning-verification form; submit control; inline validation and error region.
• States: Loading (submitting), empty (fresh form), success (routed to Home/Upload/My Videos/Settings), error (invalid or failed submission with retry), recovery (correct and resubmit).

Upload

• Information and state: Selected video; video preview; upload progress; upload status; generated share link after upload; Copy Link button; Share button; Open Video button.
• Primary actions: Select a video from the device; preview it; upload it; copy the generated link; share the generated link; open the uploaded video.
• Supporting actions: Retry or resume a failed upload where possible.
• Domain entities: Video (file, preview, duration, file size), upload job (progress, status), share link (https://crab.app/v/{VIDEO_ID}).
• Component responsibilities: Device video picker entry; preview player; progress indicator; status label; link chip with Copy Link, Share, and Open Video controls.
• States: Loading (preparing upload), empty (no video selected), success (upload complete, link generated), error (upload failed with retry/resume), recovery (resume or restart the upload).

Video Player

• Information and state: Full-screen video playback; play/pause; seek bar; volume; fullscreen; video title; Share button; Copy link button; "Video unavailable" state with a button to return to Home.
• Primary actions: Play/pause; seek; adjust volume; enter fullscreen; share the link; copy the link.
• Supporting actions: Return to Home from the unavailable state.
• Domain entities: Video (title, stream URL), share link.
• Component responsibilities: Full-bleed player stage; transport controls; title strip; Share and Copy link controls; unavailable-state panel with Home button.
• States: Loading (buffering), empty (not applicable — a video is always the subject), success (playing), error ("Video unavailable" with Home button), recovery (return to Home and retry from a valid link).

My Videos

• Information and state: The uploader's uploaded videos with thumbnail, title, duration, and upload date; Share, Delete, and Open actions.
• Primary actions: Open a video; share a video's link again; delete a video.
• Supporting actions: Confirm deletion; recover from a failed delete.
• Domain entities: Video (thumbnail, title, duration, upload date, share link).
• Component responsibilities: Library list/masonry of thumbnail cards; per-card Share, Delete, and Open controls; delete confirmation.
• States: Loading (skeleton cards), empty (crab holding an empty net), success (library populated), error (fetch or delete failure with retry), recovery (retry fetch or delete).

Settings

• Information and state: App information; Privacy Policy; Terms; Clear cache; Contact; app version.
• Primary actions: Open Privacy Policy; open Terms; clear cache; open Contact.
• Supporting actions: Read app information and app version.
• Domain entities: Application metadata, cache.
• Component responsibilities: Settings list rows; cache-clear control with confirmation; version label.
• States: Loading (not applicable — static content), empty (not applicable), success (cache cleared confirmation), error (cache-clear failure with retry), recovery (retry clear cache).

3. Functional Requirements

Each requirement is a distinct story point with provenance, lifecycle facts, and observable acceptance.

FR-1 — Select a video from the device (explicit) As a Video Uploader / Sharer I should select a video from my device so that I can upload it to Crab.

• Trigger/input: the uploader taps Select video on the Upload screen and chooses a file from the device.
• Observable result: the selected video is loaded into the Upload screen and its preview is available.
• Access state: requires the uploader's verified identity.
• Failure/recovery: if the file cannot be read, an error state with retry is shown.
• Continuation: the uploader previews the video or proceeds to upload.

FR-2 — Preview the selected video (explicit) As a Video Uploader / Sharer I should preview the selected video before uploading so that I can confirm it is the right file.

• Trigger/input: the uploader plays the selected video in the preview player on the Upload screen.
• Observable result: the video plays in the preview player.
• Access state: requires the uploader's verified identity.
• Failure/recovery: if preview fails, an error state with retry is shown.
• Continuation: the uploader proceeds to upload or selects a different video.

FR-3 — Upload the video to cloud storage with progress and status (explicit) As a Video Uploader / Sharer I should upload the video to cloud storage with visible progress and status so that I know the upload is working.

• Trigger/input: the uploader starts the upload from the Upload screen.
• Observable result: upload progress is displayed and the upload status updates until the upload completes.
• Access state: requires the uploader's verified identity.
• Failure/recovery: on upload failure, an error state with retry/resume where possible is shown.
• Continuation: on success, the share link is generated; on failure, the uploader retries or resumes.

FR-4 — Generate a unique video ID and store metadata (explicit) As a Video Uploader / Sharer I should have a unique video ID generated and my video's metadata stored so that the video can be found and played later.

• Trigger/input: a successful upload.
• Observable result: a unique video ID is generated and the video's metadata — video metadata, unique video IDs, video URLs, thumbnail URLs, duration, file size, upload timestamp — is stored in the database.
• Access state: requires the uploader's verified identity.
• Failure/recovery: if metadata storage fails, the upload is reported as failed with retry.
• Continuation: the shareable URL is generated.

FR-5 — Generate a shareable URL (explicit) As a Video Uploader / Sharer I should receive a shareable URL of the form https://crab.app/v/{VIDEO_ID} so that I can send it to anyone.

• Trigger/input: a successful upload and metadata storage.
• Observable result: the share link https://crab.app/v/{VIDEO_ID} (for example https://crab.app/v/ABC123) is displayed on the Upload screen.
• Access state: requires the uploader's verified identity.
• Failure/recovery: if link generation fails, an error state with retry is shown.
• Continuation: the uploader copies, shares, or opens the video.

FR-6 — Copy the shareable URL (explicit) As a Video Uploader / Sharer I should copy the shareable URL so that I can paste it into any messaging platform.

• Trigger/input: the uploader taps Copy Link on the Upload screen or the Video Player.
• Observable result: the link is copied to the clipboard and a copied confirmation is shown.
• Access state: requires the uploader's verified identity.
• Failure/recovery: if copying fails, an error state with retry is shown.
• Continuation: the uploader pastes the link into Telegram, WhatsApp, or another messaging platform.

FR-7 — Share the shareable URL (explicit) As a Video Uploader / Sharer I should share the shareable URL through Telegram, WhatsApp, or any other messaging platform so that recipients can open the video.

• Trigger/input: the uploader taps Share on the Upload screen, the Video Player, or a My Videos card.
• Observable result: the platform share sheet opens with the link, and the link is sent to the chosen platform.
• Access state: requires the uploader's verified identity.
• Failure/recovery: if sharing fails or is cancelled, the uploader remains on the current screen and can retry.
• Continuation: the recipient taps the link.

FR-8 — Open shared URLs directly inside the Crab app (explicit) As a Link Recipient / Viewer I should have a shared Crab link open directly inside the Crab app so that I do not have to search for the video.

• Trigger/input: the recipient taps https://crab.app/v/{VIDEO_ID} from Telegram, WhatsApp, a browser, or any other source while Crab is installed.
• Observable result: Android App Links verification routes the URL into Crab, the app detects the URL, extracts the VIDEO_ID, finds the video, and opens the Video Player directly with playback starting.
• Access state: the deep-link entry is handled by the app; the Video Player is the deep-link destination.
• Failure/recovery: if the video does not exist, the "Video unavailable" state is displayed with a button to return to Home.
• Continuation: the recipient watches the video or returns to Home.

FR-9 — Web fallback when Crab is not installed (explicit) As a Prospective Installer (Web Fallback Visitor) I should land on a web fallback page when I open a Crab link without the app installed so that I can install or open Crab.

• Trigger/input: the visitor opens https://crab.app/v/{VIDEO_ID} on a device without Crab installed.
• Observable result: the web fallback page is displayed with an option to install or open Crab.
• Access state: anonymous web access.
• Failure/recovery: if the install/open action fails, the visitor remains on the fallback page and can retry.
• Continuation: the visitor installs or opens Crab and reaches the shared video.

FR-10 — Stream uploaded videos from the server (explicit) As a Link Recipient / Viewer I should have the video streamed from the server so that playback starts without downloading the whole file.

• Trigger/input: the Video Player opens for a video.
• Observable result: the video streams from the server and begins playing.
• Access state: the Video Player is the deep-link destination.
• Failure/recovery: on buffering or stream failure, a loading or error state with retry is shown.
• Continuation: playback continues or the recipient retries.

FR-11 — Play videos with a proper video player (explicit) As a Link Recipient / Viewer I should play videos with a proper video player so that I can watch comfortably.

• Trigger/input: the Video Player opens.
• Observable result: full-screen video playback with play/pause, seek bar, volume, and fullscreen controls, plus the video title.
• Access state: the Video Player is the deep-link destination.
• Failure/recovery: on playback failure, an error state with retry is shown.
• Continuation: the recipient watches, shares, or copies the link.

FR-12 — Show uploaded videos in the user's video library (explicit) As a Video Uploader / Sharer I should see my uploaded videos in my library so that I can manage them.

• Trigger/input: the uploader opens My Videos.
• Observable result: the library shows each uploaded video with thumbnail, title, duration, and upload date, plus Share, Delete, and Open actions.
• Access state: requires the uploader's verified identity.
• Failure/recovery: if the library fetch fails, an error state with retry is shown.
• Continuation: the uploader opens, shares, or deletes a video.

FR-13 — Delete uploaded videos (explicit) As a Video Uploader / Sharer I should delete my uploaded videos so that I can remove content I no longer want to share.

• Trigger/input: the uploader taps Delete on a My Videos card and confirms.
• Observable result: the video is removed from the library and its share link no longer resolves to a playable video.
• Access state: requires the uploader's verified identity.
• Failure/recovery: if deletion fails, an error state with retry is shown and the video remains in the library.
• Continuation: the uploader continues managing the library.

FR-14 — Share videos again (explicit) As a Video Uploader / Sharer I should share my videos again so that I can re-send a link without re-uploading.

• Trigger/input: the uploader taps Share on a My Videos card or on the Video Player.
• Observable result: the platform share sheet opens with the existing https://crab.app/v/{VIDEO_ID} link.
• Access state: requires the uploader's verified identity.
• Failure/recovery: if sharing fails or is cancelled, the uploader remains on the current screen and can retry.
• Continuation: the recipient taps the link.

FR-15 — Home screen content (explicit) As a Video Uploader / Sharer I should see the Crab logo, an Upload Video button, recently uploaded videos with thumbnails, and bottom navigation on Home so that I can start the core loop immediately.

• Trigger/input: the uploader opens Home.
• Observable result: the Crab logo, Upload Video button, recently uploaded videos with video thumbnails, and bottom navigation are displayed.
• Access state: Home is the public entry surface and is reachable without signing in.
• Failure/recovery: if recent videos fail to load, an error state with retry is shown.
• Continuation: the uploader taps Upload Video or opens a recent video.

FR-16 — Upload screen content (explicit) As a Video Uploader / Sharer I should see select video, preview video, upload progress, upload status, the generated share link after upload, and Copy Link, Share, and Open Video buttons on the Upload screen so that I can complete the upload and share it.

• Trigger/input: the uploader opens Upload.
• Observable result: all listed Upload screen elements are present and functional.
• Access state: requires the uploader's verified identity.
• Failure/recovery: error and retry states are shown for selection, preview, and upload failures.
• Continuation: the uploader copies, shares, or opens the video.

FR-17 — Video Player screen content (explicit) As a Link Recipient / Viewer I should see full-screen video playback, play/pause, seek bar, volume, fullscreen, video title, Share button, and Copy link button on the Video Player so that I can watch and re-share.

• Trigger/input: the Video Player opens.
• Observable result: all listed Video Player elements are present and functional.
• Access state: the Video Player is the deep-link destination.
• Failure/recovery: the "Video unavailable" state is shown when the video does not exist, with a button to return to Home.
• Continuation: the recipient watches, shares, or copies the link.

FR-18 — Settings screen content (explicit) As a Video Uploader / Sharer I should see app information, Privacy Policy, Terms, Clear cache, Contact, and app version on Settings so that I can manage the app.

• Trigger/input: the uploader opens Settings.
• Observable result: all listed Settings elements are present and functional.
• Access state: requires the uploader's verified identity.
• Failure/recovery: if clearing cache fails, an error state with retry is shown.
• Continuation: the uploader returns to the app.

FR-19 — Cloud backend for video storage and metadata (explicit) As a Video Uploader / Sharer I should have my video stored in cloud storage with its metadata in a database so that it can be streamed and found by link.

• Trigger/input: a successful upload.
• Observable result: the video is stored in cloud video storage and its metadata — video metadata, unique video IDs, video URLs, thumbnail URLs, duration, file size, upload timestamp — is stored in the database.
• Access state: backend access is secured and uses HTTPS.
• Failure/recovery: on backend failure, the upload is reported as failed with retry.
• Continuation: the video is available for streaming and link resolution.

FR-20 — Modular backend (explicit) As a Video Uploader / Sharer I should have the backend kept modular so that Firebase, Supabase, or another suitable backend can be connected without changing my experience.

• Trigger/input: backend configuration.
• Observable result: the backend integration points are modular and a suitable backend can be connected.
• Access state: backend access is secured and uses HTTPS.
• Failure/recovery: not applicable.
• Continuation: the application continues to work with the connected backend.

FR-21 — No permanent local storage of large videos (explicit) As a Video Uploader / Sharer I should not have large videos stored permanently inside the Android application's local storage so that my device storage is not consumed.

• Trigger/input: any upload or playback.
• Observable result: large video files are not stored permanently in local application storage; only thumbnails are cached.
• Access state: not applicable.
• Failure/recovery: not applicable.
• Continuation: the application continues to stream from the server.

FR-22 — Google AdMob integration (explicit) As a Video Uploader / Sharer I should see Google AdMob banner ads, interstitial ads where appropriate, and optional rewarded ads so that the app is monetized without disrupting my experience.

• Trigger/input: ad placements in the application.
• Observable result: banner ads, interstitial ads where appropriate, and optional rewarded ads are shown; ads are not placed over important video controls and do not create accidental ad clicks.
• Access state: not applicable.
• Failure/recovery: if an ad fails to load, the application continues without the ad.
• Continuation: the application continues normally.

FR-23 — Test and configurable AdMob IDs (explicit) As a Video Uploader / Sharer I should have test AdMob IDs used during development and production IDs configurable so that development is safe and production is correct.

• Trigger/input: build configuration.
• Observable result: test AdMob IDs are used during development and production IDs are configurable.
• Access state: not applicable.
• Failure/recovery: not applicable.
• Continuation: the application continues normally.

FR-24 — Modern, fast UI/UX (explicit) As a Video Uploader / Sharer I should experience a modern, fast video-sharing interface with clean interface, modern cards, smooth animations, dark and light mode, large video thumbnails, simple navigation, fast loading states, upload progress indicators, and error and retry states so that the app feels fast and pleasant.

• Trigger/input: any interaction with the application.
• Observable result: the listed UI/UX qualities are present throughout the application.
• Access state: not applicable.
• Failure/recovery: error and retry states are shown where applicable.
• Continuation: the user continues their task.

FR-25 — Original Crab branding (explicit) As a Video Uploader / Sharer I should see original Crab branding and interface so that the app is distinct and recognizable.

• Trigger/input: any interaction with the application.
• Observable result: the application uses its own Crab branding and original interface and does not copy Diskwala's exact design.
• Access state: not applicable.
• Failure/recovery: not applicable.
• Continuation: the user continues their task.

FR-26 — Performance optimization (explicit) As a Video Uploader / Sharer I should have the application optimized for large video files, slow internet, video buffering, upload failures, retry/resume where possible, lazy loading, thumbnail caching, and low memory usage so that the app remains usable on real networks and devices.

• Trigger/input: uploads and playback under real network and device conditions.
• Observable result: the listed performance optimizations are applied.
• Access state: not applicable.
• Failure/recovery: retry/resume where possible; error and retry states are shown.
• Continuation: the user continues their task.

FR-27 — Security (explicit) As a Video Uploader / Sharer I should have my uploads and access secured so that my content and the backend are protected.

• Trigger/input: any network or backend interaction.
• Observable result: HTTPS is used; backend secret keys are never exposed inside the Android application; video IDs are validated; backend access is secured; unauthorized access to private files is prevented; uploaded files and file types are validated; appropriate upload-size limits are enforced.
• Access state: backend access is secured and uses HTTPS.
• Failure/recovery: on validation or access failure, an error state with retry is shown.
• Continuation: the user continues their task.

FR-28 — Self-service account enrollment (required_inference) As a Video Uploader / Sharer I should be able to enroll myself on first use so that I can upload and manage my own library.

• Trigger/input: the uploader opens Login for the first time and submits enrollment information.
• Observable result: