Home / Product / Consumer App

Affirmology app architecture decision, v1 (native vs wrapper, answered honestly)

Updated Jun 25, 2026 · Affirmology_AppArchitecture_Decision_v1.md

Affirmology app architecture decision, v1 (native vs wrapper, answered honestly)

Status: DECISION DOC for Jeff, written in response to your questions on the overview. This supersedes the "just wrap everything in Capacitor" framing in Affirmology_AppDelivery_Plan_v1.md where they conflict. The short version: you are right to want native for the end-user app, my "months" line was an overstatement, and the two apps want two different answers.

1. The honest correction (why I said "months," and what is actually true)

I conflated two different jobs.

• Rebuilding ATLAS (the Studio) natively from scratch is a big lift, because Atlas is a complex web app that already exists and works: the composer, the people library, the render controls, the chat, the listening room. Re-implementing all of that in Swift would be real rework for an internal tool that does not need to be slick. THAT is where "why redo it" applies. It is not that native is impossible; it is that there is no payoff.
• The AFFIRMOLOGY consumer app is NEW and scoped (a player, a library, a chat, feedback, reports). Building THAT natively is weeks, not months, and faster still with Claude Code generating the code. I was wrong to imply months for the app you actually care about going native on. Apologies for the scare.

Also, "native" does not have to mean hand-written Swift. React Native is native (it renders real native UI components, not a webview), but you build it in JavaScript/React, which is fast to produce and close to the web skills we already use. That option is the key to your whole concern, so it gets its own row below.

2. The three real options

There are not two choices (native vs web wrapper). There are three.

Option A: Native Swift / SwiftUI

• What it is: a true Apple-native app, hand-built for iOS.
• Pros: the absolute ceiling on polish, performance, gestures, and deep OS integration. Best long-term App Store citizen.
• Cons: iOS only (Android later is a whole separate build in a different language), slowest to build a feature-rich app, no reuse of any web code, and every logic change needs a new build (no instant over-the-air updates).

Option B: React Native (with Expo), the one I recommend for the consumer app

• What it is: a real native app (native UI under the hood) built in JavaScript/React. One codebase produces iOS AND Android.
• Pros: native feel and performance, excellent audio (the standard library handles background playback, offline caching, and lock-screen controls out of the box, which is exactly your must-have), fast to build, ONE codebase for iOS and Android, and OVER-THE-AIR updates: you can push most changes (logic, layout, copy, bug fixes) straight to people's phones in minutes with NO App Store review. Huge for a fast-iterating beta.
• Cons: a thin bridge layer sits under the JS; the rare bleeding-edge native trick may need a small native module. Polish is very close to hand-Swift but not the theoretical max.

Option C: Capacitor wrapper (our web app inside a native shell)

• What it is: the existing web app, put inside a native container. Real installable app, but the screens are a webview.
• Pros: maximum reuse of an app that ALREADY EXISTS (this is why it fits Atlas), fastest way to ship something already built, can still use native plugins for audio/push/offline, and in remote-URL mode you push web changes instantly.
• Cons: the UI is a webview, so scroll/gesture polish is weaker and it can feel like "a website in a box" (the thing you do not want for the consumer app); background audio needs a native plugin and is fiddlier than in React Native; and a too-thin wrapper draws Apple's "minimum functionality" scrutiny on the public store.

3. My recommendation, split by app

The two apps have different jobs, so they get different answers.

Atlas (the Studio): keep the web app, wrap it (Option C). Do NOT rebuild native.

Atlas is internal, already built, complex, and allowed to be a little clunky. It is used by you, Sol, Colin, and soon a handful of elevated creators. Spending weeks to re-create the working web Studio in Swift buys you almost nothing. Wrap it so it installs like an app, keep improving the web version (which instantly improves the app), and move on.

Crucially, wrapping now does NOT lock you out of native later. The brains of Atlas (the engine, the agents, the render pipeline, the data, the APIs) live on the SERVER. The app is just a face on top. You can replace that face later (web-wrap today, native tomorrow) without touching the engine. So starting wrapped costs you nothing strategically, and you will probably never need to redo it for an internal tool.

Affirmology consumer app: go React Native (Option B). Your instinct is right.

