# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## What This Project Is

A self-hosted implementation of Microsoft's CodePush service — a system that lets React Native developers deploy over-the-air (OTA) updates to mobile apps without going through the app store. It consists of two main components:

- **`api/`** — Node.js/Express REST API (TypeScript)
- **`cli/`** — Command-line interface for developers to manage apps and releases (TypeScript)

## Commands

### API

```bash
cd api
npm install
npm run build        # TypeScript compilation
npm run lint         # ESLint
npm run lint:fix     # Auto-fix linting issues
npm test             # Mocha tests (outputs to mochawesome-report/)
npm run start:env    # Start server with .env file
```

### CLI

```bash
cd cli
npm install
npm run build
npm run lint
npm run lint:fix
npm test
npm install -g .     # Install globally as `code-push-standalone`
```

### Docker (local dev)

```bash
cd api
docker-compose up    # Starts server + PostgreSQL + Redis + LocalStack S3
docker-compose run lint-and-test
```

The docker-compose setup binds: server `:3000`, PostgreSQL `:5432`, Redis `:6379`, LocalStack S3 `:4566`.

## Architecture

### Storage Layer

The storage layer is fully abstracted behind an interface in `api/script/storage/storage.ts`. The implementation is selected by the `STORAGE_TYPE` environment variable:

| `STORAGE_TYPE` | Implementation | Use case |
|---|---|---|
| `PostgresS3Storage` | PostgreSQL + AWS S3 | Production default |
| `RedisS3Storage` | Redis + AWS S3 | Alternative production |
| `AzureStorage` | Azure Tables + Azure Blob | Azure deployments |
| `JsonStorage` | Local filesystem JSON | Development/testing |

All routes reference only the storage interface — never a concrete implementation.

### Request Flows

**Mobile app update check:**
`GET /updateCheck` → `routes/acquisition.ts` → storage lookup → Redis cache check → rollout targeting logic in `utils/acquisition.ts` → response

**CLI release upload:**
`POST /deployments/:name/releases` → `routes/management.ts` → multipart upload → `storage.addPackage()` → S3 blob upload → DB update → Redis cache invalidation

**Authentication:**
OAuth via GitHub or Microsoft → `routes/passport-authentication.ts` → `storage.getOrAddAccount()` → cookie-based session. At least one OAuth provider must be configured via env vars.

### Data Model

PostgreSQL schema is in `api/database/schema/code-push-server-db.sql`. Key tables: `accounts`, `apps`, `collaborators`, `deployments`, `packages`, `access_keys`, `blobs`.

The `packages` table tracks release history per deployment, including rollout percentage, diff maps for delta updates, and release method (Upload/Promote/Rollback).

### Key Source Files

- `api/script/server.ts` — entry point, HTTPS/HTTP setup
- `api/script/default-server.ts` — Express app, middleware registration
- `api/script/routes/acquisition.ts` — update check/download endpoints consumed by mobile apps
- `api/script/routes/management.ts` — account/app/deployment/release management
- `api/script/redis-manager.ts` — metrics caching; Redis is optional (used for performance, not correctness)
- `api/script/utils/package-diffing.ts` — delta update generation between releases
- `cli/script/command-executor.ts` — all CLI command logic
- `cli/script/management-sdk.ts` — typed HTTP client wrapping the management API

## Configuration

Copy `api/.env.example` to `api/.env`. Minimum required variables:
- `STORAGE_TYPE` — choose a backend
- `SERVER_URL` — public URL of the server
- `GITHUB_CLIENT_ID` + `GITHUB_CLIENT_SECRET` and/or Microsoft OAuth credentials

Full environment variable reference: `api/ENVIRONMENT.md`.

## Testing

Tests live in `api/test/` and cover acquisition logic, management endpoints, storage implementations, package diffing, and Redis caching. Tests use Mocha + ts-mocha. To run a single test file:

```bash
cd api
npx ts-mocha test/<filename>.ts
```