sarlinkportal-webui/docs/routes.md

# Routes & Pages

Next.js App Router. Route groups `(auth)` and `(dashboard)` do **not** appear in the URL. Dynamic segments in `[brackets]`.

## Route table

| Folder | URL | Page | Audience |
|---|---|---|---|
| `/` | `/` | Home (redirect guard) | any |
| `(auth)/auth/signin` | `/auth/signin` | Sign In (phone) | public |
| `(auth)/auth/signup` | `/auth/signup` | Sign Up | public |
| `(auth)/auth/verify-otp` | `/auth/verify-otp` | Verify OTP (login) | public |
| `(auth)/auth/verify-otp-registration` | `/auth/verify-otp-registration` | Verify OTP (registration) | public |
| `(dashboard)/devices` | `/devices` | My Devices | user |
| `(dashboard)/devices/[deviceId]` | `/devices/{id}` | Device Details | user |
| `(dashboard)/devices-to-pay` | `/devices-to-pay` | Devices to Pay | user |
| `(dashboard)/parental-control` | `/parental-control` | Parental Control | user |
| `(dashboard)/payments` | `/payments` | My Subscriptions | user |
| `(dashboard)/payments/[paymentId]` | `/payments/{id}` | Payment Details | user |
| `(dashboard)/top-ups` | `/top-ups` | My Topups | user |
| `(dashboard)/top-ups/[topupId]` | `/top-ups/{id}` | Topup Details | user |
| `(dashboard)/wallet` | `/wallet` | Transaction History | user |
| `(dashboard)/agreements` | `/agreements` | Agreements | user |
| `(dashboard)/price-calculator` | `/price-calculator` | Price Calculator | user (admin-nav) |
| `(dashboard)/profile` | `/profile` | Profile | user |
| `(dashboard)/user-devices` | `/user-devices` | All User Devices | admin |
| `(dashboard)/user-payments` | `/user-payments` | All User Payments | admin |
| `(dashboard)/user-topups` | `/user-topups` | All User Topups | admin |
| `(dashboard)/users` | `/users` | Users Management | admin |
| `(dashboard)/users/[userId]/details` | `/users/{id}/details` | User Details | admin |
| `(dashboard)/users/[userId]/update` | `/users/{id}/update` | User Update / Verify | admin |
| `(dashboard)/users/[userId]/agreement` | `/users/{id}/agreement` | User Agreement Upload | admin |

## Layouts & special files

- **`app/layout.tsx`** (root) — html/body, fonts, providers: Jotai `Provider`, `NextTopLoader`, `Toaster`, `ThemeProvider`, `QueryProvider`. Metadata: "SAR Link Portal".
- **`app/(auth)/auth/layout.tsx`** — centered full-screen card layout for all auth pages.
- **`app/(dashboard)/layout.tsx`** — `RouteGuard` → `ApplicationLayout` (sidebar+header shell) → `QueryProvider` → children.
- **`app/(dashboard)/error.tsx`** — dashboard error boundary ("Something went wrong!" + Try again).
- **`loading.tsx`** files — `devices`, `devices/[deviceId]`, `devices-to-pay`, `payments`, `payments/[paymentId]`, `parental-control` (skeletons / loaders).

## Auth & onboarding

- **`/auth/signin`** — `LoginForm`. Enter phone number. `signin()` action checks the number: unknown → redirect `/auth/signup?phone_number=`; known+unverified → "pending verification" message; known+verified → sends OTP (`/auth/mobile/`) → `/auth/verify-otp?phone_number=`.
- **`/auth/signup`** — `SignUpForm`. Full registration (name, ID card, atoll/island, address, DOB, account no, phone, terms/policy). Requires `?phone_number=`. On submit → register → `/auth/verify-otp-registration`.
- **`/auth/verify-otp`** — `VerifyOTPForm` (client, `useSearchParams` in Suspense). Enter 6-digit PIN → `POST /callback/auth/` → stores token+user → `/devices`. Redirects to `/auth/signin` if no `phone_number`.
- **`/auth/verify-otp-registration`** — `VerifyRegistrationOTPForm`. Verifies registration OTP; validates the temp record. On success → `/auth/signin` (account stays pending admin verification; no auto-login).

## Dashboard — user

All wrapped by `RouteGuard` (redirects to `/auth/signin` if not authenticated).

- **`/devices`** — `DevicesTable` + `DynamicFilter` + add-device dialog. List of the user's devices; filter by name/MAC/vendor; paginated.
- **`/devices/{id}`** — single device: name, MAC, status badge, expiry.
- **`/devices-to-pay`** — `DevicesForPayment`: devices selected in the cart, choose number of months, create a payment.
- **`/parental-control`** — `DevicesTable` with `parentalControl` mode, filtered to active devices with no pending payment; block/unblock devices.
- **`/payments`** — `PaymentsTable` + filters (status, method, months). The user's subscriptions.
- **`/payments/{id}`** — payment detail: status, expiry countdown (if pending), covered devices (`DevicesToPay`), cancel button, pay via wallet/transfer.
- **`/top-ups`** — `TopupsTable` + filters (status, expiry, amount). Wallet top-ups.
- **`/top-ups/{id}`** — topup detail: status, countdown, `TopupToPay` (bank details + "I have paid"), cancel.
- **`/wallet`** — `WalletTransactionsTable`: debit/credit history with totals.
- **`/agreements`** — `AgreementCard`: user's service agreement (fetched from profile), Print/View.
- **`/price-calculator`** — `PriceCalculator`: interactive pricing tool.
- **`/profile`** — read-only profile fields + verification status badge. (Recently restyled to non-editable display.)

## Dashboard — admin

All additionally check `is_admin`; non-admins are redirected (to `/devices` or the user-equivalent page).

- **`/user-devices`** — `AdminDevicesTable`: all devices system-wide; filter incl. by device user; block/unblock with reason.
- **`/user-payments`** — `UsersPaymentsTable`: all payments; filters (user, MIB ref, amount, duration, status, method).
- **`/user-topups`** — `AdminTopupsTable`: all topups; filters (user, status, expiry, amount); admin manual top-up.
- **`/users`** — `UsersTable`: all users; filters (name, ID card, house, phone, verified status).
- **`/users/{id}/details`** — DB vs **National registry** comparison (via `getNationalPerson`), photo, verify/reject actions, links to update/agreement.
- **`/users/{id}/update`** — `UserUpdateForm`: edit/verify user info.
- **`/users/{id}/agreement`** — `UserAgreementForm`: upload/replace the user's agreement PDF.

## Guards summary

- Unauthenticated → `RouteGuard` / root redirect send to `/auth/signin`.
- Admin pages → `is_admin` check; redirect to the user equivalent.
- `401 UNAUTHORIZED` from the API → redirect `/auth/signin` (via api-client interceptor).

> Migration note: several dashboard pages still read auth server-side (`getServerSession`); see [architecture.md](./architecture.md) and [user-flows-and-state.md](./user-flows-and-state.md) for the in-progress move to the client token store.