This app is media-first, has to feel premium, must do offline + background audio, will iterate fast, wants Android eventually, and is going to the public App Store in August. React Native hits every one of those: native feel, the best-in-class audio library for background/offline listening, fast build, one codebase for Android later, and over-the-air updates so you can iterate without waiting on Apple. Pure Swift is the only thing that beats it on raw polish, but at the cost of iOS-only and slower iteration, which is the wrong trade for a fast-moving consumer beta. I would build it in React Native.

4. The thing that actually answers "how fast can we push changes"

This matters more than native-vs-wrapper, and it removes most of your anxiety. There are THREE kinds of "change," at three very different speeds:

1. CONTENT and DATA: which audios are available, pushing new audios, new categories, descriptions, sound beds, the chatbot's knowledge, reports. This lives on the SERVER. Updates are INSTANT, no app release, no Apple review, no matter native or wrapper. This is MOST of what you want to change. "Swap which audios are pushed every few days" is a data operation, not an app update. You will do it constantly with zero friction.
2. APP LOGIC and UI tweaks: layout, copy, feature flags, bug fixes. With React Native + over-the-air updates (or a remote-loaded web wrapper), these go straight to phones in minutes, NO Apple review. With pure Swift, these need a new build.
3. GENUINELY NEW NATIVE FEATURES: a new capability that touches native code. This needs a new binary submitted to Apple. On TestFlight that is instant for internal testers and about a day for the first external build of a version; on the public App Store a full update review is typically about a day.

So: audios and content change daily for free; UI and logic fixes ship over the air without Apple; only true new native features hit a review cycle, and even those are fast on TestFlight. One rule to respect: Apple does not allow hiding a whole new feature and flipping it on over the air to dodge review. Material new features go through a build. Everything else is fast.

This is why React Native is such a good fit: the audios are data (instant), most UI iteration is over-the-air (no review), and only big new native capabilities need a submission.

5. Your specific questions, answered

Bundle ID, what it is and what "confirm" means

A bundle ID is just a unique identifier string for the app inside Apple's system, like ai.affirmology.atlas. The reverse-domain style is a convention, not a requirement: it does NOT have to match a real URL and nothing has to exist at that address. It just has to be unique and namespaced to you. It lives in two places: registered in your Apple Developer account (Identifiers) and set in the app project config. When I asked you to "confirm," I only meant approve the string we will register. It does not exist yet and it is not referencing anything in our current system, so your read ("this is cool to use for the developer account, yes") is exactly correct. The one catch: it is effectively permanent once the app ships (it is the app's identity for TestFlight, push, and purchases), so we pick it once. Proposed: ai.affirmology.atlas and ai.affirmology.app. Approve or tweak.

Remote URL vs bundled assets

