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

# Hệ Thống GoodGo POS - Khảo Sát Cài Đặt Phát Triển Cục Bộ
**Ngày tạo**: 2026-04-12  
**Đường dẫn gốc**: /Users/velikho/Desktop/WORKING/pos-system

---

## EXECUTIVE SUMMARY

The GoodGo POS system uses a **sophisticated multi-tier Docker Compose setup** for local development on macOS. The local environment is completely self-contained with all infrastructure services (PostgreSQL, Redis, RabbitMQ, MinIO) running in Docker containers, while .NET microservices can run either via Docker OR directly via `dotnet watch run` with hot-reload.

**Key Insight**: The development setup uses a **hybrid approach**:
- Infrastructure (databases, caches, brokers) → Docker Compose
- Backend services → Can run in Docker OR locally with hot-reload
- Frontend apps → Can run locally via `pnpm dev`

---

## 1. DOCKER COMPOSE ARCHITECTURE

### File Location
`deployments/local/docker-compose.yml` (1,645 lines)

### Container Overview

#### **Shared Infrastructure Tier** (6 services)
Services that all microservices depend on:

| Service | Image | Port | Network | Mục đích |
|---------|-------|------|---------|---------|
| `postgres` | postgres:16-alpine | 5432 | microservices-network | Central PostgreSQL 16 database server |
| `redis` | redis:7-alpine | 6379 | microservices-network | Cache & SignalR backplane for all services |
| `redis-exporter` | oliver006/redis_exporter:latest | 9121 | microservices-network | Prometheus metrics scraper for Redis |
| `minio` | minio/minio:latest | 9000/9001 | microservices-network | S3-compatible object storage (API/Console) |
| `rabbitmq` | rabbitmq:3-management-alpine | 5672/15672 | microservices-network | Message broker (AMQP/Management UI) |
| `traefik` | traefik:v3.3 | 80/8080 | microservices-network | API Gateway & reverse proxy |

#### **Backend Microservices Tier** (26 services total)

**Core Platform Services (6)**
| Service | Port | Database | Key Dependencies |
|---------|------|----------|------------------|
| iam-service-net | 5001 | iam_service | postgres, redis |
| storage-service | 5002 | storage_service | iam-service, minio |
| membership-service-net | 5003 | membership_service | iam-service |
| wallet-service-net | 5004 | wallet_service | iam-service |
| merchant-service-net | 5005 | merchant_service | iam-service |
| mining-service-net | 5006 | mining_service | iam-service, redis |

**Engagement & Social Services (5)**
| Service | Port | Database | Mục đích |
|---------|------|----------|---------|
| mission-service-net | 5007 | mission_service | Gamification (check-ins, tasks) |
| promotion-service-net | 5008 | promotion_service | Vouchers, campaigns, gift cards |
| social-service-net | 5009 | social_service | Profiles, posts, followers |
| chat-service-net | 5010 | chat_service | Real-time SignalR chat |
| ads-manager-service-net | 5011 | ads_manager_service | Ad campaign management |

**Ads Services (5)**
| Service | Port | Database | Special Config |
|---------|------|----------|-----------------|
| ads-serving-service-net | 5012 | ads_serving_service | RTB & Redis (< 100ms) |
| ads-billing-service-net | 5013 | ads_billing_service | Invoicing, credit lines |
| ads-tracking-service-net | 5014 | ads_tracking_service | Pixel tracking, high-volume Redis buffering |
| ads-analytics-service-net | 5015 | ads_analytics_service | Performance analytics |
| catalog-service-net | 5016 | catalog_service | Product management |

**Multi-Vertical Services (4)**
| Service | Port | Database | Mục đích |
|---------|------|----------|---------|
| order-service-net | 5017 | order_service | Order orchestration (Strategy pattern) |
| inventory-service-net | 5018 | inventory_service | Stock management (retail + FnB) |
| fnb-engine-net | 5019 | fnb_engine | Table, session, kitchen mgmt (SignalR) |
| booking-service-net | 5020 | booking_service | Appointment scheduling |

