GoodGo Microservices Platform

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:

// ✅ 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.

🚀 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:

./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:

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

   ./scripts/db/setup-neon.sh
   # Follow the interactive prompts to configure your Neon URL
   

2. Start Infrastructure:

   # Starts Redis, Traefik, and Observability stack
   cd deployments/local
   docker-compose up -d
   

3. Run Migrations:

   ./scripts/db/migrate.sh iam-service dev
   

4. Start Services:

   ./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:

# 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
• API Documentation
• Development Guide
• Deployment Guide
• Contributing Guide

🔐 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

# 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

# Build all packages and services
pnpm build

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

🚢 Deployment

See Deployment Guide for detailed instructions.

Quick Deploy

# 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 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 file for details.

👥 Maintainer

Built with ❤️ by VelikHo (@hongochai10)

• Email: hongochai10@icloud.com
• GitHub: https://github.com/hongochai10