# Africa Alert - Screen & Navigation Documentation

## Overview

Africa Alert is a Progressive Web App (PWA) for school management with **4 distinct user roles**, each with their own personalized dashboard and navigation.

**Roles:**
- 👔 **Admin** - Full school management access (8 nav items)
- 👩‍🏫 **Teacher** - Teaching and attendance management (5 nav items)
- 👨‍🎓 **Student** - Personal portal and attendance view (4 nav items)
- 👨‍👩‍👧 **Parent** - Children's progress and fee management (5 nav items)

---

## Navigation Architecture

### Role-Based Navigation

The navigation adapts automatically based on the logged-in user's role. Each role sees only the links relevant to their responsibilities.

```
┌─────────────────────────────────────────────────────────────────────────────┐
│  🏫 Africa Alert          [Role-Specific Links...]        [Badge] [Avatar] │
│  School Management                                         [Logout]        │
└─────────────────────────────────────────────────────────────────────────────┘
```

### Navigation Config by Role

#### Admin Navigation (Full Access)
| Icon | Label | Route | Description |
|------|-------|-------|-------------|
| 📊 | Dashboard | `/dashboard/admin` | Overview & stats |
| 👨‍🎓 | Students | `/students` | Manage students |
| 👩‍🏫 | Teachers | `/teachers` | Manage teachers |
| 📚 | Classes | `/classes` | Manage classes |
| 📅 | Attendance | `/attendance` | Take/view attendance |
| 💰 | Fees | `/fees` | Manage fees |
| 💬 | Messages | `/messages` | Internal messaging |
| 📅 | Events | `/events` | School calendar |

```
┌─────────────────────────────────────────────────────────────────────────────┐
│  🏫 Africa Alert                                                             │
│  School Management                                                           │
├─────────────────────────────────────────────────────────────────────────────┤
│  📊 Dashboard │ 👨‍🎓 Students │ 👩‍🏫 Teachers │ 📚 Classes │ ...      │
│  [+ 4 more links]                                                            │
└─────────────────────────────────────────────────────────────────────────────┘
```

#### Teacher Navigation (Teaching Focus)
| Icon | Label | Route | Description |
|------|-------|-------|-------------|
| 🏠 | Dashboard | `/dashboard/teacher` | Teaching overview |
| 📚 | My Classes | `/classes` | View assigned classes |
| 📋 | Attendance | `/attendance` | Mark attendance |
| 💬 | Messages | `/messages` | Communication |
| 📅 | Schedule | `/events` | View calendar |

```
┌─────────────────────────────────────────────────────────────────────────────┐
│  🏫 Africa Alert                                                             │
│  School Management                                                           │
├─────────────────────────────────────────────────────────────────────────────┤
│  🏠 Dashboard │ 📚 My Classes │ 📋 Attendance │ 💬 Messages │ 📅 Schedule │
└─────────────────────────────────────────────────────────────────────────────┘
```

#### Student Navigation (Personal Portal)
| Icon | Label | Route | Description |
|------|-------|-------|-------------|
| 🏠 | My Dashboard | `/dashboard/student` | Personal portal |
| 📅 | My Attendance | `/attendance` | View own attendance |
| 💬 | Messages | `/messages` | Inbox |
| 📅 | Events | `/events` | School events |

```
┌─────────────────────────────────────────────────────────────────────────────┐
│  🏫 Africa Alert                                                             │
│  School Management                                                           │
├─────────────────────────────────────────────────────────────────────────────┤
│  🏠 My Dashboard │ 📅 My Attendance │ 💬 Messages │ 📅 Events            │
└─────────────────────────────────────────────────────────────────────────────┘
```

#### Parent Navigation (Children Focus)
| Icon | Label | Route | Description |
|------|-------|-------|-------------|
| 🏠 | Dashboard | `/dashboard/parent` | Children overview |
| 👨‍👩‍👧 | Children | `/attendance` | View children's attendance |
| 💰 | Fees | `/fees` | View & pay fees |
| 💬 | Messages | `/messages` | School communication |
| 📅 | Events | `/events` | School calendar |

```
┌─────────────────────────────────────────────────────────────────────────────┐
│  🏫 Africa Alert                                                             │
│  School Management                                                           │
├─────────────────────────────────────────────────────────────────────────────┤
│  🏠 Dashboard │ 👨‍👩‍👧 Children │ 💰 Fees │ 💬 Messages │ 📅 Events       │
└─────────────────────────────────────────────────────────────────────────────┘
```

---

## Navigation Bar Components

### 1. Logo & Brand
```
┌────────────────┐
│ 🏫  Africa Alert │
│    School Mgmt   │
└────────────────┘
```
- SVG icon with blue background
- App name and subtitle
- Clickable → redirects to role dashboard

