Learn the system

How manageqrcodes.com works under the hood — for users evaluating trust, and for developers working on the open-source repos.

Overview

Manage QR Codes (manageqrcodes.com) lets you create and download QR codes in the browser for free, with no account required. Sign in with Luckee only if you want a saved list you can reopen later.

This page explains how Manage QR Codes is built: what runs in your browser, what happens when you save to My codes, and which open-source repos you can clone. It is not a tutorial for designing a QR code — use the generator on the home page for that.

Who should read this page

ReaderWhat you are trying to learnWhere to start on this page
Anyone making a QR codeUnderstand privacy (local generation) and when sign-in is optional.Read the lead below, then Trust and Data flow — or skip to the generator.
Shop, event, or product ownersConfirm commercial use, file formats (PNG/SVG/PDF), and that downloads do not expire.You might use this if… and the Features section.
Developers cloning the OSS reposSee the web + Express split, env vars, and HTTP contracts without internal repo names.Repositories, HTTP, Stack, and Web code sections.
Coding agentsOnboard to the right repo and ADRs before changing code.Agent callout at the bottom of this section, then .cursor/rules/AGENTS.md.

You might use Manage QR Codes if…

  • You need URL, WiFi, vCard, email, and other scan types without a watermark.
  • You want PNG, SVG, and PDF with custom colors, frames, and optional session logos.
  • You print or share codes on menus, packaging, signs, or badges.
  • You want a free list of codes across devices (My codes) without paying for generation.

You should not expect…

  • A step-by-step “how to design my QR” guide on this page — use /#generator instead.
  • Server-side rendering of your download on manageqrcodes.com — the image is built in your browser.
  • Logos to reappear automatically when you reopen a saved code (upload again per session).
  • The live website to call the OSS Express PNG API (that repo is for self-hosted integrators).

Luckee account (optional)

Luckee sign-in syncs your profile and unlocks My codes. It does not gate generation, downloads, or commercial use.

For coding agents

  • Read qr-code-generator-web/.cursor/rules/AGENTS.md, ADR 013 (auth), and ADR 004 (API/thunks).
  • Product split: web UI (browser QR) | hosted save API (NEXT_PUBLIC_CMS_URL) | qr-code-generator-open-source-express-server (optional PNG API).

Reference: Web ADR 013 — Browser Supabase auth

What you get

CapabilityIn the UIBackend
Live preview + download PNG/SVG/PDF#generator on /Browser only (qr-code-styling, jspdf)
Many payload typesGenerator tabsRedux currentQrCode + buildPayload
Save to My codes/codesPOST /api/qr-codes (JWT)
Reopen / edit/code-detail-pageGET/PATCH /api/qr-codes/:id
Account profile/login, /signupSupabase + POST /api/account/sync
Marketing page analyticsAll pages@vercel/analytics (site traffic only, not your QR payloads)

Out of scope for the main app

  • Requiring an account to generate or download
  • Storing raw PNG/SVG bytes on the server when saving (saved rows hold fields + design metadata)
  • Wiring the manageqrcodes.com generator to POST /api/generate-code on the OSS Express server

Two different kinds of “analytics”

Your QR content: stays in the browser until you choose to save form fields to the hosted save API.

This site: optional @vercel/analytics on the Vercel deployment for manageqrcodes.com page views.

Repositories

Public OSS pair on GitHub org Luckee-Core. Hosted save infrastructure is not listed here.

RepositoryRuns onOwnsDoes not own
qr-code-generator-webVercel + local devLanding generator, auth UI, My codes UI, browser renderingServer-side QR PNG generation for the main app
qr-code-generator-open-source-express-serverSelf-host / local (default port 3023)Stateless POST /api/generate-code (PNG), /docs, api-docs.jsonLuckee sign-in, saved My codes rows

Deploy flow

  1. Users open qr-code-generator-web on Vercel (or npm run dev locally).
  2. QR images render in the browser; downloads do not require any API.
  3. Optional sign-in uses Luckee Supabase; saves call the hosted save API at NEXT_PUBLIC_CMS_URL.
  4. Integrators may run qr-code-generator-open-source-express-server for a simple PNG generation HTTP API.

Full env and route tables: docs/oss/wire-contract.md in the web repo.

Trust and security

Browser-first generation, optional hosted save API, and an optional self-hosted OSS Express API for integrators.

Zone 1 — Browser

Generation and downloads run client-side. Nothing is sent to generate a download. Logos you upload apply to the current session only; reopened saved codes ask you to add a logo again.

Zone 2 — Hosted save API

When you save, form fields and design metadata go to NEXT_PUBLIC_CMS_URL with a Supabase JWT. The browser never receives the service role key. Auth email is delivered through Luckee-hosted infrastructure, not composed in the web app.

Zone 3 — OSS Express (optional)

Self-hosted server with no auth in the default OSS build. Any client that can reach the port may call POST /api/generate-code. Tighten CORS and add rate limits before exposing beyond localhost.

Where secrets live

Secret / dataAllowedNever
SUPABASE_SERVICE_ROLE_KEYHosted save API (server env only)NEXT_PUBLIC_* or the browser
SUPABASE anon keyNEXT_PUBLIC_SUPABASE_ANON_KEY in the web appService role in the web app
Saved QR rowsPostgres behind hosted save APILocal-only without save

Auth email

Sign-up and password-reset email are sent through Luckee-hosted auth infrastructure. See operator notes in SECURITY.md when published for the web repo.

