Felt Faction iOS app v1 — implementation plan

project 2026-07-08 Search related

Status: Draft. Awaiting sign-off on the 8 decision points at
the bottom before drilling into Phase 0 as bite-sized tasks.
For Hermes: Use subagent-driven-development skill to implement
task-by-task after the user signs off on the structure.

Goal: Build a native iOS app that replaces the Felt Faction web app for members, with vision-based chip counting, a Bank/Phoenix economy, Felty's voice, and admin-configurable seasons.

Architecture:

SwiftUI native iOS app (Hydrolyze pattern)
Supabase backend (existing instance: kbcolzlyevzmlgtjthqq)
Server-side vision (Claude Sonnet / GPT-4V via Supabase Edge

Functions)

Felty's voice via templated + LLM-generated copy
Web app stays as admin surface (Connor/Nathan) for v1

Tech Stack:

Swift / SwiftUI (iOS 17+)
Supabase Swift SDK + Keychain (auth, DB, storage)
Vision framework (camera, on-device image prep)
WidgetKit + Live Activity
Core Haptics (Taptic Engine)
Sign in with Apple + Google OAuth
Push notifications (APNs)
Supabase Edge Functions (Deno) for vision calls, Felty message

generation, push triggers

Data Model (Supabase)

New tables

-- Personal access tokens (the gate)
CREATE TABLE invites (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  key TEXT UNIQUE NOT NULL,                    -- felt_xxxxxxxxxxxx
  member_name_placeholder TEXT,
  tier TEXT,                                    -- 'vip', 'high_roller', 'walk_in'
  is_used BOOLEAN DEFAULT FALSE,
  claimed_by_id UUID REFERENCES members(id),
  expires_at TIMESTAMP,                         -- 7-day default
  created_by_id UUID REFERENCES members(id),
  created_at TIMESTAMP DEFAULT NOW()
);

-- Season config
CREATE TABLE seasons (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  number INT NOT NULL,
  start_at TIMESTAMP NOT NULL,
  end_at TIMESTAMP NOT NULL,                    -- start_at + length
  length_days INT NOT NULL,                     -- customizable
  starting_chip_allocation INT NOT NULL,        -- X chips per member
  status TEXT DEFAULT 'active',                 -- 'pending', 'active', 'closed'
  bank_interest_rate DECIMAL DEFAULT 0.15,      -- 15% default
  no_show_tax INT DEFAULT 200,                  -- 200 CC default
  created_at TIMESTAMP DEFAULT NOW()
);

-- Bank loans
CREATE TABLE loans (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  member_id UUID REFERENCES members(id) NOT NULL,
  session_id UUID REFERENCES events(id) NOT NULL,
  season_id UUID REFERENCES seasons(id) NOT NULL,
  principal INT NOT NULL,
  interest_rate DECIMAL NOT NULL,
  accrued_interest INT DEFAULT 0,
  amount_repaid INT DEFAULT 0,
  is_paid_off BOOLEAN DEFAULT FALSE,
  created_at TIMESTAMP DEFAULT NOW(),
  paid_off_at TIMESTAMP
);

-- Season Awards
CREATE TABLE season_awards (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  season_id UUID REFERENCES seasons(id) NOT NULL,
  member_id UUID REFERENCES members(id) NOT NULL,
  award_type TEXT NOT NULL,                     -- 'phoenix', 'veteran', 'whale', 'drowning'
  value NUMERIC,                                 -- the metric (e.g., paid-back amount, attendance %)
  awarded_at TIMESTAMP DEFAULT NOW(),
  UNIQUE(season_id, award_type)
);

-- Chip set presets
CREATE TABLE chip_sets (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  name TEXT NOT NULL,                            -- "Standard", "High Roller", etc.
  denominations JSONB NOT NULL,                  -- [{"color": "white", "value": 1}, ...]
  reference_photos JSONB,                        -- {"white": "url", "red": "url", ...}
  created_by_id UUID REFERENCES members(id),
  is_default BOOLEAN DEFAULT FALSE,
  created_at TIMESTAMP DEFAULT NOW()
);

Extended tables (existing)

members — add oauth_provider TEXT, oauth_subject TEXT,

