Skip to content

Alhuda ERP Technical Plan

Superseded — kept for history only

This page was written in January 2026 and is not a description of how the system works today. It is kept so the reasoning behind early decisions stays readable. Current behaviour is described in Architecture and Platform reliability (PLT). Do not build from this page.

1) Data Model Overview

  • User, Role, Permission, UserRole, RolePermission
  • Department
  • Airline, AirlineQuotaBlock, SlotInventory
  • TravelGroup, GroupLeaderAssignment
  • PackageTemplate, Quotation, QuotationLineItem
  • Customer, Agent
  • Booking, BookingStatusHistory, OpsApproval, FinanceApproval
  • Payment, Invoice/Receipt, LedgerEntry
  • VisaCase, VisaStatusHistory, VisaDocument
  • MovementChart (versioned)
  • TicketRecord, TicketIssueApproval, TicketStatusHistory
  • HotelInventory, FoodInventory, GroupHotelAssignment, GroupFoodAssignment
  • OrientationEvent, PreDepartureNoticeLog
  • SpecialAssistanceRequest
  • CommunicationsLog
  • AuditLog

Relationships: - Agent owns Customers; Booking links Customer + Group + Agent. - Quotation converts to Booking. - Status histories track bookings, visas, tickets. - Finance approval gates ops approval. - Ticket issuance requires finance clearance or GM exception proof.

2) Permission Model (Summary)

  • CEO: view + high-level approvals.
  • GM: full operational control + exception approvals.
  • Dept heads/managers: full control in their domains.
  • Executives: create/edit in their domain, no approvals unless stated.
  • Ticket Manager: name updates, holds, issue after clearance.
  • Finance: payments, dues, clearance, receipts.
  • IT Admin: system administration, no business approvals.
  • Auditor: read-only + exports.

Enforcement Strategy

  • RBAC middleware per API route.
  • Server-side validators for business rules.
  • AuditLog for every approval and state transition.

3) Role-Permission Matrix (Condensed)

Legend: V=View, C=Create, E=Edit, A=Approve, R=Reject, I=Issue, D=Export, X=Delete

Inventory: GM/IT (V C E X), Ops Manager (V C E), Sales/B2B (V), Auditor (V D) Groups: GM/Ops Manager (V C E A), Ops Exec (V E), Sales/B2B (V) Sales: Sales/B2B (V C E), GM (V C E A R), Ops/Finance (V) Ops Approvals: Ops Manager (V A R), Ops Exec (V A), GM (V A R) Visa: Visa Officer/Ops (V C E A), GM (V A R) Tickets: Ticket Manager (V E I), Finance (V A), GM (A) Finance: Finance (V C E A R), GM (V A)

Critical rules: - Ops approval only after finance policy met. - Ticket issuance only after finance clearance OR GM exception proof.

4) State Machines

Booking: - Draft -> Pending Ops Review -> Pending Finance Approval -> Approved -> On Hold -> Cancelled Rules: - Ops approval requires finance policy satisfied (advance/partial/full).

Visa: - Not Started -> Applied -> Under Process -> Issued -> Rejected -> Sent to Embassy

Ticket: - Not Ready -> Name Update Pending -> On Hold (dues) -> Finance Cleared -> Issued Rules: - Issued only after clearance or GM exception with proof. - Name update must be completed within 2 days of departure.

5) API Specification (REST)

Auth: - POST /api/auth/login - POST /api/auth/logout - GET /api/auth/me

Inventory: - GET /api/airlines - POST /api/airlines - POST /api/quota-blocks - POST /api/slots/generate

Groups: - POST /api/groups - PATCH /api/groups/:id - POST /api/groups/:id/assign-slots - POST /api/groups/:id/assign-customer

Sales: - POST /api/quotations - PATCH /api/quotations/:id - POST /api/bookings - POST /api/bookings/:id/convert

Agents/B2B: - GET /api/agents - POST /api/agents - PATCH /api/agents/:id

Operations: - POST /api/bookings/:id/ops-approve - POST /api/bookings/:id/ops-reject - POST /api/communications

Visa: - POST /api/visa - PATCH /api/visa/:id/status - POST /api/visa/:id/upload

Tickets: - PATCH /api/tickets/:id/name-update - POST /api/tickets/:id/issue - POST /api/tickets/:id/exception-approve

Finance: - POST /api/payments - POST /api/bookings/:id/finance-approve

Reports: - GET /api/reports/group-manifest - GET /api/reports/dues - GET /api/reports/visa-pipeline

Server-side rules: - Capacity checks on group assignment. - Ops approval gated by finance policy. - Ticket issuance blocked without clearance/exception proof.

6) UI Specification (Screen Summary)

Layout: - Sidebar by module. - Top bar with global search (customer/passport/groupId). - Notifications drawer.

Screens: 1) Dashboard: KPIs, pending approvals, dues. 2) Inventory: quota blocks, slots, allocation. 3) Groups: list + details, slot usage. 4) Sales: inquiries, quotations, bookings. 5) Agents: agent list/detail, commissions. 6) Ops approvals: queue, verification checklist. 7) Visa: pipeline board, case detail, upload. 8) Tickets: name update queue, hold/issue flow. 9) Finance: payments, dues, receipts, exports. 10) Hotels/Food: inventory + group assignment. 11) Orientation + pre-departure notices + assistance. 12) Admin: users, roles, audit logs.

Routes: - /inventory, /groups, /groups/[id], /sales/quotations, /sales/bookings, /agents, /ops, /visa, /tickets, /finance, /admin

7) Finance Subsystem

Key fields: - totalAmount, paidAmount, balance - policy: advance / partial / full - clearanceFlag

Functions: - calculateDues(total, payments) - canApproveBooking(policy, paid) - canClearTickets(dues, exceptionProof)

Receipts: - Receipt number: ALH-YYYY-000001 sequence.

Ledger: - LedgerEntry for payments and refunds.

8) Reporting Module

Reports: - Group Manifest (passport, visa status, ticket status, hotel assignment). - Dues report (by group, by agent, aging buckets). - Visa pipeline (by status, departure window). - Ticket issuance report (issued/held/exception). - Inventory utilization (slots by airline/quota).

Performance: - Pagination, server-side filtering, indexed queries.

9) Implementation Plan (MVP Order)

1) Repo setup - Next.js + TS + Tailwind + Supabase (Postgres) + Docker - Acceptance: build runs, database connects, auth stub - Files: src/db/schema.sql, app/layout.tsx, app/page.tsx - Tests: lint + migration smoke test

2) Auth + RBAC - Seed roles/permissions - Middleware guards - Pages: /auth, /admin/users - Tests: role access matrix

3) Core inventory - Airlines, quota blocks, slots - Group capacity checks - Pages: /inventory, /groups

4) Sales - Customers, agents, quotations, bookings - Pages: /sales/quotations, /sales/bookings, /agents

5) Ops approval queue - Verification checklist + communications log - Page: /ops

6) Finance - Payments, dues calculation, clearance - Page: /finance

7) Visa - Pipeline + case detail + uploads - Page: /visa

8) Tickets - Name update queue + issue flow + exceptions - Page: /tickets

9) Hotels/Food - Inventory + group assignment - Page: /hotels

10) Audit logs + reports - Audit table + report exports - Page: /reports