# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

This is a Go microservice skeleton/template for Quantex projects. It implements a **Hexagonal Architecture** (Ports & Adapters) pattern with clear separation between domain logic, application orchestration, and infrastructure concerns. The skeleton supports multiple execution modes (REST API service, MQTT async messaging, external API integration examples) through a runner-based system.

## Development Commands

### Building and Running

```bash
# Run the REST API service (text logs)
QUANTEX_ENVIRONMENT="dev" go run main.go -c -run service

# Run the REST API service (JSON logs)
QUANTEX_ENVIRONMENT="dev" go run main.go -run service

# Run with debug mode and specific log format
QUANTEX_ENVIRONMENT="dev" go run main.go -d -f tint1 -run service

# Build for current platform
make build

# Build for Linux (production)
make linux-build
```

### Available Runners

The application supports multiple execution modes via the `-run` flag:
- `service` - Main REST API server (Gin framework)
- `async` - MQTT messaging example
- `external` - QApix external API integration example
- `tracerr` - Error handling demonstration
- `logger` - Logging format demonstration

### Log Formats

Use `-f` or `-logs-format` flag:
- `json` - Structured JSON logs (default, for production)
- `text` - Plain text logs
- `tint1` - Single-line colored logs (best for local development)
- `tint2` - Two-line colored logs

### Testing and Linting

```bash
# Run all tests
make test

# Run tests for specific package
go test ./src/client/api/rest/...

# Run single test
go test ./src/... -run TestFunctionName

# Run checks and linters
make check

# Format code (gofumpt, gci, goimports)
make fmt

# Full CI pipeline (format, tidy, checks)
make ci

# Regenerate Swagger docs
make swag

# Run development workflow (checklist + check)
make dev
```

### Branch Management

```bash
# Create new branch with naming convention
make branch t=feature u=jdoe n=39 m="add new endpoint"
# Creates: feature/jdoe/SKL-39/add_new_endpoint

# Valid types: feature, hotfix, refactor, improvement, doc, fix
```

### Deployment

```bash
# Deploy to environment (requires SSH alias in ~/.ssh/config)
make deploy e=dev
make deploy e=prod

# First-time deployment
make first-deploy e=dev
```

## Architecture

### Layer Structure

The codebase follows Hexagonal Architecture with four distinct layers:

```
main.go (entry point)
    ↓
src/cmd/ (Command/Runner layer - bootstrap & execution modes)
    ↓
src/app/ (Application layer - configuration & wiring)
    ↓
src/client/ (Infrastructure layer - external integrations)
    ↓
src/domain/ (Domain layer - business logic & contracts)
    ↓
src/common/ (Cross-cutting concerns)
```

### Directory Organization

- **`src/domain/`** - Core business models and interfaces (Asyncer, Notifier, UserDataProvider). Pure domain logic with no dependencies on infrastructure.

- **`src/app/`** - Application-level configuration structures, version information, and global settings. Bridges domain and infrastructure.

- **`src/client/`** - All infrastructure implementations:
  - `api/rest/` - Gin HTTP server, controllers, routes, middleware (auth, CORS)
  - `api/async/` - MQTT client for async messaging
  - `config/` - TOML configuration loading
  - `data/` - Data provider implementations
  - `store/` - Database (MultiDB) and external API clients (QApix)
  - `notify/` - Notification services (Google Chat, Slack)
  - `res/` - Embedded resources

- **`src/cmd/`** - Runners for different execution modes:
  - `service/` - Main REST API service runner
  - `example/` - Example runners (async, external, tracerr, logger)
  - `base.go` - Runner abstraction and factory

- **`src/common/`** - Shared utilities:
  - `logger/` - Multi-format logging (JSON, text, tint) with Gin middleware
  - `tracerr/` - Error handling with stack trace capture
  - `securetoken/` - JWT token encryption/validation

### REST API Architecture

The REST API uses **Gin framework** with the following patterns:

**Authentication Strategies:**
1. **Cookie-based** - HTTP-only secure cookie with Redis-backed session (20-minute TTL)
2. **Bearer token** - Format: `Bearer email:token`
3. **JWT token** - Service-to-service auth with permission validation

**Middleware Chain:**
```
Request → Options (CORS) → AuthRequired → Role Check → Handler
```

**Available middlewares in `src/client/api/rest/midlewares.go`:**
- `Options()` - CORS preflight handler
- `AuthRequired()` - Validates cookie or Authorization header
- `TokenAuth()` - Bearer token validation
- `JWTTokenAuth()` - JWT service token validation
- `CookieAuth()` - Session cookie validation
- Role-based: `SuperUser()`, `BackOfficeUser()`, `PartyAdmin()`, etc.