current_working_hand INT DEFAULT 0, current_net_worth INT DEFAULT 0

transactions — add category TEXT (buy_in, rebuy, settlement,

loan_disbursement, loan_repayment, interest_debit, no_show_tax)

events — add season_id UUID REFERENCES seasons(id),

chip_set_id UUID REFERENCES chip_sets(id), started_at, ended_at, status TEXT

event_attendance — add working_hand_start INT,

working_hand_end INT, vision_pnl INT, self_attest_status TEXT ('pending', 'confirmed', 'disputed'), admin_override_pnl INT

App Structure (SwiftUI)

FeltFaction/
├── App/                          # App entry, scene config
├── Core/                         # Supabase client, auth, network, models
│   ├── Supabase/
│   ├── Auth/
│   ├── Network/
│   └── Models/
├── Features/
│   ├── Auth/                     # Invite + OAuth
│   ├── Briefing/                 # Pre-session content
│   ├── Session/                  # Buy-in, working hand, cashout
│   ├── Settlement/               # Live board, vision, self-attest
│   ├── Season/                   # Standings, awards
│   └── Settings/                 # Admin config
├── Felty/                        # System voice, message templates
├── Bank/                         # Loan logic, interest, debt tracking
├── Glance/                       # Widget + Live Activity
└── Resources/                    # Assets, strings, audio

Phased Build (10-14 weeks)

Phase 0: Foundation (1-2 weeks)

0.1 Xcode project setup, SwiftUI scaffolding, asset catalog
0.2 Supabase Swift SDK + Keychain integration
0.3 Auth flow: invite token validation + Sign in with Apple + Google
0.4 RLS policies for invites / members
0.5 Basic app shell (Login, Home, Settings placeholder)
0.6 Supabase migrations for new tables (invites, seasons,

loans, season_awards, chip_sets)

0.7 Extend existing tables (members, transactions, events,

event_attendance)

0.8 iOS admin surface for invite generation (admin role in

the iOS app, role-gated UI; single role-aware app, no separate web admin for invites)

0.9 Universal Links setup (apple-app-site-association on

feltfaction.app, Info.plist configuration, AASA verification)

0.10 URL handler in iOS app (parses invite/<token> from

Universal Link, passes to Auth feature, pre-fills welcome screen)

0.11 Fallback web page at feltfaction.app/install

(App Store CTA + "your invite will be waiting for you after install" + retry mechanism)

Phase 1: Felty + Push (2-3 weeks)

1.1 Felty voice system: message templates + character voice config
1.2 Push notification infrastructure: APNs + Supabase Edge Function

for triggers

1.3 Briefing content system: admin creates Briefing, Felty reads it
1.4 Lock Screen widget (basic, expand later)
1.5 Felty message library: ~20 templates (loan offer, settlement,

no-show, season finale, etc.)

1.6 Felty admin messages: Connor can compose in the iOS app

(admin role), distributed via system share sheet

1.7 Message personalization (member name, current standing)
1.8 iOS invite generation flow — admin enters name in app,

app generates token, composes Felty's message, opens system share sheet for distribution (Telegram, iMessage, email, QR, copy)

1.9 Felty invite confirmation — when recipient accepts, DM

admin: "Olivia accepted. The House has 11 members."

1.10 QR code generation in iOS admin view — for in-person

invites (Connor generates QR, Olivia scans with iPhone camera, Universal Link opens the app)

Phase 2: Session + Buy-in + Vision (3-4 weeks)

2.1 Session lifecycle: start (Connor triggers), end, settle
2.2 Buy-in flow with rebuy accumulator (draws from net worth)
2.3 Working hand tracking (per session, persists across phases)
2.4 Cashout photo capture: camera, photo upload to Supabase

storage

2.5 Server-side vision integration: Edge Function calls Claude

Sonnet / GPT-4V with one-shot prompt + reference colors

2.6 Vision response handling: P&L computed, returned to client
2.7 Self-attest UX: "Confirm" / "Adjust" / "Dispute"
2.8 Admin override: Connor's screen can override vision
2.9 Auto-delete photos after session finalize

