Client Onboarding

This runbook implements §9 of the architecture. Provisioning is done by the control plane; this page covers what people do around it. Module behaviour referenced here (pay structures, statutory settings) is specified in the module pages, for example payroll.

Targets

Measure	Target
Self-serve trial provisioning	Under 2 minutes
First punch recorded (self-serve)	Same day
Standard-plan go-live (assisted, up to 200 employees)	2–4 weeks including one parallel payroll
Dedicated-cell provisioning	Under 1 business day, automated

1. Onboarding paths

Path	Who	Plans	Spyrl effort
Self-serve	Owner signs up on the website	Lite, Standard (trial)	None unless the client asks for help
Assisted	Implementation consultant (Spyrl or partner) with the client's HR and finance	Standard, Professional	6–20 hours per tenant, mostly data migration and the parallel run
Enterprise	Implementation lead + solutions engineer; may include a dedicated cell, SSO, custom domain, integrations	Enterprise	Project plan with milestones (project plan)

2. Self-serve runbook

Step	System behaviour	Owner action
1. Sign-up	Form collects company legal name, slug, owner name, work email, mobile, employee band, state(s). Email and mobile are verified by OTP. Slug is checked for availability and a reserved-word list	Fill in the form
2. Provision	Control plane picks the pooled cell with headroom, creates the tenant, seeds reference data (current statutory pack, leave templates, seeded roles, notification templates), creates the owner invite. Idempotent: a retry never creates a second tenant	—
3. Activate	Invite link (single use, 72 h) → set password (argon2id, breached-password check) → mandatory TOTP MFA for org_owner → recovery codes shown once	Activate
4. Sample data (optional)	A sandbox toggle loads synthetic employees, clearly labelled; one click removes them all	Explore
5. Wizard	Section 4 below. Progress shows as a go-live readiness score	Configure
6. Invite employees	After import, employees receive activation links by email, SMS or WhatsApp. No passwords are ever sent (the reference product emails a shared default password in plaintext, see research)	Choose channel and send
7. Subscribe	Before trial end, the owner picks a plan; Razorpay subscription created; tenant status → active	Pay

Automatic nudges (from the control plane): day 1 "finish company setup", day 3 "import employees", day 7 "record first punch", day 10 "run a trial payroll", day 12 "trial ends in 2 days". Customer success sees stalled tenants on the health dashboard (administration).

3. Assisted runbook

Week	Activity	Client provides	Spyrl / partner does	Exit criterion
0	Kick-off, scope, contacts, data-sharing agreement (DPA) signed	Org chart, current policies, last 3 payroll registers, statutory registrations (EPF, ESIC, PT, LWF, TAN)	Requirements checklist; maps legacy policies to Spyrl typed policies	Signed DPA and scope sheet
1	Configuration	Policy decisions	Wizard sections 1–8 with the client; records decisions in the tenant's implementation notes	Configuration review signed off by HR
1–2	Data migration	Employee master, compensation, bank, opening leave balances, YTD payroll	Runs imports in dry-run, shares error reports, commits	Zero blocking errors; reconciliation counts match
2	Attendance go-live	Device list, sites, shift rosters	Geo-fences, devices or kiosk enrolment, face enrolment consent campaign (if face add-on)	3 days of clean attendance data
3–4	Parallel payroll	Legacy payroll output for the same month	Section 6	Variance within tolerance
4	Go-live and hypercare	—	Go-live checklist; 2 weeks of priority support	Checklist complete; handover to support

Data handling during assisted onboarding. Client files are exchanged only through the in-app import area or a tenant-scoped secure upload link, never over email or chat. Consultants work in the client tenant through break-glass support access with the owner's consent (administration), so every action is audited. Local copies of client spreadsheets are prohibited.

4. Setup wizard checklist

Each item contributes to the readiness score. Items marked Blocking must be complete before the first live payroll.

#	Section	Items	Blocking
1	Company	Legal name, PAN, TAN, GSTIN (optional), registered address, logo, financial year, payroll month convention	Yes
2	Statutory registrations	EPF establishment code, ESIC employer code, PT registration per state, LWF per state, applicable statutory pack accepted	Yes (for applicable statutes)
3	Locations	Sites with address, state (drives PT/LWF), time zone, geo-fence (pin + radius), allowed networks (optional)	Yes
4	Structure	Departments, designations, grades, employment types, cost centres	Yes
5	Holidays and calendars	Holiday calendar per location, week-off patterns	Yes
6	Policies	Attendance policy (shifts, graces, half-day thresholds, lates, OT), leave policy (types, accrual, carry-forward, sandwich rule), password and session policy, approval workflows	Yes
7	Payroll	Salary structure templates, components and formulas, pay groups, payroll calendar (cut-off dates), payslip template, bank account(s) for payout, ledger mapping (if accounting export)	Yes
8	People	Employee import, reporting lines, role assignments (at least one hr_admin and one payroll_manager; segregation-of-duties check)	Yes
9	Attendance capture	Mobile punch settings, kiosk devices, biometric devices or CSV mapping, face enrolment (add-on) with consent	No
10	Notifications	Sender name, channels (email, SMS, WhatsApp), reminder schedule	No
11	Security	SSO (if plan allows), MFA for admin roles (enforced automatically), device-binding policy	No
12	Opening balances	Leave opening balances, YTD payroll (if joining mid-year), loans and advances outstanding	Yes if mid-year

