# Onboarding — As-Saaliyah

A guided tour for a developer joining this repo. ~15 minutes to a running stack.

## 1. The mental model

Two projects, one HTTP boundary:

```
Flutter app  ──HTTP──>  Next.js website (= UI + backend API)  ──>  Neon Postgres
   app/                          website/
```

- `website/` owns the database and exposes a small JSON API.
- `app/` is a pure client of that API; it never touches the DB.
- The **domain** (what an "activity" is, recurrence rules, scheduling, the
  three languages) is written twice — TypeScript in
  `website/src/domain`, Dart in `app/lib/features/daily_activities/domain` —
  and kept behaviourally identical. Change one, change the other.

## 2. Prerequisites

- Node ≥ 20 and `pnpm` (`corepack pnpm@9 …` works if pnpm isn't global).
- Flutter ≥ 3.41 / Dart ≥ 3.11 (`flutter doctor`).
- A free [Neon](https://neon.tech) Postgres project (for the website DB).

## 3. Run the backend + website

```bash
cd website
cp .env.example .env        # paste Neon DATABASE_URL (pooled) + DIRECT_URL
pnpm install
pnpm db:push                # creates CustomActivity + Completion tables
pnpm dev                    # http://localhost:3000
```

Sanity checks:
- Open `http://localhost:3000` → the Daily Activities web UI.
- `curl http://localhost:3000/api/activities/presets` → `{"data":[…]}`.

## 4. Run the app

```bash
cd app
flutter pub get
flutter run --dart-define=API_BASE_URL=http://localhost:3000
```

- Android emulator → host is `http://10.0.2.2:3000` (the built-in default).
- Physical device → use your machine's LAN IP.
- No backend? The app still runs from its offline cache (empty on first launch).

## 5. Where things live

| You want to… | Go to |
|---|---|
| Change the preset activities | `website/src/domain/daily-activities/presets.ts` |
| Change recurrence/scheduling rules | `website/src/domain/daily-activities/schedule.ts` **and** `app/lib/features/daily_activities/domain/usecases/scheduling.dart` |
| Add an API endpoint | `website/app/api/**/route.ts` (+ `src/lib/prisma.ts`) |
| Change the DB shape | `website/prisma/schema.prisma` → `pnpm db:push` |
| Add an app screen/feature | `app/lib/features/<f>/{domain,data,presentation}` + register in `core/di/injection.dart` + route in `core/routes/app_router.dart` |
| Add/adjust UI translations | `website/src/features/daily-activities/strings.ts` and `app/lib/core/constants/app_strings.dart` |

## 6. Conventions

- **Preset vs custom:** presets are code-defined and shipped to everyone
  (toggleable, not editable); custom activities are user-created and persisted
  per `userId`. The API returns both as the same `ActivityDefinition` shape.
- **API envelope:** success = `{ "data": … }`, error = `{ "error": "…" }`.
- **Dates** are location-local `YYYY-MM-DD`; weekday numbering is JS-style
  (0 = Sunday … 6 = Saturday) on both sides — keep it that way.
- **Offline-first (app):** writes apply to local cache immediately, then sync
  best-effort. Don't block the UI on the network.
- **Domain purity:** no React/Next imports in `website/src/domain`; no
  Flutter/Dio imports in the app's `domain/` layer.

## 7. Verify your setup

```bash
cd website && pnpm typecheck && pnpm test && pnpm build   # all green
cd ../app  && flutter analyze                              # "No issues found!"
```

## 8. What's next (not built yet)

Prayer-time calculation (`adhan`) feeding real anchor ordering, Hijri calendar
(replacing the manual "Ramadan mode" switch), Quran/Hadith + hifz modules,
push reminders, accounts & cross-device sync, AI-guided Arabic learning, and
micro-billing. Each is a new `features/<f>` slice on the app and a matching
`src/domain` + `app/api` addition on the website.