backend

no-dept knowledge debt bot의 Dashboard API + SQS Workers.

로컬에선 FastAPI(uvicorn), 운영에선 AWS Lambda(Mangum 어댑터)로 동일 코드를 실행한다.

사전 준비

• Python 3.11
• uv 설치
• Docker Desktop 실행
• ../shared-schema 디렉토리가 형제 경로에 있어야 함 (의존성)

빠른 시작

# 1. 의존성 설치
uv sync --extra dev
# 2. 환경변수 준비
cp .env.example .env
# 필요 시 GitHub OAuth 값 등 채우기# 3. 로컬 인프라 (DynamoDB Local + Admin UI) 기동
docker compose up -d dynamodb-local dynamodb-admin
# 4. 테이블 생성
uv run python scripts/init_db.py
# 5. (선택) 시드 데이터 — 본인 GitHub 정보로 박으면 OAuth 로그인 시 매칭됨
SEED_GITHUB_USER_ID=<your_github_numeric_id> SEED_GITHUB_LOGIN=<your_login> \
uv run python scripts/seed_dev.py
# 환경변수 미지정 시 userId=1, login=tester 기본값으로 박힘# 6. API 서버 실행 (hot reload)
uv run uvicorn backend.main:app --reload
# 7. 동작 확인
curl http://localhost:8000/health
open http://localhost:8000/docs
open http://localhost:8002

전체를 한 번에 docker로 띄우려면:

docker compose up

디렉토리

src/backend/
├── api/ # FastAPI 라우터 (HTTP 엔드포인트)
├── workers/ # SQS Lambda 핸들러
├── core/ # 공통: config, db, auth, logging
├── services/ # 비즈니스 로직 (채점, decay 등)
└── main.py # FastAPI 앱 + Mangum handler

테스트

uv run pytest # 전체
uv run pytest tests/services -v # 채점기만
uv run pytest --cov=backend # 커버리지

린팅

uv run ruff check
uv run ruff format
uv run mypy src

Lambda 배포

infra 레포의 SAM 템플릿이 본 패키지를 빌드해서 배포한다.

• API Lambda: backend.main:handler (Mangum)
• Quiz Generator Lambda: backend.workers.quiz_generator:lambda_handler

협업 인터페이스

• dashboard ↔ backend: shared-schema의 api/ 모듈 (REST + JSON)
• event-pipeline → backend worker: shared-schema의 messages/sqs.py (SQS 메시지)
• ai-quiz ↔ backend worker: shared-schema의 messages/llm.py (함수 호출)

스키마 변경 시 shared-schema 버전을 먼저 올리고, 본 레포의 의존성을 업데이트.