28b1cc6e48
- Updated all references, metadata, and templates to reflect the new branding, including layout files, components, and documentation. - Replaced hardcoded color tokens like `green-600` with semantic tokens (`success`, `warning`, etc.) for improved design consistency. - Enhanced `globals.css` with new color tokens for success, warning, and destructive states using the OKLCH color model. - Added comprehensive branding guidelines and updated the design system documentation to align with the new identity. - Updated tests and mocks to reflect the branding changes and ensured all visual/verbal references match "PragmaStack". - Added new `branding/README.md` and `branding` docs for mission, values, and visual identity definition.
263 lines
7.6 KiB
Markdown
Executable File
263 lines
7.6 KiB
Markdown
Executable File
# PragmaStack - Frontend
|
|
|
|
Production-ready Next.js 16 frontend with TypeScript, authentication, admin panel, and internationalization.
|
|
|
|
## Features
|
|
|
|
### Core
|
|
|
|
- ⚡ **Next.js 16** - App Router with React Server Components
|
|
- 📘 **TypeScript** - Full type safety
|
|
- 🎨 **Tailwind CSS** - Utility-first styling
|
|
- 🧩 **shadcn/ui** - High-quality component library
|
|
- 🌙 **Dark Mode** - System-aware theme switching
|
|
|
|
### Authentication & Security
|
|
|
|
- 🔐 **JWT Authentication** - Access & refresh token flow
|
|
- 🔒 **Protected Routes** - Client-side route guards
|
|
- 👤 **User Management** - Profile settings, password change
|
|
- 📱 **Session Management** - Multi-device session tracking
|
|
|
|
### Internationalization (i18n)
|
|
|
|
- 🌍 **Multi-language Support** - English & Italian (easily extensible)
|
|
- 🔗 **Locale Routing** - SEO-friendly URLs (`/en/login`, `/it/login`)
|
|
- 🎯 **Type-safe Translations** - TypeScript autocomplete for keys
|
|
- 📄 **Localized Metadata** - SEO-optimized meta tags per locale
|
|
- 🗺️ **Multilingual Sitemap** - Automatic sitemap generation with hreflang
|
|
|
|
### Admin Panel
|
|
|
|
- 👥 **User Administration** - CRUD operations, search, filters
|
|
- 🏢 **Organization Management** - Multi-tenant support with roles
|
|
- 📊 **Dashboard** - Statistics and quick actions
|
|
- 🔍 **Advanced Filtering** - Status, search, pagination
|
|
|
|
### Developer Experience
|
|
|
|
- ✅ **Comprehensive Testing** - 1,142+ unit tests, 178+ E2E tests
|
|
- 🎭 **Playwright** - End-to-end testing with fixtures
|
|
- 🧪 **Jest** - Fast unit testing with coverage
|
|
- 📝 **ESLint & Prettier** - Code quality enforcement
|
|
- 🔍 **TypeScript** - Strict mode enabled
|
|
|
|
## Getting Started
|
|
|
|
### Prerequisites
|
|
|
|
- Node.js 18+
|
|
- npm, yarn, or pnpm
|
|
|
|
### Installation
|
|
|
|
```bash
|
|
# Install dependencies
|
|
npm install
|
|
|
|
# Run development server
|
|
npm run dev
|
|
```
|
|
|
|
Open [http://localhost:3000](http://localhost:3000) to view the app.
|
|
|
|
### Environment Variables
|
|
|
|
Create a `.env.local` file:
|
|
|
|
```env
|
|
NEXT_PUBLIC_API_URL=http://localhost:8000/api/v1
|
|
NEXT_PUBLIC_SITE_URL=http://localhost:3000
|
|
```
|
|
|
|
## Scripts
|
|
|
|
```bash
|
|
# Development
|
|
npm run dev # Start dev server
|
|
npm run build # Production build
|
|
npm run start # Start production server
|
|
|
|
# Code Quality
|
|
npm run lint # Run ESLint
|
|
npm run format # Format with Prettier
|
|
npm run format:check # Check formatting
|
|
npm run type-check # TypeScript type checking
|
|
npm run validate # Run all checks (lint + format + type-check)
|
|
|
|
# Testing
|
|
npm test # Run unit tests
|
|
npm run test:watch # Watch mode
|
|
npm run test:coverage # Coverage report
|
|
npm run test:e2e # Run E2E tests
|
|
npm run test:e2e:ui # Playwright UI mode
|
|
|
|
# API Client
|
|
npm run generate:api # Generate TypeScript client from OpenAPI spec
|
|
```
|
|
|
|
## Project Structure
|
|
|
|
```
|
|
frontend/
|
|
├── src/
|
|
│ ├── app/ # Next.js App Router
|
|
│ │ ├── [locale]/ # Locale-specific routes
|
|
│ │ │ ├── (auth)/ # Auth pages (login, register)
|
|
│ │ │ ├── (authenticated)/ # Protected pages
|
|
│ │ │ ├── admin/ # Admin panel
|
|
│ │ │ └── layout.tsx # Locale layout
|
|
│ │ ├── sitemap.ts # Multilingual sitemap
|
|
│ │ └── robots.ts # SEO robots.txt
|
|
│ ├── components/ # React components
|
|
│ │ ├── auth/ # Auth components
|
|
│ │ ├── admin/ # Admin components
|
|
│ │ ├── forms/ # Form utilities
|
|
│ │ ├── navigation/ # Navigation (Header, LocaleSwitcher)
|
|
│ │ └── ui/ # shadcn/ui components
|
|
│ ├── lib/ # Utilities & configuration
|
|
│ │ ├── api/ # API client (auto-generated)
|
|
│ │ ├── auth/ # Auth utilities & storage
|
|
│ │ ├── i18n/ # Internationalization
|
|
│ │ │ ├── routing.ts # Locale routing config
|
|
│ │ │ ├── utils.ts # Locale utilities
|
|
│ │ │ └── metadata.ts # SEO metadata helpers
|
|
│ │ └── stores/ # Zustand state management
|
|
│ └── hooks/ # Custom React hooks
|
|
├── messages/ # Translation files
|
|
│ ├── en.json # English
|
|
│ └── it.json # Italian
|
|
├── e2e/ # Playwright E2E tests
|
|
├── tests/ # Jest unit tests
|
|
├── docs/ # Documentation
|
|
│ ├── I18N.md # i18n guide
|
|
│ └── design-system/ # Design system docs
|
|
└── types/ # TypeScript type definitions
|
|
```
|
|
|
|
## Internationalization (i18n)
|
|
|
|
The app supports multiple languages with SEO-optimized routing.
|
|
|
|
### Supported Languages
|
|
|
|
- 🇬🇧 English (default)
|
|
- 🇮🇹 Italian
|
|
|
|
### Usage
|
|
|
|
```typescript
|
|
// Client components
|
|
import { useTranslations } from 'next-intl';
|
|
|
|
export function MyComponent() {
|
|
const t = useTranslations('namespace');
|
|
return <h1>{t('title')}</h1>;
|
|
}
|
|
|
|
// Server components
|
|
import { getTranslations } from 'next-intl/server';
|
|
|
|
export default async function Page() {
|
|
const t = await getTranslations('namespace');
|
|
return <h1>{t('title')}</h1>;
|
|
}
|
|
|
|
// Navigation (always use locale-aware routing)
|
|
import { Link, useRouter } from '@/lib/i18n/routing';
|
|
|
|
<Link href="/dashboard">Dashboard</Link> // → /en/dashboard
|
|
```
|
|
|
|
### Adding New Languages
|
|
|
|
1. Create translation file: `messages/fr.json`
|
|
2. Update `src/lib/i18n/routing.ts`: Add `'fr'` to locales
|
|
3. Update `src/lib/i18n/metadata.ts`: Add `'fr'` to Locale type
|
|
4. Update `LocaleSwitcher` component with locale name
|
|
|
|
See [docs/I18N.md](./docs/I18N.md) for complete guide.
|
|
|
|
## Testing
|
|
|
|
### Unit Tests (Jest)
|
|
|
|
```bash
|
|
# Run all tests
|
|
npm test
|
|
|
|
# Watch mode
|
|
npm run test:watch
|
|
|
|
# Coverage
|
|
npm run test:coverage
|
|
```
|
|
|
|
**Coverage**: 1,142+ tests covering components, hooks, utilities, and pages.
|
|
|
|
### E2E Tests (Playwright)
|
|
|
|
```bash
|
|
# Run E2E tests
|
|
npm run test:e2e
|
|
|
|
# UI mode (recommended for debugging)
|
|
npm run test:e2e:ui
|
|
|
|
# Debug mode
|
|
npm run test:e2e:debug
|
|
```
|
|
|
|
**Coverage**: 178+ tests covering authentication, navigation, admin panel, and user flows.
|
|
|
|
## Documentation
|
|
|
|
- [Internationalization Guide](./docs/I18N.md) - Complete i18n implementation guide
|
|
- [Design System](./docs/design-system/) - Component library and patterns
|
|
- [Implementation Plan](./docs/I18N_IMPLEMENTATION_PLAN.md) - i18n implementation details
|
|
|
|
## Tech Stack
|
|
|
|
- **Framework**: Next.js 16 (App Router)
|
|
- **Language**: TypeScript 5
|
|
- **Styling**: Tailwind CSS 3 + shadcn/ui
|
|
- **State Management**: Zustand + TanStack Query
|
|
- **Forms**: React Hook Form + Zod
|
|
- **i18n**: next-intl 4.5.3
|
|
- **Testing**: Jest + Playwright
|
|
- **Code Quality**: ESLint + Prettier
|
|
|
|
## Performance
|
|
|
|
- ⚡ Server Components for optimal loading
|
|
- 🎨 Font optimization with `display: 'swap'`
|
|
- 📦 Code splitting with dynamic imports
|
|
- 🗜️ Automatic bundle optimization
|
|
- 🌐 Lazy loading of locale messages
|
|
- 🖼️ Image optimization with next/image
|
|
|
|
## Browser Support
|
|
|
|
- Chrome (latest)
|
|
- Firefox (latest)
|
|
- Safari (latest)
|
|
- Edge (latest)
|
|
|
|
## Contributing
|
|
|
|
1. Follow existing code patterns
|
|
2. Write tests for new features
|
|
3. Run `npm run validate` before committing
|
|
4. Keep translations in sync (en.json & it.json)
|
|
|
|
## License
|
|
|
|
MIT License - see LICENSE file for details
|
|
|
|
## Learn More
|
|
|
|
- [Next.js Documentation](https://nextjs.org/docs)
|
|
- [next-intl Documentation](https://next-intl-docs.vercel.app/)
|
|
- [shadcn/ui](https://ui.shadcn.com/)
|
|
- [Tailwind CSS](https://tailwindcss.com/)
|