System Design Document (SDD) — K-12 STEM & AI Competency Framework Hierarchy

1. Data Schema

The 6-level hierarchy is mapped across 5 database tables in the Cloudflare D1 SQL database:

1.1 cf_domains

Represents the 6 competency domains.

CREATE TABLE cf_domains (
  id TEXT PRIMARY KEY,
  organization_id TEXT NOT NULL REFERENCES iam_organizations(id),
  name TEXT NOT NULL,
  description TEXT,
  icon TEXT,
  color TEXT,
  sort_order INTEGER NOT NULL DEFAULT 0,
  status TEXT NOT NULL DEFAULT 'active'
);

1.2 cf_competency_areas

Represents the competency areas.

CREATE TABLE cf_competency_areas (
  id TEXT PRIMARY KEY,
  domain_id TEXT NOT NULL REFERENCES cf_domains(id) ON DELETE CASCADE,
  organization_id TEXT NOT NULL REFERENCES iam_organizations(id),
  name TEXT NOT NULL,
  description TEXT,
  sort_order INTEGER NOT NULL DEFAULT 0,
  status TEXT NOT NULL DEFAULT 'active'
);

1.3 cf_competencies

Represents the competencies.

CREATE TABLE cf_competencies (
  id TEXT PRIMARY KEY,
  area_id TEXT NOT NULL REFERENCES cf_competency_areas(id) ON DELETE CASCADE,
  organization_id TEXT NOT NULL REFERENCES iam_organizations(id),
  name TEXT NOT NULL,
  description TEXT,
  sort_order INTEGER NOT NULL DEFAULT 0,
  status TEXT NOT NULL DEFAULT 'active'
);

1.4 cf_skills

Represents individual assessable skills.

CREATE TABLE cf_skills (
  id TEXT PRIMARY KEY,
  competency_id TEXT NOT NULL REFERENCES cf_competencies(id) ON DELETE CASCADE,
  organization_id TEXT NOT NULL REFERENCES iam_organizations(id),
  cur_skill_id TEXT REFERENCES cur_skills(id),
  code TEXT,
  name TEXT NOT NULL,
  definition TEXT,
  taxonomy_level TEXT NOT NULL DEFAULT 'apply',
  status TEXT NOT NULL DEFAULT 'active'
);

1.5 cf_indicators

Represents the 5 indicators per skill.

CREATE TABLE cf_indicators (
  id TEXT PRIMARY KEY,
  skill_id TEXT NOT NULL REFERENCES cf_skills(id) ON DELETE CASCADE,
  organization_id TEXT NOT NULL REFERENCES iam_organizations(id),
  cur_indicator_id TEXT REFERENCES cur_indicators(id),
  code TEXT,
  name TEXT NOT NULL,
  description TEXT,
  assessment_criteria TEXT, -- Contains the 3-level Rubric in JSON format
  sort_order INTEGER NOT NULL DEFAULT 0,
  status TEXT NOT NULL DEFAULT 'active'
);

---

2. Indicator Rubric JSON Format

Inside cf_indicators.assessment_criteria, we store the 3-level rubric structured as a JSON array:

[
  {
    "level": 1,
    "name": "Sơ thảo (Novice)",
    "description": "Học sinh hiểu lý thuyết cơ bản và thực hiện được nhiệm vụ dưới sự trợ giúp lớn."
  },
  {
    "level": 2,
    "name": "Đạt yêu cầu (Proficient)",
    "description": "Học sinh tự thực hiện được nhiệm vụ độc lập trong các ngữ cảnh quen thuộc."
  },
  {
    "level": 3,
    "name": "Xuất sắc (Advanced)",
    "description": "Học sinh tự áp dụng sáng tạo, giải quyết lỗi nâng cao hoặc tối ưu hoá hiệu quả."
  }
]

---

3. Endpoints Integration

We introduce a tree-builder endpoint GET /api/cf/framework returning the entire nested structure:

{
  "domains": [
    {
      "id": "dom_comp_thinking",
      "name": "Tư duy Máy tính (Computational Thinking)",
      "areas": [
        {
          "id": "area_decomp",
          "name": "Decomposition (Phân rã bài toán)",
          "competencies": [
            {
              "id": "comp_decomp_basic",
              "name": "Cơ bản về Phân rã",
              "skills": [
                {
                  "id": "sk_decomp_easy",
                  "name": "Phân tích bài toán nhỏ",
                  "indicators": [
                    {
                      "id": "ind_decomp_01",
                      "name": "Xác định các phần tử độc lập",
                      "rubric": [
                        { "level": 1, "description": "Nhận biết được..." },
                        { "level": 2, "description": "Tự chia nhỏ..." },
                        { "level": 3, "description": "Tối ưu phân rã..." }
                      ]
                    }
                  ]
                }
              ]
            }
          ]
        }
      ]
    }
  ]
}

This reduces client-side computation and guarantees atomic layout loading.