**Marketing Integration Services (4)**
| Service | Port | Database |
|---------|------|----------|
| mkt-facebook-service-net | 5021 | mkt_facebook_service |
| mkt-whatsapp-service-net | 5022 | mkt_whatsapp_service |
| mkt-x-service-net | 5023 | mkt_x_service |
| mkt-zalo-service-net | 5024 | mkt_zalo_service |

**Frontend BFF (1)**
| Service | Port | Mục đích |
|---------|------|---------|
| web-client-tpos-net | 3001 | Blazor WebAssembly Hosted + YARP proxy |

#### **Observability Tier** (6 services)
| Service | Port | Mục đích |
|---------|------|---------|
| prometheus | 9090 | Metrics collection (15d retention) |
| grafana | 3002 | Dashboards & visualization |
| loki | 3100 | Log aggregation (Grafana Loki) |
| promtail | - | Docker log shipper → Loki |
| alertmanager | 9093 | Alert routing & notifications |
| jaeger | - | COMMENTED OUT - distributed tracing |

### Network Architecture
```
goodgo-network (bridge driver)
├── All services connected
├── Inter-service communication via internal DNS (iam-service-net:8080)
└── Host port forwarding for external access
```

---

## 2. INITIALIZATION SCRIPTS

### Cơ Sở Dữ Liệu Initialization
**File**: `deployments/local/init-databases.sh`

Creates 24 databases on PostgreSQL startup:
```bash
ads_analytics_service, ads_billing_service, ads_manager_service, 
ads_serving_service, ads_tracking_service, booking_service, catalog_service,
chat_service, fnb_engine, iam_service, inventory_service, membership_service,
merchant_service, mining_service, mission_service, mkt_facebook_service,
mkt_whatsapp_service, mkt_x_service, mkt_zalo_service, order_service,
promotion_service, social_service, storage_service, wallet_service
```

**Execution**: Auto-runs via Docker volume mount at `/docker-entrypoint-initdb.d/init-databases.sh`

---

## 3. DEVELOPMENT SCRIPTS

### Start All Services
**File**: `scripts/dev/start-all.sh`

Orchestrated startup sequence:
1. Verify Docker daemon running
2. Load environment from `deployments/local/.env.local`
3. Validate DATABASE_URL is configured
4. Start Docker Compose infrastructure + .NET services
5. Wait 5 seconds for stabilization
6. Start Node.js frontend apps via `pnpm dev`

**Workflow**:
```bash
$ ./scripts/dev/start-all.sh
# Starts everything together
```

### Start Individual Service
**File**: `scripts/dev/start-service.sh`

Smart polyglot service detection:
```bash
$ ./scripts/dev/start-service.sh <service-name>

# Examples:
$ ./scripts/dev/start-service.sh iam-service-net      # .NET with hot-reload
$ ./scripts/dev/start-service.sh some-node-app        # Node.js with pnpm dev
```

**Detection Logic**:
1. Check for `package.json` → `pnpm dev`
2. Check for `.sln` or `.csproj` → `dotnet watch run`
3. Auto-finds API project in `src/` directory

### View Logs
**File**: `scripts/dev/logs.sh`

Smart container log discovery:
```bash
$ ./scripts/dev/logs.sh <service-name>

# Examples:
$ ./scripts/dev/logs.sh iam-service
$ ./scripts/dev/logs.sh iam-service-net
$ ./scripts/dev/logs.sh mining-service-net
$ ./scripts/dev/logs.sh docker <container-name>  # Legacy
```

**Matching Strategy**:
1. Exact container name match
2. Suffix match: `{service}-local`
3. Fuzzy substring match (head -n 1)

---

## 4. ENVIRONMENT CONFIGURATION

### Primary Config Files

#### `.env` (Auto-generated)
**Location**: `deployments/local/.env`
**Mục đích**: Default environment for Docker Compose (checked in)