5. Import templates and validation

Templates are versioned Excel workbooks (template_version in a hidden sheet). Every import runs dry-run → error report → fix → commit. Commit is idempotent: re-uploading the same file updates rows by natural key, never duplicates them. Each committed import is an audited batch that can be reverted within 7 days if no dependent records (payroll runs, approvals) exist.

Template	Natural key	Key columns
Employees	Employee code	Name, DOB, gender, joining date, mobile, work email, location, department, designation, grade, employment type, reporting manager code, PAN, UAN, ESIC IP number, Aadhaar (optional, masked on display)
Compensation	Employee code + effective date	Structure template, annual CTC, component overrides
Bank details	Employee code	Account holder, account number, IFSC, account type
Opening leave balances	Employee code + leave type + as-of date	Balance, availed YTD
YTD payroll	Employee code + month	Gross, each component, EPF, ESI, PT, TDS deducted, previous-employer income (Form 12B)
Biometric user map	Device serial + device user ID	Employee code
Holidays	Location + date	Name, type (mandatory or optional)
Attendance history (optional)	Employee code + date	Status or in/out times (for mid-month starts)

Validation rules

Format checks (blocking unless noted):

pan:            '^[A-Z]{5}[0-9]{4}[A-Z]$'      # 4th character must be P for individuals (warning if not)
ifsc:           '^[A-Z]{4}0[A-Z0-9]{6}$'
uan:            '^[0-9]{12}$'
esic_ip:        '^[0-9]{10}$'                  # verify current length rule
aadhaar:        '^[2-9][0-9]{11}$'             # plus Verhoeff checksum; stored encrypted, shown masked
mobile_in:      '^[6-9][0-9]{9}$'
email:          RFC 5322 simplified, lower-cased
account_number: '^[0-9]{9,18}$'
employee_code:  unique per tenant, 1-20 chars, letters, digits, dash, slash

Semantic checks:

Rule	Severity
Reporting manager exists in the file or in the tenant; no cycles in the hierarchy	Blocking
Joining date ≤ today + 90 days; DOB gives age ≥ 18 (age 14–17 is blocked unless the tenant confirms an adolescent-employment exception, see privacy)	Blocking
Location state exists and has a PT rule in the active statutory pack	Blocking
Duplicate PAN, UAN, Aadhaar, bank account or mobile across employees	Blocking (bank account: warning if family accounts are allowed by policy)
Compensation total equals sum of components within ₹1 rounding	Blocking
EPF wages above the wage ceiling without a "contribute on full wages" flag	Warning
Gross above the ESI ceiling with an ESIC IP number present	Warning
Opening leave balance exceeds the policy's maximum carry-forward	Warning
YTD TDS inconsistent with YTD income (projected tax differs by more than 20%)	Warning

The error report returns the original workbook with an added "Errors" column per row and a summary sheet, so HR fixes errors in the file they know.

6. Parallel payroll run

Run Spyrl payroll for one month alongside the legacy system, using the same attendance and inputs, without paying from Spyrl.

1. Lock attendance for the month in Spyrl after HR review.
2. Enter the same variable inputs (bonuses, arrears, deductions) as legacy.
3. Calculate the run in Spyrl as a draft, which is never locked or paid.
4. Import or paste the legacy payroll register into the comparison tool: it matches by employee code and compares gross, each statutory deduction, TDS and net.
5. Investigate every variance above tolerance and classify it as legacy error, configuration error (fix in Spyrl, recalculate) or accepted difference (documented, for example rounding policy).
6. Repeat until within tolerance; HR and finance sign off in the app.

Field	Tolerance
Net pay	₹0 for at least 98% of employees; remaining differences fully explained
EPF, ESI, PT, LWF	₹0 (rounding rules must match the statute, not the legacy tool)
TDS	₹10 per employee per month, or explained by a declaration difference
Headcount and payable days	Exact match

For a large or complex tenant, run two parallel months, one of which includes a joiner, a leaver and an arrear.

7. Go-live checklist

