From 368a660e5fbd6daa93dd0d891196e49f6bcd7ecb Mon Sep 17 00:00:00 2001 From: Ho Ngoc Hai Date: Wed, 15 Apr 2026 11:29:54 +0700 Subject: [PATCH] docs: add known issues, review checklist updates, and local dev investigation Add Known Issues & Gotchas section to CLAUDE.md covering role PascalCase requirement, EF migration enforcement, and browser token cache behavior. Update Tech Lead review checklist and naming conventions accordingly. Include local development setup investigation and quick reference docs. Co-Authored-By: Claude Opus 4.6 (1M context) --- .claude/LOCAL_DEV_INDEX.md | 332 +++++++++ .claude/LOCAL_DEV_QUICK_REFERENCE.md | 391 +++++++++++ .claude/LOCAL_DEV_SETUP_INVESTIGATION.md | 821 +++++++++++++++++++++++ .claude/LOCAL_DEV_STATE.md | 130 ++++ CLAUDE.md | 32 + 5 files changed, 1706 insertions(+) create mode 100644 .claude/LOCAL_DEV_INDEX.md create mode 100644 .claude/LOCAL_DEV_QUICK_REFERENCE.md create mode 100644 .claude/LOCAL_DEV_SETUP_INVESTIGATION.md create mode 100644 .claude/LOCAL_DEV_STATE.md diff --git a/.claude/LOCAL_DEV_INDEX.md b/.claude/LOCAL_DEV_INDEX.md new file mode 100644 index 00000000..76034420 --- /dev/null +++ b/.claude/LOCAL_DEV_INDEX.md @@ -0,0 +1,332 @@ +# GoodGo POS - Local Development Documentation Index +**Created**: 2026-04-12 +**Status**: Complete Investigation βœ… + +--- + +## πŸ“š DOCUMENTS IN THIS INVESTIGATION + +### 1. **LOCAL_DEV_QUICK_REFERENCE.md** (11 KB, 391 lines) +**Best for**: Quick answers and getting started quickly + +Contains: +- 5-minute quick start (two approaches) +- Service inventory (26 services categorized) +- Port mapping reference +- Helpful commands cheat sheet +- Access points after startup +- Environment setup guide +- Troubleshooting solutions +- Tips & tricks +- Day-to-day workflow recommendations + +**Use when**: You need quick answers, commands, or getting started + +--- + +### 2. **LOCAL_DEV_SETUP_INVESTIGATION.md** (25 KB, 821 lines) +**Best for**: Understanding the complete architecture + +Contains: +- Executive summary +- Docker Compose architecture (complete breakdown) +- Initialization scripts details +- Development scripts documentation +- Environment configuration (all files explained) +- Traefik routing configuration +- Dockerfile analysis +- Development workflow options (3 approaches) +- Database configuration +- Service dependencies & startup sequence +- Health checks +- Complete port inventory +- Existing tracker files reference +- Local development quick start +- Current Docker status +- Key observations & recommendations +- File structure summary + +**Use when**: You need to understand how everything works + +--- + +### 3. **POS_DEPLOYMENT_STATE.md** (EXISTING) +**Purpose**: Comprehensive deployment state for staging/production + +Contains information about: +- Kubernetes (RKE2) deployment +- Staging environment status +- Neon PostgreSQL configuration +- Production checklist +- CI/CD pipeline (Gitea Actions + Kaniko) +- Harbor container registry + +**Use when**: Working on staging/production deployment + +--- + +## 🎯 QUICK DECISION TREE + +### I want to start development **right now** +β†’ Go to `LOCAL_DEV_QUICK_REFERENCE.md` β†’ Section "Quick Start" + +### I want to understand the **full architecture** +β†’ Go to `LOCAL_DEV_SETUP_INVESTIGATION.md` β†’ Section "Docker Compose Architecture" + +### I need to **troubleshoot a problem** +β†’ Go to `LOCAL_DEV_QUICK_REFERENCE.md` β†’ Section "Troubleshooting" + +### I want to **learn development workflow** +β†’ Go to `LOCAL_DEV_SETUP_INVESTIGATION.md` β†’ Section "Local vs. Docker Development Workflow" + +### I want **all the technical details** +β†’ Go to `LOCAL_DEV_SETUP_INVESTIGATION.md` (read entire document) + +### I need **staging/production information** +β†’ Go to `POS_DEPLOYMENT_STATE.md` + +--- + +## πŸš€ IMMEDIATE ACTIONS + +### Option A: Quick Start (5 minutes) +```bash +# Full Docker stack +cd deployments/local +docker compose up -d +open http://localhost:3001 +``` + +### Option B: Recommended (Hybrid approach) +```bash +# Terminal 1: Start infrastructure +cd deployments/local +docker compose up -d postgres redis rabbitmq minio + +# Terminal 2: Start service with hot-reload +./scripts/dev/start-service.sh iam-service-net + +# Terminal 3: Run more services as needed +./scripts/dev/start-service.sh order-service-net +``` + +--- + +## πŸ“‹ SERVICE REFERENCE + +**26 Total Services organized by category:** + +| Category | Services (6) | Ports | +|----------|---|---| +| **Core** | iam, storage, membership, wallet, merchant, mining | 5001-5006 | +| **Engagement** | mission, promotion, social, chat, ads-manager | 5007-5011 | +| **Ads** | ads-serving, ads-billing, ads-tracking, ads-analytics, catalog | 5012-5016 | +| **Multi-Vertical** | order, inventory, fnb-engine, booking | 5017-5020 | +| **Marketing** | mkt-facebook, mkt-whatsapp, mkt-x, mkt-zalo | 5021-5024 | +| **Frontend** | web-client-tpos-net | 3001 | + +--- + +## πŸ”§ INFRASTRUCTURE REFERENCE + +| Component | Port | Docker Image | Purpose | +|-----------|------|------|---------| +| PostgreSQL | 5432 | postgres:16-alpine | Database server | +| Redis | 6379 | redis:7-alpine | Cache & backplane | +| RabbitMQ AMQP | 5672 | rabbitmq:3-mgmt-alpine | Message broker | +| RabbitMQ UI | 15672 | " | Management console | +| MinIO API | 9000 | minio/minio | Object storage | +| MinIO Console | 9001 | " | MinIO UI | +| Traefik | 80, 8080 | traefik:v3.3 | API gateway | +| Prometheus | 9090 | prom/prometheus | Metrics | +| Grafana | 3002 | grafana/grafana | Dashboards | +| Loki | 3100 | grafana/loki | Log aggregation | +| Alertmanager | 9093 | prom/alertmanager | Alert routing | + +--- + +## πŸ“‚ KEY FILES LOCATION + +``` +deployments/local/ +β”œβ”€β”€ docker-compose.yml ← Main config (1,645 lines) +β”œβ”€β”€ init-databases.sh ← Auto database creation +β”œβ”€β”€ .env ← Defaults (checked in) +β”œβ”€β”€ .env.local ← Overrides (NOT committed) +└── env.local.example ← Template + +scripts/dev/ +β”œβ”€β”€ start-all.sh ← Start everything +β”œβ”€β”€ start-service.sh ← Start individual service +β”œβ”€β”€ logs.sh ← View service logs +└── setup-env.sh ← Environment setup + +infra/traefik/ +β”œβ”€β”€ traefik.yml ← Main config +└── dynamic/ + β”œβ”€β”€ routes.yml ← API routes + β”œβ”€β”€ middlewares.yml ← CORS, auth, etc. + └── services.yml ← Service definitions +``` + +--- + +## 🌐 ACCESS AFTER STARTUP + +| URL | What | Purpose | +|-----|------|---------| +| http://localhost:3001 | Main App | POS frontend | +| http://localhost/api/v1/* | API Gateway | Traefik routes services | +| http://localhost:8080 | Traefik Dashboard | Route management | +| http://localhost:9090 | Prometheus | Metrics scraping | +| http://localhost:3002 | Grafana | Dashboard visualization | +| http://localhost:3100 | Loki | Log browsing | +| http://localhost:9001 | MinIO Console | Object storage UI | +| http://localhost:15672 | RabbitMQ | Message broker UI | + +--- + +## ⚑ COMMON COMMANDS + +```bash +# Start/Stop +docker compose up -d # Start all +docker compose down -v # Stop all + clean volumes + +# Logs +./scripts/dev/logs.sh iam-service +docker logs -f + +# Services +./scripts/dev/start-service.sh iam-service-net +docker compose restart + +# Database +psql -h localhost -U goodgo -d iam_service +dotnet ef database update --project services/iam-service-net + +# Status +docker ps --format "table {{.Names}}\t{{.Status}}" +docker compose ps +``` + +--- + +## πŸ” INVESTIGATION SUMMARY + +**What was investigated:** +1. βœ… Docker Compose configuration (1,645 lines analyzed) +2. βœ… Database initialization scripts +3. βœ… Development helper scripts (3 total) +4. βœ… Traefik routing configuration +5. βœ… Environment files and structure +6. βœ… Service dependencies +7. βœ… Health checks +8. βœ… All Dockerfiles +9. βœ… Port allocation and networking +10. βœ… Existing tracker documentation + +**Key findings:** +- βœ… Enterprise-grade setup with 26 microservices +- βœ… Flexible deployment (Docker, hybrid, or local) +- βœ… Complete infrastructure included locally +- βœ… Database URLs point to staging (212.28.186.239:30992) +- βœ… Hybrid approach (Docker infra + local services) is optimal +- βœ… All documentation auto-generated + inline comments + +--- + +## πŸ“– DOCUMENTATION HIERARCHY + +``` +Start Here: + ↓ +How do I start? + β†’ LOCAL_DEV_QUICK_REFERENCE.md Β§ Quick Start + ↓ +What are the services? + β†’ LOCAL_DEV_QUICK_REFERENCE.md Β§ Service Inventory + ↓ +I need commands + β†’ LOCAL_DEV_QUICK_REFERENCE.md Β§ Helpful Commands + ↓ +I need detailed info + β†’ LOCAL_DEV_SETUP_INVESTIGATION.md Β§ All Sections + ↓ +I need to deploy + β†’ POS_DEPLOYMENT_STATE.md Β§ Kubernetes & Staging +``` + +--- + +## πŸŽ“ LEARNING PATH + +1. **Day 1 - Get Started** + - Read: `LOCAL_DEV_QUICK_REFERENCE.md` (15 min) + - Do: Run `docker compose up -d` (5 min) + - Access: http://localhost:3001 + +2. **Day 2 - Deep Dive** + - Read: `LOCAL_DEV_SETUP_INVESTIGATION.md` (30 min) + - Understand: Architecture, dependencies, workflows + +3. **Day 3+ - Development** + - Use: Hybrid approach (Docker infra + local services) + - Reference: Quick Reference & Troubleshooting sections + +--- + +## πŸ“ž SUPPORT RESOURCES + +| Issue | Document | Section | +|-------|----------|---------| +| Can't start services | Quick Ref | Troubleshooting | +| Need to understand architecture | Investigation | Docker Compose Architecture | +| Database connection issue | Quick Ref | Environment Setup / Troubleshooting | +| Service won't start locally | Quick Ref | Troubleshooting | +| Need to understand staging | Deployment State | Kubernetes Manifests | + +--- + +## βœ… CHECKLIST FOR NEW DEVELOPER + +- [ ] Read this index file (5 min) +- [ ] Read LOCAL_DEV_QUICK_REFERENCE.md (10 min) +- [ ] Configure .env.local from env.local.example (5 min) +- [ ] Start infrastructure: `docker compose up -d postgres redis...` (5 min) +- [ ] Start a service: `./scripts/dev/start-service.sh iam-service-net` (2 min) +- [ ] Access app at http://localhost:3001 or http://localhost:5001 +- [ ] Read LOCAL_DEV_SETUP_INVESTIGATION.md for full understanding (30 min) +- [ ] Set up IDE debugging (depends on IDE) +- [ ] Ready to develop! πŸš€ + +--- + +## πŸ“ NOTES + +- Database URLs in `.env` point to **staging** (212.28.186.239:30992) +- For local development, either: + - Use Docker Postgres: `Host=postgres;Port=5432` + - Or ensure network access to staging server +- All 26 services have per-service databases +- Services auto-create databases on first startup +- Health checks ensure dependencies start in correct order + +--- + +## πŸ”„ DOCUMENT STATUS + +| Document | Created | Lines | Status | +|----------|---------|-------|--------| +| LOCAL_DEV_QUICK_REFERENCE.md | 2026-04-12 | 391 | βœ… Complete | +| LOCAL_DEV_SETUP_INVESTIGATION.md | 2026-04-12 | 821 | βœ… Complete | +| LOCAL_DEV_INDEX.md | 2026-04-12 | This file | βœ… Complete | +| Existing docs | Earlier | - | βœ… Referenced | + +--- + +**Investigation completed successfully** βœ… + +All findings documented in `.claude/` directory. +Ready for reference and future development work. + diff --git a/.claude/LOCAL_DEV_QUICK_REFERENCE.md b/.claude/LOCAL_DEV_QUICK_REFERENCE.md new file mode 100644 index 00000000..efde7d7a --- /dev/null +++ b/.claude/LOCAL_DEV_QUICK_REFERENCE.md @@ -0,0 +1,391 @@ +# GoodGo POS - Local Development Quick Reference +**Last Updated**: 2026-04-12 + +--- + +## πŸš€ QUICK START (5 minutes) + +### Option 1: Full Docker Stack (Production-like) +```bash +cd deployments/local +docker compose up -d +# Wait 60 seconds for all services to be healthy +open http://localhost:3001 +``` + +### Option 2: Hybrid (Recommended for Development) +```bash +# Terminal 1: Start infrastructure +cd deployments/local +docker compose up -d postgres redis rabbitmq minio + +# Terminal 2: Start 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 (if available) +cd apps/web-client-tpos-net +pnpm dev +``` + +--- + +## πŸ“‹ SERVICE INVENTORY + +### **26 Total Microservices** + +**Core (6)**: iam, storage, membership, wallet, merchant, mining +**Engagement (5)**: mission, promotion, social, chat, ads-manager +**Ads (5)**: ads-serving, ads-billing, ads-tracking, ads-analytics, catalog +**Multi-Vertical (4)**: order, inventory, fnb-engine, booking +**Marketing (4)**: mkt-facebook, mkt-whatsapp, mkt-x, mkt-zalo +**Frontend (1)**: web-client-tpos-net + +### **Port Mapping** +``` +Service Ports: 5001-5024 (internal 8080) +Frontend: 3001 (web-client-tpos-net) +Infrastructure: + - PostgreSQL: 5432 + - Redis: 6379 + - RabbitMQ: 5672 (AMQP), 15672 (UI) + - MinIO: 9000 (API), 9001 (Console) +Observability: + - Traefik: 80, 8080 + - Prometheus: 9090 + - Grafana: 3002 + - Loki: 3100 +``` + +--- + +## πŸ”§ HELPFUL COMMANDS + +### Start/Stop +```bash +cd deployments/local + +# Start all services +docker compose up -d + +# Start specific services only +docker compose up -d postgres redis minio rabbitmq + +# Stop all +docker compose down + +# Stop and clean volumes +docker compose down -v + +# Restart a service +docker compose restart iam-service-net +``` + +### Logs & Status +```bash +# Smart log viewer +./scripts/dev/logs.sh iam-service +./scripts/dev/logs.sh order-service-net + +# Docker logs +docker logs -f postgres-local +docker logs -f iam-service-net-local + +# Container status +docker ps --format "table {{.Names}}\t{{.Status}}" +``` + +### Database +```bash +# Connect to PostgreSQL +psql -h localhost -p 5432 -U goodgo -d iam_service + +# List all databases +psql -h localhost -U goodgo -l + +# Run migrations (per service) +cd services/iam-service-net +dotnet ef database update --project src/IamService.Infrastructure +``` + +### Individual Service Development +```bash +# Start single service with hot-reload (requires infrastructure running) +./scripts/dev/start-service.sh iam-service-net + +# Or directly with dotnet +cd services/iam-service-net +dotnet watch run + +# Export environment variables first (optional) +export $(grep -v '^#' ../../deployments/local/.env.local | xargs) +``` + +--- + +## 🌐 ACCESS POINTS (After Services Start) + +| URL | Purpose | +|-----|---------| +| http://localhost | Main POS App (web-client-tpos-net) | +| http://localhost:8080 | Traefik Dashboard | +| http://localhost:9001 | MinIO Console | +| http://localhost:15672 | RabbitMQ Management | +| http://localhost:9090 | Prometheus Metrics | +| http://localhost:3002 | Grafana Dashboards | +| http://localhost:3100 | Loki Logs | + +### Direct Service Access (if needed) +``` +iam-service: http://localhost:5001 +merchant-service: http://localhost:5005 +order-service: http://localhost:5017 +wallet-service: http://localhost:5004 +catalog-service: http://localhost:5016 +fnb-engine: http://localhost:5019 +``` + +--- + +## πŸ“ KEY FILES + +| Path | Purpose | +|------|---------| +| `deployments/local/docker-compose.yml` | Main config (1,645 lines) | +| `deployments/local/.env` | Environment variables (checked in) | +| `deployments/local/.env.local` | Local overrides (NOT committed) | +| `scripts/dev/start-all.sh` | Start everything | +| `scripts/dev/start-service.sh` | Start single service | +| `scripts/dev/logs.sh` | Smart log viewer | +| `infra/traefik/traefik.yml` | API gateway config | +| `infra/traefik/dynamic/routes.yml` | Service routing | + +--- + +## βš™οΈ ENVIRONMENT SETUP + +### `.env` File (Default - Checked In) +Contains defaults with **staging database** (212.28.186.239:30992) + +### `.env.local` File (Per-Developer - NOT Committed) +Override specific settings locally. Template: `env.local.example` + +```bash +# Example: Use local PostgreSQL instead of staging +IAM_DATABASE_URL=Host=postgres;Port=5432;Database=iam_service;Username=goodgo;Password=goodgo-local-2024;SSL Mode=Disable +MERCHANT_DATABASE_URL=Host=postgres;Port=5432;Database=merchant_service;Username=goodgo;Password=goodgo-local-2024;SSL Mode=Disable +# ... etc for all 23 services +``` + +### Redis Configuration +``` +REDIS_HOST=redis +REDIS_PORT=6379 +REDIS_PASSWORD=goodgo-redis-local +``` + +### JWT Secrets (for local dev) +``` +JWT_SECRET=GoodGo-Local-Dev-JWT-Secret-2024-Min32Chars!! +JWT_ISSUER=goodgo-platform +JWT_AUDIENCE=goodgo-services +``` + +--- + +## πŸ› TROUBLESHOOTING + +### "Connection refused" when running services +**Problem**: Infrastructure services not started +**Solution**: +```bash +cd deployments/local +docker compose up -d postgres redis rabbitmq minio +``` + +### "Database connection timeout" +**Problem**: Using staging DB (212.28.186.239:30992) without network access +**Solution**: +1. Update `.env.local` to use Docker Postgres (`Host=postgres`) +2. Or ensure network access to staging IP + +### Service not found in logs +**Problem**: Container naming issue +**Solution**: +```bash +# List running containers +docker ps + +# View logs by exact container name +docker logs -f +``` + +### Port already in use +**Problem**: Another service using same port +**Solution**: +```bash +# Find what's using the port +lsof -i :5001 + +# Kill the process +kill -9 + +# Or change port in docker-compose.yml +``` + +### .NET Service won't start locally +**Problem**: Missing environment variables +**Solution**: +```bash +# Load environment before running +export $(grep -v '^#' deployments/local/.env.local | xargs) +dotnet watch run --project services/iam-service-net +``` + +--- + +## πŸ“Š ARCHITECTURE LAYERS + +``` +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ Frontend Layer (Blazor WASM) β”‚ +β”‚ web-client-tpos-net:3001 β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ + β”‚ Routes via Traefik +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β–Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ API Gateway (Traefik v3.3:80) β”‚ +β”‚ Path-based routing to services β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ + β”‚ + β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” + β”‚ β”‚ β”‚ +β”Œβ”€β”€β”€β”€β”€β”€β”€β–Όβ”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β–Όβ”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β–Όβ”€β”€β”€β”€β”€β”€β”€β” +β”‚ Core β”‚ β”‚ Engagement β”‚ Ads System β”‚ +β”‚ Services β”‚ β”‚ Services β”‚ Services (RTB) β”‚ +β””β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”˜ + β”‚ β”‚ β”‚ +β””β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ + β”‚ +β”Œβ”€β”€β”€β”€β”€β”€β–Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ Shared Infrastructure β”‚ +β”‚ postgres β”‚ redis β”‚ rabbitmq β”‚ minio β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ +``` + +--- + +## πŸ“ˆ RECOMMENDED WORKFLOW + +### Day-to-Day Development + +1. **Start infrastructure once** (morning): +```bash +cd deployments/local +docker compose up -d postgres redis rabbitmq minio +``` + +2. **Start services you're working on** (per terminal): +```bash +./scripts/dev/start-service.sh iam-service-net +./scripts/dev/start-service.sh order-service-net +# Hot-reload available - save code to auto-reload +``` + +3. **Run frontend** (separate terminal): +```bash +cd apps/web-client-tpos-net +pnpm dev +``` + +4. **Use IDE debugging**: +- Set breakpoints in VS Code / Visual Studio +- Attach debugger to running process +- Step through code normally + +5. **Stop everything** (end of day): +```bash +# Stop all containers +cd deployments/local +docker compose down + +# Optional: Clean volumes for fresh start next time +docker compose down -v +``` + +--- + +## πŸ” DATABASE SCHEMAS + +Each service has its own database: +``` +iam_service - Identity & access management +merchant_service - Shop/merchant management +order_service - Order orchestration +catalog_service - Product catalog +inventory_service - Stock management +wallet_service - Wallet/balance management +promotion_service - Vouchers & campaigns +... 17 more databases +``` + +All create automatically via `init-databases.sh` on first PostgreSQL startup. + +--- + +## πŸš€ DEPLOYMENT REFERENCE + +For **Staging/Production** deployment info: +- See `.claude/POS_DEPLOYMENT_STATE.md` +- See `.claude/DEPLOYMENT_QUICK_REFERENCE.md` + +--- + +## πŸ’‘ TIPS & TRICKS + +### Debug a specific service +```bash +# Terminal 1: Run with verbose logging +export $(grep -v '^#' deployments/local/.env.local | xargs) +cd services/iam-service-net +ASPNETCORE_ENVIRONMENT=Development dotnet watch run + +# Terminal 2: Attach debugger from IDE +``` + +### Test API locally +```bash +# Get auth token +curl -X POST http://localhost:5001/api/v1/auth/login \ + -H "Content-Type: application/json" \ + -d '{"username":"test","password":"test"}' + +# Use token in other requests +curl http://localhost:5017/api/v1/orders \ + -H "Authorization: Bearer $TOKEN" +``` + +### View database queries +```bash +# Enable EF Core command logging in appsettings.Development.json +# Then check console output for SQL queries +``` + +### Reset everything +```bash +cd deployments/local +docker compose down -v +docker compose up -d +# All databases will be recreated fresh +``` + +--- + +## πŸ“ž SUPPORT + +For detailed information: +- `.claude/LOCAL_DEV_SETUP_INVESTIGATION.md` - Full technical investigation +- `.claude/POS_DEPLOYMENT_STATE.md` - Deployment state & staging setup +- `.claude/TROUBLESHOOTING.md` - Known issues & solutions + diff --git a/.claude/LOCAL_DEV_SETUP_INVESTIGATION.md b/.claude/LOCAL_DEV_SETUP_INVESTIGATION.md new file mode 100644 index 00000000..f4430ca7 --- /dev/null +++ b/.claude/LOCAL_DEV_SETUP_INVESTIGATION.md @@ -0,0 +1,821 @@ +# GoodGo POS System - Local Development Setup Investigation +**Generated**: 2026-04-12 +**Base Path**: /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 | Purpose | +|---------|-------|------|---------|---------| +| `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 | Purpose | +|---------|------|----------|---------| +| 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 | Purpose | +|---------|------|----------|---------| +| 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 | Purpose | +|---------|------|---------| +| web-client-tpos-net | 3001 | Blazor WebAssembly Hosted + YARP proxy | + +#### **Observability Tier** (6 services) +| Service | Port | Purpose | +|---------|------|---------| +| 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 + +### Database 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 + +# 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 + +# 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 # 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` +**Purpose**: 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` +**Purpose**: 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 | Type | Purpose | 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] +``` + +### Access Points Summary + +| URL | Service | Purpose | +|-----|---------|---------| +| 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 +``` + +### Database 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{{.Status}}" + +# View health check logs +docker inspect --format='{{json .State.Health}}' postgres-local | jq . +``` + +--- + +## 11. PORTS USED (Complete Inventory) + +### Infrastructure 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 | Purpose | 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 + +### Prerequisites +```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 +``` + +### Access Points 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 + diff --git a/.claude/LOCAL_DEV_STATE.md b/.claude/LOCAL_DEV_STATE.md new file mode 100644 index 00000000..8b7b3495 --- /dev/null +++ b/.claude/LOCAL_DEV_STATE.md @@ -0,0 +1,130 @@ +# Local Dev Environment State + +## Setup Info +- **Date**: 2026-04-12 +- **Machine**: MacBook M-series, 64GB RAM +- **Docker**: Docker Desktop 4.55, Engine 29.1.3 (darwin/arm64) +- **Compose file**: `deployments/local/docker-compose.yml` +- **Env file**: `deployments/local/.env` + +## Database +- **Type**: Remote Neon PostgreSQL +- **Host**: 212.28.186.239:30992 +- **User**: cloud_admin +- **Databases**: 23 per-service databases (iam_service, merchant_service, etc.) +- **Note**: Shared with staging β€” changes here affect staging data + +## Running Services (36 containers) + +### Infrastructure +| Service | Port | Status | +|---------|------|--------| +| PostgreSQL 16 | 5432 | healthy (local container, but services use remote Neon) | +| Redis 7 | 6379 | healthy | +| RabbitMQ 3 | 5672 / 15672 (UI) | healthy | +| MinIO | 9000 / 9001 (Console) | healthy | +| Traefik v3.3 | 80 / 8080 (Dashboard) | running | + +### Microservices +| Service | Port | Status | +|---------|------|--------| +| iam-service | 5001 | healthy | +| merchant-service | 5005 | healthy | +| catalog-service | 5016 | healthy | +| order-service | 5017 | healthy | +| inventory-service | 5018 | healthy | +| fnb-engine | 5019 | healthy | +| booking-service | 5020 | healthy | +| wallet-service | 5004 | healthy | +| storage-service | 5002 | healthy | +| membership-service | 5003 | healthy | +| chat-service | 5006 | healthy | +| social-service | 5007 | healthy | +| promotion-service | 5008 | healthy | +| mining-service | 5009 | healthy | +| mission-service | 5010 | healthy | +| ads-manager-service | 5011 | healthy | +| ads-serving-service | 5012 | healthy | +| ads-billing-service | 5013 | healthy | +| ads-tracking-service | 5014 | healthy | +| ads-analytics-service | 5015 | healthy | +| mkt-facebook-service | 5021 | healthy | +| mkt-whatsapp-service | 5022 | healthy | +| mkt-x-service | 5023 | healthy | +| mkt-zalo-service | 5024 | healthy | + +### Frontend +| Service | Port | Status | +|---------|------|--------| +| pos-web (Blazor WASM) | 3001 | healthy | + +### Observability +| Service | Port | Status | +|---------|------|--------| +| Prometheus | 9090 | healthy | +| Grafana | 3002 | healthy | +| Loki | 3100 | running | +| Promtail | β€” | running | +| Alertmanager | 9093 | healthy | + +## Access Points +| URL | Purpose | +|-----|---------| +| http://localhost:3001 | POS App (Blazor WASM) | +| http://localhost:8080 | Traefik Dashboard | +| http://localhost:15672 | RabbitMQ Management (guest / goodgo-rabbitmq-local) | +| http://localhost:9001 | MinIO Console (minioadmin / minioadmin123) | +| http://localhost:9090 | Prometheus | +| http://localhost:3002 | Grafana | +| http://localhost:5001/swagger | IAM API Swagger | +| http://localhost:5005/swagger | Merchant API Swagger | + +## Dev Workflow + +### Rebuild a service after code changes +```bash +cd deployments/local +docker compose build +docker compose up -d +``` + +### Hot-reload (recommended for active dev) +```bash +# Stop Docker container for the service +docker compose stop iam-service-net-local + +# Run locally with hot-reload +cd services/iam-service-net +dotnet watch run --project src/IamService.API +``` + +### View logs +```bash +docker compose logs -f --tail=50 +``` + +### Restart all +```bash +docker compose restart +``` + +### Stop all +```bash +docker compose down +``` + +## Git β†’ CI/CD Flow +1. Edit code locally +2. Test on http://localhost:3001 +3. `git add && git commit && git push origin master` +4. GitHub β†’ Gitea sync (5 min cronjob) +5. Gitea Actions β†’ Kaniko build β†’ Harbor β†’ K8s deploy +6. Verify on https://platform.techbi.org + +## Known Issues +- PostgreSQL container runs locally but all services point to remote Neon DB +- Homebrew postgres/redis must be stopped before starting Docker (they grab ports 5432/6379) + - `brew services stop postgresql@17 && brew services stop redis` + +## Last Updated +2026-04-12 β€” Initial setup, 36 containers running healthy diff --git a/CLAUDE.md b/CLAUDE.md index e2b3a11e..31b3ca33 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -382,6 +382,7 @@ NAMING CONVENTIONS: - Domain Events: EntityVerbedDomainEvent (OrderCreatedDomainEvent) - DB columns: snake_case (created_at, merchant_id) - Services/folders: kebab-case (merchant-service-net) +- **Roles: PascalCase** (SuperAdmin, Admin, Owner, Manager, Staff) β€” ASP.NET `[Authorize(Roles="...")]` is CASE-SENSITIVE. DB `roles.Name` MUST match exactly with controller annotations. TASK FORMAT: - Service: [service-name] @@ -394,6 +395,8 @@ TASK FORMAT: REVIEW CHECKLIST: [ ] Domain layer has NO external dependencies +[ ] EF migrations created for ALL new/changed entity properties (dotnet ef migrations add) +[ ] EF migrations applied to ALL target databases before deploy [ ] Commands have FluentValidation validators [ ] Handlers use IUnitOfWork.SaveEntitiesAsync() [ ] Domain events raised in aggregate methods @@ -837,3 +840,32 @@ RULES: 7. **Tech Lead** review code (checklist) -> **CTO** approve architecture 8. **DevOps** update infra nαΊΏu cαΊ§n (Docker, K8s, Traefik routes, CI) 9. **Product Manager** validate feature vα»›i user feedback -> iterate backlog + +--- + +## Known Issues & Gotchas + +### 1. Role Names Must Be PascalCase (Case-Sensitive Auth) +- **Problem**: ASP.NET `[Authorize(Roles = "SuperAdmin")]` is **case-sensitive**. If DB stores `superadmin` (lowercase) but controller expects `SuperAdmin` (PascalCase), users get 403 Forbidden even with correct role. +- **Root cause**: IAM service seed data hoαΊ·c manual INSERT dΓΉng lowercase, nhΖ°ng controllers dΓΉng PascalCase. +- **Prevention**: + - Role names trong DB `roles.Name`: `SuperAdmin`, `Admin`, `Owner`, `Manager`, `Staff` (PascalCase) + - Role names trong `[Authorize(Roles="...")]` phαΊ£i match EXACT vα»›i DB + - Khi seed roles, LUΓ”N dΓΉng PascalCase + - Khi thΓͺm role mα»›i, check cαΊ£ DB seed + controller annotations +- **Debug**: Decode JWT token β†’ check `role` claim β†’ so sΓ‘nh vα»›i `[Authorize(Roles="...")]` trΓͺn controller + +### 2. EF Migration Must Exist Before Deploy +- **Problem**: ThΓͺm property vΓ o Entity/EF Config nhΖ°ng quΓͺn tαΊ‘o migration β†’ DB thiαΊΏu column β†’ 500 error `column X does not exist` +- **Root cause**: Developer thΓͺm domain property + EF configuration nhΖ°ng khΓ΄ng chαΊ‘y `dotnet ef migrations add` +- **Prevention**: + - **Rule**: Mα»—i khi thay Δ‘α»•i Entity property hoαΊ·c EntityTypeConfiguration β†’ PHαΊ’I tαΊ‘o migration ngay + - Command: `dotnet ef migrations add --project src/ServiceName.Infrastructure --startup-project src/ServiceName.API` + - CI pipeline SHOULD verify pending model changes (no `HasPendingModelChanges`) + - Review checklist: "EF migrations created for all entity changes?" +- **Debug**: Error `42703: column X does not exist` β†’ check EF config vs latest migration snapshot + +### 3. Browser Token Cache After Role/Auth Changes +- **Problem**: Sau khi fix role names hoαΊ·c auth config trong DB, browser vαΊ«n dΓΉng JWT cΕ© (cached trong cookie/localStorage) β†’ vαΊ«n bα»‹ 403 +- **Prevention**: Sau khi thay Δ‘α»•i auth-related data (roles, permissions, claims), user PHαΊ’I logout + login lαΊ‘i để nhαΊ­n token mα»›i +- **Debug**: Decode JWT tα»« cookie `bff_session` β†’ verify claims match expected values