gg.todo

This requires:

- Stronger domain boundaries and modular system decomposition  
- Explicit lifecycle workflows (user lifecycle, quiz lifecycle, class lifecycle)  
- Realistic business constraints (auditing, data retention, compliance, scalability)  
- Enterprise-grade API standards (pagination, filtering, idempotency, versioning policies)  
- Realistic operational requirements (logging, monitoring, environment configuration, CI/CD considerations)

You are a senior Laravel solution architect specializing in enterprise RESTful API design and scalable MySQL architectures for educational SaaS platforms. Architect a complete backend system for **QuizShort**, a multi-tenant, school-focused assessment and live-quiz platform.

--------------------------------------------------------------------
1. BUSINESS DOMAIN REQUIREMENTS (REAL-WORLD LOGIC)
--------------------------------------------------------------------
Model the system around the operational workflows of real educational institutions:

**Admin (Institution-Level)**
- Full lifecycle control of departments, classes, academic terms, enrollment, and user accounts.
- Ability to activate, suspend, archive, or freeze user accounts.
- Maintain compliance logs, audit trails, and system-wide reporting.
- Manage quiz categories, difficulty levels, and institutional content standards.
- Multi-tenancy preparation (future ready).

**Teacher (Operational Execution)**
- Manage classes and rosters assigned to them by the Admin.
- Create quizzes, schedule quiz windows, manage availability rules, and control retake policies.
- Track student progress, attendance, and performance metrics.
- Review and override scores where allowed by policy.

**Student (End User)**
- Access assigned classes and quizzes based on schedule and visibility rules.
- Participate in quizzes, live challenges, and interactive puzzle-like assessments.
- Receive results, leaderboard positions, credit scores, performance analytics.

--------------------------------------------------------------------
2. QUIZ ENGINE REQUIREMENTS (PRODUCTION SCALE)
--------------------------------------------------------------------
Support an extensible question engine with modular handlers for:

- Multiple choice (single/multiple)  
- Boolean  
- Fill-in-the-blank (text, dropdown, keyword rules)  
- Matching, pairing  
- Ordering/sequencing  
- Drag & drop interactions  
- Media-based questions (image, audio, video with CDN compatibility)  
- Hotspot/area-selection  
- Live-stream interactive questions  
- Timed speed questions with latency compensation rules  
- Poll/Opinion questions (non-scored)  
- Puzzle formats (crossword, word search, rebus)  
- Scenario/case-study with multi-part scoring

**Quiz Lifecycle**
- Draft → Review → Published → Scheduled → Active → Closed → Archived  
- Versioning support for quiz updates without affecting past attempts

**Attempt Lifecycle**
- Initiated → In-progress → Submitted → Auto-graded → Teacher review → Finalized

--------------------------------------------------------------------
3. DATABASE ARCHITECTURE (NORMALIZED + ENTERPRISE-READY)
--------------------------------------------------------------------
Provide a complete ERD covering:

- Users, roles, permissions (RBAC)
- Departments, classes, academic terms
- Class membership, teacher assignments
- Quizzes, question banks, question versions
- Options, media assets, validation rules
- Attempts, attempt logs, scoring rules, analytics tables
- Real-time challenge session structures
- Audit trails (entity-level + request-level)
- Activity logs for compliance and accountability

Include:
- Indexing strategy (composite keys, foreign-key indexing)
- Partitioning considerations for high-volume attempt data
- Soft deletes with restoration policies
- Data retention rules for archival

--------------------------------------------------------------------
4. API ARCHITECTURE (/api/v1 — ENTERPRISE STANDARDS)
--------------------------------------------------------------------
Design a consistent, production-grade REST API with:

- Authentication: Laravel Sanctum token + JWT hybrid
- RBAC middleware + fine-grained policy classes
- Resource-based endpoints following REST conventions
- Pagination, filtering, searching, sorting standards
- Idempotent POST/PUT for critical operations
- Structured error format (RFC 7807 style)

