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 and user-flows-and-state.md for the in-progress move to the client token store.