shihaam
2f5659f3ff
4.2 KiB
SAR Link Portal — Frontend Documentation
This folder is a reconstruction spec for the SAR Link Portal frontend: enough detail to rebuild the app screen-by-screen in any framework. It documents the UI, user flows, API endpoints, design system, and all hardcoded copy.
What the app is
A customer + admin portal for an ISP (SAR Link by OmegaTech Solutions). Customers register (identity-verified against the national registry), add network devices, and pay for device subscriptions by bank transfer (MIB) or from a prepaid wallet. Admins verify users and manage devices, payments, topups, and wallet credits.
Index
| Doc | What's in it |
|---|---|
| architecture.md | Stack, folder map, current (BFF) vs target (static + nginx + API_URL) architecture, auth model, deployment, cleanup list |
| design-system.md | Brand color (sarLinkOrange #f49b5b), theme tokens, fonts (Barlow/Bokor), dark mode, status colors, reusable layout patterns, app shell |
| navigation.md | Full sidebar menu tree (labels, icons, routes, permissions), user vs admin visibility, other nav entry points |
| routes.md | Every route/page: URL, purpose, components, guards, loading states |
| components.md | Component catalog by feature area + conventions |
| user-flows-and-state.md | End-to-end flows (register, login, buy/pay device, topup, parental control, admin) + Jotai atoms + React Query + auth/token storage |
| api-endpoints.md | Every backend endpoint: method, path, purpose, request/response, auth, + dead-code list |
| ui-copy.md | Every hardcoded string (headings, buttons, placeholders, toasts, validation, bank/brand/contacts) for i18n |
Related, outside this folder: ../STATIC_MIGRATION_PLAN.md (in-progress static-export migration), .build/prod/ (production compose + nginx).
How to recreate the app from these docs
- Scaffold the target stack (recommended: Vite + React + TanStack/React Router + Tailwind v4 + shadcn/ui
new-yorkneutral + lucide). See architecture.md. - Theme it from design-system.md — brand color, fonts, tokens,
title-bg, status colors, dark mode. - Build the shell — sidebar (navigation.md) + header (wallet / theme / account) + auth-page card layout (design-system.md).
- Auth — implement the login flow and token store from user-flows-and-state.md using
API_URL; guard routes. - Routes — create every screen in routes.md; compose from components.md.
- Data — wire each screen to its endpoints in api-endpoints.md via React Query; carry over the response envelope + status conventions.
- Copy — pull all visible text from ui-copy.md (fix the noted typos; set up i18n keys).
- Flows — validate the six end-to-end flows in user-flows-and-state.md.
Key facts to carry over
- API base is configurable:
API_URL=http://localhost:8000(dev) /https://portal.sarlink.net/api(prod, nginx → Django). Same build, both environments. - Auth: Knox token from
POST /callback/auth/, stored in localStorage, sent asAuthorization: Token <token>;401→ signin. - Two-tier UI: desktop tables + mobile cards for every list; filters/pagination via URL query params.
- Payments: device payments and wallet both verify via the same endpoint with a
method(TRANSFER/WALLET); MIB verification is server-side — the frontend only sends the method and shows hardcoded bank details. - Admin gating:
user.is_admin/user.user_permissions. - Dead code exists — don't port Omada, Invoice Ninja, next-auth routes, or the unused axios helpers (see api-endpoints.md).
Provenance
Compiled from a full read of app/, components/, actions/, queries/, lib/, and config. The app is mid-migration from the Node/BFF model to a static build — docs describe current behavior and flag migration deltas inline.