1. Architecture & Overview

1.1 What is Quantyx?

Quantyx Solutions is a multi-tenant SaaS administration platform built on the Base44 backend-as-a-service. It serves as a single command center for an operator managing multiple SaaS products — onboarding subscriber organisations, tracking subscriptions and billing, running a support ticketing desk with OTP-gated account access, publishing a token-gated Knowledge Base, monitoring customer health and revenue, and maintaining GDPR / compliance posture.

The application exposes two distinct surfaces:

• Admin Portal — the authenticated staff workspace (sidebar + topbar shell). Access is controlled by Base44 Auth plus a TeamMember record with granular per-product, per-module permissions.
• Client Portal — a token-based, public surface (/portal/*) where client organisations view their tickets, reply to agents, complete onboarding, and set passwords. No Base44 login is required; sessions are issued via ClientPortalSession magic links.

1.2 Technology Stack

1.3 High-Level Architecture

┌─────────────────────────────────────────────────────────────────┐
│  src/App.jsx  —  AuthProvider → QueryClientProvider → Router      │
│     └─ AuthenticatedApp                                            │
│          ├─ Public routes:  /portal/*  and  /kb/:productId          │
│          └─ <AppLayout>  (admin shell, wraps protected routes)      │
│               ├─ AppProviders  (user, products, notifications,     │
│               │                  PermissionsProvider)              │
│               ├─ Sidebar   (product switcher + nav, permission-filtered) │
│               ├─ TopBar     (search, notifications, profile)       │
│               └─ <Outlet/>  → routed page                            │
└─────────────────────────────────────────────────────────────────┘
                         │
        ┌────────────────┴───────────────────┐
        ▼                                     ▼
  Base44 SDK (client)                   Backend Functions (Deno)
  base44.entities.<Name>.{list,         base44/functions/<name>/entry.ts
    filter,get,create,update,delete}    — invoked via base44.functions.invoke()
  base44.auth.{me,logout,...}           — or via external HTTP (webhooks)

1.4 Navigation Structure (Sidebar)

The sidebar (src/components/layout/Sidebar.jsx) renders a permission-filtered list of nav items. Each item declares a module gate checked against the current user's TeamMember permission sets.

1.5 Authentication & Permissions Model

Authentication is owned by the Base44 platform (tokens, sessions, email verification). The app never implements its own auth backend.

• base44.auth.me() returns the current platform user; base44.auth.logout() ends the session.
• Every authenticated admin user is mapped to a TeamMember record (matched by user_id, status active).
• Platform users with role === 'admin' are treated as super admins even without a TeamMember record.
• Users with no active TeamMember record hit an AccessPendingScreen (see AppLayout).

Permissions are resolved in src/lib/PermissionsContext.jsx and exposed via usePermissions():

• Module access — each permission set declares a level (none | read | write | admin) per module: dashboard, organisations, tickets, payments, otp_access, settings, knowledge_base. The highest level across all sets wins.
• Organisation scoping — accessible_organisation_ids restricts which client orgs a user can see (empty = all).
• Settings scoping — accessible_settings_sections restricts which Settings tabs are visible.

Enforcement happens in two places:

• Frontend — PermissionGuard wraps routes; canAccessModule/canAccessOrganisation filter data and UI.
• Backend — sensitive functions (e.g. initiateOnboarding, generateInvoice) re-check the TeamMember permission level before acting, so a crafted client request cannot bypass the gate.

1.6 Design System

Design tokens live in src/index.css (:root light + .dark) and are mapped to Tailwind in tailwind.config.js. The palette is a polished slate/indigo light theme. Key tokens: --primary (indigo), --success, --warning, --destructive, plus sidebar-specific tokens. The font is Inter. StatusBadge (src/components/ui/StatusBadge.jsx) centralises all status pill styling across org/ticket/payment/onboarding/health/sentiment statuses.

2. Data Model

All data is stored as Base44 entities (JSON schemas in base44/entities/*.jsonc). Every record automatically includes id, created_date, updated_date, and created_by_id — these are not redeclared in the schemas below. Entities are accessed client-side via base44.entities.<Name> and server-side via base44.asServiceRole.entities.<Name>.

2.1 Core / Platform

User base44/entities/User.jsonc

Built-in. Read-only: id, created_date, full_name, email. Editable: role (admin | user). Platform admins (role='admin') are super admins. User records cannot be created/imported — users join via base44.users.inviteUser(email, role).

TeamMember base44/entities/TeamMember.jsonc

Maps a platform User to an internal staff member with a role template and per-product permission sets. The central record for all access control.

Each permission_sets[] entry:

SaasProduct base44/entities/SaasProduct.jsonc

Represents one of the SaaS products the operator manages. Carries billing config, OTP config, and KB secret.

CompanyProfile base44/entities/CompanyProfile.jsonc

The operator's own company details — used for invoice branding, bank details, portal link origin, and sidebar logo.

SubscriptionPlan base44/entities/SubscriptionPlan.jsonc

A pricing tier for a product. Supports flat and metered billing models.

2.2 Tenancy & Onboarding

Organisation base44/entities/Organisation.jsonc

A subscriber organisation on a product. The central tenancy record — most other entities reference it.

ClientUser base44/entities/ClientUser.jsonc

A user within a client organisation who can access the Client Portal. Passwords are SHA-256 hashed (salt = user id).

ClientPortalSession base44/entities/ClientPortalSession.jsonc

Token-based session for the Client Portal. Issued via magic link or password login; no Base44 auth required.

OnboardingWorkflow base44/entities/OnboardingWorkflow.jsonc

Tracks an organisation through the 8-stage onboarding lifecycle from prospect to active.

2.3 Support

Ticket base44/entities/Ticket.jsonc

TicketMessage base44/entities/TicketMessage.jsonc

OtpSession base44/entities/OtpSession.jsonc

Time-limited OTP exchange letting a support agent request, and a client approve, temporary account access.

SlaPolicy base44/entities/SlaPolicy.jsonc

2.4 Billing & Revenue

Payment base44/entities/Payment.jsonc

CreditNote base44/entities/CreditNote.jsonc

PaymentGateway base44/entities/PaymentGateway.jsonc

Configurable additional gateways (PayPal, Square, Adyen, etc.) managed in Settings → OTP & Payment Config.

DunningPolicy base44/entities/DunningPolicy.jsonc

UsageRecord base44/entities/UsageRecord.jsonc

Usage metrics for metered billing plans, reported via the reportUsage function.

2.5 Compliance & Audit

GdprRequest base44/entities/GdprRequest.jsonc

TaxValidation base44/entities/TaxValidation.jsonc

Immutable audit record of each VAT validation (VIES or manual).

ComplianceCert base44/entities/ComplianceCert.jsonc

AuditLog base44/entities/AuditLog.jsonc

Append-only event log. Written by backend functions for every significant action.

2.6 Security / Encryption

EncryptedData base44/entities/EncryptedData.jsonc

Stores AES-256-GCM ciphertext plus IV, salt, auth tag. Created by encryptData, decrypted by decryptData.

EncryptedDataKey base44/entities/EncryptedDataKey.jsonc

Per-org, per-key-type encryption key record. Keys are derived from ENCRYPTION_MASTER_KEY via scrypt/PBKDF2.

2.7 Knowledge Base

KbCategory base44/entities/KbCategory.jsonc

KbTopic base44/entities/KbTopic.jsonc

KbVersion base44/entities/KbVersion.jsonc

Immutable snapshot of a topic each time it is published — enables version history.

2.8 CRM & Notifications

OrganisationInteraction base44/entities/OrganisationInteraction.jsonc

SurveyResponse base44/entities/SurveyResponse.jsonc

Notification base44/entities/Notification.jsonc

Document base44/entities/Document.jsonc

3. Backend Functions

Backend functions live in base44/functions/<name>/entry.ts and run on the Deno runtime. They are invoked from the client via base44.functions.invoke('name', payload) or reached externally over HTTP (e.g. Stripe webhooks). Each function creates a client with createClientFromRequest(req), authenticates via base44.auth.me() (except public endpoints), and uses base44.asServiceRole to bypass user context where needed.

3.1 Onboarding Lifecycle

3.2 Billing & Payments

stripeWebhook event handling

switch (event.type) {
  case 'invoice.payment_succeeded':  // Payment → paid, store payment_date + intent/invoice ids
  case 'invoice.payment_failed':     // Payment → failed, retry_count++, next_retry_date = +3 days
  case 'customer.subscription.updated': // map {active:paid, past_due:pending, unpaid:pending,
                                        //      canceled:refunded, incomplete:pending}
}

3.3 Tax

3.4 Support & Tickets

3.5 Client Portal

3.6 Organisation & Customer Health

3.7 Knowledge Base

3.8 Security & System

3.9 Function Invocation Patterns

From the client (admin)

const res = await base44.functions.invoke('validateVatNumber', {
  organisation_id, vat_number, country_code
});
// res.data holds the JSON response

From a backend function (service role)

await base44.asServiceRole.functions.invoke('generateInvoice', { payment_id: payment.id });

External HTTP (Stripe webhook)

Register in Stripe at https://quantyxsolutions.base44.app/functions/stripeWebhook, subscribing to invoice.payment_succeeded, invoice.payment_failed, customer.subscription.updated.

4. Frontend & Routing

The frontend is a React SPA. src/App.jsx is the router and hosts all platform wrappers (AuthProvider, QueryClientProvider, BrowserRouter, Toaster). Routes are split into public Client Portal routes and authenticated admin routes wrapped by <AppLayout>.

4.1 Route Map

4.2 Application Shell

4.3 Key Pages

4.4 Component Catalog

4.5 State & Data Fetching

• AppContext (in AppLayout) — current user, products list, current product, unread notification count.
• PermissionsContext — resolved permissions, canAccessModule, canAccessOrganisation, canAccessSettingsSection, getModuleLevel.
• AuthContext — auth loading/error states, login redirect.
• Entities are read with base44.entities.<Name>.list/filter/get; realtime via .subscribe() (used for notifications and ticket messages).
• @tanstack/react-query is available for query caching; most pages use local state + direct SDK calls.

5. Automations

Automations run backend functions automatically — on a schedule, on entity record changes, or on connector webhook events. They are managed via the Base44 dashboard or the automation tools. The app currently runs seven active automations.

5.1 Scheduled Automations

5.2 Entity-Triggered Automations

6. Integrations & Environment

6.1 Core Integrations (built-in)

Always available via base44.integrations.Core.<Endpoint>:

6.2 Stripe (Payments)

Stripe is the primary payment gateway, accessed through the shared base44/shared/paymentGateway.tsabstraction (createCustomer, createSubscription, calculateTax,formatCurrency). The stripeWebhook function receives Stripe events over HTTP.

Stripe setup steps

• Set STRIPE_SECRET_KEY and STRIPE_WEBHOOK_SECRET as environment variables (Base44 dashboard → Settings → Environment Variables).
• Register the webhook endpoint in Stripe at https://quantyxsolutions.base44.app/functions/stripeWebhook.
• Subscribe to invoice.payment_succeeded, invoice.payment_failed, customer.subscription.updated.
• Use sk_test_... keys for development, sk_live_... for production; re-register the webhook per environment.

Optional stripe_tax_enabled on each SaasProduct enables automatic VAT/GST via Stripe Tax; plan tax_code maps to Stripe Tax product tax codes.

6.3 EU VIES (VAT Validation)

The validateVatNumber function calls the EU VIES REST API (ec.europa.eu/taxation_customs/vies/rest-api/check-vat-number) for EU member states, falling back to a format check for non-EU or unreachable VIES. Results are stored in TaxValidation and reflected on the Organisation.

6.4 Environment Variables / Secrets

6.5 Available App Connectors (not yet connected)

The platform supports OAuth connectors (Google Workspace, Slack, GitHub, Salesforce, HubSpot, Notion, Jira, Linear, etc.) but none are currently authorized. When needed, use get_connectors_info → request_oauth_authorization (shared) or register_workspace_connector (app-user/BYO).

7. Security & Compliance

Quantyx is designed to handle sensitive client organisational data and support regulated SaaS products. This section documents the full compliance posture across access control, encryption, GDPR, OTP-gated access, audit logging, and data classification.

7.1 Authentication & Session Security

• Admin Portal — Base44-owned auth (token-based sessions, email verification). The app never implements its own auth backend.
• Idle timeout — useIdleTimeout warns at 25 min and force-logs-out at 30 min (SessionTimeoutWarning).
• Client Portal — token-based sessions (ClientPortalSession): 8h for password login, 24h for magic link, 7h for legacy createPortalSession. Sessions carry an IP address and can be revoked.
• Client passwords — SHA-256 hashed with a per-user salt (user id); stored in ClientUser.password_hash. has_set_password gates login.
• Suspended/churned orgs — portal login and session creation are blocked for suspended/churned organisations.

7.2 Role-Based Access Control (RBAC)

Access is enforced in two layers — frontend gates and backend re-checks — so a crafted client request cannot bypass permissions.

Permission model

• Each staff user maps to a TeamMember with a role_template (super_admin, support_agent, finance, custom) and one or more permission_sets.
• Each permission set grants a level (none | read | write | admin) per module: dashboard, organisations, tickets, payments, otp_access, settings, knowledge_base. The highest level across sets wins.
• accessible_organisation_ids scopes which client orgs a user can see (empty = all).
• accessible_settings_sections scopes which Settings tabs are visible (empty = all).
• Platform users with role='admin' are super admins (bypass all gates).

Enforcement points

7.3 Data Encryption at Rest

Sensitive client data is encrypted with AES-256-GCM (authenticated encryption) via the encryptData/decryptData functions.

• Key derivation — a 256-bit key is derived per organisation + key-type from ENCRYPTION_MASTER_KEY using scrypt (encryptData) / PBKDF2 with 100,000 iterations and SHA-256 (decryptData).
• Key records — EncryptedDataKey tracks per-org keys (status active/revoked, key_version, last_rotated_at) for key rotation.
• Ciphertext record — EncryptedData stores encrypted_data (hex), iv, salt, auth_tag, key_version, plus an access_count and back-reference to the source entity.
• Integrity — the GCM auth tag is verified on decryption, detecting any tampering.
• Flagging — Ticket.is_encrypted and Payment.is_encrypted mark records whose sensitive payload is encrypted.

7.4 GDPR & Data Subject Rights

The GdprRequest entity tracks data-subject requests with a statutory 30-day response deadline.

• Each request has a status workflow (received → in_review → in_progress → completed/rejected), an assignee, a due_date (30 days), and resolution_notes.
• The GdprRequests admin page surfaces overdue and imminent-deadline requests.
• Organisation.data_classification (standard | sensitive | restricted) flags the sensitivity of stored data to prioritise handling.

7.5 OTP-Gated Account Access

Support agents can request temporary access to a client's account via a time-limited OTP exchange — the client must explicitly approve.

Agent (in TicketDetail) → requestScreenShareAccess
   creates OtpSession (status=pending), generates otp_code
   → notifyOTPRequest emails code to client contact
Client (via portal/email) → verifyScreenShareOTP
   verifies code → OtpSession status=active
   session window = product.otp_session_duration_minutes (default 30)
Expiry → status=expired (end_reason=timeout)
Agent/manual revoke → status=revoked

• OTP expiry: SaasProduct.otp_expiry_minutes (default 15) — how long the code is valid.
• Session duration: SaasProduct.otp_session_duration_minutes (default 30) — how long access stays active after approval.
• Verification channel (email | in_app | both) and IP address are recorded for audit.
• Every OTP event is written to AuditLog.

7.6 Audit Logging

The AuditLog entity is an append-only event trail. Backend functions write to it for every significant action.

Examples of audited events: onboarding initiation, VAT validation, payment setup completion, payment overdue marking, invoice generation.

7.7 Compliance Certifications

The ComplianceCert entity tracks each product's certification posture: soc2_type1/type2, iso27001/27017/27018, gdpr, hipaa, pci_dss, fedramp, with status (active | in_progress | expired | not_started), issuer, validity window, and document URL. Managed in Settings → Compliance.

7.8 Knowledge Base Access Control

End-user KB access is token-gated. The getKbContent public endpoint verifies an HMAC token signed with the product's kb_secret, ensuring only authenticated, active users of a product can read its KB. generateKbToken (admin-only) mints test tokens. KB topic edits are versioned via KbVersion snapshots on publish.

7.9 Data Classification Summary

8. Deployment & Operations

8.1 Published Application

The app is published at https://quantyxsolutions.base44.app. For external webhook URLs (e.g. Stripe), use https://quantyxsolutions.base44.app/functions/<functionName>. From inside app code, invoke functions through the SDK (base44.functions.invoke(...)), not an absolute URL.

8.2 Custom Domain

A custom domain can be connected for the public-facing surfaces. The clientPortalAuth function derives the portal magic-link origin from CompanyProfile.website (falling back to the platform domain), so updating the website field in Settings → Company Profile updates the magic-link base URL. For links a user clicks in the UI, prefer the connected custom domain.

8.3 Local Development

# install dependencies
npm install

# run the dev server (Vite)
npm run dev

# build for production
npm run build

The project is Vite + React (ESM). Use @/ import aliases. Backend functions run on the Deno runtime and are edited in base44/functions/*/entry.ts.

8.4 Environment Setup Checklist

8.5 Operational Automations (always-on)

• calculateOrgHealth — daily 02:00 — keeps health scores fresh.
• checkOverduePayments — daily 09:00 — flags overdue invoices.
• sendInvoiceReminder — daily 08:00 — 15-day pre-due reminders.
• Entity automations fire on Ticket create/update and Payment update (see §5).

8.6 Monitoring & Maintenance

• Audit trail — query AuditLog for any action's actor, time, and metadata.
• Notifications — the in-app bell + Notifications page surface system and finance alerts; unread count is realtime-subscribed in AppProviders.
• Automation health — check last_run_status and consecutive_failures via the automations tools.
• Key rotation — rotate ENCRYPTION_MASTER_KEY with overlap; EncryptedDataKey.key_version supports versioned decryption.

8.7 Extending the App

• New entity — add base44/entities/<Name>.jsonc (full JSON schema, no placeholders); access via base44.entities.<Name>.
• New backend function — add base44/functions/<name>/entry.ts; reuse shared logic in base44/shared/; test with test_backend_function.
• New page — add src/pages/<Name>.jsx, import + add a <Route> in src/App.jsx, and a sidebar nav item in Sidebar.jsx.
• New automation — use create_automation (scheduled / entity / connector).
• New connector — get_connectors_info → authorize or register, then build connector-backed features.

8.8 Known Limitations & Future Hardening

• RLS is application-layer only; add DB-level RLS rules if regulatory requirements demand enforced row isolation.
• Encryption keys are derived on demand from the master secret; wrap derived keys with a KMS-managed master key for full production hardening.
• Stripe is the only connected payment processor; additional gateways are configurable via PaymentGateway records and the testGateway function.
• No OAuth connectors are connected yet; the platform supports them when needed.