pos-system/README.md

# GoodGo Microservices Platform

[![English](https://img.shields.io/badge/Language-English-blue.svg)](README.md) [![Tiếng Việt](https://img.shields.io/badge/Ngôn%20ngữ-Tiếng%20Việt-red.svg)](README.vi.md)

Enterprise-grade microservices monorepo built with modern technologies and best practices.

## 🏗️ Architecture

This monorepo follows a microservices architecture pattern with:

- **Apps**: Frontend applications (Web + Mobile)
- **Services**: Backend microservices (Node.js/TypeScript)
- **Packages**: Shared libraries and utilities
- **Infrastructure**: Traefik, Observability, Databases
- **Deployments**: Environment-specific configurations

## 📁 Project Structure

```
├── apps/                 # Frontend applications
│   ├── web-admin/       # Next.js admin web application
│   ├── web-client/      # Next.js client web application
│   ├── app-admin/       # Flutter admin mobile application
│   └── app-client/      # Flutter client mobile application
├── services/            # Backend microservices
│   ├── iam-service/     # Identity and Access Management service (Node.js)
│   └── _template/       # Service template for new services
├── packages/            # Shared libraries
│   ├── auth-sdk/        # Auth utilities and guards
│   ├── config/          # Shared configurations
│   ├── http-client/     # Standardized API client
│   ├── logger/          # Centralized logging (Winston)
│   ├── tracing/         # OpenTelemetry setup
│   └── types/           # Shared TypeScript types
├── infra/               # Infrastructure as Code
│   ├── databases/       # Database configs (PostgreSQL/Neon, Redis)
│   ├── docker/          # Docker compose files
│   ├── observability/   # Monitoring stack (Prometheus, Grafana, Loki)
│   ├── secrets/         # Secret management
│   └── traefik/         # API Gateway configuration
├── deployments/         # Environment configs
│   ├── local/           # Local development setup
│   ├── staging/         # Staging environment (Kubernetes)
│   └── production/      # Production environment (Kubernetes)
├── scripts/             # Automation scripts (Bilingual EN/VI)
│   ├── build/           # Build scripts
│   ├── db/              # Database management (backup, seed, migrate)
│   ├── deploy/          # Deployment scripts
│   ├── dev/             # Development helpers
│   ├── setup/           # Project initialization
│   └── utils/           # Utility scripts (cleanup, generators)
└── docs/                # Documentation
```

## ⚠️ Breaking Changes

### v1.0.0 - Module Format Migration (2026-01-07)

**BREAKING**: All shared packages now use ES modules instead of CommonJS.

**What Changed:**
- TypeScript compilation target changed from `commonjs` to `ES2020`
- All packages (`@goodgo/types`, `@goodgo/http-client`, `@goodgo/logger`, `@goodgo/auth-sdk`, `@goodgo/tracing`) now export ES modules
- `package.json` files already declared `"type": "module"`, now TypeScript output matches

**Migration Required:**
If you have existing code importing these packages:

```typescript
// ✅ This still works (no changes needed for most cases)
import { UserResponse } from '@goodgo/types';
import { createHttpClient } from '@goodgo/http-client';

// ⚠️ If you were using require() (CommonJS), you must update:
// ❌ OLD: const { UserResponse } = require('@goodgo/types');
// ✅ NEW: import { UserResponse } from '@goodgo/types';
```

**Action Required:**
1. Pull latest changes
2. Clean and rebuild: `pnpm -r --filter "./packages/*" run clean && pnpm build`
3. Update any CommonJS `require()` statements to ES `import`

**Files Changed:**
- `packages/config/tsconfig/node.json` - Changed `"module": "commonjs"` → `"module": "ES2020"`
- `packages/types/tsconfig.json` - Added `"moduleResolution": "node"`

For detailed information, see [Migration Walkthrough](docs/en/guides/module-format-migration.md).

## 🚀 Getting Started

### Prerequisites

- Node.js >= 20.0.0
- pnpm >= 8.0.0
- Docker & Docker Compose
- Neon account (https://neon.tech) - for PostgreSQL database

### Quick Start (One-Command Setup)

We provide a comprehensive initialization script to get you up and running quickly:

```bash
./scripts/setup/init-project.sh
```

This script will:
1.  Check prerequisites
2.  Install dependencies
3.  Generate Prisma clients
4.  Create necessary `.env` files from examples

### Manual Installation

If you prefer to set up manually:

```bash
# Install dependencies
pnpm install

# Generate Prisma clients
pnpm prisma:generate

# Start all services (development)
./scripts/dev/start-all.sh
```

### Local Development Flow

1.  **Database Setup**:
    ```bash
    ./scripts/db/setup-neon.sh
    # Follow the interactive prompts to configure your Neon URL
    ```

2.  **Start Infrastructure**:
    ```bash
    # Starts Redis, Traefik, and Observability stack
    cd deployments/local
    docker-compose up -d
    ```

3.  **Run Migrations**:
    ```bash
    ./scripts/db/migrate.sh iam-service dev
    ```

4.  **Start Services**:
    ```bash
    ./scripts/dev/start-all.sh
    # Or to start a specific service:
    # ./scripts/dev/start-service.sh iam-service
    ```

## 🛠️ Helper Scripts

The `scripts/` directory contains bilingual (English/Vietnamese) automation scripts to streamline daily tasks:

| Category | Script | Description |
|----------|--------|-------------|
| **Setup** | `init-project.sh` | Full project initialization |
| | `install-deps.sh` | Install dependencies |
| **Dev** | `start-all.sh` | Start infrastructure and all services |
| | `start-service.sh` | Start a specific service |
| | `logs.sh` | View logs for services or docker containers |
| | `setup-env.sh` | Helper to setup environment variables |
| **DB** | `migrate.sh` | Run Prisma migrations (dev/deploy) |
| | `seed.sh` | Seed database with initial data |
| | `backup.sh` | Backup database (supports Neon) |
| | `setup-neon.sh` | Wizard to configure Neon DB connection |
| **Utils** | `create-service.sh` | Scaffold a new microservice from template |
| | `cleanup.sh` | Clean build artifacts and caches |
| **Build** | `build-all.sh` | Build entire monorepo |
| | `build-service.sh` | Build specific service |
| **Deploy** | `deploy-staging.sh` | Deploy to staging cluster |
| | `deploy-prod.sh` | Deploy to production cluster |

## 🛠️ Tech Stack

**Frontend:**
- Web: Next.js 14+ (App Router)
- Mobile: Flutter 3.x
- Styling: Tailwind CSS
- State: Zustand / Provider

**Backend:**
- Runtime: Node.js + TypeScript
- Framework: Express/NestJS (via service template)
- ORM: Prisma
- Database: PostgreSQL (Neon Serverless), Redis (Caching/Queues)

**Infrastructure:**
- Gateway: Traefik
- Containerization: Docker
- Orchestration: Kubernetes
- Observability: Prometheus, Grafana, Loki, OpenTelemetry

**DevOps:**
- Build System: Turborepo
- Package Manager: PNPM Workspaces
- CI/CD: GitHub Actions

## 🌐 Coding Standards

### Bilingual Comments
To support our diverse team, we follow a bilingual commenting standard (English & Vietnamese) for:
- Scripts
- Complex logic
- Public APIs
- Configuration files

Example:
```bash
# EN: Verify Docker daemon is running
# VI: Xác minh Docker daemon đang chạy
```

### Monorepo Management
- We use **Turborepo** for build pipelines and caching.
- **PNPM Workspaces** manage dependencies across apps and services.

## 📚 Documentation

- [Architecture Overview](docs/en/architecture/system-design.md)
- [API Documentation](docs/en/api/openapi/)
- [Development Guide](docs/en/guides/development.md)
- [Deployment Guide](docs/en/guides/deployment.md)
- [Contributing Guide](CONTRIBUTING.md)

## 🔐 Environment Variables

**Important**: Never commit `.env` files. Use `.env.example` as templates.

- **Dev**: `deployments/local/.env.local` (Shared), `services/*/.env.local` (Service specific)
- **Staging/Prod**: Managed via Kubernetes Secrets

## 🧪 Testing

```bash
# Run all tests
pnpm test

# Run tests for specific package
pnpm --filter @goodgo/iam-service test

# Run with coverage
pnpm --filter @goodgo/iam-service test:coverage
```

## 📦 Building

```bash
# Build all packages and services
pnpm build

# Build specific service
pnpm --filter @goodgo/iam-service build
```

## 🚢 Deployment

See [Deployment Guide](docs/guides/deployment.md) for detailed instructions.

### Quick Deploy

```bash
# Local
cd deployments/local && docker-compose up -d

# Staging (Kubernetes)
cd deployments/staging && kubectl apply -f kubernetes/

# Production
cd deployments/production && kubectl apply -f kubernetes/
```

## 🤝 Contributing

Please read [CONTRIBUTING.md](CONTRIBUTING.md) for details on our code of conduct and the process for submitting pull requests.

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## 👥 Maintainer

Built with ❤️ by **VelikHo** ([@hongochai10](https://github.com/hongochai10))

- **Email**: hongochai10@icloud.com
- **GitHub**: https://github.com/hongochai10