Completion Score

Register Completion Score Design Document

1. Overview

This document specifies the design for calculating and tracking completion scores for registers within a registry instance. The completion score indicates the percentage of required fields filled across a register's sections.

2. Concepts

2.1 Register Structure

A Register consists of multiple Sections:

• Sections belong to either the main REGISTER TABLE or child tables

• Each Section contains multiple Fields

• A LIST SECTION is a child section containing multiple records

2.2 Completion Score Calculation

Section Score Calculation:

• Each section has a weightage index

• Section Score = (Filled Fields / Total Fields) × Section Weightage

• For list sections: Total Fields = (fields per record) × (number of records)

Register Completion Score:

• Sum of all section scores

• Ideal Score = Sum of all section weightages

• Actual Score = Sum of all computed section scores

Example:

• 2 sections with weightages 10 and 15

• Ideal Score = 25

• Actual Score = partial sum based on filled fields

2.3 List Section Scoring

For a list section with multiple records:

• Total Fields = (fields per record) × (number of records)

• Filled Fields = sum of filled fields across all records

• Section Score = (Filled Fields / Total Fields) × Section Weightage

Example:

• 4 fields per record, 2 records total

• Record 1: 4/4 fields filled

• Record 2: 2/4 fields filled

• Section Score = [(4+2)/(4×2)] × Weightage = [6/8] × Weightage

3. Constraints

1. Parent Register Exclusion: PARENT-REGISTER sections are excluded from completion score calculations

2. List Section Calculation: For list sections, calculate total available fields as (fields per record × number of records)

4. Data Models

4.1 New Model: g2p_register_section_completion_score

Field	Type	Description
register_id	Integer	Identifies the register
internal_record_id	String	Unique record identifier within register
section_id	Integer	Identifies the section
computed_section_completion_score	Float	Calculated section score
computed_timestamp	DateTime	Timestamp of calculation

4.2 Enhanced Model: g2p_register_section

New Attribute:

• section_weightage (Float) - Weight assigned to this section in completion calculation

4.3 Enhanced Model: g2p_register_definition

New Attribute:

• completion_score_required (Boolean) - Indicates if completion score tracking is required

5. Processing Architecture

5.1 Trigger Events

Completion score computation is triggered when:

• A new REGISTER-RECORD is created (via approval or INTAKE_FORM)

• A REGISTER-RECORD is updated (via approved CHANGE_REQUEST)

• Condition: g2p_register_definition.completion_score_required = TRUE

5.2 Queue Model: g2p_completion_score_computation_queue

Field	Type	Description
internal_record_id	String	Record to compute
register_id	Integer	Associated register
section_id	Integer	Section to compute
compute_status	String	Processing status
compute_processed_timestamp	DateTime	Last processed time
compute_number_of_attempts	Integer	Retry counter

5.3 Processing Pipeline

1. Celery Beat Producer: Retrieves items from queue

2. Celery Worker:

   • Computes section completion scores

   • Inserts/updates g2p_register_section_completion_score

   • Updates queue status and timestamp

6. API Specifications

6.1 Configuration APIs (Staff API)

Register Section Weightage Configuration

• Endpoint: Configure section weightage values

• Resource: g2p_register_section

Register Definition Configuration

• Endpoint: Set completion_score_required flag

• Resource: g2p_register_definition

6.2 Metadata APIs

get_ideal_completion_score_for_register

• Input: register_id

• Output: Sum of all section weightages for the register

get_ideal_completion_score_for_section

• Input: section_id

• Output: Weightage value of the section

6.3 Data APIs

get_computed_completion_score_for_section

• Input: internal_record_id, register_id

• Output: List of section scores with computed values

get_computed_completion_score_for_record

• Input: internal_record_id, register_id

• Output: Total completion score for the record

7. User Interface

7.1 UI Components

WIDGET_COMPLETION_SCORE_SECTION

• Displays section-level progress

• Format: 7.5 / 10 (computed score / ideal score)

• Placement: Within relevant sections in UI schemas

WIDGET_COMPLETION_SCORE_REGISTER

• Displays register-level progress

• Format: 56.5 / 80 (computed score / ideal score)

• Placement: Header section of register view

7.2 Data Flow

1. UI calls Metadata APIs to retrieve ideal scores

2. UI calls Data APIs to retrieve computed scores

3. Widgets render progress indicators for sections and registers

4. Display format: Computed Score / Ideal Score

8. Implementation Summary

Component	Technology	Purpose
Queue Management	Django Model	Track pending computations
Task Processing	Celery Beat + Worker	Async score computation
Data Retrieval	REST APIs	Metadata and data access
UI Rendering	Widgets	Display completion progress