Plane 딥다이브
— 내 서버에 짓는 Jira, 그리고 프론트엔드 대이동의 실물 표본

1프로젝트 한줄 요약

Plane은 Jira · Linear · Monday · ClickUp의 오픈소스 대안입니다. 할 일(Work Item)을 만들고, 스프린트(Cycle)로 묶고, 기능 단위(Module)로 쪼개고, 문서(Page)를 같이 쓰는 — 이른바 "팀 업무 관리" 도구 전체를 담고 있습니다. 라이선스는 AGPL-3.0이고, docker compose up 한 번이면 내 서버에서 통째로 돕니다.

구조는 4층입니다. Workspace(회사) 안에 Project(팀·제품)가 있고, 그 안에 Work Item(할 일)이 쌓이며, 이 할 일들을 기간으로 자르면 Cycle(스프린트), 목적으로 자르면 Module(기능 묶음)이 됩니다. 여기에 실시간 협업 문서 Page와 외부 요청 접수함 Intake가 붙습니다.

2왜 주목받는가

비교표 — 무엇이 다른가

개발자 입장에서 진짜 볼거리 — 2026년 프론트엔드 재편의 실물 표본

제품 소개만 보면 "또 하나의 Jira 클론"입니다. 그런데 코드를 열면 이야기가 달라집니다. Plane은 최근 프론트엔드를 통째로 갈아엎었고, 그 결과가 2026년 프런트엔드 판이 어디로 움직이는지를 한 저장소 안에서 다 보여줍니다.

즉 "React 앱 = Next.js"라는 기본값을 깨고 SPA로 되돌아간, 규모 있는 실서비스 사례입니다. 2,040개 .tsx 파일 · 19만 줄짜리 프론트엔드가 실제로 그 선택으로 굴러가고 있다는 게 이 저장소의 학습 가치입니다.

3기술 스택 전체 지도

백엔드 — Django 5.2 + DRF (apps/api/)

프론트엔드 — React Router 7 + Vite (apps/web · space · admin)

실시간 협업 서버 (apps/live/)

독립 Node 서비스로, Hocuspocus 2.15.2(Yjs용 협업 백엔드)를 Express 위에 올렸습니다. 특이하게 함수형 이펙트 라이브러리 effect + @effect/platform-node를 쓰고, PDF 내보내기까지 이 서버가 맡습니다(@react-pdf/renderer).

인프라 — 컨테이너 11개

재밌는 지점은 프록시가 두 겹이라는 것입니다. 바깥은 Caddy(자동 HTTPS·라우팅), 안쪽은 각 프론트 앱이 자기 nginx로 정적 파일을 서빙합니다. Caddy는 xcaddy로 caddy-dns/cloudflare·caddy-dns/digitalocean·caddy-l4 플러그인을 넣어 직접 빌드합니다 — DNS-01 인증서 발급을 위해서입니다.

4아키텍처 심화 분석

전체 시스템 구조도

패턴 1 — API를 네임스페이스 4개로 물리 분리

apps/api/plane/urls.py는 용도에 따라 완전히 다른 Django 앱을 각각의 경로에 붙입니다.

urlpatterns = [
    path("api/",           include("plane.app.urls")),      # 내부용 (세션 인증) · 233개
    path("api/public/",    include("plane.space.urls")),    # 공개 뷰       ·  25개
    path("api/instances/", include("plane.license.urls")),  # 인스턴스 관리
    path("api/v1/",        include("plane.api.urls")),      # 외부 공개 API (API 키) · 75개
    path("auth/",          include("plane.authentication.urls")), # 37개
]

여기서 배울 점은 "내부 API"와 "외부 공개 API"를 같은 뷰로 겸용하지 않았다는 것입니다. 내부용(plane.app)은 화면이 바뀌면 마음대로 깨도 되지만, 외부용(plane.api)은 남의 스크립트가 물려 있어 못 깹니다. 실제로 외부 API 파일에는 old_url_patterns라는 목록에 "Deprecated" 주석을 달고 옛 경로를 지우지 않은 채 남겨 둡니다. 총 라우트는 약 370개입니다.

패턴 2 — 프론트엔드를 앱 3개로 쪼갠 이유

한 앱에 조건문으로 섞을 수도 있었지만, 나누면 공개 뷰 번들에 내부 기능 코드가 애초에 들어가지 않습니다. 보안이 "권한 체크"가 아니라 "빌드 산출물 분리"로 보장되는 구조고, 셋 다 각자 Docker 이미지·nginx를 가집니다.

패턴 3 — 추상 모델 상속 사슬과 소프트 삭제

