Skip to content

Requirement Specifications

Below is the breakdown of the “Visa Issuing Assistance” module into Epics, User Stories and a detailed list of functional and non-functional requirements.

1. Epics & User Stories

Epic 1 – Visa Application Management

  • US-1.1 As an Agent, I want to create a new visa application record so that I can capture all customer and applicant details in one place.
  • US-1.2 As an Agent, I want to upload and store passport images for each applicant to S3 so that I have a copy of their identity documents.
  • US-1.3 As an Agent, I want to edit or add additional applicants to an existing application so that group applications are supported.

Epic 2 – Document Requirements Retrieval

  • US-2.1 As an Agent, upon entering the applicant’s passport nationality and travel country, I want the system to fetch and display the required visa documents in real-time so that I know exactly which papers to collect.
  • US-2.2 As an Agent, I want to choose from alternative API providers (ideally free or low-cost tiers) so that integration costs remain minimal.

Epic 3 – Application Tracking

  • US-3.1 As an Agent, I want to record for each application: the supplier used, date of submission, issuance status, payment status, supplier cost and customer price so that I can track progress and margins.
  • US-3.2 As an Agent, I want to override the “payment required before submission” rule in special cases so that I have operational flexibility.

Epic 4 – Invoicing & Payment

  • US-4.1 As an Agent, I want to generate and send an invoice with a Telr payment link so customers can pay online.
  • US-4.2 As a Customer, I want to click the payment link and complete payment via Telr before my application is sent to the supplier.

Epic 5 – Visa Delivery & Secure Download (Implemented — TQ-18)

  • US-5.1 As an Agent, I want to upload visa application documents (passport copies, photos) to encrypted S3 storage and download them directly without presigned URLs.
  • US-5.2 As an Agent, I want to upload the issued visa PDF to S3 and trigger a notification (email/SMS/WhatsApp) to the customer with a secure download link.
  • US-5.3 As a Customer, I want to verify my identity (email + phone) on a public download page, receive a one-time code via my chosen channel (WhatsApp/SMS/email), and download my visa after entering the code.

Epic 6 – Alerts & Reporting

  • US-6.1 As an Agent, I want a dashboard listing all in-progress applications with their travel start dates so I can follow up proactively.
  • US-6.2 As a System, I want to send a daily email at 09:00 (local) listing “critical” visas (travel < 3 working days) to a predefined address so no rush applications are missed.
  • US-6.3 As a System, I want calendar-style alerts (e.g., pop-ups or badges) when any travel date is within configurable thresholds.

2. Detailed Requirements

2.1 Visa Application Management

2.1.1 Data Capture - The “New Visa Application” form shall include: - Customer Contact: full name, phone, email. - One or more Applicant entries: full name, date of birth, nationality, passport number, issue date, expiry date, destination country, travel start/end dates. - The form shall validate required fields and date ranges. - The form shall allow adding/removing applicant sections dynamically. - The customers shall be registered in integrated CRM system (Odoo by default). - For each enquiry (regardless of the outcome), a lead/opportunity will be generated in the CRM system.

2.1.2 Passport Image Upload - The system shall enable file upload (JPG/PNG, max 5 MB) per applicant. - Uploaded files shall be stored in AWS S3 with per-file unique keys and server-side encryption. - The application record shall save the S3 URL and metadata (upload date, uploader). - If the uploaded document is deleted from the records, it shall be deleted from S3 bucket as well.

2.2 Document Requirements Retrieval

2.2.1 External API Integration - The system uses TravelBuddyAI via RapidAPI (v2 endpoint: /v2/visa/check) for visa requirement lookups. - Previously considered providers (Smartable AI Travel, VisaHQ, Sherpa) were not selected. - The UI fires a request on nationality + destination selection and classifies the response into visa categories (NOT_REQUIRED, VOA, ONLINE, REQUIRED, UNKNOWN) using a data-driven keyword matching algorithm. See Visa Category Classification. - The API response format uses visa_rules.primary_rule.name (v2), with fallback to the legacy category field (v1). - Same-country lookups (passport = destination) are short-circuited to NOT_REQUIRED without calling the API. - The integration layer caches results for 30 days per nationality-destination pair in DocumentrequirementcacheEntity (JSONB column).

2.3 Application Tracking

2.3.1 Tracking Fields - For each application, track: Supplier Name, Submission Date, Issuance Status (Pending/In-Process/Approved/Rejected), Payment Status (Unpaid/Paid/Refunded), Supplier Cost, Mark-up Price. - The system shall compute profit margin = Price to customer – Cost from supplier. - Agents can override “Submit only if Paid” flag per application.

2.3.2 Audit Trail - All changes to status or financials must be timestamped and stored in an audit log, showing user and change details.

2.4 Invoicing & Payment

