Spyrl — Project Plan
Version: 1.0 · Date: 2026-10-31 · Status: Baseline for approval Related: summary.md · brd.md · prd.md · architecture.md · review.md · CONVENTIONS.md Time convention: weeks are counted from project kick-off (W1). Calendar dates will be fixed at kick-off. All durations are estimates to re-baseline at the end of R0.
1. Scope
1.1 In scope
| Release | Modules | Outcome |
|---|---|---|
| R0 Foundations | PLT (control plane MVP), IAM, ORG, NTF core, audit, CI/CD, observability, Stage A production | A tenant can be provisioned, can sign in securely and can configure its organisation |
| R1 MVP | EMP, ATT, LVE, PAY (India statutory incl. TDS with IT declarations), RPT (standard), MOB (ESS + MSS) | A pilot SME runs a full attend-to-pay month in Spyrl |
| R2 | CLM, EXT (+F&F), ENG, MOB kiosk + face verification, biometric device gateway, Form 16/24Q, public API & webhooks, SAML | The full HR lifecycle; Professional plan launch |
| R3 | FFM, TSM | Field Force and Timesheet add-ons |
| R4 | LMS, advanced analytics, dedicated-cell automation, accounting integrations | The Enterprise plan matures |
1.2 Out of scope (until re-prioritised)
Recruitment/ATS, performance management (appraisals, OKRs), surveys, asset management, helpdesk, multi-country payroll, on-premise installs, an invoicing/billing engine for client projects, and any per-client code forks. See prd.md "Future enhancements".
1.3 Scope-control rules
- Configuration over customisation. A client request becomes a configurable product feature behind a flag, or it is declined.
- MVP scope changes need the product owner and tech lead to agree, and must have their impact on milestone M6 (pilot payroll) recorded.
- Anything not traceable to a BR/FR is not built.
2. Team & governance
2.1 Team (core ~8 FTE + specialists)
| Role | FTE | Notes |
|---|---|---|
| Product owner / business analyst | 1 | Owns the BRD/PRD and backlog; runs the pilot programme |
| Tech lead / architect | 1 | Owns architecture.md and the ADRs; hands-on on platform and payroll engine |
| Backend engineers (NestJS) | 3 | One focused on payroll and compliance |
| Frontend engineers (React) | 2 | Web SPA and admin console |
| Mobile engineer (Expo) | 1 | ESS/MSS app, offline punches; kiosk in R2 |
| QA / automation engineer | 1 | Test strategy, Playwright/Maestro, payroll golden tests |
| DevOps / SRE | 0.5 | Dokploy, RDS, CI/CD, observability; grows to 1 in Stage B |
| Product designer | 0.5 | Design system, key flows, usability tests |
| Payroll & compliance specialist (consultant) | 0.25 | Validates statutory rules, reviews golden test cases |
| Implementation / customer success | 0.5 from W20 | Pilot onboarding, import templates, training |
2.2 Cadence
- Two-week sprints. Sprint review with pilot-client representatives from W16.
- Architecture review every two weeks. Every significant decision is recorded as an ADR in the documentation site's decision log.
- Release train: weekly from W12 (to dev/UAT), then weekly to production after GA, with the payroll-window freeze (25th–5th).
- Monthly steering: scope, risks, budget, and milestone health (RAG).
2.3 Definition of Ready / Done
| Ready | Done |
|---|---|
| Story traces to FR/BR IDs; acceptance criteria in Given/When/Then; permissions and scopes stated; designs available for UI stories; test data identified | Code reviewed; unit + integration tests pass; tenant-isolation tests pass; acceptance criteria verified with evidence; docs (module page / API) updated; telemetry added; feature flag default set; no new high-severity security findings |
3. Development phases
| Phase | Weeks | Goal | Exit criteria |
|---|---|---|---|
| Discovery & spikes | W1–W4 | Validate assumptions and remove the biggest technical unknowns | 5+ SME interviews synthesised; pricing hypothesis; spike reports: (a) Prisma + RLS + PgBouncer, (b) attendance day engine prototype, (c) payroll engine with 10 golden cases, (d) Expo offline punch + geo-fence, (e) biometric push sample |
| R0 Foundations | W1–W10 | A secure multi-tenant skeleton in production (Stage A) | M1–M3 met; isolation test suite green; first DR restore drill done |
| R1 MVP build | W9–W27 | The attend-to-pay core | All Must FRs for R1 accepted; performance and security gates passed |
| Pilot | W23–W30 | 3–5 pilot tenants run two payroll cycles in parallel with their legacy process | Payroll variance vs legacy explained to 100%; pilot NPS ≥ 30; P1 defects = 0 |
| GA | W30 | Public launch of Lite + Standard | Go-live checklist (§9.4) signed off |
| R2 | W31–W46 | Professional plan | Claims, Exit+F&F, kiosk/face live with ≥ 2 paying tenants each |
| R3 | W47–W62 | Field Force & Timesheet add-ons | ≥ 3 field-force tenants live |
| R4 | W63+ | LMS, analytics, Enterprise | First dedicated-cell Enterprise tenant live |
4. Module-wise implementation roadmap (epics)
Epic IDs follow E-<MOD>-NN (see CONVENTIONS.md §5). The detailed FRs and stories are in prd.md.
R0
| Epic | Description | Depends on | Weeks |
|---|---|---|---|
| E-PLT-01 | Monorepo, CI pipeline, Docker images, Dokploy dev/UAT, preview environments | — | W1–W3 |
| E-PLT-02 | Tenant context, Prisma tenant extension, RLS policies, isolation test harness | E-PLT-01 | W3–W6 |
| E-PLT-03 | Control plane: tenant registry, provisioning workflow, plans/entitlements SDK, feature flags | E-PLT-02 | W4–W8 |
| E-PLT-04 | Platform admin console v1 (tenants, plans, flags, support access) | E-PLT-03 | W6–W10 |
| E-IAM-01 | Invite activation, login, JWT/refresh, MFA (TOTP), password policy, sessions | E-PLT-02 | W3–W7 |
| E-IAM-02 | Role builder (permission × scope), seeded role templates, guards, audit log | E-IAM-01 | W5–W9 |
| E-ORG-01 | Company, legal entity, locations (ID sequence, geo-fence), departments, designations, grades, holidays, setup wizard shell | E-IAM-02 | W5–W9 |
| E-NTF-01 | Outbox, notification service (email, push, in-app), templates, preferences | E-PLT-02 | W5–W9 |
| E-NTF-02 | Approval workflow engine (up to 2 levels with conditions, approver resolution and reassignment, on-behalf auto-approve; delegation and escalation in R1; N-level and parallel steps in R2) | E-NTF-01 | W7–W11 |
| E-PLT-05 | Observability (OTel, Grafana, Sentry), Stage A prod cell, backups, synthetic checks | E-PLT-01 | W6–W10 |
R1 (MVP)
| Epic | Description | Depends on | Weeks |
|---|---|---|---|
| E-EMP-01 | Employee record, effective-dated job assignment, custom fields (basic), directory | E-ORG-01 | W9–W12 |
| E-EMP-02 | New hire → self-onboarding link → document approval → onboarding checklist → activation invite | E-EMP-01, E-NTF-02 | W10–W13 |
| E-EMP-03 | Import toolkit (employees, opening balances, compensation, bank) with dry-run | E-EMP-01 | W11–W14 |
| E-IAM-03 | OIDC SSO (Google Workspace, Microsoft Entra ID), Standard plan and above | E-IAM-01 | W14–W16 |
| E-ATT-01 | Shift master, attendance policy (typed), rotations, week-offs, roster assignment | E-ORG-01 | W9–W12 |
| E-ATT-02 | Punch ingestion (web, mobile selfie + geo-fence, CSV/API biometric import), punch dedup | E-ATT-01 | W10–W14 |
| E-ATT-03 | Day-computation engine (statuses, lates, half/full day, OT, extra days, penalties), recompute jobs | E-ATT-02 | W11–W16 |
| E-ATT-04 | Requests: attendance (WFH/on-duty), regularization, permission, shift change/swap, OT approval | E-ATT-03, E-NTF-02 | W13–W17 |
| E-ATT-05 | Period lock and attendance-to-payroll handoff (payable days, LOP, OT, extra/penalty) | E-ATT-03 | W16–W18 |
| E-LVE-01 | Leave-type builder (templates), policy versions, applicability | E-ORG-01 | W13–W16 |
| E-LVE-02 | Ledger, accrual/proration/carry-forward/lapse jobs, opening balances | E-LVE-01 | W14–W18 |
| E-LVE-03 | Requests, sandwich rules, comp-off earn/expire, cancellation, optional holidays, on-behalf | E-LVE-02, E-NTF-02 | W15–W20 |
| E-PAY-01 | Salary structure templates, formula components, effective-dated compensation, CTC breakdown | E-EMP-01 | W13–W16 |
| E-PAY-02 | Payroll engine library (gross-to-net, proration, rounding) + golden tests | E-PAY-01 | W13–W19 |
| E-PAY-03 | Statutory: EPF/EPS/EDLI, ESI, PT (state slabs), LWF, statutory pack versions | E-PAY-02 | W15–W20 |
| E-PAY-04 | TDS: regime selection, IT declarations, proofs (basic), monthly projection | E-PAY-02 | W17–W22 |
| E-PAY-05 | Run lifecycle (draft → … → locked → paid → reversed), variance checks, arrears, variable pay, advance salary & recovery, other deductions | E-PAY-02, E-ATT-05, E-LVE-02 | W18–W24 |
| E-PAY-06 | Outputs: payslips (PDF, password-protected, email/app), ECR, ESI, PT files, bank files, payroll register | E-PAY-05 | W21–W26 |
| E-RPT-01 | Report framework (dataset + scope-aware filters + export + schedule), persona dashboards | E-ATT-03, E-LVE-02 | W19–W26 |
| E-MOB-01 | Expo app shell, company-code login, device binding, push, offline queue | E-IAM-01 | W11–W15 |
| E-MOB-02 | ESS: punch (selfie + geo), requests, leave, balances, payslips, profile | E-MOB-01, E-ATT-02, E-LVE-03 | W14–W22 |
| E-MOB-03 | MSS: approvals inbox, team calendar, on-behalf actions, team attendance | E-MOB-02, E-NTF-02 | W18–W24 |
| E-PLT-06 | Billing (Razorpay subscriptions), metering, trial → paid lifecycle | E-PLT-03 | W18–W24 |
| E-PLT-07 | Hardening: pentest fixes, load tests (month-end), per-tenant export, DR drill #2 | all | W25–W27 |
R2–R4 (epic level)
| Release | Epics |
|---|---|
| R2 | E-CLM-01 policy & categories; E-CLM-02 claims with two-stage approval & payout via payroll; E-EXT-01 separation/termination & clearance; E-EXT-02 F&F off-cycle run & letters; E-ENG-01 announcements & recognition; E-MOB-04 kiosk mode & face verification (consent, liveness); E-ATT-06 biometric device gateway; E-PAY-07 Form 16 / 24Q data; E-PLT-08 public API & webhooks; E-IAM-04 SAML; E-PAY-08 payroll journal export (Tally XML / CSV) |
| R3 | E-FFM-01 consented tracking & ingest service; E-FFM-02 accounts, contacts, configurable pipeline, activities, payments; E-FFM-03 geo-verified visits & beat plans; E-FFM-04 travel → CLM mileage; E-TSM-01 projects/tasks/teams; E-TSM-02 weekly entry, approvals, defaulters, effort variance |
| R4 | E-LMS-01 courses (incl. SCORM import), assignment & due dates, assessments, certificates; E-RPT-02 advanced analytics (attrition, absenteeism, OT cost); E-PLT-09 Stage B (ECS + Terraform cells) if not already triggered; E-PLT-10 dedicated-cell automation; E-PAY-09 accounting API integrations (Zoho Books, ERPs) |
Stage B (ECS Fargate) is trigger-based (architecture.md §10.2) and may be pulled into R2 if a dedicated-cell contract or the scale threshold arrives earlier.
5. Dependencies
5.1 Critical path
E-PLT-02 (tenancy/RLS) → E-ORG-01 → E-EMP-01 → E-ATT-03 (day engine) → E-ATT-05 (period lock) → E-PAY-05 (run lifecycle) → E-PAY-06 (outputs) → M6 pilot payroll. Payroll is the longest, riskiest chain. It gets the strongest engineer, the compliance consultant and the earliest golden test cases.
5.2 External dependencies
| Dependency | Needed by | Owner | Fallback |
|---|---|---|---|
| Payroll/compliance specialist availability | W2 onward | PO | A second consultant on retainer |
| Pilot clients (3–5) committed with legacy payroll data | W16 | PO / founders | Friendly design partners with a discounted first year |
| AWS account and organisation set-up (ap-south-1) | W1 | DevOps | — |
| Razorpay merchant onboarding | W18 | Finance | Manual invoicing for pilots |
| Email/SMS/WhatsApp provider accounts and DLT registration (India SMS) | W8 | DevOps | Email + push only for MVP |
| Apple/Google developer accounts | W11 | Mobile | — |
| Biometric device samples (ZKTeco/eSSL) for testing | W10 | QA | CSV import only in MVP |
| Legal review: DPDP notices, consent texts, terms, DPA | W20 | Founders | Hold GA |
6. Milestones
| ID | Milestone | Week | Acceptance |
|---|---|---|---|
| M1 | Spikes complete; architecture baseline confirmed | W4 | 5 spike reports; ADRs updated; plan re-baselined |
| M2 | Secure tenant skeleton | W8 | Provision a tenant → invite → MFA login → configure ORG; isolation suite green |
| M3 | Production Stage A live | W10 | Prod cell with backups, monitoring, on-call; DR restore drill #1 recorded |
| M4 | Attendance engine feature-complete | W18 | Day statuses correct on a 30-scenario golden set; period lock works |
| M5 | Leave & payroll calculation complete | W22 | 50+ payroll golden cases pass (validated by the compliance specialist); leave ledger reconciles |
| M6 | First pilot payroll run (parallel) | W26 | One pilot tenant's month calculated; variance vs legacy fully explained |
| M7 | MVP feature-complete, hardened | W27 | All R1 Must FRs accepted; pentest high/critical findings fixed; month-end load test passed |
| M8 | Second parallel cycle + go-live decision | W30 | 3+ pilots reconciled; go-live checklist signed |
| M9 | MVP GA (Lite + Standard) | W30 | Public sign-up open; billing live |
| M10 | R2 GA (Professional) | W46 | Claims, Exit+F&F, kiosk live |
| M11 | R3 GA (add-ons) | W62 | Field Force and Timesheets live |
| M12 | First Enterprise dedicated cell | R4 / trigger | Provisioned by automation in under 1 day |
7. Priorities
- Correctness of money and time. Attendance and payroll accuracy beat feature breadth.
- Tenant isolation and security. It is never traded for speed.
- Mobile ESS/MSS. Adoption drives retention.
- Self-serve onboarding. It keeps the cost to serve low.
- Breadth (claims, exit, CRM, timesheets, LMS) comes in that order.
MoSCoW per requirement is in prd.md. For R1, anything marked Should may slip to R1.1 (within 6 weeks after GA) if it threatens M6.
8. Risks and mitigation
| ID | Risk | Likelihood | Impact | Mitigation | Owner |
|---|---|---|---|---|---|
| RSK-01 | Payroll calculation errors (statutory, proration, rounding) damage trust | Medium | Critical | Pure engine library; 50+ golden cases signed off by a specialist; parallel runs in the pilot; variance checks; immutable snapshots; reversal flow | Tech lead |
| RSK-02 | Cross-tenant data leak | Low | Critical | App filter + forced RLS + composite FKs; isolation tests in CI; pentest; least-privilege DB roles | Tech lead |
| RSK-03 | Prisma + RLS + connection pooling misbehaves under load | Medium | High | Spike in W1–W4; transaction-scoped SET LOCAL; PgBouncer transaction mode test; fallback: pass the tenant via the session in a dedicated pool | Backend |
| RSK-04 | Statutory rules change mid-build (e.g. Labour Codes wage definition, ESI/PF ceilings, PT slabs) | High | Medium | Effective-dated statutory pack published centrally; no hard-coded rates; compliance specialist watch | PO |
| RSK-05 | Pilot clients unavailable or unwilling to share legacy payroll | Medium | High | Recruit 6–8 to land 3–5; incentives; anonymised data agreements; start recruiting in W4 | PO |
| RSK-06 | Scope creep from pilots ("just one custom rule") | High | Medium | Configuration-over-customisation rule; backlog triage; R1.1 bucket | PO |
| RSK-07 | Biometric device diversity (protocols, firmware) | High | Medium | MVP = CSV/API import + one validated device family; device gateway in R2; certified-device list | Backend |
| RSK-08 | Mobile background-location and battery restrictions (Android OEMs, iOS) | High | Medium (R3) | R1 punches are foreground only; R3 tracking uses OS-sanctioned modes; point-to-point fallback; OEM testing matrix | Mobile |
| RSK-09 | Face verification accuracy, spoofing, privacy and legal concerns | Medium | High (R2) | Liveness, explicit consent, templates not images, a manual fallback (PIN + selfie), DPIA | Security |
| RSK-10 | DPDP compliance obligations under-estimated | Medium | High | Legal review by W20; privacy by design; consent and retention features in the MVP | Founders |
| RSK-11 | Under-estimated effort (the payroll and attendance engines are deep) | High | High | Spikes; re-baseline at M1; Should items can slip to R1.1; the strongest engineers on the critical path | Tech lead |
| RSK-12 | Month-end load spikes (payroll + payslip emails + punches) | Medium | Medium | Queues with per-tenant concurrency; k6 tests at 3× expected peak; autoscaled workers | DevOps |
| RSK-13 | Small team, key-person risk (payroll, DevOps) | Medium | High | Pairing; docs-as-code; runbooks; ADRs; cross-training | Tech lead |
| RSK-14 | Competition from established Indian HRMS vendors on price | High | Medium | Focus on the attend-to-pay accuracy + mobile + field niche; Lite plan; fast onboarding | Founders |
| RSK-15 | Stage A → Stage B migration disrupts production | Low | Medium | Containers + Terraform from day one; blue/green cutover; rehearse in staging | DevOps |
| RSK-16 | Implementation effort per tenant erodes margin | Medium | High | Setup wizard, import templates and toolkit, paid implementation packages; track staff-hours per tenant (BO-01, BO-04) | Customer success |
| RSK-17 | Incident during the payroll window | Medium | High | Payroll-window freeze (25th–5th), extended support hours, canary waves, reversal flow (BO-02, BO-05) | Tech lead |
| RSK-18 | Low ESS or field adoption | Medium | Medium | One app, low-end Android support, nudges, manager-led rollout, training material (BO-03) | PO |
9. Testing & release strategy
The full strategy is in the documentation site under Testing & Maintenance.
9.1 Test layers
| Layer | What | Gate |
|---|---|---|
| Unit | Domain logic, policy evaluators, the payroll engine | ≥ 80% line coverage in packages/policy and packages/payroll-engine |
| Golden / property tests | Payroll (50+ cases at M5, 150+ at GA); attendance day engine (30 scenarios at M4); leave accrual properties | 100% pass; any change to a golden output needs specialist sign-off |
| Integration | API + DB with RLS; job workers; outbox | Pass on every PR |
| Tenant isolation | Automated cross-tenant access attempts for every repository and endpoint | Zero failures; blocks merge |
| Contract | zod/OpenAPI contracts shared by web and mobile | Pass on every PR |
| E2E | Playwright (web), Maestro (mobile) on critical journeys: provision, onboard, punch, leave, payroll run, payslip | Pass before each release wave |
| Performance | k6 month-end scenario (payroll for 5k employees, 50k punches/hour, payslip fan-out) | SLOs in architecture.md §13 |
| Security | SAST, dependency and container scanning on each PR; DAST on staging weekly; external pentest before GA | No open high/critical findings at GA |
| Accessibility | axe checks in CI; manual screen-reader pass on key flows | WCAG 2.1 AA for ESS flows |
| UAT | Pilot tenants on UAT and prod (parallel payroll) | Sign-off per pilot |
9.2 Environments
local (docker-compose) → preview (per PR, Dokploy) → dev → uat (pilot training, Dokploy) → staging (production-like) → prod cells (wave 0 internal and canary → wave 1 pooled → wave 2 dedicated).
9.3 Release process
- Trunk-based development; features behind flags; weekly release trains; expand/contract migrations; SLO-gated waves.
- Payroll-window freeze (25th–5th): only patch fixes, with extra review.
- Mobile: EAS builds; OTA for JS-only fixes; a minimum supported version is enforced.
- Release notes are published to the tenants' in-app "What's new" and the docs site.
9.4 Go-live checklist (MVP GA)
- All R1 Must FRs accepted with evidence
- Payroll golden suite ≥ 150 cases, specialist sign-off
- Two parallel payroll cycles reconciled for ≥ 3 pilot tenants
- Pentest: no open high or critical findings
- DR drill #2 meets RPO ≤ 5 min and RTO ≤ 1 h
- Monitoring, alerting, on-call rota and runbooks in place
- DPDP notices, consent flows, terms, privacy policy and DPA approved by counsel
- Billing live; trial → paid flow tested
- Support process and SLAs published; help centre v1 published
- Data export (tenant offboarding) tested
10. Budget indicators (infrastructure only, estimates)
| Stage | Monthly estimate | Notes |
|---|---|---|
| Dev/UAT/preview (Dokploy on 1–2 VMs) | ₹8–15k | Small instances; previews torn down automatically |
| Stage A production (2× EC2, RDS Multi-AZ, ElastiCache, S3, CloudFront, backups) | ₹35–55k (on-demand; ~₹38–42k with reservations) | Up to ~50 tenants / 10k employees |
| Stage B production (ECS Fargate, RDS Multi-AZ + replica, Redis, S3, NAT, observability) | ₹60–120k | Scales with cells; dedicated cells billed to Enterprise contracts |
| Third-party (email/SMS/WhatsApp, maps, Sentry, Grafana Cloud) | ₹10–40k | Grows with usage; partly metered back to tenants |
Team cost is excluded. Re-estimate at M1 with real AWS pricing.
11. Communication & reporting
| Artefact | Frequency | Audience |
|---|---|---|
| Sprint review + demo | Bi-weekly | Team, stakeholders, pilots (from W16) |
| Milestone RAG + risk register update | Monthly | Steering |
| Release notes | Weekly | Tenants, support |
| Documentation updates (docs-as-code) | With every merged story | Everyone |
12. Traceability
| Plan item | Traces to |
|---|---|
| Releases R0–R4 | CONVENTIONS.md §7, prd.md release plan |
| Epics E- | PRD FR- |
| Milestones | BRD business objectives BO-01..BO-10 (brd.md) |
| Risks | architecture.md (technical), brd.md (business), review.md (final assessment) |
Synced from
/project-plan.mdin the repository root. Edit the root file, not this page.