Complete & Testflight iStockHomes iOS App

ISTOCKHOMES iOS (Xcode/SwiftUI) APP — FINISH + CONNECT TO LIVE DB + TESTFLIGHT
Client: Istockhomes
Project Name: IstockhomesXcodeV1
Platform: iOS (SwiftUI, Xcode)

========================
1) THE ONE-SENTENCE GOAL
========================
Deliver a TestFlight-ready iOS app that is FULLY LIVE + DATABASE-DRIVEN using https://istockhomes.com/App/api/index.php (and /App/api endpoints), including signup, login, email verification (6-digit code), Face ID, franchise creation, dynamic franchise branding header from database, and an operational dashboard with listings create/view.

=========================================
2) HARD REQUIREMENT: REAL API + REAL DATA
=========================================
- NO dummy JSON.
- NO “local mock data”.
- All core functions MUST call the live Istockhomes API and write/read real records in the database.
- If any needed endpoint doesn’t exist, YOU must implement it server-side (PHP in /App/api/) and document it.

====================================
3) EXISTING REQUIREMENTS (DO NOT BREAK)
====================================
- App is SwiftUI using NavigationStack patterns already.
- Existing LoginView.swift is already working and MUST NOT be rewritten/removed.
- BlackButtonStyle in ButtonStyles.swift is the ONLY button style used throughout the app.
- Keep UI clean, simple, mobile-first. No redesign rabbit holes.

===================================
4) REQUIRED FEATURES (MUST DELIVER)
===================================

A) AUTH
------
1) Signup (API-backed)
- Create a new user account via API (name, email, password minimum)
- New signups default to role: "user"
- After signup, user MUST be forced into email verification flow

2) Email Verification (6-digit code)
- API sends a 6-digit code to user’s email
- App UI allows entering the code
- API verifies the code
- Only verified users can access Dashboard

3) Login
- Login via API
- Receive token/session
- Store token securely in Keychain
- Persist login state with token validation

B) FACE ID (BIOMETRICS)
-----------------------
- After first successful login, user can enable Face ID on this device
- Next app launch: Face ID prompt unlocks the app session (token-based)
- If Face ID fails: fallback to normal login
- Never store the raw password

C) DASHBOARD (OPERATIONAL)
--------------------------
After verified login:
- Show a real working dashboard (not placeholders)
- Must include these buttons EXACTLY:
1) Add a Business
2) Add a Franchise
3) Add a Listing
4) View My Listings
- Dashboard should display:
- Current user info
- Selected franchise (if any)
- Branding header

D) FRANCHISE SYSTEM
-------------------
- Users can add/manage multiple franchises.
- “Add Franchise” must POST to DB via API.
Minimum franchise fields:
- franchise_name
- contact_name
- phone
- email
- optional: logo upload (preferred)
After franchise creation:
- App must select a franchise and load branding dynamically.

E) DYNAMIC FRANCHISE BRANDING HEADER (FROM DB)
----------------------------------------------
- Header (logo + branding) MUST load dynamically from database values via API
- No hardcoded franchise images/colors
- Branding affects (minimum):
- Header logo
- Accent/theme values (as feasible)
- Optional: contact display

F) LISTINGS (MINIMUM TESTFLIGHT FUNCTIONAL)
-------------------------------------------
Must be fully API/DB-backed:
1) Add Listing
- Simple listing form: title, price, category, description, location fields (minimum)
- Upload 1+ images (support .webp if backend supports)
- Save listing to DB via API

2) View My Listings
- Fetch the logged-in user’s listings from DB via API
- List view + detail view
- Show: primary image, title, price, category, status

=========================================
5) REQUIRED DOCUMENTATION (MUST DELIVER)
=========================================

A) API_MAP.md (MANDATORY)
- A file listing EVERY endpoint used, with:
- URL
- method (GET/POST)
- request params/body
- response example
- errors returned
- where it is used in the app (file/screen)

B) SETUP_AND_TESTFLIGHT.md (MANDATORY)
- Exact steps to:
- Build/run locally
- Configure base URL
- Create a test user
- Verify email flow
- Enable Face ID
- Create franchise & confirm branding load
- Create listing & confirm listings show
- Archive and upload to TestFlight (or instructions if I upload)

======================================
6) TESTFLIGHT DELIVERY (MUST BE PROVEN)
======================================
You must deliver an Xcode project that I can upload to TestFlight immediately.

You will provide one of these:
Option A (preferred):
- You work inside my Apple Developer account (I add you)
- You produce Archive + upload to App Store Connect

Option B:
- You deliver a project configured so I can Archive + upload myself
- You provide all signing + bundle identifier instructions

Must include:
- App icons (basic set is fine)
- Correct bundle id and versioning (v1.0 build 1 minimum)
- Clean build (no warnings that matter, no crashes)

========================================
7) TECHNICAL REQUIREMENTS (NON-NEGOTIABLE)
========================================
- SwiftUI + MVVM
- URLSession networking layer (APIClient)
- Typed models for JSON
- Keychain for token storage
- LocalAuthentication for Face ID
- Proper error handling (user friendly messages)

No external dependencies unless approved and documented.

==========================================
8) ACCEPTANCE CHECKLIST (PASS/FAIL TEST)
==========================================
PASS only if all items below work on a real device:
[ ] Signup works (creates DB user)
[ ] Email verification sends code
[ ] Code verify unlocks dashboard
[ ] Login works and persists token
[ ] Face ID unlock works after first login
[ ] Dashboard loads and buttons function
[ ] Add Franchise writes to DB
[ ] Branding header loads from DB dynamically
[ ] Add Listing writes to DB with image upload
[ ] View My Listings reads real DB data
[ ] API_MAP.md delivered
[ ] SETUP_AND_TESTFLIGHT.md delivered
[ ] TestFlight-ready archive path proven

==========================================
9) MILESTONES (RECOMMENDED PAYMENT STRUCTURE)
==========================================
Milestone 1 (25%)
- Project builds, APIClient, login end-to-end (real token)

Milestone 2 (25%)
- Signup + email verification fully working

Milestone 3 (25%)
- Face ID + franchise create/select + dynamic branding header

Milestone 4 (25%)
- Listings create/view + documentation + TestFlight-ready build

====================================
10) RED LINES (DO NOT DO THESE)
====================================
- Do not rebuild the app from scratch
- Do not remove/replace working LoginView.swift
- Do not use dummy JSON or local-only data
- Do not hardcode franchise branding
- Do not expand scope without approval

==========================================
11) WHAT YOU (DEVELOPER) MUST ASK ME FOR ON DAY 1
==========================================
You must request these immediately:
1) The Xcode project zip OR GitHub access
2) Base API details for /App/api/index.php and any existing endpoints
3) A test account (or you create one via signup)
4) Confirmation of required endpoints:
- signup
- login
- send verification code
- verify code
- create franchise
- get branding
- create listing
- upload image
- list my listings

If any endpoint is missing, you must implement it server-side in /App/api/ and document it.

==========================================
END OF BRIEF
==========================================