📘 SaaS 프로젝트 기술 문서(Architecture Document) 완성편

📘 SaaS 프로젝트 기술 문서(Architecture Document) 완성편

– 실제 회사에서 쓰는 수준으로 전체 시스템을 문서화하는 방법 –
(NestJS + Next.js + Terraform + K8s + Stripe + AI + RAG 기반 SaaS 기준)

---

우리는 지금까지 기획 → 개발 → 인프라 → 배포 → 운영 → AI → 구독 결제 → Observability까지
실제 SaaS 서비스를 만드는 전 과정을 끝냈다.

이제 마지막 단계는 **“문서화”**다.

코드가 아무리 훌륭해도 문서가 없으면
팀원이 들어올 수도 없고,
버그 대응도 어렵고,
투자자/클라이언트에게 설명조차 불가능하다.

이번 글에서는
실제 스타트업 / 기업에서 쓰는 기술 문서 템플릿과 함께
우리가 만든 SaaS 전체 시스템을 정리해본다.

이 글을 끝내면
“내 서비스의 기술 문서 한 번 보여줄게요.”
라고 할 수 있는 수준의 완성형 문서를 갖게 된다.

---

🧭 이번 글에서 만들 문서 종류

우리가 작성할 문서는 총 6종류다.

1. 시스템 아키텍처 문서 (System Architecture Document)
2. ERD + 데이터 모델 문서
3. API 스펙 문서 (Backend API Documentation)
4. 인프라 문서 (Infra / DevOps Architecture)
5. 운영 문서 (Monitoring · Alerting · Security Policy)
6. 장애 대응 Runbook (Incident Response Guide)

이 6개만 있으면
누가 와도 시스템을 이해할 수 있고,
개발자 온보딩도 훨씬 빨라진다.

---

1️⃣ 시스템 아키텍처 문서 (System Architecture)

반응형

1. 개요

본 문서는 Next.js + NestJS 기반의 AI SaaS 플랫폼 전체 구조를 설명한다.
API 서버, 프론트엔드, AI 엔진, Vector DB, Stripe Billing, Kubernetes 기반 인프라 및 DevOps 전체 체계를 포함한다.

2. 전체 아키텍처 다이어그램

              [Browser]
                  │
                  ▼
       ┌──────────────────────┐
       │   Next.js (CDN SSR)   │
       │  Cloudflare Pages     │
       └───────────┬──────────┘
                   │ REST/HTTPS
                   ▼
       ┌──────────────────────┐
       │     NestJS API       │
       │  Auth / Billing / AI │
       └───────────┬──────────┘
                   │
       ┌───────────▼──────────┐
       │  Vector DB (Qdrant)   │
       │  Redis Cache          │
       │  R2 Storage           │
       └───────────┬──────────┘
                   │
       ┌───────────▼──────────┐
       │   Kubernetes (EKS)    │
       │  Prometheus/Grafana   │
       │  ArgoCD (GitOps CI/CD)│
       └───────────────────────┘

---

2️⃣ ERD + 데이터 모델 문서

1. 핵심 테이블

User

필드 타입 설명

id	int	PK
email	string	unique
password	string	bcrypt hash
plan	enum(FREE, PRO, ENT)	구독 플랜
ai_limit	int	AI 일일 제한
createdAt	datetime	가입일

---

Subscription

필드 타입 설명

id	string	Stripe subscription id
userId	int	FK
status	active/canceled	Stripe 상태
currentPeriodEnd	datetime	갱신일

---

AiUsage

필드 타입 설명

id	int	PK
userId	int	FK
count	int	호출 1회 시 +1
createdAt	datetime	사용일

---

Document / Vector

필드 타입 설명

id	string	Qdrant vector id
text	string	본문
embedding	float[]	임베딩 벡터

---

3️⃣ API 스펙 문서 (OpenAPI 혹은 Markdown)

예: POST /auth/login

요청:
{
  "email": "test@example.com",
  "password": "1234"
}

응답:
{
  "token": "JWT",
  "user": {
    "id": 1,
    "plan": "PRO",
    "ai_limit": 200
  }
}

---

예: POST /ai/chat (요금제에 따라 Guard 적용)

요청:
{
  "prompt": "식물 잎이 노랗게 변했어. 이유 알려줘."
}

