본문으로 건너뛰기

JunkBox 시스템 개요

1. 문서 목적​

  • 이 문서는 JunkBox 전체의 지도임. AI와 관리자가 작업 대상 앱·저장소·문서를 가장 먼저 식별하는 데 사용함.
  • 앱·개발 포트·권한 코드·SQLite 파일·운영 서비스명의 목록은 이 문서의 표가 단일 기준임. 다른 가이드는 목록을 반복하지 않고 이 문서를 참조함.
  • 구조 원칙과 공통 계약은 docs/junkbox/common/guide-jb-core.md, 개발 환경과 운영 배포는 docs/junkbox/common/guide-jb-dev-ops.md가 소유함.

2. 프로젝트 정의​

  • JunkBox는 Python 기반 멀티 앱 구조를 사용하는 AI-Native 운영 시스템임.
  • 공통 라이브러리 재사용, API 우선 설계, 운영 허브 집중화, Hub SQLite 공통 저장소, 앱별 SQLite 도메인 저장소, 개발 문서 벡터 캐시를 조합하는 구조를 사용함.
  • 개인 홈서버에서 운영하는 1인 개발·운영 시스템임. 업무 영역마다 독립 앱을 두고, 로그인·권한·마스터데이터·예약 실행·메시지 전달 같은 공통 기능은 전담 앱과 공통 라이브러리에 모음.

