Year

1. What is a Year?

The Year entity is a per-course bucket of MCQ counts, scoped to a single calendar year. It exists so the product can show “how many PYQs / DQs / EQs do we have for 2023 in UPSC?“

2. Connection With Other Entities

   ┌────────────┐                          ┌────────────┐
   │   Course   │ ──── scopes ───────────▶ │   YEAR     │
   │ (NEET,UPSC)│  one row per (course,yr) │  bucket    │
   └────────────┘                          └─────┬──────┘
                                                 │
                                          counts │ refreshed
                                                 │ on every
                                                 │ MCQ change
                                                 ▼
                                          ┌────────────┐
                                          │    MCQ     │
                                          │  (year +   │
                                          │ question_  │
                                          │   type)    │
                                          └────────────┘

In plain English: every Course has its own set of Year rows. Each Year row caches counts of MCQs that carry that same year value, split by question type (PYQ / DQ / EQ). Whenever an MCQ with a year is created, edited, or deleted, the corresponding Year row’s counters are recomputed in the background.

Year has no direct link to Taxonomy, Docket, or Block — it is purely a course-level MCQ aggregate.

3. Parameters of a Year

• _id — composite primary key of the form {course_id}_{year} (e.g. 1_2023); guarantees one Year row per course per calendar year
• course_id — the course this year belongs to (NEET, UPSC, etc.); used for scoping and access control
• year — calendar year (e.g. 2023); derived from _id via helper, not stored as a separate field on every record
• pyq_count — total number of PYQ MCQs for this (course, year), across all statuses
• dq_count — total number of DQ MCQs for this (course, year), across all statuses
• eq_count — total number of EQ MCQs for this (course, year), across all statuses
• published_pyq_count — PYQ MCQs in PUBLISHED status only; this is what students see on the year filter
• published_dq_count — DQ MCQs in PUBLISHED status only
• published_eq_count — EQ MCQs in PUBLISHED status only
• status — DRAFT | PUBLISHED | UNPUBLISHED | ARCHIVE; drives visibility on student surfaces and allowed transitions
• is_deleted — soft-delete flag; excluded from reads unless explicitly requested
• created_at / updated_at — epoch-ms timestamps (UTC); updated_at advances on every count refresh
• created_by / updated_by — user IDs (or system for background-task writes)

4. Lifecycle

        ┌──────────┐  publish    ┌────────────┐  unpublish   ┌──────────────┐
 auto-  │  DRAFT   │ ──────────▶ │ PUBLISHED  │ ───────────▶ │ UNPUBLISHED  │
 create │          │             │            │ ◀─────────── │              │
 ─────▶ │          │             │            │   republish  │              │
        └────┬─────┘             └──────┬─────┘              └──────┬───────┘
             │                          │                           │
             │ archive                  │ archive                   │ archive
             ▼                          ▼                           ▼
                              ┌────────────┐
                              │  ARCHIVE   │  (terminal)
                              └────────────┘
                                    │
                                    │ + orthogonal
                                    ▼
                              ┌────────────┐
                              │ soft delete│  (is_deleted=true, reversible)
                              └────────────┘

State	Who sees it	Notes
Draft	Admin only	Auto-assigned default for newly auto-created rows in some flows.
Published	Students (mobile sync, web list)	Visible in year filter dropdowns.
Unpublished	Admin only	Temporarily hidden from students; counts still kept. Can be republished.
Archive	Admin only	Terminal — no transitions out. Year retired from product surfaces.
Soft-deleted	No-one	Orthogonal to status. Recoverable.