jarca-ledger-mcp/docs/project-structure.md

Dashboard 관리자 인증 프로젝트 구조

목적과 경계

Dashboard 진입점 앞의 인증 경계, 인증 구현, 기존 page view, test와 배포 설정의 책임 및 단방향 의존을 정의한다.

• 포함 경계: dashboard/, Dashboard 인증 test, 환경 예시, Compose와 인증 설계 문서
• 제외 경계: MCP adapter·server 인증, 가계부 application·SQLite schema 변경

디렉터리 구조

dashboard-runtime — Dashboard runtime

dashboard/
├── app.py
├── authentication.py
├── common.py
└── page_views/

경로	종류	책임	공개 진입점	내부 구현 경계	편집 정책	생성 주체
dashboard/app.py	Streamlit 진입점	page config 후 인증 gate를 호출하고 인증된 요청만 기존 Dashboard로 dispatch	main()	인증 정책 세부 구현을 포함하지 않음	DB 경로 취득 전 gate 유지	수동
dashboard/authentication.py	인증 모듈	환경변수 설정, constant-time 검증, 실패 지연, session·로그아웃과 event log	require_dashboard_authentication()	가계부 DB·gateway·page view에 의존하지 않음	credential 비보존과 fail-closed 유지	수동
dashboard/common.py	Dashboard 공통 지원	DB 경로, UI와 gateway helper	기존 함수	인증 상태를 결정하지 않음	인증된 dispatch 이후 사용	수동
dashboard/page_views/	화면 모듈	기존 금융 조회·쓰기·import UI	각 page_* 함수	인증 구현에 역방향 의존하지 않음	app.py의 인증된 dispatch로만 공개	수동

dashboard-tests — Dashboard 인증·회귀 test

tests/
├── test_dashboard_authentication.py
├── test_dashboard_authentication_app.py
└── test_dashboard_app.py

경로	종류	책임	공개 진입점	내부 구현 경계	편집 정책	생성 주체
tests/test_dashboard_authentication.py	단위 test	설정·constant-time 비교·지연·비민감 log 검증	pytest	실제 credential과 운영 DB 금지	test-only 값 사용	수동
tests/test_dashboard_authentication_app.py	Streamlit 통합 test	fail-closed, 우회 금지, 1초 지연, session과 logout 검증	pytest AppTest	synthetic fixture만 사용	acceptance criterion 대응 유지	수동
tests/test_dashboard_app.py	기존 기능 회귀 test	인증 후 핵심 page 호환성 검증	pytest AppTest	synthetic fixture만 사용	로그인 후 기존 assertion 유지	수동

deployment-docs — 배포 설정과 계약 문서

.env.example
docker-compose.yml
README.md
docs/
├── requirements/req-001_dashboard-administrator-authentication.md
├── interface-contract.md
├── project-structure.md
└── runtime-flow.md

경로	종류	책임	공개 진입점	내부 구현 경계	편집 정책	생성 주체
.env.example	설정 예시	credential 변수 이름과 용도	.env 복사	실제 secret 값 금지	빈 값만 제공	수동
docker-compose.yml	local deployment	Dashboard container로 host secret 환경변수 전달	Compose service	MCP service credential 계약 변경 금지	required-variable interpolation으로 누락 시 시작 거부	수동
README.md	운영 안내	설정, fail-closed, 보호 범위와 rate-limit 제약	사용자 문서	실제 secret 값 금지	구현과 함께 갱신	수동
docs/ 인증 문서	정본 계약	요구사항·인터페이스·구조·흐름	Markdown	데이터 모델 문서 생성 없음	harness template 구조 유지	gitea-agent impl workflow

의존 방향

출발 영역	대상 영역	허용 여부	규칙	공유 계약 위치
dashboard-app	dashboard-authentication	허용	DB 경로와 page dispatch보다 먼저 gate 호출	docs/runtime-flow.md
dashboard-authentication	dashboard-common	금지	인증은 가계부 DB·gateway와 독립	docs/interface-contract.md
dashboard-authentication	dashboard-page-views	금지	인증 모듈은 page view를 import·호출하지 않음	docs/interface-contract.md
dashboard-app	dashboard-common	인증 후 허용	gate가 참일 때만 DB/UI helper 사용	docs/runtime-flow.md
dashboard-app	dashboard-page-views	인증 후 허용	gate가 참일 때만 선택 page dispatch	docs/runtime-flow.md
dashboard-page-views	dashboard-authentication	금지	page별 인증 분기나 역방향 의존을 만들지 않음	docs/requirements/req-001_dashboard-administrator-authentication.md
dashboard-authentication	mcp-adapter	금지	이번 인증은 MCP를 보호하지 않음	README.md

변경 규칙

구분	규칙
새 모듈·파일 배치	Dashboard 공통 인증은 dashboard/authentication.py, page 기능은 기존 dashboard/page_views/에 둔다.
이름·패키지	환경변수는 JARCA_DASHBOARD_ prefix, 비공개 session key는 _jarca_dashboard_ prefix를 사용한다.
소스·테스트 대응	인증 pure helper는 test_dashboard_authentication.py, Streamlit 경계는 test_dashboard_authentication_app.py, 기존 page 호환성은 test_dashboard_app.py에서 검증한다.
생성 산출물	DB schema·migration·credential file을 생성하지 않는다. Requirement와 설계 문서만 docs/에 추가한다.

검증

• 구조 검사 명령:

  python -c "from pathlib import Path; required=['dashboard/app.py','dashboard/authentication.py','tests/test_dashboard_authentication.py','tests/test_dashboard_authentication_app.py']; assert all(Path(p).is_file() for p in required)"
  

• 구조 검사 기대 결과: exit code 0이며 모든 인증 source·test 경로가 존재한다.

• 정적 분석 명령:

  uv run --extra dashboard --extra dev ruff check dashboard tests
  

• 정적 분석 기대 결과: 새 syntax·undefined-name 오류가 없다.

• 문서와 실제 트리의 정합성: base-to-worktree 변경 파일을 본 문서의 세 영역과 대조하고 docs/data-model.md와 DB migration이 생성되지 않았는지 확인한다.