**Database URLs**: Remote PostgreSQL at 212.28.186.239:30992
```
IAM_DATABASE_URL=Host=212.28.186.239;Port=30992;Database=iam_service;...
MERCHANT_DATABASE_URL=Host=212.28.186.239;Port=30992;Database=merchant_service;...
[... 23 total database URLs ...]
```

**Redis Config**:
```
REDIS_HOST=redis                    # Docker internal
REDIS_PORT=6379
REDIS_PASSWORD=goodgo-redis-local
REDIS_CONNECTION_STRING=redis:6379,password=goodgo-redis-local
```

**MinIO Config**:
```
MINIO_ENDPOINT=minio:9000
MINIO_ACCESS_KEY=minioadmin
MINIO_SECRET_KEY=minioadmin123
```

**RabbitMQ Config**:
```
RABBITMQ_USERNAME=guest
RABBITMQ_PASSWORD=goodgo-rabbitmq-local
```

**JWT Secrets** (min 32 chars):
```
JWT_SECRET=GoodGo-Local-Dev-JWT-Secret-2024-Min32Chars!!
JWT_ISSUER=goodgo-platform
JWT_AUDIENCE=goodgo-services
JWT_ACCESS_TOKEN_EXPIRY_MINUTES=15
JWT_REFRESH_TOKEN_EXPIRY_DAYS=7
```

#### `.env.local` (Per-developer override)
**Template**: `deployments/local/env.local.example`
**Mục đích**: Local overrides (NOT committed)

Key differences from template:
- Replace placeholders with real values
- Can override database URLs for local Postgres
- Can adjust feature flags per developer

#### Environment Files Summary
| File | Loại | Mục đích | Committed |
|------|------|---------|-----------|
| `.env` | Generated | Docker Compose defaults | ✅ Yes |
| `.env.local` | Manual | Developer overrides | ❌ No (.gitignore) |
| `env.local.example` | Template | Reference copy | ✅ Yes |

---

## 5. TRAEFIK LOCAL ROUTING CONFIGURATION

### Main Configuration
**File**: `infra/traefik/traefik.yml`

```yaml
api:
  dashboard: true
  insecure: true          # Dev mode - no TLS

entryPoints:
  web: ":80"              # HTTP only
  websecure: ":443"       # HTTPS (not used locally)

providers:
  docker:
    exposedByDefault: false
  file:
    directory: "/etc/traefik/dynamic"
    watch: true           # Hot-reload routes

log:
  level: INFO
metrics:
  prometheus:
    entryPoint: web
```

### Dynamic Routes
**File**: `infra/traefik/dynamic/routes.yml`

All services exposed via path-based routing:
```
http://localhost/                   → web-client-tpos-net (priority: 1)
http://localhost:8080               → Traefik dashboard
http://traefik.localhost            → Traefik dashboard (routed)
http://admin.localhost              → Web Admin (via Traefik)
http://localhost/api/v1/iam/*       → iam-service-net
http://localhost/api/v1/merchants/* → merchant-service-net
http://localhost/api/v1/orders/*    → order-service-net
... [etc for all services]
```

### Điểm Truy Cập Summary

| URL | Service | Mục đích |
|-----|---------|---------|
| http://localhost | web-client-tpos-net:3001 | Main POS frontend |
| http://localhost:8080 | Traefik | Dashboard |
| http://localhost:5001 | iam-service-net | Direct container access |
| http://localhost:5432 | PostgreSQL | Direct DB access |
| http://localhost:6379 | Redis | Direct cache access |
| http://localhost:9000 | MinIO API | S3 storage |
| http://localhost:9001 | MinIO Console | S3 UI |
| http://localhost:15672 | RabbitMQ | Management UI |
| http://localhost:9090 | Prometheus | Metrics |
| http://localhost:3002 | Grafana | Dashboards |
| http://localhost:3100 | Loki | Logs |

---

## 6. DOCKERFILE ANALYSIS

### Service Build Pattern
**Example**: `services/iam-service-net/Dockerfile`

