pos-system/microservices/.claude/README.md

GoodGo POS System - Deployment Analysis Documents

Ngày tạo: 2026-04-09
Trạng thái: ✓ Complete

This directory contains comprehensive analysis of the GoodGo POS system deployment infrastructure.

📄 Documents

1. POS_DEPLOYMENT_STATE.md (14 KB)

Comprehensive 13-section analysis of the entire deployment infrastructure.

Contents:

• Executive summary
• Kubernetes manifests inventory (35 staging, 14 production)
• Configuration management (ConfigMap & Secrets)
• Database migrations (22 services tracked)
• Documentation structure
• Infrastructure configuration
• Service architecture patterns
• Tech stack summary
• Environment comparison (local, staging, production)
• Production deployment checklist (82 items)
• Key observations & conclusions

Best for: Complete understanding of the deployment state

2. DEPLOYMENT_QUICK_REFERENCE.md (9.1 KB)

Quick lookup reference organized by topic.

Contents:

• Critical files & directories
• Kubernetes manifests (35 staging, 14 production)
• Services manifest details
• Database migrations quick reference
• Configuration file locations
• Environment comparison table
• Service categories (Core, Engagement, Advertising, Marketing, Utilities)
• Quick commands (local dev, logs, database access, K8s)
• Tech stack summary
• Files in .claude/

Best for: Quick lookups during development/deployment

3. DEPLOYMENT_ARCHITECTURE_VISUAL.txt (31 KB)

Visual ASCII architecture diagrams showing relationships and structure.

Contents:

• Deployment environments visual
• Kubernetes manifests overview
• Configuration management diagram
• Database architecture diagram
• Clean architecture pattern per service
• Documentation structure diagram
• Tech stack visualization
• Deployment flow diagram

Best for: Understanding relationships and architecture at a glance

---

🎯 Quick Start - By Use Case

I want to deploy to staging

→ Read: DEPLOYMENT_QUICK_REFERENCE.md (Pre-Deployment Checklist section)
→ Reference: POS_DEPLOYMENT_STATE.md (section 2: Configuration & Secrets, section 10: Production Deployment Checklist)

I need to understand the database setup

→ Read: DEPLOYMENT_ARCHITECTURE_VISUAL.txt (Database Architecture section)
→ Reference: POS_DEPLOYMENT_STATE.md (section 3: Database Migrations, section 7: Database Architecture)

I need to configure a new service

→ Read: DEPLOYMENT_QUICK_REFERENCE.md (Service Architecture section)
→ Reference: POS_DEPLOYMENT_STATE.md (section 7: Service Architecture Pattern)

I need to understand Kubernetes setup

→ Read: DEPLOYMENT_ARCHITECTURE_VISUAL.txt (Kubernetes Manifests section)
→ Reference: POS_DEPLOYMENT_STATE.md (section 1: Kubernetes Manifests)

I need secrets configuration

→ Read: DEPLOYMENT_QUICK_REFERENCE.md (Key Secrets section)
→ Reference: POS_DEPLOYMENT_STATE.md (section 2: Secrets Management)

I need to check migration status

→ Read: DEPLOYMENT_QUICK_REFERENCE.md (Database Migrations section)
→ Reference: POS_DEPLOYMENT_STATE.md (section 3: Database Migrations)

---

📊 Key Statistics

Metric	Value
Total Services	26 (all .NET 10)
Staging Manifests	35 YAML files
Production Manifests	14 YAML files
Database URLs	23 (one per service)
Environments	3 (local, staging, production)
Migration Tracking	22 services with migrations
Documentation	60+ markdown files (EN + VI)
Deployment Checklist	82 items
Docker Compose Lines	1,349 (local development)

---

🏗️ Architecture Overview

Three Tier Deployment

1. Local Development (Docker Compose)

   • All 26 services + infrastructure
   • PostgreSQL 16, Redis 7, RabbitMQ 3
   • Single machine setup

2. Staging (Kubernetes)

   • 35 services (full platform)
   • Neon PostgreSQL cloud
   • Testing & quality assurance

3. Production (Kubernetes)

   • 14 services (core only)
   • Neon PostgreSQL cloud
   • Stability & performance focused

Service Categories

• Core Platform (8): IAM, Merchant, Order, FnB Engine, Catalog, Inventory, Wallet, Booking
• Engagement (5): Promotion, Membership, Chat, Social, Mission
• Advertising (5): Ads Manager, Serving, Billing, Tracking, Analytics
• Marketing (4): Facebook, WhatsApp, X, Zalo integrations
• Utilities (2): Storage, Mining

---

🔐 Security & Configuration

Configuration Strategy

• ConfigMap (public): Service URLs, Redis, RabbitMQ, logging levels
• Secrets (protected): JWT keys, database URLs, credentials

Differences Between Environments

Config	Staging	Production
JWT Authority	https://api.techbi.org	http://iam-service:8080
CORS Origins	techbi.org	goodgo.vn
Services	35 (all)	14 (core)
Features	Swagger on	Swagger off
Log Level	Information	Warning

---

📚 Documentation Hierarchy

1. This README → Overview & navigation
2. DEPLOYMENT_QUICK_REFERENCE.md → Topic-based lookup
3. POS_DEPLOYMENT_STATE.md → Comprehensive reference
4. DEPLOYMENT_ARCHITECTURE_VISUAL.txt → Visual architecture

Additional resources:

• ../README.md - Project overview
• ../CLAUDE.md - Full architecture reference
• ../ROADMAP.md - Development roadmap
• ../docs/production-checklist.md - 82-item checklist
• ../docs/ - Comprehensive documentation (EN + VI)

---

🚀 Quick Commands Reference

Local Development

cd deployments/local
docker compose up -d
./scripts/db/migrate.sh
./scripts/dev/start-service.sh iam-service-net

Staging Deployment

kubectl apply -f deployments/staging/kubernetes/
kubectl get pods -n staging

Production Deployment

kubectl apply -f deployments/production/kubernetes/
kubectl rollout status deployment -n production

Cơ Sở Dữ Liệu Access

# Local
PGPASSWORD=goodgo-local-2024 psql -h localhost -U postgres

# Cloud (Neon)
psql postgresql://cloud_admin:PASSWORD@neon.host/db_name

---

✅ Verification Checklist

Use this to verify deployment state understanding:

• Can identify all 26 services and their purposes
• Understand the difference between staging (35) and production (14) services
• Know the 23 database URLs and connection pattern
• Can locate ConfigMap and Secrets files
• Understand service discovery via K8s DNS (service-name:8080)
• Know the Clean Architecture pattern used in all services
• Can navigate the documentation structure
• Understand the 3-tier deployment strategy
• Know what the 82-point production checklist covers
• Can execute basic deployment commands

---

📞 Support & Questions

For questions about:

• Deployment infrastructure → See POS_DEPLOYMENT_STATE.md sections 1-2
• Database setup → See section 3 & 7
• Configuration → See section 2 & DEPLOYMENT_QUICK_REFERENCE.md
• Service architecture → See section 7 & DEPLOYMENT_ARCHITECTURE_VISUAL.txt
• Documentation → See section 4
• Pre-deployment checks → See section 10

---

📝 Metadata

Item	Value
Generated	2026-04-09
Analysis Scope	Complete deployment infrastructure
Services Analyzed	26 microservices
Documentation Files	3 (this directory) + 60+ in docs/
Total Documentation	~100 KB
Trạng thái	✓ Complete & Current

---

Cập nhật lần cuối: 2026-04-09
Maintainer: VelikHo
Project: GoodGo Platform - Enterprise POS System