Architecture

커리큘럼 레지스트리

Product content boundary for built-in YAML curricula.

curricula/는 Codaro가 기본 제공하는 학습 콘텐츠의 제품 자산 루트다. 문서 사이트에 넣는 읽기 자료가 아니라, 서버와 에디터가 읽어서 학습 셀 카드와 실행 가능한 notebook cell로 전개하는 YAML 소스다.

기본 구조:

curricula/
  python/
    schema.yaml
    30days/
    pandas/
    numpy/
    practical/
    ...

경계

따라서 curricula/를 docs/ 아래에 넣지 않는다. 공개 사이트에서 커리큘럼 목록을 보여줘야 하면 curricula/를 읽어 인덱스를 생성하고, 설명 문서만 docs/skills/architecture에 둔다.

기본 커리큘럼 루트는 curricula/python이다.
YAML은 yamlToDocument 변환기를 통해 document/cell 구조로 materialize된다.
커리큘럼 표면은 YAML의 type, title, description, content, cards, tips, videos, rows, code를 보존해 다양한 학습 셀 카드로 렌더링한다.
물리 셀 타입은 markdown과 code를 기본으로 유지하고, 학습 의미는 role, displayKind, executionKind, payload에 둔다.
AI가 채팅에서 만든 임시 curriculum YAML도 같은 변환기를 통과한다.
study.yaml 파일명과 /study/... URL은 기존 콘텐츠 포맷과 라우트 계약이므로 폴더명 변경과 별개로 유지한다.
built-in 레슨의 외부 패키지는 meta.packages에 둔다. 기본 프로젝트 의존성은 제품 실행용 최소 패키지로 유지하고, 학습 패키지는 레슨을 열거나 실행할 때 uv preflight로 준비한다.
트랙의 00_*소개.yaml은 단순 소개가 아니라 해당 과정을 통해 만들 수 있는 산출물, 필요한 패키지 준비, 첫 실행 검증, 이후 로드맵을 보여주는 오리엔테이션이어야 한다.

커리큘럼 목록은 평면 카테고리 나열이 아니라 카테고리 트리로 노출한다.
built-in 카테고리 트리의 SSOT는 curricula/python/__init__.py의 categoryTree다. backend studyLoader.py의 CATEGORY_TREE와 editor fallback/bundled registry는 이 값을 소비하거나 미러링하는 호환 레이어다.
editor fallback/bundled registry는 같은 트리 이름을 유지한다: Python 기초, 데이터 분석, 시각화, 수학·통계·ML, 자동화, 이미지·비전.
/api/curriculum/categories는 categories[].track, categories[].path, groups, tree를 함께 내려준다.
제품 사이드바는 tree를 먼저 렌더링하고, 없을 때만 groups를 fallback으로 쓴다. 선택된 leaf category 안에서 lesson을 펼친다.
자동화는 자동화 > 브라우저 자동화 > Playwright처럼 하위 분야를 명시한다. OS 자동화, 업무 자동화, 텍스트 자동화, 테스트 자동화처럼 분야가 갈라질 수 있으므로 새 자동화 트랙은 자동화 바로 아래에 평면으로 추가하지 않고 적절한 하위 노드에 둔다. 아직 콘텐츠가 없는 하위 노드는 API 계약에는 둘 수 있지만, 제품 사이드바에서는 실제 카테고리가 생길 때 노출한다.
새 카테고리는 기본 진입 경로를 하나만 가져야 한다. 같은 레슨을 다른 분야에서 보여줘야 하면 category를 중복 배치하지 않고 추천/관련 학습 링크로 연결한다.

Codaro 커리큘럼은 브라우저 전용 Python이 아니라 로컬 Python 커널을 기준으로 작성한다.
builtins 작성 기준은 curricula/python/basics/builtins/LOCAL_RUNTIME_COMPATIBILITY.md에 둔다.
과거 Pyodide 기준 문서는 삭제하지 않고 레거시 링크 포인터로 유지하며, 현재 source of truth는 LOCAL_RUNTIME_COMPATIBILITY.md다.
표준 라이브러리 레슨은 tempfile 같은 안전한 실습 경로를 사용하고, 저장소 루트에 .txt/.csv/로그 산출물을 만들지 않는다. 파일 삭제/외부 프로세스/네트워크 예제는 실행 영향과 복구 절차를 설명해야 한다.
커리큘럼 예제가 루트 상대 경로에 쓰는 순간 제품 workspace가 더러워지므로, 파일 입출력 학습은 임시 디렉터리나 명시적 scratch 경로를 만든 뒤 그 안에서 읽고 쓴다.