Apex Vault Bank Core Platform

graph TD
    subgraph Client Layer
        A1["Bank Member (Customer)"]
        A2["Bank Staff / Cashier / Officer"]
        A3["Executive Administrator"]
    end

    subgraph Web & Middleware Layer
        B1["Django URL Routing & View Dispatcher"]
        B2["Security & CSRF Middleware"]
        B3["Audit Log Middleware"]
        B4["Custom Auth & RBAC Evaluator"]
    end

    subgraph Core Business Services Layer
        C1["BankingService (Atomic Core Engine)"]
        C2["Risk & Fraud Detection Thresholds"]
        C3["Loan Amortization Engine"]
        C4["Notification Engine"]
    end

    subgraph Data & Storage Layer
        D1[("SQLite / PostgreSQL Database")]
        D2[("Media Storage (Avatars, KYC, Attachments)")]
    end

    A1 -->|HTTPS Requests| B1
    A2 -->|HTTPS Requests| B1
    A3 -->|HTTPS Requests| B1

    B1 --> B2 --> B3 --> B4
    B4 --> C1
    B4 --> C3

    C1 -->|select_for_update| D1
    C1 --> C2
    C1 --> C4
    C3 --> D1
    B3 --> D1
    B1 --> D2
                

graph TD
    Start(["User Arrives at Platform"]) --> AuthChoice{"Has Existing Account?"}

    AuthChoice -- No --> Register["Submit Registration Form (Username, Email, Phone, DOB)"]
    Register --> CreateAccount["System Creates User Record (Role: MEMBER, KYC: PENDING)"]
    CreateAccount --> AutoGenAcc["Auto-Generate Default Savings Account (400-XXXX-XXXX)"]
    AutoGenAcc --> KYCNotice["Prompt User for KYC Document Upload (ID/Passport)"]
    KYCNotice --> Login

    AuthChoice -- Yes --> Login["Enter Credentials (Username & Password)"]
    Login --> ValidateCreds{"Are Credentials Valid?"}

    ValidateCreds -- No --> IncrFailed["Increment failed_login_attempts"]
    IncrFailed --> CheckAttempts{"Attempts >= 5?"}
    CheckAttempts -- Yes --> LockAccount["Set is_locked = True & Log Security Audit Alert"]
    CheckAttempts -- No --> DisplayError["Display Invalid Credentials Error"]
    LockAccount --> Stop(["Access Blocked - Contact Support"])
    DisplayError --> Login

    ValidateCreds -- Yes --> CheckLock{"Is Account Locked?"}
    CheckLock -- Yes --> Stop
    CheckLock -- No --> ResetFailed["Reset failed_login_attempts = 0 & Log AUTH Audit"]

    ResetFailed --> EvaluateRole{"Evaluate User Role"}

    EvaluateRole -- MEMBER --> MemberDash["Redirect to Member Dashboard (/dashboard/)"]
    EvaluateRole -- STAFF --> StaffDash["Redirect to Staff Operations Counter (/dashboard/)"]
    EvaluateRole -- ADMIN --> AdminDash["Redirect to Executive Control Panel (/dashboard/)"]

    subgraph KYC Vetting Flow
        KYCNotice --> StaffQueue["Staff KYC Queue"]
        StaffQueue --> ReviewKYC{"Staff Reviews ID Document"}
        ReviewKYC -- Approve --> SetVerified["Set kyc_status = VERIFIED & Grant Full Limits"]
        ReviewKYC -- Reject --> SetRejected["Set kyc_status = REJECTED & Log Notes"]
    end
                

graph TD
    T1(["Member Initiates Transfer"]) --> T2["Input Source Acc, Target Acc No, Amount, PIN, Description"]
    T2 --> T3{"Validate Transaction PIN"}

    T3 -- Invalid PIN --> T_Err1["Log Audit Failure & Raise PIN Error"]
    T3 -- Valid PIN --> T4["Begin transaction.atomic() Block"]

    T4 --> T5["select_for_update() Lock Source Account"]
    T5 --> T6["select_for_update() Lock Destination Account"]

    T6 --> T7{"Validate Account Statuses"}
    T7 -- Frozen/Inactive --> T_Err2["Rollback & Raise Account Status Error"]

    T7 -- Active --> T8{"Check Sender Daily Limit"}
    T8 -- Limit Exceeded --> T_Err3["Rollback & Raise Daily Limit Exceeded"]

    T8 -- Within Limit --> T9["Calculate Transfer Fee (0.5% capped at $15; Flat $1 for Business)"]
    T9 --> T10{"Balance >= (Amount + Fee)?"}

    T10 -- Insufficient --> T_Err4["Rollback & Raise Insufficient Funds Error"]

    T10 -- Sufficient --> T11["Deduct (Amount + Fee) from Source Account"]
    T11 --> T12["Add Amount to Destination Account"]

    T12 --> T13{"Amount >= $10,000 Fraud Threshold?"}
    T13 -- Yes --> T14["Set is_flagged = True & Record Flag Reason"]
    T13 -- No --> T15["Set is_flagged = False"]

    T14 --> T16["Save Transaction Record (TXN-YYYYMMDDHHMM-XXXXXX)"]
    T15 --> T16

    T16 --> T17["Create Immutable AuditLog Entry"]
    T17 --> T18["Send Dual Notifications (Debit Alert to Sender, Credit Alert to Receiver)"]
    T18 --> T19(["Commit Transaction & Render Success Receipt"])
                

