Service Standards

Service Structure

All services follow this structure:

services/<service-name>/
├── package.json              # Service dependencies
├── tsconfig.json            # Extends shared config
├── Dockerfile               # Multi-stage build
├── .env.example             # Environment template
└── src/
    ├── index.ts             # Entry point
    ├── app.ts               # Hono app setup
    ├── routes/              # API routes
    │   └── *.ts
    └── __tests__/           # Tests
        └── *.test.ts

Creating a New Service

bun run create-service <name> [port]
# Example: bun run create-service catalog 3003

Service Checklist

• Uses @crop/shared-types for common types
• Uses @crop/shared-hono middleware (requestId, logging, cors)
• Has /health and /ready endpoints
• Has OpenAPI documentation at /docs
• Has .env.example with all required variables
• Has Dockerfile with multi-stage build
• Has tests in tests/
• Added to docker-compose.yml

API Standards

Response Format

All responses use ApiResponse wrapper:

{
  success: boolean;
  data?: T;
  error?: { code: string; message: string; details?: unknown };
  meta?: { timestamp: string; requestId: string };
}

Error Codes

• NOT_FOUND - Resource not found (404)
• BAD_REQUEST - Invalid input (400)
• UNAUTHORIZED - Not authenticated (401)
• FORBIDDEN - Not authorized (403)
• INTERNAL_ERROR - Unexpected error (500)

Environment Variables

Required for all services:

• PORT - Service port
• NODE_ENV - development/production
• MONGODB_URI - MongoDB connection string
• LOG_LEVEL - info/debug/error

Ports Convention

• 3001: search
• 3003: catalog
• 3004: media
• 3005: user
• 9200: Elasticsearch
• 27017: MongoDB

Development

# Local development
cd services/<service-name>
bun run dev

# Docker development
make dev  # From root

# Tests
bun test

# Build
bun run build

Deployment

All services deploy to Google Cloud Run via GitHub Actions.