.cursorrules

# Notifuse Coding Standards

## General Principles

- Never commit to github without asking
- Never test tracing and logging - these are implementation details
- When you return a work summary, make sure it is very very short and concise

## Go Backend Structure

- Follow Clean Architecture pattern with these layers:
  - Domain - core business logic and entities
  - HTTP - API handlers
  - Repository - data storage
  - Service - business logic

## Imports and Aliases

- Primary import path: `github.com/Notifuse/notifuse` (prefer-imports)
- UUID alias: `uuid` for `github.com/google/uuid`
- Logging alias: `zerolog` for `github.com/rs/zerolog`
- Testing aliases: `assert` and `require` for testify packages

## Project Structure

- Domain layer: `internal/domain/`
  - Domain entities:
    - internal/domain/workspace.go, internal/domain/user.go, internal/domain/template.go
    - internal/domain/contact.go, internal/domain/list.go, internal/domain/broadcast.go
    - internal/domain/transactional.go, internal/domain/task.go, internal/domain/webhook_event.go
    - internal/domain/webhook_registration.go, internal/domain/message.go, internal/domain/email_provider.go, internal/domain/auth.go
  - Domain helpers:
    - internal/domain/errors.go, internal/domain/types.go, internal/domain/nullables.go
    - internal/domain/timezones.go, internal/domain/event.go, internal/domain/nullable_json.go
- HTTP layer: `internal/http/`
  - Handlers:
    - internal/http/workspace_handler.go, internal/http/user_handler.go, internal/http/template_handler.go
    - internal/http/contact_handler.go, internal/http/list_handler.go, internal/http/broadcast_handler.go
    - internal/http/transactional_handler.go, internal/http/task_handler.go, internal/http/webhook_event_handler.go
    - internal/http/webhook_registration_handler.go, internal/http/email_handler.go, internal/http/root_handler.go, internal/http/favicon_handler.go
- Repository layer: `internal/repository/`
  - Implementations:
    - internal/repository/workspace_postgres.go, internal/repository/user_postgres.go, internal/repository/template_postgres.go
    - internal/repository/contact_postgres.go, internal/repository/list_postgres.go, internal/repository/broadcast_postgres.go
    - internal/repository/transactional_postgre.go, internal/repository/task_postgres.go, internal/repository/webhook_event_postgres.go
    - internal/repository/auth_repository.go, internal/repository/contact_list_postgres.go, internal/repository/message_history_repository.go
- Service layer: `internal/service/`
  - Implementations:
    - internal/service/workspace_service.go, internal/service/user_service.go, internal/service/template_service.go
    - internal/service/contact_service.go, internal/service/list_service.go, internal/service/broadcast_service.go
    - internal/service/transactional_service.go, internal/service/task_service.go, internal/service/webhook_event_service.go
    - internal/service/webhook_registration_service.go, internal/service/email_service.go, internal/service/auth_service.go, internal/service/contact_list_service.go
  - Email provider services:
    - internal/service/sparkpost_service.go, internal/service/mailjet_service.go, internal/service/mailgun_service.go
    - internal/service/ses_service.go, internal/service/postmark_service.go

## Error Handling

- Return errors directly: `if err != nil { return err }`
- Wrap errors with context: `errors.Wrap(err, "message")`

## Testing Guidelines

- Test files should use `_test.go` suffix
- Keep tests in the same package as code being tested
- Aim for minimum 75% test coverage
- Focus on testing business logic, not implementation details
- Skip verification of logging and tracing in tests
- Preferred testing functions: assert.NoError, require.NoError, mock.Anything, mock.AnythingOfType
- Never test logging or tracing - they are implementation details
- Focus tests on business logic and behavior, not cross-cutting concerns
- Skip verification: logging, tracing
- Test only functional behavior

## Frontend (React)

- Frontend code in `console/` folder
- Use React, React Router, React Query, and Ant Design
- Follow component naming convention: PascalCase.tsx
- Test files: `*.test.tsx` or `*.test.ts`
- CSS framework: Tailwind
- UI library: Ant Design components
- Form components: Form, Input, Select, Checkbox, Radio
- Feedback components: Modal, Drawer, Alert, message, notification
- Layout components: Layout, Space, Divider, Grid
- Data components: Table, List, Pagination

## Database

- Use Squirrel as query builder
- Use lib/pq as database driver

## Logging

- Use `github.com/Notifuse/notifuse/pkg/logger`
- Utilize logger levels: Debug, Info, Warn, Error, Fatal, WithField, WithFields

## Mocks

- Package mocks: `pkg/mocks/`
- Domain mocks: `internal/domain/mocks/`

## Tracing (OpenCensus)

- Tracing path: `pkg/tracing`
- Imports: go.opencensus.io/trace, contrib.go.opencensus.io/exporter/jaeger, contrib.go.opencensus.io/exporter/prometheus
- Exporters: Jaeger, Prometheus, Zipkin, Stackdriver, Datadog, X-Ray
- Metrics exporters: Prometheus, Stackdriver, Datadog
- Use helper functions: StartServiceSpan, EndSpan, TraceMethod, TraceMethodWithResult, AddAttribute, MarkSpanError
- DB tracing function: WrapDBDriver
- HTTP tracing middleware: internal/http/middleware/tracing.go
- App tracing init: cmd/api/app.go:InitTracing
- Tracer interface: github.com/Notifuse/notifuse/pkg/tracing.Tracer
- Tracer implementation: github.com/Notifuse/notifuse/pkg/tracing.DefaultTracer
- Tracer global access: tracing.GetTracer()
- Tracer method patterns: StartServiceSpan, EndSpan, AddAttribute, MarkSpanError, TraceMethod
- Span pattern: `ctx, span := tracing.StartSpan(ctx, "operation-name")`
- Error handling: `defer tracing.EndSpan(span, err)`
- Service span pattern: `ctx, span := tracing.StartServiceSpan(ctx, "ServiceName", "MethodName")`
- Service tracing pattern: `return tracing.TraceMethod(ctx, "ServiceName", "MethodName", func(ctx context.Context) error { /* method body */ })`
- HTTP client tracing: `client = tracing.WrapHTTPClient(client)`
- Span attributes: `tracing.AddAttribute(ctx, "key", value)`
- Span error marking: `tracing.MarkSpanError(ctx, err)`

## Code Coverage

- Use codecov ignores for tracing patterns
- Ignore tracing patterns: 'ctx, span := tracing.StartSpan', 'defer tracing.EndSpan', 'tracing.AddAttribute', 'tracing.MarkSpanError', 'tracing.TraceMethod', 'tracing.GetTracer()', 'tracing.WrapHTTPClient', 'tracing.StartServiceSpan'
- Annotation format: `// codecov:ignore`
- Block annotation:
  - Start: `// codecov:ignore:start`
  - End: `// codecov:ignore:end`
- Always surround tracing and logging with codecov ignore comments

## Project Structure Folders

- Domain folder: internal/domain
- Services folder: internal/service
- Repository folder: internal/repository
- HTTP folder: internal/http

## Notification Center

- Frontend code in `notification_center/` folder at project root
- Mobile-first design
- Built with React, TypeScript, and Vite
- Follow component naming convention: PascalCase.tsx
- Test files: `*.test.tsx` or `*.test.ts`
- CSS framework: Same as main frontend (Tailwind)
- UI library: Same as main frontend (Ant Design)