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' | 'OWNGOAL' | 'PENALTY' | 'PENALTYMISS' | 'YELLOWCARD' | 'REDCARD' | '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