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-ui | 15001 / 18001 | HUB | hub.sqlite3 | PC 운영 화면, 모바일 로그인·포털·도구, 겸용 대시보드 | junkbox-hub |
| Chess | Lichess 종료 대국 수집, Stockfish 분석, 복기 코칭, 실시간 대국 | chess-api, chess-ui | 15002 / 18002 | CHESS | chess.sqlite3 | Chess 전용 반응형 | junkbox-chess |
| Health | 근력 운동 기록과 규칙 엔진 운동 계획, 러닝 계획·실행, 체중·투약, 음식 기록 | health-api, health-ui | 15003 / 18003 | HEALTH | health.sqlite3 | 모바일 전용 | junkbox-health |
| Message | 메시지 채널 전달, 발송 이력·재발송, 예약·정기 메시지 관리 화면 | message-api, message-ui | 15004 / 18004 | MESSAGE | message.sqlite3 | 모바일 전용 | junkbox-message |
| Rename | ASITE 메타 수집 기반 파일명 변경, Favorites, 작업 로그 | rename-api, rename-ui | 15006 / 18006 | RENAME | 없음(파일 시스템 JSON) | PC 전용 | junkbox-rename |
| Automation | 예약·cron·수동 실행, 재시도, 실행 이력 | automation-api(API와 worker) | 없음 / 18007 | HUB(관리 API) | automation.sqlite3 | 화면 없음 | junkbox-automation-api, junkbox-automation-worker |
| Track | 개인 관리 항목의 처리 이력, 선택적 주기와 도래 알림 | track-api, track-ui | 15008 / 18008 | TRACK | track.sqlite3 | 모바일 전용 | junkbox-track |
| WoW | 레이드 공대원 관리와 WCL 점수, 함께한 공대원 기록, 공대 구인 알림 | wow-api, wow-ui | 15009 / 18009 | WOW | wow.sqlite3 | PC 레이드 화면, 모바일 구인 알림 | junkbox-wow |
| BizCard | 명함 이미지 수집, AI 인식, 수정, 분류 | bizcard-api, bizcard-ui | 15010 / 18010 | BIZCARD | bizcard.sqlite3 | 모바일 전용 | junkbox-bizcard |
| SipMon | 음주 세션과 잔 기록, 순수 알코올량과 개인 기준 대비 표시 | sipmon-api, sipmon-ui | 15011 / 18011 | SIPMON | sipmon.sqlite3 | 모바일 전용 | junkbox-sipmon |
| KnowBit | 공유 Markdown 자료 기반 지식 카드·퀴즈 학습과 이력 | knowbit-api, knowbit-ui | 15012 / 18012 | KNOWBIT | knowbit.sqlite3 | 모바일 전용 | junkbox-knowbit |
| QuestLog | Health·Chess 기간 집계를 조회한 일간·주간·월간 미션 판정, 직접 입력 커스텀 미션 | questlog-api, questlog-ui | 15013 / 18013 | QUESTLOG | questlog.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-ai | AI provider 어댑터, 기능별 모델 라우팅, direct·graph runner, 음성 합성 호출, prompt·graph registry, usage log 기록과 월 사용량 사전 예약, 예외 정규화, 개발 문서 벡터 동기화 |
shared-ui | 공통 템플릿과 stylesheet 매크로, Tailwind preset, base / mobile / desktop CSS, 앱 셸, 앱 아이콘, 공통 React 컴포넌트·유틸, 폰트 |
shared-crawler | HTTP 수집, HTML 파싱, Playwright 브라우저 세션 |
5. 앱 간 연동
- 앱은 서로의 DB 파일을 열지 않고 HTTP API와 service-to-service 인증으로만 연결함. 아래는 현재 연결임.
| 호출 주체 | 대상 | 연결 내용 |
|---|---|---|
| Hub 외 모든 웹앱 | Hub | 공통 로그인·JWT 세션 검증, 공통코드·메타·AI 프롬프트·포털 메뉴 조회, AI 사용 로그 전달 |
| Automation | Message | notification.send 작업으로 예약·정기 메시지 전달 요청 |
| Automation | Track | track.notification-check 작업으로 도래 알림 판정 실행 |
| Automation | Chess | chess.game-sync 종료 대국 동기화, chess.ai-review 복기 배치 실행 |
| Automation | QuestLog | questlog.finalize-period 작업으로 끝난 기간의 미션 결과 기록 실행 |
| Automation | Hub | hub.audiobook-convert 작업으로 EPUB 오디오북 변환, hub.pro-wrestling-digest 작업으로 일간 프로 레슬링 뉴스 실행 |
| Hub | Message | 프로 레슬링 뉴스 리포트 링크를 내부 알림 API로 전달 |
| Automation | WoW | raid.recruitment-scan, raid.recruitment-deliver-pending, raid.companions-sync 작업 실행 |
| Health, Track, WoW | Message | 도메인 앱이 조건을 판정한 알림을 Message internal API로 전달 |
| Message UI | Automation | Message API 게이트웨이를 거쳐 예약·정기 메시지 정의를 조회·수정 |
| Chess, WoW, Hub | Automation | 사용자 요청으로 시작하는 AI 복기, 함께한 공대원 수집, 오디오북 변환 실행 등록과 상태 조회 |
| QuestLog | Health, Chess | 서비스 토큰으로 식단 일별 합계, 활동 횟수, 종료 대국 통계의 기간 집계 조회 |
| 호스트 백업 스크립트 | Message | 백업 완료 알림 전달 |
junkbox-app | Hub, 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/가 소유함.