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)