docs: add architectural guardrails

.firecrawl/search-result.json

@@ -0,0 +1 @@
+{"success":true,"data":{"web":[{"url":"https://stackoverflow.com/questions/78782726/unresolved-reference-r-and-buildconfig-in-react-native-android-project-with-kot","title":"R and BuildConfig in React Native Android Project with Kotlin","description":"I'm currently working on a React Native project with Kotlin and I'm facing some issues during the build process in Android Studio.","position":1},{"url":"https://dev.to/stan6453/how-to-fix-all-build-errors-in-react-nativeandroid-specific-241f","title":"How to fix all build errors in react native(Android specific).","description":"In this article I will be showing you how to avoid all the errors I have encountered and how to avoid them or fix them in case you run across them while ...","position":2},{"url":"https://medium.com/@amanbashir601/resolving-android-build-issues-in-react-native-fixing-checkdebugaarmetadata-error-react-native-0-7-8c0a3520ca15","title":"Resolving Android Build Issues in React Native - Medium","description":"Recently, I encountered a frustrating Android build issue in our React Native project that was preventing successful builds. The problem was ...","position":3},{"url":"https://github.com/react-native-community/upgrade-support/issues/318","title":"React Native 0.78 Android won't build · Issue #318 - GitHub","description":"I can successfully get ios to build and run with 0.78 but with android, no matter what I do, I get this error: FAILURE: Build failed with an ...","position":4,"category":"github"},{"url":"https://www.reddit.com/r/reactnative/comments/1i3st0a/reactnative_app_suddenly_failign_to_build_with/","title":"react-native app suddenly failign to build with strange unresolved ...","description":"The issue is caused by an outdated Gradle version. Upgrading your Gradle wrapper and ensuring compatibility with your Android Gradle Plugin ...","position":5},{"url":"https://discuss.gradle.org/t/react-native-build-failed-after-update-build-gradle-compilesdkversion-34/48468","title":"React Native Build Failed After update build.gradle ...","description":"My React Native 0.675, using gradle 6.8.1 and dependencies classpath(“com.android.tools.build:gradle:4.1.2”) build normal before I need update to build.gradle ...","position":6},{"url":"https://community.intercom.com/intercom-mobile-app-26/react-native-android-build-failed-6315","title":"React native Android build failed - Intercom Community","description":"After installing and setting up intercom in a react native project, android build fail.I'm getting the following errorExecution failed for ...","position":7},{"url":"https://medium.com/decoded-by-kodex/solving-real-android-build-issues-in-react-native-expo-a-step-by-step-guide-6f66d240d731","title":"Solving Real Android Build Issues in React Native/Expo - Medium","description":"This post isn't just another generic Expo guide. It's a real-time log of how I built, debugged, and deployed a production React Native + Expo Android app.","position":8},{"url":"https://github.com/invertase/react-native-google-mobile-ads/issues/699","title":"[  ] Android build failed · Issue #699 · invertase/react-native ... - GitHub","description":"What happened? Android build failed with the error blow: FAILURE: Build ... Solution found here: https://stackoverflow.com/a/58602329 ...","position":9,"category":"github"},{"url":"https://www.reddit.com/r/reactnative/comments/1mwzpq2/android_build_failing_due_to_android_resource/","title":"Android build failing due to Android resource linking failed ... - Reddit","description":"Hey folks, I'm running into an issue while trying to build my React Native project on Android. The build fails with the following error: FAILURE","position":10}]}}

ARCHITECTURAL_GUARDRAILS.md

