sp3-verify-1770325758/CLAUDE.md

sp3-verify-1770325758

Slack Path 3: Realtime Chat

Find Your Guide

If you need to...	Read this
Set up local dev	local/setup.md
Build a feature	feature-development.md
Backend API patterns	backend/api-patterns.md
Frontend design system	frontend/design-system.md
Deploy	ops/deploying.md

Quick Reference

# 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/sp3-verify-1770325758/pkg/*, TypeScript from @sp3-verify-1770325758/*.

Architecture

sp3-verify-1770325758/
├── 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 (@sp3-verify-1770325758/ui)
│   ├── layout/   # Dashboard layout (@sp3-verify-1770325758/layout)
│   ├── auth/     # Auth provider (@sp3-verify-1770325758/auth)
│   ├── api-client/ # Typed API client (@sp3-verify-1770325758/api-client)
│   └── logger/   # HTTP/console logger (@sp3-verify-1770325758/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