FirstPass

Docs · Developers

Developer guide

How FirstPass is put together and how to change it. The source is on GitHub.

Overview

FirstPass is a Next.js app with no accounts and no database for answers. The visitor’s answers live in their browser, the rules are plain TypeScript, and a handful of small API routes do the few things a browser can’t.

PieceChoice
FrameworkNext.js 16 (App Router, Turbopack) and React 19
Language and stylingTypeScript and Tailwind CSS 4, with design tokens in app/globals.css
StateBrowser storage only, shared between pages with useSyncExternalStore
RulesPure functions over the answers: no network, so they run instantly and are easy to test
Free servicesGoogle Gemini (store page text), Pollinations (background pictures), Resend (feedback email), Vercel Blob (beta sign-ups)
HostingVercel, deployed from the main branch

Run it locally

git clone https://github.com/Matanza00/PlayStore.git
cd PlayStore
npm install
npm run dev

Open http://localhost:3000. Everything works with no settings, because every outside service is optional.

Before you push
npx tsc --noEmit
npx eslint app lib components
npm run build

Settings

Copy .env.example to .env.local to use them locally. On Vercel, add them under Project Settings, Environment Variables, then redeploy: a change only applies to new deployments.

NameNeeded?What it does
GEMINI_API_KEYOptionalFree key from Google AI Studio. Without it, the studio writes a simple template from the visitor's own words.
GEMINI_MODELOptionalAny Gemini model with a free tier. Defaults to gemini-3.5-flash-lite.
RESEND_API_KEYFor feedbackSends the feedback email. Without it, the form says nothing was sent and offers a mailto link.
FEEDBACK_TOOptionalWhere feedback is delivered. Defaults to support@nxcsol.com.
FEEDBACK_FROMOptionalThe sender, on a domain verified in Resend. Defaults to FirstPass <feedback@nxcsol.com>.
BLOB_READ_WRITE_TOKENFor beta sign-upsAdded automatically when a Vercel Blob store is connected to the project. Without it, the beta page says nothing was saved and the front page shows no count.

Keep keys out of the repo. .env.local is ignored by git, and the keys are only ever read on the server.

Project layout

