xtablo-source/docs/API_TURBOREPO_INTEGRATION.md

# API Turborepo Integration

## Overview

The `api` folder has been successfully integrated into the Turborepo monorepo structure. This document outlines the changes made and how to work with the API in the new setup.

## Changes Made

### 1. Folder Structure

- **Before**: `api/` (root level)
- **After**: `apps/api/` (inside apps directory)

The API has been moved to the `apps` directory to follow the monorepo convention where all applications live under `apps/` and shared packages live under `packages/`.

### 2. Package Configuration

#### Updated `apps/api/package.json`

```json
{
  "name": "@xtablo/api",           // Changed from "xtablo-api"
  "private": true,                 // Added
  "version": "1.0.0",              // Added version
  "scripts": {
    "typecheck": "tsc --noEmit",   // Added typecheck script
    "clean": "rm -rf dist node_modules/.cache"  // Added clean script
  }
}
```

#### Created `apps/api/turbo.json`

Turbo configuration for the API app with specific task definitions for `build`, `dev`, and `test`.

#### Created `apps/api/biome.json`

Biome configuration for linting and formatting, consistent with other apps.

### 3. Root Configuration Updates

#### Updated `package.json`

Added API-specific scripts:

```json
{
  "scripts": {
    "dev:api": "turbo dev --filter=@xtablo/api",
    "test:api": "turbo test --filter=@xtablo/api"
  }
}
```

#### Updated `biome.json`

Changed all references from `api/` to `apps/api/` in:
- File includes
- Override paths

#### Updated `apps/api/cloudbuild.yaml`

Changed Docker build context from `api` to `apps/api`.

### 4. Workspace Integration

The API is now automatically included in the pnpm workspace via the existing `apps/*` pattern in `pnpm-workspace.yaml`.

### 5. Documentation Updates

Updated all Stripe-related documentation files to reference `cd apps/api` instead of `cd api`:
- `docs/STRIPE_IMPLEMENTATION_SUMMARY.md`
- `docs/TESTING_WITH_FAKE_ACCOUNTS.md`
- `docs/STRIPE_README.md`
- `docs/STRIPE_WITH_SYNC_ENGINE.md`
- `docs/STRIPE_INTEGRATION_COMPLETE.md`
- `docs/STRIPE_QUICK_REFERENCE.md`
- `docs/STRIPE_SETUP.md`
- `docs/STRIPE_FINAL_SETUP.md`

### 6. Package Lock Files

- Removed `apps/api/package-lock.json` (npm lock file)
- Updated `pnpm-lock.yaml` to include the API package

## Usage

### Running Commands from Root

All turbo commands can now be run from the root directory with the `--filter` flag:

```bash
# Development
pnpm run dev:api

# Building
turbo build --filter=@xtablo/api

# Testing
pnpm run test:api
turbo test --filter=@xtablo/api

# Type checking
turbo typecheck --filter=@xtablo/api

# Linting and formatting
turbo lint --filter=@xtablo/api
turbo lint:fix --filter=@xtablo/api
turbo format --filter=@xtablo/api

# Clean build artifacts
turbo clean --filter=@xtablo/api
```

### Running Commands from API Directory

All existing npm scripts still work when you're inside the `apps/api` directory:

```bash
cd apps/api

# Development
pnpm dev

# Build
pnpm build

# Test
pnpm test
pnpm test:watch

# Lint
pnpm lint
pnpm lint:fix
```

### Running All Apps Together

You can now run all apps in parallel using turbo:

```bash
# Run dev for all apps
pnpm run dev

# Build all apps
pnpm run build

# Lint all apps
pnpm run lint

# Test all apps
pnpm run test
```

## Benefits

1. **Consistent Tooling**: The API now uses the same build tools (Turbo, pnpm) as other apps
2. **Parallel Execution**: Turbo can run API tasks in parallel with other apps
3. **Caching**: Turbo's caching mechanism speeds up builds and tests
4. **Dependency Management**: Shared dependencies are deduplicated by pnpm
5. **Workspace Support**: Easy to share code between the API and other packages
6. **Better DX**: Unified commands across all apps

## Verification

All tests pass:
- ✅ Type checking: `turbo typecheck --filter=@xtablo/api`
- ✅ Linting: `turbo lint --filter=@xtablo/api` (with auto-fix applied)
- ✅ Tests: `turbo test --filter=@xtablo/api` (67 tests passing)
- ✅ Build: `turbo build --filter=@xtablo/api`

## Notes

- The API's Docker configuration (`Dockerfile` and `cloudbuild.yaml`) has been updated to reference the new path
- All import sorting issues were automatically fixed with biome
- The API maintains its existing functionality and dependencies
- No changes to the API's runtime behavior or endpoints