Real-time railway platform for train tracking, railway information, and intelligent integrations.
Status: Initial Architecture / Project Setup
RailFlow는 실시간 철도 데이터를 수집해 RailFlow 내부 Domain으로 변환하고, 지도 기반 UI로 열차의 현재 상태를 제공하는 플랫폼이다.
- 외부 철도 데이터를 RailFlow의 Domain 언어로 번역한다.
- 열차의 현재 상태는 서버가 소유하고 관리한다.
- Web은 상태를 소비하고 렌더링만 담당한다.
| 영역 | 스택 |
|---|---|
| Language | TypeScript |
| Frontend | Next.js |
| Backend | NestJS |
| Monorepo | pnpm workspace, Turborepo |
| Map | MapLibre GL |
railflow/
├── apps/
│ ├── web/ # Next.js — 사용자 UI, 철도 지도
│ └── api/ # NestJS — 데이터 수집, Domain 변환, REST/SSE
│
├── packages/
│ └── contracts/ # Web / API 공유 타입
│
├── docs/
│ ├── architecture.md
│ ├── data-flow.md
│ └── conventions/
│
└── .github/
├── ISSUE_TEMPLATE/
└── pull_request_template.md
현재 단계에서 완료된 것은 구조와 규칙의 정의뿐이다. 실행 가능한 애플리케이션 코드는 아직 존재하지 않는다.
| 항목 | 상태 |
|---|---|
| Directory 구조 | ✅ 완료 |
| Git / Branch / Commit / PR Convention | ✅ 완료 |
| Architecture 문서 | ✅ 완료 |
| Monorepo 초기화 (pnpm / Turborepo) | ✅ 완료 |
NestJS 앱 초기화 (apps/api) |
✅ 완료 |
| Korail Provider (Raw 조회 + DTO) | ✅ 완료 |
Next.js 앱 초기화 (apps/web) |
⬜ 예정 |
| Korail Mapper | ⬜ 예정 |
| Train / Station Domain | ⬜ 예정 |
| Polling / Snapshot / SSE | ⬜ 예정 |
| MapLibre 지도 | ⬜ 예정 |
- Architecture — 시스템 구성, Domain / Provider 분리 원칙
- Data Flow — 데이터 처리 8단계와 각 단계의 책임
- KORAIL Provider — 외부 endpoint 응답 계약과 오류 모델
- Git Workflow — 브랜치 전략과 작업 흐름
- Branch Convention — 브랜치 네이밍 규칙
- Commit Convention — 커밋 메시지 규칙
- Issue Convention — Issue 작성 규칙
Issue 생성 → main 최신화 → 작업 Branch 생성 → 개발
→ Pull Request → main Merge → 작업 Branch 삭제
브랜치 이름은 {issue-number}-{prefix}-{main-function} 형식을 사용한다.
12-feat-korail-provider
14-fix-train-position
16-docs-architecture
자세한 내용은 Git Workflow를 참고한다.