Opening balances and data migration importer
Build: Radhakrishnan · Test: Divaram
A client never starts on an empty system. They go live with projects already part built, vendors already owed money, loans half paid and money already in the bank. This PBI builds the importer for those opening balances (docs/tasks.md P9-T04): Excel templates, a dry run that reports every problem row without writing anything, and a single dated opening journal so the ledger is complete from day one.
Done when
- An administrator can download Excel templates for project costs to date, vendor and subcontractor outstanding, loan positions, and cash and bank opening balances.
- Uploading a filled template shows a dry-run report listing every invalid row with its line number, and nothing is written.
- Committing a clean file posts one opening journal dated on the go-live date.
- After import, the five integrity controls (Administration > Integrity check) all pass.
- Importing the same file again is blocked and never doubles a balance.
Tasks
- Opening balance Excel templates and sample files Radhakrishnan
- Opening balance import service with a dry run Radhakrishnan
- Post opening balances as one opening journal and block re-runs Radhakrishnan
- Data import screen under Administration Radhakrishnan
- Tests for the opening balance importer Radhakrishnan
- Test: opening balance import end to end Divaram
Ask Prasath whether the client has sent their existing Excel workbooks (review.md Q8). If not, build against the templates and sample data.
Backups, restore drill and operations runbook
Build: Logu · Test: Thakshinenthra
A finance system with no tested restore is not ready for a client. This PBI (docs/tasks.md P9-T05) adds automated daily backups of the database and attachments, a restore script that has actually been used, rotating logs with error alerts, and a runbook someone other than its author can follow.
Done when
- A daily backup runs on the server and keeps a set number of days.
- Attachments are included in the backup.
- A restore into a clean database reproduces the source exactly, checked by row counts and the integrity check.
- docs/runbook.md covers restore, secret rotation, re-running a failed import and investigating an integrity failure.
- Someone other than the author has followed the runbook successfully.
Tasks
- Daily backup script with retention and attachments Logu
- Restore script and a timed restore drill Logu
- Log rotation and error alert emails Logu
- Operations runbook Logu
- Backup round-trip test in CI Logu
- Test: follow the runbook from scratch Thakshinenthra
Practise on a local Ubuntu VM or WSL first. Never test a restore against the production database.
UAT script and BRD traceability matrix
Build: Thakshinenthra · Test: Logu
Before sign-off, the client will check the numbers against the worked examples in their BRD. This PBI (the first half of docs/tasks.md P9-T07) turns each worked example into a step-by-step UAT scenario they can run themselves, and maps each of the 54 business rules in BRD section 70 to the test that enforces it, with an automated check that fails if a rule loses its test.
Done when
- docs/uat.md has one scenario per BRD worked example (sections 16, 18, 20, 21, 25, 26, 32, 34, 35, 36, 40, 41, 42, 45), each with steps, data and the expected figures.
- docs/traceability.md maps every one of the 54 rules to a task and at least one test.
- A test fails the build if a mapped test no longer exists or a rule has no test.
Tasks
- UAT scenarios for the BRD worked examples Thakshinenthra
- Traceability matrix for the 54 business rules Thakshinenthra
- Automated check that every rule has a test Thakshinenthra
- Write the missing tests the matrix finds Thakshinenthra
- Test: run the UAT script on a fresh database Logu
The BRD (Ledgerstone_BRD_v1_2.md) is not in the repo. Get it from Prasath before starting.
Inline validation on the remaining forms
Build: Divaram · Test: Bharath
P10-T09 added AmountInput and FieldLabel and fully wired required-field markers and inline errors on four forms. The rest were listed as not done: the reconciliation Map dialog, purchase orders, multi-project vendor payment, donations, labour, receipts, vendor payments and statement, vendor purchases and bank-import review. This PBI finishes them so every form tells the user exactly why it will not submit.
Done when
- Every required field on the listed forms shows an asterisk.
- Leaving a required field blank or invalid shows a specific inline error when the user leaves the field, and it clears once fixed.
- A disabled submit button always has a visible reason on the form.
Tasks
- Inline validation: vendor payments, multi-project payment and receipts Divaram
- Inline validation: vendor purchases and purchase orders Divaram
- Inline validation: labour, donations and the reconciliation Map dialog Divaram
- Inline validation: bank-import review rows Divaram
- Tests for the new inline errors Divaram
- Test: try to break every form Bharath
Copy the pattern from the field-officers form exactly; do not invent a second one.
Phone layout for site use (390px)
Build: Bharath · Test: Radhakrishnan
Owners and field officers often check kanaQ from a site on a phone. review.md recommends making the web app work well at 390px rather than building a mobile app. This PBI makes the shell, the main lists and the most used entry forms usable on a phone.
Done when
- At 390px wide the sidebar becomes a drawer and nothing scrolls sideways.
- Lists on the dashboard, approvals, expenses and field-officer pages show as cards on a phone.
- Field-officer bills, direct expenses and approvals can be completed on a phone.
- A Playwright project runs the smoke specs at a phone viewport.
Tasks
- Audit every main page at 390px Bharath
- App shell and sidebar on phones Bharath
- Card view for lists on small screens Bharath
- Entry forms and dialogs at 390px Bharath
- Playwright phone viewport project Bharath
- Test: walk through kanaQ on a real phone Radhakrishnan
Do the audit first and agree the list with Prasath before changing pages.
End-to-end tests for the Phase 10 modules
Build: Logu · Test: Thakshinenthra
The Playwright suite in frontend/tests/e2e covers Phases 0 to 8 well, but the modules added later have no end-to-end specs: loans, purchase orders, field officers, vendor quotations, notifications, the audit log viewer and the companies screen. This PBI adds them so future changes to those screens are caught in CI.
Done when
- Each listed module has at least one spec covering its main flow.
- The suite passes three runs in a row with no flaky failures.
Tasks
- E2E: loans and EMI Radhakrishnan
- E2E: purchase orders Radhakrishnan
- E2E: field officers Logu
- E2E: vendor quotations and price trend Radhakrishnan
- E2E: notifications, audit logs and companies Logu
- Review: run the suite three times and check for flaky specs Thakshinenthra
Follow the helpers and data setup used by vendor-payment-flow.spec.ts.
Move from the demo database to MySQL
Build: Divaram · Test: Logu
The CRM runs on an in-memory SQLite database seeded from lib/data/config.ts, which resets on every restart. A real school needs its data kept. This PBI adds a MySQL mode using the schema and migrations already in db/, while keeping demo mode for sales demos, following db/README.md.
Done when
- With DB_MODE=mysql the app reads and writes a MySQL database and data survives a restart.
- With DB_MODE=demo (the default) it behaves exactly as today.
- A script creates the first super admin.
- The demo-accounts panel is hidden in MySQL mode.
- Unit and API tests pass against MySQL.
Tasks
- Apply the MySQL schema and migrations locally Divaram
- Database switch: DB_MODE=demo or mysql Divaram
- Workspace defaults and demo-login panel in MySQL mode Divaram
- First super admin script Divaram
- Run the tests against MySQL and fix SQL differences Divaram
- Test: every module on MySQL, with a restart Logu
Read db/README.md first. Do not delete lib/data/: demo mode still needs it.
CI pipeline on GitHub Actions
Build: Radhakrishnan · Test: Divaram
The CRM has tests but nothing runs them automatically. This PBI adds a GitHub Actions workflow that runs lint, type check, unit tests, a production build and the API tests on every push and pull request.
Done when
- Every push and pull request runs lint, types, unit tests, build and API tests.
- A failing step blocks the pull request.
Tasks
- Workflow: install, lint, type check and unit tests Radhakrishnan
- Workflow: build and API tests Radhakrishnan
- Fix lint and type errors the pipeline finds Radhakrishnan
- Review: prove CI blocks a broken pull request Divaram
API tests need the app running on port 3000 with ALLOW_DEMO_PAYMENTS=1 (see README.md Scripts).
Razorpay test-mode verification
Build: Bharath · Test: Thakshinenthra
Online payments are covered by unit tests but have never been run against Razorpay's servers (README.md says so). This PBI runs the real flow with test-mode keys, including the webhook, fixes what breaks and writes a go-live checklist.
Done when
- A student can pay a balance and an invoice from the portal with Razorpay test keys.
- The webhook records a payment even when the student closes the browser before returning.
- Failed payments are recorded and staff are not told it was paid.
- docs/payments.md lists the go-live steps.
Tasks
- Run portal checkout with Razorpay test keys Bharath
- Webhook through a tunnel Bharath
- Fix defects and write the go-live checklist Bharath
- Test: online payment edge cases Thakshinenthra
Use Razorpay test mode only. Never put real keys in the repo.
Email delivery: SMTP setup, templates and failures
Build: Radhakrishnan · Test: Bharath
Invoice and welcome emails need SMTP; without it the app only reports that the email was not sent. This PBI sets up a test inbox, checks every email template looks right with the school's branding, and makes failed emails visible to staff with a way to resend.
Done when
- With SMTP set, invoice, welcome and temporary-password emails arrive and look correct.
- Each email has a plain-text version.
- A failed email is shown on the customer or invoice page with a Resend button.
Tasks
- SMTP setup with a test inbox Radhakrishnan
- Email templates: branding and plain-text versions Radhakrishnan
- Show failed emails and allow resend Radhakrishnan
- Test: emails across clients and failure cases Bharath
Use Mailtrap or Ethereal for testing so nobody real gets an email.
Sign-in security: rate limiting and forgot password
Build: Logu · Test: Radhakrishnan
Both sign-in pages accept unlimited attempts, and neither staff nor students can reset a forgotten password themselves. This PBI adds attempt limits with a short lockout and a forgot-password flow using single-use emailed links.
Done when
- After 5 failed attempts an account and IP are locked for 15 minutes.
- Staff and students can request a reset link from the sign-in page.
- Reset links work once and expire after 30 minutes.
- The response never reveals whether an email exists.
Tasks
- Sign-in attempt limits and lockout Logu
- Forgot password for staff Logu
- Forgot password for portal students Logu
- Tests for lockout and password reset Logu
- Test: sign-in security checks Radhakrishnan
Depends on C4 for sending email; use the test inbox.
API tests for the untested modules
Build: Logu · Test: Divaram
API tests in __tests__/api cover auth, customers, invoices and payments only. This PBI adds tests for LLR, DL, training, scheduling, badges, renewals, referrals and expenses, and for branch scoping, which is a security boundary.
Done when
- Each listed module has API tests for list, create, update, permission denied and feature switched off.
- Branch scoping tests prove pinned staff cannot read or change another branch's records by id.
Tasks
- API tests: LLR and DL Logu
- API tests: training, schedule, instructors and vehicles Logu
- API tests: badges, renewals, referrals and expenses Thakshinenthra
- Branch scoping tests Logu
- Review: API test readability and gaps Divaram
The API tests need the app running (see README.md Scripts).
End-to-end test of the student journey
Build: Divaram · Test: Radhakrishnan
There are no browser tests. This PBI adds Playwright and one long journey that follows a student from admission to certificate across the staff dashboard and the portal, the path described in crm-overview.html.
Done when
- Playwright runs with npm run test:e2e.
- Specs cover admission, LLR, a booked lesson, DL, a payment and invoice, and the portal course, quiz, certificate and public verification.
- The specs run in CI.
Tasks
- Add Playwright with sign-in helpers Divaram
- Spec: admission, LLR and a booked lesson Divaram
- Spec: DL, payment and invoice PDF Divaram
- Spec: portal course, quiz and certificate Divaram
- Review: E2E specs and CI run Radhakrishnan
Run against demo mode so data resets on each run.
Enquiries and lead follow-up
Build: Thakshinenthra · Test: Bharath
A driving school gets most students from walk-ins, calls and referrals, but the CRM only starts tracking someone once they are a customer. This PBI adds enquiries: capture a lead, schedule follow-ups, move it along a simple board, and convert it into a customer with the admission form pre-filled. It is a new switchable feature like the others.
Done when
- Front desk can add an enquiry with name, phone, source, service of interest and branch.
- Enquiries move through New, Contacted, Visited, Converted and Lost on a board and a list.
- Due follow-ups appear on the dashboard and as notifications.
- Converting opens the new-customer form pre-filled and links the two records.
- A report shows enquiries by source and the conversion rate.
- The feature can be switched off in Settings > Features and respects branches and module permissions.
Tasks
- Enquiry tables, migration and demo data Thakshinenthra
- Enquiry API with feature switch, permissions and branches Thakshinenthra
- Enquiries list and status board Thakshinenthra
- Follow-up reminders on the dashboard Thakshinenthra
- Convert an enquiry into a customer Thakshinenthra
- Enquiry source and conversion report Thakshinenthra
- Tests for enquiries Thakshinenthra
- Test: enquiries from first call to admission Bharath
Keep the board simple (no drag-and-drop library); buttons to move status are fine.
Lesson attendance and student progress card
Build: Bharath · Test: Logu
The schedule books lessons but does not record what happened. This PBI lets instructors mark each lesson attended, no-show or cancelled with notes, track a skills checklist per student, and show a progress card to staff and to the student in the portal.
Done when
- Each past lesson can be marked attended, no-show or cancelled, with notes.
- A configurable skills checklist (for example clutch control, reversing, parking, hill start) can be ticked per student.
- Staff see a progress card on the customer page; the student sees it under My schedule.
- A report lists attendance and no-shows per student and instructor.
Tasks
- Mark lessons attended, no-show or cancelled Bharath
- Skills checklist per student Bharath
- Progress card for staff and the portal Bharath
- Attendance report Bharath
- Tests for attendance and skills Bharath
- Test: attendance and progress card Logu
Lives under the existing Scheduling feature switch.