109 lines
4.2 KiB
Markdown
109 lines
4.2 KiB
Markdown
# 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)
|
|
```bash
|
|
# 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)**
|
|
```bash
|
|
cd client
|
|
npm install
|
|
npm run dev
|
|
# Running on http://localhost:3000 (proxies /api to :3001)
|
|
```
|
|
|
|
**Backend (Server)**
|
|
```bash
|
|
cd server
|
|
npm install
|
|
npm run dev
|
|
# Running on http://localhost:3001
|
|
```
|
|
|
|
**Database Initialization**
|
|
If running locally without Docker for the first time:
|
|
```bash
|
|
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.
|