84 lines
3.6 KiB
Markdown
84 lines
3.6 KiB
Markdown
# css-verify-1770193392
|
|
|
|
Composable app E2E test
|
|
|
|
## 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/css-verify-1770193392/pkg/*`, TypeScript from `@css-verify-1770193392/*`.
|
|
|
|
## Architecture
|
|
|
|
```
|
|
css-verify-1770193392/
|
|
├── 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 (@css-verify-1770193392/ui)
|
|
│ ├── layout/ # Dashboard layout (@css-verify-1770193392/layout)
|
|
│ ├── auth/ # Auth provider (@css-verify-1770193392/auth)
|
|
│ ├── api-client/ # Typed API client (@css-verify-1770193392/api-client)
|
|
│ └── logger/ # HTTP/console logger (@css-verify-1770193392/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 |
|
|
|-----------|------|------|
|
|
| **web** | React app | `apps/web/` |
|
|
| **api** | API service | `services/api/` |
|
|
|