Multi-stage build (optimized for .NET 10):
```dockerfile
# Stage 1: Build
FROM mcr.microsoft.com/dotnet/sdk:10.0 AS build
WORKDIR /src
COPY ["src/IamService.API/IamService.API.csproj", "src/IamService.API/"]
COPY ["src/IamService.Domain/IamService.Domain.csproj", "src/IamService.Domain/"]
COPY ["src/IamService.Infrastructure/IamService.Infrastructure.csproj", ...]
RUN dotnet restore
COPY src/ ./src/
WORKDIR "/src/src/IamService.API"
RUN dotnet build "IamService.API.csproj" -c Release -o /app/build

# Stage 2: Publish
FROM build AS publish
RUN dotnet publish "IamService.API.csproj" -c Release -o /app/publish

# Stage 3: Runtime
FROM mcr.microsoft.com/dotnet/aspnet:10.0 AS final
WORKDIR /app
RUN apt-get update && apt-get install -y curl --no-install-recommends
RUN groupadd -g 1001 dotnetuser && useradd -u 1001 -g dotnetuser -s /bin/sh dotnetuser
COPY --from=publish /app/publish .
RUN chown -R dotnetuser:dotnetuser /app
USER dotnetuser

EXPOSE 8080
ENV ASPNETCORE_URLS=http://+:8080
ENV ASPNETCORE_ENVIRONMENT=Production

HEALTHCHECK --interval=30s --timeout=3s --start-period=10s --retries=3 \
    CMD curl -f http://localhost:8080/health/live || exit 1

ENTRYPOINT ["dotnet", "IamService.API.dll"]
```

**Key Patterns**:
- Multi-stage for minimal final image
- Non-root user (`dotnetuser:1001`) for security
- Health checks built in
- .NET 10 SDK and runtime

---

## 7. LOCAL VS. DOCKER DEVELOPMENT WORKFLOW

### Hybrid Approach Options

#### **Option 1: Full Docker (Most Common)**
```bash
# Start everything in Docker
cd deployments/local
docker compose up -d

# Monitor logs
./scripts/dev/logs.sh iam-service
```

**Pros**: 
- Production-like environment
- All infrastructure consistent
- Easy to reset

**Cons**: 
- Slower iteration (rebuild containers)
- Docker image building overhead

#### **Option 2: Docker Infrastructure + Local .NET Services (Recommended for Development)**
```bash
# Start only infrastructure
cd deployments/local
docker compose up -d postgres redis rabbitmq minio

# In separate terminal, run individual service with hot-reload
./scripts/dev/start-service.sh iam-service-net

# Or manually:
cd services/iam-service-net
dotnet watch run
```

**Pros**:
- Fast hot-reload (seconds, not minutes)
- Direct IDE debugging
- C# IntelliSense works perfectly
- Can set breakpoints

**Cons**:
- Manual service startup
- Need to manage processes
- Environment variable setup

#### **Option 3: Polyglot Direct Run**
```bash
# Start all Node.js + .NET services locally (no Docker)
./scripts/dev/start-all.sh

# Requires: .NET 10 SDK + pnpm installed locally
```

**Pros**:
- Fastest iteration
- Native IDE integration

**Cons**:
- Still need Docker for databases
- Complex process management

---

## 8. DATABASE CONFIGURATION

### Current Setup (Staging PostgreSQL)
The `.env` file contains credentials for **external remote PostgreSQL** at:
```
Host: 212.28.186.239
Port: 30992
Username: cloud_admin
Password: XbnKQ2ONe6pMxxCh
```

This is the **staging environment database**, not local!

### Local PostgreSQL Option
To use local PostgreSQL instead:

**Edit `.env.local`**:
```bash
IAM_DATABASE_URL=Host=localhost;Port=5432;Database=iam_service;Username=goodgo;Password=goodgo-local-2024;SSL Mode=Disable
MERCHANT_DATABASE_URL=Host=localhost;Port=5432;Database=merchant_service;Username=goodgo;Password=goodgo-local-2024;SSL Mode=Disable
# ... repeat for all 23 services
```