Further reading

  • ADR 013 — .cursor/architecture/013-browser-supabase-auth.md
  • ADR 004 — .cursor/architecture/004-api-integration.md
  • Wire contract — docs/oss/wire-contract.md

Guest vs signed in

There is no separate cloud/local surface flag. Guests use the full generator; My codes requires a Luckee session.

PathGuestSigned in
/Full generator + downloadSame + save to My codes
/login, /signupAuth formsAuth forms
/codes, /code-detail-pageRedirect to /login (signed-in layout)List and edit saved codes
/learnStatic documentationSame

Web environment

VariablePurpose
NEXT_PUBLIC_SUPABASE_URLLuckee Supabase auth
NEXT_PUBLIC_SUPABASE_ANON_KEYBrowser auth client
NEXT_PUBLIC_CMS_URLHosted save API base (default http://localhost:3042 in dev)

Data flow

From typing in the generator to optional save in My codes.

Steps

  1. Pick a type and enter fields; qr-code-styling draws the preview as you type.
  2. Download PNG, SVG, or PDF from the browser (no generate button on the landing flow).
  3. Optional: sign in and save — saveQrCodeThunk sends SaveQrCodeBody to POST /api/qr-codes.
  4. Reopen from My codes — load the row, re-render the QR; re-add a logo if needed.

When something goes wrong

  • Save without a session — requestCmsApi returns unauthorized; sign in first.
  • Hosted save API unreachable — list/save thunks fail; generation still works.
  • Invalid payload — CMS validation errors; check type-specific fields.

Common questions

Is generating really free?

Yes. Creating and downloading on manageqrcodes.com does not require an account or payment.

Is my data private when I only download?

The image is built in your browser. Nothing is sent to generate a download. Saving sends form fields to the hosted save API for your account.

HTTP contract

Web CMS client: ApiResult with success, data or error, and httpStatus (see src/api/_shared).

OSS Express: { success: true, data } on JSON routes; POST /api/generate-code returns raw image/png bytes on success.

Hosted save API (NEXT_PUBLIC_CMS_URL)

MethodPathPurpose
GET/api/healthLiveness
GET/api/accountAccount summary (JWT)
POST/api/account/syncUpsert user from JWT
GET/api/qr-codesList saved codes
POST/api/qr-codesCreate saved code
GET/api/qr-codes/:idLoad one code
PATCH/api/qr-codes/:idUpdate saved code
DELETE/api/qr-codes/:idDelete saved code

OSS Express API (self-hosted)

MethodPathPurpose
GET/api/healthLiveness
POST/api/generate-codePNG body from JSON { url }
GET/api-docs.jsonAPI catalog
GET/docsHTML API reference

Full env and route tables: docs/oss/wire-contract.md in the web repo.

Stack

Versions follow each repo package.json at release time.

Web (qr-code-generator-web)

  • Next.js App Router (next ^16)
  • React 19, Redux Toolkit, manual thunks
  • Tailwind CSS 4
  • qr-code-styling, jspdf
  • @supabase/supabase-js (browser auth)
  • @vercel/analytics
  • Node 22.x

OSS Express (qr-code-generator-open-source-express-server)

  • Express 5, TypeScript
  • Stateless QR generation (no database in OSS default)
  • GET /docs + api-docs catalog (ADR 008)
  • Node 22.x

How the web app is built

Luckee Next.js template conventions. ADRs live in .cursor/architecture/.

Folder map

  • src/app/**/page.tsx — thin routes
  • src/packages/generator — browser QR UI
  • src/packages/codes — My codes list
  • src/store/thunks — async only
  • src/api/qr-code — hosted save API client
  • src/api/account — account sync
  • src/model — QrCode and related types

ADR quick reference

ADRSummaryThis product
001Redux: flat layers; manual thunks; no selector functionsYes
002Thin app routes; features in src/packages/Yes
003Styles object + Tailwind template literalsYes
004src/api clients; thunks only; ApiResultYes
008Static /code-detail-page + currentQrCodeYes
012Form inputs under packages; zero-prop modalsYes — generator
013Browser Supabase + CMS Bearer JWTYes — core auth

How the OSS Express API is built

Stateless PNG generation for integrators. Not wired into the manageqrcodes.com browser generator.

Folder map

  • src/services/qr-code/ — router, handlers, process-generate-qr-code
  • src/services/api-docs/ — catalog + HTML docs
  • src/services/health/
  • src/utils/http/ — response helpers

ADR quick reference

ADRSummaryThis product
001–002Services + router factory; handlers → processX()Yes
006Emoji logging; success/error JSONYes
008API docs catalog + /docs HTMLYes

Luckee OSS patterns

Same Next.js and Express template families as other Luckee apps; this product adds browser QR generation and optional hosted save APIs.

  • mentorai-server data/open-source — release checklists and pair contracts
  • oss-api-docs-pattern.md — OSS Express /docs + api-docs.json
  • oss-express-backend-benchmark.md — archetype for stateless OSS API

Glossary

TermMeaning
Hosted save APIBackend at NEXT_PUBLIC_CMS_URL for account sync and saved QR rows; not the browser generator.
SaveQrCodeBodyname, type, payload, content, and design fields sent when saving — not raw image bytes.
PayloadEncoded string placed inside the QR (e.g. URL or WiFi config) from buildPayload.
OSS Express APIOptional self-hosted POST /api/generate-code PNG server on port 3023 by default.
ApiResultWeb API boundary type from src/api/_shared (success + data or error + httpStatus).

Next steps

Agents: after this page, open .cursor/rules/AGENTS.md in the repo you are editing.