Skip to content

Home

Jump to bottom
ohsuhyeon0119 edited this page May 29, 2026 · 6 revisions

CatCratch

어린이를 위한 블록 코딩 서비스. 블록을 조립해서 캐릭터를 움직이고, AI 에이전트와 대화하며 코딩을 배운다.

서비스 소개

CatCratch는 Scratch/Entry와 같은 블록 코딩 에디터에 AI 코딩 에이전트를 결합한 웹 서비스다.

  • 블록을 드래그앤드롭으로 조립하면 캐릭터가 2D 스테이지 위에서 움직인다
  • AI 에이전트에게 말을 걸면 블록을 직접 조립해주거나, 내 코드를 설명해준다
  • 만든 프로젝트는 저장하고, 링크로 누구에게나 공유할 수 있다

주요 기능

블록 에디터

Scratch 방식의 3패널 레이아웃 [툴박스] | [블록 워크스페이스] | [스테이지]

카테고리 블록
움직임 상하좌우 이동, 좌표 이동, 회전
감지 키보드 입력, 벽 충돌 감지
말풍선 캐릭터 말하기

스테이지

  • HTML5 Canvas 기반 2D 실행 화면
  • 스프라이트 1개 (기본 에셋 라이브러리 제공)
  • 실행 버튼 → 블록을 위에서 아래로 순차 실행

프로젝트 관리

  • 로그인/회원가입 후 프로젝트 저장 및 불러오기
  • 링크 공유 → /play/:id 로 누구나 실행 가능 (편집 불가)

AI 에이전트 (2차 구현)

  • 채팅 패널에서 자연어로 대화
  • 블록 자동 조립 및 현재 프로젝트 설명/디버깅

기술 스택

영역 기술
Frontend React + TypeScript (Vite), Yarn
블록 에디터 Blockly (raw, useEffect DOM inject)
스테이지 HTML5 Canvas
스타일 CSS Modules
상태관리 React Context
Backend Python FastAPI
ORM SQLAlchemy
DB PostgreSQL
Auth JWT
로컬 환경 Docker Compose

아키텍처

image

핵심 데이터 흐름

흐름 경로
블록 실행 Blockly → JS 코드 생성 → Runtime API 바인딩 → Canvas 업데이트
저장 워크스페이스 → JSON → PUT /projects/:id → DB
공유 GET /projects/:id/play (인증 없음) → blocks_json → 실행

Frontend 구조

frontend/src/
├── pages/
│   ├── EditorPage.tsx        # 메인 에디터 (3패널 레이아웃)
│   ├── PlayPage.tsx          # /play/:id 공유 뷰
│   ├── LoginPage.tsx
│   └── DashboardPage.tsx     # 내 프로젝트 목록
│
├── components/
│   ├── BlockEditor/
│   │   ├── BlockEditor.tsx   # useEffect로 Blockly DOM inject
│   │   ├── toolbox.ts        # 블록 카테고리 정의
│   │   └── theme.ts          # 커스텀 Blockly 테마
│   ├── Stage/
│   │   ├── Stage.tsx         # Canvas 엘리먼트 + 렌더링
│   │   └── Sprite.tsx        # 스프라이트 상태 → 화면 반영
│   └── Header/
│
├── blocks/                   # 커스텀 Blockly 블록 정의
│   ├── motion.ts             # 이동, 회전 블록 + 코드 생성기
│   ├── sensing.ts            # 키보드, 충돌 감지 블록
│   └── looks.ts              # 말풍선 블록
│
├── runtime/                  # Canvas 실행 엔진
│   ├── index.ts              # Runtime API (move, say, sense)
│   ├── sprite.ts             # 스프라이트 상태 관리
│   └── executor.ts           # 생성된 JS 실행 (new Function + 타임아웃)
│
├── context/
│   ├── AuthContext.tsx
│   └── ProjectContext.tsx
│
└── api/                      # 백엔드 호출 함수
    ├── auth.ts
    └── projects.ts

블록 → Canvas 연결 구조

blocks/motion.ts    → 블록 UI 정의 + JS 코드 생성 규칙 등록
                          ↓ (Blockly.JavaScript.workspaceToCode)
                       생성된 JS 문자열
                          ↓
runtime/executor.ts → new Function()으로 실행, 무한루프 타임아웃 적용
                          ↓
runtime/index.ts    → move() / say() / sense() 실제 구현
                          ↓
Stage/Sprite.tsx    → Canvas 다시 그리기

스프라이트 에셋: 기본 이미지 파일을 프론트 번들에 포함 (/assets/sprites/)

Backend 구조

backend/app/
├── main.py               # FastAPI 앱 초기화, CORS 설정
├── database.py           # SQLAlchemy 엔진, 세션 관리
├── models/
│   ├── user.py
│   └── project.py
├── schemas/              # Pydantic 요청/응답 스키마
│   ├── auth.py
│   └── project.py
├── routers/
│   ├── auth.py           # /auth/register, /auth/login
│   └── projects.py       # /projects CRUD + /projects/:id/play
└── core/
    └── security.py       # JWT 발급/검증, bcrypt 해싱

API 엔드포인트

Method Path Auth 설명
POST /auth/register ❌ 회원가입 → JWT 반환
POST /auth/login ❌ 로그인 → JWT 반환
GET /projects ✅ 내 프로젝트 목록
POST /projects ✅ 새 프로젝트 생성
GET /projects/:id ✅ 프로젝트 불러오기
PUT /projects/:id ✅ 프로젝트 저장
DELETE /projects/:id ✅ 프로젝트 삭제
GET /projects/:id/play ❌ 공유 플레이어 뷰

Database 스키마

users

컬럼 타입 설명
id UUID (PK)
email VARCHAR unique
username VARCHAR
password_hash VARCHAR bcrypt
created_at TIMESTAMP

projects

컬럼 타입 설명
id UUID (PK)
user_id UUID (FK → users)
title VARCHAR
blocks_json JSONB Blockly 워크스페이스 직렬화 상태
created_at TIMESTAMP
updated_at TIMESTAMP

Clone this wiki locally