├── 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

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

Check prerequisites
Install dependencies
Generate Prisma clients
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

Database Setup:

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

Start Infrastructure:

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

Run Migrations:

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

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

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

👥 Team

Built with ❤️ by the GoodGo team

Languages

C# 62.8%

HTML 22.7%

TypeScript 7.5%

CSS 3%

Swift 2%

Other 1.9%