Bundled = the app ships with its files inside it (works offline, updates via release or over-the-air). Remote URL = the app loads the live website each time it opens (always current, but needs a connection, and a pure remote-URL app risks Apple's thin-wrapper rejection on the public store). For ATLAS (internal, always online) remote URL is fine and fastest. For the CONSUMER app we are going React Native, so this question mostly dissolves: React Native bundles its own code and updates over the air; the audios still stream/cache from our servers.

In-app purchase and driving upgrades (I gave you outdated info before, correcting it)

First, for the free BETA this is a non-issue; nobody is paying inside the app. For the paid launch:

• Most of your billing happens on the WEBSITE before the app even opens. Your plan (marketing to landing page to demo to sales page to pay to download to log in) means those customers buy on the web and never touch Apple's purchase system. That is the clean majority path and it is great.
• I told you earlier "you cannot link out from inside the app." That was the OLD rule. It changed. Since the 2025 US court ruling in Epic v. Apple, US apps CAN include links and buttons that send users to your website to pay. Apple's ability to charge a commission on those external links is still being fought in court as of mid-2026 (an appeals court said Apple may charge "a reasonable" fee but struck down its 27% as too high; no settled rate yet, and it may go to the Supreme Court). So the situation is friendlier than I first said, but the exact economics of linking out are unsettled.
• Net for upgrades from inside the app: you have real options. You can show "this feature is for Constellation members" prompts and have the chatbot say "you can create that in a higher tier." To take the money you can (a) link out to your website in the US app to upgrade, (b) use Apple in-app purchase in-app (smoother, Apple's cut), or (c) the always-safe path of "manage your membership in your account / we just emailed you a link." For the beta we do none of this; for launch we will pick the mix, and selling on the web with an in-app link-out is looking like the strong play.

In-app report viewer

Yes, build it, and it is better than emailing a PDF. Two layers: a beautiful NATIVE in-app READING view that renders the written report (the prose, the oracle voices, the mantras, the chart panels) so people stay in the app and it feels premium and works offline, PLUS a quiet "email me the PDF" button for those who want the document. Do not force them to leave the app to read their report. The native reading view also sidesteps clunky in-app PDF rendering entirely.

What "the 4 to 5 day build" actually means

It means roughly 4 to 5 days of actual BUILDING effort (Claude Code doing the work across our sessions, you steering and reviewing), assuming the backend exists and the scope is tight. It is NOT Apple upload or approval time (that is separate and small: TestFlight processing is 15 to 60 minutes; the one external review is about a day). And it is not "Jeff sits at the computer all day for five days." It is elapsed engineering time. It was always a rough estimate; the real gating items are the backend and the app foundation, not Apple.

Do the starter audios have to exist or be named first? No.

Build the platform DATA-DRIVEN. Categories and journey containers exist in the app; each audio is just a DATA RECORD (title, description, category, which oracle, the audio file, an optional report). You add, swap, rename, reorder, or remove audios any time with NO app release and NO Apple review. So we ship the app shell with empty-but-ready categories, and you populate and change the 5 to 10 audios over the following days, test new beds, swap things out, all as data. The app renders whatever is in each person's catalog; it does not care what the specific audios are. You can decide and re-decide the lineup continuously.

6. Reframing the Affirmology v1 (you were right, it is a TESTING SUITE)

Throwing out the "which exact 7 or 8 audios and how many per person" framing. v1 is not the finished paid client product. It is an INSTRUMENT to get audios, reports, feedback, and chatbot conversations in front of the founding testers so THEY help us decide the real starter kit, the tiers, the upsells, the journeys, and the pricing. We build the platform; the content flows through it and changes constantly.

What v1 needs to DO (the platform), independent of which audios are in it:

• A data-driven LIBRARY by category and journey, where audios appear, change, and get swapped as data (5 to 10 to start, variable, likely a human-design explainer, a longer all-systems reading that feels premium, a gene-keys journey, a longer journey, a daytime affirmational, a nighttime, a morning, mostly hybrids; exact lineup stays fluid).
• The IN-APP PLAYER, mandatory: offline and BACKGROUND audio so they can listen while scrolling Instagram or with the screen off, back and forth, over and over. Beta users are NOT emailed MP3s or download links; they use the in-app player. This is a core requirement and a reason native/React Native is the right base.
• The ORACLE CHATBOT, scoped: a Sophia/Hermes/oracle CHARACTER experience grounded in THEIR blueprint, with the oracle photos popping up in chat, optionally testing Fish-audio spoken replies. It does NOT create audios, it does not do app support, its information is deliberately limited, and it may mention features and tiers. Goal: engagement, character, and data on what people want.
• FEEDBACK everywhere plus ratings, including the nudge to rate things they listened to but did not rate.
• The IN-APP REPORT reading view plus optional email PDF.
• The Shape Affirmology FEATURE VOTING board and IDEA submission.
• USAGE tracking and PUSH notifications (new audio ready, occasional "rate this" nudges, which you approved).
• Community lives in a WhatsApp group, not an in-app forum.

And a note on the future shape: eventually you may run TWO apps, one experimental build where the founding crew tests crazy new features pre-release, and one stable public app. We do not build two now; we just keep the architecture clean so splitting later is easy.

7. Timeline to a July 1 to 3 beta (honest)

Your goal: beta in founders' hands around July 1, okay with July 2 or 3 (July 1 you are driving; July 2 to 3 you are at a computer). That is about a week from now (today is June 24), and you also want the full scale-ready backend before the beta. Native (React Native) app PLUS a real backend PLUS content in one week is aggressive but not crazy IF we scope hard.

To make July 2 to 3 realistic, the LEAN v1 cut is: magic-link login, the data-driven library by category, the offline + background player, the scoped oracle chatbot, feedback and ratings, push for "new audio ready," and a basic in-app report reading view. Fast-follows (days later, over the air, no new beta needed): the voting board, the listened-but-unrated nudge automation, a polished usage dashboard, Fish-audio replies, and Android. The backend: build the real system-of-record schema now, but only the surface the lean app needs; layer the analytics niceties right after.

Two honest flags: (1) aim for July 2 to 3, not July 1, since you are driving on the 1st and the first install always wants a human at a keyboard. (2) Even July 2 to 3 is tight; if it slips, it slips to mid-July, and the lever to protect the date is scope, not all-nighters. Starting the backend immediately is what makes the date possible.

Also: Atlas can be in your hands in DAYS (it is a wrap-and-ship), which lets you, Sol, and Colin shake out the TestFlight install experience before the consumer app is ready. Good way to de-risk the install flow.

8. Decisions captured from your message

• Atlas: wrap (web), do not rebuild native. Move Atlas to magic-link login (away from Cloudflare Access), since more than three people will be in the Studio over time; fine if it changes our Cloudflare setup.
• Atlas testers: you would rather not add Sol and Colin as App Store Connect users. Clarification: to INSTALL any iOS app, a person still needs an Apple ID + the free TestFlight app + our invite (that is Apple's install gate, unavoidable, and separate from our magic-link content login). The "different route" is to invite Sol and Colin as EXTERNAL testers by email instead of making them App Store Connect users; that avoids giving them dashboard access at the cost of one ~24h beta review. We will use that route.
• Affirmology consumer app: React Native (native), not a web wrapper.
• Backend: build the full scale-ready backend before the beta.
• Audios: data-driven and variable; the platform does not hard-code them; v1 is a testing suite, not the final client product.
• Chatbot: ships in v1, scoped (no audio creation, limited info, oracle character, photos, optional Fish voice).
• Player: in-app, offline, background; no emailed MP3s/links to beta users.
• Reports: in-app reading view plus optional email PDF.
• Push notifications: yes (new audio ready, occasional rate nudges).
• Community: WhatsApp group.
• Android: iOS first; add Android only if beta testers need it (React Native makes that a smaller add).
• Beta cohort: do not collect the 20 to 40 emails yet; for now it is just you, Sol, Colin; you will have a list in about a week, gathered via the demo + an apply/flag step, gated by the email captured at the demo.
• Beta target: around July 1, ideally July 2 to 3.
• Bundle IDs to approve: ai.affirmology.atlas, ai.affirmology.app.

9. Immediate next steps

1. Approve the two bundle IDs (ai.affirmology.atlas, ai.affirmology.app) or tell me your preferred strings. This is just you saying "yes, register these."
2. Confirm the architecture call: Atlas wrapped, consumer app React Native. If you agree, I will write the two build briefs for Claude Code (Atlas wrap + Affirmology React Native v1) mirroring the Atlas brief format, with exact pastes.
3. Greenlight starting the scale-ready backend now (it is the long pole for the July beta). I will spec its lean v1 surface so it does not balloon past the date.
4. For Atlas: confirm you want it moved to magic-link login (yes/no). If yes, that build also de-Cloudflare-Accesses Atlas; I will note the exact Cloudflare change in the brief.
5. Leave the beta-cohort emails for next week as you said; meanwhile you, Sol, and Colin are the first three testers for both apps.

10. Round 2: follow-up answers and decisions (2026-06-24)

Answers to the second round of questions, and the decisions locked from them.

• BUNDLE ID "ai" prefix: pure convention. Reverse-domain flips a domain you own, so affirmology.ai becomes ai.affirmology, and the TLD (.ai) lands first. It has no functional meaning beyond being a unique, recognizably-ours string; com.affirmology.* would work just as well. APPROVED: ai.affirmology.atlas and ai.affirmology.app.
• REACT NATIVE quality and legitimacy: confirmed strong and in heavy production use as of mid-2026: Instagram, Shopify (95 to 99% shared code, sub-500ms screens), Discord (startup time halved, 98% shared code), Coinbase, Microsoft Office, Walmart, Bloomberg, Pinterest, Uber Eats, Strava, and Tesla (3D vehicle visualization in RN). RN supports rich animation (Reanimated), custom graphics/shaders (Skia), gestures, and Lottie; bleeding-edge needs drop into a small native module. It does NOT cap the "mega cool, dynamic experience" ambition, and going fully native later (when rich with users + serious dev hires) stays open.
• THE "THIN BRIDGE" CAVEAT, plainly: RN runs your JS and draws REAL native iOS controls (not a webview), talking across a fast bridge you never notice 99% of the time. The "small native module" caveat only applies if you want a capability no RN library exposes yet (a brand-new iOS API, very custom hardware/graphics), which is a normal, well-trodden add, not a wall. "Polish near hand-Swift but not the theoretical max" is irrelevant for an audio/library/chat/reports app; we will not hit that ceiling.
• WEB CODE REUSE is NOT a factor for the consumer app (Jeff: "who cares"). Correct: reuse only mattered for ATLAS because that web app already exists. For the new consumer app it is a non-consideration; native (React Native) is the call.
• DECISION, CONSUMER APP: React Native, confirmed. Build the LEAN v1 cut first; everything else (voting board polish, usage dashboard, Fish voice replies, etc.) lands as over-the-air fast-follows. "Yes to all the features" over time; lean first to hit the date.
• DECISION, FEEDBACK: ratings PLUS written NOTES on everything, so every audio can be improved from specific notes, not just a star. Notes are a first-class field on every rating surface.
• DECISION, CHATBOT SUPPORT: the main oracle chat stays FUN and about astrology/blueprint. App support is handled separately, either by a dedicated "Support Oracle" or by context-routing within the chat (the system recognizes a support question and answers it in-character or hands to the support path), possibly behind an explicit "make a request." To design during the chatbot build; the principle is support never muddies the oracle experience.
• DECISION, ANDROID: dropped from scope entirely for now. Not even on the list. If a specific beta tester needs it, they get an Android build a little later than the rest (React Native makes that a smaller add).
• DECISION, ATLAS TESTERS: internal tester route is fine (add Sol + Colin). Near-term, Jeff will elevate several of the first beta users (about a week out) into the "inner constellation" to DESIGN audios, i.e. give them Studio/creator access. So Atlas access needs to scale past three people soon; design for easy elevation.
• ATLAS LOGIN: leaning MAGIC-LINK for both Atlas and the consumer app (one login system makes elevating people into the Studio easier), but Jeff is not final. Recommendation: use magic-link for both; it unifies identity, eases creator elevation, and drops the Cloudflare Access dependency. Awaiting Jeff's final yes.
• ATLAS LONG-TERM: wrap now, but Jeff expects to "unwrap" it (go native) before long. Noted and fine: wrapping is reversible, the server-side engine is untouched, so a later native Atlas is a face-swap, not a re-platform.

11. Round 3: Atlas goes native too (2026-06-25, Jeff's call, objection withdrawn)

DECISION: Atlas will be REBUILT NATIVE in React Native (same stack as the consumer app), NOT the Capacitor wrap. Jeff overrode the wrap recommendation, and the reasoning holds: the wrap case rested on "do not throw away working software you depend on," but Sol is not really using Atlas and Jeff wants a UI overhaul anyway, so there is little to preserve and the main cost of going native evaporates. Native Atlas in RN is actually cleaner: one stack, one shared design system across both apps, OTA updates on Atlas too. The overnight Capacitor wrap (Brief B) is parked (smallest of the three; magic-link auth + the session gate carry over). The backend and engine are untouched, so this is a new face + a new creation flow, not an engine rebuild.

CENTERPIECE: the audio-making experience moves INTO the Hermes chatbot, and it needs to be strong. A creator talks to Hermes ("make a before-bed audio for Jeff leaning into his Cancer moon"), Hermes runs the council, shows the script, the creator iterates by talking, then says "render it." The rails already exist (/api/hermes + /api/compose + /api/audio); this is a UX layer on existing plumbing, made the primary creation surface.

DESIGN PRINCIPLE (keep while making chat strong): chat-PRIMARY, not chat-ONLY. Conversation drives, but the exact controls (person, named structure, length, render settings) stay reachable in a panel for precision moments. Chat for flow, controls for precision; also eases elevating beta testers into creators (lean on chat, grow into controls).

SEQUENCING: the consumer app stays the July priority (it is the dated one). The native Atlas rebuild is a FAST-FOLLOW that reuses the consumer app's RN design system and components, so much is shared. Keeps the July date safe while Atlas gets its overhaul. (Open: run them more in parallel if Jeff prefers.)

TAHOE: Jeff restarts the Mac tonight to bring up macOS Tahoe (pairs with installing full Xcode). Heads-up captured: after the OS jump, verify the engine venv, ffmpeg, node, CocoaPods, and Xcode-vs-Tahoe version compatibility before the next build push.