Module map

Spyrl is a modular monolith (see architecture). Each module owns its tables (prefixed with the lowercase module code, e.g. att_day), exposes a public service interface, and publishes domain events through the transactional outbox. No module reads another module's tables. This page is the entry point to the per-module design specs.

Module codes, roles, scopes and release scope come from CONVENTIONS.md. Requirements live in the BRD (BR-<MOD>-*) and the PRD (FR-<MOD>-*). The behaviour we learned from the reference product is in the Spryple analysis.

Dependency diagram

Solid arrows mean "depends on / consumes data or events from". Dotted arrows are cross-cutting services that every module uses.

Key flows (each is a journey in User Workflows):

• Attend-to-pay: ATT computes day statuses, LVE supplies LOP and balances, PAY derives payable days and runs gross-to-net. See attend-to-pay.
• Hire-to-retire: EMP owns the employee and job history; IAM activates the user; EXT closes the record and triggers the F&F run in PAY. See hire-to-retire.
• Field-to-claim: FFM produces daily travel; CLM turns it into a mileage claim; PAY pays it. See field visit to travel claim.

Module table

Code	Module	Purpose	Release	Packaging
PLT	Platform & Tenant Administration	Control plane: tenant registry, provisioning, plans, entitlements, flags, billing, cells, support access, statutory packs	R0 (R1 billing)	Core (platform-operated)
ORG	Organisation Setup & Masters	Legal entities, locations, geo-fences, departments, designations, grades, holiday calendars, employee-ID sequences, custom fields, shared accounts	R0	Core
IAM	Identity, Access & Security	Users, invite activation, passwords, MFA, SSO, roles with permission × scope, sessions, device binding, audit log	R0	Core
EMP	Core HR & Onboarding	Employee record, effective-dated job history, self-onboarding, documents, checklists, induction, letters, change requests, imports	R1	Core
ATT	Attendance, Shifts & Time	Punch capture and ingest, shifts, rotations, week-offs, attendance policy, day computation, requests, OT, period lock	R1	Core
LVE	Leave & Holidays	Leave-type builder, leave policies, ledger, accrual, sandwich rule, requests, comp-off, encashment, optional holidays	R1	Core
PAY	Payroll & Statutory Compliance	Components, structures, compensation, pay runs, EPF/ESI/PT/LWF/TDS, declarations, loans, payslips, statutory and bank files	R1 (Form 16 / 24Q R2)	Core
NTF	Notifications & Workflow	Approval engine (multi-level, delegation, escalation, on-behalf), templates, channels, outbox, webhooks	R0 core, R1 approvals, R2 webhooks	Core
RPT	Reporting, Dashboards & Exports	One report framework (datasets + scope + export + schedule), persona dashboards	R1 standard, R4 advanced	Core
MOB	Mobile App & Kiosk	One Expo app: ESS, MSS, field, claims; offline punch queue; kiosk mode with face verification	R1 ESS/MSS, R2 kiosk/face	Core (face verification is an add-on)
CLM	Claims & Expense Reimbursement	Expense policy, categories, multi-bill claims, verify/approve/pay, mileage from travel, payout via payroll	R2	Plan tier (Professional+)
EXT	Exit & Full-and-Final	Resignation, termination, LWD negotiation, clearance, exit interview, F&F settlement, letters	R2	Plan tier (Professional+)
ENG	Engagement	Targeted announcements with read receipts, recognition, celebrations	R2	Plan tier (Professional+)
FFM	Field Force & Sales CRM	Consented GPS tracking, visits, beat plans, configurable pipeline, payments, daily travel	R3	Add-on (per tracked user)
TSM	Timesheets & Projects	Projects, tasks, weekly timesheets, approvals, defaulters, effort variance	R3	Add-on
LMS	Learning Management	Mandatory compliance courses, enrolment rules, assessments, certificates, badges	R4	Add-on

Cross-module conventions used in every spec

Convention	Rule
Table names	<module>_<entity> in snake_case, e.g. lve_ledger_entry. Control-plane tables have no prefix (tenant, cell, plan).
Tenancy	Every tenant-owned table has tenant_id; foreign keys include it; RLS is forced.
Effective dating	Records that change over time carry valid_from and valid_to (valid_to null = open-ended). Policies are versioned and assigned by applicability rules.
Events	<module>.<entity>.<past_tense_verb>, e.g. att.day.computed, lve.request.approved, pay.run.locked. Published through the outbox. See events.
Permissions	<module>.<resource>.<action> checked together with a scope: SELF, TEAM, DEPARTMENT, LOCATION, ORG. Written lve.request.approve@TEAM. See the RBAC matrix.
REST	/v1/<module>/<resource> with plural kebab-case resources and :id path parameters. Approvals are actioned through /v1/ntf/tasks. See API endpoints.
Data model	Physical ERDs and the data dictionary are in data model. The diagrams in the module specs show key fields only.
Labels	[Observed] and [Inferred] refer to the reference product; [Proposed] is our design.