Frontend - Educational Platform Management

Frontend application for the hierarchical educational management platform with 5 user levels and strict data isolation.

Tech Stack

• Framework: React 18 with TypeScript
• Build Tool: Vite 6
• Styling: Tailwind CSS v4 + shadcn/ui components
• State Management: Zustand (global), React Context (auth)
• Routing: React Router v7
• Internationalization: react-i18next
• Testing: Vitest (unit), Playwright (E2E)
• UI Components: shadcn/ui + Material Icons

Prerequisites

• Node.js >= 18.0.0
• npm >= 9.0.0

Installation

cd frontend
npm install

Development

# Start development server (port 5173)
npm run dev

# Start on specific port (for Playwright tests)
npm run dev -- --port 5174

Building

# Type checking
npm run typecheck

# Production build
npm run build

# Preview production build
npm run preview

Testing

# Run unit tests (Vitest)
npm run test

# Run E2E tests (Playwright)
npm test

# Install Playwright browsers
npm run install:playwright

# View test report
npm run test:report

Linting & Formatting

# Run ESLint
npm run lint

# Auto-fix ESLint issues
npm run lint:fix

# Format code with Prettier
npm run format

Project Structure

frontend/
├── public/                 # Static assets
│   └── locales/           # i18n translation files
├── src/
│   ├── components/        # React components
│   │   ├── admin/        # SuperAdmin components
│   │   ├── auth/         # Authentication components
│   │   ├── common/       # Shared components
│   │   │   ├── sidebar/  # Sidebar navigation
│   │   │   └── ProtectedRoute/  # Route protection
│   │   ├── dashboard/    # Dashboard layouts
│   │   ├── instructor/   # Instructor components
│   │   ├── layouts/      # Role-specific layouts
│   │   ├── region-admin/ # Regional admin components
│   │   ├── center-manager/ # Center manager components
│   │   └── student/      # Student components
│   ├── contexts/         # React contexts
│   ├── hooks/            # Custom React hooks
│   ├── i18n/             # i18n configuration
│   ├── services/         # API service layer
│   ├── stores/           # Zustand stores
│   └── ui/               # UI components (shadcn/ui)
├── index.html             # Entry HTML
├── package.json           # Dependencies
├── tsconfig.json          # TypeScript config
├── vite.config.ts         # Vite configuration
└── playwright.config.ts   # Playwright E2E test config

State Management

Zustand Stores

Located in src/stores/:

• useAuthStore: Authentication state (user, tokens, loading)
• useUIStore: Global UI state (sidebar, theme, language)

React Contexts

• AuthProvider: Authentication with JWT/OAuth2
• LoadingContext: Loading bar management
• DialogContext: Modal/dialog management

Routing & Navigation

Role-Based Routing

The application uses role-based routing with middleware protection:

// Protected route example
<Route path="/admin/*" element={
  <ProtectedRoute allowedRoles={['superadmin', 'admin']}>
    <SuperAdminLayout />
  </ProtectedRoute>
} />

Routes by Role

Role	Base Path	Layout	Main Routes
SuperAdmin	/admin/*	SuperAdminLayout	Dashboard, Regions, Admins, Logs, Settings
Region Admin	/region-admin/*	RegionAdminLayout	Dashboard, Centers, Managers, Reports
Center Manager	/center-manager/*	CenterLayout	Dashboard, Teachers, Students, Courses, Reports
Instructor	/instructor/*	InstructorLayout	Dashboard, Courses, Create Course, Students
Student	/student/*	StudentLayout	Dashboard, Courses, Browse, Progress

Component Architecture

Layouts

All layouts use DashboardLayout which includes:

• Sidebar: Navigation menu, profile link, language selector, logout
• Header: Page title, welcome message
• Main Content: Page-specific content

Common Components

Located in src/components/common/:

• SidebarLayout: Main navigation sidebar with profile and settings
• ProtectedRoute: Route protection middleware
• RoleGuard: Component-level role checking
• Dialog: Modal/dialog system
• ToastTest: Toast notification testing

Services Layer

All API calls go through the centralized service layer in src/services/:

• api.ts: Main API client with JWT handling
• toast.service.ts: Toast notification system

API Response Format

interface ApiResponse<T> {
  success: boolean;
  data?: T;
  error?: {
    code: string;
    message: string;
    details?: string;
  };
}

Internationalization (i18n)

• Library: react-i18next
• Languages: ES, EN, FR, GL, PT, DE, EU, CA
• Translation Files: public/locales/{lang}/common.json
• Usage: t('menu.superadmin.dashboard')

Adding New Translations

1. Edit public/locales/es/common.json
2. Edit public/locales/en/common.json
3. Use in components: t('key.path')

Color Scheme

Uses the CARGOFFER/Trascend color palette:

• Primary Blue: #1A2942 (trascend-blue)
• Teal: #00B4D8 (trascend-teal)
• Orange: #FF7A00 (trascend-orange)

See COLOR_SCHEME.md for complete palette.

Testing Credentials

Role	Email	Password
SuperAdmin	superadmin@test.com	Test1234
Regional Admin	admin_aragon@test.com	Test1234
Center Manager	director@ies-example.com	Test1234
Instructor	profesor.mates@ies-example.com	Test1234
Student	alumno1@ies-example.com	Test1234

Code Style Conventions

See ../AGENTS.md for detailed conventions:

• Imports: Node built-ins → third-party → internal (alphabetical)
• Formatting: Prettier with 2 spaces, single quotes
• TypeScript: Strict mode, explicit return types
• Naming: kebab-case files, camelCase variables, PascalCase components
• State: Zustand for global state, React hooks for local state
• Interfaces: External files (interfaces.ts) for complex types
• Component Limit: Max 400 lines - refactor if exceeded
• API Calls: Always through services layer
• Error Handling: Guard clauses, default values, no nulls
• i18n: All user-facing text must use i18n keys
• No Hardcoded Values: Use env vars or constants

Screen Organization

Each role has its own screening directory:

components/
├── superadmin/          # SuperAdmin-only components
│   ├── index.ts         # Main export
│   ├── interfaces.ts    # Type definitions
│   └── ...
├── region-admin/        # Regional admin components
├── center-manager/      # Center manager components
├── instructor/          # Instructor components
└── student/             # Student components

Environment Variables

Create .env file in frontend root:

VITE_API_BASE_URL=http://localhost:3000

Deployment

# Build for production
npm run build

# Output directory: dist/
# Deploy dist/ to your web server

Troubleshooting

Common Issues

1. Module not found: Run npm install in project root
2. Type errors: Run npm run typecheck
3. Lint errors: Run npm run lint:fix
4. i18n keys missing: Check public/locales/{lang}/common.json

Port Conflicts

If port 5173 is in use:

npm run dev -- --port 5174

Related Documentation

Project Documentation

• Main README - Project overview
• Backend README - API documentation

Code Standards & Architecture

• AGENTS.md - Coding conventions
• COLOR_SCHEME.md - Color system
• ROADMAP.md - Development milestones
• TEST_PLAN.md - Testing strategy

Planning & Requirements

• PRD - Product Requirements Document
• Constitution - Project governance
• Quality Gates - Quality standards