모델 93개가 전부 같은 뼈대를 물려받습니다. TimeAuditModel(생성·수정 시각) → UserAuditModel(생성·수정자) → SoftDeleteModel(삭제 표시) → 이 셋을 합친 AuditModel → UUID 기본키를 얹은 BaseModel 순입니다.

class SoftDeletionManager(models.Manager):
    def get_queryset(self):
        return SoftDeletionQuerySet(self.model, using=self._db).filter(deleted_at__isnull=True)

class SoftDeleteModel(models.Model):
    deleted_at = models.DateTimeField(null=True, blank=True)
    objects = SoftDeletionManager()   # 기본 매니저: 삭제된 건 안 보임
    all_objects = models.Manager()    # 탈출구: 삭제된 것까지 전부

    def delete(self, using=None, soft=True, *args, **kwargs):
        if soft:
            self.deleted_at = timezone.now()
            self.save(using=using)
            soft_delete_related_objects.delay(...)  # 연관 객체는 Celery가 뒤따라 처리
        else:
            return super().delete(using=using, *args, **kwargs)

핵심은 기본 매니저가 삭제된 행을 자동으로 걸러준다는 점입니다. 개발자가 filter(deleted_at__isnull=True)를 매번 안 써도 되고, 빠뜨려서 유령 데이터가 노출되는 사고도 안 납니다. 대신 실제 삭제 조회가 필요할 때만 all_objects라는 명시적 탈출구를 씁니다. 그리고 연쇄 삭제는 요청 안에서 처리하지 않고 Celery에 넘겨서, 이슈 1개 삭제가 트랜잭션을 몇 초씩 물고 있는 사태를 막습니다.

패턴 4 — 분수 정렬(fractional ordering)

칸반에서 카드를 3번과 4번 사이로 끌어놓으면, 순진한 구현은 뒤의 모든 행 번호를 1씩 밀어 올립니다(1000개면 1000번 UPDATE). Plane은 sort_order를 정수가 아닌 FloatField(default=65535)로 두고, 새 항목은 같은 그룹 최대값 + 10000을 받습니다. 사이에 끼울 땐 앞뒤 값의 중간값을 계산해 단 한 행만 UPDATE합니다. State.sequence도 같은 방식(15000 간격)입니다.

패턴 5 — Yjs 바이너리를 행에 그대로 저장

문서 동시 편집은 CRDT(Yjs)로 합니다. 보통은 별도 문서 저장소를 두는데, Plane은 Issue/Page 행에 컬럼 3개를 나란히 둡니다.

apps/live/src/extensions/database.ts가 이 셋을 관리합니다 — 문서를 열 때 바이너리가 비어 있으면 HTML에서 역변환해 채워 넣고, 저장할 때는 세 표현을 한 번에 API로 되돌려 씁니다. Redis는 여러 live 인스턴스 사이의 전달만 담당하고, 영속 저장은 Postgres입니다. 즉 협업 서버를 몇 대로 늘려도 데이터는 한 곳에 모입니다.

패턴 6 — 권한은 숫자 3개가 전부

class ROLE(Enum):
    ADMIN  = 20
    MEMBER = 15
    GUEST  = 5

def allow_permission(allowed_roles, level="PROJECT", creator=False, model=None):
    ...  # WorkspaceMember / ProjectMember 의 role 값을 대조

워크스페이스든 프로젝트든 같은 3단계를 씁니다. 숫자로 둔 덕에 "MEMBER 이상"을 role >= 15로 표현할 수 있고, 나중에 등급을 끼워 넣어도(예: 10) 기존 비교가 안 깨집니다. 프론트엔드도 packages/types/src/enums.ts에 EUserPermissions로 똑같은 숫자를 복제해 둡니다 — 화면 표시와 서버 판정이 같은 사전을 보게 하려는 것입니다.

패턴 7 — 프로젝트별 일련번호를 DB 락으로

Jira의 ENG-142 같은 번호는 프로젝트마다 1씩 올라갑니다. 동시에 두 명이 이슈를 만들면 번호가 겹칠 수 있는데, Plane은 Postgres의 pg_advisory_xact_lock(트랜잭션 단위 자문 잠금)으로 sequence_id 발급 구간을 직렬화합니다. 애플리케이션 락이나 재시도 루프가 아니라 DB가 제공하는 원자적 수단을 쓴 사례입니다.

웹훅 — 나가는 요청도 막아 둔다