graph TD
    subgraph Cashier Deposit Flow
        D1(["Cashier / Staff Counter"]) --> D2["Enter Account Number & Cash Amount"]
        D2 --> D3["Lock Account via select_for_update()"]
        D3 --> D4["Add Amount to Account Balance"]
        D4 --> D5["Record DEPOSIT Transaction (Created by Staff)"]
        D5 --> D6["Audit Log STAFF_ACTION & Send Credit Alert Notification to Member"]
    end

    subgraph Cashier / Member Withdrawal Flow
        W1(["Withdrawal Request"]) --> W2{"Is Cashier or Member?"}
        W2 -- Member Self-Service --> W3["Require & Verify Transaction Security PIN"]
        W2 -- Cashier Desk --> W4["Verify Customer Identity / Photo ID"]
        W3 --> W5["Lock Account via select_for_update()"]
        W4 --> W5
        W5 --> W6{"Balance >= Requested Amount?"}
        W6 -- No --> W_Err["Raise Insufficient Balance Error"]
        W6 -- Yes --> W7["Deduct Amount from Account Balance"]
        W7 --> W8["Record WITHDRAWAL Transaction"]
        W8 --> W9["Audit Log & Send Debit Alert Notification"]
    end
                

graph TD
    L1(["Member Applies for Loan"]) --> L2["Select Type (Personal, Business, Mortgage, Auto, Edu)"]
    L2 --> L3["Enter Amount, Duration (1-120 Months), Purpose, Collateral"]
    L3 --> L4["Compute Monthly EMI via Loan.compute_amortization()"]
    L4 --> L5["Create Loan Record (Status: PENDING)"]
    L5 --> L6["Send Notification & Audit Log Application"]

    L6 --> L7["Staff / Admin Review Workbench"]
    L7 --> L8{"Credit Committee Decision"}

    L8 -- Under Review --> L9["Set Status: UNDER_REVIEW & Request Additional Docs"]
    L8 -- Reject --> L10["Set Status: REJECTED, Store Rejection Reason & Notify Member"]

    L8 -- Approve --> L11["Begin transaction.atomic() Approval & Disbursement"]
    L11 --> L12["Update Loan Status: APPROVED"]
    L12 --> L13["Credit Full Loan Amount to Member's Bank Account Balance"]
    L13 --> L14["Record LOAN_DISBURSEMENT Transaction"]
    L14 --> L15["Generate Monthly Amortization Repayment Schedule (LoanRepayment Records)"]
    L15 --> L16["Send Approval Notification & Log Audit"]

    subgraph Repayment Cycle
        R1(["Member / Auto-Debit Repayment"]) --> R2["Select Repayment Amount & Enter PIN"]
        R2 --> R3["Deduct Amount from Account Balance"]
        R3 --> R4["Apply Payment to Oldest UPCOMING / LATE Installment Schedule"]
        R4 --> R5["Update total_paid & Check if Fully Paid"]
        R5 --> R6{"total_paid >= total_payable?"}
        R6 -- Yes --> R7["Mark Loan Status: FULLY_PAID"]
        R6 -- No --> R8["Retain Status: APPROVED"]
    end
                

graph TD
    C1(["Member Card Panel"]) --> C2{"Action Selected"}

    C2 -- Issue New Card --> C3["Choose Type (DEBIT / VIRTUAL) & Network (VISA / MASTERCARD)"]
    C3 --> C4["Generate Masked 16-Digit Number, CVV, Expiry Year"]
    C4 --> C5["Link to Bank Account & Set Default Daily Limit ($2,500)"]
    C5 --> C6["Notify Member & Log Card Audit"]

    C2 -- Toggle Freeze Switch --> C7{"Current Card Status?"}
    C7 -- ACTIVE --> C8["Set Status = FROZEN (Block all card transactions)"]
    C7 -- FROZEN --> C9["Set Status = ACTIVE (Restore card spending)"]
    C8 --> C10["Notify User & Update Dashboard Card Badge"]
    C9 --> C10

    C2 -- Adjust Limits & Toggles --> C11["Modify Daily Spend Limit / Toggle Online, Foreign, Contactless Features"]
    C11 --> C12["Save Settings Instantly & Audit Log Feature Change"]
                

