Software Requirements Specification — App Preview

Product: App Preview (Store Listing Preview)

Version: 0.4.0

Status: Living document

Owner: fighttechvn / app_marketing

Generated from: resources/user-story/, resources/technial-design/, resources/screens/ (authored with the add-feat + add-srs skills)

---

1. Introduction

1.1 Purpose

App Preview is a local-first tool to assemble, preview, diff, and QA an App Store / Google Play listing before you ship it. This SRS captures the product's requirements, user stories, use cases, screens, data model, non-functional requirements, risks, and test traceability.

1.2 Scope

In scope: listing preview/edit for both stores, live store sync (read), Current→New diffing, ASO/character-limit audit, first-release checklist, credential test/import/export, live device mirroring, and signed desktop distribution with auto-update.
Out of scope: writing/uploading metadata or screenshots back to the stores, the user's own app build signing, payments, analytics.

1.3 Definitions

Term	Meaning
Listing	The full set of store metadata + screenshots + graphics for an app (the `DATA` object / `listing*.json`).
New / Current	The version being prepared (editable) vs the version live on the store (read-only, from Sync).
ASO	App Store Optimization — keyword/title/field tuning for store search.
Sync	Pulling the live listing from App Store Connect + Google Play.
Sidecar	The PyInstaller-bundled Python backend embedded in the desktop app.
WDA	WebDriverAgent, used to mirror/control a real iPhone.

1.4 References

