{"id":50412323,"url":"https://github.com/cskwork/math-item-os","last_synced_at":"2026-05-31T04:04:55.338Z","repository":{"id":350358110,"uuid":"1203895438","full_name":"cskwork/math-item-os","owner":"cskwork","description":"Next.js + FastAPI monorepo for math item authoring, search, assignments, analytics, and AI solve/generate workflows.","archived":false,"fork":false,"pushed_at":"2026-04-17T16:06:45.000Z","size":1347,"stargazers_count":0,"open_issues_count":85,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-17T17:29:24.601Z","etag":null,"topics":["ai","edtech","education","fastapi","hwp","katex","knowledge-graph","korean","latex","math","nextjs","question-bank","sympy","typescript"],"latest_commit_sha":null,"homepage":"https://github.com/cskwork/math-item-os","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cskwork.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-07T13:42:58.000Z","updated_at":"2026-04-15T08:31:23.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/cskwork/math-item-os","commit_stats":null,"previous_names":["cskwork/math-item-os"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/cskwork/math-item-os","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cskwork%2Fmath-item-os","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cskwork%2Fmath-item-os/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cskwork%2Fmath-item-os/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cskwork%2Fmath-item-os/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cskwork","download_url":"https://codeload.github.com/cskwork/math-item-os/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cskwork%2Fmath-item-os/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33718496,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-31T02:00:06.040Z","response_time":95,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","edtech","education","fastapi","hwp","katex","knowledge-graph","korean","latex","math","nextjs","question-bank","sympy","typescript"],"created_at":"2026-05-31T04:04:54.459Z","updated_at":"2026-05-31T04:04:55.329Z","avatar_url":"https://github.com/cskwork.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n# Math Item OS\n\n### HWP to HTML Math Question Platform\n\n**HWP(한글) 수학 문서를 웹으로. 추출, 변환, 분석, 추천까지 한 번에.**\n\n[![TypeScript](https://img.shields.io/badge/TypeScript-5.7-3178C6?logo=typescript\u0026logoColor=white)](https://www.typescriptlang.org/)\n[![Next.js](https://img.shields.io/badge/Next.js-15-000000?logo=next.js)](https://nextjs.org/)\n[![Python](https://img.shields.io/badge/Python-3.11+-3776AB?logo=python\u0026logoColor=white)](https://python.org/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](CONTRIBUTING.md)\n\n[English](#english) | [한국어](#한국어)\n\n\u003c/div\u003e\n\n---\n\n## English\n\n### The Problem\n\nKorean math teachers and educational institutions store thousands of math problems in **HWP (Hangul Word Processor)** files -- a format that is nearly impossible to search, analyze, or reuse on the web. Converting math formulas manually is painful and error-prone.\n\n### The Solution\n\n**Math Item OS** extracts math items from HWP documents, converts them to structured HTML with LaTeX rendering, and provides AI-powered analysis including similarity detection, prerequisite mapping, and personalized assignment recommendations.\n\n```\nHWP Document --\u003e Extract \u0026 Parse --\u003e Structured HTML + LaTeX --\u003e Knowledge Graph --\u003e Smart Recommendations\n```\n\n### Key Features\n\n| Feature | Description |\n|---------|-------------|\n| **HWP-to-HTML Conversion** | Automatic extraction of math problems with LaTeX formula preservation |\n| **Knowledge Graph** | Map relationships between concepts, prerequisites, and skills |\n| **AI Similarity Search** | Find similar problems using vector embeddings and semantic analysis |\n| **Auto-Generation** | Generate new variants of existing problems using SymPy |\n| **Quality Workflow** | Multi-stage review pipeline: Draft \u003e Review \u003e Approved \u003e Retired |\n| **Assignment Engine** | Recommend personalized assignments based on student skill levels |\n| **Multi-Tenant** | Organization-level data isolation with role-based access control |\n\n### Architecture\n\n```mermaid\ngraph TB\n    subgraph Client\n        A[Next.js 15 + React 19\u003cbr/\u003eKaTeX Rendering]\n    end\n\n    subgraph API[\"API Layer\"]\n        B[tRPC 11\u003cbr/\u003eType-Safe RPC]\n        C[Auth.js v5\u003cbr/\u003eRBAC]\n    end\n\n    subgraph Services\n        D[Item Service]\n        E[Search Service]\n        F[Embedding Service]\n        G[Assignment Engine]\n    end\n\n    subgraph AI[\"Math AI Service\"]\n        H[FastAPI + SymPy\u003cbr/\u003eFormula Validation]\n        I[Sentence Transformers\u003cbr/\u003eSimilarity Analysis]\n        J[Problem Generator]\n    end\n\n    subgraph Infra[\"Infrastructure\"]\n        K[(PostgreSQL 17\u003cbr/\u003epgvector + ltree)]\n        L[(Redis 7\u003cbr/\u003eCache + Queue)]\n        M[(Meilisearch 1.12\u003cbr/\u003eFull-Text + Vector)]\n    end\n\n    A --\u003e B --\u003e C --\u003e Services\n    Services --\u003e AI\n    Services --\u003e Infra\n    AI --\u003e K\n```\n\n### Quick Start\n\n```bash\ngit clone https://github.com/cskwork/math-item-os.git\ncd math-item-os\n\n# Install dependencies\npnpm install\n\n# Start infrastructure (PostgreSQL, Redis, Meilisearch)\ndocker compose up -d\n\n# Set up environment\ncp .env.example .env\n\n# Run database migrations\npnpm db:migrate\n\n# Start development server\npnpm dev\n```\n\nOpen [http://localhost:3000](http://localhost:3000)\n\n### Requirements\n\n- Node.js \u003e= 20.0.0 / pnpm 9.15+\n- Docker \u0026 Docker Compose\n- Python 3.11+ (for Math AI service)\n\n### Project Structure\n\n```\napps/web/                 # Next.js 15 full-stack application\n  src/app/                # App Router pages (dashboard, search, admin)\n  src/server/routers/     # tRPC API routers\n  src/server/services/    # Domain services (23 services)\npackages/\n  db/                     # Prisma 6 schema + PostgreSQL client\n  math-parser/            # LaTeX formula parsing \u0026 KaTeX rendering\n  shared/                 # Shared types, validators (Zod), constants\nservices/\n  math-ai/                # Python FastAPI + SymPy microservice\ndocs/                     # Architecture, ERD, development guides\n```\n\n### Tech Stack\n\n| Layer | Technology |\n|-------|-----------|\n| **Frontend** | Next.js 15, React 19, Tailwind CSS v4, KaTeX 0.16 |\n| **API** | tRPC 11, Zod validation |\n| **Auth** | Auth.js v5, RBAC (Admin / Reviewer / Teacher) |\n| **Database** | PostgreSQL 17 (pgvector, pg_trgm, ltree) |\n| **ORM** | Prisma 6 |\n| **Search** | Meilisearch 1.12 (full-text + vector) |\n| **Queue** | BullMQ + Redis 7 |\n| **AI/Math** | FastAPI, SymPy 1.13, Sentence Transformers |\n| **Build** | Turborepo, pnpm workspaces |\n| **Test** | Vitest (unit), Playwright (E2E) |\n\n### Commands\n\n| Command | Description |\n|---------|-------------|\n| `pnpm dev` | Start development server |\n| `pnpm build` | Production build |\n| `pnpm test` | Run tests |\n| `pnpm lint` | Lint check |\n| `pnpm db:migrate` | Run database migrations |\n| `pnpm db:studio` | Open Prisma Studio |\n\n### Contributing\n\nContributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.\n\n1. Fork the repository\n2. Create your feature branch (`git checkout -b feat/amazing-feature`)\n3. Commit your changes (`git commit -m 'feat: add amazing feature'`)\n4. Push to the branch (`git push origin feat/amazing-feature`)\n5. Open a Pull Request\n\n### License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n---\n\n## 한국어\n\n### 문제\n\n한국의 수학 교사와 교육 기관은 수천 개의 수학 문제를 **HWP(한글) 파일**에 보관합니다. HWP 형식은 웹에서 검색, 분석, 재사용이 거의 불가능하며, 수학 공식을 수동으로 변환하는 작업은 고되고 오류가 잦습니다.\n\n### 해결책\n\n**Math Item OS**는 HWP 문서에서 수학 문항을 추출하고, LaTeX 렌더링이 포함된 구조화된 HTML로 변환합니다. AI 기반 유사 문항 탐색, 선수 학습 매핑, 맞춤형 과제 추천까지 지원합니다.\n\n### 주요 기능\n\n| 기능 | 설명 |\n|------|------|\n| **HWP-to-HTML 변환** | 수학 문제 자동 추출 및 LaTeX 수식 보존 |\n| **지식 그래프** | 개념, 선수 학습, 스킬 간 관계 매핑 |\n| **AI 유사 문항 검색** | 벡터 임베딩 + 의미 분석 기반 유사 문항 탐색 |\n| **문항 자동 생성** | SymPy 활용 기존 문항의 변형 자동 생성 |\n| **품질 관리 워크플로우** | 초안 \u003e 검토 \u003e 승인 \u003e 폐기 다단계 리뷰 |\n| **과제 추천 엔진** | 학생 역량 기반 맞춤형 과제 추천 |\n| **멀티테넌트** | 조직 단위 데이터 격리 + 역할 기반 접근 제어 |\n\n### 빠른 시작\n\n```bash\ngit clone https://github.com/cskwork/math-item-os.git\ncd math-item-os\npnpm install\ndocker compose up -d\ncp .env.example .env\npnpm db:migrate\npnpm dev\n```\n\n[http://localhost:3000](http://localhost:3000) 에서 확인하세요.\n\n### 문서\n\n- [시스템 아키텍처](docs/architecture.md)\n- [ERD (엔티티 관계 다이어그램)](docs/erd.md)\n- [개발 워크플로우](docs/speckit-workflow.md)\n\n---\n\n\u003cdiv align=\"center\"\u003e\n\n**Math Item OS**는 한국 수학 교육의 디지털 전환을 위한 오픈소스 프로젝트입니다.\n\nStar를 눌러 프로젝트를 응원해주세요!\n\n\u003c/div\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcskwork%2Fmath-item-os","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcskwork%2Fmath-item-os","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcskwork%2Fmath-item-os/lists"}