Backend on Kelly Dev

dev-data-server-light. 1. System

Thu, 25 Jun 2026 00:00:00 +0000

프로젝트에서 제일 간단한 기능과 구조를 가지기 때문에 가장 먼저 System 모듈을 만들었다.

System 모듈의 기능

System 모듈이 제공하는 기능은 단 두 가지뿐이다.

GET /system/status
GET /system/uptime

status는 서버가 정상적으로 동작하는지 알려주고, uptime은 서버가 실행된 이후 얼마나 시간이 지났는지를 반환한다.

비즈니스 로직도 없고, 데이터베이스도 필요하지 않으며, 파일 시스템도 다루지 않기 때문에 구조를 검증하는데 가장 좋다고 판단했다.

구조 검증

System 모듈을 만들면서 확인하고 싶었던 것은 기능이 아니라 구조였다. 당시에 생각했던 구조는 다음과 같았다.

TIL. Jun 16, 2026

Tue, 16 Jun 2026 20:29:07 +0900

오늘 한 내용

Antigravity IDE의 에이전트, 에디터, 터미널, 브라우저 구조 살펴보기
File Storage 구현 순서와 StorageService 설계

배운 내용

Antigravity는 에디터 안에서 에이전트가 작업을 수행하고, 브라우저와 터미널을 사용해 결과를 검증하는 개발 환경이다. Agent는 기능 개발이나 버그 수정처럼 실제 작업을 담당하고, Tab은 자동완성에 가깝다.

File Storage는 먼저 계약을 만들고, 그 다음 fs/promises 기반 구현체와 테스트를 추가한 뒤, Express와 분리된 Service를 얹는 순서로 진행하기로 했다. 처음부터 multipart 업로드까지 확장하지 않고, JSON과 단순한 파일 콘텐츠로 흐름을 검증하는 것도 중요한 범위 조절이었다.

TIL. Jun 11, 2026

Thu, 11 Jun 2026 21:36:55 +0900

오늘 한 내용

배운 내용

기존에는 Route가 Database 인터페이스를 직접 사용했다. 리팩터링 후에는 Route -> DatabaseService -> RecordStore -> InMemoryRecordStore 흐름으로 바꾸었다.

RecordStore는 레코드를 저장하고 꺼내는 교체 가능한 capability이고, DatabaseService는 여러 저장소 동작을 조합하는 use case다. 예를 들어 replace 이후 갱신된 레코드를 반환하거나, 삭제 결과에 따라 오류를 판단하는 흐름은 Service가 맡는다.

File Storage도 같은 기준을 적용했다. 계약은 key와 Uint8Array만 사용해 작고 명시적으로 만들고, 로컬 파일 시스템이나 경로 검증은 구현체 안에 가둔다.

TIL. Jun 8, 2026

Mon, 08 Jun 2026 21:04:28 +0900

오늘 한 내용

dev-data-server-light의 계층형 구조를 모듈형 구조로 바꾸는 작업 검토
AGENTS.md가 새 디렉토리 구조와 충돌하지 않도록 정리
Database, Route, Service의 책임 재검토

배운 내용

기존 구조는 routes, services, db처럼 계층별로 나뉘어 있었다. 새 구조에서는 모듈이 자신의 계약, 구현체, 서비스, 라우트를 함께 소유하도록 바꾸려 했다.

계층형 구조에서는 AGENTS.md에 각 계층의 역할을 적기 쉬웠지만, 모듈형 구조에서는 모듈의 책임과 공개 API를 기준으로 규칙을 작성해야 한다. 구조가 바뀌면 문서도 함께 바뀌어야 하며, 기존 규칙을 억지로 유지하면 오히려 AI가 잘못된 경계를 학습하게 된다.

TIL. Jun 4, 2026

Thu, 04 Jun 2026 20:17:42 +0900

오늘 한 내용

dev-data-server-light의 DB 모듈 설계 정리
System 모듈과 DB 인터페이스 구현 방향 검토
저장소와 애플리케이션 로직의 경계 정리

배운 내용

이름도 설계의 일부

처음에는 DocumentStore, StoredDocument, DocumentBody라는 이름을 사용했다. 하지만 DB CRUD 인터페이스를 설계하는 과정에서 이 이름들이 프로젝트가 특정 Document Database를 전제로 한다는 인상을 준다는 것을 발견했다.

In-Memory, SQL, JSON File 등 여러 구현을 염두에 둔다면 인터페이스도 구현 방식에서 자유로워야 한다. 그래서 RecordStore, StoredRecord, RecordData처럼 더 중립적인 이름으로 바꿨다.