86 lines
3.4 KiB
Markdown
86 lines
3.4 KiB
Markdown
# 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해서 재배포만 수행
|
|
|
|
## 저장소 구조 — 표준
|
|
```text
|
|
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에 일관되게 반영
|