xtablo-source/apps/api/README.md

# Xtablo API

This is the backend API for Xtablo, built with [Hono](https://hono.dev/) and TypeScript.

## Development

This package is part of the Xtablo monorepo managed with Turborepo and pnpm workspaces.

### Prerequisites

- Node.js >= 20.0.0
- pnpm 10.x

### Available Commands

From the root of the monorepo:

```bash
# Start development server
pnpm run dev:api

# Build the API
turbo run build --filter=@xtablo/api

# Run tests
pnpm run test:api

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

# Linting
turbo run lint --filter=@xtablo/api
turbo run lint:fix --filter=@xtablo/api

# Format code
turbo run format --filter=@xtablo/api
```

From within the `apps/api` directory:

```bash
# Start development server
pnpm dev

# Build
pnpm build

# Start production server
pnpm start

# Run tests
pnpm test
pnpm test:watch

# Linting and formatting
pnpm lint
pnpm lint:fix
pnpm format
```

## Project Structure

```
apps/api/
├── src/
│   ├── __tests__/     # Test files
│   ├── helpers/       # Helper functions
│   ├── middlewares/   # Hono middlewares
│   ├── routers/       # API route handlers
│   ├── types/         # TypeScript type definitions
│   ├── config.ts      # Configuration
│   ├── index.ts       # Entry point
│   └── secrets.ts     # Secret management
├── dist/              # Compiled output
├── docs/              # API documentation
├── examples/          # Usage examples
├── Dockerfile         # Docker configuration
├── cloudbuild.yaml    # Google Cloud Build config
├── package.json
├── tsconfig.json
└── turbo.json         # Turborepo config
```

## Environment Variables

See `.env.example` for required environment variables.

## Deployment

The API is deployed to Google Cloud Run. See `cloudbuild.yaml` for deployment configuration.

## Dokploy Deployment

Prefer a Dokploy `Application` instead of a Compose service.

Dokploy supports Dockerfile-based applications directly, which fits this API better than maintaining a dedicated compose wrapper. Configure the application like this:

- Build Type: `Dockerfile`
- Dockerfile Path: `apps/api/Dockerfile`
- Docker Context Path: `.`
- Docker Build Stage: `final`
- Port: `8080`
- Run Command: leave empty and use the image `CMD`

Set these Dokploy environment variables:

- `NODE_ENV`
- `DD_SERVICE=xtablo-api`
- `DD_ENV`
- `DD_VERSION`
- `DD_LOGS_INJECTION=true`
- `SUPABASE_URL`
- `SUPABASE_SERVICE_ROLE_KEY`
- `SUPABASE_CONNECTION_STRING`
- `SUPABASE_CA_CERT`
- `STRIPE_SECRET_KEY`
- `STRIPE_WEBHOOK_SECRET`
- `STRIPE_SOLO_PRICE_ID`
- `STRIPE_TEAM_PRICE_ID`
- `STRIPE_FOUNDER_PRICE_ID`
- `EMAIL_USER`
- `EMAIL_CLIENT_ID`
- `EMAIL_CLIENT_SECRET`
- `EMAIL_REFRESH_TOKEN`
- `R2_ACCOUNT_ID`
- `R2_ACCESS_KEY_ID`
- `R2_SECRET_ACCESS_KEY`
- `TASKS_SECRET`

For Datadog logs, the Dokploy host should already run a Datadog Agent with Docker log collection enabled. Then add these Docker Swarm labels in Dokploy `Advanced Settings -> Swarm Settings -> Labels`:

- `com.datadoghq.tags.service=xtablo-api`
- `com.datadoghq.tags.env=${DD_ENV}`
- `com.datadoghq.tags.version=${DD_VERSION}`
- `com.datadoghq.ad.logs=[{"source":"nodejs","service":"xtablo-api"}]`

This gives you:

- container logs in Datadog with `source: nodejs`
- service tagging as `xtablo-api`
- APM/log correlation via `dd-trace` plus `DD_LOGS_INJECTION=true`