Spyrl — Final Review & Recommendations (Phase 6)
Version: 1.0 · Date: 2026-10-31 · Reviewer stance: critical, independent of the authors of each document Reviewed: summary.md · brd.md · prd.md · project-plan.md · architecture.md · CONVENTIONS.md · research/spryple-analysis.md · the Docusaurus site (
website/docs/, 52 authored pages)
1. What was reviewed and how
| Artefact | Size | Content |
|---|---|---|
| Research | ~80 KB | 43 Help Center pages read; six parallel screenshot-review agents; module-by-module analysis, critique, 16 documentation defects, gap list, feature disposition |
| summary.md | ~14 KB | Vision, problem, customers, modules, value, enhancements, architecture, business model |
| brd.md | ~92 KB | 10 business objectives, 125 business requirements, 94 business rules, 8 workflows, 28 reports, compliance, commercial model |
| prd.md | ~298 KB | 16 module specifications, 342 functional requirements, 89 user stories with acceptance criteria, 73 NFRs, permissions, UX, integrations, notification and report catalogues |
| project-plan.md | ~24 KB | Phases, ~50 epics, critical path, 12 milestones, 18 risks, test and release strategy |
| architecture.md | ~38 KB | 14 ADRs: tenancy, cells, control plane, hosting comparison, CI/CD, DR, observability, billing, scaling |
| Docusaurus site | 52 pages | Module specs, a feature catalogue (~290 features), workflows, system design, data model and ERDs, API, integrations, operations runbooks, security and a 141-key RBAC matrix, testing, roadmap |
Checks performed:
- Cross-document grep for every release-sensitive decision: SSO, approvals, encashment, VDA, Form 16, accounting, kiosk, retention, SLOs, costs, trial length.
- Objective and target alignment between the summary and the BRD.
- Risk-register alignment between the BRD and the plan.
- Naming alignment for events, permissions and tables across the module, API and security pages.
- A full Docusaurus production build with
onBrokenLinksandonBrokenMarkdownLinksset tothrow(§9).
2. Contradictions found and resolved
| # | Contradiction | Where | Resolution (now canonical) |
|---|---|---|---|
| C1 | OIDC SSO placed in R0 in the PRD release table and plan, but in R1 in FR-IAM-007 | prd.md §5, project-plan.md E-IAM-03 | R1 (Standard plan and above). The PRD table was corrected; E-IAM-03 moved to W14–W16; the feature catalogue now marks it Must |
| C2 | Leave encashment marked "R1.1" on the roadmap but R1 Should in the PRD | roadmap.md vs FR-LVE-017 | R1 Should, which may slip to R1.1 under the plan's slip rule (project-plan.md §7) |
| C3 | Approval engine "multi-level, any/all" marked R1 Must on the module page, while the PRD caps R1 at 2 levels | notifications-workflow.md vs FR-NTF-007/012 | R1: up to 2 levels with conditions, delegation and escalation; R2: N-level and parallel steps |
| C4 | Accounting integration in R2 (architecture.md) vs R4 (CONVENTIONS.md) | architecture.md §16, CONVENTIONS §7, feature catalogue | Tally XML/CSV journal export in R2; Zoho Books/ERP APIs in R4 |
| C5 | Stage A cost ₹25–45k (architecture) vs ~₹50k on-demand (operations) | architecture.md §10, project-plan.md §10 | ₹35–55k on-demand, about ₹38–42k with reservations (still an estimate) |
| C6 | Tenant context set with SET LOCAL vs set_config(..., true) | architecture.md, CONVENTIONS, operations pages | set_config('app.tenant_id', …, true): equivalent, and explicit about PgBouncer transaction pooling |
| C7 | Summary objective targets (≥ 99.5% correct payslips; 6 staff-hours onboarding) differed from the BRD (≤ 0.1% corrected; ≤ 16 staff-hours) | summary.md §1 vs brd.md §2 | The BRD targets were adopted; the summary now shows headline targets for all ten objectives |
| C8 | The BRD introduced RSK-16 to RSK-18, which were missing from the plan's register | brd.md §16 vs project-plan.md §8 | Added to project-plan.md |
| C9 | TDS with IT declarations was first planned for R2 | early research vs screenshot evidence (§21.5) | Moved to R1, because Spryple shows IT Declaration and Form 16 menus. Form 16/24Q outputs stay in R2 |
| C10 | The glossary cited "Sec 192" only | glossary vs brd.md §14 | Updated: salary TDS moves to the Income-tax Act, 2025 from 1 April 2026; section numbers live in the statutory pack, not in code |
No unresolved contradictions remain between the BRD, PRD, plan and architecture as of this review. Note that §4 and §5 below recommend further scope cuts: WhatsApp and automated Razorpay billing move to R1.1, and Stage A collapses to four environments. Those cuts are pending stakeholder approval. Until they are approved, the BRD, PRD and plan keep their current scope, and once approved those documents must be updated together. Three items need watching because they are judgement calls rather than errors: pricing (ADR-013 is Proposed), the Lite plan's feature boundary, and Stage B timing. They are listed in §8.
3. Missing requirements and documentation gaps
| # | Gap | Severity | Recommendation | Owner / when |
|---|---|---|---|---|
| G1 | Spryple payroll screenshots largely unreviewed. The help site began blocking requests; the CTC popup, payroll generation and statutory report screens were not seen | Low (our design does not depend on them) | Optional: re-run a throttled (1 request every 5 s) review of the ~140 remaining payroll and attendance images from one agent, or request a Spryple demo | PO, before M1 |
| G2 | Our own end-user help centre (tenant-facing how-to guides, contextual help) is not planned | High for self-serve onboarding (BO-01) | Add an epic in R1: help articles generated from the typed policy schemas (descriptions, examples), plus in-app tours for the setup wizard. Spryple's own documentation defects (research §17) show why this matters | PO, R1 |
| G3 | Contract labour and daily-wage workers (manufacturing, security services): CLRA registers, minimum wages by state and skill category, daily-rated payroll | Medium | Add to the BRD as a segment question; support daily-rated pay and minimum-wage validation in R1.1; CLRA registers in R2 | PO / compliance, R1.1–R2 |
| G4 | Migration mappings from common incumbents (Excel templates, Tally payroll, other HRMS exports) | Medium | Publish mapping guides with the import toolkit; collect sample files from pilots | Customer success, W16–W24 |
| G5 | Low-literacy and vernacular UX for shop-floor workers (icon-first punch, Hindi/Telugu/Tamil) | Medium | Language priority is undecided. Decide from pilot geography by M1; at minimum the punch, leave balance and payslip screens are bilingual at GA | Design, R1 |
| G6 | Commercial and legal documents (MSA, DPA, SLA, acceptable use, sub-processor list) | High for GA | Part of the go-live checklist; legal review by W20 | Founders |
| G7 | Support tooling (helpdesk choice, status page) | Low | Pick SaaS tools (e.g. a helpdesk and a hosted status page) during R0; no build | Ops, R0 |
| G8 | Kiosk hardware guidance (tablet models, mounts, connectivity) | Low (R2) | A certified-device list in R2 | MOB, R2 |
| G9 | Multi-entity group reporting (consolidated headcount and payroll cost across legal entities in one tenant) | Medium | The PRD has legal entities. Add a consolidated group dashboard requirement for the Professional plan in R2 | PO, R2 |
| G10 | Data warehouse / BI export is only R4 | Low | Acceptable; scheduled CSV exports cover the interim | — |
4. Critical evaluation of our proposed features
| Proposal | Verdict | Reasoning |
|---|---|---|
| Typed, effective-dated policies | Keep: the core differentiator | It directly fixes Spryple's worst structural flaw (non-retroactive, duplicated rules). Constraint: ship a small number of policy types (Password, Attendance, Leave-type, Payroll, Expense), not a general rules engine. |
| Leave-type builder + ledger | Keep | The ledger is cheap to build early and very expensive to retrofit. The builder should ship with templates, so most tenants never touch it. |
| Payroll run lifecycle + immutable snapshots | Keep | It is non-negotiable for trust (RSK-01). |
| Formula-based salary components | Keep, constrained | Use a whitelisted expression language over known variables only (Basic, Gross, payable days…), with no tenant-authored code. |
| TDS engine with declarations in R1 | Keep, scope tightly | R1 covers the regime choice, the main deduction heads, monthly projection and a basic proofs workflow. Defer perquisite valuation and complex exemptions to R1.1/R2. |
| Statutory files (ECR, ESI, PT) and bank files in R1 | Keep | This is where SMEs feel the value at month end. Bank files: a generic NEFT CSV + 2–3 popular banks first. |
| Approval engine | Keep, already constrained | Two levels in R1 is the right cut. |
| One mobile app with role-based navigation | Keep | It removes Spryple's four-app fragmentation. The kiosk mode waits for R2. |
| Selfie + geo-fence in R1, face verification in R2 | Keep | Liveness, consent and a DPIA are real work. Selfie evidence is enough for the MVP. |
| Custom fields | Simplify | R1 has employee entity only, 20 fields, and basic types. Other entities come in R2. |
| WhatsApp notifications in R1 | Defer to R1.1 | BSP onboarding and template approval add schedule risk for small value at GA. Email + push + SMS are enough. |
| Razorpay billing in R1 | Simplify | Pilots and the first ~20 tenants can be invoiced manually from control-plane metering. Ship automated subscriptions in R1.1. This removes a dependency from the critical path. |
| Configurable CRM pipeline (R3) | Keep | The demo-only pipeline is Spryple's biggest CRM limitation. Templates (e.g. pharma detailing) make it usable on day one. |
| Geo-verified visits with enforcement | Keep (R3) | Spryple shows only an indicator. Enforcement options (block, flag, allow) are cheap to add once visits exist. |
| LMS (R4) | Narrow or partner | Low SME buying priority. Build mandatory/compliance courses with assignment, due dates and certificates, and consider SCORM import or a partner instead of a rich builder and gamification. |
| Timesheets (R3) | Keep as an add-on | It is useful for IT and services. Sharing the account entity with FFM avoids duplication. |
| Rewards & recognition | Keep (R2), small | Cheap, visible and good for adoption. |
5. Overengineering check
| Area | Risk | Simplification adopted or recommended |
|---|---|---|
| Cells & cell router | Building multi-cell routing before a second cell exists | MVP runs exactly one pooled cell. Keep cell_id in the tenant registry and keep the routing code a no-op until the second cell is created (architecture.md §5 already notes this). |
| Separate control-plane service | Two services to operate from day one | Keep the separate database (it is the right isolation boundary), but deploy the control-plane app on the same hosts in Stage A. A separate VPC or account comes only in Stage B. |
| Dedicated-cell automation | Terraform automation before any Enterprise contract | Defer it to the first signed Enterprise deal (R4 or trigger-based). The design stays documented. |
| Environments | local, preview, dev, UAT, staging and prod is six tiers for a small team | Stage A: local, preview, UAT (which doubles as staging) and prod. Add a separate staging tier at Stage B. |
| Observability stack | Self-hosting Tempo, Loki and Prometheus | Use Grafana Cloud + Sentry (managed) in Stage A, and self-host only if cost demands it. |
| Feature-flag platform | A full OpenFeature provider | A simple flags table in the control plane with cached SDK reads. Keep the interface OpenFeature-compatible for later. |
| Microservices extraction | Premature extraction of ingest and payroll compute | Extract only on the triggers in architecture.md §2.1. In the MVP, none is expected. |
| Compliance certifications | ISO 27001 / SOC 2 work too early | Keep the controls from day one (they are cheap) and certify only when an Enterprise pipeline requires it. |
| Public API & webhooks | Designing a full public API surface in R1 | R2 is right. R1 keeps the internal API contract-first (zod/OpenAPI), so the public API is a projection later. |
| PRD size (~300 KB) | A single huge document is hard to maintain | Treat the PRD as the R1 baseline. From R2 on, split module specs into per-module files (the Docusaurus module pages are already the natural home) and keep prd.md as the index plus NFRs. |
Not overengineered (deliberately kept): forced RLS plus isolation tests, managed Postgres with PITR from day one, the immutable payroll snapshots, expand/contract migrations, and the payroll-window freeze. Each one prevents a failure that would be existential for a payroll vendor.
6. Recommended MVP scope (final)
6.1 MVP = R0 + R1, with the simplifications from §4 and §5
| Must ship at GA | Explicitly not at GA |
|---|---|
| Self-serve trial, provisioning, plans/entitlements, platform admin console (minimal) | Automated Razorpay subscriptions (R1.1); WhatsApp (R1.1) |
| IAM: invite activation, MFA for admin roles, role builder with scopes, audit log, OIDC SSO | SAML, public API, webhooks (R2) |
| ORG: legal entity, locations with ID sequences and geo-fences, departments, designations, grades, holidays, setup wizard | Multi-entity consolidated dashboards (R2) |
| EMP: employee record with effective-dated job history, self-onboarding, document approval, checklists, imports with dry-run | Letters/e-sign, org chart (R2) |
| ATT: web and mobile punch (selfie + geo-fence), CSV/API biometric import, shifts, rotations, week-offs, regularization, permissions, shift change/swap, OT with approval, extra days/penalties, period lock | Kiosk, face verification, device push gateway (R2) |
| LVE: leave-type builder with templates, ledger, accruals, sandwich, comp-off, optional holidays, cancellation approval, on-behalf | Encashment payout may slip to R1.1 |
| PAY: structures + effective-dated compensation, run lifecycle with variance checks, EPF/ESI/PT/LWF, TDS with declarations, arrears, variable pay, advance salary, payslips, ECR/ESI/PT and bank files, reversal | Form 16/24Q, F&F, VDA, loans with interest, Tally export (R2) |
| NTF: email, push, in-app, SMS; 2-level approvals with delegation and escalation | N-level and parallel approvals (R2) |
| RPT: persona dashboards, standard reports, exports | Custom report builder (R4) |
| MOB: one app for ESS + MSS with an offline punch queue | Field tracking (R3) |
6.2 MVP success criteria
These come from brd.md BO-01 to BO-06 and the project-plan.md go-live checklist:
- 3+ pilot tenants reconcile two consecutive parallel payroll cycles with every variance explained.
- ≤ 0.1% of payslips corrected after lock during the pilot.
- ≥ 70% of pilot employees are active on mobile by the second month.
- A median of ≤ 21 days from order to first live payroll, with ≤ 16 staff-hours of implementation effort.
- Zero cross-tenant data exposures, and no open high or critical pentest findings.
6.3 If the schedule slips: cut order
Cut in this order and protect M6 (pilot payroll):
- Scheduled report emails
- Leave encashment payout
- Shift swap between employees, keeping the plain shift change
- Custom fields
- OT approval: auto-compute OT and flag it for review instead
- TDS proofs workflow: keep declarations and projection
Never cut: the period lock, the run lifecycle, the statutory files, isolation, audit or backups.
7. Future development phases
| Phase | Theme | Gate to start |
|---|---|---|
| R1.1 (≤ 6 weeks after GA) | Razorpay automation, WhatsApp, encashment (if slipped), daily-rated pay and minimum-wage checks, help-centre v2 | GA stable for 2 payroll cycles |
| R2 | Claims, Exit + F&F, Engagement, kiosk + face, device gateway, Form 16/24Q, public API and webhooks, SAML, Tally export, N-level approvals, group dashboards | ≥ 20 paying tenants; churn signals reviewed |
| R3 | Field Force & CRM, Timesheets | Demand validated: ≥ 5 qualified field-sales prospects. If the go-to-market leads with pharma/field sales, pull FFM ahead of parts of R2. Decide at M8 |
| R4 | LMS (narrow), advanced analytics, Enterprise dedicated-cell automation, accounting API integrations, BI feeds | First Enterprise contract or ≥ 150 tenants |
| Later | Recruitment/ATS, performance, surveys, assets, AI assistant (policy Q&A, anomaly detection), non-India expansion | Product-market fit in core segments |
8. Final recommendations
8.1 Business recommendation
- Position Spyrl as "attendance-to-payroll you can trust" for shift-based and multi-branch Indian SMEs. Make Field Force the first add-on, sold to pharma, FMCG and distribution. Don't compete on module count: Spryple's breadth (CRM, LMS, timesheets) is wide but shallow and inconsistently documented. Depth and correctness in the core is the defensible wedge.
- Make the Lite plan a funnel, not a separate product. It runs on the same platform with entitlements, so upgrading needs no migration.
- Validate pricing before GA. ADR-013 is still Proposed, and the BRD's indicative ₹39/₹69/₹109/₹149+ PEPM must be tested with the pilots and 10–15 prospects.
- Invest in self-serve onboarding and help content (G2) as much as in features. Implementation effort per tenant (RSK-16) is the biggest threat to unit economics.
- Treat compliance as a product. Publish the statutory pack centrally, with change logs. That is a trust and marketing asset, especially while the Labour Codes and the Income-tax Act, 2025 transition settle.
8.2 Technical recommendation
- Proceed with the architecture as written: a NestJS modular monolith; PostgreSQL with forced RLS in pooled cells; a separate control-plane database; a single Expo app; Stage A on Dokploy + managed RDS in ap-south-1; Stage B on ECS Fargate when the triggers fire.
- Run the five spikes in W1–W4 before committing the plan: Prisma + RLS + PgBouncer, the attendance day engine, the payroll engine with golden cases, Expo offline punch with a geo-fence, and a biometric push sample. Re-baseline at M1.
- Put the strongest engineers and the compliance specialist on the payroll critical path from week 1. Payroll golden tests are the most valuable test asset in the company.
- Apply the simplifications in §5: one cell, four environments, managed observability, manual billing for pilots, and WhatsApp deferred to R1.1.
- Keep the docs-as-code discipline. Root canonical documents sync into the Docusaurus site, every story updates its module page, and ADRs are recorded for every significant decision.
8.3 Decisions needed from stakeholders
| # | Decision | Needed by |
|---|---|---|
| D1 | Final product name and domain ("Spyrl" and spyrl.app are placeholders) | M1 |
| D2 | Lead segment: shift-based SMEs vs field-sales SMEs (this affects whether FFM moves ahead of R2) | M1 |
| D3 | Pilot clients (6–8 recruited, to land 3–5) | W4 to W16 |
| D4 | Payroll/compliance specialist engaged | W2 |
| D5 | Pricing hypothesis to test | M1 |
| D6 | First regional languages | M1 |
| D7 | Budget approval for the team (§2 of the plan) and Stage A infrastructure | Kick-off |
9. Verification evidence
| Check | Result |
|---|---|
Docusaurus production build (npm run build, broken links and broken Markdown links set to throw) | Pass (2026-10-31): 72 doc pages generated, 0 broken links. The one broken link found (the roadmap URL) was fixed |
| Mermaid diagram syntax (all 119 diagrams in the root docs and site, parsed with mermaid 12 + jsdom) | Pass. Two diagrams initially failed (semicolons inside sequence messages) and were fixed |
| Naming alignment (permissions, events, tables, money types) | The API endpoints use only keys in the RBAC matrix. Four missing keys were added (att.day.recompute, att.work_request.*, pay.advance.request, ext.master.manage). The webhook payload is camelCase everywhere. Money is stored as bigint paise in all module ERDs |
| Open technical decisions | Logged in the site's decision log as future ADR-015 onwards: formula expression language, the date/time library, the workflow condition language, a background-geolocation SDK, the WAF provider, and multi-entity details |
| Cross-document consistency (§2) | 10 contradictions found and resolved; none open |
| Evidence labelling | Research, BRD and PRD label Spryple claims as [Observed]/[Inferred]/[Proposed] with citations |
| Research coverage | 43/43 Help Center pages read in full; screenshot coverage partial (see G1) |
Synced from
/review.mdin the repository root. Edit the root file, not this page.