Bookings & Operations
Visa pipeline
Visa requests move through a defined state machine: new inquiry → pending documents → embassy processing → approved/rejected → passport collected. Requests capture entry type (single/multiple entry, transit) sourced from a shared lookup table.
Daily Approved Visas & Passport Handover Manifest (A4 Printable)
When a visa application is approved by the consulate/embassy:
- Approval Timestamp (
approved_at): The backend records the exact timestamp of approval (approved_at = now()) when transitioning status toapproved. - Dynamic Visa Short Codes: Generates compact standardized codes dynamically from reference data (e.g.
IND-B-3M-M-S,UK-S-1Y-M-S,UAE-T-1M-S-E) capturing Country, Type, Validity, Entry Type, and Sticker/eVisa format. - Physical Register Page Identification (
2026OCT18PG1):- Sequential page codes (
<yyyy><MMM><dd>PG<pageNumber>, e.g.2026OCT18PG1,2026OCT18PG2) computed dynamically in-memory based on approval date inAsia/Colombotime (8 rows per page matching physical register sheets). - Manifest Top Header: Prominently displayed in the top-right header box of each printed sheet (
Register Page Code: 2026OCT18PG1). - Manifest Bottom Footer: Displayed subtly as a greyed-out code badge (
footer-code-badge) inside the bottom Custody Notice card and as a muted watermark line (Register Page: 2026OCT18PG1) at the bottom of the page. - Clean Table Layout: Removed the redundant per-row
Signing Pagecolumn in favor of 8 balanced columns (#,Customer Name,Traveler Name,Visa Code,Visa / Sticker No.,Handover Date,Staff Name,Customer Signature). - Task Detail Drawer Integration: Displays a monospace blue badge
Signing Page: 2026OCT18PG1in the drawer header and a dedicated register card inVisaDetailPanel, allowing front-desk staff to instantly pull the corresponding paper signature sheet from the physical book. - Visa Only: Computed strictly for Visa requests; zero inclusion in flight responses or database schemas.
- Sequential page codes (
- Automated Daily Email (20:00 Asia/Colombo): Fires every evening at 8:00 PM Sri Lanka time to dispatch an HTML summary and attached A4 PDF (
Approved_Visas_Handover_Manifest_YYYY-MM-DD.pdf) to agency managers and owners. - On-Demand API (
GET /api/v1/visas/daily-approved/pdf): Allows generating and streaming the A4 printable manifest for today or any past calendar date on-demand.
Rejected Visa Operational Lifecycle
When an embassy or consulate refuses a visa application:
- Status Transition: The application moves to
rejectedstatus. - Client Decision Notification: Staff can send an official rejection notification email directly to the customer containing the embassy remarks, assigned consultant contact details, and passport collection instructions.
- Passport Return Finalization: Staff click “Return Passport”, which transitions the status to
passport_collected, flagsis_visa_request_rejected = true, and records the completion timestamp (completed_at). Approval emails remain suppressed. - Visual Red Dot Indicator: On the Task Tracker, Admin Table, and Client Dossier, rejected applications whose passport has been collected display a distinct red dot indicator (
bg-red-600 ring-2 ring-red-200) and red status badges instead of the green checkmark icon. - Dossier & Active Services Visibility: In the customer’s Active Services panel, rejected applications are clearly badged in red as
REJECTEDalongsidePASSPORT RETURNED. They are strictly omitted from active held visas in the Passport Vault.
Flight bookings
Flight requests are created and tracked against a customer, moving through their own status lifecycle including issued tickets.
Ticket cancellation & reschedule
- Cancellation — staff can cancel an issued ticket with a manual cancellation fee, refund amount, and reason (a judgment call per booking, not a rules engine); the cancelled state is shown inline on the case.
- Reschedule — staff can change a ticketed booking’s flight date, with a reason field. The full change history (previous date, new date, who, when) is kept server-side.
Outdated Ticket Departure Warning Indicator
To prevent departing flights with pending payments or unissued tickets from falling through the cracks:
- Database Query-Level Check:
FlightRequestRepositoryevaluates departure expiration directly in the JPQL projection (f.flightDate < :now AND f.status NOT IN ('CANCELLED', 'TICKETED') AND f.isFinalised = false), populatingisTicketOutdatedandticketDaysOutdated. - Suppression Criteria: The icon is suppressed only when the ticket is issued AND all payments are completely settled (
isFinalised == trueorticketNumber != null && invoiceStatus == 'paid'). If payments remain unpaid, partial, or un-invoiced after the flight departure date, the warning icon remains active. - Task Tracker Indicator: Displayed as a compact circular amber
Info(i) icon (w-5 h-5) with a rich tooltip showing scheduled flight date and overdue days in<TaskListView />,<AdminTaskTable />, and an alert banner in<FlightDetailPanel />.
Task tracker & Document Management
- Admins see an aggregated, filterable table of every ongoing case across the agency.
- Consultants see a Kanban board of their own assigned cases.
- Finalized Status Indicators & Decoupled Operational Completion:
- Operational completion (
completed_at = now()) occurs when a visa or flight reaches fulfillment (e.g. visa issued or moved topassport_collected; flight ticketed). - A case is only marked finalized (
is_finalised = truewith a green checkmark) when all operational steps are fulfilled, passport handover has occurred, AND all associated invoices (direct and group-linked) are fully settled (PAID). - Non-Blocking Transitions: Moving a visa to
passport_collected(or a flight toTICKETED) is non-blocking regardless of invoice status. If invoices remain unpaid or partial, the status updates successfully, recordingcompleted_atwhile keepingis_finalised = false. Staff receive an informational toast noting that the case remains unfinalized until all invoices are paid. - Approved Visas: Display a green checkmark circle (
CheckCircle2) andFINALIZEDbadge when visa number is issued, passport collection is finalized (is_finalised = true), and all linked invoices are fully paid (PAID). - Rejected Visas: Display a solid red dot indicator and
Passport Returned (Rejected)badge whenis_visa_request_rejectedis true, passport return is finalized (is_finalised = true), and all associated invoices are fully settled. - Flights: Ticket number is issued (
ticketNumberis present), the booking is not cancelled, and all linked invoices are fully settled (is_finalised = true). - If an invoice is created or modified with an outstanding balance, the finalized status is automatically revoked until payment receipt is recorded.
- Operational completion (
- Task Detail Drawer:
- Anti-Flicker Drawer Loader: Opens with a unified loading state powered by concurrent fetches (
Promise.allSettled), avoiding UI jumps between “Issue Invoice” and “View Invoice”.- Traveler Fidelity & Account Holder Hierarchy: When a ticket or visa is booked for a family member or dependent under an account holder, the drawer prominently displays the traveler’s name as the primary header with a relationship subtitle and direct dossier link to the primary account holder. Flight and Visa panels render dedicated Passenger & Traveler Information sections containing the traveler’s passport number, expiry date, nationality, date of birth, and relationship.
- Full-Drawer Finalization Overlay: When passport collection is finalized (for both approved and rejected applications), a full-coverage loading overlay (
absolute inset-0 z-50 bg-background-cream/85) covers the entire drawer. All buttons receivedisabled={isFinalizing}andisLoading={isFinalizing}, cancel/delete actions are locked, and the modal backdrop is guarded against accidental dismissal until server persistence and Redux state synchronization complete. - Contextual Document Checklist & Downloadable Templates: Displays both required checklist items and matched downloadable templates/forms from Staff Utilities (e.g. embassy visa forms, NOC templates, flight vouchers) with direct downloads formatted as
customer_name_visatype_doc_type_doc_name.ext.
- Anti-Flicker Drawer Loader: Opens with a unified loading state powered by concurrent fetches (
- Query Optimization & Embedded DTO Architecture:
VisaResponseDTOandFlightResponseDTOembedcustomerName(via a databaseLEFT JOIN CustomerEntity c) andinvoiceStatus(via targeted queries inInvoiceRepository).- The Task Tracker board relies entirely on these embedded attributes, eliminating both the previous full invoice table scan (
getAllInvoices) and the customer search query (search?query=), saving over 2.7s on board load.
- Service Issuance & Update Workflows:
- Unblocked Visa Details Management: Staff can save or update issued visa details and upload visa PDFs freely even when invoices are partially paid. The issue form intelligently adapts its primary action to “Save & Issue Visa” (or “Save & Update Visa”) when invoices are pending, reserving “Issue Visa & Finalize (Passport Collected)” exclusively for cases that are fully settled (
PAID). - Explicit Finalization Gate: In the
passport_collectedstage, the explicit “Finalize (Passport Collected)” button remains disabled with an explanatory tooltip until all invoices are fully paid. - Issue / Update Visa Flow: Staff enter visa numbers and dates while directly attaching finalized Visa PDF(s). Before any network upload, all required fields are validated. Existing uploaded documents are listed with file sizes, instant download (powered by
triggerSafeDownloadwith automatic presigned URL refresh if links expire, accompanied by real-time toasts), and Delete actions backed by styled ReactConfirmModaldialogs. - Issue / Update Ticket Flow: Staff enter ticket numbers and prices while attaching e-ticket PDFs. Existing documents are displayed directly in the drawer with resilient download and delete controls.
- Permanent Purge on Request Deletion: Deleting a flight or visa request permanently purges all attached documents from Cloudflare R2 and deletes rows from PostgreSQL.
- All files uploaded via the drawer automatically link to the customer dossier and receive structured R2 keys.
- Unblocked Visa Details Management: Staff can save or update issued visa details and upload visa PDFs freely even when invoices are partially paid. The issue form intelligently adapts its primary action to “Save & Issue Visa” (or “Save & Update Visa”) when invoices are pending, reserving “Issue Visa & Finalize (Passport Collected)” exclusively for cases that are fully settled (
Dashboard
The app serves a role-specific dashboard automatically on login — a high-level admin view for owners, an operational view for consultants. Core dashboard data is fetched once at login (not refetched on every tab switch), with a manual “Refresh” button on each consuming page.
Reference data
- Lookup values — a single generic table backs job titles, departments, branches, commission tiers, employment types, and visa entry types.
- Sequential codes — a row-locked counter table generates human-readable, prefix-based codes for employee IDs and quotation numbers.
Overdue Passport Custody Tracking (> 7 Days)
To enforce the 7-day complimentary passport collection grace period (PRIVACY_POLICY.md §4.2), the system tracks uncollected passports across both approved and rejected visa requests (i.e., cases where a decision has been reached and the physical passport is ready for handover, but the status has not yet moved to passport_collected):
- Single-Query JPQL Indicator (Zero $N+1$ Queries):
VisaRequestRepositorycomputes aCASE WHEN ... THEN true ELSE false ENDboolean projection directly insidefindAllFilteredWithIssuedVisa,findTrackerVisasWithIssuedVisa, andfindByCustomerIdWithIssuedVisausing:overdueCutoff = OffsetDateTime.now().minusDays(7)againstCOALESCE(v.approvedAt, v.createdAt)for statuses'approved'and'rejected'. - PostgreSQL Native Enum Compatibility: Native SQL queries against
visa_requests.statuscompareCAST(v.status AS text)against string literals ('approved','rejected') rather than Hibernate’s default::VisaStatuscast, avoiding PostgreSQLsearch_path/ case-sensitivevisastatustype resolution errors in production and scheduled jobs (UncollectedPassportReminderJob). - Compact
Info(i) Warning Icon in Task Tracker: In<TaskListView />(both single rows and group parent/child rows) and<AdminTaskTable />, overdue cases display a compact circular amberInfo(i) icon (w-5 h-5). Hovering over the icon reveals a dark tooltip detailing the exact number of days held in custody, days past the 7-day grace period, and the applicableLKR 500/week(LKR 100/day) vault holding fee policy. - Visa Detail Drawer Banner: Opening an overdue visa in
<VisaDetailPanel />renders an amber Overdue Passport Custody alert banner at the top of the drawer advising staff to notify the customer and apply any applicable vault holding fee before marking the passport collected.