PathWhat lives there
lib/questions.tsThe whole questionnaire as data: steps, questions, options and which ones show for which answers.
lib/rules.tsevaluate(): turns answers, the build report and link checks into findings. About 40 rules.
lib/scan.tsThe build check prompt, the report type, and a forgiving parser for what people paste back.
lib/listing.tsLength limits and wording checks for the store title and descriptions.
lib/client-info.tsReads IP, device and browser from request headers, for feedback emails.
lib/beta.tsBeta tester sign-ups in a private Vercel Blob store: one small file per device, a cached count and the newest names.
lib/feedback-email.tsBuilds the feedback email, as HTML and plain text, escaping everything typed by visitors.
components/CheckFlow.tsxThe wizard and the results page.
components/Studio.tsxThe store page studio: words, feature graphic, screenshots and icon, drawn on canvases.
components/shared.tsxThe browser storage hook and small helpers.
app/api/*/route.tsThe five server routes. See the API reference below.
docs/The Google Play policy research the rules are based on.

Data and storage

Everything the visitor enters is saved in localStorage under the key firstpass.v1. The check and the studio share it, so what someone writes in one shows in the other.

type Saved = {
  answers: Record<string, string | string[] | undefined>; // keyed by question id
  scanRaw: string;                                        // the pasted build report
  done: string[];                                         // ids of findings marked "fixed"
};

If the browser refuses storage, such as in a private window, the app still works for that visit. Nothing in storage is sent anywhere unless an endpoint below says so.

The build report

The build check hands the visitor a prompt, and they paste back the JSON their AI tool answers with. parseScan() extracts the first {…} block, so extra chatter around it is fine. Every field is optional, and null means “couldn’t tell”.

FieldTypeUsed for
framework, frameworkVersion, expoSdkstring, numberStack-specific fix prompts.
packageName, versionCodestring, numberContext in prompts.
targetSdk, minSdknumberThe target API rule (Google currently requires 36).
permissionsstring[]Permissions packages added that the visitor didn't mention.
sdks, paymentSdks, adSdksstring[]Payments and ads cross-checks.
billingLibraryVersionstringThe Play Billing version rule (8 or newer).
hasNativeLibraries, supports16KbPageSizebooleanThe 16 KB memory page rule.
debuggable, usesCleartextTraffic, isMostlyWebViewbooleanUpload and quality checks.
hasAccountDeletion, hasPrivacyPolicyLink, notesboolean, stringCross-checks against the answers.

Add a rule

A rule is a call to add() inside evaluate() in lib/rules.ts. Every rule runs every time, so wrap it in the condition that makes it apply.

The shape of a finding
type Finding = {
  id: string;                       // stable, unique: used to remember "I've fixed this"
  severity: "blocker" | "warn" | "tip";
  area: "Account" | "Privacy" | "Permissions" | "Content" | "Money" | "Build" | "Store page" | "Play Console";
  policy: string;                   // the name Google uses for this rule in its emails
  title: string;                    // plain words, no jargon
  what: string;                     // why it matters, in a sentence or two
  steps: string[];                  // what to do, in order
  prompt?: string;                  // for code fixes: wrap with prompt(a, "...")
  source: { label: string; url: string }; // Google's own page
  deadline?: string;                // shows a "From <date>" tag for announced rules
};
An example
if (is(a, "hasLogin", "yes") && is(a, "canDelete", "no")) {
  add({
    id: "delete-in-app",
    severity: "blocker",
    area: "Privacy",
    policy: "Account deletion requirement",
    title: "People must be able to delete their account in the app",
    what: "If someone can create an account, Google requires a way to delete it from inside the app.",
    steps: ["Add a Delete my account option to settings.", "Ask for confirmation, then delete the data."],
    prompt: prompt(a, "Add a Delete my account option to the settings screen…"),
    source: src.deletion,
  });
}

Add a question

Questions are data in lib/questions.ts, so changing the wording or adding one needs no form code.

{
  id: "hasLogin",                 // the key in answers
  label: "Do people sign in or create an account?",
  help: "Optional line of help under the question.",
  type: "single",                 // text | longtext | url | single | multi
  options: [{ value: "yes", label: "Yes" }, { value: "no", label: "No" }],
  optional: false,                // optional questions can be skipped
  showIf: (a) => is(a, "stack", "flutter"), // only show when this is true
}

Then read the answer in a rule with the helpers is(a, id, value), has(a, id, value) for multiple choice, and text(a, id) for free text.

API reference

Five routes, all POST with a JSON body (/api/beta also accepts DELETE). They exist for the few things a browser can’t do alone, and every one is optional to the main check.

POST /api/check-url

Opens a privacy policy or account deletion link the way a reviewer would and reports what is wrong.

// request
{ "url": "https://example.com/privacy", "kind": "privacy" | "deletion", "appName": "Tiffin Tracker" }

// response 200
{ "url": "https://example.com/privacy", "ok": false, "problems": ["The link uses http. It needs to start with https."] }

Returns 400 for a body that isn’t JSON. Only public web pages are fetched.

POST /api/write-listing

Drafts store page text with Gemini.

// request
{ "appName": "Tiffin Tracker", "oneLiner": "Helps home cooks take lunch orders", "category": "general", "features": "Take orders\nTrack deliveries" }

// response 200
{ "title": "…", "shortDesc": "…", "fullDesc": "…" }
StatusMeaning
400The app name or one-sentence description is missing.
501No key is set ({ "error": "no-key" }). The studio falls back to a template.
502Gemini was busy or didn't answer.

POST /api/background

Fetches a free AI background picture for the feature graphic, passed through as image bytes.

// request
{ "description": "warm kitchen counter with lunch boxes" }

// response 200: the image (content-type image/*), 1024 × 500
StatusMeaning
400The description is under three characters.
429The free service allows one picture every 45 seconds.
502 / 504The picture service didn't answer or took too long.

POST /api/feedback

Emails feedback to the team through Resend, with the sender’s IP address, device and browser read from the request headers.

// request
{ "message": "Required, 5 to 2,000 characters", "rating": 1-5 (optional), "email": "optional", "from": "results" (optional) }

// response 200
{ "ok": true }
StatusMeaning
400The message is too short or too long, or the email address doesn't look right.
413The request body is over 10 KB.
429More than five messages an hour from one visitor.
501No Resend key is set ({ "error": "not-configured" }).
502Resend refused or didn’t answer ({ "fallback": true }).

POST /api/beta and DELETE /api/beta

Counts someone as a beta tester, anonymously or with a name the site may show, and removes them again. Each device is one small file in a private Vercel Blob store, named by a one-way code made from the IP address and browser, so a person counts once and no address is stored.

// POST request
{ "mode": "anonymous" | "named", "name": "Faraz" (only when mode is "named") }

// POST response 200
{ "ok": true, "named": true }

// DELETE: no body. Removes this device from the list and the count.
// DELETE response 200
{ "ok": true }
StatusMeaning
400A named sign-up needs 2 to 30 letters (spaces, dots, hyphens and apostrophes are allowed, no links or numbers).
413The request body is over 2 KB.
429More than five requests an hour from one visitor.
501No Blob store is connected ({ "error": "not-configured" }).
502The store didn't answer.

Security notes

  • Link checks can’t reach private networks. /api/check-url refuses localhost, internal and private addresses, checks every redirect hop against the same rule, follows at most five redirects, and gives up after 12 seconds.
  • Feedback is escaped. Everything a visitor types is HTML-escaped before it goes into the email, and the address used for replies is validated.
  • Abuse is limited. Five feedback messages an hour per visitor, and a small body size. The counter lives in each server instance’s memory, so it is a best-effort limit, not a guarantee.
  • Keys stay on the server. No secret is exposed to the browser, and no answer is stored server-side.
  • Disclosure. The feedback page tells visitors their IP address, device and browser are sent with the message.

Deploy

The project is linked to its GitHub repository on Vercel, so every push to main builds and deploys. It runs at fp.nxcsol.com. To run your own copy for noncommercial use, import the repository into Vercel, add the settings above if you want them, and deploy. Offering a copy to others as a service needs a commercial licence.

The rules reflect Google Play policy as read on 14 November 2026. The research behind them is in the docs/ folder of the repository, and every finding links to Google’s own page so it can be re-checked.

Contributing

The FirstPass code is public and open to contributions from anyone, under a noncommercial licence (see the licence page). Fork the repository, make one focused change, run the three checks above, and open a pull request. Changes to rules must link to Google’s own page and say when it was read.

Something missing or wrong?

These docs follow the app as it works today. If a step doesn’t match what you see, tell us.

Send feedback