2.4.1 Invoice Generation - The system shall generate a PDF invoice with company details, customer info, itemized visa fees, taxes, total, and a Telr payment URL. - The invoice should be registered in an integrated ERP system (Odoo by default). - Invoices should be templatable (Logo, branding).

2.4.2 Telr Integration - On invoice send, embed a secure Telr payment link via Telr’s REST API. - The system shall receive payment notifications (webhooks) and update Payment Status automatically. - Agents can resend payment links or mark manually as Paid/Refunded.

2.5 Visa Delivery & Secure Download (Implemented — TQ-18)

2.5.1 Document Storage - All visa application documents (passport copies, photos, supporting docs) are stored in a dedicated encrypted S3 bucket (tq-visa-documents) with SSE-KMS encryption. - Agents upload and download documents directly via authenticated API endpoints (visa/document/upload, visa/document/download) — no presigned URLs for agent access. - S3 keys use only generated IDs: applications/{appId}/documents/{randomSuffix}.{ext} — no PII in paths. - MIME type validated from file bytes (Tika); only PDF, JPEG, PNG allowed; max 10 MB.

2.5.2 Visa Issuance Upload - Agents upload the issued visa PDF via visa/delivery/initiate, which stores the file in S3 and creates a delivery record. - Agent triggers customer notification via visa/delivery/notify with channel choice (email, SMS, or WhatsApp).

2.5.3 Secure Download Workflow - Customer receives a link to the public download page (visa-download.html?ref={publicGuid}). - The download page is publicly accessible (outside Keycloak authentication). - Step 1 — Identity Verification: Customer enters email and phone number. The system validates both match the application record. Max 5 attempts, then 15-minute lockout. - Step 2 — OTP Channel Selection: Customer chooses to receive a one-time code via WhatsApp, SMS, or email. - Step 3 — OTP Entry: Customer enters the 6-digit code. Code expires in 10 minutes. Max 3 validation attempts. - Step 4 — Download: On valid OTP, the system generates a presigned S3 URL (15-minute expiry) and displays a download button. Download date is recorded. - OTP codes are stored as SHA-256 hashes (not plaintext) and validated with constant-time comparison.

See Secure Document Storage Implementation for full technical details and deployment guide.

2.6 Alerts & Reporting

2.6.1 Agent Dashboard - A screen listing all in-progress applications with sortable columns: Customer, Travel Start, Status, Days to Departure.

2.6.2 Calendar Alerts - The system shall compute working days (Mon–Fri, excluding configured holidays) between “today” and Travel Start. - For each application with X days remaining (configurable threshold), display a visual alert (e.g., red badge for < 3 days).

2.6.3 Daily Critical Email - At 09:00 (Asia/Dubai), send an automated email to a predefined address with all applications where travel start is < 3 working days away. - Email content: Table of Customer, Travel Dates, Days Remaining, Status, Action Items.

2.7 Functional workflow

Visa Application Dashboard - List all applications (in-progress, submitted, issued), sortable/filterable by status, travel date, customer.

New Visa Inquiry / Intake - Capture basic customer contact and high-level trip info (country, dates).

Application Flow - (Step 1: Basic Info) — Enter/edit full customer info + one or more applicants (name, DOB, passport data).

  • (Step 2: Document requirements) — Display required documents (fetched live), allow download of checklists & instructions.

  • (Step 3: Document Upload) Upload passport scans & any other docs; show upload status and thumbnails.

  • (Step 4: Invoice & Payment) — Preview/generate PDF invoice; send Telr payment link; view payment status.

  • (Step 5: Submit to Supplier) — Review all data, then “Send” to chosen visa supplier (records supplierid & date).

  • (Step 6: Supplier Tracking & Follow-Up) — See supplier application date/status; add notes or override payment-before-submit flag.

  • (Step 7: Visa Issuance Upload) — Agent uploads issued visa PDF via visa/delivery/initiate; system stores in encrypted S3, creates delivery record.

  • (Step 8: Secure Delivery Management) — Agent selects notification channel (email/SMS/WhatsApp) and sends via visa/delivery/notify. Customer accesses public download page, verifies identity (email + phone), receives OTP, enters OTP to get time-limited presigned download URL.

Alerts & Reports

  • Critical Alerts: list visas with travel date <3 working days
  • Settings: configure thresholds, email recipients, holidays calendar

3. Non-Functional & Technical Requirements

  • Security: All PII and passport scans must be encrypted at rest (AES-256 S3 SSE) and in transit (TLS v1.2+).
  • Scalability: Design for up to 1,000 concurrent applications; caching for external API lookups.
  • Reliability: Retry logic and error notifications for API/webhook failures; dead-letter queue for failed SMS/email.
  • Audit & Compliance: Full audit trail for GDPR compliance; data retention configurable.
  • Extensibility: Modular service design to add new payment gateways or document-provider APIs.
  • Localization: UI text and date formats configurable for target markets; SMS/email templates parameterized.