### 2. Navigation Links
- Horizontal list of links (center)
- Active state: blue background + blue text
- Hover state: light gray background
- Icon + label for each link
- Responsive: hidden on mobile

### 3. Role Badge
```
┌────────────┐
│ ● Admin    │  (red background)
└────────────┘
```
| Role | Background | Text | Border |
|------|------------|------|--------|
| Admin | `#fee2e2` | `#991b1b` | `#fecaca` |
| Teacher | `#dbeafe` | `#1e40af` | `#bfdbfe` |
| Student | `#dcfce7` | `#166534` | `#bbf7d0` |
| Parent | `#fef3c7` | `#92400e` | `#fde68a` |

### 4. User Avatar
```
┌──────────────────────────┐
│ [JS] John Smith          │
│     john@school.com      │
└──────────────────────────┘
```
- Circular avatar with user initials
- Gradient purple background
- Full name + email displayed

### 5. Logout Button
- Red hover state
- Icon + text (text hidden on mobile)

---

## Login Screen

**URL:** `/login`  
**Access:** Public (all users)

### UI Layout
```
┌─────────────────────────────────────────────────────────────┐
│                                                             │
│              ┌─────────────────────────────────┐           │
│              │      🏫 Africa Alert             │           │
│              │      School Management System    │           │
│              │                                 │           │
│              │  ┌─────┐ ┌─────┐ ┌─────┐ ┌─────┐│           │
│              │  │ 👔  │ │ 👩‍🏫│ │ 👨‍🎓│ │ 👨‍👩‍👧││           │
│              │  │Admin│ │Teach│ │Stud│ │Parent││           │
│              │  └─────┘ └─────┘ └─────┘ └─────┘│           │
│              │                                 │           │
│              │  Email:    [________________]   │           │
│              │  Password: [________________]   │           │
│              │                                 │           │
│              │  [         Sign In         ]    │           │
│              │                                 │           │
│              │  Demo Accounts:                 │           │
│              │  • admin@school.com / admin123 │           │
│              │  • teacher@school.com / ...    │           │
│              └─────────────────────────────────┘           │
│                                                             │
└─────────────────────────────────────────────────────────────┘
```

### Features

1. **Role Quick-Select Buttons**
   - Click to auto-fill credentials
   - Visual hover feedback
   - 4 role options

2. **Login Form**
   - Email + password inputs
   - Loading state on submit
   - Error display

3. **Demo Accounts List**
   - Admin: `admin@school.com` / `admin123`
   - Teacher: `teacher@school.com` / `teacher123`
   - Student: `student@school.com` / `student123`
   - Parent: `parent@school.com` / `parent123`

### Login Flow
```
User clicks role
       ↓
Credentials auto-fill
       ↓
User clicks Sign In
       ↓
JWT token stored in localStorage
       ↓
Redirect to role-specific dashboard
       ↓
Navigation updates to show role-appropriate links
```

---

## Dashboard Screens

### Admin Dashboard (`/dashboard/admin`)

**Purpose:** Complete school management overview

**Stats Cards:**
| Card | Icon | Value | Trend |
|------|------|-------|-------|
| Students | 👨‍🎓 | 245 | +12% |
| Teachers | 👩‍🏫 | 28 | +5% |
| Classes | 📚 | 12 | +3 |
| Revenue | 💰 | $45K | +18% |

**Sections:**
- Quick Overview (attendance, fees)
- Quick Actions (shortcuts)
- System Status

**Access:** Full CRUD on all modules

---

### Teacher Dashboard (`/dashboard/teacher`)

**Purpose:** Teaching schedule and daily tasks

**Stats Cards:**
| Card | Icon | Value |
|------|------|-------|
| My Classes | 📚 | 4 |
| Periods Today | ⏰ | 6 |
| Pending Tasks | 🔔 | 2 |
| Messages | 💬 | 5 |

**Sections:**
- My Classes (assigned)
- Today's Schedule
- Quick Actions

**Access:** View classes, mark attendance, send messages

---

### Student Dashboard (`/dashboard/student`)

**Purpose:** Personal school portal

**Stats Cards:**
| Card | Icon | Value |
|------|------|-------|
| Attendance | 📅 | 95% |
| Classes | 📚 | 3 |
| Due Fees | 💰 | $500 |
| Messages | 💬 | 2 |

**Sections:**
- Profile Card (gradient background)
- Today's Classes
- Attendance Summary
- My Fees
- Recent Messages

**Access:** View own data only

---

### Parent Dashboard (`/dashboard/parent`)

