# 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
    ```bash
    node -v
    # v20.10.0
    ```
*   **PNPM**: v8.0.0 or higher (we use pnpm workspaces)
    ```bash
    pnpm -v
    # 8.12.0
    ```
*   **Docker & Docker Compose**: For local infrastructure
    ```bash
    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.

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

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