Portal Dev

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)