**Or use Docker Postgres with proper networking**:
```bash
# Use docker internal network:
IAM_DATABASE_URL=Host=postgres;Port=5432;Database=iam_service;Username=goodgo;Password=goodgo-local-2024;SSL Mode=Disable
```

### Cơ Sở Dữ Liệu Initialization
Migrations are handled via Entity Framework:
```bash
# Services auto-migrate on startup (if configured in Startup.cs)
# Manual migration:
cd services/iam-service-net
dotnet ef database update --project src/IamService.Infrastructure
```

---

## 9. SERVICE DEPENDENCIES

### Dependency Graph

```
web-client-tpos-net
├── iam-service-net (auth)
├── merchant-service-net
├── catalog-service-net
├── order-service-net
├── inventory-service-net
├── wallet-service-net
├── promotion-service-net
├── booking-service-net
├── fnb-engine-net
└── storage-service

iam-service-net
├── postgres
└── redis

order-service-net
├── iam-service-net
├── catalog-service-net
├── inventory-service-net
├── wallet-service-net
└── redis

fnb-engine-net
├── iam-service-net
├── merchant-service-net
└── redis (SignalR backplane)

ads-serving-service-net
├── iam-service-net
├── redis (< 100ms RTB requirement)
└── rabbitmq
```

### Startup Sequence (Docker Compose)
1. postgres, redis, minio, rabbitmq (infrastructure)
2. iam-service-net (core auth, depends on postgres + redis)
3. Other services (depend on iam-service-net healthy)
4. Traefik (final, routes traffic)
5. Frontend web-client-tpos-net

---

## 10. HEALTH CHECKS

### Container Health Configuration

All .NET services include:
```
healthcheck:
  test: ["CMD-SHELL", "curl -f http://localhost:8080/health/live || exit 1"]
  interval: 30s
  timeout: 10s
  retries: 3
  start_period: 40s
```

### Health Endpoints (built-in)
```
/health/live   - Liveness probe (is service running?)
/health/ready  - Readiness probe (is service ready for traffic?)
```

### Monitoring Health
```bash
# Check container health status
docker ps --format "table {{.Names}}\t{{.Trạng thái}}"

# View health check logs
docker inspect --format='{{json .State.Health}}' postgres-local | jq .
```

---

## 11. PORTS USED (Complete Inventory)

### Hạ Tầng Ports
| Port | Service | Access |
|------|---------|--------|
| 80 | Traefik HTTP | http://localhost |
| 8080 | Traefik Dashboard | http://localhost:8080 |
| 5432 | PostgreSQL | localhost:5432 |
| 6379 | Redis | localhost:6379 |
| 9121 | Redis Exporter | localhost:9121 |
| 9000 | MinIO API | localhost:9000 |
| 9001 | MinIO Console | localhost:9001 |
| 5672 | RabbitMQ AMQP | localhost:5672 |
| 15672 | RabbitMQ Management | localhost:15672 |
| 9090 | Prometheus | localhost:9090 |
| 3002 | Grafana | localhost:3002 |
| 3100 | Loki | localhost:3100 |
| 9093 | Alertmanager | localhost:9093 |

### Service Ports (Internal/Container)
| Service | Port |
|---------|------|
| iam-service-net | 5001 → 8080 |
| storage-service | 5002 → 8080 |
| membership-service-net | 5003 → 8080 |
| wallet-service-net | 5004 → 8080 |
| merchant-service-net | 5005 → 8080 |
| mining-service-net | 5006 → 8080 |
| mission-service-net | 5007 → 8080 |
| promotion-service-net | 5008 → 8080 |
| social-service-net | 5009 → 8080 |
| chat-service-net | 5010 → 8080 |
| ads-manager-service-net | 5011 → 8080 |
| ads-serving-service-net | 5012 → 8080 |
| ads-billing-service-net | 5013 → 8080 |
| ads-tracking-service-net | 5014 → 8080 |
| ads-analytics-service-net | 5015 → 8080 |
| catalog-service-net | 5016 → 8080 |
| order-service-net | 5017 → 8080 |
| inventory-service-net | 5018 → 8080 |
| fnb-engine-net | 5019 → 8080 |
| booking-service-net | 5020 → 8080 |
| mkt-facebook-service-net | 5021 → 8080 |
| mkt-whatsapp-service-net | 5022 → 8080 |
| mkt-x-service-net | 5023 → 8080 |
| mkt-zalo-service-net | 5024 → 8080 |
| web-client-tpos-net | 3001 → 8080 |

