22장: Platform 프로젝트 분석
Platform이란
Platform은 식품 공급망 이력 추적(traceability) SaaS 서비스다. 농업인이 작물을 재배하는 순간부터 소비자에게 도달하기까지의 모든 이력을 기록하고, 그 무결성을 블록체인으로 보증한다.
사용자 관점에서는 QR 코드를 스캔하면 “이 사과가 어느 농장에서, 언제, 어떤 방법으로 재배되었고, 어떤 유통 경로를 거쳤는지“를 신뢰할 수 있는 방식으로 확인할 수 있다.
기술 관점에서는 Rust + Axum + SQLx + Alloy + Solidity + Hyperledger Besu로 구성된 마이크로서비스 아키텍처다.
3개 마이크로서비스 구조
┌─────────────────────────────────────────────────────────────────┐
│ Platform 시스템 │
│ │
│ ┌────────────────┐ ┌────────────────┐ ┌────────────────────┐ │
│ │ account │ │ traceability │ │ iksan-api │ │
│ │ │ │ │ │ │ │
│ │ - 인증/인가 │ │ - 이력 추적 │ │ - 농업인/작물 │ │
│ │ - 계정 관리 │ │ - 제품 관리 │ │ - 블록체인 연동 │ │
│ │ - DID 신원 │ │ - 규정 준수 │ │ - 이벤트 처리 │ │
│ │ - 요금제 │ │ │ │ │ │
│ │ │ │ │ │ │ │
│ │ :3001 │ │ :3002 │ │ :3003 │ │
│ └───────┬────────┘ └───────┬────────┘ └────────┬───────────┘ │
│ │ │ │ │
│ ┌───────▼───────────────────▼────────────────────▼───────────┐ │
│ │ PostgreSQL (각 서비스별 DB 스키마) │ │
│ └───────────────────────────────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ Hyperledger Besu (IBFT 2.0) │ │
│ │ - TraceRecord 컨트랙트 │ │
│ │ - DID 컨트랙트 │ │
│ └─────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
서비스 간 통신
서비스들은 HTTP RPC로 통신한다. 예를 들어:
traceability가 이력 조회 시account에서 사용자 정보를 확인iksan-api가 이벤트를 처리할 때account에서 토큰을 검증
마이크로서비스 아키텍처지만 서비스 메시(Service Mesh)나 gRPC 없이 단순한 HTTP 통신을 사용한다. 규모가 커지면 이 부분을 개선할 수 있다.
기술 스택 전체 정리
언어 및 런타임
| 계층 | 기술 | 버전 |
|---|---|---|
| 언어 | Rust | 1.75+ |
| 비동기 런타임 | Tokio | 1.x |
| 웹 프레임워크 | Axum | 0.7 |
데이터베이스
| 서비스 | DB | ORM/쿼리 |
|---|---|---|
| account | PostgreSQL | SQLx |
| traceability | PostgreSQL | SQLx |
| iksan-api | PostgreSQL | SQLx |
모든 서비스가 PostgreSQL을 사용하지만 스키마는 분리되어 있다. 서비스 간 직접 DB 쿼리는 없고, 반드시 HTTP API를 통해 통신한다.
블록체인
| 항목 | 기술 |
|---|---|
| 클라이언트 | Hyperledger Besu |
| 합의 | IBFT 2.0 |
| Rust 라이브러리 | Alloy 0.9 |
| 컨트랙트 언어 | Solidity ^0.8.20 |
| 컨트랙트 개발 | Foundry (Forge, Cast) |
| 패턴 | UUPS 프록시 (업그레이드 가능) |
인프라
| 항목 | 기술 |
|---|---|
| 컨테이너 | Docker, Docker Compose |
| 리버스 프록시 | Nginx |
| 로깅 | tracing + tracing-subscriber |
| 설정 | 환경변수 + dotenvy |
보안
| 항목 | 구현 |
|---|---|
| 인증 | JWT (account 서비스 발급) |
| 신원 | DID (Decentralized Identifier) |
| API 보안 | Tower 미들웨어 |
| 개인키 관리 | 환경변수 (프로덕션: KMS) |
각 서비스의 역할 요약
account 서비스 (:3001)
사용자 인증과 신원 관리를 담당한다. Node.js 배경이라면 NestJS의 Auth 모듈 + Users 모듈이 합쳐진 것으로 이해하면 된다.
주요 기능:
- 회원가입/로그인 (JWT 발급)
- 계정 프로필 관리
- DID(탈중앙 신원) 등록/조회
- 요금제(subscription) 관리
- 블록체인 컨트랙트 배포 (Foundry 연동)
traceability 서비스 (:3002)
이력 추적의 핵심 비즈니스 로직을 담당한다.
주요 기능:
- 제품(product) 등록과 관리
- 이력 이벤트(trace event) 기록
- 규정 준수(compliance) 확인
- 공급망 경로 추적
- QR 코드 생성과 조회
iksan-api 서비스 (:3003)
농업인과 작물 데이터, 그리고 블록체인 연동의 핵심을 담당한다. “익산 API“라는 이름은 초기 파일럿 지역이 전북 익산이었기 때문이다.
주요 기능:
- 농업인 프로필 관리
- 작물/재배 정보 관리
- 이벤트를 블록체인에 기록 (가장 핵심)
- 해시 검증
- 블록체인 이벤트 인덱싱
코드 규모와 구조
platform의 각 서비스는 다음 구조를 따른다:
apps/{service-name}/
├── Cargo.toml
├── src/
│ ├── main.rs ← 서버 진입점
│ ├── core/
│ │ ├── app.rs ← AppState, 의존성 주입
│ │ └── config.rs ← 설정
│ ├── routes/
│ │ ├── mod.rs
│ │ └── {domain}.rs ← 라우트 핸들러
│ ├── services/
│ │ ├── mod.rs
│ │ ├── {domain}.rs ← 비즈니스 로직
│ │ └── blockchain.rs ← Alloy 연동
│ ├── repositories/
│ │ └── {domain}.rs ← DB 쿼리
│ ├── models/
│ │ └── {domain}.rs ← 데이터 타입
│ └── middleware/
│ └── auth.rs ← Tower 미들웨어
├── contracts/
│ └── src/
│ └── {Contract}.sol
└── migrations/
└── *.sql
이 구조는 다음 장에서 더 자세히 분석한다.
Platform이 가르쳐주는 것
platform 코드를 읽으면서 얻을 수 있는 것들:
- 실전 Rust 패턴:
Arc<AppState>,thiserror,anyhow, 트레이트 객체 활용 - Axum 실전: 미들웨어, 에러 처리, 상태 공유
- SQLx 실전: 마이그레이션, 복잡한 조인 쿼리, 트랜잭션
- Alloy 실전:
sol!매크로, 서명자 관리, 이벤트 인덱싱 - 마이크로서비스: 서비스 간 HTTP 통신, 에러 전파
이 장(22장) 전체에서 platform의 실제 코드 패턴을 분석한다.
다음 장(22-1)에서는 각 서비스의 구조를 Node.js/NestJS 패턴과 대응시켜 이해한다.