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

  node -v
  # v20.10.0
  

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

  pnpm -v
  # 8.12.0
  

• Docker & Docker Compose: For local infrastructure

  docker -v
  # Docker version 24.0.0
  

• 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 Traefik fill:#e1f5ff
    style DB fill:#f0e1ff
    style Redis fill:#fff4e1

Project Structure

The repository follows a monorepo structure:

Base/
├── apps/                 # Frontend applications
│   ├── web-client/       # Next.js web application
│   └── mobile-client/    # Flutter mobile application
├── services/             # Backend microservices
│   ├── iam-service/      # Authentication & Authorization
│   └── _template/        # Template for new services
├── packages/             # Shared libraries
│   ├── logger/           # Structured logging
│   ├── types/            # Shared TypeScript types
│   └── http-client/      # Internal HTTP client
├── infra/                # Infrastructure configuration
│   ├── traefik/          # API Gateway config
│   └── databases/        # Database setup scripts
├── deployments/          # Deployment configurations
│   ├── local/            # Docker Compose for dev
│   └── k8s/              # Kubernetes manifests
└── docs/                 # 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