# sp4-test-1770498663

Slack Path 4: Microservices

## Find Your Guide

| If you need to... | Read this |
|-------------------|-----------|
| **Set up local dev** | [local/setup.md](.claude/guides/local/setup.md) |
| **Build a feature** | [feature-development.md](.claude/guides/feature-development.md) |
| **Backend API patterns** | [backend/api-patterns.md](.claude/guides/backend/api-patterns.md) |
| **Frontend design system** | [frontend/design-system.md](.claude/guides/frontend/design-system.md) |
| **Deploy** | [ops/deploying.md](.claude/guides/ops/deploying.md) |

## Quick Reference

```bash
# Start local dev
./scripts/dev.sh

# Run quality checks
./scripts/quality.sh

# List all components
./scripts/discover.sh
```

## Critical Rules

- **Handler pattern:** All handlers return `error`, wrapped with `app.Wrap()`. HTTPErrors map to status codes; raw errors become 500.
- **Request binding:** Always use `app.Bind()` or `app.BindAndValidate()`. Never use raw `json.NewDecoder`.
- **Error types:** Use `httperror.BadRequest`, `httperror.NotFound`, etc. Never bare `http.Error()`.
- **Response envelope:** Use `httpresponse.OK`, `httpresponse.Created`, `httpresponse.NoContent`. All responses use `{data, meta}` envelope.
- **Auth middleware:** Auth is opt-in. Use `auth.Middleware()` in route groups for protected endpoints.
- **OpenAPI first:** Document endpoints in `spec.go` using `openapi.*` helpers. Mount with `application.EnableDocs(spec)`.
- **CSS variables:** All UI components use CSS custom properties (`var(--background)`, `var(--accent)`, etc.). Never hardcode colors.
- **Monorepo imports:** Go packages from `git.threesix.ai/jordan/sp4-test-1770498663/pkg/*`, TypeScript from `@sp4-test-1770498663/*`.

## Architecture

```
sp4-test-1770498663/
├── services/     # Go API services (port 8001+)
├── workers/      # Background workers (no port)
├── apps/         # Frontend applications (port 3001+)
├── cli/          # CLI tools (no port)
├── packages/     # Shared TypeScript packages
│   ├── ui/       # UI components (@sp4-test-1770498663/ui)
│   ├── layout/   # Dashboard layout (@sp4-test-1770498663/layout)
│   ├── auth/     # Auth provider (@sp4-test-1770498663/auth)
│   ├── api-client/ # Typed API client (@sp4-test-1770498663/api-client)
│   └── logger/   # HTTP/console logger (@sp4-test-1770498663/logger)
├── pkg/          # Shared Go packages
│   ├── app/      # Service bootstrapper (Wrap, Bind, Health)
│   ├── chassis/  # Facade re-exporting app types
│   ├── openapi/  # OpenAPI 3.0 spec builder + Scalar docs
│   ├── httperror/ # Typed HTTP errors
│   ├── httpresponse/ # Response envelope helpers
│   ├── httpvalidation/ # Struct validation
│   ├── middleware/ # RequestID, CORS, Recovery, Logger
│   ├── auth/     # JWT, API key, middleware
│   ├── config/   # Viper-based configuration
│   ├── httpclient/ # Resilient HTTP client
│   └── logging/  # slog wrapper
└── scripts/      # Development & CI scripts
```

| Slot | Language | Port Range | Purpose |
|------|----------|------------|---------|
| services/ | Go | 8001+ | REST APIs, backend services |
| workers/ | Go | none | Background jobs, queue consumers |
| apps/ | TypeScript | 3001+ | React, Next.js, Astro frontends |
| cli/ | Go | none | CLI tools, scripts |
| packages/ | TypeScript | none | Shared frontend packages |
| pkg/ | Go | none | Shared backend packages |

## Components

| Component | Type | Path |
|-----------|------|------|
| **auth-svc** | API service | `services/auth-svc/` |
| **chat-svc** | API service | `services/chat-svc/` |
| **worker-svc** | Background worker | `workers/worker-svc/` |