**Key files:**
- `server.go` - Server initialization, Redis pool setup, trusted proxies
- `controller.go` - HTTP handlers (Login, Refresh, GetUser)
- `routes.go` - Route definitions with middleware chains
- `model.go` - Request/response DTOs
- `validator.go` - Input validation
- `traslator.go` - Response formatting

### Async/MQTT Architecture

Located in `src/client/api/async/`, uses Eclipse Paho MQTT client:

- JWT-based authentication (token generated with service name and expiry)
- Auto-reconnect with keep-alive
- Topic structure: `{subdomain}/quantex/{topic}`
- Error notifications integrated
- Implements `domain.Asyncer` interface

### Configuration System

Configuration uses **TOML files** with two-level structure:

1. **Global config** (`../global_conf.toml`) - Shared settings across services
2. **Service config** (`conf.toml`) - Service-specific settings

Key configuration sections:
- `[MQTT]` - Async messaging settings
- `[Gin]` - HTTP server configuration
- `[Notify]` - Notification channels (Google, Slack)
- `[ExtAuth]` - External authentication providers

Environment variable `QUANTEX_ENVIRONMENT` (required) determines runtime behavior:
- `dev` - Development mode, debug logging, relaxed CORS
- `demo`, `open-demo` - Demo environments
- `prod` - Production mode, release logging, strict security

### Dependency Injection Pattern

Dependencies flow from `main.go` → runners → infrastructure:

```go
// Example from service runner
api := rest.New(userData, appStore, restConfig, notify)
// Dependencies: UserDataProvider, Store, Config, Notifier
```

All dependencies are interface-based for testability and loose coupling.

### Error Handling

Use `src/common/tracerr/` for errors that need stack traces:

```go
import "quantex.com/skeleton/src/common/tracerr"

// Instead of fmt.Errorf:
return tracerr.Errorf("failed to process: %w", err)

// Errors automatically include stack traces
// Critical errors trigger notification via domain.Notifier
```

### Logging

Access via standard library `log/slog`:

```go
import "log/slog"

slog.Info("message", "key", value)
slog.Error("error occurred", "error", err)
slog.Debug("debug info") // Only visible with -d flag
```

Logger integrates with Gin middleware for request logging and sends error-level logs to notifier.

## Common Development Patterns

### Adding a New REST Endpoint

1. Add handler method to `src/client/api/rest/controller.go`
2. Define request/response models in `model.go`
3. Add route in `routes.go` with appropriate middleware
4. Update Swagger comments (use `// @` annotations)
5. Run `make swag` to regenerate docs
6. Test with `make test`

### Adding a New Async Message Handler

1. In your runner, subscribe to topic:
```go
asyncManager.Subscribe("my-topic", func(topic string, msg []byte) {
    // Handle message
})
```
2. Publish messages:
```go
asyncManager.Publish("my-topic", myMessage)
```

### Adding a New Notifier

1. Create package in `src/client/notify/{provider}/`
2. Implement `domain.Notifier` interface
3. Add configuration to `src/app/model.go`
4. Wire in `main.go` or use `notify/all/all.go` for multi-channel

### Extending the Store

Add repository methods to `src/client/store/manager.go`:

```go
func (s *Store) GetSomething(ctx context.Context, id string) (*domain.Model, error) {
    // Use s.db for database access
}
```

## Module Path Convention

When initializing a new project from this skeleton:

1. Update `go.mod` module path (e.g., `quantex.com/myservice`)
2. Replace all imports from `quantex.com/skeleton` to `quantex.com/myservice`
3. Update `PROJECT` and `DOMAIN` in `Makefile.common`
4. Update `ISSUE_PREFIX` in `Makefile.common` (e.g., `MYPROJ`)

## Code Generation

### Enums

The project uses `go-enum` for type-safe enums. Files ending in `_enum.go` are generated:

```bash
# Generate enums (run after modifying enum comments)
make gogenerate
```

Example enum definition in source files:
```go
// ENUM(Test, Web, Panic, Error)
type MessageChannel string
```

### Swagger Documentation

Swagger docs are auto-generated from comments:

```go
// @Summary Get user details
// @Description Retrieves user information by ID
// @Tags users
// @Accept json
// @Produce json
// @Param id path string true "User ID"
// @Success 200 {object} UserResponse
// @Router /users/{id} [get]
```

Always run `make swag` after modifying REST API contracts.

## Important Conventions

### Import Grouping

Imports must be grouped (enforced by `gci`):
1. Standard library
2. Third-party packages
3. Quantex packages (prefixed with `quantex.com`)

