SYSTEM BLUEPRINT

학생별 코딩 실습실
입장부터 미리보기·회수까지 화면 흐름

학생과 강사가 한 수업 안에서 보게 될 화면을 순서대로 담았습니다.

스토리보드란?

스토리보드는 서비스의 화면을 실제 모습에 가깝게 미리 그려 보는 문서입니다. 학생과 강사 두 사용자 유형별로, 강의실 입장부터 수업 종료까지의 순서로 배치했습니다.

  1. 학생이 강의실에 입장해 전용 실습실에서 코드를 실행하고 미리보기로 확인하는 흐름
  2. 강사가 20명의 실습실 상태를 보고, 시작 파일을 보내고, 수업 후 한 번에 회수하는 흐름

마지막까지 보시면 생각하고 계신 시스템의 모습이 머릿속에 그려지실 것입니다.

학생 시나리오

입장 한 번으로 시작하는 실습

터미널 명령 없이 버튼만으로 작성·실행·확인까지 이어집니다.

1. 강의실 입장

입장 버튼 한 번
내 실습실 생성

2. 시작 파일 도착

선생님이 보낸 파일이
작업공간에 준비

3. 코드 작성

자동 저장되는
Python 에디터

4. 실행·미리보기

콘솔과 Streamlit 앱을
한 화면에서 확인

5. 끊겨도 이어서

자동 재연결·복구
파일은 그대로

학생 | 화면 01

강의실 입장 · 내 실습실 준비

learn.square.kr/class/2b-07
Square Learning
강의실내 작품질문하기
김서윤
오늘 수업 · 9월 22일 (월) 16:00
7차시 · 날씨 대시보드 만들기
Streamlit으로 기온 그래프와 슬라이더를 만들어 봐요.
입장 17 / 20명 박지훈 강사
받은 시작 파일
main.py1.2KB
data.txt3.4KB
app.py0.8KB
내 실습실 준비 중
72%
입장 확인
김서윤 · 6학년 2반
0.2초
전용 컨테이너 생성
sq-lab-2b-14 · python 3.12
3.8초
시작 파일 전달
main.py · data.txt · app.py
0.6초
미리보기 서버 연결
Streamlit :8501 → 프록시 경로
진행 중
에디터 열기
마지막 저장 위치로 이동
대기
내 컨테이너는 외부에서 직접 접속할 수 없고, 강의실 주소로만 열려요.

[화면 개요 및 목적]

학생이 입장을 누른 순간 그 학생 몫의 실습 공간만 만들어집니다. 미접속 학생 몫은 만들지 않아 서버 비용이 들지 않습니다. 준비되는 몇 초 동안 단계가 보여 학생이 불안해하지 않습니다.

[핵심 기능 로직]

입장 요청 → 컨테이너 생성 → 시작 파일 복사 → 미리보기 연결을 차례로 처리합니다. 실습 공간은 외부에서 직접 열 수 없고 강의실 주소를 통해서만 연결됩니다. 데모 1단계에서 직접 확인할 수 있습니다.

  • 입장 시점 생성
    Docker Engine API
  • 외부 접근 차단
    Traefik 리버스 프록시
학생 | 화면 02

실습 IDE · 실행과 미리보기

learn.square.kr/class/2b-07/lab
Square Learning
강의실내 작품질문하기
김서윤
7차시 · 나만의 날씨 대시보드● sq-lab-2b-14 연결됨자동 저장 16:07:30
초기화 저장00:04 / 00:30 실행 중
학습 콘텐츠 · 3/5
슬라이더로 그래프 바꾸기
st.slider()가 돌려준 값으로 데이터를 걸러 st.bar_chart()에 넣어 보세요.
df[df.month <= month]
파일
7차시
app.py
main.py
data.txt
my_chart.py새 파일
app.pymain.py
1import streamlit as st
2import pandas as pd
3 
4st.title("우리 동네 기온")
5df = pd.read_csv("data.txt")
6print("불러온 행:", len(df))
7 
8month = st.slider("월 선택", 1, 12, 9)
9view = df[df.month <= month]
10st.bar_chart(view, x="month", y="temp")
11st.write(f"{month}월 평균 {view.temp.mean():.1f}°C")
콘솔터미널
▶ app.py 실행 · 16:07:32
불러온 행: 365
stderr · UserWarning: data.txt 12행 기온 값이 비어 있어 건너뜀
미리보기 서버 준비 완료 → 오른쪽 패널
● 실행 중 … 4초 경과
미리보기/lab/2b-14/app
우리 동네 기온
월 선택
9
1
2
3
4
5
6
7
8
9
9월까지 평균 14.9°C
슬라이더를 움직이면 그래프가 바로 바뀌어요.

[화면 개요 및 목적]

요청하신 구성 그대로 좌측 학습 콘텐츠, 중앙 에디터, 하단 콘솔에 우측 Streamlit 미리보기를 더했습니다. 코드와 결과를 한 화면에서 보며 원인을 바로 찾을 수 있습니다.

[핵심 기능 로직]