**Purpose:** Monitor children's activities

**Stats Cards:**
| Card | Icon | Value |
|------|------|-------|
| Children | 👨‍👩‍👧 | 2 |
| Total Fees | 💰 | $2,850 |
| Due | ⚠️ | $850 |
| Messages | 💬 | 3 |

**Sections:**
- Profile Card
- My Children (with attendance + fees)
- Quick Actions
- Fee Summary

**Access:** View children, pay fees

---

## Module Pages

### Classes (`/classes`)
**Access:** Admin (CRUD), Teacher (view)

```
┌─────────────────────────────────────────────────────────────┐
│ Classes & Subjects                                          │
│ ┌─────────────────────────┐  ┌─────────────────────────────┐│
│ │ Classes            [+] │  │ Subjects              [+]   ││
│ │                       │  │                            ││
│ │ Grade 1 - A (40) [🗑]│  │ Mathematics (Grade 1) [🗑]  ││
│ │ Grade 2 - A (35) [🗑]│  │ English (Grade 1)     [🗑]  ││
│ │ Grade 3 - A (38) [🗑]│  │ Science (Grade 1)     [🗑]  ││
│ └─────────────────────────┘  └─────────────────────────────┘│
└─────────────────────────────────────────────────────────────┘
```

### Attendance (`/attendance`)
**Access:** All roles (view/edit varies)

```
┌─────────────────────────────────────────────────────────────┐
│ Attendance                                                  │
│ Date: [2026-01-15]  Class: [All Classes ▼]  [Save]        │
│ ┌────────────────────────────────────────────────────────┐ │
│ │ Student          │ Present │ Absent │ Late │ Excused │ │
│ ├────────────────────────────────────────────────────────┤ │
│ │ Alice Johnson    │  [●]    │  [ ]   │ [ ]  │   [ ]   │ │
│ │ Bob Williams     │  [ ]    │  [●]   │ [ ]  │   [ ]   │ │
│ └────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
```

### Fees (`/fees`)
**Access:** Admin (full), Parent (view/pay)

```
┌─────────────────────────────────────────────────────────────┐
│ Fees Management                                             │
│ ┌───────────┐  ┌───────────┐  ┌───────────┐                 │
│ │➕ Create  │  │📋 Assign  │  │💰 Payment │                 │
│ │Fee Group  │  │Fees       │  │Record     │                 │
│ └───────────┘  └───────────┘  └───────────┘                 │
│                                                             │
│ Student Fees:                                               │
│ ┌────────────────────────────────────────────────────────┐ │
│ │ Student │ Fee     │ Amount │ Paid  │ Status           │ │
│ ├────────────────────────────────────────────────────────┤ │
│ │ Alice J.│ Tuition │ $5,000 │$3,000 │ 🟡 Partial      │ │
│ │ Bob W.  │ Tuition │ $5,000 │$5,000 │ 🟢 Paid         │ │
│ └────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
```

### Messages (`/messages`)
**Access:** All roles

```
┌─────────────────────────────────────────────────────────────┐
│ Messages                                        [+ Compose]│
│ ┌────────────────────────────────────────────────────────┐ │
│ │ From       │ To       │ Subject       │ Date          │ │
│ ├────────────────────────────────────────────────────────┤ │
│ │ Admin      │ Jane S.  │ Meeting...    │ Jan 15, 10:30 │ │
│ │ John S.    │ Admin    │ Question...   │ Jan 14, 3:45  │ │
│ └────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
```

### Events (`/events`)
**Access:** All roles

```
┌─────────────────────────────────────────────────────────────┐
│ Events & Calendar                                 [+ Add]   │
│ ┌────────────────────────────────────────────────────────┐ │
│ │ Date      │ Title          │ Type      │ Description  │ │
│ ├────────────────────────────────────────────────────────┤ │
│ │ Jan 15    │ First Day      │ 📌 General │              │ │
│ │ Feb 20    │ Mid-Term Exams │ 📝 Exam   │ Week-long    │ │
│ │ Mar 10    │ Spring Holiday │ 🏖 Holiday│ Closed       │ │
│ └────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
```

---

## Role Permissions Matrix

