ProcessCenter 전체 시스템 아키텍처
문서 상태: 코드·배포 설정 기준 정리
대상 시스템: ProcessCenter
기준 브랜치:
main작성 목적: 프로세스 계층 관리, L5 Workflow, PortalConsole 인증, PostgreSQL 운영, 컨테이너 기반 배포를 포함한 전체 시스템 구조를 하나의 기술 문서로 정의한다.
1. 문서 개요
ProcessCenter는 조직의 프로세스 체계를 계층적으로 관리하고, L5 단위의 실행 흐름과 L6 Task·조건분기·승인 정책을 시각적으로 구성하는 웹 애플리케이션이다. 사용자는 프로세스 트리에서 L1부터 L5까지의 노드를 탐색하고, 각 프로세스의 설명·책임자·RACI·용어·공지·승인 정책·워크플로우를 관리한다.
시스템은 React 기반 단일 페이지 애플리케이션과 Express 기반 API 서버를 하나의 Node.js 런타임에서 제공한다. API 호출은 tRPC를 중심으로 구성하며, 데이터 접근은 Drizzle ORM을 통해 PostgreSQL을 사용한다. 중앙 인증이 활성화된 운영 환경에서는 PortalConsole가 사용자 인증과 포털 권한의 기준 시스템이 된다.
2. 아키텍처 요약
| 영역 | 현재 구성 | 주요 책임 |
|---|---|---|
| 사용자 인터페이스 | React 19, Vite, Tailwind CSS, Radix UI, portal-foundation | 프로세스 트리, 상세 화면, 관리 화면, L5 Workflow 편집 및 시각화 |
| 웹 서버 | Express 4 | 정적 파일 제공, API 라우팅, 인증 엔드포인트, 헬스체크 및 런타임 부트스트랩 |
| API 계층 | tRPC 11 | 타입 안전한 query·mutation, 보호 절차와 관리자 절차, 도메인 라우터 조합 |
| 애플리케이션 서비스 | 도메인 서비스·Repository 분리 | 프로세스 변경, 워크플로우 변경, 승인·권한·감사·코드 정규화 |
| 데이터 접근 | Drizzle ORM | PostgreSQL 스키마 매핑, 트랜잭션, 마이그레이션, 동시성 제어 |
| 주 데이터베이스 | PostgreSQL | 프로세스 메타데이터, 사용자·권한, 워크플로우, 공지, 승인, 이력, 런타임 설정 |
| 인증 | PortalConsole OAuth/OIDC 계열 연동 + PKCE | 중앙 로그인, state 검증, authorization code 교환, 세션 쿠키 발급 |
| 파일 저장 | Managed Forge presigned upload 또는 R2 계열 provider | 프로필·프로세스·디렉터리 미디어 저장 |
| AI/RAG | Private AI/RAG 선택 연동 | 내부 임베딩·검색·LLM 기반 보조 기능 |
| 배포 | Docker multi-stage(자체 호스팅·관리형 클라우드 공통) | 빌드·런타임 분리, node dist/index.js 실행, 실패 재시작 |
3. 시스템 컨텍스트
브라우저는 ProcessCenter의 정적 애플리케이션을 로드한 뒤 tRPC 클라이언트를 통해 API를 호출한다. 서버는 인증 세션을 확인한 후 도메인 서비스와 Repository를 거쳐 PostgreSQL을 조회·변경한다. 파일 자체는 애플리케이션 서버에 저장하지 않고 설정된 스토리지 공급자의 presigned URL 흐름을 사용한다.
4. 런타임 구성
4.1 프론트엔드
프론트엔드는 client/src 아래에서 관리되는 React SPA이다. 라우팅은 Wouter를 사용하고, 서버 상태와 tRPC 호출은 TanStack React Query 기반 클라이언트를 통해 처리한다. UI는 Radix UI와 Tailwind CSS를 바탕으로 구성하며, 내부 공통 UI 패키지인 @hohyun94/portal-foundation을 사용한다.
주요 화면은 프로세스 트리·프로세스 상세, 사용자·권한 관리, 포털 런타임 설정, 승인·공지 관리, 용어 관리, L5 Workflow 편집기와 캔버스이다. L5 Workflow 캔버스는 내부 L5/L6 단계, START·END, gateway·condition, 외부유입 L5를 하나의 흐름으로 표시하며, 외부유입 카드의 실제 DOM 경계를 측정해 SVG 연결선의 접점을 계산한다.
4.2 웹 서버와 API
서버 진입점은 빌드 후 dist/index.js이며, Express 앱이 정적 프론트엔드와 API를 함께 제공한다. tRPC 라우터는 도메인별로 분리된다.
| 라우터 | 책임 |
|---|---|
admin | 사용자·역할·관리자용 운영 기능 |
approvals | 승인 정책 및 승인 대상 관리 |
flow | L5 Workflow 단계·전환·외부유입·조건분기 |
notices | 공지사항과 포털 표시 콘텐츠 |
processes | 프로세스 노드·책임자·계층 관리 |
rag | 검색·RAG 보조 기능 |
runtimeSettings | 인증 모드·배포 프로필·PortalConsole 설정 |
절차는 공개 접근이 필요한 기능, 로그인 사용자를 위한 protectedProcedure, 관리자 권한이 필요한 adminProcedure로 구분된다. 변경 작업은 Repository 직접 호출보다 서비스 계층을 우선 사용하여 검증·권한·감사·트랜잭션 정책을 한 곳에서 적용한다.
4.3 애플리케이션 서비스와 Repository
서비스 계층은 도메인 규칙과 여러 Repository의 조합을 담당한다. 대표적으로 processMutationService는 프로세스 생성·수정과 책임자 교체를 처리하고, workflowMutationService는 단계·전환·gateway·condition의 변경과 외부 L5 연결을 처리한다. processCodeNormalizationService는 레거시 코드 정규화와 PostgreSQL 초기화 시 데이터 보정에 사용된다.
Repository 계층은 processRepository, workflowReadRepository, workflowWriteRepository, userRepository, roleRepository, approvalRepository, historyRepository 등으로 분리된다. 이 구조는 SQL·ORM 접근과 도메인 규칙을 분리하고, 워크플로우 읽기 모델과 쓰기 모델을 독립적으로 최적화할 수 있게 한다.
5. 데이터 아키텍처
5.1 핵심 도메인 모델
processNodes는 L1~L5 계층을 표현하는 기준 엔티티이며, parentId를 통해 조직·프로세스 트리를 구성한다. L5 Workflow는 workflowSteps와 workflowTransitions로 표현된다. 단계의 kind는 process, gateway, condition, start, end 등으로 구분되고, 전환은 source·target 단계와 outcome·label·condition expression을 가진다.
외부유입 연결은 현재 L5의 워크플로우에 다른 L5의 단계가 진입하는 관계이다. 외부 L5는 현재 워크플로우의 일반 단계와 동일한 선행 엔티티 의미를 가지지만, 자기 자신을 source로 저장하거나 자기 L5 대표 프록시를 중복 생성해서는 안 된다. 조회 모델은 잘못 생성된 자기 대표 프록시가 화면에 다시 나타나지 않도록 방어한다.
5.2 PostgreSQL 호환성 원칙
운영 데이터베이스는 PostgreSQL을 기준으로 한다. ORM·SQL 작성 시 MySQL 전용 함수와 문법을 사용하지 않으며, advisory lock은 PostgreSQL의 pg_try_advisory_xact_lock을 사용한다. 마이그레이션·초기 데이터 보정·RAG 결과 파싱은 PostgreSQL 반환 타입과 NULL 의미를 기준으로 검증한다.
다음 원칙을 유지한다.
| 원칙 | 적용 |
|---|---|
| 트랜잭션 범위 | 데이터 변경과 관련 이력·연관 데이터 변경을 가능한 동일 트랜잭션에서 처리 |
| 동시성 | 코드 정규화와 중복 방지 작업에 트랜잭션 advisory lock 사용 |
| 타입 명시 | PostgreSQL 함수 인자와 JSON·배열·날짜 타입을 명시적으로 처리 |
| 기본값 | 애플리케이션 기본값과 DB 기본값을 불일치시키지 않음 |
| 마이그레이션 | drizzle.config.postgres.ts와 db:postgres:migrate를 운영 기준으로 사용 |
| 재시도 | 일시적 트랜잭션 충돌이나 연결 오류에 제한적인 transaction retry 적용 |
6. 인증과 권한
6.1 PortalConsole 로그인 흐름
로그인 엔드포인트는 저장된 포털 런타임 설정의 PortalConsole origin과 portal ID를 사용한다. 요청 시 생성한 state와 PKCE verifier는 짧은 만료 시간을 가진 HttpOnly 쿠키에 저장한다. callback에서는 code, state, verifier, 만료 시간을 검증하고, PortalConsole에서 반환한 포털 식별자와 관리자 권한을 확인한다.
인증이 성공하면 PortalConsole 사용자 ID를 기반으로 ProcessCenter 사용자를 upsert하고, 포털 관리자 claim에 따라 애플리케이션 역할을 설정한다. 이후 ProcessCenter 세션 쿠키가 발급된다. /auth/callback과 /api/auth/callback을 모두 지원해 배포 플랫폼의 rewrite 차이를 흡수한다.
6.2 권한 모델
권한은 중앙 인증의 사용자 식별과 ProcessCenter의 애플리케이션 역할을 결합한다. 전역 관리자 기능은 adminProcedure로 보호하며, 프로세스별 책임자·관리자 권한은 프로세스 노드와 사용자 간 할당 데이터로 관리한다. 포털별 관리자 권한은 PortalConsole의 포털 claim과 ProcessCenter의 권한 조회 모델을 함께 고려해야 한다.
민감한 작업은 다음 검증을 거친다.
- 세션이 유효한지 확인한다.
- 대상 포털과 사용자의 포털 범위를 확인한다.
- 관리자 또는 해당 프로세스 변경 권한을 확인한다.
- 입력값의 ID·레벨·관계·중복·순환 참조를 검증한다.
- 변경 결과와 필요한 감사 이력을 트랜잭션으로 저장한다.
7. 주요 업무 흐름
7.1 프로세스 계층 관리
사용자는 프로세스 트리에서 대상 노드를 선택한다. 서버는 계층·코드·부모 노드·표시 순서·책임자·RACI 정보를 조회하고, 수정 시 코드 중복·레벨 관계·권한을 검증한다. 사용자 책임자 정보는 PortalConsole 식별자를 저장하여 중앙 디렉터리의 사용자 이름과 애플리케이션의 프로세스 책임 관계를 분리한다.
7.2 L5 Workflow 관리
L5 Workflow는 단계와 전환을 별도로 저장한다. 일반 L5 엔티티, L6 엔티티, gateway, condition, START·END 단계는 각각의 workflowStep으로 관리되며, 전환은 source와 target 사이의 관계로 저장된다.
외부유입 L5는 현재 L5 Workflow 안의 선행 엔티티 후보로 노출된다. 사용자가 특정 외부 L5를 선택하면 서버는 외부 L5의 실제 단계 또는 분기 단계를 사용하고, 현재 L5와 source L5가 동일한 자기 참조는 차단한다. 화면의 외부유입 카드는 일반 L5 카드와 동일한 크기와 기본 박스 규칙을 사용하며, 외부 연결이라는 의미는 카드 라벨과 점선으로만 표현한다.
화살표는 SVG 경로로 그리되, 외부유입 카드와 SVG의 실제 DOM 사각형을 측정해 시작점의 X 중앙과 Y 하단을 계산한다. 도착점은 후행 도형의 상단 경계로 계산한다. 이 방식은 헤더 구분선이나 캔버스 고정 Y값을 엔티티로 잘못 취급하는 문제를 방지한다.
7.3 L4 통합 워크플로우 맵
L4 워크플로우 맵은 L4 단위로 새로운 연결을 수동 작성하는 별도 모델이 아니라, 해당 L4의 직속 하위 L5 워크플로우를 실제 데이터에서 조합한 읽기 전용 통합 뷰다. 각 L5는 독립적인 lane 안에 자신의 L6·START·END·의사결정·조건분기와 내부 전환을 그대로 표시한다. L5 간 연결은 각 L5 워크플로우에 실제로 등록된 외부유입·외부전달 전환을 집계하여 점선 handoff로 표현한다.
flow.getIntegrated는 현재 L4의 직속 L5 목록을 조회한 뒤, 각 L5의 workflowSteps와 workflowTransitions를 함께 반환한다. 이어서 각 L5의 inbound transition을 조사해 source L5도 동일 L4에 속하는 관계만 handoff로 포함한다. 따라서 수동 l4WorkflowEdges 테이블에 새 선을 별도로 만들지 않아도, L5 화면에서 만든 실제 업무 연결이 L4 상위 맵에 자동 반영된다.
| 표시 요소 | 데이터 원천 | 시각 규칙 |
|---|---|---|
| L5 lane | L4 직속 processNodes | L5 코드·명칭을 헤더로 표시 |
| 내부 단계 | 각 L5의 workflowSteps | L6·START·END·의사결정·조건분기 모양을 유지 |
| 내부 전환 | 각 L5의 workflowTransitions | 실선 직교 화살표 |
| L5 간 handoff | 실제 외부유입 transition 집계 | 파란 점선 화살표와 handoff 라벨 |
| 상세 목록 | 집계된 handoff | source L5 → target L5와 결과 상태·조건 표시 |
7.4 파일·미디어 흐름
파일 업로드는 서버가 presigned URL을 발급하거나 관리형 Forge 업로드 흐름을 중계하고, 브라우저가 대상 스토리지에 직접 업로드하는 구조를 우선한다. 업로드 후에는 파일 URL·메타데이터·대상 엔티티 관계를 애플리케이션 DB에 기록한다. 서버 로컬 디스크를 영속 저장소로 사용하지 않으므로 컨테이너 인스턴스 교체에도 파일 관계가 유지된다.
8. 배포 아키텍처
Dockerfile은 dependencies, build, runtime의 multi-stage 구조를 사용한다. dependencies 단계에서 pnpm install --frozen-lockfile을 실행하고, build 단계에서 프론트엔드와 서버를 함께 빌드한다. runtime 단계에는 node_modules, package.json, dist, drizzle만 복사하며 비특권 사용자 processcenter로 실행한다.
운영 호스트에서는 build command로 의존성 설치와 빌드를 수행하고, start command는 node dist/index.js를 사용한다. 런타임 컨테이너에서 pnpm을 다시 실행하지 않으므로 이전의 런타임 pnpm 실행 파일 누락 문제를 피한다. 실패 시 재시작 정책은 최대 10회 재시도를 사용한다.
8.1 운영 환경 변수
| 변수 | 용도 | 운영 원칙 |
|---|---|---|
DATABASE_URL | PostgreSQL 접속 문자열 | 호스트 secret으로 관리 |
DATABASE_DIALECT | DB 방언 선택 | 운영에서는 postgresql로 명시 |
PORTAL_CONSOLE_ORIGIN | PortalConsole 기본 연결 주소 | 운영에서는 HTTPS 사용 |
PORTAL_CONSOLE_PORTAL_ID | 인증 대상 포털 ID | 저장된 포털 설정과 일치시킴 |
PORTAL_CONSOLE_API_KEY | 서버 측 PortalConsole API 인증 | 브라우저에 노출하지 않음 |
DEPLOYMENT_PROFILE | CLOUD(기본) 또는 ON_PREM | 플랫폼 자동 감지 없이 운영에서 명시 |
PROFILE_STORAGE_PROVIDER | managed 또는 스토리지 provider 선택 | 영속 스토리지 사용 |
BUILT_IN_FORGE_API_URL | 관리형 파일 업로드 연동 | secret으로 관리 |
PRIVATE_EMBEDDING_URL | 사설 임베딩 API | MODEL_GATEWAY_URL·토큰이 있으면 게이트웨이 경유, 없으면 이 주소 직접 호출 |
PRIVATE_LLM_URL | 사설 LLM API | 위와 동일(게이트웨이 미설정 시 폴백) |
MODEL_GATEWAY_URL | 모델 접근 단일 창구(키·쿼터·감사) | 설정 시 임베딩·LLM 완성·RAG 답변이 모두 게이트웨이 경유 |
MODEL_GATEWAY_SERVICE_TOKEN | 게이트웨이 서비스 토큰 | secret으로 관리, 브라우저에 노출하지 않음 |
PORT | Express 수신 포트 | 호스팅이 제공하는 포트를 그대로 사용 |
런타임 설정 화면은 identity mode, deployment profile, PortalConsole origin, portal ID를 DB의 singleton 설정으로 저장할 수 있다. 단, API key 존재 여부와 일부 연결 정보는 서버 환경 변수를 기준으로 판정한다. 따라서 화면에 저장한 origin·portal ID와 배포 환경 변수의 실제 서비스 연결 가능 여부를 함께 확인해야 한다.
9. 보안 설계
인증 상태 쿠키는 HttpOnly·Secure·SameSite 정책을 사용하고, OAuth callback의 state와 PKCE verifier를 검증한다. return path는 외부 URL로 탈출하지 않는 안전한 내부 경로만 허용한다. PortalConsole API key, DB URL, 스토리지 자격 증명, private AI endpoint secret은 서버 환경 변수로만 보관한다.
API는 기본적으로 세션 기반 보호 절차를 사용하며, 관리자용 mutation은 별도의 권한 검증을 요구한다. 모든 외부 입력은 Zod 스키마로 길이·형식·열거값·배열 크기를 제한한다. 워크플로우에서는 존재하지 않는 단계, 다른 L5에 속한 단계, 자기 참조, 중복 관계를 검증해야 한다.
9.1 보안 경계와 방어 심화 구조
보안은 단일 인증 기능이 아니라 브라우저·API·도메인·데이터·외부 연동의 경계를 모두 통과하는 다층 구조로 운영한다. PortalConsole가 신원 확인의 기준이지만, ProcessCenter는 그 claim을 그대로 신뢰하지 않고 callback state·PKCE·포털 식별자·세션·애플리케이션 권한을 단계적으로 검증한다.
| 경계 | 현재 적용 제어 | 보완 운영 원칙 |
|---|---|---|
| 브라우저와 서버 | HTTPS 환경에서 Secure cookie, HttpOnly 세션, SameSite=None, 신뢰 프록시 설정 | 운영 도메인과 TLS 종료 지점을 문서화하고 cookie attribute 변경을 배포 승인 대상으로 관리 |
| 교차 출처 요청 | CORS_ORIGINS 또는 APP_ORIGIN 허용 목록, credentials 허용, OPTIONS 사전 요청 처리 | 와일드카드 origin을 사용하지 않고 운영·staging origin을 환경별로 분리 |
| 요청 본문 | JSON·urlencoded body 최대 50MB 제한 | 대용량 첨부는 presigned upload로 우회하고 API body limit 상향을 금지 |
| 인증 callback | state·PKCE verifier·만료·안전 return path·portal mismatch 검증 | PortalConsole redirect URI와 portal ID를 변경 관리 목록으로 유지 |
| API 권한 | protectedProcedure, adminProcedure, 업무별 canManageProcesses | 관리자 역할만으로 부족한 업무는 프로세스 범위 기반 권한을 추가 검증 |
| 입력·도메인 무결성 | Zod schema, L5 소속, 중복·순환·분기 outcome 검증 | DB unique/FK/check 제약과 서비스 검증을 이중 적용 |
| 데이터·비밀정보 | DB·API key·스토리지 key는 서버 환경 변수 보관 | secret rotation 일정과 접근 권한 분리를 운영 정책으로 설정 |
| 파일 다운로드 | 세션 확인, 대상 ID 유효성, no-store 응답 | 파일 관계 권한을 프로세스 단위 접근 제어와 연계하고 다운로드 감사 로그를 추가 |
9.2 예외 처리 아키텍처
예외 처리는 사용자에게 안전하고 행동 가능한 메시지를 제공하는 동시에, 운영자가 원인을 추적할 수 있는 구조여야 한다. 현재 tRPC 계층은 UNAUTHORIZED, FORBIDDEN, BAD_REQUEST, CONFLICT 등의 명시적 TRPCError를 사용하고, REST 다운로드 엔드포인트는 인증·입력·존재 여부를 각각 HTTP 401·400·404로 반환한다. PortalConsole callback은 토큰 교환 오류를 내부 타입으로 분류해 로그인 재시도 메시지로 변환한다.
| 오류 분류 | 대표 사례 | 사용자 응답 | 서버 처리 | 재시도 |
|---|---|---|---|---|
| 인증 실패 | 세션 없음·만료, OAuth state 불일치 | 로그인 또는 재시도 안내 | 401/UNAUTHORIZED, 민감 claim 비노출 | 사용자가 재로그인 |
| 권한 거부 | 관리자 전용 mutation, 프로세스 관리 권한 없음 | 권한 부족 안내 | 403/FORBIDDEN, 대상 데이터 변경 금지 | 자동 재시도 안 함 |
| 입력·업무 규칙 | 잘못된 L5 소속, 중복 연결, 순환 흐름, 잘못된 outcome | 수정 가능한 필드·관계 안내 | 400/BAD_REQUEST 또는 409/CONFLICT | 수정 후 재시도 |
| 외부 연동 | PortalConsole unavailable, token exchange 실패, 스토리지 응답 실패 | 서비스 연결·잠시 후 재시도 안내 | 오류 유형 정규화, 상세 토큰·응답 본문 미노출 | idempotent 요청만 제한적 재시도 |
| 데이터베이스 | 직렬화 충돌, advisory lock 경합, 일시적 연결 실패 | 처리 지연 또는 재시도 안내 | transactionRetry 제한 재시도, 실패 시 rollback | 안전한 write만 제한 재시도 |
| 예기치 않은 서버 오류 | 코드 버그, 알 수 없는 의존성 오류 | 일반화된 오류 메시지 | 5xx, 구조화 로그·알림 대상으로 기록 | 자동 재시도 금지 |
9.3 예외 처리 보완 우선순위
현재의 route-local try/catch, tRPC 오류, transaction retry만으로는 운영 원인 추적을 일관되게 하기 어렵다. 다음 보완을 운영 아키텍처의 목표 상태로 둔다.
- 전역 오류 정규화 미들웨어를 Express 정적 파일·REST·tRPC 경계 뒤에 두고, 예기치 않은 예외를 동일한 오류 envelope로 변환한다.
- 모든 요청에 correlation ID를 부여하고, 사용자 ID·라우터·대상 엔티티 ID·결과 코드·지연 시간을 구조화 JSON 로그로 기록한다. 비밀번호·token·cookie·API key·원문 개인정보는 마스킹한다.
- PortalConsole·스토리지·private AI에 대해 timeout, circuit breaker, dependency health를 정의한다. 외부 쓰기 요청은 중복 실행되지 않도록 idempotency key 또는 중복 방지 제약을 사용한다.
- 운영 런타임 로그에서 알림을 연결하고, 인증 실패 급증·5xx 비율·DB retry 초과·외부 연동 실패율을 운영 지표로 관리한다.
- 보안 헤더(CSP, HSTS,
X-Content-Type-Options, frame 제한)와 rate limiting을 Express 경계에 추가하고, 관리자·인증·다운로드 endpoint에는 더 엄격한 정책을 적용한다.
10. 장애 대응과 운영 점검
| 점검 대상 | 확인 방법 | 주요 증상 |
|---|---|---|
| 컨테이너 기동 | 배포 런타임 로그 | dist/index.js 실행 실패, 포트 바인딩 오류 |
| DB 연결 | 서버 기동 로그와 DB health | migration 실패, DATABASE_URL 오류 |
| PortalConsole | GET /api/auth/config, /api/auth/login | directory_service_unavailable, callback 교환 실패 |
| OAuth 설정 | 저장된 origin·portal ID·redirect URI | 다른 포털로 redirect, portal mismatch |
| 워크플로우 저장 | flow mutation 응답과 서버 로그 | 외부 L5 자기 참조, 단계 소속 불일치 |
| 파일 업로드 | presigned URL 응답과 object storage | 업로드 URL 만료, CORS·권한 오류 |
| PostgreSQL 호환성 | migration·테스트·쿼리 로그 | MySQL 함수, 타입 캐스팅, 함수 시그니처 오류 |
장애 조사 시 먼저 배포 런타임 로그에서 애플리케이션 기동 이후의 stack trace를 확인한다. 빌드가 성공했더라도 migration 또는 startServer 과정에서 실패할 수 있으므로 build log만으로 정상 배포를 판단하지 않는다.
11. 테스트 전략
서버 도메인 테스트는 Vitest로 실행한다. 특히 다음 영역은 회귀 테스트를 유지해야 한다.
| 테스트 영역 | 검증 내용 |
|---|---|
| DB compatibility | PostgreSQL provider, advisory lock, 기본값, migration 동작 |
| Directory gateway | state·PKCE·callback·portal mismatch·세션 발급 |
| Flow router | 단계·전환·외부유입·자기 참조 차단 |
| Workflow inbound | 외부 L5 후보·실제 단계 재사용·다중 외부 연결 |
| Process governance | 코드·계층·권한·책임자·감사 규칙 |
| UI workflow | 외부 카드 크기, SVG edge 접점, 다크모드 필드 가독성 |
기본 검증 순서는 다음과 같다.
pnpm run check
pnpm test
pnpm run buildPostgreSQL 운영 마이그레이션은 다음 명령을 기준으로 한다.
pnpm run db:postgres:generate
pnpm run db:postgres:migrate12. 현재 구조의 장점과 개선 과제
현재 구조는 프론트엔드·API·서비스·Repository·DB의 책임이 분리되어 있고, 중앙 인증과 독립 실행 모드를 모두 지원한다. PostgreSQL 호환성을 명시적으로 점검할 수 있으며, L5 Workflow의 외부 연결을 일반 단계와 구분하면서도 동일한 업무 의미로 처리한다. 배포는 빌드와 런타임을 분리하고 non-root 사용자로 실행하여 운영 안정성과 기본 보안 수준을 확보한다.
향후에는 다음 과제를 우선순위에 따라 검토한다.
| 우선순위 | 과제 | 기대 효과 |
|---|---|---|
| 높음 | 외부유입 연결의 DB 제약조건·유일성·순환 참조 방어 강화 | 잘못된 관계의 영속 저장 방지 |
| 높음 | migration 실행과 애플리케이션 기동의 분리 검토 | 배포 실패 원인 단순화 및 롤백 안정성 향상 |
| 중간 | tRPC 라우터별 OpenAPI 또는 운영 API 카탈로그 생성 | 운영·연동 문서 자동화 |
| 중간 | 구조화된 JSON 로그와 request correlation ID 도입 | 운영 로그 추적성 향상 |
| 중간 | Workflow 캔버스의 시각 회귀 테스트 도입 | 좌표·스케일·브라우저별 렌더링 회귀 방지 |
| 낮음 | 대형 프론트엔드 chunk의 route-level code splitting | 초기 로딩 성능 향상 |
13. 소스 기준 및 참고 파일
이 문서는 외부 일반론이 아니라 ProcessCenter 저장소의 실제 구현을 기준으로 작성했다. 주요 근거 파일은 다음과 같다.
- Dockerfile — Node 22 Alpine multi-stage 이미지와 runtime command.
- docs/deployment-platforms.md — 플랫폼 중립 배포 절차와 환경변수.
- package.json — 실행 스크립트, 프레임워크, ORM, 테스트 도구.
- server/app.ts — Express 애플리케이션 구성과 서버 부트스트랩.
- server/routers.ts — tRPC 도메인 라우터 조합.
- server/_core/trpc.ts — procedure와 요청 컨텍스트 구성.
- server/_core/context.ts — 세션 기반 사용자 컨텍스트 생성과 인증 실패 격리.
- server/_core/cookies.ts — Secure·HttpOnly·SameSite 세션 쿠키 정책.
- server/directory-gateway.ts — PortalConsole 로그인·PKCE·callback·세션 처리.
- server/runtimeSettings.ts — 환경 변수와 DB 런타임 설정 병합 정책.
- server/db-connection.ts — DB 연결과 provider 선택.
- server/services/transactionRetry.ts — 재시도 가능한 DB 트랜잭션 오류 판정.
- drizzle/schema.ts — PostgreSQL 기준 도메인 스키마.
- server/repositories/workflowReadRepository.ts — Workflow 읽기 모델과 외부유입 조회 방어.
- server/routers/flow.ts — 실제 L5 워크플로우·handoff 기반 L4 통합 맵과 Workflow mutation.
- client/src/components/TaskFlowMap.tsx — L5 Workflow 캔버스와 외부유입 카드·SVG 연결선.
- client/src/components/IntegratedWorkflowMap.tsx — L4 하위 L5 workflow lane과 L5 간 handoff 통합 뷰.
- client/src/components/workflowLayout.ts — 노드 크기, 위치, 직교 연결선 경로 계산.
14. 변경 관리 원칙
아키텍처에 영향을 주는 변경은 다음 순서로 검토한다. 먼저 데이터 모델과 외부 계약의 변경 여부를 판단하고, 그다음 서비스·Repository·라우터·UI 순으로 영향을 분석한다. PostgreSQL migration과 rollback 가능성을 확인한 뒤, PortalConsole callback과 운영 런타임 환경에서의 동작을 검증한다. 마지막으로 단위 테스트·타입 검사·production build·실제 배포 runtime log를 모두 확인한 후 main에 반영한다.
특히 다음 변경은 사전 검토 대상이다.
processNodes,workflowSteps,workflowTransitions의 의미 또는 키 변경.- PortalConsole origin, portal ID, redirect URI, claim 계약 변경.
- 세션 쿠키 정책, 관리자 procedure, 포털별 권한 계산 변경.
- PostgreSQL migration, SQL 함수, advisory lock, JSON 타입 처리 변경.
- Workflow 캔버스의 좌표계·스케일·DOM 측정 방식 변경.
- 컨테이너 실행 명령, 환경 변수, health check, 재시작 정책 변경.