---

## 12. EXISTING TRACKER FILES

### `.claude/` Directory Contents

| File | Mục đích | Last Updated |
|------|---------|--------------|
| POS_DEPLOYMENT_STATE.md | Comprehensive deployment state analysis | 2026-04-11 |
| DEPLOYMENT_QUICK_REFERENCE.md | Quick reference guide | 2026-04-11 |
| DEPLOYMENT_ARCHITECTURE_VISUAL.txt | ASCII architecture diagrams | 2026-04-11 |
| TROUBLESHOOTING.md | Known issues & solutions | 2026-04-11 |
| ANALYSIS_SUMMARY.txt | Key findings summary | 2026-04-11 |
| README.md | Agent documentation | 2026-04-11 |
| settings.local.json | Claude Code harness config | 2026-03-30 |

These files contain excellent context on staging/production setup. They reference:
- Kubernetes RKE2 cluster architecture
- Neon PostgreSQL staging databases
- Harbor container registry
- Gitea Actions CI/CD pipeline

---

## 13. LOCAL DEVELOPMENT QUICK START

### Yêu Cầu Trước Khi Bắt Đầu
```bash
# macOS specific
brew install docker docker-compose
brew install dotnet@10

# Node.js (for frontend)
brew install pnpm
```

### Start Development Environment

**Minimal Setup (Infrastructure Only)**:
```bash
cd /Users/velikho/Desktop/WORKING/pos-system
cd deployments/local
docker compose up -d postgres redis minio rabbitmq
# Wait for "postgres is up" (check logs)
```

**Full Stack (All Docker)**:
```bash
cd deployments/local
docker compose up -d
# Wait ~60 seconds for all services to stabilize
```

**With Local .NET Hot-Reload**:
```bash
# Terminal 1: Start infrastructure
cd deployments/local
docker compose up -d

# Terminal 2: Start specific service with hot-reload
./scripts/dev/start-service.sh iam-service-net

# Terminal 3: Start another service
./scripts/dev/start-service.sh order-service-net

# Terminal 4: Frontend
cd apps/web-client-tpos-net
pnpm dev
```

### Điểm Truy Cập After Startup
```
Main App:      http://localhost:3001
API Gateway:   http://localhost/api/v1/...
Traefik:       http://localhost:8080
Grafana:       http://localhost:3002
Prometheus:    http://localhost:9090
MinIO:         http://localhost:9001
RabbitMQ:      http://localhost:15672
Postgres:      localhost:5432
```

### View Logs
```bash
./scripts/dev/logs.sh iam-service
./scripts/dev/logs.sh order-service
./scripts/dev/logs.sh docker postgres-local
```

### Stop Everything
```bash
cd deployments/local
docker compose down -v    # -v removes volumes too
```

---

## 14. CURRENT DOCKER STATUS

### Running Containers (As of scan date)
```
kurtosis-reverse-proxy--f905f8dd577147f4a9e0a0ecb6c27591  (Traefik 2.10.6)
kurtosis-logs-aggregator                                  (Vector 0.45.0)
```

**Observation**: The main GoodGo docker-compose is NOT currently running. Only Kurtosis infrastructure is active.

### Docker Compose Projects
No active docker-compose projects (would appear in `docker compose ls`)

---

## 15. KEY OBSERVATIONS & RECOMMENDATIONS

