# cp949/storix architecture

> Architecture diagram of the GitHub repository cp949/storix, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/cp949/storix
- Repository: https://github.com/cp949/storix

## Overview

Storix — 호출 서버가 경로 기반 파일시스템 API로 파일과 디렉터리를 저장·조회하는 독립 VFS 서버입니다. 주 흐름은 호출 서버의 서비스 key 요청에서 시작해 namespace 및 VFS API를 거쳐 메타데이터 DB와 S3 호환 blob 저장소를 사용하고 결과를 돌려주는 것입니다. 주요 도메인 단계로 업로드 세션, 변경 feed, snapshot, 휴지통 복구와 GC·백업·복원을 포함했습니다. 데모 웹/서버는 Storix API를 이용하는 별도 문서 보관 예시입니다. 관계는 README와 제공된 SOURCE INDEX 및 발췌로 확인되는 범위에 한정했습니다.

Main entry points: [`apps/api/src/vfs/vfs.service.ts`](https://github.com/cp949/storix/blob/main/apps/api/src/vfs/vfs.service.ts) (VFS 서비스), [`apps/api/src/vfs/fs.controller.ts`](https://github.com/cp949/storix/blob/main/apps/api/src/vfs/fs.controller.ts) (파일 API), [`apps/api/src/persistence/vfs-node.repository.ts`](https://github.com/cp949/storix/blob/main/apps/api/src/persistence/vfs-node.repository.ts) (Node 저장소), [`apps/api/src/persistence/data-source.ts`](https://github.com/cp949/storix/blob/main/apps/api/src/persistence/data-source.ts) (메타데이터 DB)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API 및 네임스페이스"]
  node_namespace["Namespace 관리"]
  node_auth["API 키 인증<br/>[api-key.guard.ts]"]
  node_capability["Capability 설정"]
end

subgraph group_vfs["파일시스템 도메인"]
  node_fsapi["파일 API<br/>[fs.controller.ts]"]
  node_vfsservice["VFS 서비스<br/>[vfs.service.ts]"]
  node_mutation["파일 변경"]
  node_content["콘텐츠 전송<br/>[content.service.ts]"]
  node_upload["분할 업로드"]
  node_feed["변경 feed"]
  node_snapshot["Snapshot"]
  node_trash["휴지통 복구"]
end

subgraph group_storage["저장 및 운영"]
  node_database[("메타데이터 DB<br/>[data-source.ts]")]
  node_nodes["Node 저장소"]
  node_blobstorage["Blob 저장 계층<br/>[s3-blob-storage.ts]"]
  node_gc["정리 작업<br/>[gc.job.ts]"]
  node_backup["백업 작업<br/>[backup.job.ts]"]
  node_restore["복원 작업<br/>[restore.job.ts]"]
end

subgraph group_demo["문서 보관 데모"]
  node_demoweb["보관함 웹"]
  node_democontroller["보관함 API"]
  node_storixclient["Storix HTTP 클라이언트"]
end

node_caller(("호출 서버"))
node_objectstore[("S3 호환 저장소")]

node_caller -->|"서비스 key 전송"| node_auth
node_auth -->|"인증 후 요청"| node_fsapi
node_caller -->|"namespace 관리"| node_namespace
node_fsapi -.->|"파일 요청 처리"| node_vfsservice
node_vfsservice -.->|"변경 수행"| node_mutation
node_vfsservice -.->|"콘텐츠 처리"| node_content
node_fsapi -.->|"분할 업로드"| node_upload
node_caller -->|"변경 cursor 조회"| node_feed
node_caller -->|"snapshot 조작"| node_snapshot
node_caller -->|"복구・purge"| node_trash
node_caller -->|"기능 확인"| node_capability
node_vfsservice -.->|"node 읽기・쓰기"| node_nodes
node_mutation -.->|"메타데이터 변경"| node_nodes
node_content -.->|"blob 전송"| node_blobstorage
node_upload -->|"세션 상태 저장"| node_nodes
node_nodes -->|"DB 질의"| node_database
node_blobstorage -->|"S3 객체 처리"| node_objectstore
node_gc -.->|"만료 데이터 정리"| node_database
node_gc -->|"미참조 blob 회수"| node_objectstore
node_backup -.->|"DB 백업"| node_database
node_restore -.->|"DB 복원"| node_database
node_demoweb -.->|"보관함 요청"| node_democontroller
node_democontroller -->|"Storix 호출"| node_storixclient
node_storixclient -.->|"HTTP 요청"| node_fsapi

click node_namespace "https://github.com/cp949/storix/blob/main/apps/api/src/namespace/namespace.controller.ts"
click node_auth "https://github.com/cp949/storix/blob/main/apps/api/src/auth/api-key.guard.ts"
click node_capability "https://github.com/cp949/storix/blob/main/apps/api/src/capability/capability.service.ts"
click node_fsapi "https://github.com/cp949/storix/blob/main/apps/api/src/vfs/fs.controller.ts"
click node_vfsservice "https://github.com/cp949/storix/blob/main/apps/api/src/vfs/vfs.service.ts"
click node_mutation "https://github.com/cp949/storix/blob/main/apps/api/src/vfs/mutation.service.ts"
click node_content "https://github.com/cp949/storix/blob/main/apps/api/src/vfs/content.service.ts"
click node_upload "https://github.com/cp949/storix/blob/main/apps/api/src/vfs/upload-session-part.service.ts"
click node_feed "https://github.com/cp949/storix/blob/main/apps/api/src/vfs/change-feed.service.ts"
click node_snapshot "https://github.com/cp949/storix/blob/main/apps/api/src/vfs/vfs-snapshot.service.ts"
click node_trash "https://github.com/cp949/storix/blob/main/apps/api/src/vfs/vfs-trash.service.ts"
click node_database "https://github.com/cp949/storix/blob/main/apps/api/src/persistence/data-source.ts"
click node_nodes "https://github.com/cp949/storix/blob/main/apps/api/src/persistence/vfs-node.repository.ts"
click node_blobstorage "https://github.com/cp949/storix/blob/main/apps/api/src/storage/s3-blob-storage.ts"
click node_gc "https://github.com/cp949/storix/blob/main/apps/api/src/jobs/gc.job.ts"
click node_backup "https://github.com/cp949/storix/blob/main/apps/api/src/jobs/backup.job.ts"
click node_restore "https://github.com/cp949/storix/blob/main/apps/api/src/jobs/restore.job.ts"
click node_demoweb "https://github.com/cp949/storix/blob/main/apps/demo1/web/src/components/DocumentArchive.tsx"
click node_democontroller "https://github.com/cp949/storix/blob/main/apps/demo1/was/src/document-archive/documents.controller.ts"
click node_storixclient "https://github.com/cp949/storix/blob/main/apps/demo1/was/src/storix-client/storix-client.service.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_namespace,node_auth,node_capability toneBlue
class node_fsapi,node_vfsservice,node_mutation,node_content,node_upload,node_feed,node_snapshot,node_trash,node_objectstore toneAmber
class node_database,node_nodes,node_blobstorage,node_gc,node_backup,node_restore toneMint
class node_demoweb,node_democontroller,node_storixclient toneRose
class node_caller toneIndigo
```

## Components

### API 및 네임스페이스

- [Namespace 관리](https://github.com/cp949/storix/blob/main/apps/api/src/namespace/namespace.controller.ts): `apps/api/src/namespace/namespace.controller.ts`
- [API 키 인증](https://github.com/cp949/storix/blob/main/apps/api/src/auth/api-key.guard.ts): `apps/api/src/auth/api-key.guard.ts`
- [Capability 설정](https://github.com/cp949/storix/blob/main/apps/api/src/capability/capability.service.ts): `apps/api/src/capability/capability.service.ts`

### 파일시스템 도메인

- [파일 API](https://github.com/cp949/storix/blob/main/apps/api/src/vfs/fs.controller.ts): `apps/api/src/vfs/fs.controller.ts`
- [VFS 서비스](https://github.com/cp949/storix/blob/main/apps/api/src/vfs/vfs.service.ts): `apps/api/src/vfs/vfs.service.ts`
- [파일 변경](https://github.com/cp949/storix/blob/main/apps/api/src/vfs/mutation.service.ts): `apps/api/src/vfs/mutation.service.ts`
- [콘텐츠 전송](https://github.com/cp949/storix/blob/main/apps/api/src/vfs/content.service.ts): `apps/api/src/vfs/content.service.ts`
- [분할 업로드](https://github.com/cp949/storix/blob/main/apps/api/src/vfs/upload-session-part.service.ts): `apps/api/src/vfs/upload-session-part.service.ts`
- [변경 feed](https://github.com/cp949/storix/blob/main/apps/api/src/vfs/change-feed.service.ts): `apps/api/src/vfs/change-feed.service.ts`
- [Snapshot](https://github.com/cp949/storix/blob/main/apps/api/src/vfs/vfs-snapshot.service.ts): `apps/api/src/vfs/vfs-snapshot.service.ts`
- [휴지통 복구](https://github.com/cp949/storix/blob/main/apps/api/src/vfs/vfs-trash.service.ts): `apps/api/src/vfs/vfs-trash.service.ts`

### 저장 및 운영

- [메타데이터 DB](https://github.com/cp949/storix/blob/main/apps/api/src/persistence/data-source.ts): `apps/api/src/persistence/data-source.ts`
- [Node 저장소](https://github.com/cp949/storix/blob/main/apps/api/src/persistence/vfs-node.repository.ts): `apps/api/src/persistence/vfs-node.repository.ts`
- [Blob 저장 계층](https://github.com/cp949/storix/blob/main/apps/api/src/storage/s3-blob-storage.ts): `apps/api/src/storage/s3-blob-storage.ts`
- [정리 작업](https://github.com/cp949/storix/blob/main/apps/api/src/jobs/gc.job.ts): `apps/api/src/jobs/gc.job.ts`
- [백업 작업](https://github.com/cp949/storix/blob/main/apps/api/src/jobs/backup.job.ts): `apps/api/src/jobs/backup.job.ts`
- [복원 작업](https://github.com/cp949/storix/blob/main/apps/api/src/jobs/restore.job.ts): `apps/api/src/jobs/restore.job.ts`

### 문서 보관 데모

- [보관함 웹](https://github.com/cp949/storix/blob/main/apps/demo1/web/src/components/DocumentArchive.tsx): `apps/demo1/web/src/components/DocumentArchive.tsx`
- [보관함 API](https://github.com/cp949/storix/blob/main/apps/demo1/was/src/document-archive/documents.controller.ts): `apps/demo1/was/src/document-archive/documents.controller.ts`
- [Storix HTTP 클라이언트](https://github.com/cp949/storix/blob/main/apps/demo1/was/src/storix-client/storix-client.service.ts): `apps/demo1/was/src/storix-client/storix-client.service.ts`

### Other components

- **호출 서버**
- **S3 호환 저장소**

## Connections

- 호출 서버 → API 키 인증: 서비스 key 전송 (evidence: `README.md`)
- API 키 인증 → 파일 API: 인증 후 요청 (evidence: `README.md`)
- 호출 서버 → Namespace 관리: namespace 관리 (evidence: `README.md`)
- 파일 API → VFS 서비스: 파일 요청 처리
- VFS 서비스 → 파일 변경: 변경 수행
- VFS 서비스 → 콘텐츠 전송: 콘텐츠 처리
- 파일 API → 분할 업로드: 분할 업로드
- 호출 서버 → 변경 feed: 변경 cursor 조회 (evidence: `README.md`)
- 호출 서버 → Snapshot: snapshot 조작 (evidence: `README.md`)
- 호출 서버 → 휴지통 복구: 복구・purge (evidence: `README.md`)
- 호출 서버 → Capability 설정: 기능 확인 (evidence: `README.md`)
- VFS 서비스 → Node 저장소: node 읽기・쓰기
- 파일 변경 → Node 저장소: 메타데이터 변경
- 콘텐츠 전송 → Blob 저장 계층: blob 전송
- 분할 업로드 → Node 저장소: 세션 상태 저장 (evidence: `apps/api/src/vfs/upload-session-part.service.ts`)
- Node 저장소 → 메타데이터 DB: DB 질의 (evidence: `apps/api/src/persistence/vfs-node.repository.ts`)
- Blob 저장 계층 → S3 호환 저장소: S3 객체 처리 (evidence: `apps/api/src/storage/s3-blob-storage.ts`)
- 정리 작업 → 메타데이터 DB: 만료 데이터 정리
- 정리 작업 → S3 호환 저장소: 미참조 blob 회수 (evidence: `README.md`)
- 백업 작업 → 메타데이터 DB: DB 백업
- 복원 작업 → 메타데이터 DB: DB 복원
- 보관함 웹 → 보관함 API: 보관함 요청
- 보관함 API → Storix HTTP 클라이언트: Storix 호출 (evidence: `apps/demo1/was/src/document-archive/documents.controller.ts`)
- Storix HTTP 클라이언트 → 파일 API: HTTP 요청
