# 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.