Recipely：一套代码覆盖 iOS、Android 与 Web 的 AI 菜谱应用

One codebase. iOS, Android and the web. A recipe app that puts the recipe first — and writes one for you when you only have a video.

recipely.net · About · dev.recipely.net

Table of contents

Purpose & scope

The problem. Recipes online are optimised for ad impressions, not for cooking. You scroll past a life story to reach the ingredients, you lose your place mid-step, and you have no good way to keep the handful of recipes you actually make.

What Recipely does. It puts the recipe first: ingredients and steps as checklists, timers that live inside the step that mentions them, and a personal collection that follows you across devices. If a recipe only exists in your head or in a video someone sent you, the AI generator turns it into a structured recipe you can edit and save.

In scope

• Recipe discovery, search, filtering and sorting; detail view with ingredients, steps and photos.
• Authoring: manual creation, AI generation from a prompt, and import from an Instagram video (server-side transcription + vision).
• Cooking aids: ingredient checklists, step completion, inline countdown timers with alarms.
• Social surface: likes, saves, comments, notifications, public profiles.
• Accounts: email/password, Google and Apple sign-in, password reset, account deletion.
• A full responsive web build with its own desktop shell and SEO-indexable public pages.

Out of scope — deliberately, for now

• Meal planning, shopping lists and pantry tracking.
• Offline-first sync — the app reads from the network and caches in memory; it is not a local-first database.
• Nutrition as medical guidance: values are informational and come from the source data.
• Real-time collaboration or messaging between users.

Features

Tech stack

Architecture

Five layers. Each layer may only import from layers below it — enforced mechanically, not by convention.

┌─ presentation ── UI, routing, theme, i18n, widgets
│    ↓
├─ application ─── use cases, Zustand stores, DI registration
│    ↓
├─ domain ──────── entities, value objects, repository & port interfaces (pure TypeScript)
│    ↓
├─ infrastructure  repository implementations, DTOs, mappers, HTTP, storage, Firebase
│    ↓
└─ core ────────── Result, Failure hierarchy, BaseEntity, DI container (imports nothing)

The parts that are easy to get wrong:

• domain never imports a framework. Entities use a private constructor plus a static create(): Result<T, Failure>, so an invalid entity cannot be constructed at all.
• infrastructure is reached only through ports. Storage, notifications, audio and the rest sit behind interfaces declared in domain/application and resolved through the DI container. The presentation layer may not import @infrastructure; the only sanctioned exceptions are infrastructure/constants/* and the composition root.
• Errors are values. Result<T, Failure> throughout domain and application code — no thrown exceptions for expected failure.
• Aggregates are documented. Cross-aggregate references are by id only, and every entity is listed as root-or-member in the table in architecture.md.

Presentation anatomy

src/presentation/app/ is both the expo-router root and where pages live. Only index.tsx, _layout.tsx, +special and [param] files register as routes — a custom route context (presentation/navigation/route-context.js, wired through metro.config.js) hides everything else, so a page's parts can be co-located with it:

app/recipes/
  index.tsx      the route itself — composition only, no business rules
  body/          large view sections
  items/         rows, tiles, chips, cards → grouped: filters/ hero/ cards/ banners/
  sheets/        bottom sheets and modals
  hooks/         the page's use-* hooks
  model/         pure TypeScript: types, mappers, labels
  shared/        parts used by this page and its nested detail page
  [recipeId]/    nested detail page, same anatomy

Note

That custom context replaces a framework-owned module, so it inherits every use the framework has for it — including looking +native-intent up by key to find redirectSystemPath. Rule Q exists because hiding that file once unplugged the iOS share extension in complete silence.

Design system

presentation/base/theme/ is split by what a file is for:

• tokens/ — every design measurement, one module per purpose (sizing/, typography/, effects/), plus scale.ts, which adapts measurements to the device.
• colors/ — palette/ (raw palettes and themes), surfaces/ (what a colour means: severity, error, variant semantics), contrast/ (WCAG contrast maths).
• context/ — which theme is active at runtime, and how a component reads it.

Sizing is responsive by construction: measurements scale from a 375pt baseline against the device's shortest edge (clamped, neutral on web), boxes containing text use minHeight rather than height, and line heights are derived from font size so text survives the OS accessibility font scale. Full rules in architecture.md §5a.

Repository layout

index.js           entry point — installs the crash net, then hands off to expo-router
src/
  presentation/    UI — app/ (pages), base/ (widgets, theme, hooks), navigation/, i18n/, bootstrap/
  application/     use cases, stores, DI registration, test fixtures
  domain/          entities, value objects, repository & port interfaces
  infrastructure/  repository impls, DTOs, mappers, HTTP client, storage, Firebase, crypto
  core/            Result, Failure, BaseEntity, the DI Container, named literals
assets/            images, fonts, sounds (reached via @assets/*)
public/            static web assets (about page, legal pages)
plugins/           Expo config plugins (splash force-dark, release signing, R8, iOS dSYM upload)
scripts/           check-structure, generate-map, prune-web-export, apply-variant-robots
.github/workflows/ ci.yml — the whole pipeline

Path aliases: @core/*, @domain/*, @application/*, @infrastructure/*, @presentation/*, @assets/*, @/* (repo root). Relative imports are allowed only inside barrel index.ts files.

Tip

Looking for where something lives? PROJECT-MAP.md is a generated ~1k-token index of the whole tree, and check:structure fails while it is stale — so it is never wrong.

Getting started

Prerequisites

• Node.js 20+ (CI runs 20) and npm
• Xcode 16+ for iOS; Android Studio with JDK 17 for Android
• A .env.local for anything that talks to a real service

Install

npm install

Environment

Create .env.local in the repo root. Everything is EXPO_PUBLIC_* because it is read on the client:

EXPO_PUBLIC_API_BASE_URL=            # optional — overrides the per-variant default
EXPO_PUBLIC_API_AES_KEY=             # 32-byte hex; must match the backend's API_AES_KEY
EXPO_PUBLIC_WEB_APP_URL=             # optional — canonical web origin for share links
EXPO_PUBLIC_GOOGLE_WEB_CLIENT_ID=    # Firebase → Auth → Google sign-in
EXPO_PUBLIC_FIREBASE_API_KEY=
EXPO_PUBLIC_FIREBASE_APP_ID=
EXPO_PUBLIC_FIREBASE_AUTH_DOMAIN=
EXPO_PUBLIC_FIREBASE_PROJECT_ID=
EXPO_PUBLIC_FIREBASE_STORAGE_BUCKET=
EXPO_PUBLIC_FIREBASE_MESSAGING_SENDER_ID=
EXPO_PUBLIC_FIREBASE_MEASUREMENT_ID=
EXPO_PUBLIC_FIREBASE_VAPID_KEY=      # web push only

Warning

The AES key ships inside the binary and is extractable by reverse engineering. It hardens the request envelope; TLS is what actually protects the transport.

Run

npm start            # Expo dev server (production backend)
npm run start:dev    # …against the dev backend

npm run web          # web in a browser
npm run ios          # prebuild + run on a simulator/device
npm run android

.vscode/launch.json ships ready-made profiles: Recipely: Expo (Dev/Prod) and Recipely: Web (Dev/Prod).

Build variants

APP_VARIANT selects the whole environment at config-evaluation time — bundle identifier, display name, URL scheme, Firebase config and backend host — so both variants can live on one device.

Quality gates

Four checks. Work is not done until all four are green.

npm run lint             # ESLint (expo config) — zero errors
npm run typecheck        # tsc --noEmit, strict
npm test                 # Jest
npm run check:structure  # architectural rules (also checks PROJECT-MAP.md is fresh)
npm run map              # regenerate PROJECT-MAP.md after moving files

check:structure (scripts/check-structure.mjs) is what keeps the architecture from drifting. It is not a linter — it encodes the rules a linter cannot see, and most of them were added the day a bug proved they were needed:

A Husky pre-commit hook runs lint-staged → tsc --noEmit → check:structure on every commit. The emergency bypass is git commit --no-verify, and the reason belongs in the commit message.

Important

A bug fix ships the test that would have caught it. Every behavioural fix lands with a regression test that fails without it, a mechanical guard where one is possible, and a one-line entry in docs/regressions.md recording the class of mistake — not the incident. That file is why this table keeps growing.

Testing

npx jest                          # everything
npx jest src/domain               # one layer
npx jest --watch                  # while developing
npx jest path/to/file.test.ts     # one file

Tests live in __tests__/ next to what they cover. Every use case, repository, mapper, store, value object and entity is expected to have one; component tests use the shared harness in presentation/base/test-support/, which renders inside the theme and safe-area providers.

Some invariants are asserted as tests rather than left to review — theme/tokens/__tests__/scale.test.ts fails if a design-token ladder stops ascending, so a token added in the wrong place is caught immediately rather than at the next redesign.

Observability

Crash reporting is installed at the entry point, before the app starts — index.js calls installCrashHandlers() and only then hands off to expo-router/entry. Three layers, because no one of them sees everything:

Two rules keep the reports readable: FailureReporter.report only escalates the unforeseen codes to Crashlytics (a validation message the product already answers is counted as an analytics event instead), and breadcrumbs are places in the code, never values — an id or URL on a crash report is user data leaving the device.

CI/CD

.github/workflows/ci.yml, on every push:

Caution

Merging to dev does not ship a mobile build. Lint, tests and the dev web deploy always run; the Android and iOS builds run only when explicitly requested — either by putting [dist], [dist:android] or [dist:ios] in the subject line of the merge commit, or with gh workflow run ci.yml --ref dev -f android=true. The ios input defaults to false. IOS_CI_ENABLED is the iOS kill switch.

Only the subject line is scanned. It used to be the whole message, and a commit whose body merely explained the markers shipped an IPA nobody wanted.

Branch flow: feature branch → PR → dev → (release PR) → main. main is release-only.

Conventions cheat-sheet

Full rules live in CLAUDE.md and architecture.md; this is the short version.

License

Released under the GNU AGPL-3.0. You may read, run, modify, self-host and redistribute this code, provided your version is released under the same licence and its source is available to anyone who uses it — including over a network.

A copyright licence covers code and nothing else, so the name Recipely, the logo and the store listings are reserved separately in TRADEMARKS.md: a fork is welcome, a look-alike in the stores under the same name is not.

Note that this repository is the client. The backend it talks to is a separate, private repository, and no API key, encryption key or service credential is committed here — so this tree is something to learn from and build on rather than a deployable copy of the product.

Documentation map