React Ant Design Frontend

React + Ant Design Frontend Skill

Tech Stack

Project Structure

apps/web/src/
├── App.tsx                # Root routing (public + protected routes)
├── main.tsx               # Entry: Sentry, i18n, BrowserRouter, AuthProvider, ThemeProvider
├── auth/                  # AuthContext, RequireAuth, RequireRole, auth.types
├── components/            # Shared: ErrorBoundary, EventModal, ExportButton, ImageUpload, LoadingSkeleton, ScoreEditModal
├── lib/
│   ├── api.ts             # Axios instance with token refresh interceptor
│   └── i18n.ts            # i18next config (vi/en, localStorage detection)
├── locales/
│   ├── vi.ts              # Vietnamese translations (~1,244 lines)
│   └── en.ts              # English translations (~1,207 lines)
├── pages/                 # All page components (PascalCase)
│   ├── __tests__/         # Page component tests
│   ├── match-detail/      # MatchDetailPage sub-components
│   └── reports/           # ReportsPage tab sub-components
├── services/              # API service modules (camelCase)
│   └── __tests__/         # Service tests
├── shell/
│   ├── AppShell.tsx       # Protected layout (Sider + Header + Content)
│   ├── PublicLayout.tsx   # Public layout (gradient header + footer)
│   ├── ThemeContext.tsx    # Dark/light mode context
│   └── menu.ts            # Role-based menu items (12 items)
└── utils/
    └── constants.ts       # STATUS_MAP, EVENT_TYPE_MAP, POSITION_MAP, CAN_EDIT_ROLES

All Pages & Routes

Public (No Auth)

Public Layout (PublicLayout)

Protected (RequireAuth + AppShell)

All Services & API Methods

authApi.ts (17 functions)

teamApi.ts

playerApi.ts

stadiumApi.ts

seasonApi.ts

seasonTeamApi.ts

matchApi.ts

scheduleApi.ts

standingsApi.ts

searchApi.ts

regulationApi.ts

userApi.ts

uploadApi.ts

http.ts (LEGACY — not used)

fetch-based HTTP client. All active services import from lib/api.ts (Axios) instead.

Shared Components (src/components/)

Page Sub-Components

Auth Flow

Types (auth/auth.types.ts)

User { id, email, role, name? }
AuthState { user, accessToken, isAuthed }
AuthContextValue = AuthState & { login, logout, applyOAuthTokens }

AuthContext (auth/AuthContext.tsx)

• Access token: in-memory only (NEVER in localStorage)
• Refresh token: in localStorage for persistence
• Bootstrap: On mount → silent refresh via /auth/refresh → decode JWT for User
• Login: POST /auth/login → stores both tokens
• OAuth: applyOAuthTokens(at, rt) → decode JWT → set user
• Logout: POST /auth/logout → clears both tokens
• Session expiry: Listens for auth:expired custom event

Token Refresh (lib/api.ts)

• Axios response interceptor on 401 → attempts refresh using stored RT
• Queues concurrent failing requests during refresh (only one refresh runs at a time)
• Dispatches auth:expired custom event when refresh fails
• Also handles 429 → dispatches api:rate-limited custom event

Route Guards

• RequireAuth: Redirects to /login if !isAuthed, preserves intended URL in location.state
• RequireRole: Checks user.role against allow[] array, redirects to /403

Roles

ADMIN | TEAM_MANAGER | REFEREE | SUPERVISOR | PUBLIC

Shell / Layout

AppShell (shell/AppShell.tsx) — Protected

• Ant Design Layout with collapsible Sider + Header + Content
• Sidebar: Dynamic menu filtered by user role (from menu.ts)
• Header: Global search (debounced 300ms autocomplete via /search), dark mode toggle, language toggle (VI/EN), user dropdown (profile, change password, logout)
• <Outlet /> renders child routes

PublicLayout (shell/PublicLayout.tsx)

• Gradient header with V-League branding
• Horizontal menu: Standings, Schedule, Results
• Login button
• Footer with copyright

ThemeContext (shell/ThemeContext.tsx)

• Light/dark mode toggle via React Context
• Persisted to localStorage key vleague-theme
• Returns theme.darkAlgorithm or theme.defaultAlgorithm for Ant Design

Menu (shell/menu.ts) — 12 items

i18n Setup

Configuration (lib/i18n.ts)

• Languages: Vietnamese (vi, fallback) and English (en)
• Detection: localStorage key vleague-lang → browser navigator
• Plugin: i18next-browser-languagedetector

Translation Files