Run `make fmt` to auto-format.

### Error Handling

- Always check errors
- Use `tracerr` for errors that need debugging context
- Wrap errors with context: `tracerr.Errorf("context: %w", err)`
- Critical errors automatically notify via configured channels

### Logging Best Practices

- Use structured logging with key-value pairs
- Use appropriate log levels (Debug, Info, Warn, Error)
- Include relevant context in log messages
- Avoid logging sensitive information (tokens, passwords)

### Testing

- Place `*_test.go` files alongside source code
- Use table-driven tests for multiple cases
- Integration tests should check `QUANTEX_ENVIRONMENT`
- Run with race detector: `go test -race ./...`

### Git Workflow

- Create branches using `make branch` command
- Reference issue numbers in commits (e.g., `SKL-123`)
- Run `make ci` before pushing
- PRs must pass all checks
- Keep PRs under 500 lines of diff
- Follow the checklist in `checklist.md`

## Security Considerations

### Authentication

Sessions are stored in Redis with 20-minute TTL. Cookie settings:
- `HttpOnly: true` - Prevents JavaScript access
- `Secure: true` in production - HTTPS only
- `SameSite: Strict` in production - CSRF protection

### JWT Tokens

Service-to-service JWT tokens use encryption and permission validation. See `src/common/securetoken/` for implementation.

### Configuration Secrets

- Never commit secrets to repository
- Use environment variables for sensitive data
- Configuration files in repo should be templates only
- Production secrets should be managed via deployment pipeline

## Troubleshooting

### "git state is not clean" Error

The `make ci` and `make push` commands check for uncommitted changes. Commit or stash changes before running.

### MultiDB Permission Errors

MultiDB creates log folders with restrictive permissions. Either:
```bash
# Run with sudo
sudo QUANTEX_ENVIRONMENT="dev" go run main.go -run service

# Or change permissions
sudo chmod 644 multiDB
sudo chmod 644 multiDB/2024_11_22
```

### Swagger Generation Fails

Ensure `src/client/api/rest/docs/docs.go` exists (even if empty):
```bash
mkdir -p src/client/api/rest/docs
echo "package docs" > src/client/api/rest/docs/docs.go
make swag
```

### MQTT Connection Issues

Check configuration in `conf.toml`:
```toml
[MQTT]
Protocol = "wss"
URL = "async-non-prod.quantex.com.ar/mqtt/"
Subdomain = "dev"
Secret = "your-secret-here"
```

Ensure the secret matches the server configuration.

## Templates

### Ticket Creation Template:

**Important:** In the console write the template in markdown format so the user can copy paste it directly.

```markdown
## ℹ️ Issue Type

- [ ] feature
- [ ] hotfix
- [ ] refactor
- [ ] improvement
- [ ] doc
- [ ] fix

## ❌ Issue Description

Summary_of_what_is_the_issue_and_include_screenshots_and_links_of_slack_to_follow_the_problem

## ✅ Expected Behaviuor

Explain_little_about_how_it_should_be_working

## 📋 Steps to Reproduce

What_steps_should_someone_take_to_reproduce_the_issue_include_screenshots_and_links

## 🐛 Possible Impacts

What_other_areas_in_our_code_might_be_affected_or_is_it_possible_that_something_else_broke_with_these_changes
```

## Code Review Description Template

**Important:** In the console write the template in markdown format so the user can copy paste it directly.

```markdown
## 🐛 Reason to Be

Double_click_to_replace_with_a_brief_summary_of_what_this_MR_does_including_a_summary_of_the_original_issue_and_include_screenshots_and_links_to_designs_if_this_MR_has_a_UI_component

Resolves #Issue_number

Related #Issue_number


## ✅ Expected Behaviuor

Explain_little_about_how_is_it_working_in_the_current_MR


## 📋 How To Test

What_steps_should_someone_take_to_test_these_changes_include_screenshots_and_links_to_mocks_for_any_ui_work


##  ⚠️ Check List

1. [ ]  Title format _**SKL-33: Implement Logging using Qapix Endpoints**_ (PREFIX-Issue#: Message)
2. [ ]  Run `make ci` at your end
3. [ ]  Check the pipeline is **🟢 SUCCESS**
4. [ ]  Set the Assignee and Reviewer
5. [ ]  Create 2 PRs for ⚡ HOTFIX in master and develop️
```

## Related Documentation

- README.md - Project initialization steps and examples
- checklist.md - PR review checklist
- AGENTS.md - Repository guidelines (if exists)
- `.golangci.yml` - Linter configuration
- `tools/check/` - Linter exclusions and settings