2.1 웹·서버와 네이티브 앱 명칭​

  • JunkBox는 웹·서버와 설치형 클라이언트를 포함하는 전체 생태계 명칭임.
  • junkbox는 /home/sleepzz/dev/workspaces/junkbox의 기존 Python·FastAPI·React 기반 웹앱·서버 저장소를 의미함. 이 문서의 apps/*-api, apps/*-ui, libs/*는 해당 저장소 내부 경로임.
  • junkbox-app은 /home/sleepzz/dev/workspaces/junkbox-app의 별도 네이티브 클라이언트 프로젝트를 의미함. 제품 표시 이름은 JunkBox이며 현재 대상 플랫폼은 Android임.
  • Health 웹앱, health-ui, 설치형 Health PWA는 기존 웹 실행 환경을 의미하며 JunkBox 네이티브 앱과 구분함. PWA 설치를 네이티브 앱 설치나 Android 백그라운드 실행 서비스와 동일하게 취급하지 않음.
  • junkbox-app은 별도 저장소의 Android 앱이며 Hub 앱 인증, Health 러닝 계획의 웹→앱 인계, 화면과 독립된 러닝 실행을 구현함. 웹·API와 네이티브 앱의 세부 계약은 docs/junkbox/apps/guide-apps-junkbox-app.md를 따름.

3. 앱 목록​

3.1 웹·서버 앱​

  • 패키지는 junkbox 저장소의 apps/ 하위 폴더명임. 개발 포트는 Vite UI / FastAPI 순서임.
  • SQLite 파일은 모두 호스트 /sorc001/junkbox/db/에 있으며 표의 파일명만 다름.
  • 운영 컨테이너 내부 포트는 모든 Docker 서비스가 8080으로 통일함. 규칙은 공통 개발 환경·운영 배포 가이드의 운영 컨테이너 포트 통일 규칙을 따름.
앱업무 목적패키지개발 포트권한 코드SQLite 파일화면 유형운영 서비스명
Hub공통 로그인·권한, 포털, 운영 대시보드, 마스터데이터·AI 프롬프트 관리, Markdown·북마크·EPUB 오디오북 변환 도구hub-api, hub-ui15001 / 18001HUBhub.sqlite3PC 운영 화면, 모바일 로그인·포털·도구, 겸용 대시보드junkbox-hub
ChessLichess 종료 대국 수집, Stockfish 분석, 복기 코칭, 실시간 대국chess-api, chess-ui15002 / 18002CHESSchess.sqlite3Chess 전용 반응형junkbox-chess
Health근력 운동 기록과 규칙 엔진 운동 계획, 러닝 계획·실행, 체중·투약, 음식 기록health-api, health-ui15003 / 18003HEALTHhealth.sqlite3모바일 전용junkbox-health
Message메시지 채널 전달, 발송 이력·재발송, 예약·정기 메시지 관리 화면message-api, message-ui15004 / 18004MESSAGEmessage.sqlite3모바일 전용junkbox-message
RenameASITE 메타 수집 기반 파일명 변경, Favorites, 작업 로그rename-api, rename-ui15006 / 18006RENAME없음(파일 시스템 JSON)PC 전용junkbox-rename
Automation예약·cron·수동 실행, 재시도, 실행 이력automation-api(API와 worker)없음 / 18007HUB(관리 API)automation.sqlite3화면 없음junkbox-automation-api, junkbox-automation-worker
Track개인 관리 항목의 처리 이력, 선택적 주기와 도래 알림track-api, track-ui15008 / 18008TRACKtrack.sqlite3모바일 전용junkbox-track
WoW레이드 공대원 관리와 WCL 점수, 함께한 공대원 기록, 공대 구인 알림wow-api, wow-ui15009 / 18009WOWwow.sqlite3PC 레이드 화면, 모바일 구인 알림junkbox-wow
BizCard명함 이미지 수집, AI 인식, 수정, 분류bizcard-api, bizcard-ui15010 / 18010BIZCARDbizcard.sqlite3모바일 전용junkbox-bizcard
SipMon음주 세션과 잔 기록, 순수 알코올량과 개인 기준 대비 표시sipmon-api, sipmon-ui15011 / 18011SIPMONsipmon.sqlite3모바일 전용junkbox-sipmon
KnowBit공유 Markdown 자료 기반 지식 카드·퀴즈 학습과 이력knowbit-api, knowbit-ui15012 / 18012KNOWBITknowbit.sqlite3모바일 전용junkbox-knowbit
QuestLogHealth·Chess 기간 집계를 조회한 일간·주간·월간 미션 판정, 직접 입력 커스텀 미션questlog-api, questlog-ui15013 / 18013QUESTLOGquestlog.sqlite3모바일 전용junkbox-questlog
  • Health의 공유 운동 기준정보 관리는 HEALTH와 HUB 권한을 모두 요구함.
  • 앱별 운영 도메인, 기본 진입 경로, 세부 화면은 각 앱 가이드가 소유함.
  • 앱을 추가·삭제하거나 포트·권한 코드·DB 파일·서비스명이 바뀌면 이 표를 먼저 갱신함.

3.2 네이티브 앱​

  • junkbox-app은 별도 저장소의 Android 앱임. Hub 앱 인증, Health 러닝 계획의 웹→앱 인계와 화면에 독립된 러닝 실행, 운동 세트 완료 뒤의 휴식 타이머를 제공함.
  • 웹을 우선하고 백그라운드 지속 실행·음성·기기 연동처럼 웹 제약이 큰 기능만 네이티브로 구현함. 상세 계약은 docs/junkbox/apps/guide-apps-junkbox-app.md를 따름.

4. 공통 라이브러리​

라이브러리책임
shared-core설정, 비동기 DB, 공통 모델, 인증, 예외, KST 일시 유틸, 공통 마스터 데이터 저장소와 소비 클라이언트, 포털 메뉴 조회, TTL 캐시, 헤더 검색 해석
shared-aiAI provider 어댑터, 기능별 모델 라우팅, direct·graph runner, 음성 합성 호출, prompt·graph registry, usage log 기록과 월 사용량 사전 예약, 예외 정규화, 개발 문서 벡터 동기화
shared-ui공통 템플릿과 stylesheet 매크로, Tailwind preset, base / mobile / desktop CSS, 앱 셸, 앱 아이콘, 공통 React 컴포넌트·유틸, 폰트
shared-crawlerHTTP 수집, HTML 파싱, Playwright 브라우저 세션

5. 앱 간 연동​

  • 앱은 서로의 DB 파일을 열지 않고 HTTP API와 service-to-service 인증으로만 연결함. 아래는 현재 연결임.
호출 주체대상연결 내용
Hub 외 모든 웹앱Hub공통 로그인·JWT 세션 검증, 공통코드·메타·AI 프롬프트·포털 메뉴 조회, AI 사용 로그 전달
AutomationMessagenotification.send 작업으로 예약·정기 메시지 전달 요청
AutomationTracktrack.notification-check 작업으로 도래 알림 판정 실행
AutomationChesschess.game-sync 종료 대국 동기화, chess.ai-review 복기 배치 실행
AutomationQuestLogquestlog.finalize-period 작업으로 끝난 기간의 미션 결과 기록 실행
AutomationHubhub.audiobook-convert 작업으로 EPUB 오디오북 변환, hub.pro-wrestling-digest 작업으로 일간 프로 레슬링 뉴스 실행
HubMessage프로 레슬링 뉴스 리포트 링크를 내부 알림 API로 전달
AutomationWoWraid.recruitment-scan, raid.recruitment-deliver-pending, raid.companions-sync 작업 실행
Health, Track, WoWMessage도메인 앱이 조건을 판정한 알림을 Message internal API로 전달
Message UIAutomationMessage API 게이트웨이를 거쳐 예약·정기 메시지 정의를 조회·수정
Chess, WoW, HubAutomation사용자 요청으로 시작하는 AI 복기, 함께한 공대원 수집, 오디오북 변환 실행 등록과 상태 조회
QuestLogHealth, Chess서비스 토큰으로 식단 일별 합계, 활동 횟수, 종료 대국 통계의 기간 집계 조회
호스트 백업 스크립트Message백업 완료 알림 전달
junkbox-appHub, Health앱 인증, 러닝 계획 인계와 진행 반영, 운동 타이머 연결
  • AI 호출은 shared-ai를 거치며 현재 Hub 도구, WoW 공대 구인 분석, BizCard 명함 인식, KnowBit 카드·퀴즈가 사용함. Chess 복기 코칭도 LLM을 사용함.
  • 외부 시스템은 Lichess(Chess), Warcraft Logs(WoW), Apprise(Message), Linkding과 GitHub Vault 저장소(Hub 도구), LiteLLM proxy(LLM·임베딩·Hub 오디오북 음성 합성 등 AI 호출, 음성 합성은 LiteLLM이 Google Cloud Text-to-Speech를 호출), ASITE(Rename)임.

6. 워크스페이스 구조​

junkbox/
├── apps/
│ ├── hub-api/ hub-ui/
│ ├── chess-api/ chess-ui/
│ ├── health-api/ health-ui/
│ ├── message-api/ message-ui/
│ ├── rename-api/ rename-ui/
│ ├── track-api/ track-ui/
│ ├── wow-api/ wow-ui/
│ ├── bizcard-api/ bizcard-ui/
│ ├── sipmon-api/ sipmon-ui/
│ ├── knowbit-api/ knowbit-ui/
│ ├── questlog-api/ questlog-ui/
│ ├── automation-api/
│ └── dev-server-origin.ts
├── libs/
│ ├── shared-core/
│ ├── shared-ai/
│ ├── shared-ui/
│ └── shared-crawler/
├── scripts/
├── docs/
├── ai-outputs/
├── .agents/skills/
├── .vscode/tasks.json
├── justfile
├── AGENTS.md
├── docker-compose.yml
├── docker-compose.prod.yml
├── pyproject.toml
└── uv.lock
  • {app}-api는 FastAPI 백엔드이며 서버 렌더링 HTML 골격 위에 {app}-ui의 빌드 산출물을 서빙함. {app}-ui는 Vite 기반 React + TypeScript 프런트엔드임.
  • scripts/는 로컬 개발 실행, 마스터데이터 조회, 개발 문서 검색·동기화 스크립트를 둠. ai-outputs/는 사용자가 수동 반영할 SQL·Markdown 산출물 위치임.

6.1 네이티브 클라이언트 워크스페이스​

  • 기존 junkbox와 네이티브 클라이언트 junkbox-app은 /home/sleepzz/dev/workspaces 아래 형제 디렉터리임.
  • junkbox-app/apps/android/는 Android Studio 프로젝트 루트이며 앱 소스·Gradle Wrapper·빌드 및 검증 도구를 포함함. 제품 취지·합의·단계별 구현 계획과 AI 인계는 junkbox/docs/junkbox-app/PROJECT-PLAN.md가 소유하고 확장 검토·후속 작업 계획도 같은 폴더에 둠. 앱의 실제 구현·검증·홈 메뉴·배포 문서는 junkbox-app/docs/android/에 유지함.
  • 웹·서버·앱의 AI 작업 창구는 junkbox로 통일하고 junkbox/AGENTS.md와 junkbox/.agents/skills/만 관리함. 앱 저장소에는 별도 에이전트 지침·스킬·후속 작업 프롬프트를 두지 않음. 두 Git 저장소와 GitHub Actions는 각각 유지하며 검색·수정·검증·Git 대상 경로를 저장소별로 구분함.
  • Android 환경은 app-profiles.json의 운영 prodRelease와 개발 devDebug로 명시함. 환경별 이름·패키지·주소·scheme·아이콘 자원을 분리하며 커밋 검토 전 운영 APK를 검증함. 휴대폰 테스트 APK는 JunkBox의 junkbox-app-dev-apk 스킬로 빌드·검증하며 상세 계약은 네이티브 앱 가이드와 앱 docs/android/BUILD-PROFILES.md를 따름.
  • OS별 경로는 apps/<os>/로 구분함. 현재 Android만 대상이며 다른 OS 소스나 멀티플랫폼 공통 엔진을 선행 구현하지 않음.
  • 서버·웹·API·도메인 DB 변경은 junkbox가 소유하고 네이티브 화면·기기 실행 기능은 junkbox-app이 소유함. 두 프로젝트는 소스 직접 import나 DB 파일 공유 대신 API 계약으로 연결하는 책임 경계임.

7. 문서 체계​

  • JunkBox 개발 문서의 원본은 vault/docs/junkbox/**/*.md임. 작성 규칙은 docs/junkbox/common/guide-jb-docs.md를 따름.
폴더내용문서
common/전체 공통 구조·원칙·규칙시스템 개요(이 문서), 코어, 개발 환경·운영 배포, 공통 마스터 데이터, 공통 UI, 문서 작성 규칙
libs/공통 라이브러리의 책임과 사용 규칙shared-core, shared-ai, shared-ui, shared-crawler
apps/앱별 업무 목적, 책임 경계, 데이터, API, 화면앱마다 guide-apps-{app}-api.md와 guide-apps-{app}-ui.md. KnowBit, 네이티브 junkbox-app은 단일 문서
domain/구현과 무관하게 유지되는 업무 지식과 용어Health 운동 전략·운동 기구 사용법·5km 러닝 플랜, Chess 용어집
  • AI 작업 절차와 승인 규칙은 junkbox 저장소의 AGENTS.md와 .agents/skills/가 소유함. Vault 문서는 현재 구조와 의도를 설명함.
  • 네이티브 앱의 계획·검토·인계 문서는 junkbox/docs/junkbox-app/, Android 구현·검증·배포 문서는 junkbox-app/docs/android/가 소유함.