README.md, docs/ (Astro Starlight, live at https://fighttechvn.github.io/app_marketing/)
resources/feature-brief.md
OpenAPI: docs/public/openapi.yaml

---

2. Overall Description

2.1 Product perspective

A multi-surface product sharing one backend and one Playground UI:

Local site (run.sh): landing + Playground + docs + /api/* on one 127.0.0.1 origin.
Static build (GitHub Pages): preview-only Playground + docs (no backend; Sync/Test inert).
Desktop app (Tauri + Python sidecar): native window hosting the Playground with full backend.

2.2 Architecture

flowchart LR
  subgraph Client
    H[home.html landing]
    P[index.html Playground]
  end
  subgraph Backend[server/ on 127.0.0.1]
    R[http_app.py router]
    S[stores.py ASC + Play]
    A[android.py adb]
    I[ios.py WDA]
    PV[preview.py]
    PR[project.py]
    CR[credentials.py]
  end
  subgraph Stores
    ASC[App Store Connect]
    GP[Google Play]
  end
  P -->|/api/*| R
  R --> S --> ASC
  S --> GP
  R --> A
  R --> I
  R --> PV
  R --> PR
  R --> CR
  Desktop[Tauri shell] -->|spawns sidecar| Backend

2.3 User classes

Indie developer / first-time publisher — needs the checklist + preview + key verification.
Release manager — needs diff + ASO + multi-locale review per update.
Designer — needs screenshot galleries + slot diff + device mirroring.
Maintainer — builds and signs the desktop app.

2.4 Operating environment

macOS (required for iOS sync, device mirroring, and desktop signing); Linux/Windows for the web tool and Android.
Python 3 backend (stdlib http.server + PyJWT, cryptography, google-api-python-client, google-auth).
Modern browser (vanilla JS, no framework). Node + Astro for building docs.

---

3. Requirements Summary

ID	Requirement	Epic	Priority
FR-01	Render a listing as an App Store and Google Play mockup, with New/Current variants and multi-locale.	EP01	Must
FR-02	Edit metadata in place, edit raw JSON, and add/auto-classify screenshots.	EP01	Must
FR-03	Sync the live listing (metadata + screenshots) from ASC + Play into Current.	EP02	Must
FR-04	Diff Current → New for text and screenshots with badges + lightbox.	EP03	Must
FR-05	Audit each field against store character limits per locale, live.	EP04	Must
FR-06	Provide a persisted first-release checklist with progress.	EP05	Should
FR-07	Test ASC + Play credentials without saving; import/export listing + self-contained `.env`.	EP06	Must
FR-08	Mirror and remote-control a connected Android device and iPhone; preview web/media/markdown.	EP07	Should
FR-09	Ship a signed/notarized desktop app (macOS/Windows) with auto-update and seeded app data.	EP08	Should

---

4. User Stories

Authoritative source files in resources/user-story/. Summary index:

Story	Title	Epic
EP01.US001	Preview a listing on both stores	EP01
EP01.US002	Switch between New and Current variants	EP01
EP01.US003	Edit metadata and assets in place	EP01
EP01.US004	View the listing per locale	EP01
EP01.US005	Dark mode and multi-language UI	EP01
EP02.US001	Sync the live App Store listing	EP02
EP02.US002	Sync the live Google Play listing	EP02
EP02.US003	See a clear sync result	EP02
EP02.US004	Keep credentials on the machine	EP02
EP03.US001	Diff metadata field-by-field	EP03
EP03.US002	Diff screenshots slot-by-slot	EP03
EP03.US003	Summarize and dismiss	EP03
EP04.US001	Audit field lengths against store limits	EP04
EP04.US002	See counts live while editing	EP04
EP04.US003	Catch empty required fields	EP04
EP05.US001	Work through a first-submission checklist	EP05
EP05.US002	Track progress	EP05
EP05.US003	Verify required assets and declarations	EP05
EP06.US001	Verify API keys without saving	EP06
EP06.US002	Import a listing or credentials	EP06
EP06.US003	Export a self-contained config	EP06
EP07.US001	Mirror and control an Android device	EP07
EP07.US002	Mirror and control an iPhone	EP07
EP07.US003	Preview web, media, and markdown	EP07
EP08.US001	Install and launch a native app	EP08
EP08.US002	Isolated, seeded app data	EP08
EP08.US003	Receive automatic updates	EP08
EP08.US004	Build and sign from source	EP08

---

5. Use Cases

UC-01 Prepare and verify a release (primary flow)

Actor: Release manager · Pre: repo cloned, server running.

Add credentials → Test keys (EP06).
Sync the Current listing (EP02).
Try template or drag screenshots + edit text to build New (EP01).
Toggle ASO checks and trim over-limit fields (EP04).
Review Diff Current → New per locale (EP03).
Run the Release checklist (EP05).
Export JSON / .env for handoff (EP06).

Post: a verified New listing ready to paste into ASC / Play Console.

UC-02 Verify credentials only

Actor: Developer. Paste .env → Test keys → per-store ✓/✗ → optionally Save .env (EP06).

UC-03 QA on a real device

Actor: Designer. Open preview panel → pick Android/iPhone → Live → tap/swipe and capture (EP07).

UC-04 Install and auto-update the desktop app

Actor: Any user. Install signed .dmg/installer → launch → File ▸ Check for Updates (EP08).

---

6. Screens / UI Surfaces

The ASCII layout documents below are injected from resources/screens/*.md by resources/srs.sh.

---

Store Listing Preview (Playground)

Source: resources/screens/ep01-store-preview-screen.md

Layout Mode: Split-panel (sticky control bar + store mockup)


┌────────────────────────────────────────────────────────────────────────┐
│ Store Listing Preview · App Store + Google Play         [☾ theme] [lang]│
├────────────────────────────────────────────────────────────────────────┤
│ [App Store][Google Play]   [New ⬆][Current]   en-US│vi│ko│…             │
│ [📁 Open][✨ Try template][⟳ Sync][Review Diff]                          │
│ [ASO checks][Edit on page][Release checklist][Edit JSON][⤓ Export][⤒ Import][Load images…] │
│ ⤵ or drag images / a folder anywhere                                     │
├────────────────────────────────────────────────────────────────────────┤
│  APP STORE MODE                          │  GOOGLE PLAY MODE             │
│  ┌────────────────────────────────────┐  │  ┌─────────────────────────┐  │
│  │ [icon] App Name            [ GET ] │  │  │ Apps ▸                  │  │
│  │        Subtitle (≤30)         [↗] │  │  │ [icon] App Title (≤30)  │  │
│  │ Free · iPhone & iPad               │  │  │ Developer · ★ · 50K+    │  │
│  ├────────────────────────────────────┤  │  │ [ Install ]             │  │
│  │ ★★★★★ │ 4+ │ #1 │ Dev │ EN │ v1.4 │  │  ├─────────────────────────┤  │
│  ├────────────────────────────────────┤  │  │ [Phone (5)][Tablet (2)] │  │
│  │ iPhone  ▸ [▢ ▢ ▢ ▢] scroll ...    │  │  │ [▸ screenshots] ...     │  │
│  │ iPad    ▸ [▢ ▢ ▢] ...              │  │  │ About this app …        │  │
│  │ Promotional text (≤170)            │  │  │ What's new …            │  │
│  │ Description (≤4000) …              │  │  │ ┌ App icon ┐ ┌ Feature ┐ │  │
│  │ What's New (v1.4) …               │  │  │ │ Uploaded │ │ 1024×500 │ │  │
│  │ Keywords: [chip][chip][chip]       │  │  │ Package · short desc    │  │
│  └────────────────────────────────────┘  │  └─────────────────────────┘  │
└────────────────────────────────────────────────────────────────────────┘

Components

Store toggle: switches App Store ↔ Google Play layout.
Variant toggle: New (editable) ↔ Current (read-only/locked).
Locale buttons: generated from DATA.locales; switch all copy + screenshots.
Action bar: Open folder, Try template, Sync, Review Diff, ASO checks, Edit on page, Release checklist, Edit JSON, Export, Import, Load images.
Screenshot galleries: iphone/ipad (App Store), phone/tablet sub-tabs (Play).
Graphics block (Play): app icon + feature graphic with status pills.

States

Initial: empty placeholder listing, no overflow.
Loaded: listing.json rendered.
Editing: dashed outlines on contenteditable fields; live counters.
Current: locked; drag-drop shows "Current is locked".

Events

StoreToggle → re-render mockup.
VariantToggle → swap New/Current; lock when Current.
LocaleSelect → re-render copy/screenshots/ASO.
EditOnPage → enable contenteditable.
DropImages → classify by name → aspect ratio → assign gallery.

SRS Export

resources/srs.sh renders this document inside Screens / UI Surfaces.

Review Diff (Current → New)

Source: resources/screens/ep03-review-diff-screen.md


┌──────────────────────────────────────────────────────────────┐
│ Review changes — Current → New                          [✕]  │
├──────────────────────────────────────────────────────────────┤
│ [ Text & metadata ] [ Screenshots ]                          │
├──────────────────────────────────────────────────────────────┤
│  ── App ───────────────────────────────────────────────────  │
│  name            [CHG]  ~~Old name~~   →   New name           │
│  subtitle        [ADD]                 →   New subtitle       │
│  ── en-US ─────────────────────────────────────────────────  │
│  keywords        [CHG]  ~~old,kw~~     →   new,kw             │
│                                                              │
│  (Screenshots tab)                                           │
│  iPhone   Current 3 → New 4                                  │
│   #1 [▢ cur] → [▢ new] [CHG]   #4 [ — ] → [▢ new] [ADD]      │
├──────────────────────────────────────────────────────────────┤
│ 4 text field(s) · 2 screenshot change(s) · Current → New     │
│                                   [ Close ] [ Looks good ✓ ]  │
└──────────────────────────────────────────────────────────────┘

Components

Tab bar: Text & metadata | Screenshots.
Text rows: field name + CHG/ADD/REM badge, old (red strikethrough) → new (green).
Screenshot rows: per gallery, slot-aligned Current → New thumbnails with badges.
Fullscreen lightbox: click a thumbnail to zoom (Esc / backdrop closes).
Footer: change summary + Close / Looks good.

States

No Current synced: all New screenshots show ADD.
Mixed: CHG / ADD / REM badges per row.

Events

TabSwitch → show text or screenshot pane.
ThumbClick → open lightbox.
Close / LooksGood → dismiss modal.

SRS Export

resources/srs.sh renders this document inside Screens / UI Surfaces.

Store SEO / ASO Audit Panel

Source: resources/screens/ep04-aso-audit-screen.md

Layout Mode: Side panel (toggle)


┌───────────────────────────────────────────────┐
│ ASO checks · App Store · en-US           [✕]  │
├───────────────────────────────────────────────┤
│ name              "PulseFit: Habit Coach"  21/30 ✓│
│ subtitle          "Workouts, habits …"     28/30 ✓│
│ keywords          "fitness,workout,…"     104/100 ✗│
│ promotionalText   "Build daily habits…"    96/170 ✓│
│ description        …                      812/4000 ✓│
│ whatsNew           …                      140/4000 ✓│
│ Bundle ID         `com.demo.pulsefit`             │
├───────────────────────────────────────────────┤
│ (Google Play)                                  │
│ title             "PulseFit: Habit Coach"  21/30 ✓│
│ shortDescription  "Guided workouts…"       58/80 ✓│
│ fullDescription    …                      900/4000 ✓│
│ changelog          …                      120/500 ✓│
│ Package           `com.demo.pulsefit`             │
└───────────────────────────────────────────────┘

Components

Per-field row: label, value preview, count badge (used/limit).
Green badge ≤ limit; red badge > limit; empty-required flag.
Reference codes: bundle id (iOS) / package (Android).

States

Within limits: all green.
Over limit: red badge on the offending field.
Empty required: distinct flag.

Events

ToggleAso → show/hide panel.
FieldEdit → updateAso() re-render badges live.
LocaleSwitch / StoreSwitch → re-audit.

SRS Export

resources/srs.sh renders this document inside Screens / UI Surfaces.

First-Release Checklist

Source: resources/screens/ep05-release-checklist-screen.md


┌──────────────────────────────────────────────────────────────┐
│ First-release checklist                  [Reset]        [✕]  │
│ ████████████████░░░░░░░░░░░░  62%                            │
│ Tags: [WEB UI]=console  [API]=scriptable  [DECLARATION]=true │
├──────────────────────────────────────────────────────────────┤
│ ▸ Accounts & signing                                        │
│   [x] Apple Developer Program active            [WEB UI]     │
│   [x] App Store Connect API key (.p8 path)      [API]        │
│   [ ] Google Play service account (Release Mgr) [API]        │
│ ▸ App records (one-time)                                     │
│   [x] ASC app record created                                │
│ ▸ Listing content                                           │
│   [ ] iOS screenshots 6.9"/6.7", iPad 12.9"     [WEB UI]     │
│   [x] Icon 1024/512 no alpha · feature 1024×500             │
│ ▸ Build · ▸ Version requirements · ▸ Submit                  │
│ ▸ Known first-submission rejections                         │
└──────────────────────────────────────────────────────────────┘

Components

Progress bar: live percent of checked items.
Groups: Accounts & signing, App records, Listing content, Build, App Store version requirements, Submit, Known rejections.
Item: checkbox + label + tag (WEB UI / API / DECLARATION).
Reset: clears all + localStorage.

States

Restored: checkbox state from store-release-checklist-v1.
In progress: percent < 100.
Complete: percent = 100.

Events

ToggleItem → recompute percent → persist.
Reset → clear all + storage.

SRS Export

resources/srs.sh renders this document inside Screens / UI Surfaces.

Credentials Import / Export

Source: resources/screens/ep06-credentials-screen.md


┌──────────────────────────────────────────────────────────────┐
│ Export config                                          [✕]   │
├──────────────────────────────────────────────────────────────┤
│ [ Listing JSON ] [ Env · Sync API ]                          │
├──────────────────────────────────────────────────────────────┤
│ ⚠️ CONTAINS REAL CREDENTIALS — keep private                  │
│ ┌──────────────────────────────────────────────────────────┐ │
│ │ ASC_KEY_ID=...                                           │ │
│ │ ASC_ISSUER_ID=...                                        │ │
│ │ ASC_KEY_P8_B64=...                                       │ │
│ │ BUNDLE_ID=...                                            │ │
│ │ PLAYSTORE_PACKAGE_NAME=...                               │ │
│ │ PLAYSTORE_SERVICE_ACCOUNT_JSON_B64=...                   │ │
│ └──────────────────────────────────────────────────────────┘ │
│              [ 💾 Save .env ]  [ 🔌 Test keys ]              │
├──────────────────────────────────────────────────────────────┤
│ Test result:  ✓ App Store Connect: app found                 │
│               ✓ Google Play: sa@project.iam … edit ok        │
└──────────────────────────────────────────────────────────────┘

Components

Tabs: Listing JSON (copy / save .json) · Env · Sync API.
Env textarea: editable on Import, read-only export shows current server env.
Buttons: Save .env (POST /api/env), Test keys (POST /api/test), Copy, Choose file, Load → Current.
Result area: per-store ✓ (green) / ✗ (red) + detail.

States

Export: prefilled from GET /api/env (sync keys only, base64-inlined).
Import: paste/pick; Save refuses overwrite unless ?force=1.
Tested: per-store ok/detail rendered.

Events

TestKeys → POST /api/test → render results.
SaveEnv → POST /api/env.
LoadToCurrent → set parsed JSON as read-only Current.

SRS Export

resources/srs.sh renders this document inside Screens / UI Surfaces.

Device Mirror & Preview Panel

Source: resources/screens/ep07-device-mirror-screen.md

Layout Mode: Right-side rail + slide-out panel


┌──────────────────────────────────────────────┬────┐
│  Preview panel (resizable, ≥320px)      [↗][✕]│ ▐  │
│ ┌──────────────────────────────────────────┐ │ 📱 │
│ │ Android ▾  [⟳][▶ Live][⚡ scrcpy]         │ │ 🍎 │
│ │ ┌──────────────────────────────────────┐ │ │    │
│ │ │                                      │ │ │ ✕  │
│ │ │      [ live device screen ]          │ │ │    │
│ │ │       tap ● swipe ╱                   │ │ └────┘
│ │ └──────────────────────────────────────┘ │ │
│ │ [▭ Recents][○ Home][◁ Back][🔉][🔊][⏻]   │ │
│ │ [ type text… ] [Send][⏎][⌫]              │ │
│ │ connected · 12.5 fps                      │ │
│ └──────────────────────────────────────────┘ │
│ Tabs also: 🍎 iPhone (WDA MJPEG) · Web · Media · Markdown │
└──────────────────────────────────────────────┴────┘

Components

Rail: 📱 Android · 🍎 iPhone · Web · Media · Markdown · ✕ close.
Device selector + Refresh/Scan; Live toggle; scrcpy (Android) / Start WDA (iOS).
Mirror area: screencap/MJPEG with tap ripple + swipe trail; FPS readout.
Navigator buttons + text input.
Media/Markdown tabs render local files via /api/preview-file.

States

Scanning: "scanning…" until devices resolve.
Connected: model + fps / resolution shown.
Tool missing: "adb missing" / "WDA not running" / setup helper.

Events

Refresh/Scan → list devices.
Live → start screencap poll / MJPEG stream.
TapMirror → POST input (tap/swipe) with feedback.
NavButton / SendText → key/button/text event.

SRS Export

resources/srs.sh renders this document inside Screens / UI Surfaces.

7. Data Model

erDiagram
  LISTING ||--|| APP : has
  LISTING ||--o{ LOCALE_ENTRY : contains
  LISTING ||--o{ SCREENSHOT : contains
  LISTING ||--|| GRAPHICS : has
  LISTING ||--|| LIMITS : has
  APP {
    string name
    string iosBundleId
    string androidPackage
    string versionName
    string developer
    string defaultLocale
  }
  LOCALE_ENTRY {
    string displayName
    string appstore_name
    string appstore_subtitle
    string appstore_keywords
    string googleplay_title
    string fullDescription
    string whatsNew
  }
  SCREENSHOT {
    string gallery
    string file
    string label
    string size
  }
  GRAPHICS {
    string appIcon_file
    string featureGraphic_file
  }
  LIMITS {
    int appstore_name
    int googleplay_shortDescription
  }

Field-length limits (DATA.limits):

Store	Field	Limit
App Store	name	30
App Store	subtitle	30
App Store	keywords	100
App Store	promotionalText	170
App Store	description	4000
App Store	whatsNew	4000
Google Play	title	30
Google Play	shortDescription	80
Google Play	fullDescription	4000
Google Play	changelog	500

Persisted artifacts: listing.json (New), listing-current.json (Current), listing-template.json (demo), assets/{template,new,current}/, .env.

---

8. External Interfaces (API)

Backend on 127.0.0.1 (from server/http_app.py):

Method	Endpoint	Purpose	Epic
GET	`/api/sync`	Pull live ASC + Play listing → `listing-current.json`	EP02
GET	`/api/scan`	Scan project folder (creds/assets/listings)	EP01
POST	`/api/open`	Switch active project folder	EP01
POST	`/api/apply-template`	Copy demo assets → New	EP01
GET	`/api/env`	Export sync-only `.env` (base64-inlined)	EP06
POST	`/api/env`	Save imported `.env` (first-time / `?force=1`)	EP06
POST	`/api/test`	Verify ASC + Play creds (no save)	EP06
GET	`/api/adb/devices`	List Android devices	EP07
GET	`/api/adb/screen`	Android screencap (PNG)	EP07
POST	`/api/adb/input`	Android tap/swipe/text/key	EP07
POST	`/api/adb/scrcpy`	Launch native scrcpy	EP07
GET	`/api/wda/devices`	List iOS devices	EP07
GET	`/api/wda/status`	WDA status	EP07
GET	`/api/wda/screen`	iOS screenshot (PNG)	EP07
GET	`/api/wda/mjpeg`	iOS MJPEG stream	EP07
POST	`/api/wda/input`	iOS tap/swipe/text/button/lock	EP07
POST	`/api/wda/launch`	Launch WDA via xcodebuild	EP07
GET	`/api/preview-file`	Serve local media/markdown	EP07

---

9. Non-Functional Requirements

ID	Category	Requirement
NFR-01	Security	Backend binds `127.0.0.1` only; credentials never leave the device; only `SYNC_KEYS` are exportable (no signing/Firebase secrets).
NFR-02	Privacy	`/api/test` never persists; `/api/env` POST refuses to overwrite without `?force=1`; `.env`, `assets/new`, `assets/current` are gitignored.
NFR-03	Usability	Preview works offline with no keys; dark theme + 5-language landing (en/vi/ko/ar-RTL/ja); no flash of wrong theme.
NFR-04	Performance	Inline edits update without full re-render (caret preserved); screenshots lazy-load; device mirror reports FPS; MJPEG with polling fallback.
NFR-05	Portability	Single-file frontend, stdlib-based backend, PyInstaller sidecar; desktop on macOS + Windows.
NFR-06	Reliability	Missing external tools (adb/scrcpy/iproxy/xcodebuild) and missing creds degrade gracefully with readable status.
NFR-07	Distribution	Desktop artifacts are signed + notarized and auto-update via a cryptographically verified `latest.json`.
NFR-08	Maintainability	Backend split by concern under `server/`; docs in Astro; demo assets regenerable via `gen-dummy.mjs`.

---

10. Risks

Risk	Impact	Mitigation
ASC JWT / key misconfig	Sync fails	`/api/test` dry-run before save; readable error details.
Play edit session left open	Stuck edits	Test + sync always delete the edit session.
Credential leakage via export	Secret exposure	Export limited to `SYNC_KEYS`; explicit "keep private" warning; localhost-only.
iOS mirroring setup complexity	Feature unusable	One-click WDA launch + setup helper with go-ios commands.
Static Pages build has no backend	Sync/Test appear broken	Docs state preview-only; full tool requires `run.sh`/desktop.
Desktop update signature mismatch	Failed/blocked update	Tauri updater verifies signature before install.

---

11. Traceability

Requirement	Epic	User stories	Technical design	Screen	Verification
FR-01	EP01	US001–US002,004,005	`technial-design/ep01-store-preview.md`	`screens/ep01-store-preview-screen.md`	`./run.sh` → toggle stores/variants/locales
FR-02	EP01	US003	ep01	ep01 screen	drag images, edit fields, Download listing.json
FR-03	EP02	US001–US004	ep02	ep01 screen (⟳ Sync)	`curl /api/sync`
FR-04	EP03	US001–US003	ep03	ep03 screen	Review Diff after Sync + edit
FR-05	EP04	US001–US003	ep04	ep04 screen	toggle ASO, type past a limit
FR-06	EP05	US001–US003	ep05	ep05 screen	tick items, reload (persistence)
FR-07	EP06	US001–US003	ep06	ep06 screen	`curl /api/test`, `/api/env`
FR-08	EP07	US001–US003	ep07	ep07 screen	`curl /api/adb/devices`, `/api/wda/devices`
FR-09	EP08	US001–US004	ep08	(native frame of ep01)	`./run_desktop.sh`, `./appdist.sh`

---

12. Build & Run


# Local full site (landing + playground + docs + /api/*)
./run.sh
./run.sh --build      # force-rebuild docs

# Backend only
python3 serve.py 8092

# Desktop app
cd desktop && bash scripts/setup-prereqs.sh && ./run_desktop.sh

# Regenerate this SRS
./resources/srs.sh

Screen Flow

Each screen shows its real layout; arrows are the navigation events that move between screens.

First-Release Checklist

┌──────────────────────────────────────────────────────────────┐
│ First-release checklist                  [Reset]        [✕]  │
│ ████████████████░░░░░░░░░░░░  62%                            │
│ Tags: [WEB UI]=console  [API]=scriptable  [DECLARATION]=true │
├──────────────────────────────────────────────────────────────┤
│ ▸ Accounts & signing                                        │
│   [x] Apple Developer Program active            [WEB UI]     │
│   [x] App Store Connect API key (.p8 path)      [API]        │
│   [ ] Google Play service account (Release Mgr) [API]        │
│ ▸ App records (one-time)                                     │
│   [x] ASC app record created                                │
│ ▸ Listing content                                           │
│   [ ] iOS screenshots 6.9"/6.7", iPad 12.9"     [WEB UI]     │
│   [x] Icon 1024/512 no alpha · feature 1024×500             │
│ ▸ Build · ▸ Version requirements · ▸ Submit                  │
│ ▸ Known first-submission rejections                         │
└──────────────────────────────────────────────────────────────┘

···

Store Listing Preview (Playground)

┌────────────────────────────────────────────────────────────────────────┐
│ Store Listing Preview · App Store + Google Play         [☾ theme] [lang]│
├────────────────────────────────────────────────────────────────────────┤
│ [App Store][Google Play]   [New ⬆][Current]   en-US│vi│ko│…             │
│ [📁 Open][✨ Try template][⟳ Sync][Review Diff]                          │
│ [ASO checks][Edit on page][Release checklist][Edit JSON][⤓ Export][⤒ Import][Load images…] │
│ ⤵ or drag images / a folder anywhere                                     │
├────────────────────────────────────────────────────────────────────────┤
│  APP STORE MODE                          │  GOOGLE PLAY MODE             │
│  ┌────────────────────────────────────┐  │  ┌─────────────────────────┐  │
│  │ [icon] App Name            [ GET ] │  │  │ Apps ▸                  │  │
│  │        Subtitle (≤30)         [↗] │  │  │ [icon] App Title (≤30)  │  │
│  │ Free · iPhone & iPad               │  │  │ Developer · ★ · 50K+    │  │
│  ├────────────────────────────────────┤  │  │ [ Install ]             │  │
│  │ ★★★★★ │ 4+ │ #1 │ Dev │ EN │ v1.4 │  │  ├─────────────────────────┤  │
│  ├────────────────────────────────────┤  │  │ [Phone (5)][Tablet (2)] │  │
│  │ iPhone  ▸ [▢ ▢ ▢ ▢] scroll ...    │  │  │ [▸ screenshots] ...     │  │
│  │ iPad    ▸ [▢ ▢ ▢] ...              │  │  │ About this app …        │  │
│  │ Promotional text (≤170)            │  │  │ What's new …            │  │
│  │ Description (≤4000) …              │  │  │ ┌ App icon ┐ ┌ Feature ┐ │  │
│  │ What's New (v1.4) …               │  │  │ │ Uploaded │ │ 1024×500 │ │  │
│  │ Keywords: [chip][chip][chip]       │  │  │ Package · short desc    │  │
│  └────────────────────────────────────┘  │  └─────────────────────────┘  │
└────────────────────────────────────────────────────────────────────────┘

VariantToggle→

Review Diff (Current → New)

┌──────────────────────────────────────────────────────────────┐
│ Review changes — Current → New                          [✕]  │
├──────────────────────────────────────────────────────────────┤
│ [ Text & metadata ] [ Screenshots ]                          │
├──────────────────────────────────────────────────────────────┤
│  ── App ───────────────────────────────────────────────────  │
│  name            [CHG]  ~~Old name~~   →   New name           │
│  subtitle        [ADD]                 →   New subtitle       │
│  ── en-US ─────────────────────────────────────────────────  │
│  keywords        [CHG]  ~~old,kw~~     →   new,kw             │
│                                                              │
│  (Screenshots tab)                                           │
│  iPhone   Current 3 → New 4                                  │
│   #1 [▢ cur] → [▢ new] [CHG]   #4 [ — ] → [▢ new] [ADD]      │
├──────────────────────────────────────────────────────────────┤
│ 4 text field(s) · 2 screenshot change(s) · Current → New     │
│                                   [ Close ] [ Looks good ✓ ]  │
└──────────────────────────────────────────────────────────────┘

←LoadToCurrent

Credentials Import / Export

┌──────────────────────────────────────────────────────────────┐
│ Export config                                          [✕]   │
├──────────────────────────────────────────────────────────────┤
│ [ Listing JSON ] [ Env · Sync API ]                          │
├──────────────────────────────────────────────────────────────┤
│ ⚠️ CONTAINS REAL CREDENTIALS — keep private                  │
│ ┌──────────────────────────────────────────────────────────┐ │
│ │ ASC_KEY_ID=...                                           │ │
│ │ ASC_ISSUER_ID=...                                        │ │
│ │ ASC_KEY_P8_B64=...                                       │ │
│ │ BUNDLE_ID=...                                            │ │
│ │ PLAYSTORE_PACKAGE_NAME=...                               │ │
│ │ PLAYSTORE_SERVICE_ACCOUNT_JSON_B64=...                   │ │
│ └──────────────────────────────────────────────────────────┘ │
│              [ 💾 Save .env ]  [ 🔌 Test keys ]              │
├──────────────────────────────────────────────────────────────┤
│ Test result:  ✓ App Store Connect: app found                 │
│               ✓ Google Play: sa@project.iam … edit ok        │
└──────────────────────────────────────────────────────────────┘

···

Store SEO / ASO Audit Panel

┌───────────────────────────────────────────────┐
│ ASO checks · App Store · en-US           [✕]  │
├───────────────────────────────────────────────┤
│ name              "PulseFit: Habit Coach"  21/30 ✓│
│ subtitle          "Workouts, habits …"     28/30 ✓│
│ keywords          "fitness,workout,…"     104/100 ✗│
│ promotionalText   "Build daily habits…"    96/170 ✓│
│ description        …                      812/4000 ✓│
│ whatsNew           …                      140/4000 ✓│
│ Bundle ID         `com.demo.pulsefit`             │
├───────────────────────────────────────────────┤
│ (Google Play)                                  │
│ title             "PulseFit: Habit Coach"  21/30 ✓│
│ shortDescription  "Guided workouts…"       58/80 ✓│
│ fullDescription    …                      900/4000 ✓│
│ changelog          …                      120/500 ✓│
│ Package           `com.demo.pulsefit`             │
└───────────────────────────────────────────────┘

ToggleAso→

Device Mirror & Preview Panel

┌──────────────────────────────────────────────┬────┐
│  Preview panel (resizable, ≥320px)      [↗][✕]│ ▐  │
│ ┌──────────────────────────────────────────┐ │ 📱 │
│ │ Android ▾  [⟳][▶ Live][⚡ scrcpy]         │ │ 🍎 │
│ │ ┌──────────────────────────────────────┐ │ │    │
│ │ │                                      │ │ │ ✕  │
│ │ │      [ live device screen ]          │ │ │    │
│ │ │       tap ● swipe ╱                   │ │ └────┘
│ │ └──────────────────────────────────────┘ │ │
│ │ [▭ Recents][○ Home][◁ Back][🔉][🔊][⏻]   │ │
│ │ [ type text… ] [Send][⏎][⌫]              │ │
│ │ connected · 12.5 fps                      │ │
│ └──────────────────────────────────────────┘ │
│ Tabs also: 🍎 iPhone (WDA MJPEG) · Web · Media · Markdown │
└──────────────────────────────────────────────┴────┘

→ Event navigates to the next screen ← Event navigates back

Feature Board

User stories across the sprint board. Click a card to see its full description and tasks.

Backlog 0

To Do (Sprint) 0

In Progress 0

In Review 0

Done 0

EP01.US001EP01: Store Listing PreviewDone

Preview a listing on both stores

4 tasks

As a developer, I want to see my listing rendered as a realistic App Store and Google Play mockup so that I know how it will look before I submit.

✓A store toggle switches between **App Store** (iOS) and **Google Play** (Android) layouts.
✓App Store view shows: app icon, name (≤30), subtitle (≤30), GET button, metadata row (rating/age/category/developer/language/version), iPhone + iPad screenshot galleries, promotional text, description, what's new, keyword chips.
✓Google Play view shows: icon, title (≤30), developer, rating/downloads/age, Install button, phone + tablet screenshot sub-tabs, full description, what's new, app icon + feature graphic block, package id, short description.
✓Empty/placeholder state renders without overflow when no listing is loaded.

EP01.US002EP01: Store Listing PreviewDone

Switch between New and Current variants

4 tasks

As a release manager, I want to flip between the **New** version I'm preparing and the **Current** version live on the store so that I always know which one I'm looking at.

✓A variant toggle offers **New ⬆** and **Current**.
✓**Current** is read-only; attempting drag-drop shows a "Current is locked" message.
✓**New** is editable (text + screenshots).
✓The active variant label is visible in the control bar.

EP01.US003EP01: Store Listing PreviewDone

Edit metadata and assets in place

5 tasks

As a developer, I want to edit text and swap screenshots directly on the preview so that I can iterate quickly.

✓"Edit on page" enables contenteditable fields with dashed outlines; edits update the in-memory listing without losing caret position.
✓Character counters turn red when a field exceeds its store limit (live).
✓"Edit JSON" exposes the raw listing.json with Apply / Format / Download / Reset.
✓Images can be added via "Load images…", drag-and-drop (whole page or per slot), or a directory pick; they auto-classify into iphone/ipad/phone/tablet/icon/feature-graphic by filename hint then aspect ratio.
✓A toast confirms how many images landed in each gallery.

EP01.US004EP01: Store Listing PreviewDone

View the listing per locale

3 tasks

As a publisher with localized listings, I want to switch locale so that I can review each market's metadata and screenshots.

✓Locale buttons are generated from the listing's locales.
✓Switching locale updates all text, ASO counts, and (where present) screenshots live.
✓The selected locale persists across reloads.

EP01.US005EP01: Store Listing PreviewDone

Use the tool in dark mode and multiple UI languages

3 tasks

As a user, I want a dark theme and a localized UI so that the tool fits my environment.

✓Theme toggle (light/dark) persists to localStorage.
✓Landing page UI is translatable to en, vi, ko, ar (RTL), ja.
✓No flash of the wrong theme on load.

EP02.US001EP02: Store SyncDone

Sync the live App Store listing

4 tasks

As a developer, I want to pull my current App Store listing so that I can diff and preview against what users see today.

✓⟳ Sync authenticates to App Store Connect with a JWT minted from ASC_KEY_ID / ASC_ISSUER_ID / the .p8 key (ES256, ~1100 s expiry).
✓The app is resolved by BUNDLE_ID; the latest appStoreVersion and per-locale appStoreVersionLocalization fields (name, subtitle, keywords, promotionalText, description, whatsNew) are fetched.
✓iPhone (APP_IPHONE_67) and iPad (APP_IPAD_PRO_3GEN_129) screenshots are downloaded to assets/current/ and labeled with their original dimensions.
✓Results are written to listing-current.json.

EP02.US002EP02: Store SyncDone

Sync the live Google Play listing

4 tasks

As a developer, I want to pull my current Play listing so that the Current variant reflects production.

✓Sync authenticates with the Play service account JSON over the androidpublisher scope and opens an edit session.
✓All listings languages are fetched (title, shortDescription, fullDescription).
✓phoneScreenshots for en-US are downloaded to assets/current/.
✓The edit session is discarded (read-only; no store changes).

EP02.US003EP02: Store SyncDone

See a clear sync result

3 tasks

As a user, I want feedback after syncing so that I know what was loaded.

✓A toast reports counts, e.g. "Synced — App Store iPhone 3 / iPad 2, Play phone 5 (v1.4.0)".
✓GET /api/sync returns {ok, appstore:{iphone,ipad}, googleplay:{phone}, locales[], versionName}.
✓Missing/invalid credentials produce a readable error, not a crash; preview-only use (no keys) still works.

EP02.US004EP02: Store SyncDone

Keep credentials on the machine

2 tasks

As a security-conscious user, I want sync to run locally so that my keys never leave my device.

✓The server binds 127.0.0.1 only.
✓Credentials load from {project}/.env and optionally {APP_DIST}/.env.prod; nothing is uploaded to a third party.

EP03.US001EP03: Review DiffDone

Diff metadata field-by-field

4 tasks

As a release manager, I want a per-field text diff so that I can confirm exactly what is changing in this update.

✓"Review Diff" opens a modal titled "Review changes — Current → New".
✓The **Text & metadata** tab groups changes by section (App, then each locale).
✓Each changed field shows the old value (red strikethrough) and new value (green) with a CHG / ADD / REM badge.
✓Unchanged fields are not noise.

EP03.US002EP03: Review DiffDone

Diff screenshots slot-by-slot

3 tasks

As a designer, I want to compare screenshots per slot so that I can spot accidental swaps, additions, or removals.

✓The **Screenshots** tab lists each gallery (iPhone, iPad, phone, tablet) with "Current N → New M".
✓Each slot shows Current (left) and New (right) thumbnails with CHG / ADD / REM badges; missing slots show a "—" placeholder.
✓Clicking a thumbnail opens a fullscreen lightbox (≤95vw × 90vh) captioned e.g. "New · #2 — iPhone"; Esc or backdrop closes it.

EP03.US003EP03: Review DiffDone

Summarize and dismiss

3 tasks

As a user, I want a summary and a clean exit so that I can close the review with confidence.

✓The footer summarizes "X text field(s) · Y screenshot change(s) · Current → New".
✓"Looks good ✓" and "Close" both dismiss the modal.
✓If Current was never synced, the diff treats all New screenshots as additions (and says so implicitly via ADD badges).

EP04.US001EP04: Store SEO / ASO AuditDone

Audit field lengths against store limits

4 tasks

As a developer, I want each metadata field checked against its store's character limit so that I never submit an over-length field.

✓Toggling "ASO checks" shows a per-field audit for the active store and locale.
✓App Store fields and limits: name 30, subtitle 30, keywords 100, promotionalText 170, description 4000, whatsNew 4000.
✓Google Play fields and limits: title 30, shortDescription 80, fullDescription 4000, changelog 500.
✓Each field shows a count badge: green within limit, red over limit.

EP04.US002EP04: Store SEO / ASO AuditDone

See counts live while editing

2 tasks

As an editor, I want counters to update as I type so that I can trim copy in real time.

✓Inline editing updates the ASO badges immediately (the ASO panel re-renders without a full page re-render).
✓Bundle id (iOS) and package name (Android) are shown in code format for reference.

EP04.US003EP04: Store SEO / ASO AuditDone

Catch empty required fields

2 tasks

As a publisher, I want empty required fields flagged so that I don't ship an incomplete listing.

✓Empty fields are visibly distinguishable from filled ones.
✓The audit is locale-aware: switching locale re-audits that locale's values.

EP05.US001EP05: First-Release ChecklistDone

Work through a first-submission checklist

3 tasks

As a first-time publisher, I want a guided checklist so that I don't miss anything that would cause a rejection.

✓"Release checklist" opens a full-screen modal grouped into sections: Accounts & signing, App records, Listing content, Build, App Store version requirements, Submit, and Known first-submission rejections.
✓Each item is a checkbox with explanatory text.
✓Items are tagged WEB UI (console-only), API (scriptable), or DECLARATION (must not be fabricated).

EP05.US002EP05: First-Release ChecklistDone

Track progress

3 tasks

As a user, I want to see how far along I am so that I know what's left.

✓A progress bar shows percent complete and updates live as items are checked.
✓Checkbox state persists in localStorage (store-release-checklist-v1).
✓A Reset clears all items and the stored state.

EP05.US003EP05: First-Release ChecklistDone

Verify required assets and declarations

3 tasks

As a publisher, I want the checklist to enumerate concrete required assets so that I can confirm each one.

✓Listing content section enumerates required screenshot sizes (iPhone 6.9"/6.7", iPad 12.9", Android phone), no-alpha icon rules, and per-locale metadata.
✓App Store version section covers copyright, content rights, age rating, app privacy, pricing, and export compliance.
✓Submit section covers iOS review submission state and Android production promotion.

EP06.US001EP06: Credentials, Import/Export & Key VerificationDone

Verify API keys without saving

4 tasks

As a developer, I want to test my App Store Connect and Google Play credentials so that I know they work before I rely on them.

✓"Test keys" POSTs the pasted .env to /api/test; nothing is written to disk.
✓App Store test mints a JWT and calls /v1/apps?filter[bundleId]=…; result reports ok + detail.
✓Google Play test authenticates the service account and opens then deletes a throwaway edit; result reports ok + the service-account email.
✓Each store shows ✓ (green) or ✗ (red) with a readable detail message.

EP06.US002EP06: Credentials, Import/Export & Key VerificationDone

Import a listing or credentials

3 tasks

As a user, I want to import a listing JSON or .env so that I can load a config from elsewhere.

✓Import offers two tabs: Listing JSON and Env · Sync API.
✓Listing JSON: paste or pick a .json file → "Load → Current" sets it as the read-only Current variant.
✓Env: paste or pick a file → "Save .env to local" POSTs to /api/env; by default it does not overwrite an existing .env (requires ?force=1).

EP06.US003EP06: Credentials, Import/Export & Key VerificationDone

Export a self-contained config

4 tasks

As a user, I want to export my listing and a self-contained .env so that I can hand off or back up my setup.

✓Export offers Listing JSON (copy / save .json) and Env · Sync API.
✓The exported .env includes only SYNC keys (ASC_KEY_ID, ASC_ISSUER_ID, ASC_KEY_P8 → _B64, BUNDLE_ID, PLAYSTORE_PACKAGE_NAME, PLAYSTORE_SERVICE_ACCOUNT_JSON → _B64); signing/Firebase secrets are never exported.
✓File-path credentials are base64-inlined so the .env is self-contained (no side files).
✓The export warns that it contains real credentials and must be kept private.

EP07.US001EP07: Device Mirror & Remote ControlDone

Mirror and control an Android device

5 tasks

As a developer, I want to see and drive a connected Android phone so that I can capture or QA screens without leaving the tool.

✓The Android tab lists devices via GET /api/adb/devices (serial, state, model, scrcpy availability).
✓"Live" polls GET /api/adb/screen?serial=… for a screencap stream with an FPS readout.
✓Tapping/swiping the mirror sends POST /api/adb/input (tap/swipe/text/key) with on-image touch feedback.
✓Navigator buttons (Recents/Home/Back/Vol/Power) and a text input send key/text events.
✓"scrcpy" launches a native high-FPS window via POST /api/adb/scrcpy.

EP07.US002EP07: Device Mirror & Remote ControlDone

Mirror and control an iPhone

5 tasks

As a developer, I want to mirror a real iPhone so that I can preview live screens on iOS.

✓The iPhone tab lists devices via GET /api/wda/devices and shows WDA status via /api/wda/status.
✓"Start WDA" launches WebDriverAgent via xcodebuild (POST /api/wda/launch), auto-detecting signing team and project; a setup helper shows go-ios commands.
✓"Live" streams MJPEG from /api/wda/mjpeg?udid=…, falling back to polling /api/wda/screen.
✓Tap/swipe/text/buttons (Home, Vol, Lock) send POST /api/wda/input (logical points).
✓A USB tunnel via iproxy forwards ports 8100/9100.

EP07.US003EP07: Device Mirror & Remote ControlDone

Preview web, media, and markdown

4 tasks

As a user, I want to open links, images, and docs in the side panel so that I can review supporting material in context.

✓Clicking an in-page link opens it in the panel: media files → Media tab, .md → Markdown tab, else Web tab (iframe, no-referrer).
✓Media tab renders image/video/audio from a file pick or GET /api/preview-file?path=….
✓Markdown tab renders .md/.mdx with a dependency-free converter.
✓The panel is resizable (min 320px) and can pop out to a new tab.

EP08.US001EP08: Desktop App DistributionDone

Install and launch a native app

3 tasks

As a user, I want a double-click desktop app so that I can use App Preview without a terminal.

✓A signed/notarized .dmg (macOS) and NSIS installer (Windows) install without Gatekeeper/SmartScreen blocks.
✓On launch, the Tauri shell spawns the Python sidecar, waits for READY http://127.0.0.1:<port>/, and opens a native window on that URL.
✓The bundled app serves the Playground directly at /; Sync/Test/Try-template work as in run.sh.

EP08.US002EP08: Desktop App DistributionDone

Keep app data isolated and seeded

3 tasks

As a user, I want my edits stored in a stable per-user location so that updates don't wipe my work.

✓First run seeds ~/Library/Application Support/vn.fighttech.appstorepreview/ (or the platform equivalent) from the bundled tool.
✓Writable: .env, listing.json, listing-current.json, assets/new/, assets/current/.
✓The native File menu offers Open Folder and Check for Updates.

EP08.US003EP08: Desktop App DistributionDone

Receive automatic updates

3 tasks

As a user, I want the app to update itself so that I always have the latest version.

✓The Tauri updater reads latest.json from the GitHub Release; updates are cryptographically signed and verified before install + relaunch.
✓"Check for Updates" works on demand; a silent check runs on launch.
✓CI builds and publishes signed artifacts on a version bump (macOS + Windows).

EP08.US004EP08: Desktop App DistributionDone

Build and sign from source

3 tasks

As a maintainer, I want a reproducible signed build so that I can cut releases.

✓desktop/scripts/build-sidecar.sh embeds the Playground and PyInstaller-builds the backend binary.
✓desktop/scripts/build.sh produces the .app/.dmg; signing uses a Developer ID cert + ASC API key for notarization (assets under .signing/).
✓deploy.sh / appdist.sh build and publish to a GitHub Release (.dmg, latest.json, .app.tar.gz, .sig).

Software Requirements Specification — App Preview

1. Introduction

1.1 Purpose

1.2 Scope

1.3 Definitions

1.4 References

2. Overall Description

2.1 Product perspective

2.2 Architecture

2.3 User classes

2.4 Operating environment

3. Requirements Summary

4. User Stories

5. Use Cases

UC-01 Prepare and verify a release (primary flow)

UC-02 Verify credentials only

UC-03 QA on a real device

UC-04 Install and auto-update the desktop app

6. Screens / UI Surfaces

Store Listing Preview (Playground)

Layout Mode: Split-panel (sticky control bar + store mockup)

Components

States

Events

SRS Export

Review Diff (Current → New)

Layout Mode: Tab-based modal

Components

States

Events

SRS Export

Store SEO / ASO Audit Panel

Layout Mode: Side panel (toggle)

Components

States

Events

SRS Export

First-Release Checklist

Layout Mode: Full-screen modal (grouped)

Components

States

Events

SRS Export

Credentials Import / Export

Layout Mode: Tab-based modal (Export & Import)

Components

States

Events

SRS Export

Device Mirror & Preview Panel

Layout Mode: Right-side rail + slide-out panel

Components

States

Events

SRS Export

7. Data Model

8. External Interfaces (API)

9. Non-Functional Requirements

10. Risks

11. Traceability

12. Build & Run

Screen Flow

Feature Board

Backlog 0

To Do (Sprint) 0

In Progress 0

In Review 0

Done 0

Preview a listing on both stores

Switch between New and Current variants

Edit metadata and assets in place

View the listing per locale

Use the tool in dark mode and multiple UI languages

Sync the live App Store listing

Sync the live Google Play listing

See a clear sync result

Keep credentials on the machine

Diff metadata field-by-field

Diff screenshots slot-by-slot

Summarize and dismiss