--- title: Blueprint description: AI-native workspace, Claude Agent SDK, MCP 클라이언트, 멀티테넌트 web UI. --- # Blueprint **한 줄 소개**: 인간 운영자와 AI 에이전트가 함께 일하는 통합 워크스페이스. Next.js + Claude Agent SDK 로 13종 에이전트 실행, frame · stream · magnet MCP 서버를 도구로 호출. ## 기술 스택 | 항목 | 값 | |---|---| | 언어 | TypeScript | | 프레임워크 | Next.js 16 (App Router) + React 19 | | 스타일 | Tailwind CSS 4 + `@axe/ui` 디자인 토큰 (`/Users/axe/axelabs/src/lib/`, sync 됨 → `src/app/_axe-ui/`) | | DB | PostgreSQL 16 (Prisma 6.19) — D-config-17 cutover 2026-05-15. SQLite 는 historical (cutover 이전 `prisma/data/blueprint.db`) | | 인증 | NextAuth 4 + Microsoft Entra ID (Azure AD) | | 에이전트 | `@anthropic-ai/claude-agent-sdk` 0.2.92 | | 실시간 | Socket.IO 4.8 (port 3101 WebSocket) | | 터미널 | node-pty 1.1 (PTY) | | MCP 클라이언트 | `@anthropic-ai/sdk` 0.82 (HTTP/SSE transport) | ## 포트 | 포트 | 용도 | |---|---| | 3100 | Next.js dev / production HTTP | | 3101 | Socket.IO WebSocket | | 3180 | Caddy 외부 노출 (HTTPS) | ## 디렉토리 구조 ``` /Users/axe/blueprint/ ├── src/ │ ├── app/ Next.js App Router │ │ ├── layout.tsx │ │ ├── page.tsx landing │ │ ├── onboard/ 가입 흐름 │ │ ├── axe/ 대시보드 (admin, agents, issues, projects, skills, team, trinity) │ │ └── api/ 93+ route.ts │ │ ├── auth/[...nextauth] │ │ ├── agents/ │ │ ├── sessions/ │ │ ├── workspaces/ │ │ ├── graph/ Microsoft Graph API proxy │ │ └── teams-graph-* Teams 통합 │ ├── lib/ │ │ ├── auth.ts NextAuth + Azure AD │ │ ├── anthropic-client.ts │ │ ├── customers.ts customers.yaml reader (mtime cache) │ │ ├── mcp/ │ │ │ └── frame.ts frame HTTP MCP 등록, ~21개 tool wrapping │ │ ├── agents/ │ │ │ └── execution-service.ts │ │ └── teams/ │ ├── server/ │ │ └── websocket.ts Socket.IO + PTY (port 3101) │ └── prisma/ │ └── schema.prisma Member / User / Agent / Session / Issue ├── docker/ │ └── docker-compose.yml └── docs/ ├── project-blueprint.md 47KB master doc (5 분과) └── project-blueprint/ ├── division1-org.md ├── division2-tech.md ├── division3-ops.md ├── division4-claude-code.md └── division5-risk-governance.md ``` ## 데이터 모델 (요약) ``` Entity (axec / axev / sys — D-bp-entity-3 NOT NULL) ├─ slug UNIQUE (axec | axev | sys | …) ├─ name 한국어 정식 명칭 (hive shared.entity.legal_name mirror, D-bp-entity-4) ├─ kind "corporate" | "system" | "fund" | … ├─ bizNo 사업자등록번호 (D-bp-entity-5, hive mirror) ├─ fiscalYearStartMonth 1-12 (KR default 1) ├─ countryCode ISO 3166-1 alpha-2 (KR default) └─ workspaces[] 1:N Member (인간/에이전트 통합) ├─ User (email, aadObjectId, role: admin|member, │ entityScopes: JSON ["axev","axec"] — D-bp-entity-8 raw 순서, │ defaultEntity: 사용자별 명시적 default — D-bp-entity-7, │ ownedBy: 본인 owner FK (AI agent ↔ human, D-bp-entity-9)) │ └─ EntityRole[] per-(user, entity) 권한 grant (D-bp-entity-17, │ role: admin|owner|member, grantedById audit) └─ Agent (agentId by SDK, memberId) Workspace (PARA row — Project/Area/Resource/Archive) ├─ entityId → Entity (NOT NULL — D-bp-entity-3, General bucket 폐기) ├─ paraLayer ParaLayer enum {PROJECT, AREA, RESOURCE, ARCHIVE} ├─ sourceWorkspaceId / sourceArtifactPath / copiedAt (D-bp-entity-2 fork provenance) └─ Session (mode: chat|terminal|hybrid|agent) ├─ Messages └─ TerminalSessions Issue ├─ assignee:Member └─ reporter:Member AppSetting (key-value, frame_mcp_token 회전 저장) OperatorAlert (D-bp-alert-1, L2 silent-drop 영구 기록) ├─ source 처리 진입점 (e.g. processChatBundle) ├─ chatId / messageId ├─ primaryError / ackError ├─ createdAt └─ acknowledgedAt / acknowledgedBy (NULL = unresolved) MailSendLog (D-bp-mcp-mail-1, 2026-05-29 — send_mail append-only audit; migration 20260529120000_add_mail_send_log) ├─ callerEmail 인증된 caller (MCP token email claim) ├─ sentAs 실제 발신 mailbox (caller, 또는 send-as target) ├─ subject ├─ toCount / ccCount / bccCount / attachmentCount (주소 자체는 미저장) ├─ status "sent" | "dry_run" | "failed" ├─ messageId Graph sendMail 202 no-body → null ├─ httpStatus / error └─ createdAt index: createdAt / (callerEmail, createdAt) McpSchema (D-bp-artifact-1, 2026-05-23 — schema discovery cache) ├─ service ← 'frame' | 'hive' | 'magnet' | 'stream' | … ├─ schemaId ← 'frame.balance@1.0' (@version suffix 포함) ├─ envelopeVersion ← MCP /schemas envelope.version ├─ body ← JSONB { description, produced_by, key_fields, … } ├─ fetchedAt ← @updatedAt — 매 fetch 마다 갱신 ├─ firstSeenAt ← 첫 발견 시점 └─ @@unique([service, schemaId]) 새 version = 새 row, body 변경 = drift warn OAuth* (D-axe-idp-1, 2026-06-03 — Blueprint = 플랫폼 OIDC Provider; src/lib/platform-oidc.ts) ├─ OAuthAuthCode 단발 authorization code (PKCE S256, 10분 TTL, atomic 소비) ├─ OAuthRefreshToken 회전 refresh token (sha256 hash 만 저장, revokedAt/rotatedTo) └─ OAuthClient RFC 7591 DCR 동적 클라이언트 (loopback/downstream) — axe-cli 는 정적 Artifact (D-bp-artifact-1, 2026-05-23 — typed fact unit) ├─ id ← cuid PK ├─ schemaId ← 'frame.balance@1.0' or 'freeform.llm@auto' — McpSchema lookup ├─ workspaceId ← Workspace FK (CASCADE delete) ├─ entityId ← cached from Workspace.entityId ├─ paraLayer ← cached from Workspace.paraLayer ├─ content ← JSONB — typed payload per schemaId ├─ citations ← JSONB array — 6-kind discriminated union │ (onedrive / frame.* / hive.* / teams.message / │ mail.thread / external.web) ├─ confidence ← Decimal(3,2) 0.00 ~ 1.00 (default 1.0) ├─ auditTrail ← JSONB array — append-only event log │ (propose / confirm / reject / edit / dispatch / │ archive / restore) ├─ parentArtifactId ← self-FK — sub-Project chain + dispatch fork ├─ createdAt / updatedAt / archivedAt └─ index: workspaceId / (entityId, paraLayer) / schemaId / parentArtifactId / archivedAt ArtifactLink (D-bp-artifact-6, 2026-05-23 — multi-parent reference) ├─ artifactId ← Artifact FK (CASCADE delete) ├─ workspaceId ← Workspace FK (CASCADE delete) ├─ linkType ← 'reference' | 'sub_project' | 'cross_link' ├─ linkedAt ← @default(now()) ├─ linkedById ← User FK (SetNull on user delete — preserve audit) └─ PK (artifactId, workspaceId) 같은 artifact 동일 workspace 중복 link 차단 ``` ### entity scope flow `User.entityScopes` 는 sign-in 콜백 (`auth.ts` → `hydrateEntityScopesForUser`) 가 [customers.yaml](https://github.com/soohunkang/blueprint/blob/main/src/lib/entity-scopes.ts) `user_entity_map` + `default_entities_by_domain` 에서 hydrate. admin 이 customers.yaml 미명시 시 DB 의 모든 Entity slug fallback (lock-out 방지). 각 `/api/workspaces/*` 라우트가 `requireWorkspaceEntityAccess` 로 entity gate 검증 (D-bp-entity-3: nullable early-out 제거, 모든 workspace 명시적 entity). `User.defaultEntity` (D-bp-entity-7): hydration 시 null + non-empty scopes → scopes[0] 자동 set. scope 외 default → scopes[0] fallback. TopNav 의 fallback chain (D-bp-entity-8) = URL `?entity=` → localStorage `axe:lastEntity` → `defaultEntity` → `entityScopes[0]` → "all". createWorkspace fallback = opts.entitySlug → drivePath segment → defaultEntity → entityScopes[0] → throw. 사용자 변경 endpoint = `PATCH /api/user/default-entity { slug }` (server-side `entityScopes.includes(slug)` 검증). D-bp-entity-8 정정: hydrate 가 raw `customers.yaml` 순서 보존 (이전 alphabetic sort 폐기) — yaml list 순서가 진정한 default SOT. ### EntityRole (D-bp-entity-17, 2026-05-22) entityScopes 가 entity 가시성만 표현하는 한계 해결. `EntityRole { userId, entitySlug, role: admin|owner|member }` 가 entity 별 3-tier 권한 SSOT. hierarchy `admin > owner > member` 를 `src/lib/entity-roles.ts` 의 `hasEntityRole(userId, slug, min)` / `requireEntityRole(...)` 로 평가. tenant-wide `User.role='admin'` (Soohun/ai@) 은 모든 entity 에 implicit admin (row 없어도 bypass — admin fallback 정신 계승). Hydration 정책: signIn 콜백이 `hydrateEntityRolesForUser` 호출 — entityScopes 에 새로 들어온 slug 마다 `member` 행 자동 생성, scope 에서 제거된 slug 의 행은 revoke. owner/admin overlay 는 오직 `/axe/admin/users` 에서 tenant admin 이 grant (PATCH `/api/users/[id]/entity-roles { entitySlug, role: admin|owner|member|none }`). MCP scope 매핑 (내부 API `GET /api/internal/entity-roles?email=...`, HMAC bearer `BLUEPRINT_INTERNAL_API_KEY`): admin/owner → hive `[read,write,approve,admin]` · frame `[read,write,close,admin]`; member → `admin` 제외 동일 set; row 없음 → 빈 set (entity 비노출). hive/frame OIDC RP 측 연동은 PR 2/3 에서 별도 결정. ### owned account switching (D-bp-entity-9, 2026-05-22) `User.ownedBy` — owner (human) → owned (AI agent identity, e.g. ai@/cfo@) 관계. 운영자 1 인이 본인 + agent 여러 identity 운영하는 패턴. switch flow: 1. owner 가 TopNav 의 **사용자 이름 (button)** 을 클릭 → popover 메뉴 펼침 (D-bp-entity-12) 2. owned account 선택 시 `POST /api/auth/switch-account { targetUserId }` → server-side `target.ownedBy === caller.userId` 검증 3. httpOnly cookie `axe:active-user-id` set + reload 4. session callback (`src/lib/auth.ts`): 매 read 마다 cookie 발견 시 ownership 재검증 → `session.user.*` (id/email/name/role/entityScopes/defaultEntity) 모두 target 로 override. JWT 의 authenticated identity 는 untouched (audit trail 보존) 5. revert = 메뉴 에서 self 선택 → 동일 endpoint (no-op, dropdown 즉시 close) `/api/auth/owned-accounts` GET = dropdown options 채움 (caller + ownedUsers). `isImpersonating=true` 시 trigger button lime border + label color + tooltip. mid-session ownership revoke 시 자동 revert (매 session read 재검증). admin role 도 bypass 불가 — owned-only. **D-bp-entity-12 (TopNav UX)**: 사용자 이름 자체가 dropdown trigger (M365/Gmail 패턴). 별도 `