@@ -0,0 +1,181 @@
+# Architectural Guardrails — CardScannerApp
+
+> These guardrails protect the architectural integrity of CardScannerApp. All contributors and AI agents must follow them.
+
+---
+
+## 1. Tech Stack (Locked)
+
+| Layer | Technology | Version Constraint | Notes |
+|-------|-----------|-------------------|-------|
+| **Framework** | React Native (bare workflow) | 0.73.x | No Expo managed workflow |
+| **Language** | TypeScript | >= 5.0 | Strict mode enabled |
+| **Camera** | react-native-vision-camera | 4.x | Primary camera interface |
+| **Document Scanner** | react-native-document-scanner-plugin | 1.8.x | Quad detection + perspective correction |
+| **OCR** | react-native-vision-camera-mlkit | 0.4.x | Google ML Kit on-device text recognition |
+| **Image Preprocessing** | react-native-image-manipulator | 1.x | Resize to 1200px before OCR |
+| **Contact Parsing** | BCR Library (vendored) | — | Copied into `src/vendor/bcr/` |
+| **Contacts** | react-native-contacts | 7.x | Use `openContactForm`, never `addContact` |
+| **vCard Export** | react-native-vcards | 0.0.x | vCard 3.0 format |
+| **File System** | react-native-fs | 2.20.x | File I/O for vCard generation |
+| **Sharing** | react-native-share | 10.x | Native share sheet |
+| **Navigation** | @react-navigation/native + stack | — | 3-screen flow: Scan → Review → Save |
+| **E2E Testing** | Detox | 20.x | Camera bypass via deep link injection |
+| **Animation** | react-native-reanimated | 3.x | Required by vision-camera |
+| **Worklets** | react-native-worklets-core | 1.x | Required by vision-camera |
+
+### Dependency Rules
+- **Pin exact versions** — no `^` or `~` prefixes on native modules
+- **No Expo** — this is a bare React Native project. Do not introduce Expo packages
+- **No cloud OCR** — all OCR processing must remain on-device (Google ML Kit)
+- **No external analytics** — no tracking, crash reporting, or telemetry SDKs
+
+---
+
+## 2. Architecture Principles
+
+### 2.1 Four-Layer Pipeline
+```
+Camera + Doc Scan  →  On-Device OCR  →  Field Parser  →  Contact Save + vCard
+Layer 1                Layer 2           Layer 3          Layer 4
+```
+
+Each layer is **independent** and communicates only through the `ContactCard` type.
+
+### 2.2 Single Source of Truth — ContactCard
+```ts
+interface ContactCard {
+  name: string;
+  firstName: string;
+  lastName: string;
+  company: string;
+  title: string;
+  email: string;
+  phone: string;
+  address: string;
+  website: string;
+  rawOcrText: string;
+  imageUri: string;
+  scannedAt: string;
+}
+```
+- All layers produce/consume this type
+- **Never** add fields without updating all consumers
+- **Never** bypass this type for inter-layer communication
+
+### 2.3 User-in-the-Loop for Contact Writes
+- Always use `openContactForm` — never `addContact`
+- User must confirm before any contact is written to the OS address book
+- Silently writing garbled OCR output fails App Store review
+
+### 2.4 Review Screen is Mandatory
+- OCR is imperfect — always show editable fields before save
+- Every input must have `testID={field-${key}}` for E2E testing
+- No auto-save without user review
+
+---
+
+## 3. Platform-Specific Guardrails
+
+### iOS
+- **Camera orientation**: ML Kit reads sensor buffer as landscape-fixed. MUST pass `outputOrientation: 'portrait'` on iOS
+- **File URIs**: Document scanner returns `file://` prefix — strip before passing to ML Kit
+- **vCard MIME type**: Use `text/vcard`
+- **Minimum iOS**: 14.0
+
+### Android
+- **Camera orientation**: EXIF handles rotation automatically — do NOT pass `outputOrientation`
+- **File URIs**: Document scanner returns bare paths — no stripping needed
+- **vCard MIME type**: Use `text/x-vcard` (required for Outlook compatibility)
+- **Minimum SDK**: 26 (Android 8.0)
+
+### Cross-Platform
+- Always strip `file://` prefix before passing URI to ML Kit on **all** platforms (safe no-op on Android)
+- Resize images to 1200px width before OCR on both platforms
+- Never compress below 0.7 quality
+
+---
+
+## 4. Testing Guardrails
+
+### Unit Tests
+- Minimum 90% coverage threshold
+- All utility functions must have tests
+- ParserService must be tested with real card text samples
+
+### E2E Tests (Detox)
+- **Physical device required** — no camera on emulators/simulators
+- Use **deep link injection** (`cardscanner://inject?imageUri=...`) to bypass camera in tests
+- Test assets must be normalized to 1200px width
+- Required test cards:
+  - `card_standard_1200.jpg` — full fields
+  - `card_minimal_1200.jpg` — minimal fields (crash safety)
+  - `card_complex_1200.jpg` — non-standard layout
+
+### CI Requirements
+- Lint + TypeScript check on every PR
+- Unit tests with coverage enforcement
+- E2E tests for both iOS and Android
+
+---
+
+## 5. Security & Privacy
+
+- **No data leaves the device** — all processing is local
+- **No external APIs** — no cloud OCR, no analytics, no telemetry
+- **Camera permission** — only active during scan session
+- **Contacts permission** — only when user explicitly saves
+- **No network calls** — the app should function fully offline
+
+---
+
+## 6. File Structure
+
+```
+src/
+├── types/
+│   └── ContactCard.ts          # Shared type — create first
+├── services/
+│   ├── OcrService.ts           # Layer 2: ML Kit OCR
+│   ├── ParserService.ts        # Layer 3: BCR field extraction
+│   ├── ContactService.ts       # Layer 4: Save to OS contacts
+│   └── VCardService.ts         # Layer 4: vCard export + share
+├── utils/
+│   └── imagePreprocess.ts      # Image resize before OCR
+├── vendor/
+│   └── bcr/                    # Vendored BCR Library
+├── screens/
+│   ├── ScanScreen.tsx          # Layer 1: Camera + document scan
+│   ├── ReviewScreen.tsx        # Editable fields before save
+│   └── SaveScreen.tsx          # Contact save + vCard share
+└── App.tsx                     # Navigation stack
+```
+
+---
+
+## 7. Change Protocol
+
+Before making architectural changes:
+
+1. **Check this document** — does the change violate any guardrail?
+2. **Update guardrails** — if intentionally changing architecture, update this file first
+3. **Create an ADR** — for significant changes, create an Architecture Decision Record in `docs/adr/`
+4. **Update tests** — ensure E2E tests still pass with the change
+5. **Update docs** — keep `docs/ARCHITECTURE.md` in sync
+
+---
+
+## 8. Known Issues & Workarounds
+
+| Issue | Fix | Status |
+|-------|-----|--------|
+| iOS OCR text rotated | Pass `outputOrientation: 'portrait'` | ✅ Documented |
+| `file://` prefix on iOS | Strip before ML Kit on all platforms | ✅ Documented |
+| ML Kit pod fails on Apple Silicon sim | Use physical device or `arch -x86_64 pod install` | ⚠️ Workaround |
+| vCard fails in Outlook Android | Use `text/x-vcard` MIME type | ✅ Documented |
+| BCR returns empty Company | Fallback: largest non-name block | ⚠️ Workaround |
+| Detox camera on emulator | Deep link injection bypass | ✅ Documented |
+
+---
+
+*Last updated: 2026-04-05*