VantaFlow SaaS Architecture

Vision

VantaFlow is a headless ERP software-as-a-service (SaaS) platform built to serve multiple business verticals via highly specialized modules (such as Commercial Garages, Manufacturing, Supply Chain, and HR).

The platform is designed with a Headless Architecture:

• Backend: Frappe / ERPNext providing robust database schema, RBAC, and background orchestration.
• Frontend: Nuxt 4 + PrimeVue delivering a blazing fast, premium, and highly interactive user experience.

---

Multi-Tenancy Strategy

Instead of grouping all tenant data into a single database with row-level security, VantaFlow uses Database-Level Isolation via Frappe's native multi-site capability.

1. The Central Control Site (admin.localhost)

This site is the "Landlord". It does not store client data. It only has the vantaflow_central app installed. It tracks:

• Tenant Sites: The clients who have signed up.
• Tenant Subscriptions: The modules (features) the client has paid for.

When a new Tenant Site is "Provisioned" via the UI button, a background python queue worker spins up and:

1. Physically creates a new MariaDB database (bench new-site).
2. Generates an encrypted database password for recovery.
3. Installs the commercial_garage (and other core apps) into that specific site.
4. Programmatically provisions the client's Administrator user.

2. Tenant Sites (e.g., client1.vantaflow.com)

These are fully isolated Frappe sites.

• They contain a single settings Doctype: VantaFlow Tenant Settings.
• During provisioning, the central orchestrator automatically syncs the modules the client has purchased (e.g., garage, etims) into this settings document.

3. The Dynamic Frontend Proxy

The Nuxt 4 frontend acts as a unified portal for all clients.

• When a user visits client1.vantaflow.com (or demo.localhost:3001), the Nuxt Nitro server intercepts the API request.
• It preserves the Host header (the subdomain) and forwards the API request to the backend Frappe server on port 8000.
• Frappe natively reads the Host header, identifies the correct client site folder, and queries the isolated database.

4. Client-Side Gating

When a client logs into the frontend:

1. A global route guard (useAuth()) hits the get_active_modules API.
2. The Frappe backend checks the VantaFlow Tenant Settings for that specific client's isolated database.
3. The frontend dynamically trims the Sidebar menu and blocks restricted URLs if the client has not paid for those modules.

---

Roadmap

Phase 1: Core Foundation (Completed)

• Set up Nuxt 4 + PrimeVue frontend.
• Scaffolding the basic Dashboard layouts (Financials, Supply Chain).

Phase 2: Multi-Tenancy & Proxy (Completed)

• Implement dynamic Host header proxying in Nuxt.
• Create VantaFlow Tenant Settings doctype and useAuth Nuxt gating logic.

Phase 3: Central SaaS Orchestrator (Completed)

• Build the vantaflow_central Frappe app.
• Implement the Tenant Site and Tenant Subscription tracking models.
• Build the background worker logic to spin up new sites dynamically.

Phase 4: Commercial Garage Module (In Progress)

• Develop the database schema (Doctypes) for Vehicles, Job Cards, and Check-ins within the commercial_garage app.
• Build the frontend Vue components to allow mechanics and advisors to interface with the garage backend.