원칙

basedb는 아키텍처 문서를 바탕으로 설계되었습니다. 저장소의 docs/architecture 아래에 있는 16개 장으로 된 문서입니다. 00장에서 스물다섯 가지 결정을 정하며, 그 취지는 다음과 같습니다.

데이터는 형식이 아니라 테이블입니다

사용자 데이터베이스는 PostgreSQL 스키마이고, 테이블은 테이블이며, 필드는 알아보기 쉬운 이름이 붙은 타입 있는 열입니다. EAV(엔터티-속성-값)도, 무엇이든 담아 두는 JSON 문서도, 알 수 없는 이름도 없습니다. _basedb 카탈로그는 이 객체들을 설명할 뿐, 대신하지 않습니다.

의도된 결과로, SQL 직접 사용은 정당한 사용 방식입니다. 제약 조건은 데이터베이스에 걸려 있고, 기록은 트리거가 남깁니다. 쓰기가 애플리케이션을 거친다고 가정하는 부분은 없습니다.

권한 결정 지점은 하나뿐입니다

인터페이스, REST API, MCP 서버, 공유 양식, 웹훅 모두 코어에 있는 같은 권한 적용 지점을 거칩니다. 인터페이스도 API의 여느 소비자와 다르지 않습니다. 비공개 경로도, 서비스 토큰도 없습니다. 볼 수 없는 리소스는 존재하지 않는 리소스와 정확히 같은 응답을 받습니다.

코어가 결정하고, 어댑터가 변환합니다

TypeScript 모노레포입니다. @basedb/core가 모든 로직(카탈로그, DDL 엔진, 권한, 레코드, 기록)을 담당하고, apps/api(Hono), apps/mcp, apps/web(Next.js)은 서로를 호출하지 않는 어댑터입니다. 인터페이스는 코어에 절대 의존하지 않으며, 오직 HTTP로만 통신합니다.

결정 없이는 아무것도 사라지지 않습니다

삭제는 없애는 것이 아니라 한쪽으로 옮기는 것입니다. 삭제된 테이블은 행을 유지하고, 옮겨진 이름으로 SQL에서 읽을 수 있으며, 복원할 수 있습니다. 물리명을 바꿔도 이전 이름은 별칭으로 계속 제공됩니다. 영구 삭제는 시스템 관리에서 내리는 결정이며, 그 전에 검증된 내보내기를 수행합니다.

PostgreSQL, 그 외에는 없습니다

PostgreSQL 16 이상만 있으면 되며, 필수 외부 의존성은 없습니다. 메시지 큐도, 캐시도, 검색 엔진도 필요 없습니다. 웹훅 대기열, 기록 비우기, 속도 제한 모두 데이터베이스나 프로세스 안에서 처리됩니다.

더 알아보기

장	주제
00	구조적 결정과 오류 코드 목록
01	이름 규칙과 슬러그화
02	신뢰할 수 있는 단일 출처인 _basedb 카탈로그
03	DDL 엔진과 마이그레이션
04	필드 타입과 PostgreSQL 대응
05	권한
06	수명 주기: 이름 바꾸기, 삭제, 영구 삭제
07	기록
08	REST API와 웹훅
09	MCP 서버
10	소프트웨어 아키텍처
11	인터페이스
12	AI 통합
13	인증
14	환경
15	공유 양식