fchinembiri
/
geocrop-platform.
1
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
geocrop-platform./apps/nextgen/SCREENS.md

570 lines
25 KiB
Markdown
Raw Blame History

# 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*
Reference in New Issue View Git Blame Copy Permalink