# 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](#prerequisites)
2. [Architecture Overview](#architecture-overview)
3. [Project Structure](#project-structure)
4. [Installation & Setup](#installation--setup)
5. [Development Workflow](#development-workflow)
6. [Common Commands](#common-commands)
7. [Troubleshooting](#troubleshooting)

## Prerequisites

Before starting, ensure you have the following installed:

* **Node.js**: v20.0.0 or higher (recommended v22+ or v25+)
 ```bash
 node -v
 # v25.2.1
 ```
* **PNPM**: v8.15.0 or higher (we use pnpm workspaces)
 ```bash
 pnpm -v
 # 8.15.0
 ```
* **Docker & Docker Compose**: v24.0.0 or higher for local infrastructure
 ```bash
 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.

```mermaid
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

```mermaid
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

```bash
git clone <repository-url>
cd Base
```

### 2. Configure Environment

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

```bash
# 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](https://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`:

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

### 4. Start Infrastructure

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

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

### 5. Install Dependencies

```bash
pnpm install
```

### 6. Setup Database Schema

Push the Prisma schema to your Neon database.

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

### 7. Start Services

Start all backend services in development mode.

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

## Development Workflow

### Creating a New Service

1. Copy the template:
 ```bash
 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`.

```bash
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](development.md) - Deep dive into coding standards
* [API Documentation](../api/openapi/) - Explore the APIs
* [Architecture](../architecture/system-design.md) - Understand the system design