Parents' Paperwork: System Design

Scope and goals

Version 1 turns a family's facts into a personal, correct calendar of deadlines, guides, documents and benefits, shared across siblings. It is software-first: it informs and guides, it never acts on a parent's accounts.

In scope for v1

• Family workspace: parents, siblings, roles, task ownership
• A versioned rules engine that generates each family's deadlines for the Indian tax year (April to March) and long-cycle items
• Guided walkthroughs per task, with step progress shared across the family
• Document vault with status, validity and links to tasks
• Trackers: deposits, insurance, pension, nominees
• Government benefits eligibility per parent
• Reminders by push and WhatsApp; document scanning with extraction
• Emergency card export

Out of scope for v1

• Logging in to bank, tax or government portals for the parent
• Storing passwords, OTPs or full card numbers
• Moving money or recommending investments
• Filing returns or forms on the family's behalf (hand-off to partners only)

Requirements

Functional

Non-functional

Architecture

The rules engine is the centre: rule or fact changes flow through the job queue, which regenerates tasks, schedules reminders and runs extraction. Services and workers share one PostgreSQL database; document images live in encrypted object storage in India.

Data model

Everything hangs off a Family. Facts about parents and their holdings drive rules; rules produce Tasks; Tasks reference Documents. Generated rows always keep the rule version that made them.

Account numbers are never stored in full: masked_ref keeps the last four digits so families can tell holdings apart.

Rules engine

Rules are data, not code. Each rule is a versioned JSON record that a content team edits and reviews; the engine evaluates it against a family's facts to produce tasks. This is the product's moat, so it gets the most care.

Rule schema (example: pensioner life certificate)

{
  "id": "pension.life_certificate",
  "version": 3,
  "applies_when": { "parent.pension_type": { "in": ["central", "state"] } },
  "schedule": {
    "due": "YYYY-11-30",
    "window_opens": [
      { "when": { "parent.age_on": { "date": "YYYY-10-01", "gte": 80 } }, "date": "YYYY-10-01" },
      { "else": "YYYY-11-01" }
    ],
    "recurrence": "yearly"
  },
  "consequence": "Pension paused from December until submitted; paid as arrears.",
  "steps": ["Install AadhaarFaceRD and Jeevan Pramaan", "Keep Aadhaar, PPO and account number ready", "Face scan on a video call", "Save the Jeevan Pramaan ID"],
  "required_doc_types": ["aadhaar", "ppo"],
  "help": ["video_walkthrough", "ippb_doorstep"],
  "source_url": "https://jeevanpramaan.gov.in",
  "reviewed_on": "2026-09-15",
  "owner": "rules-team"
}

How a family's calendar is generated

1. A trigger arrives: a fact changed (new deposit, birthday crossed 75 or 80), a rule version was published, or the nightly sweep runs.
2. The engine loads the family's facts and every active rule, and evaluates applies_when for each parent and holding.
3. For each match it computes due dates and windows for the current and next tax year.
4. It upserts tasks keyed on (family, rule id, subject, period), so reruns never duplicate. Owner, step progress and completion are preserved.
5. Tasks whose rule no longer applies are archived, not deleted, and the family is told why.
6. Reminder jobs are rescheduled for any task whose dates moved.

Versioning and review

• A rule change creates a new version in draft. A second reviewer must approve it against the cited source before publishing.
• Publishing triggers regeneration for affected families, with a changelog line shown in the app (for example: "Forms 15G/15H replaced by Form 121 from 1 April 2026").
• Every rule shows a "reviewed on" date; rules older than 6 months are flagged for review.

Reminders and notifications

Reminders are scheduled jobs created per task and member, sent in the member's own timezone at a sensible local hour (9:00 by default).

1. When a task is created or its dates change, the scheduler writes Reminder rows for each offset: window opens, 30 days, 7 days, 1 day.
2. A worker polls due reminders every minute and skips any whose task is done.
3. Owners get every reminder; other members get only the 7-day and overdue ones, to avoid noise.
4. Delivery goes by push first; WhatsApp (approved message templates) for members who opt in; email as fallback.
5. Each send is logged. A failed send retries 3 times with backoff, then falls to the next channel.
6. If a task is still open 3 days before its due date and has no owner, every member is alerted.

WhatsApp templates contain no sensitive values, only the task name and a deep link, for example: "Dad's life certificate is due 30 Nov. Open the walkthrough."

Document scanning and extraction

A scan becomes a filed document and, where it carries a date, a task, with a person confirming every field.

1. The app captures the image, crops and de-skews it on the device, and uploads it over TLS to object storage in India.
2. An OCR step extracts the text; a classifier predicts the document type (policy, FD receipt, tax notice, bank letter).
3. A field extractor pulls type-specific fields: provider, holder, reference (masked), dates, amounts.
4. Identifiers such as Aadhaar or PAN numbers are masked before the extracted text is stored.
5. The member reviews the pre-filled form; nothing is saved until they confirm.
6. On confirm, the Document row is written and the rules engine runs for that parent, creating any new tasks.

Extraction confidence is stored per field. Low-confidence fields are highlighted in the review form.

Benefits eligibility engine

Schemes use the same condition language as rules, evaluated per parent. The engine only suggests a status; a family member confirms whether a benefit is actually in use.

State schemes are scoped by parent.state_of_residence; v1 launches with central schemes plus Maharashtra. When a parent crosses an age threshold (70, 75, 80), the engine re-evaluates and notifies the family of newly eligible benefits. "Mark in use" by a member is never overwritten by the engine; a conflict is shown as "Check".

Security, privacy and compliance

The design minimises what is stored, and treats each parent as a data principal under India's Digital Personal Data Protection Act, 2023.

API, stack and rollout

API surface (REST over HTTPS, JSON)

Changes made by one member reach others through a WebSocket channel per family.

Suggested stack

Scaling. Load is light and predictable: most work is nightly regeneration and reminder sends, with known peaks in November (life certificates), April (tax declarations) and July (returns). Workers scale out ahead of those months.

Rollout

1. Pilot (Oct 2026 to Apr 2027): WhatsApp plus a spreadsheet, rules applied by hand. Proves demand and the rule set.
2. v1 alpha: app for pilot families, central rules plus Maharashtra benefits, manual scan review.
3. v1 public: automated extraction, paid plans, partner hand-offs.
4. Later: more states, Hindi and regional languages, B2B employer channel.

Open questions

• Which OCR and extraction service meets the India data-residency requirement at acceptable cost?
• How is consent captured from a parent who does not use the app themselves?
• What review turnaround can the rules team commit to when a rule changes mid-season?