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.