Portal Development Standards

Tech Stack

• Frontend: React 19 + TypeScript 5.9 + Vite 7 (strict mode ON)
• Styling: Custom CSS design tokens (portal-tokens.css), NOT Tailwind in portal
• Auth: Clerk (JWT RS256, phone/email login)
• Backend: PHP (plain, no framework) on cPanel with MySQL via PDO
• State: React Context + hooks (PortalAuthContext, NotificationContext)

TypeScript Rules

• No

  any

  — use

  unknown

  and narrow with type guards
• No

  @ts-ignore

  — fix the type instead
• Prefer

  interface

  over

  type

  for object shapes
• All API responses typed in

  src/portal/types.ts

• Use discriminated unions for state (loading | error | success)

React Rules

• Functional components only, custom hooks for reusable logic (useX naming)
• No prop drilling > 2 levels — use context or composition
• useEffect only for sync with external systems (API, DOM, subscriptions)
• Never store derived state — compute inline or useMemo
• Handle loading, error, empty states in every async component
• Dialog pattern: parent owns

  showDialog

  state, dialog has

  open/onConfirm/onCancel

  props

CSS Rules (Portal)

• Use portal design tokens:

  --p-red

  ,

  --p-bg-card

  ,

  --p-border

  ,

  --p-cream

  ,

  --p-amber

  ,

  --p-text-muted

• Class naming:

  portal-{component}-{modifier}

  (e.g.

  portal-btn-primary

  ,

  portal-badge-revoked

  )
• Add reusable styles to

  portal-components.css

  , inline styles OK for one-off layout
• Responsive: test at 320px, 768px, 1024px, 1440px

PHP Backend Rules

• PDO prepared statements for ALL queries — never concatenate user input into SQL
• JSON responses:

  { success: true, data: ... }

  or

  { success: false, error: "..." }

• Function naming:

  portalVerbNoun

  (e.g.

  portalGetUsers

  ,

  portalCreateUnit

  ,

  portalRevokeUser

  )
• Always check JWT + role before data access
• Return appropriate HTTP status codes (200, 201, 400, 401, 403, 404, 500)

API Call Pattern (Frontend)

// In api.ts — all API calls go through apiFetch with auth header
// Errors thrown as Error objects, caught in component try/catch
// Always show error to user via setSaveError or setError state

Date Handling

• Storage: DDMMYYYY string (e.g. "25031999")
• Display: DD/MM/YYYY or "25 Mar 1999"
• Input:

  <DateInput>

  component (calendar picker, always DD/MM/YYYY)
• Never use raw

  <input type="date">

  — always use DateInput component

File Naming

components/     PascalCase.tsx      (DateInput.tsx, StatusBadge.tsx)
pages/          PascalCase.tsx      (DashboardPage.tsx, ViewMemberPage.tsx)
hooks/          camelCase.ts        (useNotifications.ts)
context/        PascalCase.tsx      (PortalAuthContext.tsx)
__tests__/      camelCase.test.ts   (api.test.ts)
*.ts            camelCase.ts        (api.ts, types.ts, constants.ts)
*.css           kebab-case.css      (portal-components.css)

Build Verification

Always run after changes:

npx tsc --noEmit     # Type check
npx vite build       # Production build

Key Files

• Types:

  src/portal/types.ts

• API client:

  src/portal/api.ts

• Constants & field definitions:

  src/portal/constants.ts

• Routes:

  src/portal/PortalRoutes.tsx

• Auth context:

  src/portal/context/PortalAuthContext.tsx

• Backend routes:

  api/routes/portal.php

• API router:

  api/index.php

• Design tokens:

  src/portal/portal-tokens.css

• Component styles:

  src/portal/portal-components.css

Role Hierarchy

admin > zonal_secretary > regional_president > unit_president/campus_president > member

Member Statuses

active | inactive | migrated | revoked

• inactive: reversible, stores reasons + who set it
• revoked: reversible, hidden from unit/regional, stores reason + who revoked
• Delete: permanent removal (admin/zonal only)