• locales/vi.ts — ~1,244 lines, comprehensive Vietnamese catalog
• locales/en.ts — ~1,207 lines, English mirror

Namespace Convention

dashboard.*, matches.*, teams.*, players.*, seasons.*, schedule.*, standings.*, stadiums.*, users.*, profile.*, sessions.*, regulations.*, reports.*, headToHead.*, login.*, register.*, forgotPassword.*, resetPassword.*, changePassword.*, verifyEmail.*, teamDetail.*, playerDetail.*, stadiumDetail.*, forbidden.*, oauth.*

TypeScript Types

Domain Types (co-located in service files)

Enums (string unions)

• Position: 'GK' | 'DF' | 'MF' | 'FW'
• PlayerType: 'DOMESTIC' | 'FOREIGN'
• MatchStatus: 'DRAFT' | 'PUBLISHED' | 'LOCKED' | 'FINISHED' | 'POSTPONED'
• SeasonStatus: 'UPCOMING' | 'IN_PROGRESS' | 'COMPLETED'
• SeasonTeamStatus: 'REGISTERED' | 'APPROVED' | 'REJECTED' | 'WITHDRAWN'
• EventType: 'GOAL' | 'OWN_GOAL' | 'PENALTY' | 'PENALTY_MISS' | 'YELLOW_CARD' | 'RED_CARD' | 'SUBSTITUTION'
• UserRole: 'ADMIN' | 'TEAM_MANAGER' | 'REFEREE' | 'SUPERVISOR' | 'PUBLIC'
• ThemeMode: 'light' | 'dark'

State Management Patterns

No Redux/Zustand — pure React patterns:

• AuthContext: Global auth state (React Context + useState)
• ThemeContext: Dark/light mode (React Context + useState)
• Per-page local state: useState + useEffect for data fetching
• useCallback: Memoized fetch functions
• useMemo: Derived data (filtered lists, role checks, menu items)
• Promise.allSettled: Parallel API calls on Dashboard and Reports
• useRef: Debounce timers (global search), prevent duplicate processing (OAuth)
• Custom events: auth:expired, api:rate-limited for cross-cutting concerns

Environment Variables

Utility Constants (utils/constants.ts)

Notable Patterns

1. Lazy loading: All protected pages + layouts are React.lazy(). Auth pages eager for fast first paint
2. Dual HTTP clients: lib/api.ts (Axios, primary) + services/http.ts (fetch, legacy/unused)
3. Token refresh queue: Concurrent 401s queued; only one refresh runs at a time
4. PDF export: Dynamic import('jspdf') to avoid bundling unless needed
5. CSV export: ExportButton component + csvExport.ts utility (UTF-8 BOM for Excel)
6. Player CSV import: apiImportPlayersCsv sends FormData; downloadPlayerCsvTemplate() for template
7. Match status FSM: DRAFT → PUBLISHED → LOCKED → FINISHED (with POSTPONED side-paths)
8. Standings highlighting: AFC Champions League zone (green) + relegation zone (red) via CSS classes
9. Session management: View active sessions, revoke individual/all
10. OAuth flow: Server redirect → /auth/oauth-callback?accessToken=&refreshToken=
11. Global search: Debounced 300ms autocomplete in AppShell header
12. Recharts: Bar charts (goals by round, team points), Pie chart (goal distribution)
13. Sentry: Browser tracing + session replay (100% dev / 20% prod)

Testing Conventions

• 15 page test suites, 13 service test suites, 2 auth test suites
• Page tests: src/pages/__tests__/*.test.tsx
• Service tests: src/services/__tests__/*.test.ts
• Auth tests: src/auth/AuthContext.test.tsx, RequireAuth.test.tsx
• Always use vi.hoisted() for mock variables inside vi.mock()
• Mock ../../lib/api for service tests
• Mock individual service files + react-router-dom for page tests
• Use getAllByText() instead of getByText() for Ant Design duplicate text
• Import from __tests__/ goes up one level: ../ComponentName

Polyfills (vitest.setup.ts)

• @testing-library/jest-dom/vitest for custom matchers
• i18n initialized with Vietnamese, no language detector
• ResizeObserver polyfill (Ant Design Tabs/Collapse)
• window.matchMedia polyfill (Ant Design responsive)

Common Commands

cd apps/web
pnpm dev                     # Start dev server (port 5173)
pnpm build                   # Production build
pnpm preview                 # Preview production build
pnpm test                    # Vitest (30 suites)
pnpm exec vitest             # Watch mode
pnpm lint                    # ESLint

Converted and distributed by TomeVault — claim your Tome and manage your conversions.