# MamadApp

Emergency tracker web app with role-based admin management and hierarchical user organization.

## Overview
MamadApp tracks user status (shelter and activity) and provides an admin console to manage users across a hierarchy:
Field > Department > Team > Person. Admins can manage only the scope they are assigned to.

## Requirements
- Node.js 18+
- MySQL 8+
- npm (or pnpm)

## Repository Layout
- `app/` Next.js app routes (UI + API)
- `components/` shared UI components
- `hooks/` client hooks (real-time polling)
- `lib/` database and auth utilities
- `scripts/` database setup, migration, and maintenance
- `types/` shared TypeScript types

## Configuration
1) Copy `config.json.template` to `config.json`
2) Update database settings:
   - `database.host`
   - `database.user`
   - `database.password`
   - `database.database`

## Database Setup

Fresh install:
1) (Optional) Create database user:
   - Run `scripts/setup-database-user.sql` as MySQL root.
2) Create schema:
   - Run `scripts/schema.sql`

Existing database:
1) Run `scripts/migrate-managed-types.sql`
   - Adds `managed_types` table
   - Converts `users.field/department/team` to `VARCHAR`
   - Seeds managed types and hierarchy from existing user data

See `scripts/README.md` for details and archived migrations.

## Running the App
Local development:
- `npm install`
- `npm run dev`

Production build:
- `npm run build`
- `npm run start`

## Admin Roles and Permissions

Global admin:
- Full access to all fields/departments/teams
- Can create, rename, and delete managed types
- Can move any user

Field admin (Field A):
- Can manage users in Field A only
- Can create/rename/delete departments and teams under Field A
- Can move users within Field A (including across departments/teams)

Department admin (Dept X in Field A):
- Can manage users in Dept X only
- Can create/rename/delete teams under Dept X
- Can move users within Dept X

Team admin (Team Y in Dept X):
- Can manage users in Team Y only
- Cannot create/rename/delete managed types
- Can only move users within Team Y

## Managed Types (Fields, Departments, Teams)
Managed types are stored in `managed_types` with hierarchy:
- `field` has no parent
- `department` parent = field
- `team` parent = department

UI behavior:
- Managed types list is filtered based on the admin scope.
- Department and team creation requires selecting a parent.
- Rename updates both `managed_types` and existing user rows.
- Deleting is blocked if users or child types still reference the value.

## Database Tables

`users` (core):
- identity: `national_id`, `name`
- auth: `password`, `must_change_password`, `password_changed_at`
- scope: `field`, `department`, `team`
- role: `role`, `is_admin`
- status: `in_shelter`, `last_updated`
- safety: `lock_status`

`managed_types`:
- `type`: `field | department | team`
- `name`
- `parent_id` for hierarchy

`admin_actions`:
- Tracks resets, password resets, and role changes

## Common Tasks

Add a new field/department/team:
- Use the Admin UI (global/field/department admins only).
- Department/team creation requires selecting a parent.

Move a user:
- Use the Admin UI and the edit (pencil) button in user tables.
- User movement is restricted by admin scope.

Rename a type:
- Use the managed types UI. Rename cascades to users.

## Troubleshooting

Managed types not appearing:
- Ensure `managed_types` table exists.
- Run `scripts/migrate-managed-types.sql`.

Cannot delete a type:
- Users or child types still reference it.
- Reassign users and delete children first.

Permissions denied:
- Verify the admin role and assigned scope (field/department/team values).

## Notes
- Admin actions are logged in `admin_actions`.
- Managed types are hierarchical and validated in API routes.