# 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:#7F8C8D,color:#fff
    style Traefik fill:#2980B9,color:#fff
    style IAM fill:#27AE60,color:#fff
    style Template fill:#E67E22,color:#fff
    style DB fill:#8E44AD,color:#fff
    style Redis fill:#F39C12,color:#fff
    style Kafka fill:#3498DB,color:#fff
```

### Color Palette

```mermaid
graph LR
    A["Primary<br/>#2980B9"] --> B["Data/Cache<br/>#F39C12"]
    B --> C["Success<br/>#27AE60"]
    C --> D["Warning<br/>#E67E22"]
    D --> E["Error<br/>#C0392B"]
    E --> F["Processing<br/>#8E44AD"]
    F --> G["Info<br/>#3498DB"]
    G --> H["Neutral<br/>#7F8C8D"]
    
    style A fill:#2980B9,color:#fff
    style B fill:#F39C12,color:#fff
    style C fill:#27AE60,color:#fff
    style D fill:#E67E22,color:#fff
    style E fill:#C0392B,color:#fff
    style F fill:#8E44AD,color:#fff
    style G fill:#3498DB,color:#fff
    style H fill:#7F8C8D,color:#fff
```

## 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