응답:
{
  "answer": "...",
  "tokens": 221
}

---

예: /billing/create-checkout-session

요청:
{
  "priceId": "price_abc123"
}

응답:
{
  "checkoutUrl": "https://checkout.stripe.com/..."
}

---

4️⃣ 인프라 문서 (Infra Architecture)

구성 목록

영역 기술

Compute	AWS EKS + EC2 NodeGroup
Networking	VPC, ALB, SecurityGroup
Storage	RDS(MySQL), Redis, R2
Containers	Docker + Kubernetes
CD	ArgoCD (GitOps)
CI	GitHub Actions
IaC	Terraform
CDN	Cloudflare
Image Registry	ECR

---

IaC 구조

/terraform
  /modules
     /vpc
     /eks
     /rds
     /redis
     /cloudflare
  main.tf
  variables.tf
  outputs.tf

---

CI/CD 흐름

Developer → Git Push(main)
 ↓
GitHub Actions (Docker Build)
 ↓
ECR Push
 ↓
k8s manifest 업데이트
 ↓
ArgoCD 자동 배포
 ↓
EKS API 서버 반영
 ↓
Cloudflare CDN 출력

---

5️⃣ 운영 문서 (Monitoring & Alerting)

Sentry Alerts

조건 알림

500 에러 발생	Slack #alert
오류율 > 5%	Slack + Email
성능 저하(trace slow)	Slack

---

Prometheus Alerts

메트릭 알림 규칙

CPU > 80% (5분 지속)	scale-out 필요
Memory > 85%	노드 증설
RPS 급감	서버 문제
5xx 증가	API 장애

---

Slack 알림 템플릿

🚨 *서버 오류 발생*
- 서비스: NestJS API
- 메시지: {{error}}
- 경로: {{url}}
- 시간: {{timestamp}}

---

6️⃣ 장애 대응 Runbook (Incident Response Guide)

운영에서 진짜 중요한 문서는 바로 이것.

---

장애 1: AI API 응답 없음

1. OpenAI 상태 페이지 확인
2. Circuit Breaker fallback 작동 여부 확인
3. Redis 캐시 fallback 실행
4. 요청 제한(Rate-limit) 확인
5. Sentry trace를 따라가 원인 확인

---

장애 2: 구독 결제 반영 안됨

1. Stripe Webhook 로그 확인
2. /stripe/webhook NestJS 로그 확인
3. Subscription 테이블 업데이트 누락 여부 확인
4. Stripe Dashboard → event resend

---

장애 3: API 500 폭증

1. Sentry Error message 형태 분석
2. 최근 배포 여부 확인 → ArgoCD rollback
3. Redis / DB 연결 상태 확인
4. Cloudflare WAF 로그 확인
5. Prometheus로 CPU/Memory 상태 점검

---

장애 4: 프론트 화면 안 뜸

1. Cloudflare Pages 빌드 로그 확인
2. Next.js API route 확인
3. env 값 누락 여부 검사
4. Cloudflare DNS propagation 확인

---

7️⃣ 문서를 어디에 저장해야 할까?

추천 구조:

/docs
  /architecture
  /infra
  /api
  /database
  /operating
  /runbook

또는 Notion, GitHub Wiki로 관리해도 된다.

---

🎉 이번 글 요약

항목 완료

시스템 아키텍처 문서	✔️
데이터 모델 문서	✔️
API 스펙 정리	✔️
인프라 DT 문서	✔️
모니터링/운영 문서	✔️
장애 대응 Runbook	✔️

이제 이 시리즈 전체가
**“사이드 프로젝트 → 진짜 서비스로 성장하는 전체 과정”**이 문서로 남았다.

---

🔮 다음편 예고 (실제 마지막 실무 단계)

다음 글에서는 기술 문서를 기반으로 하는 팀 온보딩(Onboarding) 가이드를 만든다.

“신입/주니어/외주 개발자가 이 프로젝트에 들어오면
무엇부터 읽고, 어떤 환경을 세팅하고, 어떤 순서로 개발해야 하는가?”

기업 실무에서 가장 중요한 문서이며
팀 효율을 가장 극적으로 올려주는 문서다.

---

 

SaaS문서화, 시스템아키텍처, DevOps문서, NestJS, Next.js, Stripe, Observability, VectorDB, Terraform, Kubernetes, Runbook