System Architecture & Functional Modules
Native macOS SwiftUI, GRDB SQLite, multi-provider AI backend, AP/AR workflows, analytics, and security policies.
1. System Overview & Local-First Architecture
FoundationOptionV is a native macOS local-first business financial management application for tracking vendors, customers, invoices, purchase orders, contracts, and accounting records. OptionV operates with zero backend servers—all records are stored locally in an SQLite database (GRDB) in your Mac's Application Support folder. Document tokenization uses Apple Vision Framework and PDFKit. For AI audit and insights, OptionV supports direct, optional connections to OpenAI, Anthropic Claude, and Google Gemini using your own device-restricted Keychain API keys.
Strict Local-First Persistence: All financial tables, master records, and audit logs are persisted securely in local Application Support SQLite databases with no external server tracking.
Zero Cloud Leaks: Data stays on your device unless you export JSON backups or opt into third-party AI features.
Secure Keychain Storage: AI API keys are stored exclusively in your Mac's local Keychain without iCloud syncing.
2. Accounts Payable (AP) & Invoice Ingestion Engine
AP EngineIncoming vendor invoices undergo native OCR tokenization to extract Invoice Number, PO Number, Vendor Number, Tax ID, IBAN, Invoice Date, Currency, Net Amount, Tax Amount, Freight, and Misc Fees. Extracted invoices undergo Smart Reconciliation against the Vendor Master Database, PO Ledger, and Active Invoice Ledger. Single Mode offers interactive live field mapping with AI hints, while Batch Mode (BatchInvoiceAIEngine) provides a parallel processing queue with automated triage into Ready, Duplicate, Quarantine, or Failed states. Unmatched or mismatched invoices are routed to Quarantine Review.
PO Number is optional: Invoices without a PO match directly against vendorNumber master data.
Credit Memo Support: Accepts negative amounts (e.g., -1,200.00) and posts credit balance reductions to the AP ledger.
Supported Invoice Types: Standard Invoice, Tax Invoice, Prepayment, Final Invoice, Credit Memo, and Debit Memo.
3. Accounts Receivable (AR) & Dynamic Credit Memo Generation
AR EngineOutbound customer billing generates official invoices linked directly to customer profiles and Customer Purchase Orders (Sales Orders). Payment terms (Net 14, Net 30, Net 60) dynamically compute due dates (dueDate = invoiceDate + paymentTermsDays). When 'Credit Memo' is selected, the system switches to negative balance mode with automatic 'CM-' prefixing (e.g. CM-20260417-1030), negative line item unit prices/totals (-$X.XX), negative subtotal/VAT base, and credit note posting to AR receivables.
5 Executive Vector PDF Templates: Classic (Corporate), Modern (Accents), Minimalist (Monospace), Bold (High Contrast), and Elegant (Refined).
Terms Hierarchy: Active salesContract payment terms take precedence over default customer master records.
External PO Tracking: vendorPONumber preserves customer reference identifiers across sales orders and invoices.
4. AI Audit Suite & Compliance Logging Engine
AI & AuditThe AI Audit Advisor (AIAuditAssistantView) delivers a natural language conversational assistant for AP/AR datasets with one-click Prompt Chips ('Summarize issues', 'Cost impact', 'Vendor risk', 'Explain duplicates') and entity recognition that auto-detects and highlights invoice numbers. The reactive AuditMemoryManager records Log UUID, Timestamp, User Query, AI Response, Active Provider, Model Name, Category/Action, Execution Latency (seconds), and Status (Success/Failed). The AIAuditPDFExporter generates CoreText/CoreGraphics multi-page compliance reports with KPI summary cards and 'Page X of Y' stamps.
Automatic Reactive Logging: Audits all user queries, prompt chip clicks, suggested questions, and batch AI extractions.
Direct Provider Communication: Requests go directly from your Mac to OpenAI, Anthropic, or Google with no intermediary server.
Formal Compliance Export: Produces audit-grade signed PDF reports with executive KPI dashboards and compliance stamps.
5. Financial Analytics, Dynamic Aging & Multi-Currency Engine
AnalyticsReal-time financial analytics dashboards deliver instant KPI strips (Gross Volume Spend, Total Revenue, Match Health Rate, Critical Anomalies) and dynamic aging schedules (<30 days, 31-60, 61-90, 90+ days) for both AP payables and AR receivables. Working capital metrics compute Days Payable Outstanding (DPO) and Days Sales Outstanding (DSO). The multi-currency engine queries the free Frankfurter Exchange Rate API (api.frankfurter.dev) using currency codes and dates only—never sending business, vendor, or invoice details.
Privacy-Preserving Rates: Multi-currency conversion requests contain only currency codes and dates, never business data.
Real-Time Aging: Aging buckets recalculate dynamically against live invoice dates and payment terms.
Working Capital KPIs: Monitor liquidity and cash cycle efficiency with live DPO and DSO tracking.
Multi-Format Exports: Export executive summaries, AP/AR ledgers, and statement center records to CSV and signed PDFs.
6. Security, Integrity & Data Control Policies
SecurityOptionV enforces strict enterprise privacy and integrity policies: 1) Local-First Storage (GRDB SQLite in Application Support protected by macOS file permissions and FileVault disk encryption); 2) Device-Only Keychain Storage for optional AI API keys (no iCloud sync); 3) Safety Copies created automatically before any backup restore; 4) Portable JSON Data Exports available on-demand via Settings → Backup & Restore; 5) In-App macOS System Notifications via Apple UserNotifications framework.
Complete Data Ownership: Export all data to JSON anytime via Settings → Backup & Restore.
Safety Copies on Restore: Automatic safety copy is made before restoring to prevent accidental data overwrites.
Zero Account Dependency: No sign-ups, tracking, advertising, or remote data collection.
Subsystems & Core Engines
Architecture specifications for batch AI extraction, Smart matching, dynamic credit memos, vector PDF templates, and compliance audit reporting.
BatchInvoiceAIEngine
AP · High-throughput batch processing queue running parallel background OCR, multi-provider AI key-value extraction, PO fallback matching, and automated triage into Ready, Duplicate, Quarantine, or Failed states.
// Batch AI extraction & triage
enum BatchStatus { ready, duplicate, quarantine, failed }SmartReconciliation
AP · Automated Smart verification cross-referencing extracted invoice data against Vendor Master records (Tax ID, IBAN, Terms), Purchase Order Ledger (PO Number, line items, currency), and Active Invoice Ledger.
// Smart match verification
verify(vendorMaster, poLedger, activeInvoiceLedger)CreditMemoEngine
AP & AR · Credit memo generator formatting negative liability amounts (e.g., -1,200.00), auto-assigning 'CM-' prefixes (e.g. CM-20260417-1030), and posting credit balance reductions to vendor or customer ledgers.
// Negative liability calculation
unitPrice = -abs(price); totalDue = -abs(subtotal + tax)VectorPDFTemplates
AR · Executive vector PDF rendering engine across 5 corporate design templates: Classic (Enterprise letterhead), Modern (Accent colors), Minimalist (Monospaced accounting), Bold (High-contrast blocks), and Elegant (Refined borders).
AIAuditAssistantView
AI · Conversational natural language assistant analyzing AP/AR datasets with one-click Prompt Chips ('Summarize issues', 'Cost impact', 'Vendor risk', 'Explain duplicates') and entity recognition highlighting invoice numbers.
// Prompt chip shortcuts
chips = ["Summarize issues", "Cost impact", "Vendor risk", "Explain duplicates"]AuditMemoryManager
Audit · Reactive audit logging engine capturing Log UUID, Timestamp, User Query, AI Response, Active Provider, Model Name, Category/Action, Latency (seconds), and Status with token-bounded context management.
// Audit log schema
recordLog(uuid, timestamp, query, response, provider, model, latency, status)AIAuditPDFExporter
Compliance · Multi-page compliance PDF exporter utilizing CoreText & CoreGraphics with Executive Title Block, Date/Scope Metadata, Summary KPI Dashboard (Queries, Success Rate, Latency), and 'Page X of Y' stamps.
// Multi-page PDF pagination & KPI stamp
renderComplianceHeader(kpiDashboard); renderPageNumber("Page X of Y");FinancialAnalyticsEngine
Analytics · Real-time financial dashboards with KPI strips, dynamic aging buckets (<30, 31-60, 61-90, 90+ days), DPO/DSO working capital metrics, and multi-currency converter supporting USD, EUR, GBP, CHF, CAD, and JPY.
Architecture & Operational Flowcharts
Visual lifecycle diagrams for AP/AR processing, batch AI queues, Smart reconciliation, and compliance audit export.
AP Ingestion & Reconciliation Flow
End-to-end Accounts Payable pipeline: PDF/image OCR ingestion → Vendor Master & PO Ledger against → Batch AI triage → Quarantine review → Ledger posting.
AR Invoicing & 5-Template Vector PDF Generation
Accounts Receivable flow: Sales order conversion → Payment terms due date calculation → Dynamic Credit Memo generator (CM- prefix) → Vector PDF export across 5 design templates.
Documentation & Developer Resources
System architecture specifications, AI & OCR integration protocols, compliance schemas, and native builds.
OptionV System Architecture Spec v2.0
Comprehensive specification covering Native macOS SwiftUI, GRDB SQLite, and multi-provider AI backend.
Multi-Provider AI & Vision OCR Protocol
Integration guide for Gemini, OpenAI, Claude, DeepSeek, Ollama, and Apple Vision OCR tokenization.
AIAuditPDFExporter & Compliance API
Reactive audit logging schema, CoreText compliance report exporter, and KPI calculation formulas.
OptionV macOS Native Application
Download signed Apple Silicon / Intel native macOS installation build with local-first SQLite engine.
Operational FAQs & Guardrail Policies
Frequently asked operational questions, credit memo procedures, Smart reconciliation rules, and audit compliance mechanisms.
How does the BatchInvoiceAIEngine triage incoming invoices?
BatchInvoiceAIEngine runs a parallel high-throughput queue performing background OCR and AI key-value extraction. It cross-checks extracted IDs against the Vendor Master and PO Ledgers to triage each document into: Ready (verified match), Duplicate (detected existing invoice number), Quarantine (unmatched vendor or PO discrepancy), or Failed (OCR/parsing error).
How are Credit Memos handled across Accounts Payable (AP) and Accounts Receivable (AR)?
In AP, setting Invoice Type to 'Credit Memo' accepts negative monetary amounts (e.g., -1,200.00) and automatically posts a credit balance reduction to the vendor ledger. In AR, the Dynamic Credit Memo Generator switches to negative balance mode, auto-prefixes the invoice with 'CM-' (e.g., CM-20260417-1030), converts line items and tax bases to negative values, and reduces customer receivable balances.
What validation steps are included in the Smart Reconciliation?
The Smart Reconciliation engine cross-references extracted invoice data against: 1) Vendor Master Database (Tax ID, IBAN, Vendor Number, Payment Terms); 2) Purchase Order Ledger (PO Number, approved amounts, currency, and line items); and 3) Active Invoice Ledger (real-time duplicate detection on normalized IDs). Invoices failing corroboration are routed to Quarantine Review.
How does the Reactive Audit Logging Engine (AuditMemoryManager) capture AI interactions?
AuditMemoryManager automatically audits user queries, prompt chips, suggested questions, and batch AI extractions. It captures: Unique Log UUID, Timestamp, User Query, AI Response, Active Provider (OpenAI, Anthropic Claude, Google Gemini), Model Name, Category/Action, Execution Latency (seconds), and Status (Success/Failed). All content is sent directly from your Mac to the selected provider with zero intermediary servers.
What information is included in the compliance reports generated by AIAuditPDFExporter?
AIAuditPDFExporter produces formal multi-page compliance PDFs via CoreText & CoreGraphics. Each report includes an Executive Title Block, Date & Scope Metadata, a Summary KPI Dashboard (Total Queries, Success Rate, Avg Latency, Active Providers), Formatted Prompt & Response cards, and Running Page Numbering ('Page X of Y') with an official compliance stamp.
How do the Security, Privacy & Guardrail Policies operate?
OptionV enforces 5 key privacy and security policies: 1) Strict Local Persistence (GRDB SQLite inside Application Support); 2) Device-Only Keychain Storage (no iCloud sync for AI API keys); 3) Safety Copies created automatically before database restores; 4) Portable JSON Data Exports on-demand via Settings → Backup & Restore; and 5) Privacy-preserving multi-currency lookup via Frankfurter Exchange Rate API (only currency codes and dates are sent).