ObjectOS아키텍처
실제로 무엇이 실행되는가 — 이 제품을 도입할지 평가하는 엔지니어를 위한 안내.
아키텍처
ObjectOS를 배포할 때 여러분의 머신에서 무엇이 실행되는지, 어떤 데이터가 네트워크 밖으로 나가고 어떤 데이터가 나가지 않는지에 대한 실용적인 관점입니다.
핵심 개념은 두 개의 얇은 계층입니다.
- 메타데이터 — 객체 / 뷰 / 액션 / 플로우 / 에이전트의 패키지입니다. 대부분은 샌드박스화된 도구 API를 대상으로 AI Builder가 작성하며, 때때로 직접 편집되기도 하지만 항상 버전 관리되고 감사됩니다.
- 단일 Node.js 런타임 — 이 메타데이터를 동작하는 애플리케이션으로 해석합니다. REST API, Console UI, 권한, 작업, AI 도구가 모두 하나의 프로세스 안에서 여러분의 데이터베이스와 통신합니다.
코드 생성 단계도, "사용자가 원하는 것을 설명함"과 "그것이 라이브로 동작함" 사이의 배포 파이프라인도 없습니다. 런타임은 HITL 승인 이후 새 메타데이터를 핫 로드합니다.
무엇을 배포하는가
ObjectOS 인스턴스당 하나의 Node.js 프로세스. 그것이 전부입니다.
┌─────────────────────────────────────────────────────┐
│ ObjectOS process │
│ ┌───────────────────────────────────────────────┐ │
│ │ HTTP dispatcher (/ · /api · /_console …) │ │
│ ├───────────────────────────────────────────────┤ │
│ │ Per-project ObjectKernel (LRU cached) │ │
│ │ ├─ Auth (Better Auth) │ │
│ │ ├─ Security (RBAC + row-level + field) │ │
│ │ ├─ ObjectQL (data engine, generates SQL) │ │
│ │ ├─ REST API generator │ │
│ │ └─ Capabilities loaded per artifact │ │
│ │ (audit, storage, jobs, queue, AI …) │ │
│ └───────────────────────────────────────────────┘ │
└──────────┬──────────────────────────────────────────┘
│
▼
Your business database
(Postgres / MySQL / SQLite / Turso / MongoDB)정적으로 링크된 단일 바이너리 수준의 복잡도입니다. 사이드카도, Kafka도, 별도의 캐시 계층도 필요하지 않습니다. 필요할 때 추가하세요. 첫날부터 그 비용을 치를 필요는 없습니다.
데이터는 어디에 있는가
| 데이터 | 저장 위치 | 네트워크 밖으로 나가는가? |
|---|---|---|
| 비즈니스 레코드 | 여러분의 데이터베이스 | 아니오 |
| 사용자 계정, 세션, OAuth 토큰 | 여러분의 데이터베이스 | 아니오 |
| 감사 로그 | 여러분의 데이터베이스 | 아니오 |
| 설정, API 키, 시크릿 | 여러분의 데이터베이스 / 시크릿 매니저 | 아니오 |
| 업로드된 파일 | 여러분의 디스크 또는 S3/R2 버킷 | 아니오 |
컴파일된 앱 정의(objectstack.json) | 디스크의 파일 또는 컨트롤 플레인에서 가져옴 | 선택적 |
ObjectOS는 외부로 연결을 시도하지 않습니다. 텔레메트리도, 라이선스 검사도 없습니다. 인터넷 접속을 완전히 차단해도 무기한 계속 실행됩니다. 에어갭을 참고하세요.
요청이 처리되는 방식
1. Ingress / TLS termination (your load balancer)
2. HTTP dispatcher (security headers, request id)
3. Hostname → project resolution (cached, TTL configurable)
4. Get or build per-project kernel from LRU
5. AuthPlugin — session cookie, bearer token, or API key
6. SecurityPlugin — RBAC + row-level + field-level checks
7. Route handler — generated REST, declarative action, or custom
8. Data driver — ObjectQL compiles to SQL / Mongo query
9. Response with X-Request-Id propagated커널이 워밍업된 상태에서는 4~8단계가 일반적으로 5ms 미만으로 실행됩니다.
세 개의 계층 (통합할 때만 중요함)
대부분의 고객은 ObjectOS만 배포합니다. 나머지 두 계층은 아티팩트가 어디에서 오는지 알고 싶을 때를 위해 존재합니다.
| 계층 | 무엇인가 | 어디에서 실행되는가 |
|---|---|---|
Framework(@objectstack/*) | 오픈소스 커널, ObjectQL, 플러그인, 드라이버 | npm — 빌드 시점에 포함됨 |
| Control plane(선택적) | 컴파일된 objectstack.json 아티팩트를 게시함. 호스팅되는 ObjectStack Cloud를 사용하거나, 직접 운영하거나, 완전히 생략할 수 있음 | 여러분의 CI, 우리 클라우드, 또는 여러분의 노트북 |
| ObjectOS | 여러분이 운영하는 런타임 | 여러분의 인프라 |
단일 앱을 출시한다면 컨트롤 플레인이 필요하지 않습니다. CI에서
objectstack.config.ts → dist/objectstack.json을 컴파일하고 그 JSON을
이미지에 담아 출시하세요. 다수의 테넌트와 앱을 가진 내부 앱 마켓플레이스를
운영한다면, 컨트롤 플레인이 카탈로그가 머무는 곳입니다.
부팅 모드
| 모드 | 언제 | 어떻게 |
|---|---|---|
| Standalone | 단일 앱, 개발, 평가, 에어갭, 대부분의 프로덕션 배포 | pnpm dev 또는 디스크에서 dist/objectstack.json 실행 |
| File-backed | 외부에서 관리되는 아티팩트를 사용하는 프로덕션 | OS_ARTIFACT_PATH=/path/to/objectstack.json 설정 |
| Cloud-connected | 컨트롤 플레인이 공급하는 멀티 테넌트 / 멀티 앱 배포 | OS_CLOUD_URL + OS_CLOUD_API_KEY 설정 |
모드는 환경 변수로부터 자동 감지됩니다.
성능 특성
| 지표 | 수치 |
|---|---|
| 콜드 스타트(프로세스 기동, 트래픽 수신 준비) | 약 1초 |
| 커널당 워밍업(프로젝트로의 첫 요청) | 기능에 따라 50~300ms |
| 워밍업된 요청 지연(REST를 통한 CRUD) | 일반적으로 10ms 미만 + 데이터베이스 지연 |
| 메모리 사용량 | 기본 약 150MB, 활성 프로젝트 커널당 약 10~30MB |
| 인스턴스당 동시 프로젝트 수 | OS_KERNEL_CACHE_SIZE로 제한됨(기본값 32) |
왜 이런 형태인가
- 사이드카 없는 단일 Node 프로세스 →
docker run에 들어맞고, systemd 유닛에 들어맞고, Lambda 같은 환경에 들어맞습니다. - 프로젝트당 커널, LRU 캐시 → 하나의 인스턴스가 매 요청마다 워밍업 비용을 치르지 않고도 많은 소규모 앱을 처리할 수 있습니다.
- 선언된 메타데이터 위에 생성되는 API → CI에 코드 생성 단계가 없고, 게시할 클라이언트 SDK도 없습니다. API는 구조적으로 여러분의 데이터 모델과 일치합니다.
- 모든 기능은 선택적 플러그인 → 이미지 크기가 실제로 사용하는 것에 맞춰 조정됩니다.