290 lines
31 KiB
Plaintext
290 lines
31 KiB
Plaintext
╔════════════════════════════════════════════════════════════════════════════════════════╗
|
|
║ GoodGo POS System - Deployment Architecture ║
|
|
║ (As of 2026-04-09) ║
|
|
╚════════════════════════════════════════════════════════════════════════════════════════╝
|
|
|
|
┌─ DEPLOYMENT ENVIRONMENTS ──────────────────────────────────────────────────────────────┐
|
|
│ │
|
|
│ LOCAL DEVELOPMENT STAGING PRODUCTION │
|
|
│ ═══════════════════════ ═════════════ ══════════════ │
|
|
│ │
|
|
│ docker-compose.yml Kubernetes (RKE2) Kubernetes (RKE2) │
|
|
│ (1349 lines) Multi-node cluster Multi-node cluster │
|
|
│ Single machine ≥3 nodes │
|
|
│ │
|
|
│ ┌─────────────────┐ ┌──────────────────┐ ┌──────────────────┐ │
|
|
│ │ All 26 Services │ │ 35 Services │ │ 14 Services │ │
|
|
│ │ PostgreSQL 16 │ │ Neon PostgreSQL │ │ Neon PostgreSQL │ │
|
|
│ │ Redis 7 │ │ (cloud) │ │ (cloud) │ │
|
|
│ │ RabbitMQ 3 │ │ │ │ │ │
|
|
│ │ MinIO │ │ Domain: │ │ Domain: │ │
|
|
│ │ Traefik │ │ api.staging. │ │ goodgo.vn │ │
|
|
│ │ Full Observ. │ │ goodgo.vn │ │ pos.goodgo.vn │ │
|
|
│ └─────────────────┘ └──────────────────┘ └──────────────────┘ │
|
|
│ │
|
|
└─────────────────────────────────────────────────────────────────────────────────────────┘
|
|
|
|
┌─ KUBERNETES MANIFESTS (deployments/) ──────────────────────────────────────────────────┐
|
|
│ │
|
|
│ STAGING (35 YAML files) PRODUCTION (14 YAML files) │
|
|
│ ════════════════════════ ════════════════════════════ │
|
|
│ │
|
|
│ Core POS (8) Core POS (8) │
|
|
│ • iam-service • iam-service │
|
|
│ • merchant-service • merchant-service │
|
|
│ • order-service • order-service │
|
|
│ • fnb-engine • fnb-engine │
|
|
│ • catalog-service • catalog-service │
|
|
│ • inventory-service • inventory-service │
|
|
│ • wallet-service • wallet-service │
|
|
│ • booking-service • booking-service │
|
|
│ │
|
|
│ Engagement (5) Infrastructure (6) │
|
|
│ • promotion-service • redis.yaml │
|
|
│ • membership-service • ingress.yaml │
|
|
│ • chat-service • namespace.yaml │
|
|
│ • social-service • configmap.yaml │
|
|
│ • mission-service • secrets.yaml │
|
|
│ │
|
|
│ Advertising (5) │
|
|
│ • ads-manager-service │
|
|
│ • ads-serving-service │
|
|
│ • ads-billing-service │
|
|
│ • ads-tracking-service │
|
|
│ • ads-analytics-service │
|
|
│ │
|
|
│ Marketing Integrations (4) │
|
|
│ • mkt-facebook-service │
|
|
│ • mkt-whatsapp-service │
|
|
│ • mkt-x-service │
|
|
│ • mkt-zalo-service │
|
|
│ │
|
|
│ Utilities & Infrastructure (8) │
|
|
│ • storage-service │
|
|
│ • mining-service │
|
|
│ • rabbitmq.yaml │
|
|
│ • redis.yaml, redis-sentinel.yaml │
|
|
│ • minio.yaml │
|
|
│ • ingress.yaml, namespace.yaml, network-policy.yaml │
|
|
│ • configmap.yaml, secrets.yaml │
|
|
│ • act-runner-rbac.yaml, gitea-sync-cronjob.yaml │
|
|
│ │
|
|
└─────────────────────────────────────────────────────────────────────────────────────────┘
|
|
|
|
┌─ CONFIGURATION MANAGEMENT ────────────────────────────────────────────────────────────┐
|
|
│ │
|
|
│ ┌── CONFIGMAP.YAML (Public Configuration) │
|
|
│ │ │
|
|
│ │ ASP.NET Core JWT Configuration Service Discovery (K8s DNS) │
|
|
│ │ ──────────────── ──────────────── ───────────────────────── │
|
|
│ │ ASPNETCORE_ENV Jwt__Authority [ServiceName]__BaseUrl │
|
|
│ │ ASPNETCORE_URLS Jwt__Audience iam-service:8080 │
|
|
│ │ Jwt__RequireHttps merchant-service:8080 │
|
|
│ │ order-service:8080 │
|
|
│ │ Cache & Messaging Feature Flags ... (26 services) │
|
|
│ │ ────────────────── ────────────── │
|
|
│ │ Redis__Host:redis Features__Swagger CORS Origins │
|
|
│ │ Redis__Port:6379 Features__Details Staging: │
|
|
│ │ RabbitMQ__Port:5672 API_VERSION: v1 • platform.techbi.org │
|
|
│ │ • api.techbi.org │
|
|
│ │ Storage Logging Level Production: │
|
|
│ │ ─────── ───────────── • pos.goodgo.vn │
|
|
│ │ MinIO__Bucket Staging: Info • goodgo.vn │
|
|
│ │ MinIO__BucketName Production: Warning • admin.goodgo.vn │
|
|
│ │ │
|
|
│ └───────────────────────────────────────────────────────────────────────── │
|
|
│ │
|
|
│ ┌── SECRETS.YAML (PLACEHOLDER - Real values in kubectl/GitHub Secrets) │
|
|
│ │ │
|
|
│ │ JWT Secrets (2) Database URLs (23) Infrastructure │
|
|
│ │ ──────────────── ────────────────── ────────────── │
|
|
│ │ • Jwt__Secret • IAM_DATABASE_URL Redis: │
|
|
│ │ • Jwt__RefreshSecret • MERCHANT_DATABASE_URL • Redis__Password │
|
|
│ │ • ORDER_DATABASE_URL • ConnectionStrings │
|
|
│ │ OIDC • ... (20 more services) MinIO: │
|
|
│ │ ──── • AccessKey, SecretKey │
|
|
│ │ IdentityServer__IssuerUri Connection Format: • Endpoint │
|
|
│ │ Host=host;Port=5432; RabbitMQ: │
|
|
│ │ Database=db;Username=user; • Username, Password │
|
|
│ │ Password=pass;SSL=Prefer │
|
|
│ │ │
|
|
│ └───────────────────────────────────────────────────────────────────────── │
|
|
│ │
|
|
└─────────────────────────────────────────────────────────────────────────────────────────┘
|
|
|
|
┌─ DATABASE ARCHITECTURE ───────────────────────────────────────────────────────────────┐
|
|
│ │
|
|
│ PER-SERVICE DATABASE PATTERN │
|
|
│ ════════════════════════════════ │
|
|
│ │
|
|
│ Service → Database PostgreSQL Location │
|
|
│ ──────────────────────────────────────────────────────────────────────── │
|
|
│ iam-service-net → iam_service Neon (cloud) │
|
|
│ merchant-service-net → merchant_service Neon (cloud) │
|
|
│ order-service-net → order_service Neon (cloud) │
|
|
│ fnb-engine-net → fnb_engine Neon (cloud) │
|
|
│ catalog-service-net → catalog_service Neon (cloud) │
|
|
│ inventory-service-net → inventory_service Neon (cloud) │
|
|
│ wallet-service-net → wallet_service Neon (cloud) │
|
|
│ booking-service-net → booking_service Neon (cloud) │
|
|
│ promotion-service-net → promotion_service Neon (cloud) │
|
|
│ membership-service-net → membership_service Neon (cloud) │
|
|
│ chat-service-net → chat_service Neon (cloud) │
|
|
│ social-service-net → social_service Neon (cloud) │
|
|
│ storage-service-net → storage_service Neon (cloud) │
|
|
│ mining-service-net → mining_service Neon (cloud) │
|
|
│ mission-service-net → mission_service Neon (cloud) │
|
|
│ ads-manager-service-net → ads_manager_service Neon (cloud) │
|
|
│ ads-serving-service-net → ads_serving_service Neon (cloud) │
|
|
│ ads-billing-service-net → ads_billing_service Neon (cloud) │
|
|
│ ads-tracking-service-net → ads_tracking_service Neon (cloud) │
|
|
│ ads-analytics-service-net → ads_analytics_service Neon (cloud) │
|
|
│ mkt-facebook-service-net → mkt_facebook_service Neon (cloud) │
|
|
│ mkt-whatsapp-service-net → mkt_whatsapp_service Neon (cloud) │
|
|
│ mkt-x-service-net → mkt_x_service Neon (cloud) │
|
|
│ mkt-zalo-service-net → mkt_zalo_service Neon (cloud) │
|
|
│ │
|
|
│ [Additional services continue...] │
|
|
│ │
|
|
└─────────────────────────────────────────────────────────────────────────────────────────┘
|
|
|
|
┌─ DATABASE MIGRATIONS ──────────────────────────────────────────────────────────────────┐
|
|
│ │
|
|
│ Pattern: services/[service-name]-net/src/[Service].Infrastructure/ │
|
|
│ │
|
|
│ Migrations/ │
|
|
│ ├── yyyyMMddHHmmss_Name.cs (Migration implementation) │
|
|
│ ├── yyyyMMddHHmmss_Name.Designer.cs (EF Core generated) │
|
|
│ └── [ServiceName]ContextModelSnapshot.cs (Current model snapshot) │
|
|
│ │
|
|
│ Example - Order Service Migrations: │
|
|
│ • 20260117175742_InitialOrder.cs │
|
|
│ • 20260305004928_AddTableIdAndDiscountFields.cs │
|
|
│ • 20260306175520_PhaseTwo.cs │
|
|
│ │
|
|
│ All 22 .NET services have migration files following this pattern. │
|
|
│ │
|
|
└─────────────────────────────────────────────────────────────────────────────────────────┘
|
|
|
|
┌─ CLEAN ARCHITECTURE PATTERN (Per Service) ────────────────────────────────────────────┐
|
|
│ │
|
|
│ ServiceName/ │
|
|
│ │ │
|
|
│ ├── src/ │
|
|
│ │ ├── ServiceName.API/ │
|
|
│ │ │ ├── Application/ │
|
|
│ │ │ │ ├── Commands/ (CQRS Commands + IRequestHandler) │
|
|
│ │ │ │ ├── Queries/ (CQRS Queries + IRequestHandler) │
|
|
│ │ │ │ ├── Validations/ (FluentValidation) │
|
|
│ │ │ │ └── Behaviors/ (LoggingBehavior, ValidatorBehavior, TransactionBehavior)
|
|
│ │ │ ├── Controllers/ ([ApiVersion("1.0")]) │
|
|
│ │ │ └── Program.cs (DI + Middleware Pipeline) │
|
|
│ │ │ │
|
|
│ │ ├── ServiceName.Domain/ │
|
|
│ │ │ ├── AggregatesModel/[Entity]/ │
|
|
│ │ │ │ ├── [Entity].cs (Aggregate Root) │
|
|
│ │ │ │ └── I[Entity]Repository.cs │
|
|
│ │ │ ├── SeedWork/ │
|
|
│ │ │ │ ├── Entity.cs (Base with DomainEvents) │
|
|
│ │ │ │ ├── IAggregateRoot.cs │
|
|
│ │ │ │ ├── IRepository.cs │
|
|
│ │ │ │ ├── ValueObject.cs │
|
|
│ │ │ │ └── Enumeration.cs │
|
|
│ │ │ ├── Events/ (Domain Events - INotification) │
|
|
│ │ │ └── Exceptions/ │
|
|
│ │ │ │
|
|
│ │ └── ServiceName.Infrastructure/ │
|
|
│ │ ├── Persistence/ (DbContext, IUnitOfWork, Domain Event Dispatch) │
|
|
│ │ ├── EntityConfigurations/ (Fluent API, snake_case columns) │
|
|
│ │ ├── Repositories/ (Repository Implementations) │
|
|
│ │ ├── Migrations/ (EF Core Migrations) │
|
|
│ │ ├── Idempotency/ (RequestManager for Duplicate Detection) │
|
|
│ │ └── DependencyInjection.cs (AddInfrastructure()) │
|
|
│ │ │
|
|
│ └── tests/ │
|
|
│ ├── ServiceName.UnitTests/ (xUnit + Moq + FluentAssertions) │
|
|
│ └── ServiceName.FunctionalTests/ (WebApplicationFactory + InMemory DB) │
|
|
│ │
|
|
└─────────────────────────────────────────────────────────────────────────────────────────┘
|
|
|
|
┌─ DOCUMENTATION STRUCTURE ─────────────────────────────────────────────────────────────┐
|
|
│ │
|
|
│ docs/ │
|
|
│ ├── README.md (Project overview) │
|
|
│ ├── production-checklist.md (82-point deployment checklist) │
|
|
│ ├── adr/ (Architecture Decision Records) │
|
|
│ ├── audit/ (19 role-based audit reports) │
|
|
│ ├── en/ (English documentation) │
|
|
│ │ ├── architecture/ (8 architecture docs) │
|
|
│ │ ├── guides/ (9 deployment & dev guides) │
|
|
│ │ ├── skills/ (15 skill docs) │
|
|
│ │ ├── runbooks/ (incident response, rollback) │
|
|
│ │ └── templates/ (templates for extensions) │
|
|
│ └── vi/ (Vietnamese translations) │
|
|
│ └── [same structure as en/] │
|
|
│ │
|
|
│ Key Files: │
|
|
│ • CLAUDE.md (Agent config & full architecture) │
|
|
│ • ROADMAP.md (Development phases & features) │
|
|
│ • CTO_DEPLOYMENT_REPORT.md (Deployment analysis) │
|
|
│ • CTO_FIX_TRACKER.md (Bug tracking) │
|
|
│ │
|
|
└─────────────────────────────────────────────────────────────────────────────────────────┘
|
|
|
|
┌─ TECH STACK ──────────────────────────────────────────────────────────────────────────┐
|
|
│ │
|
|
│ Backend Frontend Database Infrastructure │
|
|
│ ────────────── ──────────────── ──────────── ───────────────────── │
|
|
│ .NET 10.0 Blazor WASM PostgreSQL 16 Kubernetes (RKE2) │
|
|
│ C# 14 MudBlazor 8.15 Neon (cloud) Docker (containerization) │
|
|
│ ASP.NET Core MAUI Redis 7 Traefik v3 (API Gateway) │
|
|
│ MediatR 12.4+ SwiftUI (iOS) RabbitMQ 3 Prometheus (metrics) │
|
|
│ EF Core 10 MinIO (S3) Grafana (dashboards) │
|
|
│ FluentValidation Loki (logs) │
|
|
│ Serilog GitHub Actions (CI/CD) │
|
|
│ Polly (resilience) Docker Hub (registry) │
|
|
│ Dapper pnpm + Turborepo (monorepo) │
|
|
│ │
|
|
└─────────────────────────────────────────────────────────────────────────────────────────┘
|
|
|
|
┌─ DEPLOYMENT FLOW ─────────────────────────────────────────────────────────────────────┐
|
|
│ │
|
|
│ DEVELOPMENT BRANCH │
|
|
│ ↓ │
|
|
│ GitHub Push │
|
|
│ ↓ │
|
|
│ GitHub Actions (build & test) │
|
|
│ ↓ │
|
|
│ Build Docker Images (goodgo/*:sha) │
|
|
│ ↓ │
|
|
│ Push to Docker Hub │
|
|
│ ↓ │
|
|
│ STAGING DEPLOYMENT │
|
|
│ └─ kubectl apply -f deployments/staging/kubernetes/ │
|
|
│ └─ All 35 services deployed │
|
|
│ └─ Run smoke tests & E2E tests │
|
|
│ ↓ │
|
|
│ MANUAL APPROVAL (CTO + Tech Lead) │
|
|
│ ↓ │
|
|
│ PRODUCTION DEPLOYMENT │
|
|
│ └─ kubectl apply -f deployments/production/kubernetes/ │
|
|
│ └─ Core 14 services deployed │
|
|
│ └─ Canary: 1 replica → monitor → full rollout │
|
|
│ └─ Post-deployment verification (20 smoke tests) │
|
|
│ │
|
|
│ ROLLBACK (if needed) │
|
|
│ └─ kubectl rollout undo deployment/[service] -n production │
|
|
│ │
|
|
└─────────────────────────────────────────────────────────────────────────────────────────┘
|
|
|
|
╔════════════════════════════════════════════════════════════════════════════════════════╗
|
|
║ ║
|
|
║ Files Created in .claude/: ║
|
|
║ • POS_DEPLOYMENT_STATE.md (Comprehensive 13-section analysis) ║
|
|
║ • DEPLOYMENT_QUICK_REFERENCE.md (Quick lookup reference) ║
|
|
║ • DEPLOYMENT_ARCHITECTURE_VISUAL.txt (This visual architecture) ║
|
|
║ ║
|
|
║ Status: ✓ COMPLETE - Deployment state thoroughly analyzed and documented ║
|
|
║ ║
|
|
╚════════════════════════════════════════════════════════════════════════════════════════╝
|