pos-system/docs/en/guides/getting-started.md

Getting Started

Note

: This guide assumes you are setting up the project on macOS or Linux. Windows users should use WSL2.

Table of Contents

1. Prerequisites
2. Architecture Overview
3. Project Structure
4. Installation & Setup
5. Development Workflow
6. Common Commands
7. Troubleshooting

Prerequisites

Before starting, ensure you have the following installed:

• Node.js: v20.0.0 or higher (recommended v22+ or v25+)

  node -v
  # v25.2.1
  

• PNPM: v8.15.0 or higher (we use pnpm workspaces)

  pnpm -v
  # 8.15.0
  

• Docker & Docker Compose: v24.0.0 or higher for local infrastructure

  docker -v
  # Docker version 29.1.3, build f52814d
  

• Git: For version control
• Neon Account: Serverless PostgreSQL (https://neon.tech)

Architecture Overview

GoodGo Platform uses a microservices architecture with a shared infrastructure layer.

graph TD
    Client[Client Apps] --> Traefik[Traefik Gateway]
    
    Traefik --> IAM[IAM Service]
    Traefik --> Template[Template Service]
    
    IAM --> DB[(Neon PostgreSQL)]
    IAM --> Redis[(Redis Cache)]
    IAM --> Kafka[Kafka Events]
    
    style Client fill:#34495E,stroke:#2C3E50,color:#ECF0F1
    style Traefik fill:#1A5490,stroke:#154360,color:#ECF0F1
    style IAM fill:#1E8449,stroke:#186A3B,color:#ECF0F1
    style Template fill:#BA6610,stroke:#935116,color:#ECF0F1
    style DB fill:#6C3483,stroke:#512E5F,color:#ECF0F1
    style Redis fill:#CA6F1E,stroke:#A04000,color:#ECF0F1
    style Kafka fill:#21618C,stroke:#1B4F72,color:#ECF0F1

Color Palette

graph LR
    A["🔵 Primary<br/>#1A5490"] --> B["🟠 Data/Cache<br/>#CA6F1E"]
    B --> C["🟢 Success<br/>#1E8449"]
    C --> D["🟡 Warning<br/>#BA6610"]
    D --> E["🔴 Error<br/>#922B21"]
    E --> F["🟣 Processing<br/>#6C3483"]
    F --> G["🔷 Info<br/>#21618C"]
    G --> H["⚫ Neutral<br/>#34495E"]
    
    style A fill:#1A5490,stroke:#154360,color:#ECF0F1
    style B fill:#CA6F1E,stroke:#A04000,color:#ECF0F1
    style C fill:#1E8449,stroke:#186A3B,color:#ECF0F1
    style D fill:#BA6610,stroke:#935116,color:#ECF0F1
    style E fill:#922B21,stroke:#78281F,color:#ECF0F1
    style F fill:#6C3483,stroke:#512E5F,color:#ECF0F1
    style G fill:#21618C,stroke:#1B4F72,color:#ECF0F1
    style H fill:#34495E,stroke:#2C3E50,color:#ECF0F1

Project Structure

The repository follows a monorepo structure:

Base/
├── apps/                    # Frontend applications
│   ├── app-admin/           # Admin dashboard application
│   ├── app-client/          # Client mobile application (Flutter)
│   ├── web-client/          # Next.js web application
│   └── web-docs/            # Documentation website (Next.js)
├── services/                # Backend microservices
│   ├── iam-service/         # Authentication & Authorization service
│   └── _template/           # Template for new services
├── packages/                # Shared libraries
│   ├── auth-sdk/            # Authentication SDK
│   ├── config/              # Shared configuration utilities
│   ├── http-client/         # Internal HTTP client
│   ├── logger/              # Structured logging (@goodgo/logger)
│   ├── tracing/             # OpenTelemetry tracing
│   └── types/               # Shared TypeScript types
├── infra/                   # Infrastructure configuration
│   ├── databases/           # Database setup scripts
│   ├── docker/              # Docker configurations
│   ├── observability/       # Prometheus, Grafana, Loki configs
│   ├── secrets/             # Secrets management templates
│   └── traefik/             # API Gateway configuration
├── deployments/             # Deployment configurations
│   ├── local/               # Docker Compose for development
│   ├── staging/             # Staging environment configs
│   └── production/          # Production Kubernetes manifests
├── scripts/                 # Automation scripts
│   ├── build/               # Build scripts
│   ├── db/                  # Database utilities
│   ├── deploy/              # Deployment scripts
│   ├── dev/                 # Development helpers
│   ├── observability/       # Monitoring setup scripts
│   ├── setup/               # Initial setup scripts
│   └── utils/               # Utility scripts
└── docs/                    # Documentation
    ├── en/                  # English documentation
    └── vi/                  # Vietnamese documentation

Installation & Setup

1. Clone the Repository

git clone <repository-url>
cd Base

2. Configure Environment

Each service and the local infrastructure needs environment variables. We provide templates for these.

# Initialize project setup (copies .env.example to .env)
./scripts/setup/init-project.sh

3. Setup Neon Database

We use Neon (Serverless PostgreSQL) for all environments (Dev, Staging, Prod).

1. Create a project at neon.tech.
2. Create a branch named dev (or use main).
3. Get the Connection String from the Neon dashboard.
4. Update deployments/local/.env.local:

DATABASE_URL="postgres://user:pass@ep-xyz.region.neon.tech/neondb"

4. Start Infrastructure

Start the supporting infrastructure (Redis, Traefik, Observability) using Docker Compose.

cd deployments/local
docker-compose up -d
# Expected output: Containers for traefik, redis, kafka created

5. Install Dependencies

pnpm install

6. Setup Database Schema

Push the Prisma schema to your Neon database.

# Run migrations for IAM service
pnpm --filter @goodgo/iam-service prisma migrate dev

7. Start Services

Start all backend services in development mode.

pnpm dev
# or start specific service
pnpm --filter @goodgo/iam-service dev

Development Workflow

Creating a New Service

1. Copy the template:

   cp -r services/_template services/my-new-service
   

2. Update package.json name.
3. Add logic in src/modules/.
4. Register in deployments/local/docker-compose.yml.

Making Changes

1. Create a new branch: feature/my-feature.
2. Implement changes.
3. Run tests: pnpm test.
4. Commit with conventional commits: feat(iam): add login endpoint.

Common Commands

Command	Description
pnpm install	Install all dependencies
pnpm dev	Start all services in dev mode
pnpm build	Build all packages and services
pnpm test	Run unit tests
pnpm lint	Lint code
docker-compose up -d	Start local infra
docker-compose down	Stop local infra

Troubleshooting

Port Conflicts

Error: Bind for 0.0.0.0:80 failed: port is already allocated

Solution: Check what's using port 80 (likely another web server) and stop it, or change Traefik ports in docker-compose.yml.

lsof -i :80
kill -9 <PID>

Database Connection Failed

Error: P1001: Can't reach database server

Solution:

1. Check your internet connection (Neon is cloud-based).
2. Verify DATABASE_URL in deployments/local/.env.local.
3. Ensure your IP is allowed in Neon dashboard settings.

Service Not Found in Gateway

Error: 404 Not Found from api.localhost

Solution:

1. Check if service is running.
2. Check Traefik dashboard at http://localhost:8080.
3. Verify PathPrefix labels in docker-compose.yml.

Next Steps

• Development Guide - Deep dive into coding standards
• API Documentation - Explore the APIs
• Architecture - Understand the system design