Maintenance & Support
How Spyrl is kept healthy after launch and how clients get help. Incident severities are defined in backup and DR; this page maps support priorities onto them.
1. Support tiers
| Tier | Who | Handles |
|---|---|---|
| L0 Self-help | Help centre, in-app guides, setup wizard tips, status page | How-to questions, known issues, statutory change notes |
| L1 Support desk | Support specialists (HR/payroll-literate) | Triage, how-to, configuration help, data fixes the tenant can do with guidance, routing |
| L2 Support engineering | Support engineers with break-glass access (administration) | Investigation in logs and traces, consented tenant sessions, import and connector problems, runbook execution |
| L3 Engineering | Module owners and on-call | Defects, performance, incidents, data repairs that need code |
| Payroll SME | Payroll specialist | Statutory interpretation, payroll variances, pack questions |
Tenant admins are the first line for their own employees: employees ask their HR, and HR contacts Spyrl. Employee-originated tickets are redirected to the tenant's HR unless the issue is account access.
2. SLAs per plan
Business hours are 09:00–19:00 IST, Monday–Saturday, excluding national holidays.
| Lite | Standard | Professional | Enterprise | |
|---|---|---|---|---|
| Channels | Email, in-app | Email, in-app, chat | Email, in-app, chat, phone (business hours) | All + named CSM + phone 24×7 for P1 |
| Coverage | Business hours | Business hours | Business hours; P1 24×7 | 24×7 for P1/P2 |
| First response P1 | 8 business hours | 4 h | 1 h | 30 min |
| First response P2 | 1 business day | 8 business hours | 4 h | 2 h |
| First response P3 | 3 business days | 2 business days | 1 business day | 8 business hours |
| Target resolution or workaround P1 | Best effort | 1 business day | 8 h | 4 h |
| Uptime commitment | 99.5% target | 99.5% target | 99.5% target (99.9% in Stage B) | 99.9% contractual with service credits (requires Stage B, architecture §10.2) |
| Payroll window priority | — | Priority queue 25th–5th | Priority queue | Dedicated contact |
| Onboarding | Self-serve | Self-serve or paid assisted | Assisted included | Implementation project |
Priorities
| Priority | Definition | Maps to |
|---|---|---|
| P1 | Production unusable for the tenant, payroll cannot be processed or paid on time, or suspected data exposure | SEV1/SEV2 |
| P2 | Major feature broken with no workaround (for example punches failing at one site, payslips not generated) | SEV2/SEV3 |
| P3 | Feature problem with a workaround; configuration question blocking a task | SEV3 |
| P4 | How-to, cosmetic, feature request | SEV4 / product backlog |
Service credits (Enterprise) are defined in the contract; a typical schedule is 5% of the monthly fee per 0.1% below the commitment, capped at 25% (proposal, commercial validation needed).
3. Ticket workflow
- Every ticket carries tenant, cell, plan, module code (ATT, PAY and so on), priority and the release version.
- Tickets touching payroll get a payroll SME reviewer before resolution.
- No sensitive data in tickets. Agents redact screenshots and spreadsheets attached by clients (PAN, bank, salary); the help desk auto-masks PAN- and Aadhaar-like patterns. Files needed for investigation go through the tenant's in-app secure upload, not ticket attachments.
- Reopened tickets return to the same agent; three reopenings escalate to the support lead.
4. Known-error and runbook management
| Artefact | Content | Where | Owner |
|---|---|---|---|
| Known-error record | Symptom, affected versions/tenants, root cause (if known), workaround, linked engineering issue, status | Help desk knowledge base, internal | Support lead |
| Public known issues | Customer-safe summary and workaround | Help centre + status page | Support lead |
| Operational runbooks | One per alert key (rb/...) and per procedure (restore, tenant move, deletion) | docs/runbooks/ in the main repository, reviewed as code | Engineering on-call owners |
| Support playbooks | Common L1/L2 procedures (import errors, device mapping, SSO setup, reset MFA with identity check) | Internal KB | Support engineering |
Rules: a known error that generates more than 5 tickets in a month gets a product fix prioritised; a runbook used in an incident is reviewed in the postmortem; runbooks unused for 6 months are validated in a game-day or deleted.
5. Dependency update policy (Renovate)
| Category | Policy |
|---|---|
| Security updates | Renovate opens immediately; fix SLAs follow the security overview (critical 48 h, high 7 days) |
| Patch and minor (npm) | Grouped weekly PR per area (backend, web, mobile, tooling); automerge for dev dependencies and patch versions when CI passes |
| Major versions | Individual PRs, scheduled; one major framework upgrade per quarter at most (for example NestJS, React, Prisma, Expo SDK) |
| Expo SDK | Follow each new SDK within 2 releases (Expo supports a limited window and stores raise target-API requirements yearly) |
| Node.js | Run an active LTS; upgrade within 6 months of a new LTS and before the current one reaches end of life |
| PostgreSQL | Minor versions via RDS auto minor upgrade in the maintenance window; major version upgrade yearly at most, rehearsed on staging, outside the payroll window (blue/green deployment where available) |
| Base images | Rebuilt weekly even without code changes so OS patches land; pinned by digest |
| Lockfiles | Committed; npm ci only; new dependencies need a short justification and a licence check (no AGPL in the server bundle without review) |
| Supply chain | Provenance and signatures on images (cosign), SBOMs kept per release, typosquat checks on new packages |
6. Deprecation policy
| Surface | Notice | Mechanism |
|---|---|---|
Public API /v1 endpoints and webhook payload versions | 6 months (12 for Enterprise if contracted) | Deprecation/Sunset headers, developer-portal notice, monthly email to clients still calling (upgrades) |
| Mobile app versions | 90-day support window; minimum version raised with 14 days' notice | In-app soft banner, then 426 |
| Product features | 3 months for features in active use; a migration path or export provided | In-app announcement, release notes, CSM outreach for affected tenants |
| Integrations / connectors | 3 months; 6 months for payroll-critical exports (bank, statutory formats remain until the portal or bank retires them) | Connector health banner and email |
| Browser support | Last 2 versions of evergreen browsers; announced annually | Help centre |
| Feature flags | Removed within 90 days of full rollout | Tech-debt ticket auto-created |
7. Documentation maintenance
Docs-as-code. This site lives in website/ in the main repository and is built in CI; broken links fail the build.
| Content | Source of truth | Rule |
|---|---|---|
| Canonical documents (summary, BRD, PRD, project plan, architecture, review, conventions, research) | Root files in the repository | Mirrored into reference/ by website/scripts/sync-docs.mjs before every build. Never edit reference/ by hand. Docs pages link to them (for example architecture, PRD) instead of copying their content |
| Module specs, operations, security, quality pages | website/docs/* | Updated in the same PR as the behaviour change; a PR template checkbox asks "docs updated?" |
| Permission matrix | packages/policy/permissions.ts | CI check compares with the RBAC matrix |
| API reference | Generated OpenAPI from packages/contracts | Never hand-written (API overview) |
| Data dictionary | Prisma schema comments (classification and purpose) | Generated (data model) |
| Runbooks | docs/runbooks/ | An alert cannot merge without its runbook |
| Decision log | ADR entries under architecture/ | A change to a canonical decision in CONVENTIONS §6 needs an ADR entry first |
Owners follow CONVENTIONS §9: Product owns product/, features/, workflows/, roadmap/; Product + Eng own modules/; Eng owns architecture/, data/, api/, integrations/; Ops owns operations/; Security owns security/; QA owns quality/. A CODEOWNERS file enforces review by the owning group. Each page is reviewed at least once per release theme (R1–R4); pages untouched for 6 months are flagged in a quarterly docs review.
8. Tech-debt budget
- 15–20% of each sprint's capacity goes to tech debt, reliability and upgrades, rising to 30% when the error budget is under 25% (observability).
- Debt is tracked as issues labelled
tech-debtwith a module code and an impact note (risk, toil hours, slowed delivery). The engineering lead ranks them monthly. - Automatic debt sources: flags past expiry, deprecated API usage by our own code, quarantined tests, Renovate major PRs older than 60 days, known errors with more than 5 tickets a month, manual steps found in DR drills.
- One "hardening week" after each major release theme (R1–R4) is reserved for debt and documentation, never scheduled in a payroll window.
9. KPIs
| Area | KPI | Target (initial) |
|---|---|---|
| Support | First-response SLA met | 95% per plan |
| Support | Resolution SLA met (P1/P2) | 90% |
| Support | CSAT | 4.5 / 5 or better |
| Support | Tickets per 100 active employees per month | Falling quarter over quarter; under 1.0 after hypercare |
| Support | Self-service deflection (KB views resolving without a ticket) | 40% |
| Reliability | SLO attainment per cell | Within targets in observability |
| Reliability | Change failure rate (releases needing rollback or a hotfix) | Under 10% |
| Reliability | MTTR for SEV1/SEV2 | Under 1 h / 4 h |
| Payroll | Payroll runs completed without a Spyrl-caused correction | 99.5% |
| Delivery | Lead time from merge to production (wave 1) | Under 7 days |
| Maintenance | Critical/high vulnerabilities past SLA | 0 |
| Maintenance | Dependencies more than one major version behind | Under 5 |
| Maintenance | Flaky-test rate in CI | Under 1% of runs |
| Docs | Pages reviewed in the last release theme | 100% of operations, security and module pages |
| Customer | Onboarding time to go-live (assisted, Standard) | 2–4 weeks |