System design & architecture
One Laravel application serves the public website, the superadmin panel and every customer company's own workspace. This page explains the parts, how data is kept separate, how an inspection moves from purchase order to release note, and how the service is billed and secured.
1
code base for every host
6
user roles, least privilege
7
inspection stage states
0
passwords stored
01 · Overview
TPI ERP runs the day-to-day work of a third party inspection agency: vendor purchase orders and their items, inspection stages, inspector visits, site reports with photos, technical review, the Inspection Report (IR) number and the Inspection Release Note (IRN). Customers can follow their own orders, and the agency is told by email at every step.
Design goals
Technology
Quality
02 · System context
The host name in the browser decides what the application shows. All addresses point at the same installation.
03 · Components
A classic layered Laravel design. Business rules sit in small support classes that can be tested on their own, controllers stay thin, and everything slow (email) goes through the queue.
Presentation
Blade views
Server-rendered pages, A4 print layouts for IR / IRN
Tailwind + Alpine
Loaded from CDN, mobile-first, no npm build
Branded emails
Shared layout, journey tracker, buttons
Public website
Landing, pricing, sign-up, this page
HTTP layer
ResolveTenant
Runs first: host → portal or workspace
SaasOnly / TenantOnly
Wrong host gets 404, never a login page
auth · active
Signed in and still active
subscription
Past due banner, suspended = read-only
Application
Masters
Clients, vendors, units, stages
Vendor POs & items
PO no., control no., stages, files
Assignments & reports
Visits, photos, review, IR / IRN
Portal, reports, settings
Customer view, CSV export, activity log
Domain services
StageStatus
Stage state machine and labels
Sequences
Yearly counters for TPI / CN / IR / IRN numbers
TenantManager · Provisioner
Switch database, files, mail; create workspaces
Billing · Limits
Invoices, GST, life cycle; plan limits
Infrastructure
MySQL connections
central + tenant
Private disk
storage/app/private
Database queue
jobs table per workspace
Scheduler
one cron line drives all
04 · Request lifecycle
Example: an inspector opens acme-tpierp.namisite.com/my-inspections.
Host lookup
ResolveTenant finds the workspace by its address (or custom domain). Unknown → "workspace not found"; closed → 403.
Switch context
The tenant connection, table prefix, file folder, app URL, company name and mail sender are set for this request only.
Host guard
Workspace routes refuse portal hosts and the other way round, before any login check.
Sign-in check
Session cookie for this workspace; user must be active (and its client active for customers).
Subscription
Trial / active pass. Past due shows a banner. Suspended allows reading and printing only.
Controller
Role check, query scoped to the user (own visits, own client), view rendered, action logged.
05 · Multi-tenancy
One installation, many companies. Isolation is done at the data layer, not with a "company id" on every row, so a missed filter in one screen can never show another company's data.
| What | How it is kept separate |
|---|---|
| Database tables | Own prefix (t12_vendor_pos…) in the shared tenant database, or a dedicated database |
| Files & photos | Own private folder workspaces/{name}, served only after a permission check |
| Logins & sessions | Own users, sign-in codes and session table; cookies are per host |
| Queue & emails | Own jobs table; emails go out under the company's own name |
| Settings & numbers | Own number formats, counters, company details and mail settings |
| Central data | Plans, workspaces, invoices, payments live only in saas_* tables, never visible inside a workspace |
Provisioning a new workspace
Schema changes reach every workspace with one command (tenants:migrate); any artisan command can run per workspace.
06 · Inspection workflow
Each inspection stage of each item moves through a small state machine. Quantities are tracked per stage, so part of a lot can be approved while the balance is inspected again.
Numbers
PO TPI/{FY}/{SEQ}, item CN-{SEQ}, IR/{FY}/{SEQ}, IRN/{FY}/{SEQ}. FY is the Indian financial year; counters restart each April and are issued inside a database transaction, so two people never get the same number.
Quantity rules
Item quantities are checked against the PO. Each visit offers a quantity; the report splits it into accepted and rejected. A stage is complete when the approved quantity reaches the stage total.
Documents
PO files, stage control files and site photos are private. IR and IRN print as A4 pages (print or save as PDF) for staff and for the customer.
07 · Roles & access
| Action | Admin | Coordinator | Technical head | Inspector | Viewer | Customer |
|---|---|---|---|---|---|---|
| Masters, staff, settings | ✓ | · | · | · | · | · |
| Create vendor POs and items | ✓ | · | · | · | · | · |
| Assign inspectors, upload control files | ✓ | ✓ | · | · | · | · |
| Submit inspection reports | · | · | · | ✓own visits | · | · |
| Approve / hold / reject, IR and IRN | ✓ | · | ✓ | · | · | · |
| See POs, reports, export | ✓ | ✓ | ✓ | · | ✓ | · |
| Own client's orders, IR / IRN | · | · | · | · | · | ✓read-only |
| Subscription page | ✓ | · | · | · | · | · |
Superadmins are a separate kind of account with their own sign-in, guard and session table; they manage workspaces from the outside and have no login inside a customer's workspace.
08 · Email flows
Every email is queued (the page answers at once) and sent by the scheduler within about a minute. Workflow emails share one branded layout with a five-step journey tracker and one clear button.
Inside a workspace
| Visit assigned or changed | Inspector (cc coordinator) |
| Report submitted / resubmitted | All active technical heads |
| Approved with IR no. | Inspector (cc coordinator) |
| On hold, with reason | Inspector (cc coordinator) |
| Rejected, with next step | Inspector (cc coordinator) |
| IRN released | Inspector, coordinator, client's customer logins |
| Sign-in code | The person signing in |
| Welcome | New staff or customer login |
From the service
| Sign-up verification code | The person signing up |
| Workspace ready | The new workspace admin |
| Tax invoice issued / reminder | Workspace billing contact |
| Payment received | Workspace billing contact |
| Demo / contact / plan-change enquiry | All superadmins |
| Superadmin sign-in code | The superadmin |
Customer copies show only their PO, item, stage and IR / IRN numbers, never internal remarks. Each workspace can switch workflow emails and the customer IRN email on or off, and preview every email with sample data.
09 · Subscriptions & billing
A daily job (saas:billing, 9 AM IST) issues invoices and moves workspaces between states. Payments are recorded by the superadmin; nothing is charged automatically and data is never deleted for non-payment.
Invoices
Renewal invoice 7 days before the period ends. GST 18%: CGST + SGST inside the seller's state, IGST otherwise. Numbered per financial year.
Plan limits
Checked inside the workspace at the moment of use: active staff, active customer logins, POs per month, file storage, and features such as the customer portal, export and workflow emails.
Commercial terms
A one-time setup fee of ₹10,000 is charged extra on any plan and is non-refundable. The minimum subscription period on any plan is 6 months. Any specific add-ins for modules, changes, or AI model adoption are charged extra, and are implemented on the basis of a shared proposal and a signed agreement.
10 · Security
🔑
Passwordless sign-in
A 6-digit code by email: stored hashed, valid 10 minutes, single use, 5 tries, 5 sends an hour. Same reply whether or not the email exists, so accounts cannot be discovered.
🧱
Tenant isolation
Separate tables or database, file folder, sessions and queue per workspace. The host decides the workspace before any code reads data.
👤
Least privilege
Six roles checked on every action. Inspectors see only their own visits; customers only their own client's orders, never vendor PO files or review notes.
📁
Private files
Uploads live outside the public web folder and are streamed only after a permission check. Size and type are limited.
🛡️
Web protections
HTTPS everywhere, CSRF tokens on every form, escaped output, validated input, rate limits on sign-in, sign-up and enquiry forms, a honeypot against form spam.
🧾
Audit trail
Activity log of who did what and from which IP; superadmin actions on workspaces are recorded as workspace history.
🚫
Inactive means blocked
Deactivating a user, or a client, ends access at the next request. Imported legacy accounts start inactive.
🔒
Separate admin plane
Superadmins use their own guard, OTP table, session table and cookie, on their own host.
🕒
Consistent time
Times stored in UTC and shown in India time; financial-year numbering follows Indian rules.
11 · Scaling & roadmap
The design starts small on purpose and has clear next steps that do not change the core.
| When needed | Step |
|---|---|
| Large customer | Move the workspace to a dedicated database (already supported per workspace) |
| Online payments | Payment gateway (e.g. Razorpay) for invoices and auto-renewal |
| Many workspaces | Wildcard DNS and SSL, Redis for queue and cache, a VPS or container host |
| Lots of photos | Object storage (S3-compatible) behind the same private-file checks |
| Self-service plan changes | Upgrade / downgrade from the Subscription page with pro-rated invoices |
| Integrations | Read-only API for customers' ERPs; AI-assisted report checks on request |
See it working
Open the live demo, or start a free 14-day trial with your own workspace.
