sequenceDiagram
    participant Citizen as 👤 Citizen
    participant Frontend as 🌐 Frontend<br/>Next.js
    participant API as 📡 NestJS API
    participant DB as 🗄️ PostgreSQL
    participant MinIO as 📦 MinIO
    participant Blockchain as ⛓️ Besu<br/>Smart Contracts
    participant Dept1 as 🏢 Dept 1<br/>Approver
    participant Dept2 as 🏢 Dept 2<br/>Approver
    participant Webhook as 🔔 Webhook

    rect rgb(31, 41, 55)
    note over Citizen,API: 1. License Request Submission
    Citizen->>Frontend: Create Resort License<br/>Request & Upload<br/>Documents
    Frontend->>API: POST /licenses/create<br/>Form Data + Files
    API->>DB: Create license_request<br/>status: DRAFT
    end

    rect rgb(59, 130, 246)
    note over API,MinIO: 2. Document Upload & Hashing
    API->>MinIO: Upload Documents<br/>(PDF, Images, etc.)
    MinIO-->>API: Document URLs
    API->>API: Generate SHA-256<br/>Hash of Files
    API->>DB: Store document_metadata<br/>with content_hash
    end

    rect rgb(168, 85, 247)
    note over API,Blockchain: 3. Blockchain Recording
    API->>Blockchain: Call DocumentRegistrar<br/>recordDocumentHash()<br/>params: licenseHash,<br/>department, timestamp
    Blockchain->>Blockchain: Emit DocumentHashRecorded<br/>event
    Blockchain->>DB: Store blockchain<br/>tx_hash in license_request
    API-->>Frontend: Request Submitted
    Frontend-->>Citizen: Confirmation + Request ID
    end

    rect rgb(20, 184, 166)
    note over DB,DB: 4. Update to SUBMITTED State
    API->>DB: Update license_request<br/>status: SUBMITTED
    API->>DB: Create audit_log entry
    end

    rect rgb(59, 130, 246)
    note over API,Dept1: 5. Route to Department 1
    API->>API: Resolve workflow for<br/>Resort License POC
    API->>DB: Create approval_request<br/>status: PENDING<br/>department: Tourism
    API->>Webhook: Send notification
    Webhook->>Dept1: Email: License<br/>Ready for Review
    end

    rect rgb(139, 92, 246)
    note over API,Dept2: 6. Route to Department 2 (Parallel)
    par Department 2 Review
        API->>DB: Create approval_request<br/>status: PENDING<br/>department: Fire Safety
        API->>Webhook: Send notification
        Webhook->>Dept2: Email: License<br/>Ready for Review
    end
    end

    rect rgb(34, 197, 94)
    note over Dept1,Blockchain: 7. Department 1 Approval
    Dept1->>Frontend: Review Documents<br/>& Attachments
    Dept1->>API: POST /approvals/approve<br/>approval_id, comments
    API->>DB: Update approval_request<br/>status: APPROVED<br/>reviewed_by, timestamp
    API->>Blockchain: Call ApprovalManager<br/>recordApproval()<br/>params: licenseHash,<br/>department, signature
    Blockchain->>Blockchain: Emit ApprovalRecorded
    end

    rect rgb(34, 197, 94)
    note over Dept2,Blockchain: 8. Department 2 Approval (Parallel)
    par Department 2 Review
        Dept2->>Frontend: Review Documents
        Dept2->>API: POST /approvals/approve
        API->>DB: Update approval_request<br/>status: APPROVED
        API->>Blockchain: recordApproval()
        Blockchain->>Blockchain: Emit ApprovalRecorded
    end
    end

    rect rgb(236, 72, 153)
    note over API,Blockchain: 9. Final Approval Processing
    API->>API: Check all approvals<br/>complete
    API->>Blockchain: Call LicenseRequestNFT<br/>mint()<br/>params: applicant,<br/>licenseURI, metadata
    Blockchain->>Blockchain: Mint ERC-721<br/>Soulbound NFT
    Blockchain->>Blockchain: Emit Transfer event
    end

    rect rgb(20, 184, 166)
    note over DB,Frontend: 10. Update Final State
    API->>DB: Update license_request<br/>status: APPROVED<br/>nft_token_id
    API->>DB: Create audit_log<br/>entry: APPROVED
    API->>Webhook: Send notification
    Webhook->>Citizen: Email: License<br/>Approved!
    API-->>Frontend: License Approved
    Frontend-->>Citizen: Display NFT &<br/>Certificate
    end

    rect rgb(96, 125, 139)
    note over Citizen,Frontend: 11. License Verification
    Citizen->>Frontend: Download License<br/>Certificate
    Frontend->>API: GET /licenses/{id}<br/>/verify
    API->>Blockchain: query getLicenseNFT()<br/>tokenId
    Blockchain-->>API: NFT metadata,<br/>owner, issuer
    API-->>Frontend: Verified ✓
    Frontend-->>Citizen: Display Verified<br/>License Certificate
    end
