14. Platform & Infrastructure

NkapBooks is built as a native desktop application using modern web technologies wrapped in a Rust-powered shell. This section covers the platform architecture, cross-platform support, automatic updates, theming, internationalization, and keyboard shortcuts that make NkapBooks a professional-grade desktop accounting tool.

14.0 Technology Stack Overview

NkapBooks combines a modern frontend framework with a lightweight, secure native shell:

┌─────────────────────────────────────────────────────────────┐
│                    NkapBooks Desktop App                      │
├─────────────────────────────────────────────────────────────┤
│  Frontend (Renderer Process)                                 │
│  ┌───────────────────────────────────────────────────────┐  │
│  │  Vue.js 3 + TypeScript + Tailwind CSS                 │  │
│  │  • Reactive UI with Composition API                   │  │
│  │  • Vue Router for SPA navigation                      │  │
│  │  • Pesa library for currency arithmetic               │  │
│  │  • Luxon for date/time handling                       │  │
│  │  • CodeMirror for template editing                    │  │
│  │  • Feather Icons for iconography                      │  │
│  └───────────────────────────────────────────────────────┘  │
├─────────────────────────────────────────────────────────────┤
│  Backend (Tauri Rust Core)                                   │
│  ┌───────────────────────────────────────────────────────┐  │
│  │  Tauri 2 + Rust                                       │  │
│  │  • SQLite / PostgreSQL database drivers               │  │
│  │  • License verification & anti-tampering              │  │
│  │  • PDF generation & printing                          │  │
│  │  • File system access & backup management             │  │
│  │  • Auto-update download & installation                │  │
│  │  • Stronghold for secure credential storage           │  │
│  └───────────────────────────────────────────────────────┘  │
├─────────────────────────────────────────────────────────────┤
│  Tauri Plugins                                               │
│  • plugin-dialog — Native file/folder dialogs                │
│  • plugin-fs — File system read/write                        │
│  • plugin-os — OS detection & platform info                  │
│  • plugin-process — App relaunch & exit                      │
│  • plugin-shell — Open external URLs                         │
│  • plugin-stronghold — Encrypted key-value storage           │
│  • plugin-updater — Signed auto-update system                │
└─────────────────────────────────────────────────────────────┘

Why Tauri Instead of Electron?

14.1 Offline-First Architecture

NkapBooks is designed to work entirely offline. No internet connection is required for any core accounting functionality.

Local Data Storage

All data is stored locally on your device:

What Works Offline

What Requires Internet

Database Architecture

NkapBooks uses a schema-driven architecture where every document type is defined by a JSON schema. The database tables are automatically created and migrated based on these schemas.

SQLite (Default):

• Single file database — easy to backup, move, and restore
• No server process required
• Supports multiple databases (switch between companies)
• File stored in the OS-specific app data directory

PostgreSQL (Optional):

• Full ACID compliance with advanced query capabilities
• Suitable for multi-user network installations
• Configured during setup or from the Database Selector screen

Multi-Database Support

NkapBooks supports managing multiple companies through separate database files:

1. Each company has its own database file (SQLite) or database instance (PostgreSQL)
2. Switch between databases from the Database Selector screen
3. Each database maintains its own:
   • Chart of accounts
   • Users and permissions
   • Settings and preferences
   • Transaction history
   • Print templates

14.2 Cross-Platform Support

NkapBooks runs natively on all major desktop operating systems.

Supported Platforms

Installation

Windows

1. Download the .msi or .exe installer from the NkapBooks website
2. Run the installer — it will install to Program Files by default
3. Launch NkapBooks from the Start Menu or desktop shortcut
4. Updates are installed passively (Windows NSIS passive install mode)

macOS

1. Download the .dmg file for your architecture (Intel or Apple Silicon)
2. Open the .dmg and drag NkapBooks to your Applications folder
3. On first launch, you may need to right-click → Open to bypass Gatekeeper
4. The app runs natively — no Rosetta translation needed on Apple Silicon

Linux

1. Download the package for your distribution:
   • AppImage: Make executable (chmod +x) and run directly — no installation needed
   • .deb: Install with sudo dpkg -i nkapbooks_*.deb or via your package manager
   • .rpm: Install with sudo rpm -i nkapbooks_*.rpm or via DNF/Yum
2. Launch from your application menu or command line

Platform-Specific Features

Window Configuration

NkapBooks uses a frameless window with custom title bar controls:

Content Security Policy

The application enforces a strict CSP for security:

14.3 Auto-Updates

NkapBooks includes an automatic update system powered by the Tauri Updater plugin. Updates are signed, downloaded in the background, and installed when the user chooses to restart.

Update Flow

The update system follows a state machine pattern:

┌──────┐    ┌──────────┐    ┌─────────────┐    ┌───────┐
│ idle │───▶│ checking │───▶│ downloading │───▶│ ready │
└──────┘    └──────────┘    └─────────────┘    └───────┘
                 │                  │
                 ▼                  ▼
              ┌───────┐         ┌───────┐
              │ error │         │ error │
              └───────┘         └───────┘

