docs: add architecture guide and reorganize docs

packages/mobile-sdk-alpha/README.md

@@ -49,7 +49,11 @@ const nfc = parseNFCResponse(rawBytes);
 
 ## Migration checklist
 
-Track progress in [MIGRATION_CHECKLIST.md](./MIGRATION_CHECKLIST.md).
+Track progress in [MIGRATION_CHECKLIST.md](./docs/MIGRATION_CHECKLIST.md).
+
+## Architecture checklist
+
+Plan implementation with [ARCHITECTURE.md](./docs/ARCHITECTURE.md) and task prompts in [ARCHITECTURE_PROMPTS.md](./docs/ARCHITECTURE_PROMPTS.md).
 
 ## Dev scripts
 

packages/mobile-sdk-alpha/docs/ARCHITECTURE.md

@@ -0,0 +1,27 @@
+# Architecture
+
+> Detailed task prompts are listed in [ARCHITECTURE_PROMPTS.md](./ARCHITECTURE_PROMPTS.md).
+
+## Overview
+
+The alpha SDK follows an adapter-first, React Native–oriented design. Tree-shakable named exports and `"sideEffects": false` keep bundles lean. While React Native is the only supported platform today, the structure below leaves room to add web, Capacitor, or Cordova targets without major refactors.
+
+## Architecture Checklist (easy → hard)
+
+1. **Modular feature directories** – group new capabilities (e.g., `liveness/`, `detection/`) in their own folders and re-export from `src/index.ts`.
+2. **Bridge layer for native events** – wrap `NativeModules`/`NativeEventEmitter` so features register listeners through a shared adapter.
+3. **Exception classes** – add typed errors (`InitError`, `LivenessError`, etc.) and surface them instead of generic `Error`.
+4. **SDK lifecycle management** – evolve `createSelfClient` into an SDK class with `initialize`/`deinitialize` and stored config.
+5. **Package targets** – keep React Native build first, but scaffold entry points for web and future environments (Capacitor/Cordova).
+6. **Dogfood in `/app`** – integrate the SDK into the monorepo's `app` workspace to validate real flows.
+7. **Android demo app** – ship a minimal React Native Android project demonstrating MRZ → NFC → proof generation.
+
+## Working in Parallel
+
+Architecture tasks above can proceed alongside the SDK migration checklist. Steps completed in the migration doc (currently through step 2) unblock items 3–5, so teams can tackle architecture and migration independently.
+
+## Additional Notes
+
+- Favor small, sensical abstractions over premature generality.
+- Maintain tree-shakability by avoiding side effects in new modules.
+- Document new APIs and flows under `docs/` as they solidify.

packages/mobile-sdk-alpha/docs/ARCHITECTURE_PROMPTS.md

@@ -0,0 +1,88 @@
+# Architecture Prompts
+
+Each item from the architecture checklist expands into concrete tasks. Pick items independently to parallelize work.
+
+> **Note**: This document uses standard Markdown `<details>` and `<summary>` tags for collapsible sections.
+
+## Pre-flight checks
+
+Run these commands before committing changes:
+
+```bash
+yarn workspace @selfxyz/mobile-sdk-alpha nice
+yarn workspace @selfxyz/mobile-sdk-alpha build
+yarn workspace @selfxyz/mobile-sdk-alpha types
+yarn workspace @selfxyz/mobile-sdk-alpha test
+yarn lint
+yarn build
+```
+
+## 1. Modular feature directories
+
+<details>
+<summary><strong>Split features into dedicated folders</strong></summary>
+
+1. Under `src/`, create folders like `liveness/` and `detection/` as features are added.
+2. Re-export feature APIs from `src/index.ts` to keep tree shaking intact.
+
+</details>
+
+## 2. Bridge layer for native events
+
+<details>
+<summary><strong>Introduce shared event bridge</strong></summary>
+
+1. Add `src/bridge/nativeEvents.ts` wrapping `NativeModules` and `NativeEventEmitter`.
+2. Expose `addListener` and `removeListener` helpers so modules can register without touching React Native directly.
+
+</details>
+
+## 3. Exception classes
+
+<details>
+<summary><strong>Add typed error hierarchy</strong></summary>
+
+1. Create `src/errors/` with classes like `InitError` and `LivenessError` extending `Error`.
+2. Replace generic throws with these classes and document them in the README.
+
+</details>
+
+## 4. SDK lifecycle management
+
+<details>
+<summary><strong>Move to an SDK class</strong></summary>
+
+1. Convert `createSelfClient` into a class exposing `initialize()` and `deinitialize()`.
+2. Store configuration and adapters on the instance to avoid global state.
+
+</details>
+
+## 5. Package targets
+
+<details>
+<summary><strong>Scaffold additional entry points</strong></summary>
+
+1. Add build outputs for web, Capacitor, and Cordova under `dist/`.
+2. Configure `package.json` `exports` to point to the new bundles.
+
+</details>
+
+## 6. Dogfood in `/app`
+
+<details>
+<summary><strong>Integrate with monorepo app</strong></summary>
+
+1. Add `@selfxyz/mobile-sdk-alpha` to `app/package.json` and wire flows to use the SDK.
+2. Validate builds and tests in the `app` workspace.
+
+</details>
+
+## 7. Android demo app
+
+<details>
+<summary><strong>Provide minimal Android sample</strong></summary>
+
+1. Under `samples/android/`, scaffold a basic React Native project showing MRZ → NFC → proof generation.
+2. Document setup steps in `samples/android/README.md`.
+
+</details>