• All blocking wizard items complete; readiness score 100% on blocking items.
• Parallel payroll signed off by HR and finance.
• Statutory file test: ECR and ESIC files generated from the parallel run validate against the portal's checker or format (no upload of test data).
• Bank file test: one file shared with the client's bank relationship manager, accepted format confirmed.
• At least two people hold payroll roles, with segregation of duties satisfied (preparer is not the approver).
• MFA active for every admin role holder.
• Employees invited; activation rate above 80% (shop-floor sites may rely on kiosk instead).
• Consent campaign complete for face and location features if enabled.
• Support contacts and escalation path shared; hypercare start and end dates set.
• Trial → active (subscription live) and metering confirmed in the control plane.

8. Dedicated-cell provisioning

Used for Enterprise contracts (architecture §3.2). Fully automated through the control plane once approved.

1. Commercial approval recorded on the tenant (isolation model C or D, region ap-south-1, maintenance window, optional customer-managed KMS key).
2. Create cell in the control plane: generates the Terraform variables for the cell module (deployment) and opens a PR in infra/ for review by a second engineer.
3. Apply through the pipeline: RDS (and, for model D, the VPC and app tier) created; secrets registered; alarms and dashboards created.
4. Migrate the empty database to the current production version (the cell joins wave 2).
5. Provision tenant into the new cell (same seed steps as pooled).
6. Register the cell in the cell map; routing rule added for the tenant host and custom domain.
7. Verify: synthetic checks green, backup job ran, cross-region copy present, isolation check passes.
8. If the tenant is moving from a pooled cell (for example a trial that became Enterprise): run the tenant mobility export/import (logical copy by tenant_id), verify row counts and checksums per table, freeze writes (maintenance banner, under 30 minutes for typical SMEs), final delta, switch routing, unfreeze, keep the pooled copy read-only for 7 days, then purge it.

9. Custom domain setup (Enterprise)

1. The tenant admin enters hr.client.com in Settings → Domain.
2. Spyrl shows two DNS records to create: a TXT _spyrl-verify.hr.client.com record with a token, and a CNAME hr.client.com → <slug>.cname.spyrl.app.
3. The control plane polls DNS (every 5 minutes for 72 hours). On verification it requests a certificate (ACM DNS-validated certificate attached to the ALB/CloudFront with SNI, or on-demand TLS in Stage A if ACM quotas are a concern) and adds the host routing rule.
4. Spyrl sends a confirmation; <slug>.spyrl.app keeps working and redirects to the custom domain if the tenant chooses.
5. Email sender: optionally verify the client domain in SES (DKIM CNAMEs) so notifications come from hr@client.com.
6. Certificate renewal is automatic; if the CNAME is removed, renewal fails, the admin is warned 30 days ahead, and traffic falls back to the Spyrl subdomain.

Mobile users keep using the company code; custom domains affect web only.

10. Offboarding, data export and deletion

Stage	Trigger	Access	Duration
Notice	Cancellation request or non-renewal	Full	Until end of paid term
Export window	Term ends	Read-only; exports allowed	30 days (contract may extend to 90)
Suspended	Export window ends	No user access; data intact	30 days grace (for reactivation)
Deletion	Grace ends, or immediate on written request after export	—	Deletion completes within 30 days

Runbook

1. Owner (or plt.data_export.request holder) requests full export: CSV and JSON per entity, all documents and payslips as a zip, audit log export, with a manifest and SHA-256 checksums. Delivered as a time-limited encrypted download link (7 days) to the owner, with a password sent by a separate channel.
2. The owner confirms receipt in the app (or 30 days pass).
3. Spyrl checks for legal holds (a dispute, a regulator request). A hold stops deletion for the held data only.
4. Deletion job (per cell): deletes tenant rows from every tenant-owned table (verified by the RLS coverage list, so no table is missed), deletes the S3 prefix t/<tenant_id>/ including object versions (Object Lock compliance-mode payroll artefacts are deleted when their lock expires; their existence is stated in the certificate), destroys the tenant's data key in KMS (crypto-shredding of envelope-encrypted fields), and removes cache and search entries.
5. Backups: tenant data in backups ages out with the 35-day PITR window and snapshot retention. We do not edit backups; the deletion certificate states the date by which backups no longer contain the data.
6. Control plane retains the tenant record (name, dates, invoices) for statutory accounting retention; personal data of tenant users is anonymised there.
7. A deletion certificate (PDF, signed) is issued to the owner listing what was deleted, when, and the backup age-out date.
8. Dedicated cells: the Terraform workspace is destroyed after the final snapshot ages out or is deleted per contract.

Statutory retention (payroll records for 8 years) is the client's responsibility after export, because the client is the data fiduciary and employer. The offboarding email says so explicitly (privacy).