hanarang-dashboard/ARCHITECTURE.md

ARCHITECTURE.md — 하나랑 대시보드

목표

하나랑 대시보드는 4자매 멀티에이전트 운영 상태, 프로젝트 진행, QA 결과, 배포 상태를 한눈에 보여주는 관제 대시보드야. 이 문서는 현재 런타임 구조와, 이번 Sprint 014에서 반영할 Hermes 전환/문서 구조 개편 기준을 함께 정리해.

핵심 원칙

• 하랑은 코드 직접 수정하지 않고 문서/오케스트레이션만 담당
• main은 항상 배포 가능 상태를 유지
• 나랑 구현 → 다랑 QA → 하랑 main merge → 이랑 main pull + 재배포 순서를 고정
• 문서가 코드보다 먼저 올라가야 함
• 런타임/문서 구조 변경 시 한 번에 끊지 말고 호환 구간을 둠

시스템 아키텍처

1) Control Plane

• Frontend: frontend/ (Next.js 16 + styled-components)
• Backend: backend/ (Nest.js + Prisma)
• DB: MariaDB
• Gitea 연동: repo / branch / commit / PR / plan 문서 tree 조회

2) Agent Plane

• 하랑: Orchestrator / Planner
• 나랑: Generator / Developer
• 다랑: Evaluator / QA
• 이랑: Infra / Deploy

3) Execution Plane

• 각 자매 노드는 Hermes 기반 워크스페이스를 사용
• 기존 OpenClaw 경로를 일부 유지하던 코드는 Hermes 경로를 우선 지원해야 함
• 이번 개편에서 다음 경로를 기본값으로 삼음
  • workspace: ~/.hermes/workspace
  • sessions: ~/.hermes/sessions
  • agents: ~/.hermes/workspace/agents
  • avatars: ~/.hermes/avatar.(png|jpg|jpeg|webp)
• 단, 이행 기간 동안은 .openclaw 경로도 fallback으로 함께 읽어야 함

배포/운영 흐름

1. 하랑이 .plans/, ARCHITECTURE.md, docs/를 먼저 작성하고 push
2. 나랑이가 feature/hotfix branch에서 구현 후 push
3. 다랑이가 같은 branch를 pull해서 QA 수행, .plans/qa/에 결과 md 작성 후 push
4. 하랑이가 QA 결과를 확인하고 main으로 merge
5. main은 즉시 배포 기준 브랜치가 됨
6. 이랑이는 별도 수정 없이 최신 main을 pull해서 재배포만 수행

저장소 구조 — 표준

hanarang-dashboard/
├── AGENTS.md
├── ARCHITECTURE.md
├── README.md
├── .plans/
│   ├── OVERVIEW.md
│   ├── design/
│   │   ├── index.md
│   │   ├── DESIGN-SYSTEM.md
│   │   ├── architecture.md
│   │   ├── api-design.md
│   │   ├── db-schema.md
│   │   └── ui/
│   ├── sprints/
│   ├── hotfix/
│   ├── qa/
│   └── deploy/
├── docs/
│   ├── product-specs/
│   ├── references/
│   ├── tech-debt-tracker.md
│   └── QUALITY_SCORE.md
├── frontend/
└── backend/

Sprint 014 이행 규칙

• Backend는 다음 두 구조를 동시에 읽을 수 있어야 함
  • 기존: .plans/sprints/, .qa/, .openclaw/...
  • 신규: .plans/sprints/, .plans/hotfix/, .plans/qa/, .hermes/...
• Frontend 프로젝트 페이지는 Sprint / Hotfix / QA / Deploy 흐름을 기준으로 다시 구성
• 네비게이션에서 프로젝트는 두 번째 위치로 고정

이번 개편의 직접 목적

• Hermes 전환 때문에 전체 자매가 offline으로 보이는 문제 해결
• 자매 프로필 이미지 fallback 체계 정리
• 변경된 파일 구조에 맞춘 프로젝트 진행률/이력/핫픽스 UI 재설계
• main = deployable 원칙을 코드/문서/UI에 일관되게 반영