Internal Portal — App Overview

// No stored balance value — everything calculated at runtime:
balance = opening_balance
           + SUM(all credits on this account)
           - SUM(all debits from this account)

// Transfer = atomic pair: either both sides or neither
BEGIN TRANSACTION
  post_debit(source_account, amount)
  post_credit(target_account, amount)
COMMIT

// File stored OUTSIDE the public web directory
REQUEST: /receipts/download?id=42
  → Check session          // Is user logged in?
  → Check permission       // Does this receipt belong to the user?
  → Stream file from secured path
  // No direct URL to the file exists — bypass impossible

Sequential numbering: R-YYYY-00001, 00002, 00003 …
  // Gaps are detectable — audit trail integrity

// Open standard: CalDAV (RFC 4791) + iCalendar (RFC 5545)
Local appointment
  → iCalendar format (VEVENT)
  → HTTPS PUT → Nextcloud CalDAV endpoint
  → Nextcloud syncs further to phone, desktop …

Incoming from server:
  → HTTPS GET → parse iCalendar → update local DB

// Compatible with: macOS, iOS, Android, Thunderbird, Outlook

// Open standard: CardDAV (RFC 6352) + vCard 3.0 (RFC 6350)
Local contact (name, address, phone, e-mail …)
  → Serialise vCard: FN, ADR, TEL, EMAIL, ORG …
  → HTTPS PUT → Nextcloud CardDAV endpoint

Incoming:
  → Parse vCard → update local DB

// Customer number: assigned atomically → no duplicates possible
New customer number = MAX(existing) + 1  ← inside a transaction

// Lock is server-side — UI manipulation has no effect
EDIT REQUEST for entry dated [date]:

  days_elapsed = TODAY − ENTRY_DATE

  IF days_elapsed > 7:
    → Reject request (403)   // independent of user, independent of browser
  ELSE:
    → Editing permitted

// Inspection warning: checked daily, 60-day lead time
IF (inspection_date − TODAY) < 60 days → dashboard warning

// Rounding in favour of the employee (15-minute increments)
Arrived late → deviation is ROUNDED UP   // employee gets less minus
Left early   → deviation is ROUNDED DOWN  // employee gets less minus

// Uniform daily-target calculation for sick / holiday / public holiday:
daily_target = weekly_hours ÷ 6   // Mon–Sat, regardless of reason

// Monthly balance:
balance = (worked + holiday_hrs + sick_hrs + public_holiday_hrs)
          − (planned_working_days × daily_target)
// positive = overtime  /  negative = shortfall

// Time-based escalation — runs server-side
FOR EACH open ticket:

  hours_without_response = NOW − last_activity_timestamp

  IF hours_without_response > 72:
    → Status    → "Escalated"
    → Priority  → at least "Urgent"
    → Visibility → flagged for department management

// Internal notes are a separate data type —
// they cannot accidentally be forwarded to external parties.

// Encryption: XSalsa20-Poly1305 (libsodium) — same as Signal/WhatsApp
ENCRYPT:
  key        = Argon2id(master_password, random_salt)
               ↑ memory+CPU-intensive → brute-force economically infeasible
  nonce      = 24 random bytes (unique per entry)
  ciphertext = XSalsa20-Poly1305(plaintext, nonce, key)
  → stored: nonce ‖ ciphertext   ← only this in the DB

AFTER USE:
  key        = sodium_memzero()   ← immediately erased from RAM

// Without master password: vault content unreadable even with DB access.

// Finalisation = snapshot + number assignment in one transaction
FINALISE INVOICE:
  → Status: "Draft" → "Open"
  → Freeze customer data: copy name, address, VAT ID
    // Later address changes no longer affect this invoice
  → Assign invoice number: INV-YYYY-NNN  ← atomic, no duplicates
  → Invoice is now write-protected

// Payment received → automatically creates receipt entry
POST PAYMENT: 1 click → receipt INV-2025-042 appears in receipts

// Every incoming value passes through this chain — no exceptions:
PUBLIC FORM (no login required):

  input = { name, email, subject, description }

  → HTML escape          // prevents XSS attacks
  → Limit length          // prevents overflow attacks
  → Verify CSRF token     // prevents cross-site submissions
  → save as new ticket

ADMIN BACKEND:
  → Portal authentication required
  → only users with ticket permission

// No static HTML files — every page is assembled at runtime
REQUEST: /?lang=en&slug=about-us

  → Language from URL (de / en, default: de)
  → Load article by slug from DB
  → Load sections + columns (order from DB)
  → Per column: check type
      Text  → output HTML content of chosen language
      Image → output alt text of chosen language
      HTML  → output raw block (admin-created content only)
  → Load menu from DB → render navigation

// Change in admin → live immediately, no deployment, no cache flush

// All write operations land in an IndexedDB queue
OFFLINE:
  create/update/delete → IDB pending-store (localId, action, data)
  Note immediately visible (temporary ID, negative)

ONLINE (reconnect):
  FOR EACH pending operation (in order):
    → POST   /nextcloud/notes/api/v1/notes        (create)
    → PUT    /nextcloud/notes/api/v1/notes/{id}  (update)
    → DELETE /nextcloud/notes/api/v1/notes/{id}  (delete)
    → temporary ID → replaced by real NC ID

// iPhone sync runs in parallel via the same NC API — no extra effort

// Search runs server-side — no full list download required
REQUEST: /plu/api.php?q=apple

  → Check session         // Portal auth required
  → SQL LIKE search:
      WHERE code        LIKE '%apple%'
         OR description  LIKE '%apple%'
  → JSON response to browser

// Data synced via Nextcloud —
// changes on one device instantly visible on all others.

// All messages run exclusively through own server
CLIENT (Element app / browser):
  → HTTPS to Matrix API on own VPS
  → End-to-end encryption via Megolm (Olm/Double-Ratchet)
  → Keys stored locally only on the device

SERVER (Synapse on VPS):
  → stores only encrypted messages
  → no plaintext readable server-side
  → federates only on request with other Matrix servers

// Federation can be disabled — purely internal operation possible