실행 버튼은 30초가 지나면 자동으로 멈춥니다. print와 오류는 실행 중 바로바로 콘솔에 표시되고, 미리보기는 슬라이더 등 입력까지 그대로 동작합니다. 데모 2·3단계와 연결됩니다.

  • VS Code 수준 편집
    Monaco Editor
  • 실시간 콘솔 출력
    WebSocket 스트림
  • 앱 미리보기
    Streamlit iframe
학생 | 화면 03

연결 끊김 · 자동 복구

learn.square.kr/class/2b-07/lab
Square Learning
강의실내 작품질문하기
김서윤
7차시 · 나만의 날씨 대시보드● sq-lab-2b-14 연결됨자동 저장 16:07:30
초기화 저장1.4초 · 완료 다시 실행
학습 콘텐츠 · 3/5
슬라이더로 그래프 바꾸기
st.slider()가 돌려준 값으로 데이터를 걸러 st.bar_chart()에 넣어 보세요.
df[df.month <= month]
파일
7차시
app.py
main.py
data.txt
my_chart.py새 파일
app.pymain.py
1import streamlit as st
2import pandas as pd
3 
4st.title("우리 동네 기온")
5df = pd.read_csv("data.txt")
6print("불러온 행:", len(df))
7 
8month = st.slider("월 선택", 1, 12, 9)
9view = df[df.month <= month]
10st.bar_chart(view, x="month", y="temp")
11st.write(f"{month}월 평균 {view.temp.mean():.1f}°C")
콘솔터미널
▶ app.py 실행 · 16:07:32
불러온 행: 365
stderr · UserWarning: data.txt 12행 기온 값이 비어 있어 건너뜀
미리보기 서버 준비 완료 → 오른쪽 패널
✓ 종료 코드 0 · 1.4초
미리보기/lab/2b-14/app
우리 동네 기온
월 선택
9
1
2
3
4
5
6
7
8
9
9월까지 평균 14.9°C
슬라이더를 움직이면 그래프가 바로 바뀌어요.
자동 복구 완료7초 걸림
작성하던 코드는
그대로 남아 있어요
연결 끊김 감지
16:12:04 · 무한 반복으로 메모리 한도 512MB 도달
실습실 자동 재생성
16:12:07 · 새 컨테이너 sq-lab-2b-14 · 1/3회
파일 3개 복원 · 다시 연결됨
16:12:11 · app.py 마지막 저장 16:11:58
이어서 실습하기
무엇이 문제였나요?

[화면 개요 및 목적]

와이파이가 잠깐 끊기거나 무한 반복 코드로 실습 공간이 멈춰도 수업이 끊기지 않습니다. 학생은 복구 과정을 보고, 작성하던 파일이 그대로 남은 것을 확인합니다.

[핵심 기능 로직]

끊기면 자동으로 다시 연결하고 놓친 출력을 다시 받습니다. 비정상 종료가 감지되면 새 실습 공간을 만들어 저장된 파일을 붙이며, 반복 실패는 횟수를 제한합니다. 데모 4단계에서 체험합니다.

  • 파일 영구 보관
    Docker named volume
  • 자동 재생성
    헬스체크 · 백오프
강사·운영자 시나리오

20명 수업을 한 화면에서 관리

상태 확인, 자료 전달, 회수, 검수 결과까지 운영 흐름입니다.

1. 수업 열기

반·차시 선택
입장 허용

2. 시작 파일 전달

반 전체 작업공간에
한 번에 전달

3. 상태 확인

학생별 실행·유휴
재생성 여부

4. 일괄 회수

수업 종료 버튼
12시간 자동 종료

5. 검수 확인

수용 기준 통과율
부하 테스트 결과

강사·운영자 | 화면 01

강의실 컨테이너 현황 · 일괄 회수

learn.square.kr/teacher/2b-07
Square Learning
강의실강사 콘솔수업 자료검수
박지훈 강사
6학년 2반 · 7차시 · 16:00 시작
강의실 컨테이너 현황
5초마다 갱신
수업 종료 · 일괄 회수
실행 중
13
유휴
3
자동 재생성
1
미접속 (생성 안 함)
3
김서윤실행중
CPU 34% · 메모리 334MB
이도현실행중
CPU 12% · 메모리 180MB
박하은유휴
CPU 1% · 메모리 103MB
최준우실행중
CPU 57% · 메모리 115MB
정민서미접속
컨테이너 없음
강지호실행중
CPU 22% · 메모리 250MB
조예린재생성
재생성 2/3회
윤시우실행중
CPU 41% · 메모리 383MB
장수아실행중
CPU 18% · 메모리 222MB
임건우유휴
CPU 2% · 메모리 110MB
한지민실행중
CPU 63% · 메모리 157MB
오태윤실행중
CPU 29% · 메모리 299MB
서다은미접속
컨테이너 없음
신유찬실행중
CPU 15% · 메모리 201MB
권나연실행중
CPU 38% · 메모리 362MB
황민재실행중
CPU 9% · 메모리 159MB
안소율유휴
CPU 1% · 메모리 103MB
송재원실행중
CPU 26% · 메모리 278MB
류하린미접속
컨테이너 없음
전우진실행중
CPU 44% · 메모리 404MB
무입력 12시간 자동 종료 예정: 오늘 없음 · 최근 종료 9월 21일 (일) 04:12 · 2개호스트 CPU 31% · 메모리 11.4GB / 32GB

