Home / Product / Consumer App

Affirmology app delivery plan, v1 (Atlas + Affirmology to real iOS apps)

Updated Jun 25, 2026 · Affirmology_AppDelivery_Plan_v1.md

Affirmology app delivery plan, v1 (Atlas + Affirmology to real iOS apps)

Status: PLAN for Jeff to revise. The Apple Developer account is active, which unlocks everything below. This doc covers two shipments on the same account: ATLAS (the team app, for Jeff, Sol, Colin) and the AFFIRMOLOGY app v1 (the beta-team listening app). It answers: how we build them, how accounts and logins work, how people download them, the timings, the Atlas path, and the path plus open decisions for Affirmology v1.

One account holds BOTH apps as separate records. Cost is the standard $99/year (already paid). Nothing below requires a second developer account.

1. The one big technical decision: wrap the web app, do not rebuild native

"A real Apple app" does NOT have to mean rewriting everything in Swift. The fast, correct path that reuses all the work we have already done is to WRAP our existing web app in a native shell using Capacitor, then ship that through TestFlight and (later) the App Store.

• What Capacitor is: an open-source native runtime that puts our web app (HTML/CSS/JS, the same Studio/Atlas/Affirmology code) inside a real native iOS app container. The output is a genuine .ipa (a real Apple app) that installs from TestFlight and the App Store, shows up with our icon, runs full-screen, and can use native features (push notifications, background audio, offline storage, the native share sheet).
• Why this and not a native rebuild: a from-scratch Swift app would throw away the entire web codebase (Studio, the player, the oracle chat, the reports) and take months. Capacitor reuses ~all of it and turns it into a shippable Apple app in days. For our timeline and team, this is the right call by a wide margin.
• Is it "really" a native app: yes. It is distributed exactly like any native app (TestFlight, App Store), and we add native capabilities where they matter (notifications, offline, background audio). The web wrapper is the inside; the outside is a real iOS app.
• The one caveat, for LATER (not for the beta): for the PUBLIC App Store, Apple rejects "thin wrappers" that are just a website in a box (Guideline 4.2). We clear that bar because our app has real native value: offline downloaded audio, push nudges, a real background-audio player, our own login. We make sure those native pieces are present before any public App Store submission. For TestFlight beta, this is not a gate at all.

Recommendation: Capacitor wrapper for BOTH Atlas and Affirmology. Same approach, same tooling, two app records.

2. Accounts and logins (the part to be crystal clear on)

There are TWO different "logins," and people confuse them. Keep them separate in your head:

