Identity buckets (Inbox top-level)

Summary

The 12 canonical top-level buckets that group every identity (and every document that hangs off it) in the Inbox left rail. Each bucket has an allowed set of identity_type values (see identity-types), a period key that controls the year axis in the folder tree, and a fixed display order.

Canonical values

Key	Bucket	Allowed identity_types	Period key	Display order
BUCKET.TAX	Tax	virtual — cross-cuts every identity by AY (via denormalised document.ay)	ay	1
BUCKET.BANKS	Banks	bank_savings, bank_current, bank_credit_card, bank_fd	fy	2
BUCKET.EMPLOYER	Employer	employer	ay	3
BUCKET.INVESTMENTS	Investments	broker, mf_amc, bond_issuer, crypto_exchange	fy	4
BUCKET.LOANS	Loans	loan_home, loan_car, loan_personal, loan_education, loan_ev	fy	5
BUCKET.INSURANCE	Insurance	insurance_health, insurance_life, insurance_motor, insurance_home, insurance_travel, insurance_personal_accident	fy	6
BUCKET.HEALTH	Health	health_condition (disease/condition; doctors + prescriptions + reports are entries under it)	event_date	7
BUCKET.ASSETS	Assets	asset_real_estate, asset_precious_metal, asset_vehicle	calendar	8
BUCKET.RETIREMENT	Retirement	retirement_epf, retirement_ppf, retirement_nps, retirement_gratuity	fy	9
BUCKET.BUSINESS	Business	business_entity	fy	10
BUCKET.IDENTITY-DOCS	Identity documents	identity_doc (PAN, Aadhaar, passport, driving licence, voter ID)	none	11
BUCKET.OTHER	Other	other	none	12

Additional canonical values

Key	Value	Last changed
BUCKET.SELF-IS-NOT-A-BUCKET	identity_type = "self" is the login owner's own identity — it does NOT live in any of the 12 buckets. Docs where identity_id = "self" (e.g., Form 26AS, AIS, TIS, ITR-V, PAN/Aadhaar copies) are cross-listed under Tax (via document.ay) or Identity documents (for ID copies).	2026-07-11
BUCKET.TAX-IS-VIRTUAL	The Tax bucket is a view — its documents live physically under Employer / Banks / Investments / Loans / Insurance / Assets identities, and cross-list into Tax when their parsed fields drive an AY (Form 16, interest cert, CG statement, property tax receipt, insurance premium, etc.). Only 26AS / AIS / TIS / ITR-V / challans live under the Self identity as their primary home.	2026-07-11
BUCKET.TREE-DEPTH	Fixed 4 levels: Bucket → Identity → Year → Document. Year level is skipped for identity_doc and other (period_key = none).	2026-07-11
BUCKET.NEEDS-ATTENTION	Virtual thirteenth bucket "⚠ Needs your attention" — surfaces every doc whose status ∈ { pending_identity_confirmation, needs_ocr, needs_classification, pending_password }, regardless of identity. Always shown at the bottom of the left rail.	2026-07-11
BUCKET.ROUTING-KEY	Every identity_type is registered against exactly one bucket. The mapping is a pure function bucketOf(identity_type) → Bucket in packages/shared/src/schemas/buckets.ts. Adding an identity_type requires updating that map + this table.	2026-07-11
BUCKET.YEAR-AXIS-BY-PERIOD-KEY	ay → AY YYYY-YY (April→March, tax-scoped). fy → FY YYYY-YY (also April→March, financial-scoped). calendar → YYYY (Jan→Dec, for property purchase deeds / vehicle RC etc.). event_date → year of the event (health consults, one-off assets docs). none → year level skipped.	2026-07-11

Related

• user-identity-entry — the concept this entity instantiates
• identity-types — the ~31 identity_type variants that fill these buckets
• ledger-entry-types — the entry_type enum grouped by bucket
• inbox-document-types — every parser + its natural bucket
• pillar-inbox — the Inbox surface that renders this tree
• inbox-pillar — Inbox concept
• inbox-folder-taxonomy — superseded by this page
• family-workspace — Pro Family renders the same tree per family member
• 2026-07-11-user-identity-entry-model — the establishing ADR

Sources

• .context/wiki/entities/* § "Identity buckets"
• packages/shared/src/schemas/buckets.ts