[화면 개요 및 목적]

강사가 교실 자리 배치처럼 20명의 실습 공간 상태를 봅니다. 한 학생이 자원을 많이 쓰거나 재생성 중이어도 다른 학생은 정상으로 표시되고, 수업이 끝나면 버튼 하나로 모두 회수합니다.

[핵심 기능 로직]

상태 조회 API로 5초마다 갱신합니다. 회수는 강사 일괄 회수와 12시간 무입력 자동 종료 두 방식이며, 회수해도 학생 파일은 보관되어 다음 입장 때 복원됩니다.

  • 학생별 자원 한도
    cgroups CPU·메모리·PID
  • 회수 2방식
    회수 API · 유휴 타이머
강사·운영자 | 화면 02

실습 시작 파일 전달 · API 연동

learn.square.kr/teacher/2b-07/files
Square Learning
강의실강사 콘솔수업 자료검수
박지훈 강사
7차시 시작 파일
main.py1.2KB
data.txt3.4KB
app.py0.8KB
seoul_temp_2025.csv48KB
대상 반
6학년 2반6학년 1반5학년 3반
덮어쓰기 규칙
학생이 고친 파일은 유지 모두 새 파일로 교체
3개 파일 전달하기
전달 완료
17명
입장 시 전달 예정
3명
오늘 API 호출
1,284
서비스 연동 API 기록인증 토큰 · 반별 권한 확인 후 처리
POST/v1/classrooms/2b-07/files2023.4KB · 17명 전달16:02:11
POST/v1/classrooms/2b-07/enter201김서윤 · 컨테이너 생성16:01:48
GET/v1/classrooms/2b-07/status200실행 13 · 유휴 316:01:45
POST/v1/classrooms/2b-07/enter200이도현 · 기존 볼륨 복원16:01:39
POST/v1/classrooms/2b-06/recall409이미 회수됨15:58:02
DELETE/v1/classrooms/2b-06/containers20218개 회수 시작15:50:00

[화면 개요 및 목적]

차시별 시작 파일(.py, .txt 등)을 반 전체에 한 번에 보냅니다. 아직 입장하지 않은 학생에게는 입장하는 순간 전달됩니다. 기존 서비스와 주고받는 기록도 함께 확인합니다.

[핵심 기능 로직]

입장·상태 조회·회수·파일 전달을 서비스 연동 API로 제공하고 명세 문서로 넘깁니다. 이미 회수된 반에 다시 요청하는 등 잘못된 호출은 명확한 응답으로 막습니다.

  • 서비스 연동
    Fastify REST API · OpenAPI
  • 반별 권한 확인
    토큰 인증
강사·운영자 | 화면 03

검수 리포트 · 20명 동시 접속

learn.square.kr/admin/acceptance
Square Learning
강의실강사 콘솔수업 자료검수
박지훈 강사
주간 진행 공유 · 11월 17일 (월)
수용 기준 검수 리포트
PDF 내려받기
수용 기준 통과율
87%
47개 중 41개 통과
20명 동시 입장 준비 시간
p95 7.4초
실행 결과 첫 출력
p95 0.8초
무한 루프 1명 · 옆 학생 지연
+0.1초
기준별 결과 · 이번 주 변경분
R3실행 버튼 · 30초 초과 시 자동 중단31.0초에 종료통과
R6입장 학생만 컨테이너 생성미접속 3명 생성 0건통과
R9비정상 종료 후 자동 재생성평균 6.2초통과
R11외부 인바운드 차단직접 포트 접속 0건 성공통과
R8네트워크 단절 후 자동 재연결Wi-Fi 끊김 시나리오 작성 중진행중
R10무입력 12시간 자동 종료시각 기준 수정 후 재검미통과
설치 문서 운영·장애 대응 문서 소스 이관 (12월 3주)k6 · 가상 학생 20명 × 40분

[화면 개요 및 목적]

요구사항 시트의 수용 기준을 하나씩 테스트로 바꿔 매주 통과율을 공유합니다. 12월 말 검수 전에 어떤 항목이 남았는지 미리 보이므로 일정 위험을 일찍 알 수 있습니다.

[핵심 기능 로직]

가상 학생 20명이 동시에 입장·실행하는 부하 시나리오와, 무한 반복 코드가 옆 학생에게 주는 영향을 수치로 기록합니다. 설치·운영 문서와 소스 이관 여부도 같은 화면에서 챙깁니다.

  • 20명 동시 접속 검증
    k6 부하 테스트
  • 넘겨받는 운영
    설치·운영 문서
시나리오

| 화면 01

[화면 개요 및 목적]

[핵심 기능 로직]

    | 화면 02

    [화면 개요 및 목적]

    [핵심 기능 로직]

      | 화면 03

      [화면 개요 및 목적]

      [핵심 기능 로직]