hmac_signature = hmac.new(
    webhook.secret_key.encode("utf-8"),
    json.dumps(payload).encode("utf-8"),
    hashlib.sha256,
)
headers["X-Plane-Signature"] = hmac_signature.hexdigest()

받는 쪽이 "이 요청이 정말 내 Plane에서 왔는지" 검증할 수 있게 HMAC 서명을 붙입니다. 동시에 settings/common.py에는 WEBHOOK_ALLOWED_IPS · WEBHOOK_ALLOWED_HOSTS · WEBHOOK_DISALLOWED_DOMAINS가 있습니다 — 사용자가 웹훅 주소를 http://169.254.169.254/(클라우드 메타데이터) 같은 내부 주소로 넣어 서버를 대신 심부름 보내는 SSRF 공격을 막기 위한 것입니다. 여기에 취약한 SECRET_KEY 하드코딩 목록(GHSA-cmwv-pjmw-8483)을 감지해 경고를 띄우는 코드까지 있습니다.

5디렉토리 구조 해부

store/issue/ 하나만 봐도 규모가 보입니다 — archived/, cycle/, module/, profile/, project/, project-views/, workspace/, workspace-draft/, issue-details/, helpers/에 더해 보기 방식별 스토어(캘린더·간트·칸반) 3개가 따로 있습니다. "이슈 목록"이 어디서 오느냐가 맥락마다 다르기 때문에 스토어를 그 맥락 수만큼 나눈 구조입니다.

6학습 포인트 (기술별)

export class IssueStore implements IIssueStore {
  issuesMap: { [issue_id: string]: TIssue } = {};
  issueService;
  constructor() {
    makeObservable(this, {
      issuesMap: observable,
      addIssue: action, updateIssue: action, removeIssue: action,
    });
    this.issueService = new IssueService();
  }
}

7하드웨어 / 시스템 요구사항

현실적인 권장값을 정리하면:

• 그냥 써 보기 (미리 빌드된 이미지 + docker compose): 2 vCPU · 4GB RAM · 20GB 디스크
• 소스 빌드 · 기여: 4 vCPU · 12GB RAM 이상 · 디스크 30GB+ (얕은 클론만 101MB, node_modules 별도)
• GPU 필요 없음 — 저장소 어디에도 GPU·특수 하드웨어 요구가 없습니다
• 바깥으로 열어야 하는 포트는 80/443 뿐(Caddy). 나머지는 전부 내부 네트워크

8직접 해볼 수 있는 실습 과제

9관련 기술 심화 학습 로드맵

더 깊이 가고 싶다면

• 비교 학습: 같은 문제를 다른 스택으로 푼 저장소와 나란히 보기 — Twenty(CRM, NestJS+GraphQL), Focalboard, Vikunja(Go), Taiga(Django, 구세대 설계)
• 정렬 알고리즘: 분수 정렬의 정밀도 한계(float 반복 삽입 시 자릿수 고갈)와 대안인 LexoRank·fractional indexing 문자열 방식
• CRDT 이론: Yjs가 쓰는 YATA 알고리즘, OT와의 차이, 오프라인 병합이 왜 어려운가
• Rust 툴체인: oxlint·oxfmt·nh3처럼 JS/Python 생태계 안에 Rust 도구가 들어오는 흐름 (oxc, Biome, ruff, uv)

10핵심 키워드 사전

11참고 링크

프로젝트

• github.com/makeplane/plane — 저장소 (기본 브랜치는 master가 아니라 preview)
• plane.so — 공식 사이트·클라우드
• developers.plane.so — 외부 API 문서
• CONTRIBUTING.md — 개발 환경 세팅 (버전 기재는 오래됐으니 Dockerfile과 대조)
• Releases — 현재 v1.4.2 계열

핵심 의존 기술

• Django 5.2 문서 · Django REST Framework
• Celery 문서 — 특히 beat 스케줄링
• React Router 7 — 프레임워크 모드가 Next.js 자리를 어떻게 대체하는지
• MobX 6 · mobx-utils (computedFn)
• TipTap · Yjs · Hocuspocus
• Pragmatic drag and drop — 칸반 구현의 표준 선택지
• Turborepo · pnpm catalogs
• Caddy · xcaddy
• oxc (oxlint · oxfmt) — Rust 기반 JS 툴체인

비교해 볼 만한 저장소

• twentyhq/twenty — 오픈소스 CRM. NestJS + GraphQL로 같은 급의 문제를 다르게 푼 사례
• go-vikunja/vikunja — Go로 만든 할 일 관리. 훨씬 가벼운 대안
• kanboard/kanboard — PHP 단일 파일급 초경량 칸반. 반대편 극단