4.2 KiB

Raw Blame History

Africa Alert - Smart School PWA

Project Overview

Africa Alert is a comprehensive, offline-first Progressive Web App (PWA) school management system tailored for the African educational context (initially focused on Zimbabwe). It serves four primary stakeholders: administrators, teachers, students, and parents, providing a unified role-aware interface.

Key Features

Offline-First: Local SQLite mirror on the server allows continued operation without internet; a sync engine reconciles data with a cloud-based Supabase instance when online.
Unified Management: Covers student records, classes, attendance, fees, messaging, calendar, exams, payroll, inventory, and more.
Role-Based Access Control (RBAC): Distinct dashboards and permissions for Admin, Teacher, Student, and Parent roles.
Cashless Fee Collection: Integrated with Paynow Zimbabwe for online fee payments.
Containerized: Simplified deployment using Docker and Docker Compose.

Tech Stack

Frontend: React 18, Vite, TypeScript, Tailwind CSS, Zustand (state management), Lucide (icons), Recharts.
Backend: Node.js, Express, SQLite (better-sqlite3), JWT (auth), multer (uploads).
Database: SQLite (local mirror at ./server/data/school.db) + Supabase (cloud backup/replication).
Deployment: Docker, Docker Compose, npx serve for static client hosting.

Building and Running

Prerequisites

Node.js 20+
Docker and Docker Compose (recommended for production-like environment)

Docker Deployment (Recommended)

# Clone and start everything
docker-compose up -d

# Access the app:
# Frontend: http://localhost:3000
# API: http://localhost:3001

Local Development

To run the services independently for development:

Frontend (Client)

cd client
npm install
npm run dev
# Running on http://localhost:3000 (proxies /api to :3001)

Backend (Server)

cd server
npm install
npm run dev
# Running on http://localhost:3001

Database Initialization If running locally without Docker for the first time:

cd server
npm run db:init

Development Conventions

Architecture & Design

Monolithic API: Express modules are organized into controllers mounted under /api/<module> in server/src/index.js.
Sync Engine: The SyncEngine (server/src/services/SyncEngine.js) runs periodically (30s) to push/pull changes using a "server-wins" conflict resolution strategy.
Database Metadata: Every table must include uid (UUID), last_synced_at, sync_status (synced, pending, conflict), and is_deleted (soft delete).
Shared Secrets: DO NOT hardcode secrets. Use .env files (see AGENTS.md and docker-compose.yml for required variables).

Coding Standards

Naming:
- React Components: PascalCase
- Hooks: useCamelCase
- Database Columns: snake_case
- API Controllers: camelCase.controller.js
Folders:
- Frontend: client/src/components/, client/src/pages/<role>/, client/src/store/.
- Backend: server/src/controllers/, server/src/services/, server/src/database/.
Git Strategy:
- dev branch: Integration and development.
- main branch: Production (must always be deployable).
- Use conventional commits (e.g., feat(exams): ..., fix(auth): ...).

Role-Based Permissions

Refer to SCREENS.md for the canonical mapping of screens to user roles and permissions.

Key Files & Documentation

AGENTS.md: Detailed architecture, mandates, and role-specific instructions for AI agents. READ THIS FIRST.
DATABASE_SCHEMA.md: Comprehensive list of tables and columns.
SCREENS.md: UI map and permissions matrix.
server/src/database/init.js: The source of truth for the database schema (SQL).
docker-compose.yml: Infrastructure and environment configuration.

AI Agent Roles

When interacting with this repository, assume one of the following roles as defined in AGENTS.md:

Architect: System design and cross-cutting concerns.
Backend: API, business logic, and database.
Frontend: UI/UX, state management, and PWA behavior.
DevOps: CI/CD, containerization, and deployment.
QA: Testing and validation.
Documentation: READMEs, API docs, and architecture diagrams.

4.2 KiB Raw Blame History