How It Works

1. Check: On app startup (and on database connection), NkapBooks checks the update endpoint for a newer version
2. Download: If an update is available, it's automatically downloaded in the background
   • The update notification widget appears at the bottom-right of the screen
   • A progress bar shows the download percentage and bytes transferred
3. Ready: When the download completes, the user is notified and can choose:
   • Restart Now — Install the update and relaunch the app immediately
   • Later — Dismiss the notification; the update will be installed when the app is closed
4. Install: The update is applied:
   • Windows: NSIS installer runs in passive mode (no user interaction needed)
   • macOS/Linux: Binary is replaced on disk; the app relaunches

Update Notification UI

When an update is available and downloading, a notification widget appears:

The notification includes a progress bar with four stages:

1. ✓ Checking for updates
2. ✓ Downloading update
3. ✓ Installing update
4. ○ Ready to restart

Update Stages

Deduplication

The update system tracks the last downloaded version to prevent re-downloading the same update when the check runs again (e.g., on database reconnection after the initial startup check already completed).

Signed Updates

All update bundles are signed with a public key embedded in the application. The update endpoint provides signed manifests that the Tauri updater verifies before applying:

Close-Time Install

If the user dismisses the update notification ("Later"), the downloaded update is still applied when the app window is closed. This ensures updates are eventually installed even if the user never clicks "Restart Now":

1. User clicks Later → notification is dismissed
2. User continues working normally
3. When the user closes the app, the pending install callback runs
4. The update is installed silently before the process exits

Update Availability

14.4 Dark Mode

NkapBooks includes a complete dark mode implementation that covers every surface in the application — pages, sidebar, forms, charts, POS interface, and dialogs.

Toggling Dark Mode

Dark mode can be toggled from:

1. Sidebar toggle — Click the moon/sun icon at the bottom of the sidebar
2. System Settings — The darkMode field in SystemSettings stores the preference

Ripple Transition Effect

NkapBooks features a visually polished circular ripple animation when switching between light and dark mode:

┌───────────────────────────────────────┐
│                                       │
│           ●──────────▶ Ripple expands │
│          /                from click  │
│         / radius                      │
│        /                              │
│   Click                               │
│   Point                               │
│                                       │
└───────────────────────────────────────┘

How the animation works:

1. The toggle captures the click position (x, y coordinates)
2. It calculates the maximum radius needed to cover the entire screen from that point
3. If the browser supports the View Transitions API:
   • A ::view-transition-new(root) pseudo-element animates a clip-path: circle() from 0px to the max radius
   • Duration: 800ms with ease-out easing
4. Fallback (if View Transitions API is unavailable):
   • A CSS overlay div is created with position: fixed covering the viewport
   • The overlay animates its clip-path from 0 to the max radius
   • The actual theme change is applied at the midpoint (350ms) of the animation
   • The overlay is removed after the animation completes (800ms)
5. The preference is persisted to SystemSettings.darkMode in the database

Dark Mode Coverage

Persistence

Dark mode preference is stored in two places for reliability:

1. SystemSettings.darkMode — Stored in the database (primary, when DB is connected)
2. darkModeRef — A reactive Vue ref used as fallback when the database is not available (e.g., on the Database Selector screen)

When the app starts, it reads the stored preference and applies it before the first render to prevent a flash of the wrong theme.

14.5 Multi-Language (i18n)

NkapBooks supports multiple languages with real-time language switching — no page reload required.

Desktop App Languages

The desktop application currently supports:

How Language Switching Works

Language switching in NkapBooks is instantaneous — no page reload needed:

┌──────────────┐    ┌──────────────────┐    ┌──────────────────┐
│ User selects │───▶│ Fetch translation │───▶│ Update reactive  │
│ new language │    │ map from file     │    │ refs & UI        │
└──────────────┘    └──────────────────┘    └──────────────────┘

1. User selects a language in Settings (or during Setup Wizard)
2. The app fetches the translation map for that language code
3. The translation map is applied to the translation string system (t tagged template literal)
4. Schema labels are re-translated in memory via translateSchemaMap()
5. The reactive language ref (systemLanguageRef) updates, triggering UI re-renders
6. The preference is saved to the config store

Translation System

NkapBooks uses a tagged template literal system for translations:

// In Vue components and TypeScript code:
const message = t`Hello, welcome to NkapBooks`;
const greeting = t`${count} invoices created`;

The t function:

• Looks up the string in the current language map
• Returns the translated string if found
• Falls back to the original English string if no translation exists
• Supports interpolation with ${variable} placeholders

Translation Files

Translation files are CSV files stored in the translations/ directory:

Each CSV file contains two columns:

• Column 1: English source string
• Column 2: Translated string

These files are bundled as Tauri resources and deployed with the application binary.

Schema Translation

In addition to UI strings, NkapBooks translates schema labels (field names, document type names, option labels):