| Feature | Admin | Teacher | Student | Parent |
|---------|:-----:|:-------:|:-------:|:------:|
| **Dashboard** | | | | |
| View dashboard | ✓ | ✓ | ✓ | ✓ |
| Role-specific stats | ✓ | ✓ | ✓ | ✓ |
| **Users** | | | | |
| Manage students | ✓ | - | - | - |
| Manage teachers | ✓ | - | - | - |
| View own profile | ✓ | ✓ | ✓ | ✓ |
| **Academic** | | | | |
| Manage classes | ✓ | - | - | - |
| View classes | ✓ | ✓ | ✓ | ✓ |
| Mark attendance | ✓ | ✓ | - | - |
| View attendance | ✓ | ✓ | ✓ | ✓ |
| **Financial** | | | | |
| Manage fees | ✓ | - | - | - |
| View fees | ✓ | - | ✓ | ✓ |
| Pay fees | - | - | - | ✓ |
| **Communication** | | | | |
| View messages | ✓ | ✓ | ✓ | ✓ |
| Send messages | ✓ | ✓ | ✓ | ✓ |
| **Calendar** | | | | |
| Manage events | ✓ | - | - | - |
| View events | ✓ | ✓ | ✓ | ✓ |

**Legend:** ✓ = Full access, - = No access

---

## Responsive Design

### Breakpoints

| Width | Layout | Navigation |
|-------|--------|------------|
| >1024px | Full | Desktop: all links visible |
| 768-1024px | 2-column | Tablet: condensed nav |
| <768px | 1-column | Mobile: hamburger menu |

### Mobile Navigation
- Hamburger menu icon appears
- Full-screen overlay menu
- All links listed vertically
- Logout button at bottom

---

## Route Structure

```
/
├── login                          # Public
│
├── dashboard/
│   ├── admin                      # Admin dashboard
│   ├── teacher                    # Teacher dashboard
│   ├── student                    # Student dashboard
│   └── parent                     # Parent dashboard
│
├── students                       # Admin only
├── teachers                       # Admin only
├── classes                        # Admin, Teacher
├── attendance                     # All roles
├── fees                           # Admin, Parent
├── messages                       # All roles
└── events                         # All roles
```

### Route Protection
1. Check if user is authenticated (JWT token)
2. Check if user has required role
3. Redirect unauthorized users to their dashboard

---

## File Structure

```
africa-alert-pwa/
├── client/src/
│   ├── components/
│   │   └── Nav.tsx                 # Role-aware navigation
│   │
│   ├── pages/
│   │   ├── Login.tsx               # Login with role select
│   │   │
│   │   ├── Students.tsx            # Admin only
│   │   ├── Teachers.tsx            # Admin only
│   │   ├── Classes.tsx             # Admin, Teacher
│   │   ├── Attendance.tsx           # All roles
│   │   ├── Fees.tsx                # Admin, Parent
│   │   ├── Messages.tsx            # All roles
│   │   ├── Events.tsx              # All roles
│   │   │
│   │   └── dashboard/
│   │       ├── AdminDashboard.tsx  # Full management
│   │       ├── TeacherDashboard.tsx # Teaching focus
│   │       ├── StudentDashboard.tsx # Personal portal
│   │       └── ParentDashboard.tsx  # Children overview
│   │
│   ├── store/
│   │   └── auth.ts                 # Zustand auth state
│   │
│   ├── App.tsx                     # Routes + protection
│   ├── main.tsx                    # Entry point
│   └── index.css                   # Global styles
│
├── server/
│   └── src/
│       ├── index.js                # API routes
│       └── database/
│           └── init.js             # Schema + seed data
│
├── docker-compose.yml
├── Dockerfile
└── README.md
```

---

## Key Implementation Details

### Navigation Config
```javascript
const NAV_CONFIG = {
  admin: [
    { path: '/dashboard/admin', label: 'Dashboard', icon: LayoutDashboard },
    { path: '/students', label: 'Students', icon: GraduationCap },
    // ... 8 items
  ],
  teacher: [
    { path: '/dashboard/teacher', label: 'Dashboard', icon: Home },
    { path: '/classes', label: 'My Classes', icon: BookOpen },
    // ... 5 items
  ],
  // ...
};
```

### Role Colors
```javascript
const ROLE_COLORS = {
  admin: { bg: '#fee2e2', color: '#991b1b', border: '#fecaca' },
  teacher: { bg: '#dbeafe', color: '#1e40af', border: '#bfdbfe' },
  student: { bg: '#dcfce7', color: '#166534', border: '#bbf7d0' },
  parent: { bg: '#fef3c7', color: '#92400e', border: '#fde68a' },
};
```

### Route Protection
```javascript
function ProtectedRoute({ children, allowedRoles }) {
  const { token, user } = useAuthStore();
  
  if (!token) return <Navigate to="/login" />;
  
  if (allowedRoles && !allowedRoles.includes(user.role)) {
    return <Navigate to={`/dashboard/${user.role}`} />;
  }
  
  return children;
}
```

---

*Document Version: 3.0*  
*Last Updated: June 2026*  
*Features: Role-based nav, 4 dashboards, permissions matrix, responsive design*