Authoring Principles
How all MASARUK analysis files must be written, reviewed, and maintained
1. Purpose
This document defines how all files inside the analysis/ folder must be written, reviewed, and maintained.
- All analysis is consistent, precise, and implementation-ready
- Any engineer (Backend, Frontend, Mobile, QA, DevOps), AI agents, and external vendors can understand the system
- Requirements can be mapped directly to code, data models, tests, and deployments
- The analysis reflects the actual product as inferred from UI screens and raw analysis
2. Sources of Truth
All analysis must be based strictly on the following, in order of priority:
1. Raw analysis and UI descriptions
Screenshots and textual breakdowns of Admin, Provider Portal, B2C Web, Mobile Apps
2. Official product and technical identity
Product name, tech stack (Next.js, Flutter, Node.js, PostgreSQL), integrations (HyperPay, STC Pay, Firebase)
3. Minimal, clearly justified technical inference
Only when the UI cannot function without the inferred element
❌ Forbidden:
- Invent features, modules, or integrations that do not exist
- Redesign business rules from imagination
- Add assumptions without documenting them as open questions
3. Language Policy
The analysis folder is primarily written in English, with these rules:
Arabic Text
- Arabic UI text is always preserved exactly as shown in the UI
- Even if there are spelling or grammar issues, copy as-is
- Examples: 'ملغاه', 'تم أرسال تقييمك بنجاح'
Fields and Labels
- Always provide the Arabic UI label (verbatim)
- Always provide the English technical equivalent
- For statuses: provide Arabic, English, and Enum values
4. File Structure
- Every file starts with a header block (File, Folder, Project)
- Use numbered sections for main topics
- Use sub-sections for detailed breakdowns
- Include cross-references to related documents
- End with Related Documents section
5. Quality Rules
- No speculation or invented features
- All assumptions must be logged in open-questions.md
- Cross-reference related documents
- Use consistent terminology across all files
- Review before finalizing any document