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