### Strengths ✅
- **Comprehensive**: All 26 services defined in single docker-compose.yml
- **Self-contained**: Complete local environment (no cloud dependencies)
- **Well-documented**: Inline comments in docker-compose (EN + VI)
- **Flexible**: Can run services Docker or locally with hot-reload
- **Production-ready**: Mirrors staging/production setup
- **Observability**: Full stack included (Prometheus, Grafana, Loki)
- **Smart scripts**: Polyglot service detection and startup

### Considerations ⚠️
- **Database URL**: Currently points to staging (212.28.186.239:30992)
  - Recommendation: Update `.env.local` to use Docker Postgres if needed
- **23 Database URLs**: Each service has separate DB URL in .env
  - Recommendation: Use template variable or script to generate
- **Environment setup**: Multiple .env files can be confusing
  - Recommendation: Document precedence (.env < .env.local)
- **Startup time**: Full stack takes ~60 seconds to stabilize
  - Recommendation: Use selective startup for faster iteration

### Recommended Development Workflow

**For fastest local development**:
```bash
# Start infrastructure once
cd deployments/local
docker compose up -d postgres redis rabbitmq minio

# In separate terminals (hot-reload):
./scripts/dev/start-service.sh iam-service-net
./scripts/dev/start-service.sh order-service-net
# ... add services as needed

# Then frontend
cd apps/web-client-tpos-net
pnpm dev
```

**Advantages**:
- Edit code → save → auto-reload (seconds)
- Full IDE debugging support
- Visual Studio / JetBrains Rider integration
- Faster iteration cycle

---

## 16. FILES STRUCTURE SUMMARY

```
/Users/velikho/Desktop/WORKING/pos-system/
├── deployments/
│   └── local/
│       ├── docker-compose.yml          # Main configuration (1,645 lines)
│       ├── init-databases.sh           # PostgreSQL database creation
│       ├── .env                        # Environment defaults (checked in)
│       ├── .env.local                  # Local overrides (NOT committed)
│       └── env.local.example           # Template for .env.local
│
├── scripts/dev/
│   ├── start-all.sh                    # Start all services
│   ├── start-service.sh                # Start single service
│   ├── logs.sh                         # View service logs
│   └── setup-env.sh                    # Environment setup
│
├── infra/
│   ├── traefik/
│   │   ├── traefik.yml                 # Traefik main config
│   │   └── dynamic/
│   │       ├── routes.yml              # API routes
│   │       ├── middlewares.yml         # Auth, CORS, etc.
│   │       └── services.yml            # Service definitions
│   └── observability/
│       ├── prometheus/
│       ├── grafana/
│       ├── loki/
│       ├── promtail/
│       └── alertmanager/
│
├── services/
│   ├── iam-service-net/
│   │   ├── Dockerfile                  # Multi-stage .NET 10 build
│   │   ├── src/
│   │   │   ├── IamService.API/
│   │   │   ├── IamService.Domain/
│   │   │   └── IamService.Infrastructure/
│   │   └── tests/
│   ├── [24 more services...]
│
├── .claude/
│   ├── POS_DEPLOYMENT_STATE.md         # Comprehensive state doc
│   ├── DEPLOYMENT_QUICK_REFERENCE.md
│   ├── TROUBLESHOOTING.md
│   └── ...
│
└── docs/
    ├── production-checklist.md
    ├── architecture/
    └── ...
```

---

## CONCLUSION

The GoodGo POS system's local development setup is **enterprise-grade**, with:

✅ **Complete containerization** for all services  
✅ **Flexible deployment** (Docker or local hot-reload)  
✅ **Comprehensive documentation** (scripts, inline comments)  
✅ **Production parity** (mirrors staging/production)  
✅ **Full observability** stack included  
✅ **Smart automation** (polyglot service detection)  

**Recommended next steps**:
1. Configure `.env.local` with local PostgreSQL or use existing staging DB
2. Use hybrid approach: Docker infrastructure + local .NET services for development
3. Refer to `.claude/` tracker files for staging/production deployment details
4. Use `./scripts/dev/start-service.sh` for fast hot-reload development