Login 1: to GET the app (Apple's side)

To install a TestFlight app, a person needs three things, and NONE of them is a developer account:

1. An Apple ID (the normal Apple account everyone with an iPhone already has).
2. The free TestFlight app, installed from the App Store.
3. An invite from us (an email invitation or a TestFlight link).

That is it. Testers do not pay anything, do not need a developer account, and do not touch Xcode. They tap our invite, install, and run.

Login 2: to USE the app (our side)

Once the app is open, the person logs into THEIR Affirmology content with OUR own magic-link / one-time-code auth (the Option B decision already made in the Delivery App spec), tied to their email in our database. This is what controls who sees what, their audios, their chart, their tier.

So the email is the through-line. Best practice: collect each person's email once, use that SAME email for (a) their TestFlight invite and (b) our magic-link allowlist. Then "get the app" and "log into the app" line up cleanly.

Important consequence: our magic-link auth is the REAL gate on content. Even if someone got the app who should not have, they cannot log in unless their email is on our invite list. That means the TestFlight layer does not have to be perfectly locked; the content is safe regardless.

Atlas specifically (Jeff, Sol, Colin)

Atlas already gates on Cloudflare Access (email one-time PIN for Jeff and Sol). For a three-person internal tool that is fine to keep as-is inside the app. We do not need to rebuild Atlas auth to ship it; we just wrap the existing gated web app. (If we later want Atlas to feel more app-native at sign-in, we move it to the same magic-link, but that is optional and not blocking.)

3. How a tester downloads it (the literal flow)

What you will tell each beta person, in plain steps:

1. Install the free "TestFlight" app from the App Store.
2. Open the invite we send (an email button, or a link we text them).
3. In TestFlight, tap Accept, then Install for "Affirmology."
4. Open the app, enter your email, tap the magic link (or type the 6-digit code) we email you, and you are in.

On Android (if/when we add it): the same Capacitor project produces an Android app; distribution is via Google Play internal testing or a direct link. iOS first per your ask.

4. Distribution: internal vs external TestFlight (this sets the timings)

TestFlight has two tester types, and the difference decides how fast each app reaches people. (Verified against Apple's current TestFlight docs, June 2026.)

• INTERNAL testers: up to 100, and each must be a User on our App Store Connect account. They get every build INSTANTLY with NO Apple review. Perfect for Atlas (Jeff, Sol, Colin = 3 people). We add their Apple ID emails as App Store Connect users and they are testing within an hour of a build upload.
• EXTERNAL testers: up to 10,000, invited by email or a shareable link. The FIRST build of each version needs a "Beta App Review" by Apple, typically about 24 hours (range 4 to 48h). After that, new builds of the same version usually clear in minutes. Right for the Affirmology beta team (20 to 40 people): we are not going to make 40 people App Store Connect users, so they go through the external track.
• Build expiry: EVERY TestFlight build (internal or external) expires after 90 days. We re-upload before then. Not a concern for a short beta, just know it.

For the Affirmology beta we can invite external testers by EMAIL (controlled, matches the no-strangers ethos) rather than a public link. And again, our magic-link is the real content gate, so this stays locked to the inner orbit.

5. Timings (what gates what)

• Apple Developer account: ACTIVE already. This was the long pole and it is done.
• Atlas to the three of you: gated only by BUILD time, not Apple. Once Claude Code produces and uploads a build, it processes in about 15 to 60 minutes, then it is instantly available to internal testers with no review. Realistically Atlas can be in your hands a day or two after we start, mostly dependent on wrapping/signing, not Apple.
• Affirmology v1 to the beta team: gated by (a) building the consumer FRONT END and backend first (it does not exist yet, see section 7), then (b) wrapping it, then (c) a one-time ~24 to 48h Beta App Review for external testers. Plan a one-day Apple buffer on top of build time.
• Re-builds during the beta: internal (Atlas) instant; external (Affirmology) same-version updates clear in minutes after the first review.

6. The Atlas path (ready to start now)

Atlas is the closer of the two because its web app essentially already exists (the cloud Studio is live on Render + R2, and Atlas is that plus the Hermes chat surface and the mode toggle). The cloud-is-24/7 prerequisite Atlas needed is already met. So Atlas is mostly a wrap-and-ship job.

What is needed and who does each part. Two actors: CLAUDE CODE on your Mac (it has Xcode and the repos; the Cowork chat cannot run Xcode), and YOU clicking the few things only a human can do in Apple's web UI.

6a. One-time setup YOU do in App Store Connect (the human-only clicks)

1. Sign in at https://appstoreconnect.apple.com with the developer Apple ID.
2. Users and Access: add Sol and Colin as Users with their Apple ID emails (role: at least "Developer" or "App Manager" so they can be internal testers). This is how they become internal testers with instant, no-review builds.
3. We will create the Atlas app record (this can be done by you or by Claude Code via the API); you confirm the bundle id and name.

6b. What Claude Code does on the Mac (you paste it the brief below)

Copy this into a Claude Code window on the Mac:

Read /Users/jeffreyparker/CLAUDE/AFFIRMOLOGY/CLAUDE OUTPUTS/Affirmology/Affirmology_AppDelivery_Plan_v1.md
and /Users/jeffreyparker/CLAUDE/AFFIRMOLOGY/Affirmology_Atlas_AppSpec_v1.md and Affirmology_Atlas_Overview_v1.md.

Goal: ship Atlas as a real iOS app to TestFlight for internal testers (Jeff, Sol, Colin),
by wrapping the existing Atlas/Studio web app in Capacitor. Do NOT rebuild native and do
NOT touch the locked demo.

Steps:
1. Confirm Node 22+ and Xcode are installed; install CocoaPods if missing.
2. In the Atlas/Studio web project, add Capacitor (@capacitor/core, @capacitor/cli,
   @capacitor/ios) and initialize with app name "Atlas" and bundle id "ai.affirmology.atlas"
   (confirm this id with Jeff first).
3. Decide load mode WITH Jeff: for an always-online internal tool, point the Capacitor
   webDir/server at the live https://studio.affirmology.ai (remote URL) for v1 speed, OR
   bundle the web build. Recommend remote-URL for Atlas internal. Implement the chosen one.
4. Add the iOS platform, app icon, and splash (use the brand assets; emerald/gold).
5. Add native plugins we want now: push notifications (for team pings) and status-bar/
   safe-area handling. Background audio is more relevant to the Affirmology app; skip for Atlas
   unless trivial.
6. Open in Xcode, set the Signing Team to the active developer account, set version/build,
   Archive, and upload to App Store Connect (Organizer > Distribute App).
7. In App Store Connect, create/confirm the Atlas app record, enable TestFlight, add the
   internal testers group (Jeff, Sol, Colin). Confirm the build shows as ready to test.
8. Report back exactly what Jeff must click to invite Sol and Colin, and verify the app
   launches and that Cloudflare Access sign-in works inside the native shell. If Access OTP
   is clunky in the webview, flag it and propose moving Atlas to the magic-link auth.

Constraints: reuse the existing web app, do not alter the demo, keep brand styling, no em dashes
in any copy. Verify the build installs on a real device before declaring done.

6c. Atlas decisions for you (quick)

1. Bundle id and name: "Atlas" with id ai.affirmology.atlas ok, or different?
2. Load mode: remote-URL (load studio.affirmology.ai live, fastest) vs bundled assets. Recommend remote for an internal tool.
3. Sign-in inside the app: keep Cloudflare Access for the three of you (recommended, zero rebuild), or move Atlas to the magic-link now?
4. Push notifications in Atlas now (team message pings), or later?

7. The Affirmology app v1 path (what has to happen, in order)

Unlike Atlas, the Affirmology consumer app does NOT have a built web app yet. It is fully specced (Affirmology_DeliveryApp_Spec_v1.md) but not built. So shipping it to TestFlight is a longer chain than Atlas, and the wrapping is the LAST step, not the first.

The order that has to happen:

1. BACKEND (the scale-ready Postgres system of record + event spine + schema from the spec, section 10). This is the foundation you asked to invest in properly. Longest pole.
2. STARTER AUDIOS: the suite of chart-driven starter audios per beta person, rendered and approved in the Studio (you are readying these). Remember every one is personal/chart-driven; the suite is a shared set of STRUCTURES, each rendered from each person's own chart.
3. CONSUMER FRONT END (the 4-to-5-day build in the spec): library by category, the offline-capable player, feedback everywhere plus the listened-but-unrated nudge, the Shape Affirmology voting board, the oracle chatbot, reports plus email, and our magic-link login.
4. WRAP in Capacitor (same as Atlas) with native offline audio, push notifications (for the feedback nudges), and background audio. Bundle id e.g. ai.affirmology.app, name "Affirmology."
5. SHIP to external TestFlight testers (the 20 to 40), one-time Beta App Review ~1 day, invite by email.

So Atlas can reach you in days; Affirmology reaches the beta team after the backend, audios, and front end exist. They share the SAME wrapping approach, so the iOS work is mostly reused the second time.

7a. Affirmology v1 decisions for you to revise (the meaningful ones)

Already decided (from the spec): our own magic-link auth; offline audio required; the Shape Affirmology voting board; WhatsApp group for community; every audio chart-driven.

Still open, and worth your input:

1. Backend scope for the beta: build the full scale-ready Postgres backend BEFORE the beta (cleaner, no migration, slower to first testers), or stand the beta up on a lighter store and migrate to the full backend after (faster to testers, some rework)? Recommendation: build the real backend now since you explicitly want it and the beta data is exactly what should live in it.
2. Starter suite definition: which structures are in the v1 suite (Foundational, Before-Bed, Morning, Astrological-Moment, others?), and how many audios per person at launch.
3. The beta cohort: the 20 to 40 emails (the Founding Constellation list). We need these for both the TestFlight invites and our magic-link allowlist (same emails).
4. Chatbot in the beta: ships in v1, or added a week or two in as the advanced-tier preview after first-suite feedback (the time-limited taste idea)? This affects the v1 build scope.
5. Push notifications: use them for the listened-but-unrated nudges and "new audio ready" (recommended, it is a core retention loop), confirm yes.
6. Tester invite style: email-invited external testers (controlled, recommended) vs a shareable TestFlight link.
7. Android: iOS-only for v1 (your ask), or produce the Android build from the same project at the same time?

8. What to know for the PAID public launch later (not now, but plan for it)

Two Apple realities to design around before any public, paid App Store release. They do NOT affect the free beta, but decisions made now should not paint us into a corner:

• Guideline 4.2 (no thin wrappers): the public app must feel app-native. We are fine because we are adding offline audio, push, and a real player, but keep investing in those native touches rather than shipping a bare webview.
• In-app purchase (the money one): Apple requires that digital memberships and digital content sold INSIDE the iOS app go through Apple's in-app purchase, and Apple takes 15 to 30 percent. This shapes how we sell the Starter Kit and memberships: charge on the WEB (keep 100 percent, but cannot link to it from inside the iOS app per Apple's rules) versus sell via Apple IAP in-app (smoother conversion, Apple's cut). This is a real strategic decision for the paid launch and worth its own analysis when we get there. For the free beta it is a non-issue.

9. Bottom line and immediate next move

• Approach: wrap, do not rebuild. Capacitor turns our existing web apps into real iOS apps, distributed via TestFlight, on the one active developer account.
• Atlas is close: it is a wrap-and-ship of the live Studio/Atlas web app to INTERNAL testers (you, Sol, Colin), no Apple review, in your hands in days. Start it with the Claude Code brief in section 6b plus your few App Store Connect clicks in 6a.
• Affirmology v1 is a chain: backend, then starter audios, then the consumer front end, then the same wrap, then a one-day external Beta App Review. Settle the section 7a decisions and we sequence the build.
• Logins, simply: Apple ID + TestFlight to get the app; our magic-link (one email per person, reused on both sides) to get into the content. Our login is the real gate.

Numbered immediate steps

1. Tell me your answers (or edits) to the Atlas decisions in section 6c and the Affirmology decisions in section 7a. Even rough answers let us start.
2. For Atlas now: confirm the bundle id ai.affirmology.atlas and the name "Atlas," then paste the section 6b brief into a Claude Code window on your Mac.
3. In parallel, in App Store Connect (https://appstoreconnect.apple.com): go to Users and Access and add Sol and Colin by their Apple ID emails so they can be internal testers.
4. Gather the beta cohort emails (the same emails will serve TestFlight invites and our magic-link allowlist) so they are ready when Affirmology v1 is built.
5. I will then produce the Affirmology v1 build brief for Claude Code (backend + front end + wrap), mirroring the Atlas one, once your section 7a answers are in.