# Joseph App — Full Platform Specification
**Version:** 1.0 — MVP + Full Roadmap  
**Last Updated:** May 2026  
**App Name:** Joseph (يوسف)  
**Tagline EN:** Discover Your Calling. Build Your Project. Serve the Kingdom.  
**Tagline AR:** اكتشف دعوتك. ابنِ مشروعك. اخدم الملكوت.

---

## Table of Contents

1. [Platform Overview](#1-platform-overview)
2. [Design System — Mobile App](#2-design-system--mobile-app)
3. [Database Architecture](#3-database-architecture)
4. [Rounds / Cohort System](#4-rounds--cohort-system)
5. [Mobile App — Flutter (Full Spec)](#5-mobile-app--flutter-full-spec)
   - 5.1 Auth & Onboarding
   - 5.2 Home Dashboard
   - 5.3 Discover Your Calling (دعوتي)
   - 5.4 Work in God's Word (شغلي للرب)
   - 5.5 Build Your Project (ابنِ مشروعك)
   - 5.6 Kingdom Projects (مشروع برسالة)
   - 5.7 Live Mentor (مرشدك)
   - 5.8 Community (مجتمع يوسف)
   - 5.9 Challenges (التحديات)
   - 5.10 Joseph Map (خريطة يوسف)
   - 5.11 Notifications
   - 5.12 Profile & Settings
6. [Admin Panel — Native PHP + MySQL (Full Spec)](#6-admin-panel--native-php--mysql-full-spec)
   - 6.1 Admin Roles & Permissions
   - 6.2 Dashboard
   - 6.3 Rounds Management
   - 6.4 Users Management
   - 6.5 Content Management (all 7 sections)
   - 6.6 Mentors & Sessions
   - 6.7 Community Moderation
   - 6.8 Challenges Management
   - 6.9 Joseph Map Management
   - 6.10 Notifications & Announcements
   - 6.11 Reports & Analytics
   - 6.12 Settings & Localization
7. [API Architecture](#7-api-architecture)
8. [Localization Strategy](#8-localization-strategy)
9. [MVP Scope](#9-mvp-scope)
10. [Future Roadmap](#10-future-roadmap)

---

## 1. Platform Overview

### What is Joseph?

Joseph is a bilingual (Arabic/English) digital platform designed for Christian youth to:
- Discover their calling and gifts
- Build businesses rooted in biblical principles
- Understand "Work as Worship"
- Apply Business as Mission (BAM)
- Join guided cohorts (Rounds) with mentors and a faith-based community

The platform consists of:
| Layer | Technology |
|---|---|
| Mobile App | Flutter (iOS + Android) |
| Admin Panel | Native PHP 8.2, Bootstrap 5, Vanilla JS |
| Database | MySQL 8.0 |
| API | REST, JSON, PHP backend |
| Push Notifications | Firebase Cloud Messaging (FCM) |
| Real-time Chat | WebSocket or Firebase Realtime DB |
| File Storage | Local server / S3-compatible |

### Target Users (Mobile App)
1. Youth who don't know where to start
2. Youth with skills who want to build a project
3. Youth who want to work in a God-honoring way
4. Youth who want a Kingdom-purpose project
5. Church leaders who want to equip youth
6. Christian business owners seeking spiritual + practical principles

### Admin Users
| Role | Description |
|---|---|
| Super Admin | Full system control |
| Editor | Manages content (lessons, challenges, topics) |
| Mentor | Manages own sessions, responds to users |
| Moderator | Manages community, flags, approvals |
| Round Manager | Manages cohort enrollment and progress |

---

## 2. Design System — Mobile App

### Theme: Luxury Gold & Black

The Joseph app visual identity is built on a premium, timeless luxury aesthetic — rooted in the story of Joseph's elevation from servant to ruler. Every screen should feel like entering a space of dignity, purpose, and clarity.

### Color Palette

| Token | Hex | Usage |
|---|---|---|
| `primary` | `#C9A84C` | Gold — primary CTA, highlights, icons |
| `primary-dark` | `#A8852E` | Pressed/hover state of gold |
| `primary-light` | `#E8C97A` | Soft gold — subtitles, borders |
| `background` | `#0A0A0A` | Deep black — main background |
| `surface` | `#141414` | Card surfaces |
| `surface-elevated` | `#1E1E1E` | Elevated cards, bottom sheets |
| `on-surface` | `#F5F0E8` | Primary text on dark |
| `on-surface-secondary` | `#9A9080` | Secondary text / captions |
| `accent-teal` | `#2C7873` | Secondary accent (Kingdom section) |
| `accent-crimson` | `#8B2020` | Error / alert states |
| `divider` | `#2A2A2A` | Dividers and separators |
| `gold-gradient-start` | `#F0D080` | Gradient start |
| `gold-gradient-end` | `#8B6914` | Gradient end |

### Typography

| Role | Font | Weight | Size |
|---|---|---|---|
| Display / Hero | Playfair Display | Bold | 32–40sp |
| Heading 1 | Playfair Display | SemiBold | 24–28sp |
| Heading 2 | Playfair Display | Medium | 20sp |
| Body | Inter | Regular | 16sp |
| Body Small | Inter | Regular | 14sp |
| Caption | Inter | Light | 12sp |
| Arabic Display | Amiri | Bold | 28–36sp |
| Arabic Body | Cairo | Regular | 16sp |
| Arabic Caption | Cairo | Light | 13sp |

### UI Components

| Component | Style Description |
|---|---|
| Primary Button | Gold gradient, black text, rounded 12dp, subtle shadow |
| Secondary Button | Gold border on black, gold text, transparent fill |
| Ghost Button | No border, gold text only |
| Cards | `#141414` background, 1px `#2A2A2A` border, 12–16dp radius, gold top accent line |
| Bottom Navigation | Black bar, gold selected icon, muted unselected |
| AppBar | Transparent over black, gold logo center or left, gold icon buttons |
| Input Fields | Dark fill `#1A1A1A`, gold bottom border on focus, `#F5F0E8` text |
| Tags/Chips | Gold border, small rounded, gold text |
| Progress Bars | Gold fill on dark track |
| Badges | Gold solid, black text |
| Section Dividers | Thin gold horizontal line with centered label |
| Illustrations | Line-art style, gold on black — inspired by ancient Egyptian/Byzantine motifs |
| Loading | Gold shimmer skeleton |

### Iconography
- Line icons (Phosphor or Lucide style), gold colored on dark backgrounds
- Section icons: each of the 7 sections has a unique symbolic icon (dove, compass, tools, crown, person, community, flame)

### Spacing & Grid
- Base spacing unit: 8dp
- Margin: 20dp horizontal
- Card padding: 16–20dp
- Bottom nav height: 64dp
- Safe area: respect iOS/Android notch

### Motion & Animation
- Page transitions: Fade + slide (300ms ease-in-out)
- Card tap: Scale 0.97 spring animation
- Gold shimmer loading on skeleton screens
- Lottie animations for: milestone achievements, challenge completion, Joseph Map stage unlock

---

## 3. Database Architecture

### Core Tables

#### users
```
id, name_ar, name_en, email, phone, password_hash, avatar,
gender, birth_year, city, country, church_name,
primary_language (ar/en), notification_token,
status (pending/active/suspended), created_at, updated_at
```

#### rounds
```
id, name_ar, name_en, description_ar, description_en,
start_date, end_date, max_participants, registration_deadline,
status (draft/open/active/closed/archived),
round_number, cohort_year, created_by, created_at
```

#### round_applications
```
id, user_id, round_id, motivation_text, skills_summary,
goal_type (job/project/calling/kingdom_project),
status (pending/approved/rejected/waitlisted),
reviewed_by, reviewed_at, rejection_reason, created_at
```

#### round_enrollments
```
id, user_id, round_id, enrolled_at, track
(discover_self/start_project/kingdom_project),
progress_percentage, completed_at, certificate_issued
```

#### joseph_map_stages
```
id, stage_key, order_index, name_ar, name_en,
description_ar, description_en, icon, milestone_label_ar,
milestone_label_en, unlocks_at_percentage
```

#### user_map_progress
```
id, user_id, current_stage_id, stage_started_at,
stage_completed_at, notes
```

#### sections
```
id, section_key, name_ar, name_en, icon, color,
description_ar, description_en, is_active, order_index
```

#### lessons
```
id, section_id, title_ar, title_en, body_ar, body_en,
verse_ar, verse_en, verse_reference, practical_application_ar,
practical_application_en, accountability_question_ar,
accountability_question_en, content_type (article/video/audio),
media_url, thumbnail_url, duration_seconds, is_published,
is_premium, order_index, created_by, created_at
```

#### challenges
```
id, title_ar, title_en, description_ar, description_en,
duration_days, type (7day/14day/30day/custom),
is_active, start_date, related_section_id, created_at
```

#### challenge_days
```
id, challenge_id, day_number, task_ar, task_en,
verse_ar, verse_en, reflection_question_ar,
reflection_question_en, tip_ar, tip_en
```

#### user_challenge_progress
```
id, user_id, challenge_id, round_id, enrolled_at,
current_day, last_checkin_at, status (active/paused/completed),
completion_percentage
```

#### skill_assessment_questions
```
id, question_ar, question_en, question_type (single/multi/scale),
order_index, category (enjoyment/skill/style/market/teamwork/leadership)
```

#### skill_assessment_options
```
id, question_id, option_ar, option_en, tags (JSON),
weight_score
```

#### user_assessments
```
id, user_id, completed_at, raw_answers (JSON),
personality_type, strength_tags (JSON), risk_tags (JSON),
suitable_fields (JSON), project_type, next_steps (JSON)
```

#### project_types
```
id, type_key, name_ar, name_en, description_ar, description_en,
icon, steps (JSON), templates (JSON)
```

#### kingdom_models
```
id, model_key, name_ar, name_en, description_ar, description_en,
examples (JSON), is_featured
```

#### mentors
```
id, user_id, bio_ar, bio_en, expertise_tags (JSON),
availability_schedule (JSON), session_price (0=free),
is_active, rating_avg, total_sessions, approved_by, created_at
```

#### mentor_sessions
```
id, mentor_id, user_id, round_id, session_type (chat/video/group),
scheduled_at, duration_minutes, status (pending/confirmed/completed/cancelled),
meeting_link, notes, user_rating, user_review, created_at
```

#### community_groups
```
id, name_ar, name_en, type (field/city/project_type/prayer/accountability),
description_ar, description_en, icon, is_private,
max_members, moderator_id, round_id, created_at
```

#### community_posts
```
id, group_id, user_id, content_ar, content_en, media_urls (JSON),
is_pinned, is_approved, flagged_count, created_at
```

#### community_post_replies
```
id, post_id, user_id, content, created_at
```

#### notifications
```
id, user_id, title_ar, title_en, body_ar, body_en,
type (system/lesson/challenge/mentor/community/round),
related_id, related_type, is_read, sent_at
```

#### admin_users
```
id, name, email, password_hash, role
(super_admin/editor/mentor/moderator/round_manager),
preferred_language (ar/en), is_active, last_login, created_at
```

#### admin_activity_logs
```
id, admin_id, action, target_type, target_id, details (JSON), created_at
```

#### app_settings
```
id, key, value, type (text/json/boolean/number),
description, updated_by, updated_at
```

---

## 4. Rounds / Cohort System

### Concept
A **Round** (دورة) is a structured cohort program — a defined period during which a group of users go through the Joseph curriculum together, supported by mentors and community.

### Round Lifecycle

```
DRAFT → OPEN (Registration) → ACTIVE (Running) → CLOSED → ARCHIVED
```

#### Stage Descriptions
| Status | Description |
|---|---|
| Draft | Round created but not visible to users |
| Open | Registration window active — users can apply |
| Active | Round is running, enrolled users access content |
| Closed | Round ended, no new activity |
| Archived | Historical reference only |

### Round Application Flow (User)
1. User sees available round on app with description, dates, and goal
2. User submits application:
   - Motivation text (Why do you want to join?)
   - Skills summary (What are your current skills?)
   - Goal type: Job / Project / Calling / Kingdom Project
3. Application status: **Pending → Approved / Rejected / Waitlisted**
4. If approved → User is enrolled and assigned to a track
5. Admin sets max participants and registration deadline

### Tracks Within a Round
| Track | Target User |
|---|---|
| Discover Myself (اكتشف نفسي) | Youth who don't know their direction |
| Start a Project (ابدأ مشروع) | Youth with skills or an idea |
| Kingdom Project (مشروع ملكوتي) | Youth seeking mission + impact |

### Round Content Binding
- Challenges can be linked to a specific round (group starts together)
- Lessons can be sequenced and unlocked per round week
- Joseph Map progress tracked per round enrollment
- Community groups created per round

### Certificates
- On round completion (configurable threshold %), user receives a digital certificate
- Certificate includes: user name, round name, track, date, app logo
- Available for download as PDF from within the app

---

## 5. Mobile App — Flutter (Full Spec)

### 5.1 Auth & Onboarding

#### Splash Screen
- Full black screen
- Joseph logo (gold crown/wheat motif) fades in with gold shimmer
- App name "Joseph" in Playfair Display, gold
- Arabic tagline fades in below: اكتشف دعوتك. ابنِ مشروعك. اخدم الملكوت.
- Duration: 2.5 seconds → auto-navigate

#### Language Selection (First Launch Only)
- Two elegant cards side by side: English / العربية
- Gold border on selected
- "Continue" gold button
- Language stored locally and in profile

#### Welcome Screens (3 slides, swipeable)
| Slide | Illustration | Headline EN | Headline AR |
|---|---|---|---|
| 1 | Compass on black | Discover Your Calling | اكتشف دعوتك |
| 2 | Building blocks | Build With Purpose | ابنِ بهدف |
| 3 | Torch/flame | Serve the Kingdom | اخدم الملكوت |

- Gold dots indicator
- Skip (muted) + Next (gold)
- Final slide: "Get Started" full-width gold button

#### Register Screen
Fields: Full Name, Email, Phone, Password, Confirm Password, City, Church Name (optional), Gender
- "I agree to Terms and Conditions" checkbox
- Register button → gold gradient
- Already have account? Sign In link

#### Sign In Screen
- Email + Password
- Forgot Password link
- Sign In button
- Don't have account? Register link

#### Goal Selection (Post-Register, Onboarding Step)
- Screen title: "What's your goal?" / "ما هدفك؟"
- 4 cards with icon, title, subtitle:
  1. Find My Direction — I'm not sure where to start
  2. Build a Project — I have a skill or idea
  3. Work with Purpose — I want to honor God in my work
  4. Kingdom Impact — I want a mission-driven project
- Multiple selection allowed
- This data sets their track recommendation

#### Skill Assessment Invitation
- After goal selection: "Let's discover your strengths"
- User can "Start Now" or "Later"

---

### 5.2 Home Dashboard

#### Layout (Top to Bottom)
1. **AppBar**: Logo left, notification bell right, language toggle right
2. **Greeting**: "Good morning, [Name] 👑" in gold, date below
3. **Active Round Card** (if enrolled):
   - Round name, progress bar (gold), days remaining
   - Track badge, "Continue" button
4. **Verse of the Day** — decorative card, gold border, verse text + reference, soft background pattern
5. **Today's Lesson** — card with thumbnail, section tag, title, duration chip
6. **Your Task Today** — bold action card, gold accent left bar, task text, checkbox
7. **Weekly Progress** — 7-dot row, filled gold = completed days
8. **Quick Actions Grid** (2x2 or 2x3):
   - Start Your Project
   - Test Your Skills
   - Request a Mentor
   - Your Community
   - Joseph Map
   - Kingdom Project
9. **Success Stories** — horizontal scroll, portrait cards with quote excerpt
10. **Upcoming Sessions** (if mentor session booked)

---

### 5.3 Discover Your Calling — دعوتي

#### Entry Screen
- Section icon + title
- Description: "Answer a few questions and discover your strengths, personality, and the right path for you."
- "Start Assessment" button
- View Previous Results (if done before)

#### Assessment Flow
**Phase 1 — Enjoyment (6 questions)**
What activities bring you joy? What do you lose track of time doing?

**Phase 2 — Skills (6 questions)**
What do people ask you for help with? What comes naturally to you?

**Phase 3 — Work Style (4 questions)**
Do you prefer: Sales / Management / Creativity / Teaching?
Individual / Team?

**Phase 4 — Market Awareness (3 questions)**
What needs do you see around you? What problems could you solve?

**Phase 5 — Leadership Style (3 questions)**
Are you a Leader / Executor / Innovator?

**UI per Question:**
- Question text (large, Playfair)
- Options as selectable cards (gold border on selected)
- Progress indicator (gold bar at top, e.g., "12 / 22")
- Back arrow enabled

#### Results Screen
After submission — elegant results reveal animation:

| Section | Content |
|---|---|
| **Personality Type** | e.g., "The Creative Builder" with icon |
| **Your Strengths** | 3–5 tags (gold chips) |
| **Watch Out For** | 2–3 risk traits |
| **Best Fields For You** | e.g., Digital, Training, Social |
| **Recommended Project Type** | e.g., Digital Services |
| **Your Next Steps** | Numbered list |
| **Recommended Track** | Card with CTA to enroll |

- "Save Results" button
- "Share Results" (image export)
- "Start Your Journey" → routes to recommended section

---

### 5.4 Work in God's Word — شغلي للرب

#### Section Home
- Section header (gold icon, title, subtitle)
- Topic list: cards with icon, title, verse preview, completion indicator
- Filter tabs: All / Completed / In Progress / Saved

#### Topics List (Pre-loaded)
1. Work as Worship — العمل عبادة
2. Faithfulness in Little — الأمانة في القليل
3. Integrity in the Marketplace — النزاهة في السوق
4. Not Loving Money — عدم محبة المال
5. Diligence & No Laziness — الاجتهاد وعدم الكسل
6. Hearing God's Voice at Work — سماع صوت الله في شغلي
7. Dealing with Failure — كيف أتعامل مع الفشل
8. Dealing with Competition — كيف أتعامل مع المنافسة
9. Dealing with Partnership — كيف أتعامل مع الشراكة
10. My Project as a Blessing — مشروعي بركة لا دخل فقط

#### Lesson Detail Screen
Layout (scrollable):
1. **Topic Title** — Playfair, large, gold
2. **Key Verse** — styled card, gold border, verse + reference
3. **Explanation** — body text, readable, well-spaced
4. **Practical Application** — card with action icon, steps
5. **Accountability Question** — italic, reflective tone
6. **Weekly Challenge** — gold action card with checkbox
7. **Mark as Complete** — bottom sticky button
8. **Related Lessons** — horizontal scroll

Content types supported:
- Article (rich text)
- Video (inline player)
- Audio (custom player with waveform, gold controls)

---

### 5.5 Build Your Project — ابنِ مشروعك

#### Section Home
- Title + subtitle
- "What kind of project?" → Project type selector
- My Project (if already started) — progress card
- Browse All Tracks

#### Project Type Selection (8 Types)
| Type | Arabic |
|---|---|
| Services Project | مشروع خدمات |
| Products Project | مشروع منتجات |
| Digital Project | مشروع رقمي |
| Training & Coaching | تدريب وكوتشنج |
| Trade | تجارة |
| Content Creation | صناعة محتوى |
| Social / Service Project | مشروع اجتماعي/خدمي |
| Sustainable Kingdom Project | مشروع ملكوتي مستدام |

#### Track Detail (per project type)
Steps presented as a vertical journey (stepper):
1. Choose Your Idea
2. Study the Need
3. Target Customer
4. Pricing
5. First Experiment
6. Marketing
7. Money Management
8. Build a Team
9. Expand

Each step:
- Title + description
- Guided questions
- Action tasks
- Downloadable template link
- "Mark Step Complete" button

#### Templates Library
Available templates (PDF/fillable view):
- Project Idea Canvas
- Simple Market Study Template
- Pricing Model Template
- 30-Day Launch Plan
- Cost & Profit Calculator

---

### 5.6 Kingdom Projects — مشروع برسالة

#### Section Home
- Intro: "Not just a business. A mission."
- Three models displayed as cards:
  1. Kingdom Principles Business — مشروع تجاري بمبادئ ملكوتية
  2. Direct Community Service — يخدم المجتمع مباشرة
  3. Business as Mission (BAM) — مشروع Business as Mission

#### Key Questions Guided Module
Interactive Q&A exploration:
- How can my project have a mission?
- How can I serve society through my business?
- How can I create job opportunities?
- How can I use profit to support ministry?
- How can I create a sustainable service model?
- How do I balance profit and mission?

#### Example Inspirations
- Training Academy for Youth
- Content Platform that Builds Values
- Brand Supporting a Social Cause
- Company that Employs and Equips Youth
- Project that Funds a Ministry or Mission

Each example: story card, model type tag, key lesson

---

### 5.7 Live Mentor — مرشدك

#### Section Home
- Browse Mentors: filterable by expertise, language, availability
- My Sessions: upcoming, past
- Request Help — quick form for urgent needs

#### Mentor Card
- Avatar (circular, gold ring)
- Name, title/expertise
- Star rating + session count
- Expertise tags (gold chips)
- Available / Busy indicator
- "Book Session" button

#### Mentor Profile
- Full bio
- Expertise areas
- Session types offered (Chat / Video / Group)
- Price per session (or Free)
- Reviews
- Availability calendar
- "Book" CTA

#### Session Booking Flow
1. Select session type
2. Select date/time from calendar
3. Add topic / what you need help with
4. Confirm booking
5. Receive confirmation + calendar event

#### Request Help (Quick Form)
Category options:
- Confused about an idea
- Failed in a project
- Have debts
- Looking for a partner
- Need a start plan
- Want skills evaluation

Short text field + Submit → Goes to mentor pool / admin

#### Chat Interface
- Gold message bubbles (own)
- Dark bubbles (mentor)
- File attachment support
- Voice note support
- Read receipts

---

### 5.8 Community — مجتمع يوسف

#### Section Home
- My Groups: horizontally scrollable cards
- Discover Groups: filterable list
- Community Rules banner (visible always)

#### Group Types
| Type | Description |
|---|---|
| By Field | Tech, Education, Arts, Healthcare, etc. |
| By City | Cairo, Alexandria, Assiut, etc. |
| By Project Type | Content, Services, Trade, etc. |
| Prayer | Praying for work and projects |
| Accountability | Weekly check-in partners |
| Round Groups | Specific to a cohort round |

#### Community Rules (enforced)
- Respect all members
- No exploitation
- No random selling/promotion
- No misleading content
- No non-transparent partnerships
- Report violations with one tap

#### Post Feed (Inside Group)
- Pinned posts at top (gold pin icon)
- Posts: user avatar, name, time, text, optional image
- Reactions: Pray 🙏 / Encourage 💪 / Helpful 💡
- Comments thread
- Report button (flag icon)
- Pending approval badge if moderation is on

#### Success Stories Section
- Curated by admin
- Full-width photo card
- Story title, excerpt, "Read More"
- Share button

---

### 5.9 Challenges — التحديات

#### Section Home
- Active Challenge (if enrolled): large card, day counter, progress ring
- Available Challenges: list
- Completed Challenges: history with badge

#### Challenge Types
| Challenge | Duration | Focus |
|---|---|---|
| 7-Day Faithfulness | 7 days | Integrity in work |
| 14-Day Skill Discovery | 14 days | Identifying gifts |
| 30-Day Project Launch | 30 days | Starting a project |
| Financial Discipline | 21 days | Money management |
| Marketing Without Fear | 10 days | Promotion & outreach |
| Work as Worship | 7 days | Spiritual work mindset |

#### Daily Challenge Screen
- Day number + challenge title
- Progress ring (gold, animated)
- Today's Task — prominent card
- Today's Verse
- Reflection Question
- Practical Tip
- Check-In button (marks day complete)
- Streak indicator (gold flame)

#### Completion Screen
- Lottie animation: gold confetti / crown
- Badge earned
- Summary of journey
- Share achievement (image card)
- "What's Next?" recommendation

---

### 5.10 Joseph Map — خريطة يوسف

#### Concept
A visual journey map showing 7 stages — where the user currently is and what's ahead.

#### 7 Stages
| # | Key | Label EN | Label AR |
|---|---|---|---|
| 1 | discovered | Discovering Myself | اكتشف نفسي |
| 2 | learning | Learning & Growing | أتعلم وأنمو |
| 3 | ideating | Starting an Idea | أبدأ فكرة |
| 4 | testing | Testing the Market | أجرب السوق |
| 5 | launching | Launching My Project | أطلق مشروعي |
| 6 | building | Building My Team | أبني فريقي |
| 7 | impact | Creating Kingdom Impact | أصنع تأثير ملكوتي |

#### Map UI
- Vertical or diagonal path design (like a treasure/journey map)
- Each stage: circular node, gold when reached, dim when ahead
- Connecting path: gold dotted line, animated when progressing
- Active stage: glowing gold pulse
- Tapping a stage: bottom sheet with description, resources, and what to do to unlock

#### Progress Logic
- Advances based on: lesson completions, challenge check-ins, assessment, round progress
- Admin can manually adjust stage via admin panel
- Milestone celebrated with Lottie animation on stage unlock

---

### 5.11 Notifications

- Notification center in-app (bell icon, badge)
- Types:
  - System (round updates, announcements)
  - Lesson (new lesson, daily reminder)
  - Challenge (daily task reminder, streak warning)
  - Mentor (session reminder, message)
  - Community (new post in my group)
  - Round (application status, new round open)
- Each notification: icon, title, body, time, read/unread indicator
- Tap → navigates to relevant screen

---

### 5.12 Profile & Settings

#### Profile Screen
- Avatar (editable, circular, gold ring)
- Name, Church, City
- Joseph Map current stage badge
- Round enrollment status
- Assessment results summary
- Statistics: Lessons completed / Challenges completed / Days active

#### Settings
- Language toggle (Arabic / English)
- Notification preferences (per type)
- Change password
- Edit profile
- Terms & Conditions
- Privacy Policy
- About Joseph
- Log Out

---

## 6. Admin Panel — Native PHP + MySQL (Full Spec)

### Tech Stack
- PHP 8.2 (no framework — pure procedural/OOP)
- MySQL 8.0
- Bootstrap 5.3
- Vanilla JavaScript (ES6+)
- jQuery (for select2, datatables, etc.)
- DataTables.js (for all data grids)
- Chart.js (analytics charts)
- Select2 (enhanced dropdowns)
- SweetAlert2 (confirmations, alerts)
- Flatpickr (date/time pickers)
- Summernote WYSIWYG (for rich text content)

### Admin Color Theme (Panel UI)
- Sidebar: `#0D0D0D` (near black)
- Sidebar active: `#C9A84C` (gold) text + left border
- Top bar: `#111111`
- Content area: `#F8F7F4` (warm off-white)
- Card backgrounds: `#FFFFFF`
- Accent: `#C9A84C` (gold)
- Danger: `#DC3545`
- Success: `#198754`

### Language Toggle (Admin)
- Top-right toggle: EN | AR
- Panel labels, buttons, table headers switch language
- Content fields always show both: `field_ar` and `field_en` side by side

---

### 6.1 Admin Roles & Permissions

| Permission | Super Admin | Editor | Round Manager | Moderator | Mentor |
|---|---|---|---|---|---|
| Manage Admins | ✅ | ❌ | ❌ | ❌ | ❌ |
| Manage Rounds | ✅ | ❌ | ✅ | ❌ | ❌ |
| Approve Applications | ✅ | ❌ | ✅ | ❌ | ❌ |
| Manage Content | ✅ | ✅ | ❌ | ❌ | ❌ |
| Manage Challenges | ✅ | ✅ | ❌ | ❌ | ❌ |
| Manage Community | ✅ | ❌ | ❌ | ✅ | ❌ |
| Manage Mentors | ✅ | ❌ | ❌ | ❌ | ❌ |
| View Own Sessions | ✅ | ❌ | ❌ | ❌ | ✅ |
| Manage Own Sessions | ✅ | ❌ | ❌ | ❌ | ✅ |
| View Analytics | ✅ | ❌ | ✅ | ❌ | ❌ |
| Manage Notifications | ✅ | ✅ | ❌ | ❌ | ❌ |
| System Settings | ✅ | ❌ | ❌ | ❌ | ❌ |

---

### 6.2 Dashboard (Home)

**Top KPI Row (4 cards):**
- Total Active Users
- Active Round Enrollments
- Pending Applications
- Sessions This Week

**Second Row (Charts — Chart.js):**
- User Registrations (line chart, 30 days)
- Round Enrollment by Track (donut chart)

**Third Row:**
- Recent Applications (mini table: name, round, goal, status, action)
- Upcoming Mentor Sessions (mini table: mentor, user, date, type)
- Flagged Community Posts (mini table: group, post excerpt, flags count, action)

**Quick Actions Bar:**
- + New Round
- + New Lesson
- + Send Notification
- + New Challenge

---

### 6.3 Rounds Management

#### Rounds List Page
- DataTable: Round #, Name (EN/AR), Dates, Status, Participants, Actions
- Filter: by status, by year
- "New Round" button

#### Create / Edit Round Form
Fields:
- Round Number (auto-incremented or manual)
- Name AR + Name EN
- Description AR + Description EN (Summernote rich text)
- Registration Start Date + End Date (Flatpickr)
- Round Start Date + End Date
- Max Participants
- Status dropdown
- Tracks enabled (checkboxes: Discover / Start / Kingdom)
- Save as Draft / Publish

#### Round Detail Page
Tabs:
1. **Overview** — stats: total applied, approved, rejected, enrolled, completed
2. **Applications** — DataTable with:
   - User name, email, goal type, motivation (expandable), status
   - Bulk actions: Approve selected / Reject selected
   - Individual: View Full Application → modal with all details + Approve/Reject/Waitlist buttons + rejection reason field
3. **Enrolled Users** — DataTable:
   - Name, track, enrollment date, progress %, Joseph Map stage
   - Manual stage override button
   - Issue Certificate button
4. **Round Groups** — list community groups tied to this round
5. **Round Challenges** — assign challenges to run within this round
6. **Analytics** — progress chart, completion rate, track distribution

---

### 6.4 Users Management

#### Users List
- DataTable: ID, Name, Email, City, Round Status, Reg Date, Status
- Filters: Status, Round, City, Gender, Church
- Actions per row: View, Edit, Suspend, Delete

#### User Detail Page
Tabs:
1. **Profile** — all fields editable, avatar preview
2. **Round History** — all rounds applied/enrolled/completed
3. **Assessment Results** — personality type, strengths, field recommendations
4. **Lesson Progress** — completed lessons per section, percentage
5. **Challenge Progress** — active and past challenges, check-in history
6. **Joseph Map** — current stage, history of stage changes
7. **Mentor Sessions** — past and upcoming
8. **Community** — groups joined, posts made, flags received
9. **Activity Log** — timestamped list of all user actions

#### Bulk Actions
- Export to CSV
- Send notification to selected users
- Change round enrollment status

---

### 6.5 Content Management

#### 6.5.1 Sections Manager
- List of 7 sections with name, icon, status toggle, order
- Drag-and-drop reorder
- Edit: names (AR/EN), icon upload, color picker, description (AR/EN), active toggle

#### 6.5.2 Lessons Manager
**Lessons List:**
- DataTable: Title EN, Section, Type, Status (Published/Draft), Premium, Created, Actions
- Filter by section, type, status
- "New Lesson" button

**Create/Edit Lesson Form:**
- Section (dropdown)
- Title AR + Title EN
- Content Type: Article / Video / Audio
- Body AR (Summernote WYSIWYG, RTL mode)
- Body EN (Summernote WYSIWYG)
- Key Verse AR + EN + Reference
- Practical Application AR + EN (Summernote)
- Accountability Question AR + EN
- Weekly Challenge AR + EN
- Media URL (video/audio link or file upload)
- Thumbnail upload
- Duration (seconds — auto-detect if file uploaded)
- Is Premium (toggle)
- Order Index
- Is Published (toggle)
- Save Draft / Publish Now

#### 6.5.3 Skill Assessment Manager
**Questions List:**
- DataTable: ID, Category, Question EN preview, Type, Order, Actions
- Drag-to-reorder

**Create/Edit Question Form:**
- Question AR + EN
- Category (Enjoyment / Skill / Work Style / Market / Teamwork / Leadership)
- Question Type (Single Select / Multi Select / Scale 1–5)
- Order Index

**Options Manager (per question):**
- Inline add/edit/delete options
- Option AR + EN
- Tags (JSON — e.g., ["creative", "visual", "solo"])
- Weight Score

**Results Configuration:**
- Personality type mappings (based on tag combinations)
- Strength tag definitions
- Field recommendation logic
- Project type mapping table

#### 6.5.4 Project Types Manager
- List: Type key, Name EN/AR, Status, Actions
- Create/Edit:
  - Type key (slug)
  - Name AR + EN
  - Description AR + EN
  - Icon upload
  - Steps editor (repeater): Title AR/EN, Description AR/EN, Questions, Tasks
  - Templates (upload PDF templates)

#### 6.5.5 Kingdom Models Manager
- CRUD for 3 models + examples
- Name AR + EN, Description AR + EN, Examples (repeater), Featured toggle

---

### 6.6 Mentors & Sessions

#### Mentors List
- DataTable: Avatar, Name, Expertise, Sessions, Rating, Status, Actions
- Approve / Suspend / Remove

#### Mentor Application Review
- Bio, expertise, proposed schedule, pricing
- Approve with role assignment or Reject with reason

#### Create/Edit Mentor Profile (Admin side)
- Link to existing user account
- Bio AR + EN (Summernote)
- Expertise tags (Select2 multi)
- Session types offered (checkboxes)
- Price per session
- Availability schedule (weekly grid)
- Activate / Deactivate

#### Sessions Manager
- DataTable: Mentor, User, Type, Date/Time, Status, Rating
- Filters: by mentor, by status, by date range
- View session notes
- Cancel session + notify both parties
- Edit status manually

#### Request Help Queue
- Incoming requests from users
- Fields: User, Category, Message, Date, Status (new/assigned/resolved)
- Assign to mentor
- Internal note field

---

### 6.7 Community Moderation

#### Groups Manager
- List all groups: Type, Name, Members, Moderator, Round, Status
- Create Group: type, name AR/EN, description AR/EN, icon, private toggle, max members, assign moderator, link to round
- Edit / Deactivate / Delete group

#### Posts Moderation
- DataTable: Group, User, Post excerpt, Date, Flags, Status (approved/pending/rejected/removed)
- Filter: Flagged only, Pending only
- View full post in modal
- Actions: Approve / Remove / Warn User / Ban User from Group

#### Moderation Settings (per group)
- Require post approval before publish: Yes/No
- Auto-flag threshold (N flags = auto-hide)
- Allowed content types (text/image/file)

#### Community Rules Editor
- Edit rules list (AR + EN) — shown in app to all users

#### Reported Content Queue
- Reports from users
- Reporter, reported user, content, reason, date
- Actions: Dismiss / Remove Content / Warn User / Suspend User

---

### 6.8 Challenges Management

#### Challenges List
- DataTable: Title EN/AR, Duration, Type, Status (Active/Inactive), Days Configured, Users Enrolled, Actions

#### Create/Edit Challenge
- Title AR + EN
- Description AR + EN
- Duration (days)
- Type (7day / 14day / 30day / custom)
- Related Section (dropdown)
- Linked Round (optional)
- Active toggle
- Start Date (if round-linked)
- Save

#### Days Manager (per challenge)
- List of all days (numbered)
- Inline editor per day:
  - Day number
  - Task AR + EN
  - Verse AR + EN
  - Reflection Question AR + EN
  - Tip AR + EN

#### Challenge Analytics
- Total enrolled
- Active now
- Completion rate by day (dropout chart — bar graph)
- Users who completed

---

### 6.9 Joseph Map Management

#### Stages Manager
- 7 stages listed in order
- Drag-to-reorder
- Edit per stage:
  - Stage key
  - Name AR + EN
  - Description AR + EN (shown in app)
  - Icon upload
  - Milestone label AR + EN
  - Unlocks at % threshold (configurable)

#### User Stage Overrides
- Search user → view current stage → manually advance or move back → add admin note
- Logged in admin_activity_logs

---

### 6.10 Notifications & Announcements

#### Send Notification
- Target: All Users / By Round / By Track / By City / Individual User / Group
- Type: System / Lesson / Challenge / Mentor / Community / Round
- Title AR + EN
- Body AR + EN
- Related entity (optional — links deep-link in app)
- Schedule (send now / schedule date-time)
- Preview → Confirm → Send

#### Notification Logs
- DataTable: Target, Type, Title, Sent At, Delivery Count, Open Rate
- Filter by date, type

#### In-App Announcements
- Banner/Modal announcements for all app users
- Title AR + EN, Body AR + EN, Image, Link, Active dates

---

### 6.11 Reports & Analytics

#### User Growth Report
- Line chart: registrations over time (daily/weekly/monthly)
- By city, by church, by gender

#### Round Report
- Per-round: enrolled, track split, progress distribution, completion rate
- Export CSV

#### Content Engagement Report
- Lessons: views, completion rate, avg time spent
- Most popular lessons, least completed

#### Challenge Report
- Per challenge: enrollment, daily completion rate (dropout curve), badges issued

#### Mentor Activity Report
- Sessions per mentor, avg rating, request resolution time

#### Community Health Report
- Posts per group, flags per group, member growth

#### Joseph Map Report
- Stage distribution (how many users at each stage)
- Average time per stage

#### Export Options
- All reports exportable as CSV
- Dashboard summary exportable as PDF

---

### 6.12 Settings & Localization

#### App Settings
- App Name (AR/EN)
- Tagline (AR/EN)
- Contact Email
- Support WhatsApp
- Social Links
- Terms & Conditions (Summernote, AR/EN)
- Privacy Policy (Summernote, AR/EN)
- About Us (Summernote, AR/EN)

#### Feature Toggles
- Enable/disable per section: Calling / Word / Project / Kingdom / Mentor / Community / Challenges / Joseph Map
- Maintenance mode toggle
- New round notification auto-send toggle

#### Admin User Management (Super Admin only)
- List admins: Name, Email, Role, Status, Last Login
- Invite new admin (email invite with temp password)
- Edit role
- Deactivate

#### Activity Log Viewer
- All admin actions: who did what, when, on which record
- Filterable by admin, action type, date range

---

## 7. API Architecture

### Base URL
```
https://api.josephapp.com/v1/
```

### Auth
- JWT tokens (access token 24h, refresh token 30 days)
- Header: `Authorization: Bearer {token}`

### Core Endpoints (Summary)

#### Auth
```
POST /auth/register
POST /auth/login
POST /auth/refresh
POST /auth/forgot-password
POST /auth/reset-password
```

#### Rounds
```
GET    /rounds                       — list open rounds
GET    /rounds/{id}                  — round detail
POST   /rounds/{id}/apply            — submit application
GET    /rounds/{id}/my-enrollment    — current user enrollment
```

#### Assessment
```
GET    /assessment/questions
POST   /assessment/submit
GET    /assessment/my-results
```

#### Lessons
```
GET    /sections
GET    /sections/{id}/lessons
GET    /lessons/{id}
POST   /lessons/{id}/complete
```

#### Challenges
```
GET    /challenges
GET    /challenges/{id}
POST   /challenges/{id}/enroll
GET    /challenges/{id}/today
POST   /challenges/{id}/checkin
```

#### Joseph Map
```
GET    /joseph-map/stages
GET    /joseph-map/my-progress
```

#### Mentors
```
GET    /mentors
GET    /mentors/{id}
POST   /sessions/book
GET    /sessions/my
POST   /help-request
```

#### Community
```
GET    /groups
GET    /groups/{id}/posts
POST   /groups/{id}/posts
POST   /posts/{id}/reply
POST   /posts/{id}/report
```

#### Notifications
```
GET    /notifications
POST   /notifications/mark-read
PUT    /notifications/device-token
```

#### Profile
```
GET    /profile
PUT    /profile
PUT    /profile/password
PUT    /profile/language
```

### Response Format
```json
{
  "status": "success",
  "data": {},
  "message": "Operation completed",
  "meta": {
    "page": 1,
    "per_page": 20,
    "total": 150
  }
}
```

### Error Format
```json
{
  "status": "error",
  "code": "ROUND_CLOSED",
  "message_en": "This round is no longer accepting applications.",
  "message_ar": "هذه الدورة لم تعد تقبل طلبات التسجيل."
}
```

---

## 8. Localization Strategy

### Mobile App (Flutter)
- `flutter_localizations` + `intl` package
- ARB files: `lib/l10n/app_en.arb` and `lib/l10n/app_ar.arb`
- All static strings externalized
- RTL layout automatic when Arabic selected
- API responses: app sends `Accept-Language: ar` or `en` header
- API returns correct `name_ar`/`name_en`, `body_ar`/`body_en` etc.
- User language preference stored in profile and local storage
- Font switching: Playfair/Inter for EN ↔ Amiri/Cairo for AR

### Admin Panel (PHP)
- Language JSON files: `lang/en.json` and `lang/ar.json`
- `$_SESSION['admin_lang']` persists toggle
- `t('key')` helper function used for all labels
- RTL toggle: `<html dir="rtl">` and Bootstrap RTL CSS when AR active
- Content forms always show both AR + EN fields side by side
- All tables have bilingual data columns

---

## 9. MVP Scope

### What to build first (Phase 1)

#### Mobile App MVP
- [ ] Splash, Language Selection, Welcome Slides
- [ ] Register, Login, Forgot Password
- [ ] Goal Selection (onboarding)
- [ ] Home Dashboard (simplified)
- [ ] Skill Assessment (full flow + results)
- [ ] Work in God's Word — all 10 topics (article only)
- [ ] Build Your Project — 3 project types with steps
- [ ] 30-Day Challenge (single challenge)
- [ ] Joseph Map (view only — 7 stages)
- [ ] Basic Profile & Settings

#### Admin Panel MVP
- [ ] Login + session management
- [ ] Dashboard (basic KPIs)
- [ ] Round Management (create, open, approve applications, enroll)
- [ ] Users list + detail view
- [ ] Lessons CRUD (sections + lessons)
- [ ] Assessment question manager
- [ ] 30-Day Challenge CRUD
- [ ] Joseph Map stages editor
- [ ] Basic notification send
- [ ] Admin roles (Super Admin + Editor only for MVP)

#### MVP Exclusions (Phase 2+)
- Live mentor chat + session booking
- Community groups + posts
- Kingdom Projects deep module
- Advanced analytics
- Certificate generation
- Moderator role
- Audio/video content
- Success stories

---

## 10. Future Roadmap

| Phase | Features |
|---|---|
| **Phase 2** | Mentor chat + session booking, Community groups, Kingdom Projects module |
| **Phase 3** | Audio/Video lesson support, Certificate generation, Success stories |
| **Phase 4** | Advanced analytics, Business plan generator AI, Moderator tools |
| **Phase 5** | BAM Hub, Church partnership portal, Sponsorship/funding module for Kingdom projects |
| **Phase 6** | Web version of app (PWA), Partner church dashboard |

---

## Appendix A — Section Icons Reference

| Section | Icon Concept |
|---|---|
| دعوتي (Calling) | Compass |
| شغلي للرب (Word) | Open Bible / Dove |
| ابنِ مشروعك (Build) | Hammer & Gear |
| مشروع برسالة (Kingdom) | Crown |
| مرشدك (Mentor) | Person with star |
| مجتمع يوسف (Community) | Interlinked circles |
| التحديات (Challenges) | Flame / Shield |
| خريطة يوسف (Map) | Map pin / Path |

---

## Appendix B — Round Application Email Templates

**On Submission (User):**
> "Thank you [Name], your application for [Round Name] has been received. We will review it and notify you shortly. — The Joseph Team"

**On Approval (User):**
> "Congratulations [Name]! Your application for [Round Name] has been approved. Your journey begins on [Start Date]. Welcome to the Joseph community."

**On Rejection (User):**
> "Thank you [Name] for your interest in [Round Name]. After careful review, we are unable to enroll you in this round. [Reason if provided]. We encourage you to apply for the next round."

**On Waitlist (User):**
> "Thank you [Name]. You have been placed on the waitlist for [Round Name]. We will notify you if a spot becomes available."

---

*End of Joseph App Specification — v1.0*