Tirosh Source Repo Guide
이 guide는 source-repo를 처음 보는 개발자가 repo의 목적, 실행 흐름, architecture boundary, delivery 정책을 빠르게 이해하도록 돕는 문서입니다.
source-repo는 Hospital-at-Home SaMD patient monitoring/risk assessment 예제를 기준으로 구성한 polyglot monorepo입니다.
이 guide에서는 아래 경계를 설명합니다.
- app과 reusable package의 책임
- contract와 fixture 관리
- CI/CD, release, versioning 기준
- Nexus registry와 package publish 기준
- container image와 firmware artifact 기준
실제 운영 환경으로 배포하는 흐름은 이 repo의 책임이 아닙니다. Kubernetes environment promotion, production secret, rollback은 CD repo와 infra gate에서 다룹니다.
1. 이 Guide가 다루는 것
1-1. Source Repo의 학습 범위
이 guide는 단순한 API reference가 아닙니다. 이 repo에서 반복되는 engineering boundary를 설명합니다.
| Boundary | 이 guide에서 확인할 것 |
|---|---|
| Product | Hospital-at-Home SaMD 예제가 어떤 clinical 흐름을 갖는지 확인합니다. |
| Architecture | app, package, usecase, adapter, contract가 어떻게 나뉘는지 확인합니다. |
| Local development | local toolchain, compose demo, smoke command를 확인합니다. |
| Development workflow | issue, branch, commit, PR, self-review 기준을 확인합니다. |
| Languages | TypeScript, Python, Rust, Go, C/Firmware가 각각 맡는 책임을 확인합니다. |
| Delivery | CI gate, branch 전략, versioning, release, Nexus, container 기준을 확인합니다. |
1-2. 이 Guide가 직접 다루지 않는 것
Source repo는 deployable artifact를 만들고 검증합니다. 아래 항목은 CD repo나 infra 문서에서 다룹니다.
- Kubernetes environment overlay
- production secret
- cluster policy
- environment promotion
- production rollback
2. 처음 온 사람을 위한 길
2-1. 30분 안에 큰 그림 보기
repo의 목적과 구조만 먼저 잡고 싶다면 아래 순서로 읽습니다.
- Getting Started Overview로 repo 구조와 책임을 봅니다.
- Product Scenario로 Hospital-at-Home 예제 맥락을 봅니다.
- Architecture Overview로 app/package/usecase/adapter 경계를 봅니다.
- Contribution Flow로 issue, branch, PR 흐름을 봅니다.
- Glossary에서 낯선 delivery 용어를 확인합니다.
2-2. Local에서 실행까지 가기
local에서 demo를 직접 올리는 것이 목표라면 아래 순서가 빠릅니다.
- Local Development로 필요한 toolchain을 준비합니다.
- Demo Flow로 device-to-dashboard path를 실행합니다.
- Containers로 compose와 container image 기준을 확인합니다.
- 문제가 생기면 CI/CD의 local Make target 기준을 확인합니다.
2-3. Delivery 정책 이해하기
branch, package, image, release publish 정책을 이해하려면 아래 순서로 읽습니다.
- CI/CD로 PR,
main, release tag에서 무엇이 실행되는지 봅니다. - Versioning으로 dev version과 release version을 구분합니다.
- Release로 package, image, firmware artifact handoff를 확인합니다.
- Nexus로 registry 주소와 credential 기준을 확인합니다.
- Security로 supply-chain permission 기준을 확인합니다.
3. 상황별 빠른 이동
3-1. 자주 찾는 질문
| 하고 싶은 일 | 먼저 볼 문서 |
|---|---|
| local에서 repo를 준비하고 싶다 | Local Development |
| compose demo와 smoke를 실행하고 싶다 | Demo Flow |
| app/package 경계를 이해하고 싶다 | App / Package Boundary |
| contract와 fixture 기준을 보고 싶다 | Contracts |
| issue, branch, commit, PR 규칙을 확인하고 싶다 | Contribution Flow |
| CI, branch, publish 정책을 확인하고 싶다 | CI/CD |
| release 절차와 artifact 기준을 보고 싶다 | Release |
| Nexus registry 주소와 credential 기준이 궁금하다 | Nexus |
| container image build/publish 기준을 보고 싶다 | Containers |
| SaMD traceability와 품질 기준을 보고 싶다 | SaMD Quality |
| 낯선 용어를 빠르게 확인하고 싶다 | Glossary |
3-2. 언어별 시작점
| 언어 또는 영역 | 문서 |
|---|---|
| TypeScript / React | TypeScript / React |
| Python | Python |
| Rust | Rust |
| Go | Go |
| C / Firmware | C / Firmware |
| Python API reference | Python API |
| Storage reference | Storage |
4. Guide Map
4-1. Getting Started
Getting Started 문서는 repo를 처음 보는 사람이 local 실행 흐름까지 도달하는 길입니다.
| Topic | Document |
|---|---|
| Repo overview | getting-started/overview.md |
| Local development | getting-started/local-development.md |
| Demo flow | getting-started/demo-flow.md |
4-2. Development Workflow
Development Workflow 문서는 작업을 issue로 시작하고, branch와 commit을 만들고, PR로 main에 반영하는 기준을 설명합니다.
| Topic | Document |
|---|---|
| Contribution flow | workflow/contribution-flow.md |
4-3. Product And Architecture
Product 문서는 예제 제품의 언어를 정의하고, Architecture 문서는 그 제품 언어가 코드 경계로 어떻게 나뉘는지 설명합니다.
| Topic | Document |
|---|---|
| Product scenario | product/scenario.md |
| Clinical workflow | product/clinical-workflow.md |
| SaMD quality traceability | product/samd-quality.md |
| Architecture overview | architecture/overview.md |
| Clean Architecture | architecture/clean-architecture.md |
| App/package boundary | architecture/app-package-boundary.md |
| Cross-language contracts | architecture/contracts.md |
4-4. Delivery And Reference
Delivery 문서는 package, image, firmware artifact, registry, release handoff를 다룹니다. Reference 문서는 특정 boundary를 더 자세히 검토할 때 사용합니다.
| Topic | Document |
|---|---|
| CI/CD | delivery/ci-cd.md |
| Release | delivery/release.md |
| Versioning | delivery/versioning.md |
| Nexus | delivery/nexus.md |
| Containers | delivery/containers.md |
| Security | delivery/security.md |
| Glossary | glossary.md |
| Clinical UI review | reference/clinical-ui-review.md |
| Firmware driver boundary | reference/firmware-driver-boundary.md |
5. 이 Guide를 읽을 때의 기준
5-1. 표준의 세 가지 의미
이 guide에서 “표준”은 세 가지 의미로 나눠 씁니다.
| Category | Meaning |
|---|---|
| Industry de facto | 생태계에서 널리 쓰이며 새 팀원이 외부 경험으로 이해하기 쉬운 기본 선택입니다. |
| Team standard | Tirosh repo에서 반복성과 CI parity를 위해 고정한 선택입니다. |
| Product-specific rule | Hospital-at-Home SaMD 예제와 내부 delivery 환경 때문에 생긴 규칙입니다. |
5-2. 문서와 코드는 같은 경계를 봐야 한다
문서에만 있는 기준이나 코드에만 있는 관행은 오래 유지되기 어렵습니다.
- Repo 전체 빠른 시작은
source-repo/README.md가 담당합니다. - MkDocs site의 문서 탐색은 이 Home이 담당합니다.
- App과 package별 실행/사용법은 각 app/package
README.md가 담당합니다. - Delivery 기준은 CI/CD, Release, Security를 따릅니다.
6. 검증 명령
6-1. 문서 검증
문서 변경은 strict build로 확인합니다.
make docs/check
6-2. Demo 검증
문서에서 설명하는 device-to-dashboard path가 실제로 이어지는지 확인하려면 demo smoke를 실행합니다.
make demo/check