Spyrl — Project Summary
Version: 1.0 · Date: 2026-10-31 · Audience: founders, business stakeholders, product and engineering leads Read next: brd.md (business) · prd.md (product) · architecture.md (technical) · project-plan.md (delivery) · review.md (final recommendation) · research · conventions
1. Product vision
Spyrl gives every Indian SME the attendance-to-payroll backbone that large enterprises take for granted. It is accurate, compliant and mobile-first, and it is priced and onboarded like a consumer app. One platform serves hundreds of client organisations, and any client that needs isolation can get it without a separate product.
Objectives (headline targets; the full KPIs for all ten objectives are in brd.md §2)
| # | Objective | Headline target |
|---|---|---|
| BO-01 | Fast, low-touch go-live | Trial provisioned in ≤ 2 min; median ≤ 21 days from order to first live payroll; ≤ 16 staff-hours of implementation for a tenant with ≤ 200 employees |
| BO-02 | Accurate, on-time payroll | ≤ 0.1% of payslips corrected after lock; 100% of runs done before the pay date |
| BO-03 | Adoption | ≥ 70% of employees active monthly on ESS by month 3; median approval time ≤ 24 h |
| BO-04 | Healthy unit economics | Gross margin ≥ 75% on pooled tenants; platform cost ≤ ₹8 per billed employee per month |
| BO-05 | Serve many clients with a small team | Zero tenant-specific code branches; ≥ 95% of pooled tenants on the latest version within 7 days |
| BO-06 | Statutory compliance | ≥ 98% of statutory files accepted on first upload; zero penalties caused by Spyrl |
| BO-07 – BO-10 | Growth, retention, trust with personal data, field-team productivity | 150 paying tenants by GA + 18 months; logo churn ≤ 1.5%/month; zero cross-tenant exposures; ≥ 90% of visits geo-verified (R3) |
2. Problem statement
Indian SMEs (10–1,000 employees) in manufacturing, retail, healthcare, IT services, pharma distribution and field sales run HR on a mix of biometric devices, Excel, WhatsApp and a payroll accountant. That leads to five recurring problems:
- Attendance and payroll don't reconcile. Punches from devices, phones and registers have to be cleaned by hand every month before salaries can be computed.
- The rules are complex and local. Shift and night-shift rules, sandwich leave, comp-offs, lates-to-leave deductions, extra-day pay, EPF/ESI/PT/LWF/TDS and gratuity all change by state and date.
- Field staff are invisible. Visits, kilometres and reimbursements get disputed.
- Tools are rigid or expensive. Enterprise HCMs cost too much to implement. Low-cost tools hard-code rules: the reference product fixes 10 leave types and a demo-only sales pipeline, and applies policy changes "only to new employees".
- Security is weak. Shared default passwords, credentials emailed in plaintext and undocumented permissions are common. All three were observed in the reference product (see research §21.2).
3. Target customers and users
| Segment | Size | Why they buy | Plan |
|---|---|---|---|
| Micro-business (shop, clinic, small workshop) | 5–50 | Face/selfie attendance + simple salary | Lite |
| SME with shifts (manufacturing, retail, healthcare, security services) | 50–1,000 | Shifts, rotations, attendance-to-payroll, statutory compliance | Standard / Professional |
| Field-sales SME (pharma, FMCG distribution, insurance, education) | 20–500 | Tracking, visits, pipeline, travel claims + HR | Standard + Field Force add-on |
| IT / services SME | 20–500 | Leave, payroll, timesheets, projects | Standard + Timesheets |
| Larger or regulated client (multi-entity groups, hospitals, PSU vendors) | 500–5,000 | Isolation, SSO, audit, SLA | Enterprise (dedicated cell) |
Users: owners, HR administrators and managers, finance and payroll managers, reporting managers, employees, field executives, kiosk operators, instructors and auditors. See CONVENTIONS.md §4 and the Personas & roles page of the documentation site.
4. Core modules
| Code | Module | Release | What it does |
|---|---|---|---|
| PLT | Platform & tenant administration | R0 | Provisioning, plans and entitlements, billing, feature flags, cells, support access |
| ORG | Organisation setup | R0 | Company, legal entities, locations (with employee-ID sequences and geo-fences), departments, designations, grades, holidays |
| IAM | Identity & access | R0 | Invite activation, SSO, MFA, device binding, role builder (permission × scope), audit |
| EMP | Core HR & onboarding | R1 | New hire → self-onboarding → document approval → checklists → effective-dated job records; imports |
| ATT | Attendance, shifts & time | R1 | Biometric / mobile / web / kiosk capture; shifts, rotations, week-offs; regularization, permissions, OT, extra days and penalties; period lock |
| LVE | Leave & holidays | R1 | Leave-type builder, accruals, ledger, sandwich and comp-off rules, optional holidays, cancellation approvals |
| PAY | Payroll & statutory | R1 | Structures, effective-dated compensation, run lifecycle, EPF/ESI/PT/LWF/TDS with declarations, statutory and bank files, payslips, arrears, advances |
| NTF | Notifications & workflows | R1 | Multi-level approvals, delegation, escalation; email, push, SMS and WhatsApp templates |
| RPT | Reports & dashboards | R1 | Persona dashboards, scope-aware standard reports, scheduled exports |
| MOB | Mobile app | R1–R2 | One app for ESS, MSS, field users and claims, plus a kiosk mode |
| CLM | Claims | R2 | Expense policies and limits, two-stage approval, mileage from field travel, payout through payroll |
| EXT | Exit & F&F | R2 | Resignation and termination, clearance owners, F&F computation, letters |
| ENG | Engagement | R2 | Targeted announcements, recognition |
| FFM | Field force & CRM | R3 | Consent-based tracking, geo-verified visits, configurable pipeline, payments, travel |
| TSM | Timesheets | R3 | Projects, tasks, weekly entry, approvals, effort variance |
| LMS | Learning | R4 | Mandatory and compliance courses, assessments, certificates |
5. Key features (the ones that win deals)
- Punch anywhere, reconcile once. Biometric, mobile selfie with geo-fence, kiosk and web punches all flow into one attendance engine. It handles shift rules, graces, half and full days, OT, extra days and penalties, and it locks per payroll period.
- Policies that tell the truth. Every rule is a typed setting with help text, an effective date and applicability (location, department, grade, employment type). There are no hidden "only applies to new employees" surprises.
- Payroll you can defend. Each run moves through Draft → Calculated → Reviewed → Approved → Locked → Paid, with variance checks and immutable snapshots. The ECR, ESI, PT and bank files are ready to upload. TDS uses IT declarations.
- One app for everyone. Employees, managers, field staff and the kiosk use the same app; navigation depends on role and plan.
- Field force with consent. Tracking runs only during work hours, visits are verified against the client location, and km-based travel claims flow into the same claims pipeline.
- Self-serve onboarding. A setup wizard, import templates with dry-run, and a parallel payroll run before go-live.
6. Business value proposition
| For | Value |
|---|---|
| Owners | Lower payroll cost leakage (buddy punching, OT and penalty errors), statutory peace of mind, real-time workforce visibility |
| HR & payroll | Month-end closes in hours instead of days; fewer disputes; audit-ready records |
| Managers | Approvals and shift planning on mobile in seconds |
| Employees | Transparent attendance, leave balances and payslips; quick claims |
| Spyrl (the business) | A high-retention system of record, PEPM revenue that grows with the client's headcount, add-on upsell (Field Force, Timesheets, LMS) |
7. Proposed enhancements over the reference product
The full critique is in research/spryple-analysis.md §17–§21.
| Area | Reference product (Spryple) | Spyrl |
|---|---|---|
| Configuration | 48 numbered HR rules, duplicated and not effective-dated [Observed] | Typed, versioned, effective-dated policies with applicability rules [Proposed] |
| Leave | 10 fixed types; eligibility by gender and marital status [Observed] | Leave-type builder, ledger, inclusive eligibility [Proposed] |
| Payroll | Pay groups chosen by CTC range; TDS entry is manual in the docs [Observed] | Structures + effective-dated compensation, run lifecycle, statutory and bank files, a TDS engine [Proposed] |
| Security | Default password "Welcome1!" emailed in plaintext [Observed] | Invite activation, MFA, SSO, device binding, full audit [Proposed] |
| Mobile | 4 apps (HCM, Lite, CRM, Claims) [Observed] | One app + kiosk mode; Lite becomes a plan [Proposed] |
| CRM | Fixed demo-centric stages [Observed] | Configurable pipelines, enforced geo-verification, consent and retention [Proposed] |
| Lifecycle | No F&F, letters or clearance owners documented [Observed gap] | F&F, letters, clearance workflow [Proposed] |
| Platform | — | Control plane, plans and billing, public API and webhooks, per-tenant export [Proposed] |
8. Recommended technology & architecture
Details are in architecture.md.
| Layer | Choice | Why |
|---|---|---|
| Backend | NestJS 11 modular monolith (TypeScript) with api/worker/ingest process roles | Team familiarity (qmaks), one deployable, ACID across the attendance → payroll chain |
| Database | PostgreSQL 16+ via Prisma; shared schema with tenant_id + forced Row-Level Security | Cheapest isolation that is strong enough for SMEs; defence-in-depth |
| Async | Redis + BullMQ; transactional outbox | Month-end spikes, reliable notifications |
| Web | Vite + React 19 + Tailwind 4 + shadcn/ui + TanStack Query (one SPA, role-aware) | Matches the team's lookin-hr stack |
| Mobile | Expo + Expo Router, one app, offline punch queue, kiosk mode, OTA updates | One codebase for iOS and Android |
| Storage | S3 (tenant-prefixed keys, presigned URLs, Object Lock for payroll artefacts) | Durable, cheap, auditable |
| Observability | OpenTelemetry → Grafana stack; Sentry | Tenant-tagged telemetry, SLO-gated rollouts |
| Hosting | AWS ap-south-1 (India data residency). Stage A: Dokploy on EC2 + managed RDS Multi-AZ. Stage B: ECS Fargate + Terraform | Low cost at launch, a clear path to scale |
9. Multi-client business model
- Plans: Lite, Standard, Professional and Enterprise, priced per active employee per month with a minimum fee per plan. Indicative pricing (to be validated) is ₹39 / ₹69 / ₹109 / from ₹149 PEPM; see brd.md §15.
- Add-ons: Field Force (per tracked user), Timesheets, LMS, face verification, and WhatsApp messages (metered).
- Trial → paid: a 14–30-day self-serve trial in a pooled cell, payment through Razorpay Subscriptions (UPI AutoPay, cards, e-mandate), GST invoices.
- Implementation services (optional, paid): data migration, a parallel payroll run, and biometric device setup for clients that want hand-holding.
- Enterprise: an annual contract, a dedicated cell, a custom domain, SAML, a 99.9% SLA, and a sandbox tenant.
10. Deployment & management strategy
- Hybrid cells: pooled by default, dedicated on demand. Every cell runs the same images and migrations. Cells cap the blast radius and let the platform scale by adding cells, not by re-architecting.
- A control plane owns the tenant registry, automated provisioning (a new tenant in under 2 minutes), entitlements, billing, feature flags, wave-based rollouts and audited support access.
- Operations: expand/contract migrations; a payroll-window change freeze (25th–5th); RDS point-in-time recovery with cross-region copies (RPO ≤ 5 minutes, RTO ≤ 1 hour); quarterly DR drills; 99.5% availability in Stage A and 99.9% in Stage B.
- Client onboarding: a self-serve wizard, import templates, an optional assisted migration, and a parallel payroll run before go-live.
11. Delivery at a glance
The full plan is in project-plan.md.
| Release | Scope | Indicative timing* |
|---|---|---|
| R0 Foundations | Platform, IAM, ORG, NTF core, CI/CD, observability | Months 1–2 |
| R1 MVP | EMP, ATT, LVE, PAY (India statutory incl. TDS), RPT, mobile ESS/MSS | Months 3–7 (GA at the end of month 7, after pilots) |
| R2 | Claims, Exit + F&F, Engagement, kiosk + face, device gateway, Form 16/24Q, public API | Months 8–11 |
| R3 | Field Force & CRM, Timesheets | Months 12–15 |
| R4 | LMS, advanced analytics, enterprise automation | Months 16+ |
*Assumes a core team of about 7–8 people (see the plan). The timing is an estimate to validate during R0.
12. Bottom line
Build the attend-to-pay core first and build it exceptionally well. Use a pooled multi-tenant architecture with a dedicated-cell escape hatch, and keep CRM, timesheets and LMS as add-ons after the core is proven with pilot clients. The reasoning, with the risks and the MVP cut, is in review.md.
Synced from
/summary.mdin the repository root. Edit the root file, not this page.