Phase 3: Bank + Phoenix (2-3 weeks)

3.1 Loan mechanic: auto-offer at zero, configurable interest rate
3.2 Debt tracking
3.3 Auto-debit on settlement: bank collects interest, applies

winnings

3.4 Live settlement board: Connor's screen shows live P&L

resolution

3.5 "$X left until Y breaks even" indicator
3.6 "Dead in water" state enforcement
3.7 Phoenix badge on loan repayment with interest
3.8 Edge cases: double-loan prevention, manual loan write-off

Phase 4: Settings + Admin (1-2 weeks)

4.1 Admin settings page: season length, starting chip allocation,

bank interest rate, no-show tax

4.2 Chip set registration: presets, reference photos per

denomination

4.3 Felty admin messages: send from admin surface
4.4 Season Awards surface: Phoenix, Veteran, Whale, Drowning at

season finale

4.5 Auto-debit no-show tax (claimed-then-no-show only)

Phase 5: Polish (1-2 weeks)

5.1 Live Activity: session in progress, "Olivia: +$312 this hand"
5.2 Home Screen widgets: top 3 standings, next session countdown
5.3 Haptics polish: Taptic patterns for game state
5.4 Onboarding flow: first-time member walkthrough
5.5 Error handling: edge cases, retries, offline state
5.6 Accessibility: VoiceOver, Dynamic Type, contrast

Total: ~10-14 weeks for v1.

Open Items (operational defaults)

These are defaults, not mechanics. Admins can tune via the settings page. The system needs some default to start with:

Setting	Suggested default	Why
Starting chip allocation (X)	500 chips	Round, fits in a 5-denomination chip set
Bank interest rate	15%	Steep, "real casino" feel (per v4)
No-show tax	200 CC	Existing House Rule #3
Default season length	90 days (3 months)	Existing 3-month season structure
Reference chip set	5 denominations, 5 colors	Standard poker set

Decision Points (for sign-off before Phase 0)

SwiftUI native (vs React Native / Capacitor). Recommended

based on Hydrolyze pattern + brand language fit + native features (Vision, Core Haptics, Live Activity).

Server-side vision v1 (vs on-device Core ML). Recommended

for faster ship; on-device in v2 after collecting training data.

Sign in with Apple as primary (vs Google as primary).

Recommended for App Store compliance + iOS UX. Google as fallback.

Auth gating via personal access token (vs email invite link

or magic link). Recommended for security + audit trail.

Web app stays as admin surface (vs killed entirely).

Recommended to keep Connor's keyboard-and-mouse workflow.

Watch app deferred to v2 (vs v1). Recommended based on user

uncertainty ("I don't know if we need a watch app").

Live settlement board on Connor's phone (vs a dedicated

iPad admin app). Recommended for v1; iPad is a v2.

10-14 week timeline. Recommended based on phased scope;

admin can compress by deferring Season Awards UI to v2.

Universal Link as the distribution surface (vs copy-paste

token, magic link, or QR-only). Recommended for frictionless "tap once" flow. Token is in the URL; iOS app parses it.

**iOS app is the canonical admin surface for invite

generation** (vs separate Telegram bot DM'ing members). Recommended: admin enters name in the iOS app, app composes Felty's message + Universal Link, opens system share sheet. No separate bot. Felty exists as a character in the iOS app only.

Single iOS app, role-aware (vs separate admin app).

Recommended: same app, two roles (admin sees admin features, member sees member features). Role determined at auth time. Web app shrinks to marketing/static + un-migrated admin actions.

Updated timeline: 11-15 weeks for v1 (no change from previous; the iOS-only distribution is simpler than the bot-based flow).

Sign off on these and I'll drill into Phase 0 as the first bite-sized tasks (Xcode project setup, Supabase client, auth flow, RLS policies, basic app shell).

v2 (deferred, for context)

Standalone Apple Watch app
Watch face complication
iMessage extension
Vision framework → on-device chip-count (Core ML)
SharePlay → virtual attendee mode
MultipeerConnectivity → offline CC exchange
HealthKit overlay (pacing patterns)
In-app "$X left until Y breaks even" banners
On-device chip-count training (collect from v1 sessions)