**API Modules**
- Authentication & session management
- User lifecycle management
- Department & class management
- Quiz builder
- Question-type handlers (modularized)
- Quiz scheduling & availability
- Attempt submission & scoring engine
- Real-time challenge endpoints (start, join, broadcast, score-updates)
- Audit logs & reporting
- Teacher & student dashboards

--------------------------------------------------------------------
5. VALIDATION, SCORING & BUSINESS LOGIC LAYER
--------------------------------------------------------------------
Implement a strategy-driven validation architecture supporting:

- Exact match  
- Keyword match  
- Regex  
- Case-insensitive  
- Multi-answer  
- Weighted scoring  
- Partial credit scoring  
- Sequencing tolerance rules  
- Puzzle-specific logic (crossword grid validation)

--------------------------------------------------------------------
6. SECURITY MODEL (PRODUCTION-GRADE)
--------------------------------------------------------------------
Include:

- OAuth-ready structure (for future third-party integrations)
- Token-based access (Sanctum + JWT)
- Rate limiting per role
- Input sanitization and encoding rules
- XSS, CSRF, SQL injection, and replay-attack mitigation
- IP monitoring and suspicious activity alerts
- Entity-level access policies
- Sensitive data encryption

--------------------------------------------------------------------
7. OPERATIONAL REQUIREMENTS
--------------------------------------------------------------------
Include architectural notes for:

- Logging (structured logs, user action logs)
- Monitoring (health checks, readiness endpoints)
- Queue/workers for heavy tasks (scoring, media processing)
- Event broadcasting for live challenges
- Deployment configuration (environment separation)
- Caching strategy using Redis
- Backup and disaster recovery considerations

--------------------------------------------------------------------
8. DOCUMENTATION REQUIREMENTS
--------------------------------------------------------------------
Deliver:
- Full API documentation 
- Request/response examples for every endpoint
- Authentication flow diagrams
- Error codes and meaning
- Postman Collection: `postman-collection-endpoint.json`   fulls setup all Endpoint of API request and use the local URL 127.0.0.1/ and standard base on project build . 
  - Fully configured ready-to-test endpoints
  - Environment variables for base URL and tokens

--------------------------------------------------------------------
9. ARCHITECTURE GOAL
--------------------------------------------------------------------
Backend must be:
- Modular
- Scalable
- Maintainable
- Future-proof for mobile and web integrations
- Real-world production-ready for enterprise education institutions

Return the full technical blueprint based on this prompt. You are a seasoned software architect specializing in designing and optimizing educational assessment systems and APIs. I require your expertise to analyze and enhance the current quiz management workflow and its underlying API logic to ensure robustness, scalability, and clarity of operations.

Please address the following key aspects in your assessment and redesign proposal:

- Quiz Lifecycle Management: Define clear states for quizzes including creation, categorization by type, scheduling, drafting, and expiration based on timetable, subject, and section parameters established by teachers.

- Student Interaction Handling: Devise mechanisms to track ongoing quiz attempts, enforce time limits per quiz and per question as configured by teachers, and handle edge cases such as unanswered questions resulting in zero points.

- Exception and Reassignment Logic: Specify processes for scenarios where students miss quizzes but the quiz remains active, allowing teachers to reassign quizzes to specific students efficiently.

- Scoring and Reporting: Outline rules for score calculation upon completion, ensuring accurate aggregation of marks assigned by teachers, and enable comprehensive monitoring of student participation, missed quizzes, and performance metrics.

- Dashboard and User Management: Propose a smart dashboard design to give teachers real-time insight into quiz statuses, student progress, and the ability to manage assignments and exceptions seamlessly.

- API Flow and Standards: Recommend logical flow improvements and best practices for API design supporting these features, ensuring maintainability, security, and extensibility.

Leverage your advanced experience in API architecture and educational software to deliver a detailed, logically coherent, and standards-compliant solution that addresses all functional requirements and edge cases within the quiz workflow.