gru_emoney_token-factory/api/GETTING_STARTED.md

# Getting Started with eMoney API

## Prerequisites

- **Node.js**: 18.0.0 or higher
- **pnpm**: 8.0.0 or higher (package manager)
- **TypeScript**: 5.3.0 or higher
- **Redis**: For idempotency handling
- **Kafka/NATS**: For event bus (optional for development)

## Installing pnpm

If you don't have pnpm installed:

```bash
# Using npm
npm install -g pnpm

# Using curl (Linux/Mac)
curl -fsSL https://get.pnpm.io/install.sh | sh -

# Using Homebrew (Mac)
brew install pnpm

# Verify installation
pnpm --version
```

## Workspace Setup

This is a pnpm workspace with multiple packages. Install all dependencies from the `api/` root:

```bash
cd api
pnpm install
```

This will install dependencies for all packages in the workspace:
- Services (REST API, GraphQL, Orchestrator, etc.)
- Shared utilities (blockchain, auth, validation, events)
- Tools (Swagger UI, mock servers, SDK generators)
- Packages (schemas, OpenAPI, GraphQL, etc.)

## Running Services

### REST API Server

```bash
cd api/services/rest-api
pnpm run dev
```

Server runs on: http://localhost:3000

### GraphQL API Server

```bash
cd api/services/graphql-api
pnpm run dev
```

Server runs on: http://localhost:4000/graphql

### Swagger UI Documentation

```bash
cd api/tools/swagger-ui
pnpm run dev
```

Documentation available at: http://localhost:8080/api-docs

### Mock Servers

```bash
cd api/tools/mock-server
pnpm run start:all
```

Mock servers:
- REST API Mock: http://localhost:4010
- GraphQL Mock: http://localhost:4020
- Rail Simulator: http://localhost:4030
- Packet Simulator: http://localhost:4040

## Building

Build all packages:

```bash
cd api
pnpm run build:all
```

Build specific package:

```bash
cd api/services/rest-api
pnpm run build
```

## Testing

Run all tests:

```bash
cd api
pnpm run test:all
```

Run specific test suite:

```bash
cd test/api
pnpm test
```

## Workspace Commands

From the `api/` root:

```bash
# Install all dependencies
pnpm install

# Build all packages
pnpm run build:all

# Run all tests
pnpm run test:all

# Run linting
pnpm run lint:all

# Clean all build artifacts
pnpm run clean:all
```

## Package Management

### Adding Dependencies

To a specific package:

```bash
cd api/services/rest-api
pnpm add express
```

To workspace root (dev dependency):

```bash
cd api
pnpm add -D -w typescript
```

### Using Workspace Packages

Internal packages use `workspace:*` protocol:

```json
{
  "dependencies": {
    "@emoney/blockchain": "workspace:*",
    "@emoney/validation": "workspace:*"
  }
}
```

## Troubleshooting

### pnpm not found

Install pnpm globally:
```bash
npm install -g pnpm
```

### Workspace dependencies not resolving

Ensure you're running commands from the `api/` root:
```bash
cd api
pnpm install
```

### Build errors

Clear node_modules and reinstall:
```bash
cd api
rm -rf node_modules
rm pnpm-lock.yaml
pnpm install
```

## Next Steps

1. Review [API README](README.md) for architecture overview
2. Check [Swagger UI Guide](../docs/api/swagger-ui-guide.md) for API documentation
3. See [Integration Cookbook](../docs/api/integration-cookbook.md) for usage examples
4. Review [Error Catalog](../docs/api/error-catalog.md) for error handling