Build an iOS and web app with Fóir
Start from Tilly, a complete app built on Fóir. It has an iPhone app, a website with a web app, subscriptions and an admin console that opens inside Fóir. You set it up in your own Fóir project, then your coding agent changes it into your product. Fóir runs the backend, so the code you keep is your app's own logic.
What the template includes
- An iPhone app in SwiftUI with the camera, a map, feeds and follows.
- A website and web app in one TanStack Start project, deployed as one Cloudflare Worker.
- One sign-in for both apps, from one user pool in your Fóir project.
- Subscriptions through RevenueCat on iOS and Stripe on the web, checked on the server.
- An admin console inside Fóir, where your team edits copy, reviews reports and manages users.
- Public and private profiles with follow requests, enforced by Fóir's access rules.
One project behind every screen
The iPhone app, the web app and the console all read the same Fóir project. They read directly, with a publishable key and the user's session. Anything that changes data goes through a signed operation that Fóir runs.
The screenshots come from a demo account. Every cat in them is an illustration.
The iPhone app
The SwiftUI app reads the same Fóir records as the web app, so a profile or a cat looks the same on both. Catches start in its camera, which suggests cats it has seen nearby.
The admin console inside Fóir
Your team runs the app from a page that opens in Fóir's console, signed in with their Fóir accounts. Its tabs cover the app's words, art styles, challenges, settings and content reports. The words are the same ones the iPhone app and the website show, in every language you add.
The parts you replace
Cats and catches are Tilly's own subject. A cat's page collects every catch of that cat with what each person noticed. When you adapt the template, these become your app's records and screens. Sign-in, billing, the CMS and the console carry over.
Turn Tilly into your app
The repository includes three skills for your coding agent, used in order. In Claude Code, type /adapt-tilly. In Codex, ask it to use the adapt-tilly skill.
/adapt-tilly
Interviews you about your product: who it's for, what they do on a first visit and what brings them back, what they create and who can see it, what the iPhone app, the website and the console each need, and whether you'll charge. It writes a product brief and leaves the code alone.
/plan-foir-app
Compares the brief with the template, decides what stays and what changes, and writes the work as ordered tickets in your issue tracker.
/build-foir-app
Works through the tickets. It changes the models, screens and operations, keeps sign-in, billing, the CMS and the console working, and runs the checks as it goes.
The first questions
A real /adapt-tilly session opens like this:
Let's start the discovery. I won't edit any code yet.
1. What is your app idea? Give me a sentence or two, and a concrete example of someone using it.
2. Who are your users? Describe the people who will use it, and whether staff or admins will also manage content in the embedded console.
It asks a couple of questions at a time and waits for your answers. Anything you haven't decided goes in the brief as an open question, and you can correct the brief before any code changes.
Other skills in the repository cover billing, moving to production, App Store preparation and testing the app on a simulator or a phone.
Set it up
What you need
- A Fóir account with an empty project for development.
- A Cloudflare account, for the one Worker that serves the website, the console and the operations.
- Xcode and an Apple Developer account for the iOS app.
- RevenueCat for iOS subscriptions, Stripe for web billing and an OpenAI key for moderation, photo challenges, breed suggestions and artwork. Every feature is always on, so each one needs its keys.
1. Get the code and connect your agent
On GitHub, choose Use this template on the Tilly repository to start your own repository, then install its dependencies with Node 22.18 or newer and pnpm 10.33.
pnpm install --frozen-lockfileConnect Fóir's MCP server (https://mcp.foir.dev/mcp) to your coding agent, sign in with OAuth and choose your workspace and project. The agent then reads AGENTS.md and README.md, which have the full rules behind this guide.
Copy .env.example to .env and fill in your project and tenant IDs and your site's origin. Leave the keys empty: your first push creates them and writes them into .env.
2. Create the schema
One root foir.config.ts declares the models for the app and the website, so iOS and the web share one project and one user pool. On a fresh project, push the schema on its own first and review the changes before you confirm.
FOIR_BOOTSTRAP_SCHEMA_ONLY=true pnpm exec foir push --no-prune3. Deploy, install the app and finish the configuration
Fill in your project and tenant in web/wrangler.jsonc, then build and deploy. One build holds the website, the console and the operation handlers.
pnpm build
pnpm deployOnce your site serves /_foir/apps/tilly.json, install the app into your project. This registers its operations, the signed endpoints the apps call for every write. Add the app's provider credentials in Fóir, preview and apply the operations' quotas, then push the full configuration.
foir apps install <your-origin>/_foir/apps/tilly.json
pnpm configure:operations
pnpm configure:operations --apply
pnpm exec foir push --no-pruneThen load the example content. Preview it first. The seed asks for your project ID so it can't land anywhere else.
pnpm seed --dry-run
pnpm seed --development-project <your project ID>4. Run the apps
Run the web app with pnpm dev. For iOS, run ios/scripts/app-key.sh to copy your publishable key into the build settings, set your team, bundle identifiers and site URL in ios/Config, and open ios/Tilly.xcodeproj.
pnpm devSign in with a test account and save a catch, using a photo you're allowed to use. Take or choose a photo, confirm which cats are in it and save. The iPhone suggests cats it has seen nearby, and the browser asks you to pick them.
5. Try privacy and follows
Switch your test account to Private. Sign in as a second account and follow the first: the button shows Requested, and the first account gets a badge on its profile button. Accept the request and the follower sees the catches. Signed out, or as anyone else, the catches and their photo files stay hidden.
Behind this is one audience record per person. Every record in a catch points at it, and Fóir lets whoever can read the audience read the catch. Switching privacy changes that one record and leaves the catches as they are.
6. Check it
pnpm test
pnpm build
pnpm check:web
pnpm check:publicThese run without calling any provider. On a Mac, the check:ios-* scripts compile the native checks, and Xcode builds the app itself. When you change sign-in, uploads or sharing, check what each account sees, in the records and in the photo files: the owner, a follower, someone else and a signed-out visitor.
7. Check the paid and AI features
Every feature is on from the start: photo challenges, moderation, breed suggestions, artwork and billing. Each one uses the provider keys you added in step 3, which live in the app's credential fields in Fóir, never in the Worker or the phone. Test your store products and server entitlements end to end before you take real payments. Apple's sandbox, a provider's test store and live billing are separate environments.
When you're ready to launch, create a fresh production project from your reviewed configuration and content. Development users, photos and test purchases stay behind.
Known gaps and how Fóir will close them
A few things the template needs aren't in Fóir yet. Each has a workaround in the template, and some limit a feature for now. The list says how each gap will close, with no dates. Your copy of the template has the details in docs/known-gaps.md.
Payments and Premium
Fóir payments and entitlements closes these. A Stripe or App Store purchase becomes one subscription record and one entitlement in your project, kept current by provider webhooks and a regular check with each provider, and Fóir checks it on the server. • Subscriptions are reconciled by one installed operation that provider webhooks start. This closes when Fóir keeps the subscription and entitlement itself. • Paid allowances use operation quotas, and those don't fail closed if their rules can't load. This closes with one entitlement and quota check that Fóir enforces. • Provider keys are read through the installed app instead of the root config. This closes when a root-config operation can read its own saved credential. Payment keys move to Fóir payments.
Access between users
• Following uses an audience record, a follow made of two records and a tidy step. This closes when apps can declare access rules such as "readable by the owner's accepted followers", and an unfollow then ends access at once. • On a private profile, counts show only to the user and their followers. This closes when an operation's declared permissions decide what it reads and writes, so counts can live on both profiles and show to everyone. • Blocks aren't enforced in both directions. The same declared permissions and access rules close this. • An operation can't change several records in one atomic write, so each write is made safe to repeat. This closes with atomic multi-record writes.
Notifications
• Follow and like notifications to another user are switched off. This closes when a hook with the named-recipient permission can notify another user, and people can delete their own notifications. • A hook that runs when an operation finishes doesn't know which user started it. This closes when it carries that user's signed identity.
Caching and live updates
• Private and social models skip the response cache, so a narrower audience applies straight away. This closes when Fóir clears cached reads on every visibility or permission change. • Signed-out visitors can't subscribe to public posts, so the page reads them again on a timer. This closes when subscriptions follow the same read rules as queries. • A nested filter on a catch's state can miss a tag, so the apps check each catch themselves. This closes when the filter is fixed.
AI features
• Breed suggestions, challenge checks and artwork call OpenAI from an operation with the installed credential. Fóir still owns identity, quotas and private data. This closes when an operation can call a declared Fóir agent.
Sign-in
• The website hides Sign in with Apple, and the iPhone app keeps it. This closes when Fóir's hosted sign-in supports Apple's web flow next to the native one.
Console
• Translations are edited in Fóir's own field editor. This closes when an embedded console page can save a translated field. • Challenges are published from Fóir's editor. This closes when an embedded page can publish the exact version it reviewed.
Setup and tooling
• A fresh project takes three pushes: the schema, the app install, then the full config. This closes when a dry run reports what the real push would refuse and one push can install the app first. • Operation quotas have to be applied again after each app install or update. This closes when the app manifest carries them and updates keep them. • Each environment's app manifest address is kept in private settings. This closes when named projects treat it as a per-project destination. • When you remove a field that holds data, the decision file the CLI writes needs its model key quoted by hand. This closes when the CLI quotes it. • A partial update over MCP can replace fields it doesn't name, so the app uses typed GraphQL operators. This closes when MCP updates merge. • Pointed at Fóir's dev environment, the CLI's custom-domain instructions name the production login edge. This closes when they name the edge you're using. • Email previews clip at phone width and show a different Reply-To. This closes when the layouts fit phones and the preview uses your project's Reply-To.
Troubleshooting
- A field is missing from generated types: the key you generated with can't read it, so check that key's permissions before you change code.
- A photo won't load: a record and its file have separate access, so check both.
- An operation looks stuck: open its run in Fóir before retrying, so paid work isn't repeated.
- A feature fails: its provider keys are probably missing. Fill them in the app's credential fields in Fóir. For billing, the console's Premium tab has Check setup, which lists the missing keys.
Where to read more
README.md in your copy of the template has the full setup, and AGENTS.md has the rules your agent follows. The Fóir docs cover each platform feature the template uses.