diff --git a/.gitignore b/.gitignore index 525f720..526a9e3 100644 --- a/.gitignore +++ b/.gitignore @@ -246,3 +246,10 @@ __marimo__/ # File uploads (generated during runtime) uploads/ **/uploads/ + +# Local developer notes (do not version) +**/TODO.md +**/todo.md + +# Local backups and caches +**/node_modules.bak-*/ diff --git a/README.md b/README.md index 20c40a0..33a4af9 100644 --- a/README.md +++ b/README.md @@ -5,7 +5,7 @@ ![Architecture](https://img.shields.io/badge/Architecture-Event%20Driven%20Microservices-orange) ![Test Coverage](https://img.shields.io/badge/Tests-High%20Test%20Coverage-success) ![Built with Node.js](https://img.shields.io/badge/Backend-Node.js%20%26%20TypeScript-339933?logo=nodedotjs) -![Built with React](https://img.shields.io/badge/Frontend-Next.js%2014%2B%20%26%20React-61DAFB?logo=react) +![Built with React](https://img.shields.io/badge/Frontend-Next.js%2015%20%26%20React%2019-61DAFB?logo=react) ![Database](https://img.shields.io/badge/Database-PostgreSQL-336791?logo=postgresql) ![Events](https://img.shields.io/badge/Events-RabbitMQ%20Powered-FF6600) ![Docker](https://img.shields.io/badge/Container-Docker%20Ready-2496ED?logo=docker) @@ -98,6 +98,7 @@ For per-service smoke tests, see the individual service READMEs in `services/*/R - [πŸ”§ Development Setup](docs/development.md) - [πŸš€ Deployment Guide](docs/deployment.md) - [πŸ“‘ API Documentation](docs/api.md) +- [🎨 Frontend Documentation](docs/frontend.md) - [πŸ”” Notification Service](docs/notification-service.md) - [🀝 Contributing Guide](CONTRIBUTING.md) - [πŸ§ͺ SQL Examples (dev-only)](docs/sql-examples/README.md) diff --git a/docs/README.md b/docs/README.md index de7fbc2..a5809b0 100644 --- a/docs/README.md +++ b/docs/README.md @@ -17,7 +17,7 @@ Welcome to the comprehensive documentation for the Pediafor Assessment Platform | [πŸš€ Deployment Guide](./deployment.md) | Production deployment with Docker and events | | [πŸ”§ Development Guide](./development.md) | Complete development setup and workflow | | [πŸ“‘ API Reference](./api.md) | Complete API documentation with examples | -| [🎨 Frontend Guide](../frontend/README.md) | React/Next.js frontend architecture | +| [🎨 Frontend Guide](./frontend.md) | React/Next.js frontend architecture | | [πŸ§ͺ SQL Examples](./sql-examples/README.md) | Development-only SQL snippets | ## πŸ—οΈ Service Documentation @@ -37,4 +37,4 @@ Welcome to the comprehensive documentation for the Pediafor Assessment Platform --- -Docs Version: 1.3 β€’ Last Updated: October 20, 2025 +Docs Version: 2.0 β€’ Last Updated: October 29, 2025 diff --git a/docs/frontend-requirements.md b/docs/frontend-requirements.md deleted file mode 100644 index cf6b098..0000000 --- a/docs/frontend-requirements.md +++ /dev/null @@ -1,688 +0,0 @@ -# Frontend Requirements Document - Pediafor Assessment Platform - -[![Status](https://img.shields.io/badge/Status-Requirements%20Defined-blue)](.) -[![Framework](https://img.shields.io/badge/Framework-Next.js%2014%2B-black?logo=nextdotjs)](.) -[![UI](https://img.shields.io/badge/UI-Tailwind%20CSS%20%2B%20Shadcn%2Fui-06B6D4?logo=tailwindcss)](.) -[![State](https://img.shields.io/badge/State-TanStack%20Query%20%2B%20Zustand-FF4154)](.) -[![Real-time](https://img.shields.io/badge/Real--time-WebTransport-green)](.) -[![Theme](https://img.shields.io/badge/Theme-Dark%2FLight%20Mode-purple)](.) -[![License](https://img.shields.io/badge/License-Open%20Source-brightgreen)](.) -[![Last Updated](https://img.shields.io/badge/Updated-October%202025-blue)](.) - -## Table of Contents - -1. [Project Overview](#project-overview) -2. [Technical Architecture](#technical-architecture) -3. [Design System](#design-system) -4. [User Roles & Permissions](#user-roles--permissions) -5. [Core Features](#core-features) -6. [Security Requirements](#security-requirements) -7. [Performance & Scalability](#performance--scalability) -8. [Development Specifications](#development-specifications) -9. [Future Roadmap](#future-roadmap) - ---- - -## Project Overview - -### **Vision Statement** -Build a modern, open-source assessment platform frontend that provides an intuitive, accessible, and powerful interface for educational institutions. The frontend will seamlessly integrate with our production-ready microservices backend to deliver a complete assessment solution. - -### **Key Principles** -- **Open Source First**: All dependencies and tools must be open source -- **Accessibility**: WCAG 2.1 AA compliance from day one -- **Performance**: Sub-second page loads and responsive interactions -- **Scalability**: Support for institutional-scale concurrent usage -- **Security**: FERPA/GDPR compliant with comprehensive audit logging - ---- - -## Technical Architecture - -### **Project Structure** -``` -frontend/ -β”œβ”€β”€ src/ -β”‚ β”œβ”€β”€ app/ # Next.js 14+ App Router -β”‚ β”‚ β”œβ”€β”€ (auth)/ # Authentication routes -β”‚ β”‚ β”œβ”€β”€ student/ # Student dashboard & flows -β”‚ β”‚ β”œβ”€β”€ teacher/ # Teacher dashboard & flows -β”‚ β”‚ β”œβ”€β”€ admin/ # Admin interface -β”‚ β”‚ └── globals.css # Global styles -β”‚ β”œβ”€β”€ components/ # Reusable UI components -β”‚ β”‚ β”œβ”€β”€ ui/ # Shadcn/ui base components -β”‚ β”‚ β”œβ”€β”€ forms/ # Form components -β”‚ β”‚ β”œβ”€β”€ assessment/ # Assessment-specific components -β”‚ β”‚ β”œβ”€β”€ analytics/ # Dashboard & analytics components -β”‚ β”‚ └── layouts/ # Layout components -β”‚ β”œβ”€β”€ lib/ # Utilities and configurations -β”‚ β”‚ β”œβ”€β”€ api.ts # API client with PASETO integration -β”‚ β”‚ β”œβ”€β”€ auth.ts # Authentication utilities -β”‚ β”‚ β”œβ”€β”€ transport.ts # WebTransport client -β”‚ β”‚ β”œβ”€β”€ cache.ts # Caching strategies -β”‚ β”‚ └── utils.ts # Helper functions -β”‚ β”œβ”€β”€ hooks/ # Custom React hooks -β”‚ β”œβ”€β”€ stores/ # Zustand stores -β”‚ β”œβ”€β”€ types/ # TypeScript type definitions -β”‚ └── styles/ # Theme and styling utilities -β”œβ”€β”€ public/ # Static assets -β”‚ β”œβ”€β”€ logos/ # Pediafor brand assets -β”‚ β”‚ β”œβ”€β”€ light/ # Light mode logos -β”‚ β”‚ β”œβ”€β”€ dark/ # Dark mode logos -β”‚ β”‚ └── formats/ # SVG, PNG, JPEG, ICO -β”‚ └── icons/ # Application icons -β”œβ”€β”€ package.json -β”œβ”€β”€ tailwind.config.js -β”œβ”€β”€ next.config.js -β”œβ”€β”€ tsconfig.json -└── Dockerfile # Container configuration -``` - -### **Technology Stack** - -#### **Core Framework** -- **React**: 18+ with functional components and hooks -- **Next.js**: 14+ with App Router for optimal performance -- **TypeScript**: Latest version with strict mode -- **Node.js**: Latest LTS version - -#### **UI & Styling** -- **Tailwind CSS**: Utility-first responsive design -- **Shadcn/ui**: Modern component library on Radix primitives -- **Lucide React**: Comprehensive icon library -- **CSS Variables**: Dynamic theming support - -#### **State Management** -- **TanStack Query**: Server state management and caching -- **Zustand**: Client-side state management -- **React Hook Form**: Form state and validation - -#### **Real-time Communication** -- **WebTransport**: Primary choice for real-time features -- **WebSocket**: Fallback for environments without WebTransport support - -#### **Development Tools** -- **ESLint**: Code linting with TypeScript support -- **Prettier**: Code formatting -- **Husky**: Git hooks for quality checks -- **Jest**: Unit testing framework -- **Playwright**: End-to-end testing - ---- - -## Design System - -### **Brand Colors** -- **Primary Orange**: `#ed5622` - Logo, call-to-action buttons, important highlights -- **Secondary Gray**: `#4e4e4e` - Text, subtle UI elements -- **Extended Palette**: - - **Success**: `#10b981` - Success states, positive feedback - - **Warning**: `#f59e0b` - Warning states, pending actions - - **Error**: `#ef4444` - Error states, critical alerts - - **Info**: `#3b82f6` - Information, links, navigation - - **Neutral Grays**: `#f9fafb` to `#111827` - Backgrounds, borders - -### **Theme System** -- **Light Mode**: Default theme with high contrast -- **Dark Mode**: OLED-friendly dark theme -- **System Preference**: Auto-detection with manual override -- **Persistence**: Theme choice saved in localStorage - -### **Typography Scale** -- **Font Family**: System font stack with Inter as web font fallback -- **Scale**: Modular scale from 12px to 72px -- **Weight**: Regular (400), Medium (500), Semibold (600), Bold (700) -- **Line Height**: Optimized for readability (1.4-1.6) - -### **Component Design Principles** -- **Consistency**: Unified spacing, colors, and interaction patterns -- **Accessibility**: ARIA labels, keyboard navigation, screen reader support -- **Responsiveness**: Mobile-first design with progressive enhancement -- **Performance**: Lazy loading, code splitting, optimized assets - ---- - -## User Roles & Permissions - -### **Role-Based Navigation (Dynamic)** -Navigation elements and features are dynamically shown/hidden based on user role: - -#### **Student Role** -```typescript -interface StudentPermissions { - assessments: { - view: boolean; // View assigned assessments - take: boolean; // Take assessments - viewResults: boolean; // View detailed results - resume: boolean; // Resume incomplete assessments - }; - profile: { - view: boolean; // View own profile - edit: boolean; // Edit basic profile info - }; -} -``` - -#### **Teacher Role** -```typescript -interface TeacherPermissions { - assessments: { - create: boolean; // Create new assessments - edit: boolean; // Edit own assessments - delete: boolean; // Delete own assessments - assign: boolean; // Assign to students - grade: boolean; // Manual grading - analytics: boolean; // View class analytics - }; - questions: { - create: boolean; // Create question banks - import: boolean; // Import questions - export: boolean; // Export questions - template: boolean; // Create reusable templates - }; - students: { - view: boolean; // View assigned students - grade: boolean; // Grade submissions - feedback: boolean; // Provide feedback - }; - bulk: { - grade: boolean; // Bulk grading operations - assign: boolean; // Bulk assignment - export: boolean; // Bulk data export - }; -} -``` - -#### **Admin Role** -```typescript -interface AdminPermissions { - users: { - create: boolean; // Create users - edit: boolean; // Edit all users - delete: boolean; // Delete users - roles: boolean; // Manage user roles - }; - system: { - settings: boolean; // Platform settings - monitoring: boolean; // System monitoring - audit: boolean; // Audit logs - backup: boolean; // Data backup/restore - }; - analytics: { - platform: boolean; // Platform-wide analytics - export: boolean; // Advanced reporting - compliance: boolean; // Compliance reports - }; - tenancy: { - manage: boolean; // Multi-tenant management - settings: boolean; // Tenant-specific settings - }; -} -``` - ---- - -## Core Features - -### **Authentication & Session Management** - -#### **Authentication Flow** -```typescript -interface AuthenticationFeatures { - login: { - credentials: boolean; // Email/password login - rememberMe: boolean; // Persistent sessions - sso: boolean; // SSO integration (future) - mfa: boolean; // Multi-factor auth (future) - }; - session: { - timeout: number; // Base session timeout - extension: boolean; // Manual session extension - activityTracking: boolean; // Reset timer on activity - gracefulExpiry: boolean; // 5-minute warning system - autoSave: boolean; // Continuous draft saving - reauth: boolean; // In-place re-authentication - }; - tokens: { - paseto: boolean; // PASETO V4 token handling - refresh: boolean; // Automatic token refresh - secure: boolean; // httpOnly cookies - }; -} -``` - -#### **Session Timeout Strategy** -1. **Activity Monitoring**: Track user interactions (keypress, mouse, scroll) -2. **WebTransport Pings**: Lightweight keep-alive signals -3. **Warning System**: 5-minute countdown modal before expiry -4. **Auto-Save**: Continuous draft saving every 30 seconds -5. **Graceful Recovery**: In-place re-authentication without data loss - -### **Assessment Features** - -#### **Question Types & Support** -```typescript -interface QuestionTypes { - mcq: { - singleSelect: boolean; // Single correct answer - multiSelect: boolean; // Multiple correct answers - shuffle: boolean; // Answer randomization - }; - trueFalse: { - simple: boolean; // Basic true/false - explanation: boolean; // Require explanation - }; - shortAnswer: { - text: boolean; // Text-based answers - numeric: boolean; // Numeric answers - keywords: boolean; // Keyword matching - }; - essay: { - richText: boolean; // Rich text editor - wordLimit: boolean; // Word count limits - rubric: boolean; // Rubric-based grading - }; - fileUpload: { - documents: boolean; // PDF, DOC, TXT - images: boolean; // JPG, PNG, SVG - size: string; // "10MB max per file" - security: boolean; // Secure upload/download - }; - media: { - images: boolean; // Image-based questions - audio: boolean; // Audio playback - video: boolean; // Video embedding - }; -} -``` - -#### **Assessment Creation Tools** -```typescript -interface AssessmentTools { - builder: { - dragDrop: boolean; // Drag-and-drop question builder - templates: boolean; // Reusable templates - preview: boolean; // Live preview mode - validation: boolean; // Real-time validation - }; - import: { - json: boolean; // JSON format - csv: boolean; // CSV spreadsheets - word: boolean; // Word documents - aiGenerated: boolean; // AI tool outputs - questionBank: boolean; // Existing question banks - }; - advanced: { - randomization: boolean; // Question randomization - pools: boolean; // Question pools - branching: boolean; // Conditional logic - adaptive: boolean; // Adaptive difficulty - }; - timing: { - assessment: boolean; // Overall time limits - section: boolean; // Section-based timing - question: boolean; // Per-question timing - extensions: boolean; // Time extensions - }; -} -``` - -### **Student Experience** - -#### **Assessment Taking Flow** -```typescript -interface StudentFlow { - dashboard: { - assigned: boolean; // View assigned assessments - draft: boolean; // Resume incomplete assessments - completed: boolean; // View completed assessments - schedule: boolean; // Upcoming assessments calendar - }; - taking: { - navigation: { - linear: boolean; // Linear within sections - free: boolean; // Free within sections - review: boolean; // Review mode before submit - }; - features: { - autoSave: boolean; // Auto-save on question change - flagging: boolean; // Flag questions for review - timer: boolean; // Visible countdown timer - warnings: boolean; // Time warnings - offline: boolean; // Offline capability (future) - }; - }; - results: { - immediate: boolean; // Instant feedback (MCQ only) - detailed: boolean; // Question-by-question breakdown - rubric: boolean; // Rubric-based scores - feedback: boolean; // Teacher comments - analytics: boolean; // Performance analytics - }; -} -``` - -### **Teacher Experience** - -#### **Assessment Management** -```typescript -interface TeacherTools { - creation: { - wizard: boolean; // Step-by-step assessment wizard - templates: boolean; // Assessment templates - questionBanks: boolean; // Reusable question libraries - collaboration: boolean; // Share with other teachers - }; - assignment: { - students: boolean; // Select specific students - groups: boolean; // Assign to student groups - schedule: boolean; // Schedule future assessments - attempts: boolean; // Multiple attempt settings - }; - grading: { - automatic: boolean; // Auto-grading for MCQ - manual: boolean; // Manual grading interface - anonymous: boolean; // Anonymous grading mode - rubrics: boolean; // Rubric-based grading - bulk: boolean; // Bulk grading operations - override: boolean; // Override auto-grades - }; - analytics: { - class: boolean; // Class performance overview - individual: boolean; // Individual student progress - question: boolean; // Question difficulty analysis - trends: boolean; // Performance trends - export: boolean; // Data export capabilities - }; -} -``` - -### **Admin Experience** - -#### **Platform Management** -```typescript -interface AdminFeatures { - userManagement: { - crud: boolean; // Create, read, update, delete users - roles: boolean; // Role assignment and management - bulk: boolean; // Bulk user operations - import: boolean; // Import from CSV/LDAP - }; - systemSettings: { - branding: boolean; // Platform branding - features: boolean; // Feature toggles - security: boolean; // Security policies - integrations: boolean; // Third-party integrations - }; - analytics: { - platform: boolean; // Platform-wide analytics - usage: boolean; // Usage statistics - performance: boolean; // System performance metrics - compliance: boolean; // Compliance reporting - }; - maintenance: { - backups: boolean; // Data backup management - logs: boolean; // System logs and audit trails - monitoring: boolean; // Real-time system monitoring - updates: boolean; // System update management - }; -} -``` - ---- - -## Security Requirements - -### **Compliance & Privacy** -- **FERPA Compliance**: Educational records protection -- **GDPR Compliance**: Data privacy and user rights -- **Audit Logging**: Comprehensive action tracking -- **Data Encryption**: At-rest and in-transit encryption - -### **File Upload Security** -```typescript -interface FileUploadSecurity { - validation: { - serverSide: boolean; // Server-side file validation - typeChecking: boolean; // MIME type verification - scanning: boolean; // Malware scanning - }; - storage: { - encryption: boolean; // Encrypted storage - isolation: boolean; // Outside web root - objectStorage: boolean; // S3-compatible storage - }; - access: { - tokenBased: boolean; // PASETO-signed download tokens - timeLimit: boolean; // Time-limited access - userValidation: boolean; // User permission checks - }; - naming: { - randomization: boolean; // Cryptographically secure renaming - pathPrevention: boolean; // Path traversal prevention - }; -} -``` - -### **Session Security** -- **PASETO V4 Tokens**: Cryptographically secure tokens -- **httpOnly Cookies**: XSS protection -- **CSRF Protection**: Cross-site request forgery prevention -- **Rate Limiting**: API abuse prevention - ---- - -## Performance & Scalability - -### **Performance Targets** -- **Page Load**: < 1 second for initial load -- **Navigation**: < 200ms for page transitions -- **API Responses**: < 500ms for most operations -- **Real-time Updates**: < 100ms latency - -### **Caching Strategy** -```typescript -interface CachingStrategy { - client: { - tanstackQuery: boolean; // API response caching - localStorage: boolean; // Persistent local storage - sessionStorage: boolean; // Session-based storage - }; - browser: { - serviceWorker: boolean; // Offline capability (future) - staticAssets: boolean; // Static asset caching - }; - cdn: { - optional: boolean; // Optional CDN for institutions - configurable: boolean; // Admin-configurable - }; -} -``` - -### **Scalability Features** -- **Code Splitting**: Route-based code splitting -- **Lazy Loading**: Component and image lazy loading -- **Progressive Loading**: Incremental content loading -- **Virtualization**: Large list virtualization - ---- - -## Development Specifications - -### **Environment Configuration** -```typescript -interface EnvironmentConfig { - development: { - hotReload: boolean; // Fast refresh - debugging: boolean; // Source maps and dev tools - mockData: boolean; // Mock data for development - }; - production: { - optimization: boolean; // Bundle optimization - minification: boolean; // Code minification - compression: boolean; // Gzip/Brotli compression - }; - docker: { - containerized: boolean; // Docker deployment - multiStage: boolean; // Multi-stage builds - optimization: boolean; // Image size optimization - }; -} -``` - -### **Testing Strategy** -```typescript -interface TestingStrategy { - unit: { - jest: boolean; // Unit testing with Jest - coverage: number; // 90%+ code coverage target - components: boolean; // Component testing - }; - integration: { - api: boolean; // API integration tests - e2e: boolean; // End-to-end with Playwright - accessibility: boolean; // A11y testing - }; - performance: { - lighthouse: boolean; // Lighthouse CI - loadTesting: boolean; // Load testing - monitoring: boolean; // Performance monitoring - }; -} -``` - -### **Quality Assurance** -- **TypeScript**: Strict mode with comprehensive typing -- **ESLint**: Airbnb configuration with custom rules -- **Prettier**: Consistent code formatting -- **Husky**: Pre-commit hooks for quality checks -- **Commitizen**: Conventional commit messages - ---- - -## Future Roadmap - -### **Phase 1: Core MVP** (Current Focus) -- [ ] Project setup and basic architecture -- [ ] Authentication and role-based routing -- [ ] Basic assessment creation and taking -- [ ] Essential student and teacher dashboards -- [ ] Auto-grading integration - -### **Phase 2: Enhanced Features** -- [ ] Advanced question types and media support -- [ ] Comprehensive analytics and reporting -- [ ] Bulk operations and data export -- [ ] Real-time collaboration features -- [ ] Mobile responsive optimization - -### **Phase 3: Advanced Capabilities** -- [ ] SSO integration and MFA -- [ ] Advanced rubric-based grading -- [ ] AI-powered question generation -- [ ] Plagiarism detection integration -- [ ] Advanced analytics and insights - -### **Phase 4: Enterprise Features** -- [ ] Multi-tenancy support -- [ ] Mobile applications -- [ ] Offline capability -- [ ] Advanced integrations (LMS, SIS) -- [ ] Internationalization/localization - -### **Phase 5: Innovation** -- [ ] AI-powered adaptive assessments -- [ ] Advanced proctoring features -- [ ] Blockchain-based certification -- [ ] VR/AR assessment experiences -- [ ] Advanced accessibility features - ---- - -## WebTransport vs WebSocket Comparison - -### **WebTransport Advantages** -```typescript -interface WebTransportBenefits { - performance: { - multiplexing: boolean; // Multiple streams over single connection - headOfLineBlocking: boolean; // No head-of-line blocking - udpBased: boolean; // UDP for better performance - }; - reliability: { - builtInRetransmission: boolean; // Automatic retransmission - congestionControl: boolean; // Better congestion control - encryption: boolean; // Built-in TLS 1.3 - }; - features: { - bidirectional: boolean; // Bidirectional communication - unordered: boolean; // Unordered message delivery - partialReliability: boolean; // Partial reliability options - }; -} -``` - -### **Implementation Strategy** -```typescript -interface RealtimeStrategy { - primary: "WebTransport"; // Modern browsers - fallback: "WebSocket"; // Legacy browser support - detection: boolean; // Feature detection - gracefulDegradation: boolean; // Seamless fallback -} -``` - ---- - -## Implementation Priority - -### **Critical Path Features** (Must Have) -1. **Authentication System**: Login, logout, session management -2. **Role-based Navigation**: Dynamic UI based on user roles -3. **Assessment Taking**: Basic question types and submission -4. **Auto-grading Integration**: MCQ automatic scoring -5. **Results Display**: Score and feedback presentation - -### **High Priority Features** (Should Have) -1. **Assessment Creation**: Teacher assessment builder -2. **Question Banks**: Reusable question management -3. **Student Dashboard**: Assessment list and progress -4. **Teacher Analytics**: Basic class performance metrics -5. **File Upload**: Secure file handling - -### **Medium Priority Features** (Could Have) -1. **Advanced Question Types**: Essay, file upload, media -2. **Bulk Operations**: Bulk grading and assignment -3. **Export Capabilities**: Data export in multiple formats -4. **Real-time Features**: Live updates and notifications -5. **Advanced Analytics**: Detailed performance insights - -### **Future Features** (Won't Have Initially) -1. **SSO Integration**: External authentication providers -2. **Mobile Apps**: Native mobile applications -3. **Offline Capability**: Offline assessment taking -4. **AI Features**: AI-powered question generation -5. **Advanced Integrations**: LMS and SIS integrations - ---- - -## Conclusion - -This Frontend Requirements Document provides a comprehensive roadmap for building the Pediafor Assessment Platform frontend. The specifications balance immediate needs with future scalability, ensuring we build a robust, user-friendly, and maintainable application. - -The modular architecture and phased development approach allow for iterative improvements while maintaining code quality and user experience standards. The emphasis on open-source technologies, accessibility, and security ensures the platform meets educational institution requirements. - -**Next Steps:** -1. Set up the Next.js 14+ project with TypeScript -2. Configure Tailwind CSS and Shadcn/ui components -3. Implement authentication and role-based routing -4. Begin core assessment features development -5. Integrate with existing backend APIs - ---- - -**Document Version**: 1.0 -**Last Updated**: October 9, 2025 -**Status**: Requirements Finalized -**Approved By**: Product Team -**Next Review**: November 2025 \ No newline at end of file diff --git a/docs/frontend.md b/docs/frontend.md new file mode 100644 index 0000000..a06c36d --- /dev/null +++ b/docs/frontend.md @@ -0,0 +1,203 @@ +# Frontend Documentation β€” Pediafor Assessment Platform + +[![Framework](https://img.shields.io/badge/Framework-Next.js%2015-black?logo=nextdotjs)](.) +[![UI](https://img.shields.io/badge/UI-Tailwind%20CSS%20%2B%20Shadcn%2Fui-06B6D4?logo=tailwindcss)](.) +[![State](https://img.shields.io/badge/State-TanStack%20Query%20%2B%20Zustand-FF4154)](.) +[![Real-time](https://img.shields.io/badge/Real--time-WebTransport%20%2B%20WebSocket-green)](.) +[![Accessibility](https://img.shields.io/badge/Accessibility-WCAG%202.1%20AA-brightgreen)](.) + +This is the dedicated documentation hub for the Pediafor Frontend. It supersedes the legacy β€œfrontend-requirements.md” by providing a living, implementation-focused reference. For a quick developer guide, see the app-local `frontend/README.md`. This file is the authoritative, more detailed reference for design, architecture, and standards. + +## Contents + +- Overview and principles +- Technology stack +- Architecture and project structure +- Design system and theming +- Roles and permissions model +- Core feature specs (auth, assessments, results, admin) +- Security and compliance +- Performance and scalability targets +- Development and testing standards +- Roadmap + +--- + +## Overview and Principles + +Vision: build a modern, accessible, and performant UI for an assessment platform that scales to institutions and integrates seamlessly with our event-driven backend. + +Core principles: +- Open Source First: permissive license, widely adopted tech +- Accessibility by Default: WCAG 2.1 AA +- Performance Pragmatism: fast initial load, snappy nav, measured budgets +- Security Mindset: token hygiene, least-privilege, defense-in-depth +- Evolvable Architecture: clear boundaries, typed contracts, testability + +--- + +## Technology Stack + +Core framework: +- React 19 with functional components and hooks +- Next.js 15 (App Router) +- TypeScript (strict) +- Node.js (LTS) + +UI & Styling: +- Tailwind CSS (utility-first) +- shadcn/ui (Radix primitives) +- Lucide React icons + +State & Forms: +- TanStack Query (server state, caching) +- Zustand (client state) +- React Hook Form + zod (validation) + +Realtime: +- WebTransport primary, WebSocket fallback + +Tooling: +- ESLint + Prettier +- Jest (unit) and Playwright (E2E) + +--- + +## Architecture and Project Structure + +Top-level overview mirrors the production Next.js app (App Router): + +``` +frontend/ +β”œβ”€β”€ src/ +β”‚ β”œβ”€β”€ app/ # Next.js 15 App Router (React 19) +β”‚ β”‚ β”œβ”€β”€ (auth)/ # Authentication routes +β”‚ β”‚ β”œβ”€β”€ student/ # Student experience +β”‚ β”‚ β”œβ”€β”€ teacher/ # Teacher experience +β”‚ β”‚ └── admin/ # Admin panel +β”‚ β”œβ”€β”€ components/ # Reusable UI (shadcn/ui foundation) +β”‚ β”œβ”€β”€ hooks/ # React hooks +β”‚ β”œβ”€β”€ lib/ # api/auth/transport/cache/utils +β”‚ β”œβ”€β”€ stores/ # Zustand client state +β”‚ β”œβ”€β”€ types/ # Shared types +β”‚ └── styles/ # Tailwind tokens and globals +β”œβ”€β”€ public/ # Static assets +└── tests/ # Jest + Playwright +``` + +Key choices: +- App Router with server components where useful; route groups per role +- TanStack Query for server state, optimistic updates, and cache invalidation +- WebTransport primary with WebSocket fallback for realtime +- Strict TypeScript with domain types and zod for validation where applicable + +--- + +## Design System and Theming + +- Foundation: Tailwind CSS, shadcn/ui (Radix primitives) +- Brand palette and semantic tokens: success/warn/error/info combined with neutrals +- Typography: Inter system stack, modular scale; readable line-heights +- Themes: light/dark with system preference and manual override, persisted via localStorage +- Accessibility: focus-visible, ARIA, high-contrast variants, keyboard-first patterns + +Example semantic tokens (excerpt): + +```css +/* Semantic Colors */ +--success: #10B981; +--warning: #F59E0B; +--error: #EF4444; +--info: #3B82F6; +``` + +--- + +## Roles and Permissions Model + +We render role-aware navigation and guard routes. Simplified shape: + +```ts +type Role = 'student' | 'teacher' | 'admin' + +interface StudentPermissions { + assessments: { view: boolean; take: boolean; viewResults: boolean; resume: boolean } + profile: { view: boolean; edit: boolean } +} + +interface TeacherPermissions { + assessments: { create: boolean; edit: boolean; delete: boolean; assign: boolean; grade: boolean; analytics: boolean } + questions: { create: boolean; import: boolean; export: boolean; template: boolean } + students: { view: boolean; grade: boolean; feedback: boolean } + bulk: { grade: boolean; assign: boolean; export: boolean } +} + +interface AdminPermissions { + users: { create: boolean; edit: boolean; delete: boolean; roles: boolean } + system: { settings: boolean; monitoring: boolean; audit: boolean; backup: boolean } + analytics: { platform: boolean; export: boolean; compliance: boolean } + tenancy: { manage: boolean; settings: boolean } +} +``` + +--- + +## Core Feature Specs + +### Authentication and Session +- Login, registration, forgot/reset password flows +- PASETO V4 tokens stored in httpOnly cookies; refresh flow supported +- Session timeout with activity tracking, 5‑minute warning, auto‑save, graceful re‑auth + +### Assessment Experience (Student) +- Draft autosave on change and every 30s; forward-only sections supported +- Review mode before submit; timers (per-section and overall) +- Results list and detail with realtime updates from grading events + +### Teacher Tools +- Builder: drag/drop, templates, validation, preview; basic MCQ/TF/short answer +- Assignment: schedule, attempts, groups; publish/unpublish +- Grading: manual rubric UI with per-question points and comments +- Analytics: class overview, question difficulty, CSV export + +### Admin Panel +- Dashboard KPIs, recent activity; Users CRUD (bulk ops), Settings (auth/notifications/flags) +- Audit logs with filters and CSV export; Health tiles with polling/backoff + +--- + +## Security and Compliance + +- FERPA and GDPR alignment; audit logging for sensitive actions +- File upload security: server-side validation and scanning; signed, time-limited downloads +- Content Security Policy and CSRF protections in API mode + +--- + +## Performance and Scalability Targets + +- Initial load < 1s, route transitions < 200ms on typical dev hardware +- API responses < 500ms for common operations; realtime fanout < 100ms typical +- Route-based code-splitting; skeletons; virtualized large lists +- Caching: TanStack Query + browser caching; optional CDN-friendly assets + +--- + +## Development and Testing + +- TypeScript strict; ESLint + Prettier; conventional commits +- Unit tests with Jest; E2E with Playwright on port 3101 in prod mode +- Realtime hooks covered with predicate-based cache invalidation +- See `frontend/README.md` for scripts, envs, and E2E modes (mock vs api) + +--- + +## Roadmap (Excerpt) + +- Short term: multi-browser E2E matrix; API-mode E2E job; analytics depth; i18n scaffold +- Medium: route-level code-splitting for heavy pages; performance budgets and Web Vitals +- Future: offline/PWA exploration for safe student flows; advanced accessibility audits + +--- + +Docs Version: 2.1 β€’ Last Updated: October 29, 2025 diff --git a/frontend/.gitignore b/frontend/.gitignore index f2e32af..67e87f3 100644 --- a/frontend/.gitignore +++ b/frontend/.gitignore @@ -4,3 +4,4 @@ node_modules/ dist/ node_modules.bak-*/ test-results/ +TODO.md diff --git a/frontend/README.md b/frontend/README.md index e7f74c7..6d6f91c 100644 --- a/frontend/README.md +++ b/frontend/README.md @@ -1306,6 +1306,7 @@ We're in **Phase 1** of frontend development, focusing on: - **[Main Project README](../README.md)**: Complete platform overview - **[Backend API Docs](../docs/api.md)**: REST API reference - **[Architecture Docs](../docs/architecture.md)**: System architecture +- **[Frontend Documentation](../docs/frontend.md)**: In-depth frontend docs (more detailed than this README) - **[Contributing Guide](../CONTRIBUTING.md)**: General contribution guidelines --- diff --git a/frontend/tests/e2e/admin-smoke.spec.ts b/frontend/tests/e2e/admin-smoke.spec.ts index 007d533..df2a663 100644 --- a/frontend/tests/e2e/admin-smoke.spec.ts +++ b/frontend/tests/e2e/admin-smoke.spec.ts @@ -44,7 +44,8 @@ test.describe('Admin Panel smoke', () => { test('dashboard shows KPI cards and activity', async ({ page, baseURL }) => { await expect(page.getByRole('heading', { name: /system overview/i })).toBeVisible(); await expect(page.getByText('Total Users')).toBeVisible(); - await expect(page.getByText('1234')).toBeVisible(); + // Accepts formatted numbers like 1,234 as well + await expect(page.getByText(/1,?234/)).toBeVisible(); await expect(page.getByRole('heading', { name: /recent activity/i })).toBeVisible(); }); @@ -57,6 +58,9 @@ test.describe('Admin Panel smoke', () => { await page.waitForTimeout(100); // simple debounce window await expect(page.getByRole('row', { name: /alice johnson/i })).toBeVisible(); + // Clear search then filter role + await page.getByLabel('Search').fill(''); + await page.waitForTimeout(50); // Filter role await page.getByLabel('Role').selectOption('teacher'); await expect(page.getByRole('row', { name: /bob smith/i })).toBeVisible(); diff --git a/frontend/tests/e2e/admin-users-crud.spec.ts b/frontend/tests/e2e/admin-users-crud.spec.ts index a0c8e33..f0536a9 100644 --- a/frontend/tests/e2e/admin-users-crud.spec.ts +++ b/frontend/tests/e2e/admin-users-crud.spec.ts @@ -42,9 +42,10 @@ test.describe('Admin Users create/edit', () => { await page.getByRole('button', { name: /add user/i }).click(); await page.getByLabel('Name').fill('New Person'); await page.getByLabel('Email').fill('new@example.com'); - await page.getByLabel('Role').selectOption('student'); + // Scope Role selection to the Create user form to avoid strict mode conflicts + await page.getByLabel('Create user').getByLabel('Role').selectOption('student'); await page.getByRole('button', { name: /create user/i }).click(); - await expect(page.getByRole('status', { name: /user created/i })).toBeVisible(); + await expect(page.getByText(/user created/i)).toBeVisible(); }); test('edit user inline and save', async ({ page }) => { @@ -53,7 +54,7 @@ test.describe('Admin Users create/edit', () => { const nameInput = page.getByRole('row', { name: /alice@example.com/i }).getByRole('textbox').first(); await nameInput.fill('Alice Cooper'); await page.getByRole('row', { name: /alice@example.com/i }).getByRole('button', { name: /save/i }).click(); - await expect(page.getByRole('status', { name: /user updated/i })).toBeVisible(); + await expect(page.getByText(/user updated/i)).toBeVisible(); await expect(page.getByRole('row', { name: /alice cooper/i })).toBeVisible(); }); }); diff --git a/scripts/README.md b/scripts/README.md index de3891c..b78a490 100644 --- a/scripts/README.md +++ b/scripts/README.md @@ -2,7 +2,7 @@ This directory contains comprehensive testing tools to verify that the entire Pediafor Assessment Platform works correctly across all services. -## οΏ½ Organization +## Organization ``` scripts/ diff --git a/services/assessment-service/README.md b/services/assessment-service/README.md index 8013fc1..1654cc7 100644 --- a/services/assessment-service/README.md +++ b/services/assessment-service/README.md @@ -5,6 +5,8 @@ [![Runtime](https://img.shields.io/badge/runtime-Node.js%2018+-brightgreen?logo=nodedotjs)](.) [![Lang](https://img.shields.io/badge/lang-TypeScript%205.x-blue?logo=typescript)](.) +> Full service documentation: see [docs/assessment-service.md](../../docs/assessment-service.md) + ## Overview The Assessment Service is a core microservice in the Pediafor Assessment Platform, responsible for managing assessments, questions, and media. @@ -239,4 +241,4 @@ Starter issues/ideas: --- -Docs Version: 1.3 β€’ Last Updated: October 20, 2025 \ No newline at end of file +Docs Version: 1.4 β€’ Last Updated: October 29, 2025 \ No newline at end of file diff --git a/services/gateway-service/README.md b/services/gateway-service/README.md index 6811518..a606f63 100644 --- a/services/gateway-service/README.md +++ b/services/gateway-service/README.md @@ -6,6 +6,8 @@ [![Runtime](https://img.shields.io/badge/runtime-Node.js%2018+-brightgreen?logo=nodedotjs)](.) [![Lang](https://img.shields.io/badge/lang-TypeScript%205.x-blue?logo=typescript)](.) +> Full service documentation: see [docs/gateway-service.md](../../docs/gateway-service.md) + ## Overview The Gateway Service is the single entry point for all client applications accessing the Pediafor Assessment Platform. It handles authentication, routing, and other cross-cutting concerns. @@ -84,4 +86,4 @@ Starter issues/ideas: --- -Docs Version: 1.3 β€’ Last Updated: October 20, 2025 \ No newline at end of file +Docs Version: 1.4 β€’ Last Updated: October 29, 2025 \ No newline at end of file diff --git a/services/grading-service/README.md b/services/grading-service/README.md index 6aaef6e..c6f7ec1 100644 --- a/services/grading-service/README.md +++ b/services/grading-service/README.md @@ -5,6 +5,8 @@ [![Runtime](https://img.shields.io/badge/runtime-Node.js%2018+-brightgreen?logo=nodedotjs)](.) [![Lang](https://img.shields.io/badge/lang-TypeScript%205.x-blue?logo=typescript)](.) +> Full service documentation: see [docs/grading-service.md](../../docs/grading-service.md) + ## Overview The Grading Service is a microservice in the Pediafor Assessment Platform responsible for automated grading of student submissions. @@ -163,4 +165,4 @@ Starter issues/ideas: --- -Docs Version: 1.3 β€’ Last Updated: October 20, 2025 \ No newline at end of file +Docs Version: 1.4 β€’ Last Updated: October 29, 2025 \ No newline at end of file diff --git a/services/notification-service/README.md b/services/notification-service/README.md index 438df36..ded35af 100644 --- a/services/notification-service/README.md +++ b/services/notification-service/README.md @@ -6,6 +6,8 @@ [![Lang](https://img.shields.io/badge/lang-TypeScript%205.x-blue?logo=typescript)](.) [![Events](https://img.shields.io/badge/events-RabbitMQ-FF6600?logo=rabbitmq)](.) +> Full service documentation: see [docs/notification-service.md](../../docs/notification-service.md) + ## Overview The Notification Service delivers student-facing notifications and email alerts. It persists notifications, exposes REST APIs for clients, and reacts to grading events. @@ -77,4 +79,4 @@ Starter issues/ideas: --- -Docs Version: 1.3 β€’ Last Updated: October 24, 2025 +Docs Version: 1.4 β€’ Last Updated: October 29, 2025 diff --git a/services/submission-service/README.md b/services/submission-service/README.md index b3b5e22..1074214 100644 --- a/services/submission-service/README.md +++ b/services/submission-service/README.md @@ -5,6 +5,8 @@ [![Runtime](https://img.shields.io/badge/runtime-Node.js%2018+-brightgreen?logo=nodedotjs)](.) [![Lang](https://img.shields.io/badge/lang-TypeScript%205.x-blue?logo=typescript)](.) +> Full service documentation: see [docs/submission-service.md](../../docs/submission-service.md) + ## Overview The Submission Service is a core microservice in the Pediafor Assessment Platform responsible for managing student submissions. @@ -210,4 +212,4 @@ Note: Through the API Gateway, protected alias routes are available at `/submiss --- -Docs Version: 1.3 β€’ Last Updated: October 20, 2025 \ No newline at end of file +Docs Version: 1.4 β€’ Last Updated: October 29, 2025 \ No newline at end of file diff --git a/services/user-service/README.md b/services/user-service/README.md index 07d624e..d664370 100644 --- a/services/user-service/README.md +++ b/services/user-service/README.md @@ -6,6 +6,8 @@ [![Runtime](https://img.shields.io/badge/runtime-Node.js%2018+-brightgreen?logo=nodedotjs)](.) [![Lang](https://img.shields.io/badge/lang-TypeScript%205.x-blue?logo=typescript)](.) +> Full service documentation: see [docs/user-service.md](../../docs/user-service.md) + ## Overview The User Service is a core microservice in the Pediafor Assessment Platform, responsible for user authentication and management.