1. When a non-English language is selected, the schema map is translated in memory
2. All form labels, list column headers, and dropdown options show translated text
3. When switching back to English, translations are cleared and original labels are restored

Website/Server Internationalization

The NkapBooks documentation website supports:

The website uses Nuxt i18n with JSON locale files for full page translation support. The i18n framework allows easy addition of new languages by creating additional locale files.

Language Direction (RTL/LTR)

NkapBooks includes infrastructure for right-to-left (RTL) language support:

• A Vue InjectionKey (languageDirectionKey) provides reactive direction state
• The Tailwind CSS configuration includes tailwindcss-rtl for RTL utility classes
• When an RTL language is activated, the entire UI mirrors automatically

14.6 Keyboard Shortcuts

NkapBooks includes a context-based keyboard shortcut system that enables efficient, keyboard-driven workflows throughout the application.

Shortcut System Architecture

The shortcut system is built on a context-based architecture:

┌─────────────────────────────────────────────────────────────┐
│                    Shortcuts Class                            │
│                                                              │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐        │
│  │  Context A   │  │  Context B   │  │  Context C   │        │
│  │  (Sidebar)   │  │  (Form)      │  │  (Modal)     │        │
│  │             │  │             │  │             │        │
│  │  Ctrl+S     │  │  Ctrl+S     │  │  Escape     │        │
│  │  Ctrl+N     │  │  Ctrl+Enter │  │  Enter      │        │
│  └─────────────┘  └─────────────┘  └─────────────┘        │
│                                                              │
│  Evaluation: Most recent context wins (stack-based)          │
└─────────────────────────────────────────────────────────────┘

Key concepts:

1. Context: Each UI component registers its shortcuts with a unique context (typically the component instance itself)
2. Stacking: When multiple contexts define the same shortcut, the most recently registered context wins
3. Propagation: A shortcut can optionally propagate to earlier contexts if propagate: true is set
4. Cleanup: When a component is destroyed, its context is removed and shortcuts are unregistered

Modifier Keys

The shortcut system supports the following modifier keys:

The pmod (platform modifier) automatically resolves to Ctrl on Windows/Linux and Cmd on macOS, ensuring consistent behavior across platforms.

Global Shortcuts

These shortcuts work from anywhere in the application:

Navigation Shortcuts

Document Form Shortcuts

When editing a document (invoice, payment, journal entry, etc.):

POS Shortcuts

The Point of Sale module supports full keyboard-driven checkout:

Shortcut Registration API

Components register shortcuts using the Shortcuts class:

// Register a shortcut
shortcuts.pmod.set(context, ['KeyS'], () => saveDocument());

// Register with Shift modifier
shortcuts.pmod.shift.set(context, ['KeyS'], () => saveAsNew());

// Register Escape (no modifiers)
shortcuts.set(context, ['Escape'], () => closeForm());

// Clean up when component unmounts
shortcuts.delete(context);

Developer Tools Restrictions

In production builds, certain keyboard shortcuts are disabled for security:

14.7 Application Lifecycle

NkapBooks follows a defined lifecycle from launch to database connection:

┌──────────────┐    ┌──────────────┐    ┌──────────────┐    ┌──────────────┐
│  App Launch  │───▶│  Config Init │───▶│  Database    │───▶│  Desk Mode   │
│              │    │              │    │  Selector    │    │              │
│  • Load Tauri│    │  • Language  │    │              │    │  • Dashboard │
│  • Init Vue  │    │  • Dark Mode │    │  OR          │    │  • Sidebar   │
│  • License   │    │  • Config    │    │              │    │  • All       │
│    Service   │    │    from Store│    │  Setup       │    │    Features  │
│              │    │              │    │  Wizard      │    │              │
└──────────────┘    └──────────────┘    └──────────────┘    └──────────────┘

Startup Sequence

1. Tauri Initialization: The Rust backend starts, creates the native window (1200×800, frameless, centered)
2. Config Loading: The app reads configuration from the Tauri Stronghold store (language, dark mode preference)
3. Language Setup: If a non-English language is configured, the translation map is loaded
4. License Initialization: The license service initializes (non-blocking, runs in background)
5. Screen Routing:
   • If no database exists → Setup Wizard
   • If databases exist → Database Selector (or auto-connect to last used database)
   • After database connection → Login (if authentication is enabled) → Desk Mode
6. Post-Connection Setup:
   • License entity tracking starts
   • Backup manager starts (checks every hour)
   • Update check is scheduled
   • Schema translations are applied

Security Features

14.8 Bundled Resources

NkapBooks ships with bundled resources that are deployed alongside the application binary:

These resources are configured in the Tauri bundle settings and are available to both the Rust backend and the frontend renderer through the asset protocol.

Summary

NkapBooks delivers a native desktop experience that's fast, secure, and works reliably with or without an internet connection. The Tauri 2 + Vue.js 3 architecture ensures small binary sizes, low resource usage, and strong security — all while providing a modern, polished user interface with dark mode, keyboard shortcuts, and multi-language support.