graph TD
    S1(["Member Issues Inquiry / Complaint"]) --> S2["Submit Support Ticket (Category, Subject, Priority, Message, File)"]
    S2 --> S3["Generate Ticket Reference ID (TCK-XXXXXXXX)"]
    S3 --> S4["Set Status = OPEN & Route to Staff Support Desk"]

    S4 --> S5["Staff Officer Claims / Assigned to Ticket"]
    S5 --> S6["Set Status = IN_PROGRESS"]
    S6 --> S7["Threaded Communications (Member & Staff Exchange Messages / Attachments)"]

    S7 --> S8{"Issue Resolved?"}
    S8 -- Needs More Info --> S7
    S8 -- Resolved --> S9["Staff Marks Status = RESOLVED"]
    S9 --> S10["Member Closes Ticket (Status = CLOSED)"]
                

graph TD
    F1["Transaction Processed in BankingService"] --> F2{"Amount >= $10,000.00?"}

    F2 -- Yes --> F3["Set is_flagged = True & Record Flag Reason"]
    F3 --> F4["Route to Staff Fraud Workbench (/transactions/fraud-alerts/)"]
    F2 -- No --> F5["Normal Transaction Execution"]

    F4 --> F6{"Compliance Officer Audit"}

    F6 -- Approve / Legit --> F7["Officer Clicks Clear Flag -> Set is_flagged = False"]
    F7 --> F8["Log Staff Compliance Audit Action"]

    F6 -- Fraudulent / Suspicious --> F9["Officer Clicks Freeze Account"]
    F9 --> F10["Set Account Status = FROZEN"]
    F10 --> F11["Block All Future Debits/Credits & Trigger Alert Notification"]
                

erDiagram
    User ||--o{ BankAccount : "owns"
    User ||--o{ Loan : "applies for"
    User ||--o{ BankCard : "holds"
    User ||--o{ SupportTicket : "opens"
    User ||--o{ AuditLog : "generates"
    User ||--o{ Notification : "receives"

    BankAccount ||--o{ Transaction : "sent_transactions"
    BankAccount ||--o{ Transaction : "received_transactions"
    BankAccount ||--o{ BillPayment : "bill_payments"
    BankAccount ||--o{ BankCard : "linked_cards"
    BankAccount ||--o{ Loan : "disbursed_to"

    Transaction ||--o| BillPayment : "bill_detail"

    Loan ||--o{ LoanRepayment : "amortization_schedule"

    SupportTicket ||--o{ TicketMessage : "messages"
    User ||--o{ TicketMessage : "authors"

    User {
        int id PK
        string username
        string role "ADMIN | STAFF | MEMBER"
        string kyc_status "PENDING | VERIFIED | REJECTED"
        string transaction_pin_hash
        int failed_login_attempts
        boolean is_locked
    }

    BankAccount {
        int id PK
        string account_number UK "400-XXXX-XXXX"
        string account_type "SAVINGS | CHECKING | BUSINESS | FIXED"
        decimal balance
        string status "ACTIVE | FROZEN | DORMANT | CLOSED"
        decimal daily_transfer_limit
    }

    Transaction {
        int id PK
        string reference UK "TXN-YYYYMMDDHHMM-XXXXXX"
        decimal amount
        decimal fee
        string transaction_type "DEPOSIT | WITHDRAWAL | TRANSFER | BILL_PAYMENT | LOAN"
        string status "COMPLETED | PENDING | FLAGGED"
        boolean is_flagged
    }

    BillPayment {
        int id PK
        string biller_category
        string biller_name
        string customer_reference
        decimal amount
    }

    Loan {
        int id PK
        string loan_id UK "LN-XXXXXX"
        string loan_type
        decimal amount
        decimal interest_rate
        int duration_months
        decimal monthly_installment
        decimal total_payable
        decimal total_paid
        string status "PENDING | UNDER_REVIEW | APPROVED | REJECTED | FULLY_PAID"
    }

    LoanRepayment {
        int id PK
        int installment_number
        date due_date
        decimal amount_due
        decimal amount_paid
        string status "UPCOMING | PAID | LATE"
    }

    BankCard {
        int id PK
        string card_id UK "CRD-XXXXXX"
        string card_number
        string card_type "DEBIT | VIRTUAL | CREDIT"
        decimal daily_limit
        string status "ACTIVE | FROZEN | BLOCKED"
        boolean is_online_enabled
    }

    SupportTicket {
        int id PK
        string ticket_id UK "TCK-XXXXXX"
        string category
        string priority
        string status "OPEN | IN_PROGRESS | RESOLVED | CLOSED"
    }

    AuditLog {
        int id PK
        string action
        string category
        string description
        string ip_address
        datetime timestamp
    }

    Notification {
        int id PK
        string title
        string message
        string notification_type
        boolean is_read
    }