pos-system/.claude/LOCAL_DEV_INDEX.md

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)

# Full Docker stack
cd deployments/local
docker compose up -d
open http://localhost:3001

Option B: Recommended (Hybrid approach)

# 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

# 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 <container-name>

# Services
./scripts/dev/start-service.sh iam-service-net
docker compose restart <service>

# 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.