docs(sayd-mobile): add full planning suite for the member app proposal

Four-pillar decomposition (membership/money, activities, events, gate/invitations)
with data model, API spec, UX/motion system, and delivery plan.

Proposal/sayd-mobile/docs/00-overview.md

+# Sayd Mobile — Product & Architecture Overview
+
+> Planning suite for the نادي الصيد المصري member mobile app.
+> Companion to the commercial proposal (`../عرض تطبيق الاعضاء.md`).
+
+## Document map
+
+| Doc | Contents |
+|-----|----------|
+| `00-overview.md` | This file — vision, principles, scope, architecture |
+| `01-feature-catalog.md` | **The core deliverable.** Every pillar exploded into numbered, executable features |
+| `02-data-model.md` | Postgres schema, DDL, state machines |
+| `03-api-spec.md` | Full REST surface, auth, error contract |
+| `04-app-ux-motion.md` | Screen inventory, navigation, and the motion/animation design system |
+| `05-portal-infra-delivery.md` | Staff portal screens, Heroku infra, CI/CD, sprint plan, open questions |
+
+## Repositories
+
+| Repo | Purpose |
+|------|---------|
+| `root/sayd-mobile-app` | Flutter client (iOS 14+, Android 8+), Arabic-first RTL |
+| `root/sayd-mobile-portal` | PHP 8.1+ backend API + staff web portal, Postgres, Heroku |
+
+---
+
+## 1. What we are actually selling
+
+A **member-facing mobile app** backed by a **deliberately flat** management portal.
+
+The backend's entire responsibility is:
+1. Hold a read-optimized copy of member / family / dues / activity data (fed by Excel upload, then maintained through simple screens).
+2. Take money and emit **invoices and receipts**.
+3. Issue and verify **QR codes** (gate entry + guest invitations + event tickets).
+4. Show **primitive reports** — a collections dashboard and CSV exports. Nothing more.
+
+It is **not** an ERP. No general ledger, no journal entries, no HR, no inventory, no procurement, no POS,
+no approval-chain workflow engine. The ClubPHP ERP is referenced in these docs only where it teaches us
+what a real club workflow looks like (installment interest, medical-cert clearance levels, invitation
+quotas). It is **not** an architectural template and none of its code or schema is reused.
+
+The differentiator we are selling is not feature count — it is that **the member-facing experience is
+exceptional**: fast, Arabic-native, and genuinely beautifully animated. Budget the craft accordingly
+(see `04-app-ux-motion.md`).
+
+---
+
+## 2. Product principles
+
+These are binding. When a new feature request arrives, test it against these before saying yes.
+
+1. **Flat, not ERP.** If a feature needs double-entry accounting, multi-step approval chains, or
+   role-permission matrices beyond ~5 staff roles — it is Phase 2. Say so explicitly rather than
+   half-building it.
+2. **Excel in, receipt out.** Every dataset must be re-importable from a CSV template. Even after the
+   portal grows CRUD screens, bulk re-upload stays a first-class path — that is the club's actual muscle
+   memory and our migration safety net.
+3. **One phone number = one identity.** No passwords, no self-registration, no staff account activation.
+   The mobile number on the uploaded roster *is* the authentication substrate.
+4. **Every money path ends in the same receipt object.** Renewal, installment, fine, activity fee, event
+   ticket, extra invitation — six sources, one payment engine, one receipt. Never let a pillar grow its
+   own payment integration.
+5. **Every person is independently addressable.** The member, the spouse, and *each child* has their own
+   status, own QR, own medical certificate, own attendance record. Never model the family as one unit
+   with one state.
+6. **Motion budget goes to moments, not to lists.** Balance reveals, payment success, QR pulse, medical
+   status transitions, card flips — these get lavish treatment. List screens stay instant and legible.
+7. **Offline-tolerant where it hurts.** The gate QR must render with no connectivity. Statement and card
+   data must render from cache. Payment must never be attempted offline.
+8. **Idempotent by default.** Billing jobs, payment intents, and CSV imports all re-run safely. This is
+   non-negotiable — it is the difference between a trusted system and a support nightmare.
+
+---
+
+## 3. Scope boundary (restated so it cannot drift)
+
+### In scope — Phase 1
+The four pillars in `01-feature-catalog.md`, plus the cross-cutting systems (auth, payments, ingestion,
+notifications, reporting).
+
+### Out of scope — Phase 2 candidates
+Facility/court/pool booking · in-club wallet & stored balance · restaurant/cafeteria ordering ·
+chalets & seasonal village bookings · support ticketing · achievements/gamification · tournament brackets
+& live match center · full accounting · HR & payroll · inventory & procurement · in-club POS.
+
+**Specific creep risks to watch** (each is a real gravitational pull from inside a Phase-1 pillar):
+- Gate access → *facility booking*. Scanning a QR at a gate is not the same product as reserving a court.
+- Coach evaluation → *full athlete performance management*. Show the evaluation; don't build the analytics suite.
+- Paid events → *generic e-commerce*. Events have fixed inventory and a roster; that's it.
+- Collections dashboard → *BI tool*. Six revenue lines and a CSV export. Stop there.
+
+---
+
+## 4. Architecture at a glance
+
+```
+┌──────────────────────────┐         ┌──────────────────────────────┐
+│   Flutter app (member)   │         │  Gate scanner (web, tablet)  │
+│   iOS 14+ / Android 8+   │         │  PWA, camera, offline queue  │
+└───────────┬──────────────┘         └───────────────┬──────────────┘
+            │ HTTPS/JSON, Bearer token               │
+            └──────────────┬─────────────────────────┘
+                           ▼
+        ┌──────────────────────────────────────────┐
+        │  PHP 8.1+ API  (sayd-mobile-portal)      │
+        │  • /api/v1/*   member API                │
+        │  • /api/gate/* scan API (low latency)    │
+        │  • /portal/*   staff web UI (HTML/CSS/JS)│
+        │  • /jobs/*     scheduled billing + jobs  │
+        └───────┬──────────────────────┬───────────┘
+                │                      │
+        ┌───────▼────────┐    ┌────────▼─────────────────────────┐
+        │  PostgreSQL    │    │ External: payment gateway,       │
+        │  (Heroku PG)   │    │ FCM/APNs push, SMS provider,     │
+        └────────────────┘    │ S3-compatible object storage     │
+                              └──────────────────────────────────┘
+```
+
+**Stack decisions and why:**
+
+| Layer | Choice | Rationale |
+|-------|--------|-----------|
+| Mobile | Flutter | One codebase, both stores, and the animation primitives we need for the "sexy" mandate are first-class. |
+| Backend | PHP 8.1+, no framework | Matches the team's existing muscle memory (ClubPHP is hand-rolled PHP). A flat backend does not justify a framework's weight. Plain PDO + a thin router + a template layer. |
+| DB | PostgreSQL | Heroku-native. We rely on JSONB (custom event forms, config blobs), partial indexes, and proper `timestamptz` — all things MySQL handles worse. |
+| Host | Heroku | Managed, fast to ship, review apps for staging. Accepted trade-off: dyno cold starts and egress region (see infra doc for the Egypt-latency note). |
+| Storage | S3-compatible | Medical certs, receipts, event images, member photos. Never on the dyno filesystem — it's ephemeral. |
+| Portal UI | HTML/CSS/JS, no SPA framework | ~15 staff screens, mostly forms and tables. A build step would cost more than it returns. |
+
+---
+
+## 5. The four pillars
+
+| # | Pillar | Promise | Catalog section |
+|---|--------|---------|-----------------|
+| 1 | **Membership & Money** | See my and my family's membership status, dues, installments and fines — and pay them. | F1 |
+| 2 | **Sports Activities** | Browse and join activities, upload medical certificates, track attendance and coach evaluations. | F2 |
+| 3 | **Club Life & Paid Events** | Read club news, and book & pay for paid events (trips, Umrah, etc.). | F3 |
+| 4 | **Gate & Invitations** | Enter via personal QR (mine or any child's), and buy extra guest invitations past my monthly quota. | F4 |
+| — | **Cross-cutting** | Auth, payments, ingestion, notifications, reporting, platform. | F5–F9 |
+
+---
+
+## 6. How to read the feature catalog
+
+Every feature carries an ID (`F1.2.3`), a priority, and acceptance criteria.
+
+| Priority | Meaning |
+|----------|---------|
+| **P0** | Ship-blocking. The pillar is not deliverable without it. |
+| **P1** | Required for a credible launch. Cut only under schedule emergency, with the club's sign-off. |
+| **P2** | High-value polish. Ship if the schedule holds. |
+| **P3** | Explicitly deferred to Phase 2 — listed so it is recorded, not forgotten. |
+
+Estimates are in **engineer-days** and assume one senior full-stack engineer plus one Flutter engineer
+working in parallel. They cover build + self-test, not QA cycles or client review latency.